Source Edit

Cross-platform utilities to manipulate path names. The manipulation routines work directly on the paths and does not check the file system.

Imports

strings, private/strsliceutils

Types

Component = tuple[kind: ComponentKind, path: Path]

A tuple describing a path component Source Edit

ComponentKind {.pure.} = enum
  Prefix, ## The prefix in which a rooted path will start from.
           ## 
           ## A path might have more than one prefix (ie. UNC host and shares).
           ## In such cases the prefixes can be concatenated into one using
           ## the `Separator`.
  Root, PreviousDir, Element

The type of path component Source Edit

ComponentSlice = tuple[kind: ComponentKind, slice: Slice[int]]

A tuple describing a path component Source Edit

Path {.requiresInit.} = distinct Nulless

A distinct string representing an operating system path.

For POSIX, the path will always be represented under the following rules:

Any /.. at the beginning will be collasped into /.
Any . path element will be omitted, unless its the only element.
Any // will be converted to /.
Any trailing slash will be removed.

For Windows, the path will always be represented under the following rules:

Any / separator will be converted to \.
Any \.. at the root component will be collasped into \\.
Any . path element will be omitted, unless its the only element or is necessary for disambiguation.
Any \\ will be converted to \, unless they occur at the beginning of the path.
Any trailing backslash will be removed if they are not significant.
For DOS paths, the drive letter is always in uppercase.

This type does not support Windows' native NT paths (paths starting with \??) and will treat them as relative paths. The \\? prefix should be used to handle them instead.

The path is never an empty string.

Source Edit

Consts

Separator = '/': The main path separator of the target operating system. Source Edit
ValidSeparators = {'/'}: The valid path separators of the target operating system. Source Edit

Procs

func `/`[T: string | Nulless | Path](base, rel: T): Path {....raises: [ValueError], inline.}: Returns a path formed by joining base with rel. Source Edit
func isAbsolute(p: Path): bool {.inline, ...raises: [], tags: [], forbids: [].}: Returns whether the path p is an absolute path. Source Edit
func join[T: string | Nulless | Path](base: var Path; parts: varargs[T]) {. ...raises: [ValueError].}: Join parts to base path.

Each parts entry is treated as if its relative to the result of base joined with prior entries.

If any of parts contains NUL, ValueError will be raised.

Platform specific details

On Windows, drive-relative paths can only be created if the base itself is pointing to a drive-relative entry (ie. C:relative). A bare drive like C: will always be joined into a drive-absolute path to reduce the surprise factor.

Source Edit
func toPath(p: sink Path): Path {....raises: [], tags: [], forbids: [].}: Returns p as is. This is provided for generics. Source Edit
func toPath(s: string | Nulless): Path {....raises: [ValueError].}: Convert the string s into a Path.

An empty string is assumed to be . (current directory).

Raises ValuesError if an invalid character is found in s.
Source Edit

Iterators

iterator components(s: Path | Nulless): Component: Parse s and yields its path components.

Some normalizations are done:

Duplicated separators (ie. //) will be skipped.

Current directory (ie. .) will be skipped.

Previous directories relative to root (ie. /..) will be skipped.

Source Edit
iterator components(s: string): Component {....raises: [ValueError], tags: [], forbids: [].}: Parse s and yields its path components as slices of the input.

Overload of components(Nulless) for strings.

A ValueError will be raised if s contains NUL.
Source Edit
iterator componentSlices(s: Path | Nulless): ComponentSlice: Parse s and yields its path components as slices of the input.

Some normalizations are done:

Duplicated separators (ie. //) will be skipped.

Current directory (ie. .) will be skipped.

Previous directories relative to root (ie. /..) will be skipped.

Platform specific details

Currently, Prefix is only yielded on Windows.

Windows' UNC prefix will be splitted into two parts, both branded as Prefix.

Source Edit
iterator componentSlices(s: string): ComponentSlice {....raises: [ValueError], tags: [], forbids: [].}: Parse s and yields its path components as slices of the input.

Overload of componentSlices(Nulless) for strings.

An error will be raised if s contains NUL.
Source Edit

Converters

converter toNulless(p: Path): Nulless {....raises: [], tags: [], forbids: [].}: One-way implicit conversion to nulless string.

This allows read-only string operations to be done on p.
Source Edit
converter toString(p: Path): string {....raises: [], tags: [], forbids: [].}: One-way implicit conversion to string.

This allows read-only string operations to be done on p.
Source Edit