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

    Lists entries at a filesystem path.

    list(path: string | Path) -> Result<Array<{ kind: string, name: string, sizeBytes: Option<int> }>, string>
    Module
    std.fs
    Receiver
    Not applicable
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.fs in language mode 5.21.

    The current compiler selects std/fs.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.

    Each function accepts a string path or a Path. Strings use the host path syntax. A Path supplies its normalized relative text. Relative paths use the working directory in an ordinary installed CLI invocation. A package host applies its configured filesystem base and capability policy.

    Path and payload arguments are evaluated once in source order before the operation starts. The operation acquires and releases its own resources before returning. It does not change a separately opened File cursor.

    Empty paths and paths containing NUL return Err containing a string. Missing read targets, incorrect path kinds, permission denial, package capability denial, and host failures use the same error channel. Errors are values. They do not terminate the program unless the caller chooses to propagate or assert them.

    An error string identifies the public operation and the supplied path. It also describes the failure condition. Platform wording, operating system error numbers, and localized explanations are not stable API values.

    readText returns the entire regular file as text. UTF-8 validity and text preservation follow UTF-8 decoding. Empty files return an empty string. Invalid UTF-8 returns Err without a decoded text value.

    readBytes returns every byte in order, including zero bytes and bytes that are not valid UTF-8. Empty files return empty Bytes. Reading does not create or modify the file.

    writeText encodes its string as UTF-8. writeBytes writes the supplied bytes unchanged. Both create a missing regular file or replace the full contents of an existing regular file. An empty payload creates or truncates the file to zero bytes. No newline or byte order mark is added.

    Writes do not create missing parent directories. They follow the host permission and creation policy. Replacing a file with shorter content removes its previous suffix. Success returns Ok(()) after all payload bytes have been accepted.

    A write failure may occur after creation, truncation, or a prefix write. Err does not promise rollback, atomic replacement, or persistence across a system crash. Earlier argument effects remain visible.

    list returns immediate children sorted by their exact names in ascending Unicode scalar order. It does not return dot or parent pseudoentries, traverse child directories, normalize Unicode names, or fold case. The name field contains the child name without the parent path.

    Each entry kind is exactly file, directory, symlink, or other. Classification uses the entry itself and does not follow a symbolic link. For a regular file, sizeBytes is Some of its byte length when that length fits in int. Other kinds and an unrepresentable size use None().

    A name that cannot be represented as Unicode, a failure while reading an entry, or a failure obtaining its metadata returns Err for the whole list. No partial array is returned. Separate operations do not provide a filesystem snapshot, so other processes may change a path between calls.

    Host access follows symbolic links where the operation addresses their target, subject to host capability checks. A normalized Path is not an authorization token. Use File when operations must retain one open resource and cursor, and std.fs when the operation concerns complete contents or directory entries.

    Related rule: Read and replace whole files and list directories

    Result

    Additional contracts are Pending.

    The declared result type is Result<Array<{ kind: string, name: string, sizeBytes: Option<int> }>, string>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    List immediate children in ascending exact name order with kind and optional regular file byte length.

    Related entries

    Link

    std.fs

    Read and replace whole files and list directories

    Link
    Ruletopaz.stdlib.contract.filesystem.rule

    Read and replace whole files and list directories

    Each function accepts a string path or a Path. Strings use the host path syntax. A Path supplies its normalized relative text. Relative paths use the working directory in an ordinary installed CLI invocation. A package host applies its configured filesystem base and capability policy.

    Path and payload arguments are evaluated once in source order before the operation starts. The operation acquires and releases its own resources before returning. It does not change a separately opened File cursor.

    Empty paths and paths containing NUL return Err containing a string. Missing read targets, incorrect path kinds, permission denial, package capability denial, and host failures use the same error channel. Errors are values. They do not terminate the program unless the caller chooses to propagate or assert them.

    An error string identifies the public operation and the supplied path. It also describes the failure condition. Platform wording, operating system error numbers, and localized explanations are not stable API values.

    readText returns the entire regular file as text. UTF-8 validity and text preservation follow UTF-8 decoding. Empty files return an empty string. Invalid UTF-8 returns Err without a decoded text value.

    readBytes returns every byte in order, including zero bytes and bytes that are not valid UTF-8. Empty files return empty Bytes. Reading does not create or modify the file.

    writeText encodes its string as UTF-8. writeBytes writes the supplied bytes unchanged. Both create a missing regular file or replace the full contents of an existing regular file. An empty payload creates or truncates the file to zero bytes. No newline or byte order mark is added.

    Writes do not create missing parent directories. They follow the host permission and creation policy. Replacing a file with shorter content removes its previous suffix. Success returns Ok(()) after all payload bytes have been accepted.

    A write failure may occur after creation, truncation, or a prefix write. Err does not promise rollback, atomic replacement, or persistence across a system crash. Earlier argument effects remain visible.

    list returns immediate children sorted by their exact names in ascending Unicode scalar order. It does not return dot or parent pseudoentries, traverse child directories, normalize Unicode names, or fold case. The name field contains the child name without the parent path.

    Each entry kind is exactly file, directory, symlink, or other. Classification uses the entry itself and does not follow a symbolic link. For a regular file, sizeBytes is Some of its byte length when that length fits in int. Other kinds and an unrepresentable size use None().

    A name that cannot be represented as Unicode, a failure while reading an entry, or a failure obtaining its metadata returns Err for the whole list. No partial array is returned. Separate operations do not provide a filesystem snapshot, so other processes may change a path between calls.

    Host access follows symbolic links where the operation addresses their target, subject to host capability checks. A normalized Path is not an authorization token. Use File when operations must retain one open resource and cursor, and std.fs when the operation concerns complete contents or directory entries.

    Why

    Exact bytes and strict text decoding keep data conversion explicit. Whole file replacement has a clear effect, and Result makes permission and host failures recoverable. Sorting names makes directory traversal repeatable for a fixed directory state without assuming a host enumeration order.

    Examples Replace and create text files with exact contentPreserve a byte order mark and physical line endingsPreserve raw bytes and reject invalid UTF-8 textList immediate entries in exact name orderReturn recoverable errors for the wrong path kindEvaluate payloads before replacing a fileIdentify the operation and path in a readText errorIdentify the operation and path in a readBytes errorIdentify the operation and path in a writeText errorIdentify the operation and path in a writeBytes errorIdentify the operation and path in a list error

    Source evidence

    Replace and create text files with exact content

    Link

    run · running · Verification: not-run

    main.tpzReplace and create text files with exact contentOpen in Playground
    1. import std.fs
    2. import std.path { Path }
    3. import std.test
    4. import std.io
    6. let path = test.assertOk(Path.from("chapter.txt"))
    7. test.assertOk(fs.writeText(path, "short\n"))
    8. io.writeLine(test.assertOk(fs.readText("chapter.txt")))
    9. test.assertOk(fs.writeText("created.txt", "한글"))
    10. io.writeLine(test.assertOk(fs.readText("created.txt")))
    11. test.assertOk(fs.writeText("created.txt", ""))
    12. let text = test.assertOk(fs.readText("created.txt"))
    13. let empty = text == ""
    14. io.writeLine("empty {empty}")
    Expected outputexit 0
    short

한글
empty true
    $ topaz run main.tpz · target product 5.21.3
    chapter.txtReplace and create text files with exact contentOpen in Playground
    1. a much longer old value
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. short
    3. 한글
    4. empty true

    This exact example has not been executed.

    Source evidence

    Preserve a byte order mark and physical line endings

    Link

    run · running · Verification: not-run

    main.tpzPreserve a byte order mark and physical line endingsOpen in Playground
    1. import std.fs
    2. import std.test
    3. import std.io
    5. io.writeLine(test.assertOk(fs.readText("source.txt")))
    Expected outputexit 0
    alpha
한글
    $ topaz run main.tpz · target product 5.21.3
    source.txtPreserve a byte order mark and physical line endingsOpen in Playground
    1. alpha
    2. 한글
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. alpha
    2. 한글

    This exact example has not been executed.

    Source evidence

    Preserve raw bytes and reject invalid UTF-8 text

    Link

    run · running · Verification: not-run

    main.tpzPreserve raw bytes and reject invalid UTF-8 textOpen in Playground
    1. import std.fs
    2. import std.bytes { Bytes }
    3. import std.test
    4. import std.io
    6. let bytes = test.assertOk(Bytes.fromArray([0, 65, 255]))
    7. test.assertOk(fs.writeBytes("data.bin", bytes))
    8. io.writeLine(test.assertOk(fs.readBytes("data.bin")).toHex())
    9. test.assertErr(fs.readText("data.bin"))
    10. io.writeLine("invalid text rejected")
    11. test.assertOk(fs.writeBytes("data.bin", Bytes.empty()))
    12. io.writeLine(test.assertOk(fs.readBytes("data.bin")).toHex())
    Expected outputexit 0
    0041ff
invalid text rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0041ff
    2. invalid text rejected

    This exact example has not been executed.

    Source evidence

    List immediate entries in exact name order

    Link

    run · running · Verification: not-run

    main.tpzList immediate entries in exact name orderOpen in Playground
    1. import std.fs
    2. import std.test
    3. import std.io
    5. let entries = test.assertOk(fs.list("entries"))
    6. for entry in (entries) {
    7. let size = match (entry.sizeBytes) {
    8. case Some(value) => "{value}"
    9. case None() => "none"
    10. }
    11. io.writeLine("{entry.name} {entry.kind} {size}")
    12. }
    Expected outputexit 0
    a.txt file 1
nested directory none
z.txt file 2
    $ topaz run main.tpz · target product 5.21.3
    entries/z.txtList immediate entries in exact name orderOpen in Playground
    1. zz
    entries/a.txtList immediate entries in exact name orderOpen in Playground
    1. a
    entries/nested/inside.txtList immediate entries in exact name orderOpen in Playground
    1. inside
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. a.txt file 1
    2. nested directory none
    3. z.txt file 2

    This exact example has not been executed.

    Source evidence

    Return recoverable errors for the wrong path kind

    Link

    run · running · Verification: not-run

    main.tpzReturn recoverable errors for the wrong path kindOpen in Playground
    1. import std.fs
    2. import std.test
    3. import std.io
    5. test.assertErr(fs.readText("directory"))
    6. test.assertErr(fs.readBytes("directory"))
    7. test.assertErr(fs.writeText("directory", "text"))
    8. test.assertErr(fs.list("plain.txt"))
    9. io.writeLine("wrong kinds rejected")
    Expected outputexit 0
    wrong kinds rejected
    $ topaz run main.tpz · target product 5.21.3
    directory/inside.txtReturn recoverable errors for the wrong path kindOpen in Playground
    1. inside
    plain.txtReturn recoverable errors for the wrong path kindOpen in Playground
    1. plain
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. wrong kinds rejected

    This exact example has not been executed.

    Source evidence

    Evaluate payloads before replacing a file

    Link

    run · running · Verification: not-run

    main.tpzEvaluate payloads before replacing a fileOpen in Playground
    1. import std.fs
    2. import std.test
    3. import std.io
    5. function target() -> string {
    6. io.writeLine("path")
    7. return "source.txt"
    8. }
    9. function payload() -> string {
    10. io.writeLine("text")
    11. io.writeLine(test.assertOk(fs.readText("source.txt")))
    12. return "new"
    13. }
    14. test.assertOk(fs.writeText(target(), payload()))
    15. io.writeLine(test.assertOk(fs.readText("source.txt")))
    Expected outputexit 0
    path
text
old
new
    $ topaz run main.tpz · target product 5.21.3
    source.txtEvaluate payloads before replacing a fileOpen in Playground
    1. old
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. path
    2. text
    3. old
    4. new

    This exact example has not been executed.

    Source evidence

    Identify the operation and path in a readText error

    Link

    run · running · Verification: not-run

    main.tpzIdentify the operation and path in a readText errorOpen in Playground
    1. import std.fs
    2. import std.bytes { Bytes }
    3. import std.test
    4. import std.io
    6. let error = test.assertErr(fs.readText("missing/item.txt"))
    7. let operation = error.contains("readText")
    8. let path = error.contains("missing/item.txt")
    9. io.writeLine("{operation} {path}")
    Expected outputexit 0
    true true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true true

    This exact example has not been executed.

    Source evidence

    Identify the operation and path in a readBytes error

    Link

    run · running · Verification: not-run

    main.tpzIdentify the operation and path in a readBytes errorOpen in Playground
    1. import std.fs
    2. import std.bytes { Bytes }
    3. import std.test
    4. import std.io
    6. let error = test.assertErr(fs.readBytes("missing/item.txt"))
    7. let operation = error.contains("readBytes")
    8. let path = error.contains("missing/item.txt")
    9. io.writeLine("{operation} {path}")
    Expected outputexit 0
    true true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true true

    This exact example has not been executed.

    Source evidence

    Identify the operation and path in a writeText error

    Link

    run · running · Verification: not-run

    main.tpzIdentify the operation and path in a writeText errorOpen in Playground
    1. import std.fs
    2. import std.bytes { Bytes }
    3. import std.test
    4. import std.io
    6. let error = test.assertErr(fs.writeText("missing/item.txt", "text"))
    7. let operation = error.contains("writeText")
    8. let path = error.contains("missing/item.txt")
    9. io.writeLine("{operation} {path}")
    Expected outputexit 0
    true true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true true

    This exact example has not been executed.

    Source evidence

    Identify the operation and path in a writeBytes error

    Link

    run · running · Verification: not-run

    main.tpzIdentify the operation and path in a writeBytes errorOpen in Playground
    1. import std.fs
    2. import std.bytes { Bytes }
    3. import std.test
    4. import std.io
    6. let error = test.assertErr(fs.writeBytes("missing/item.txt", Bytes.empty()))
    7. let operation = error.contains("writeBytes")
    8. let path = error.contains("missing/item.txt")
    9. io.writeLine("{operation} {path}")
    Expected outputexit 0
    true true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true true

    This exact example has not been executed.

    Source evidence

    Identify the operation and path in a list error

    Link

    run · running · Verification: not-run

    main.tpzIdentify the operation and path in a list errorOpen in Playground
    1. import std.fs
    2. import std.bytes { Bytes }
    3. import std.test
    4. import std.io
    6. let error = test.assertErr(fs.list("missing/item.txt"))
    7. let operation = error.contains("list")
    8. let path = error.contains("missing/item.txt")
    9. io.writeLine("{operation} {path}")
    Expected outputexit 0
    true true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true true

    This exact example has not been executed.

    Source evidence

    Menu

    Download