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

ReadBinary(string?)

Reads the entire file as binary data.

public BinaryData ReadBinary(string? mediaType = null)

Parameters

mediaType string?

The media type of the file's contents, such as application/zip; null leaves it unset.

Returns

BinaryData

ReadDotEnv()

Reads the variables assigned in a dotenv (.env) file, in file order.

public OrderedDictionary<string, string> ReadDotEnv()

Returns

OrderedDictionary<string, string>

Remarks

Each line is a NAME=value assignment, optionally prefixed with export, a # comment, or blank. Unquoted values are trimmed and end at a # preceded by whitespace. Single-quoted values are literal. Double-quoted values support backslash escapes for newline, carriage return, tab, double quote, and backslash. Quoted values may span lines. Variable references such as $HOME are read as written, never expanded. A later assignment replaces the value of an earlier one with the same name.

Exceptions

FormatException

A line is not an assignment, comment, or blank line, or a quoted value is not closed.

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 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

UpdateDotEnv(IEnumerable<KeyValuePair<string, string>>)

Sets variables in this existing dotenv (.env) file, keeping the rest of the file as it is.

public void UpdateDotEnv(IEnumerable<KeyValuePair<string, string>> variables)

Parameters

variables IEnumerable<KeyValuePair<string, string>>

The variables to set. Variables that aren't already in the file are added.

Remarks

Variables that aren't supplied keep their values, so variables can hold just the variables to change, or the result of ReadDotEnv() after changing it. Updating never removes a variable. Only the values of changed variables are rewritten in their existing quote style when they can represent the new value. Comments, blank lines, line order, export prefixes, inline comments, line endings, and encoding are kept. New variables are appended to the end of the file. Existing lines aren't moved, whatever order the variables are supplied in. When a name is assigned more than once, changing it rewrites only the last assignment, which is the one ReadDotEnv() uses.

Exceptions

FileNotFoundException

The file doesn't exist. Use WriteDotEnv() to create one.

FormatException

The existing file isn't valid dotenv content.

ArgumentException

A new variable name contains characters other than letters, numbers, _, -, or .. The file is left unchanged.

WriteBinary(BinaryData)

Writes binary data to this existing file location, replacing its contents.

public void WriteBinary(BinaryData data)

Parameters

data BinaryData

The complete file content. Its media type isn't stored. Missing parent directories are not created.

WriteDotEnv(IEnumerable<KeyValuePair<string, string>>)

Writes variables to this file in dotenv (.env) format, replacing its contents.

public void WriteDotEnv(IEnumerable<KeyValuePair<string, string>> variables)

Parameters

variables IEnumerable<KeyValuePair<string, string>>

The variable names and values, in file order. Missing parent directories are not created.

Remarks

Values are written unquoted when they contain only letters, numbers, and common URL punctuation, otherwise single-quoted when possible, and double-quoted with escapes as a last resort. ReadDotEnv() reads every written value back unchanged. Use UpdateDotEnv() to change an existing file while keeping its comments and layout.

Exceptions

ArgumentException

A variable name contains characters other than letters, numbers, _, -, or .. The file is left unchanged.

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 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.

WriteStream(Stream, CancellationToken)

Copies a stream to this existing file location, replacing its contents, without buffering the stream in memory.

public Task WriteStream(Stream source, CancellationToken cancellationToken = default)

Parameters

source Stream

The stream to copy from its current position to its end. It is left open. Missing parent directories are not created.

cancellationToken CancellationToken

Cancels the copy.

Returns

Task

Remarks

If the copy fails or is canceled, the file is deleted rather than left partly written.

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 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