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

    Write a line, read standard input, and open file resources.

    APIs in this module

    6 APIs

    NameModule
    File.closestd.io
    File.readstd.io
    File.writestd.io
    std.io.openstd.io
    std.io.readStdinstd.io
    std.io.writeLinestd.io

    Module

    Link

    Process streams carry input and output. File resources share a cursor and closed state across aliases. Use std.fs for operations on complete file contents.

    Why

    Link

    Stream operations expose consumption and lifetime. Whole file replacement already has its own meaning in std.fs.

    Availability

    Link

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

    Public API

    Link

    std.io.writeLine

    std.io.readStdin

    std.io.open

    File.close

    File.read

    File.write

    Pending contracts

    Link

    Read standard input through its end

    Link
    Ruletopaz.stdlib.contract.stdin-consumption.rule

    Read standard input through its end

    readStdin reads the remaining standard input bytes through EOF. UTF-8 validity and text preservation follow UTF-8 decoding. It does not append or remove a newline.

    No remaining bytes produces an empty string. A later call reads from the stream position left by the earlier call and therefore returns an empty string at EOF. A terminal follows the same EOF rule as redirected input.

    The call may wait for input or EOF. Reading consumes input even when the result is later discarded. A host read failure or invalid UTF-8 produces a structured runtime fault at the readStdin call because the function returns a string rather than a Result.

    The Topaz 6.0 host input fault is TPZ4008. Its primary location is the readStdin call.

    Why

    Standard input is a stream shared with the host. Consuming it once gives EOF one meaning and lets terminal and redirected input obey the same rule. Strict UTF-8 prevents malformed bytes from silently becoming different text.

    Examples Preserve redirected text and its line endingsReturn empty text at an empty input streamObserve EOF after standard input has been consumed

    Source evidence

    Preserve redirected text and its line endings

    Link

    run · running · Verification: not-run

    main.tpzPreserve redirected text and its line endingsOpen in Playground
    1. import std.io
    3. let text = io.readStdin()
    4. io.writeLine(text)
    Expected outputexit 0
      alpha
한글
    $ topaz run main.tpz · target product 5.21.3
    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

    Return empty text at an empty input stream

    Link

    run · running · Verification: not-run

    main.tpzReturn empty text at an empty input streamOpen in Playground
    1. import std.io
    3. let text = io.readStdin()
    4. let empty = text == ""
    5. io.writeLine("{empty}")
    Expected outputexit 0
    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

    This exact example has not been executed.

    Source evidence

    Observe EOF after standard input has been consumed

    Link

    run · running · Verification: not-run

    main.tpzObserve EOF after standard input has been consumedOpen in Playground
    1. import std.io
    3. let first = io.readStdin()
    4. let second = io.readStdin()
    5. let atEnd = second == ""
    6. io.writeLine(first)
    7. io.writeLine("{atEnd}")
    Expected outputexit 0
    alpha
true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. alpha
    2. true

    This exact example has not been executed.

    Source evidence

    Use a file handle with a shared cursor

    Link
    Ruletopaz.stdlib.contract.file-resources.rule

    Use a file handle with a shared cursor

    open evaluates its path once and opens an existing regular file for reading and writing. It does not create or truncate a file. A successful result is Ok containing a File with the cursor at the first byte.

    String paths use the host path syntax. Relative paths resolve against the working directory for an ordinary installed CLI invocation. A package host applies its configured filesystem base and capability policy. NUL, an empty path, a missing file, a directory, and denied read or write access return Err containing an error string.

    An open error follows the filesystem error context contract with open as the public operation. An error result does not grant a handle, and path validation does not bypass operating system or package permissions.

    File values refer to a resource identity. Copies share the open state and cursor. The handle continues to identify the opened file when the directory entry is renamed or replaced. This is the host resource exception in collection value semantics.

    read consumes the remaining bytes from the shared cursor through EOF. UTF-8 validity and text preservation follow UTF-8 decoding. A successful read returns Ok containing text, and a successful read at EOF returns an empty string.

    A read error returns Err containing an error string without a text value. Bytes already consumed before a host or decoding error are not restored. Callers must not assume the previous cursor position after a read error.

    write encodes its string as UTF-8 and writes all bytes at the shared cursor. It adds no newline. Success advances the cursor by the encoded byte count, overwrites those bytes, and preserves an existing suffix beyond them. A write at EOF extends the file.

    An empty write succeeds without moving the cursor. A closed handle, denied access, or host write failure returns Err. A host failure may leave a written prefix and an advanced cursor. It does not roll back earlier argument effects or file changes.

    close returns unit, releases the resource, and marks every alias closed. Closing an already closed resource also returns unit. A later read or write through any alias returns Err. A host failure while closing produces a structured runtime fault at the close call.

    The Topaz 6.0 host close fault is TPZ4009. Its primary location is the close call. A successful write or close does not promise persistence across a system crash.

    Receiver and argument expressions are evaluated once in source order before each resource operation. Use std.fs for whole file replacement or whole file reads. Use File when successive operations must share a cursor and lifetime.

    Why

    A handle gives successive operations one cursor and one lifetime. Whole file operations already belong to std.fs, so rereading and replacing by path would duplicate their meaning. An existing file open avoids surprising creation or truncation, and recoverable access failures stay in Result.

    Examples Open and close an existing file without changing its bytesReject a directory when opening a fileShare the cursor across file aliasesWrite at the cursor and retain the rest of the fileExtend a file after reading through EOFClose every alias and reject later accessReturn a file read error for invalid UTF-8

    Source evidence

    Open and close an existing file without changing its bytes

    Link

    run · running · Verification: not-run

    main.tpzOpen and close an existing file without changing its bytesOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. file.close()
    7. io.writeLine(test.assertOk(fs.readText("source.txt")))
    8. let missing = test.assertErr(io.open("missing.txt"))
    9. let named = missing.contains("missing.txt")
    10. io.writeLine("missing {named}")
    Expected outputexit 0
    original
missing true
    $ topaz run main.tpz · target product 5.21.3
    source.txtOpen and close an existing file without changing its bytesOpen in Playground
    1. original
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. original
    2. missing true

    This exact example has not been executed.

    Source evidence

    Reject a directory when opening a file

    Link

    run · running · Verification: not-run

    main.tpzReject a directory when opening a fileOpen in Playground
    1. import std.io
    3. match (io.open(".")) {
    4. case Err(_) => io.writeLine("directory rejected")
    5. case Ok(file) => {
    6. file.close()
    7. io.writeLine("directory accepted")
    8. }
    9. }
    Expected outputexit 0
    directory rejected
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. directory rejected

    This exact example has not been executed.

    Source evidence

    Share the cursor across file aliases

    Link

    run · running · Verification: not-run

    main.tpzShare the cursor across file aliasesOpen in Playground
    1. import std.io
    2. import std.test
    4. let file = test.assertOk(io.open("source.txt"))
    5. let alias = file
    6. io.writeLine(test.assertOk(file.read()))
    7. let tail = test.assertOk(alias.read())
    8. let atEnd = tail == ""
    9. io.writeLine("{atEnd}")
    10. alias.close()
    Expected outputexit 0
    alpha
true
    $ topaz run main.tpz · target product 5.21.3
    source.txtShare the cursor across file aliasesOpen in Playground
    1. alpha
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. alpha
    2. true

    This exact example has not been executed.

    Source evidence

    Write at the cursor and retain the rest of the file

    Link

    run · running · Verification: not-run

    main.tpzWrite at the cursor and retain the rest of the fileOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. test.assertOk(file.write("XY"))
    7. let tail = test.assertOk(file.read())
    8. io.writeLine("tail {tail}")
    9. file.close()
    10. let whole = test.assertOk(fs.readText("source.txt"))
    11. io.writeLine("whole {whole}")
    Expected outputexit 0
    tail cdef
whole XYcdef
    $ topaz run main.tpz · target product 5.21.3
    source.txtWrite at the cursor and retain the rest of the fileOpen in Playground
    1. abcdef
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. tail cdef
    2. whole XYcdef

    This exact example has not been executed.

    Source evidence

    Extend a file after reading through EOF

    Link

    run · running · Verification: not-run

    main.tpzExtend a file after reading through EOFOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. test.assertOk(file.read())
    7. test.assertOk(file.write("β"))
    8. file.close()
    9. io.writeLine(test.assertOk(fs.readText("source.txt")))
    Expected outputexit 0
    alphaβ
    $ topaz run main.tpz · target product 5.21.3
    source.txtExtend a file after reading through EOFOpen in Playground
    1. alpha
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. alphaβ

    This exact example has not been executed.

    Source evidence

    Close every alias and reject later access

    Link

    run · running · Verification: not-run

    main.tpzClose every alias and reject later accessOpen in Playground
    1. import std.io
    2. import std.fs
    3. import std.test
    5. let file = test.assertOk(io.open("source.txt"))
    6. let alias = file
    7. file.close()
    8. alias.close()
    9. test.assertErr(alias.read())
    10. io.writeLine("read rejected")
    11. test.assertErr(alias.write("changed"))
    12. io.writeLine("write rejected")
    13. io.writeLine(test.assertOk(fs.readText("source.txt")))
    Expected outputexit 0
    read rejected
write rejected
original
    $ topaz run main.tpz · target product 5.21.3
    source.txtClose every alias and reject later accessOpen in Playground
    1. original
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. read rejected
    2. write rejected
    3. original

    This exact example has not been executed.

    Source evidence

    Return a file read error for invalid UTF-8

    Link

    run · running · Verification: not-run

    main.tpzReturn a file read error for invalid UTF-8Open in Playground
    1. import std.io
    2. import std.fs
    3. import std.bytes { Bytes }
    4. import std.test
    6. let invalid = test.assertOk(Bytes.fromArray([255]))
    7. test.assertOk(fs.writeBytes("invalid.txt", invalid))
    8. let file = test.assertOk(io.open("invalid.txt"))
    9. test.assertErr(file.read())
    10. file.close()
    11. io.writeLine("invalid text rejected")
    Expected outputexit 0
    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. invalid text rejected

    This exact example has not been executed.

    Source evidence

    Menu

    Download