Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.path

    Path.from

    Validates and normalizes text into a logical project-relative Path.

    from(text: string) -> Result<Path, string>
    Module
    std.path
    Receiver
    Not applicable
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.path in language mode 5.21.

    The current compiler selects std/path.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    Not applicable

    Parameter constraints

    Additional contracts are Pending.

    Path.from(text) is the constructor for normalized relative paths and returns Result<Path, string>.

    Path.from normalizes path separators and removes empty and dot components. Parent components must stay within the relative root. A path reduced to no components is represented by a dot.

    Empty text, NUL, absolute paths, and parent traversal beyond the relative root return Err. These input failures are values that a caller can handle.

    A leading slash or backslash returns Err. Text that starts with one ASCII character followed immediately by a colon returns Err.

    Path.cwdRelative and Path.project are absent. A Path value already satisfies normalization and has no normalize member.

    Path operations inspect text without accessing the filesystem. Constructing a Path does not establish that its target exists or is accessible.

    Related rule: Construct normalized paths with Path.from

    Result

    Additional contracts are Pending.

    The declared result type is Result<Path, string>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Construct a normalized relative Path and return invalid path text as Err. Existing Path values already satisfy the normalization invariant.

    Why

    Link

    Normalizing at construction makes every Path operation use the same representation. A second constructor or an identity normalize call adds no path meaning.

    Related entries

    Link

    std.path

    Construct normalized paths with Path.from

    Link
    Ruletopaz.stdlib.contract.path-from.rule

    Construct normalized paths with Path.from

    Path.from(text) is the constructor for normalized relative paths and returns Result<Path, string>.

    Path.from normalizes path separators and removes empty and dot components. Parent components must stay within the relative root. A path reduced to no components is represented by a dot.

    Empty text, NUL, absolute paths, and parent traversal beyond the relative root return Err. These input failures are values that a caller can handle.

    A leading slash or backslash returns Err. Text that starts with one ASCII character followed immediately by a colon returns Err.

    Path.cwdRelative and Path.project are absent. A Path value already satisfies normalization and has no normalize member.

    Path operations inspect text without accessing the filesystem. Constructing a Path does not establish that its target exists or is accessible.

    Why

    One constructor gives relative path text one interpretation. Normalization is a Path invariant, so a separate identity operation gives the same value a second spelling.

    Examples Construct a normalized pathReject a path that escapes its relative rootReject Path.cwdRelativeReject Path.projectReject Path.normalizeDistinguish rejected ASCII prefixes from relative path text

    Diagnostics TPZ5006

    Source evidence

    Construct a normalized path

    Link

    run · running · Verification: not-run

    main.tpzConstruct a normalized pathOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let chapter = test.assertOk(Path.from("chapters/./draft/../main.tpz"))
    6. io.writeLine(chapter.toString())
    Expected outputexit 0
    chapters/main.tpz
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. chapters/main.tpz

    This exact example has not been executed.

    Source evidence

    Reject a path that escapes its relative root

    Link

    run · running · Verification: not-run

    main.tpzReject a path that escapes its relative rootOpen in Playground
    1. import std.path { Path }
    2. import std.io
    4. match (Path.from("../chapter.tpz")) {
    5. case Err(_) => io.writeLine("outside root rejected")
    6. case Ok(_) => io.writeLine("accepted")
    7. }
    Expected outputexit 0
    outside root rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. outside root rejected

    This exact example has not been executed.

    Source evidence

    Reject Path.cwdRelative

    Link

    reject · checking · Verification: not-run

    main.tpzReject Path.cwdRelativeOpen in Playground
    1. import std.path { Path }
    2. let value = Path.cwdRelative("chapter.tpz")
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:2:18

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject Path.project

    Link

    reject · checking · Verification: not-run

    main.tpzReject Path.projectOpen in Playground
    1. import std.path { Path }
    2. let value = Path.project("chapter.tpz")
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:2:18

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject Path.normalize

    Link

    reject · checking · Verification: not-run

    main.tpzReject Path.normalizeOpen in Playground
    1. import std.path { Path }
    2. function inspect(path: Path) -> () {
    3. let value = path.normalize()
    4. return ()
    5. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:3:20

    No stdout.

    This exact example has not been executed.

    Source evidence

    Distinguish rejected ASCII prefixes from relative path text

    Link

    run · running · Verification: not-run

    main.tpzDistinguish rejected ASCII prefixes from relative path textOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. test.assertErr(Path.from("a:"))
    6. test.assertErr(Path.from("1:"))
    7. test.assertErr(Path.from("!:"))
    8. io.writeLine(test.assertOk(Path.from("aa:")).toString())
    9. io.writeLine(test.assertOk(Path.from("é:")).toString())
    10. io.writeLine(test.assertOk(Path.from("가:")).toString())
    Expected outputexit 0
    aa:
é:
가:
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. aa:
    2. é:
    3. 가:

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Unknown member or field

    Menu

    Download