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

    Construct normalized paths from text with Path.from.

    APIs in this module

    7 APIs

    NameModule
    Path.extensionstd.path
    Path.fileNamestd.path
    Path.fromstd.path
    Path.joinstd.path
    Path.parentstd.path
    Path.toStringstd.path
    Path.withExtensionstd.path

    Module

    Link

    The module exports immutable normalized relative paths. Path.from constructs a path from text. Members inspect components or produce another normalized Path without accessing the filesystem.

    Why

    Link

    A normalized representation gives path composition one meaning before the host applies filesystem permissions and platform rules.

    Availability

    Link

    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.

    Exported types

    Link

    export type Path = Path

    Type members keep the compiler-owned type name shown in their declarations. Importing a module does not create a new type identity.

    Public API

    Link

    Path.extension

    Path.fileName

    Path.from

    Path.join

    Path.parent

    Path.toString

    Path.withExtension

    Pending contracts

    Link

    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

    Inspect and transform normalized paths

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

    Inspect and transform normalized paths

    A Path is immutable normalized relative text. Every member evaluates its receiver and arguments once in ordinary call order. Members perform no host access and leave the receiver unchanged on success and failure.

    toString returns the exact normalized representation. Separators are forward slashes and the relative root is a dot. Constructing a Path from that text returns the same representation.

    join accepts nonempty relative child text. It rejects NUL, a leading separator, and a colon immediately after one ASCII character before combining the child with the receiver. Both slash forms are separators. Parent components remove preceding components from the combined path and return Err when none remain to remove.

    Joining a child may reach the relative root but may not cross it. A dot child preserves the receiver. Invalid child text returns Err containing an error string without producing a Path. Error text identifies Path.join and the invalid condition.

    parent removes the final component. For a one component path it returns Some containing the dot root. The relative root has no parent and returns None().

    fileName returns the final component without any preceding separator. The relative root returns None(). These results describe text and do not establish whether the path identifies a file or directory.

    extension returns the text after the final dot in the file name, provided that dot is not its first character. A leading dot alone does not introduce an extension. A final dot returns Some(""). A name without such a dot and the relative root return None().

    withExtension replaces the final extension or appends one when it is absent. The argument supplies the suffix without a leading dot. An empty argument removes an existing suffix and its separating dot. A leading dot, either separator, or NUL in the argument returns Err.

    withExtension preserves a leading dot that belongs to the file name. It returns Err when the receiver is the relative root because that path has no file name. A successful replacement is normalized with the same rules as Path.from.

    Path validation describes lexical text. Host operations may reject an otherwise valid Path because of platform naming rules, permissions, or capability restrictions. A Path does not establish filesystem existence or prevent a symbolic link from resolving elsewhere.

    Why

    One normalized representation makes composition predictable. Parent and extension queries describe components without consulting host state. A suffix has one accepted spelling, and joining validates the child before its leading separator can disappear inside the combined text.

    Examples Join relative components without changing the receiverReject invalid child text before joiningInspect the final component and the relative rootKeep the relative root as the parent of one componentDistinguish an absent extension from an empty extensionReplace and remove a final extensionPreserve the name of a file that starts with a dotReject a second suffix spelling and a path without a file name

    Source evidence

    Join relative components without changing the receiver

    Link

    run · running · Verification: not-run

    main.tpzJoin relative components without changing the receiverOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let base = test.assertOk(Path.from("chapters/draft"))
    6. let child = test.assertOk(base.join("../final/./main.tpz"))
    7. io.writeLine(base.toString())
    8. io.writeLine(child.toString())
    9. io.writeLine(test.assertOk(base.join("../..")).toString())
    10. io.writeLine(test.assertOk(base.join(".")).toString())
    Expected outputexit 0
    chapters/draft
chapters/final/main.tpz
.
chapters/draft
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. chapters/draft
    2. chapters/final/main.tpz
    3. .
    4. chapters/draft

    This exact example has not been executed.

    Source evidence

    Reject invalid child text before joining

    Link

    run · running · Verification: not-run

    main.tpzReject invalid child text before joiningOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let base = test.assertOk(Path.from("chapters"))
    6. for child in (["", "/outside", "C:/outside", "../../outside"]) {
    7. match (base.join(child)) {
    8. case Err(_) => io.writeLine("rejected")
    9. case Ok(_) => io.writeLine("accepted")
    10. }
    11. }
    12. io.writeLine(base.toString())
    Expected outputexit 0
    rejected
rejected
rejected
rejected
chapters
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. rejected
    2. rejected
    3. rejected
    4. rejected
    5. chapters

    This exact example has not been executed.

    Source evidence

    Inspect the final component and the relative root

    Link

    run · running · Verification: not-run

    main.tpzInspect the final component and the relative rootOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let file = test.assertOk(Path.from("chapters/main.tpz"))
    6. io.writeLine(test.assertSome(file.parent()).toString())
    7. io.writeLine(test.assertSome(file.fileName()))
    8. io.writeLine(test.assertSome(file.extension()))
    9. let root = test.assertOk(Path.from("."))
    10. test.assertNone(root.parent())
    11. test.assertNone(root.fileName())
    12. test.assertNone(root.extension())
    13. io.writeLine(root.toString())
    Expected outputexit 0
    chapters
main.tpz
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
    2. main.tpz
    3. tpz
    4. .

    This exact example has not been executed.

    Source evidence

    Keep the relative root as the parent of one component

    Link

    run · running · Verification: not-run

    main.tpzKeep the relative root as the parent of one componentOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let file = test.assertOk(Path.from("main.tpz"))
    6. match (file.parent()) {
    7. case Some(parent) => io.writeLine(parent.toString())
    8. case None() => io.writeLine("missing")
    9. }
    Expected outputexit 0
    .
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. .

    This exact example has not been executed.

    Source evidence

    Distinguish an absent extension from an empty extension

    Link

    run · running · Verification: not-run

    main.tpzDistinguish an absent extension from an empty extensionOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. for name in (["README", ".env", ".env.local", "archive.tar.gz", "trailing."]) {
    6. let file = test.assertOk(Path.from(name))
    7. match (file.extension()) {
    8. case Some(extension) => io.writeLine("present [{extension}]")
    9. case None() => io.writeLine("absent")
    10. }
    11. }
    Expected outputexit 0
    absent
absent
present [local]
present [gz]
present []
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. absent
    2. absent
    3. present [local]
    4. present [gz]
    5. present []

    This exact example has not been executed.

    Source evidence

    Replace and remove a final extension

    Link

    run · running · Verification: not-run

    main.tpzReplace and remove a final extensionOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let file = test.assertOk(Path.from("chapters/main.tpz"))
    6. io.writeLine(test.assertOk(file.withExtension("pdf")).toString())
    7. io.writeLine(test.assertOk(file.withExtension("")).toString())
    8. io.writeLine(file.toString())
    Expected outputexit 0
    chapters/main.pdf
chapters/main
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.pdf
    2. chapters/main
    3. chapters/main.tpz

    This exact example has not been executed.

    Source evidence

    Preserve the name of a file that starts with a dot

    Link

    run · running · Verification: not-run

    main.tpzPreserve the name of a file that starts with a dotOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let file = test.assertOk(Path.from(".env"))
    6. io.writeLine(test.assertOk(file.withExtension("local")).toString())
    7. io.writeLine(test.assertOk(file.withExtension("")).toString())
    Expected outputexit 0
    .env.local
.env
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. .env.local
    2. .env

    This exact example has not been executed.

    Source evidence

    Reject a second suffix spelling and a path without a file name

    Link

    run · running · Verification: not-run

    main.tpzReject a second suffix spelling and a path without a file nameOpen in Playground
    1. import std.path { Path }
    2. import std.test
    3. import std.io
    5. let file = test.assertOk(Path.from("chapter.txt"))
    6. for extension in ([".pdf", "pdf/extra", "pdf\\extra"]) {
    7. match (file.withExtension(extension)) {
    8. case Err(_) => io.writeLine("rejected")
    9. case Ok(_) => io.writeLine("accepted")
    10. }
    11. }
    12. let root = test.assertOk(Path.from("."))
    13. match (root.withExtension("pdf")) {
    14. case Err(_) => io.writeLine("root rejected")
    15. case Ok(_) => io.writeLine("root accepted")
    16. }
    Expected outputexit 0
    rejected
rejected
rejected
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. rejected
    2. rejected
    3. rejected
    4. root rejected

    This exact example has not been executed.

    Source evidence

    Menu

    Download