Class AbsolutePath

Namespace

DotNetDo

Assembly

DotNetDo.Core.dll

An immutable, normalized absolute path with explicit root semantics.

public sealed record AbsolutePath : IEquatable<AbsolutePath>

Properties

Exists

Whether a file or directory currently exists at this path.

public bool Exists { get; }

Property Value

bool

Extension

The final component's extension, including its leading period; empty when it has none.

public string Extension { get; }

Property Value

string

IsExistingDirectory

Whether an existing directory occupies this path.

public bool IsExistingDirectory { get; }

Property Value

bool

IsExistingFile

Whether an existing regular file occupies this path.

public bool IsExistingFile { get; }

Property Value

bool

IsRoot

Whether this path contains only its root and no path components.

[MemberNotNullWhen(false, "Name")]
public bool IsRoot { get; }

Property Value

bool

Name

The final path component, or null for a root or empty path.

public string? Name { get; }

Property Value

string?

NameWithoutExtension

The final component without its last extension; null for a root path.

public string? NameWithoutExtension { get; }

Property Value

string?

Parent

The containing path. Accessing this property on a root throws.

public AbsolutePath Parent { get; }

Property Value

AbsolutePath

Root

The Unix, drive, or UNC root of this path.

public AbsolutePath Root { get; }

Property Value

AbsolutePath

UnixPath

Renders the normalized path with forward slashes, regardless of the current platform.

public string UnixPath { get; }

Property Value

string

WindowsPath

Renders the normalized path with backslashes, regardless of the current platform.

public string WindowsPath { get; }

Property Value

string

Methods

CopyInto(AbsolutePath, TransferOptions?)

Copies this item beneath the supplied destination directory using its current name.

public AbsolutePath CopyInto(AbsolutePath directory, TransferOptions? options = null)

Parameters

directory AbsolutePath

The directory that will contain a copy under this item's current name.

options TransferOptions?

Controls replacement of existing items and creation of missing directories.

Returns

AbsolutePath

CopyTo(AbsolutePath, TransferOptions?)

Copies this file or directory to the exact destination path.

public AbsolutePath CopyTo(AbsolutePath destination, TransferOptions? options = null)

Parameters

destination AbsolutePath

The exact destination filename or directory path.

options TransferOptions?

Controls replacement of existing items and creation of missing parent directories.

Returns

AbsolutePath

Delete()

Deletes the file or directory.

public void Delete()

EnsureDirectoryExists()

Creates this directory and any missing parents, returning this path.

public AbsolutePath EnsureDirectoryExists()

Returns

AbsolutePath

Equals(AbsolutePath?)

Compares normalized path structure using ordinal segment equality.

public bool Equals(AbsolutePath? other)

Parameters

other AbsolutePath?

Returns

bool

GetAncestry()

Returns the path and its parents up to and including the root.

public IEnumerable<AbsolutePath> GetAncestry()

Returns

IEnumerable<AbsolutePath>

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

GlobDirectories(IEnumerable<string>, GlobOptions?)

Returns directories beneath this directory matched by the ordered include and exclude patterns.

public AbsolutePath[] GlobDirectories(IEnumerable<string> patterns, GlobOptions? options = null)

Parameters

patterns IEnumerable<string>

Ordered directory-relative globs. Exclusions begin with ! and remove earlier matches.

options GlobOptions?

Optional glob comparison settings; defaults to ordinal matching.

Returns

AbsolutePath[]

GlobDirectories(string, GlobOptions?)

Returns directories beneath this directory matched by the ordered include and exclude patterns.

public AbsolutePath[] GlobDirectories(string pattern, GlobOptions? options = null)

Parameters

pattern string

A glob relative to this directory. Prefix with ! to exclude earlier matches.

options GlobOptions?

Optional glob comparison settings; defaults to ordinal matching.

Returns

AbsolutePath[]

GlobFiles(IEnumerable<string>, GlobOptions?)

Returns files beneath this directory matched by the ordered include and exclude patterns.

public AbsolutePath[] GlobFiles(IEnumerable<string> patterns, GlobOptions? options = null)

Parameters

patterns IEnumerable<string>

Ordered directory-relative globs. Exclusions begin with ! and remove earlier matches.

options GlobOptions?

Optional glob comparison settings; defaults to ordinal matching.

Returns

AbsolutePath[]

GlobFiles(string, GlobOptions?)

Returns files beneath this directory matched by the ordered include and exclude patterns.

public AbsolutePath[] GlobFiles(string pattern, GlobOptions? options = null)

Parameters

pattern string

A glob relative to this directory. Prefix with ! to exclude earlier matches.

options GlobOptions?

Optional glob comparison settings; defaults to ordinal matching.

Returns

AbsolutePath[]

IsWithin(AbsolutePath)

Returns whether this path is equal to or nested beneath the supplied directory.

public bool IsWithin(AbsolutePath directory)

Parameters

directory AbsolutePath

The candidate ancestor; paths on a different root are never considered ancestors.

Returns

bool

MoveInto(AbsolutePath, TransferOptions?)

Moves this item beneath the supplied destination directory using its current name.

public AbsolutePath MoveInto(AbsolutePath directory, TransferOptions? options = null)

Parameters

directory AbsolutePath

The directory that will contain this item under its current name.

options TransferOptions?

Controls replacement of existing items and creation of missing directories.

Returns

AbsolutePath

MoveTo(AbsolutePath, TransferOptions?)

Moves this file or directory to the exact destination path.

public AbsolutePath MoveTo(AbsolutePath destination, TransferOptions? options = null)

Parameters

destination AbsolutePath

The exact destination filename or directory path.

options TransferOptions?

Controls replacement of existing items and creation of missing parent directories.

Returns

AbsolutePath

Parse(string)

Normalizes a Unix-rooted, drive-rooted, or UNC-rooted path without accessing the filesystem.

public static AbsolutePath Parse(string path)

Parameters

path string

The non-empty absolute path text; may use either directory separator. Relative, drive-relative, NUL-containing, and root-escaping paths are rejected.

Returns

AbsolutePath

QuotedArgument()

Renders the value as one quoted command-line argument.

public string QuotedArgument()

Returns

string

ReadJson(JsonSerializerOptions?)

Reads the file as a JSON document model.

public JsonNode? ReadJson(JsonSerializerOptions? options = null)

Parameters

options JsonSerializerOptions?

Returns

JsonNode?

ReadJson<T>(JsonSerializerOptions?)

Deserializes the file into the requested value type.

public T? ReadJson<T>(JsonSerializerOptions? options = null)

Parameters

options JsonSerializerOptions?

JSON serializer behavior; null uses System.Text.Json.JsonSerializerOptions.Default.

Returns

T?

Type Parameters

T

ReadLines(Encoding?)

Reads all file lines using the supplied encoding or UTF-8.

public string[] ReadLines(Encoding? encoding = null)

Parameters

encoding Encoding?

The text encoding; null uses UTF-8.

Returns

string[]

ReadText(Encoding?)

Reads the entire file as text using the supplied encoding or UTF-8.

public string ReadText(Encoding? encoding = null)

Parameters

encoding Encoding?

The text encoding; null uses UTF-8.

Returns

string

ReadToml(TomlSerializerOptions?)

Reads the file as a TOML document model.

public TomlTable ReadToml(TomlSerializerOptions? options = null)

Parameters

options TomlSerializerOptions?

Returns

TomlTable

ReadToml<T>(TomlSerializerOptions?)

Deserializes the file into the requested value type.

public T? ReadToml<T>(TomlSerializerOptions? options = null)

Parameters

options TomlSerializerOptions?

TOML serializer behavior; null uses Tomlyn defaults.

Returns

T?

Type Parameters

T

ReadXml()

Reads the file as an XML document model.

public XDocument ReadXml()

Returns

XDocument

ReadXml<T>()

Deserializes the file into the requested value type.

public T? ReadXml<T>()

Returns

T?

Type Parameters

T

ReadYaml()

Reads the root node of one YAML document from the file.

public YamlNode? ReadYaml()

Returns

YamlNode?

ReadYaml<T>(IDeserializer?)

Deserializes one YAML document from the file into the requested value type.

public T? ReadYaml<T>(IDeserializer? deserializer = null)

Parameters

deserializer IDeserializer?

The YAML deserializer; null uses DotNetDo's default instance.

Returns

T?

Type Parameters

T

RecreateDirectory()

Delete and recreate this directory.

public AbsolutePath RecreateDirectory()

Returns

AbsolutePath

RelativePathTo(AbsolutePath)

Computes the lexical path from this location to another path on the same root.

public RelativePath RelativePathTo(AbsolutePath path)

Parameters

path AbsolutePath

The destination path. It must use the same Unix, drive, or UNC root as this path.

Returns

RelativePath

TemporaryFileContents(Action<AbsolutePath>)

Temporarily replaces this file's contents and restores its original bytes when disposed.

public IDisposable TemporaryFileContents(Action<AbsolutePath> replace)

Parameters

replace Action<AbsolutePath>

The operation that replaces this file's contents.

Returns

IDisposable

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

TryParse(string?, out AbsolutePath?)

Tries to normalize a Unix-rooted, drive-rooted, or UNC-rooted path without accessing the filesystem.

public static bool TryParse(string? path, out AbsolutePath? result)

Parameters

path string?

The path text; may use either directory separator. null, relative, drive-relative, and NUL-containing paths are invalid.

result AbsolutePath?

The normalized absolute path when parsing succeeds; otherwise null.

Returns

bool

UnzipTo(AbsolutePath, UnzipOptions?)

Extracts this ZIP archive into the exact destination directory.

public AbsolutePath UnzipTo(AbsolutePath destination, UnzipOptions? options = null)

Parameters

destination AbsolutePath

The exact output directory. Its parent directory must exist.

options UnzipOptions?

Controls merging with existing destination entries.

Returns

AbsolutePath

WriteJson<T>(T, JsonSerializerOptions?)

Serializes the value to this file.

public void WriteJson<T>(T value, JsonSerializerOptions? options = null)

Parameters

value T

The value serialized as JSON. Missing parent directories are not created.

options JsonSerializerOptions?

JSON serializer behavior; null uses System.Text.Json.JsonSerializerOptions.Default.

Type Parameters

T

WriteLines(IEnumerable<string>, Encoding?)

Writes lines to this existing file location using the supplied encoding or UTF-8.

public void WriteLines(IEnumerable<string> lines, Encoding? encoding = null)

Parameters

lines IEnumerable<string>

The lines to write using the platform newline. Missing parent directories are not created.

encoding Encoding?

The text encoding; null uses UTF-8.

WriteText(string, Encoding?)

Writes text to this existing file location using the supplied encoding or UTF-8.

public void WriteText(string text, Encoding? encoding = null)

Parameters

text string

The complete file content. Missing parent directories are not created.

encoding Encoding?

The text encoding; null uses UTF-8.

WriteToml<T>(T, TomlSerializerOptions?)

Serializes the value to this file.

public void WriteToml<T>(T value, TomlSerializerOptions? options = null)

Parameters

value T

The value serialized as TOML. Missing parent directories are not created.

options TomlSerializerOptions?

TOML serializer behavior; null uses Tomlyn defaults.

Type Parameters

T

WriteXml(XDocument)

Writes an XML document model to this file.

public void WriteXml(XDocument value)

Parameters

value XDocument

WriteXml<T>(T)

Serializes the value to this file.

public void WriteXml<T>(T value)

Parameters

value T

The value serialized with System.Xml.Serialization.XmlSerializer. Missing parent directories are not created.

Type Parameters

T

WriteYaml(YamlNode)

Writes one YAML document-model root node to this file.

public void WriteYaml(YamlNode value)

Parameters

value YamlNode

WriteYaml<T>(T, ISerializer?)

Serializes the value as one YAML document to this file.

public void WriteYaml<T>(T value, ISerializer? serializer = null)

Parameters

value T

The value serialized as YAML. Missing parent directories are not created.

serializer ISerializer?

The YAML serializer; null uses DotNetDo's default instance.

Type Parameters

T

ZipTo(AbsolutePath, ZipOptions?)

Creates a ZIP archive from this file or directory at the exact destination path.

public AbsolutePath ZipTo(AbsolutePath destination, ZipOptions? options = null)

Parameters

destination AbsolutePath

The exact archive path. Its parent directory must exist.

options ZipOptions?

Controls compression and replacement of an existing archive.

Returns

AbsolutePath

Operators

implicit operator string(AbsolutePath)

Renders the path using the current operating system's directory separator.

public static implicit operator string(AbsolutePath path)

Parameters

path AbsolutePath

Returns

string

operator /(AbsolutePath, AbsolutePath) Deprecated

The right operand must be relative.

Prevents joining two absolute paths.

[Obsolete("The right operand must be relative.", true)]
public static AbsolutePath operator /(AbsolutePath left, AbsolutePath right)

Parameters

left AbsolutePath

right AbsolutePath

Returns

AbsolutePath

operator /(AbsolutePath, RelativePath)

Resolves a relative path against an absolute path, rejecting traversal above its root.

public static AbsolutePath operator /(AbsolutePath left, RelativePath right)

Parameters

left AbsolutePath

The absolute base path.

right RelativePath

The relative path to resolve.

Returns

AbsolutePath

operator /(AbsolutePath, string)

Parses and resolves relative path text against an absolute path.

public static AbsolutePath operator /(AbsolutePath left, string right)

Parameters

left AbsolutePath

The absolute base path.

right string

Relative path text; rooted, drive-relative, NUL-containing, and root-escaping values are rejected.

Returns

AbsolutePath