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.toml.parse

    Parses TOML text into a TOMLValue.

    parse(text: string) -> Result<TOMLValue, string>
    Module
    std.toml
    Receiver
    Not applicable
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.toml in language mode 5.21.

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

    parse accepts a complete TOML 1.0 document. An empty document or comments with whitespace produce an empty root table. Basic and literal strings, multiline strings, dotted and quoted keys, inline tables, arrays and arrays of tables retain their TOML meanings.

    Integers must fit the signed 64 bit range. TOML decimal, hexadecimal, octal and binary spellings and valid underscore separators are accepted. Floating values use IEEE binary64 rounding. The TOML inf and nan forms are valid TOML values. Finite overflow follows the TOML numeric error boundary and returns Err.

    Offset date times, local date times, local dates and local times remain distinct TOML kinds. Invalid calendar fields and time fields return Err. Strings that resemble dates remain strings.

    A key or table definition may not redefine an existing value under the TOML 1.0 rules. Names are compared after decoding. Malformed escapes, leading zeroes and misplaced underscore separators return Err without exposing a partial document.

    A failure returns a nonempty string identifying the cause, one based line and Unicode scalar column. CRLF is a single line break. The first offending scalar is the location and an incomplete input points immediately after its last scalar. Source comments and layout are not retained in TOMLValue.

    The text argument is evaluated once. Parsing consumes the complete document, performs no I/O and does not invoke JSON conversion. Syntax failures use Err rather than a runtime diagnostic.

    Related rule: Parse complete TOML 1.0 documents

    Result

    Additional contracts are Pending.

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

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Parse a complete TOML 1.0 document and report invalid input with a cause and position.

    Related entries

    Link

    std.toml

    Parse complete TOML 1.0 documents

    Link
    Ruletopaz.stdlib.contract.toml-parse.rule

    Parse complete TOML 1.0 documents

    parse accepts a complete TOML 1.0 document. An empty document or comments with whitespace produce an empty root table. Basic and literal strings, multiline strings, dotted and quoted keys, inline tables, arrays and arrays of tables retain their TOML meanings.

    Integers must fit the signed 64 bit range. TOML decimal, hexadecimal, octal and binary spellings and valid underscore separators are accepted. Floating values use IEEE binary64 rounding. The TOML inf and nan forms are valid TOML values. Finite overflow follows the TOML numeric error boundary and returns Err.

    Offset date times, local date times, local dates and local times remain distinct TOML kinds. Invalid calendar fields and time fields return Err. Strings that resemble dates remain strings.

    A key or table definition may not redefine an existing value under the TOML 1.0 rules. Names are compared after decoding. Malformed escapes, leading zeroes and misplaced underscore separators return Err without exposing a partial document.

    A failure returns a nonempty string identifying the cause, one based line and Unicode scalar column. CRLF is a single line break. The first offending scalar is the location and an incomplete input points immediately after its last scalar. Source comments and layout are not retained in TOMLValue.

    The text argument is evaluated once. Parsing consumes the complete document, performs no I/O and does not invoke JSON conversion. Syntax failures use Err rather than a runtime diagnostic.

    Why

    Configuration files need a named format version and predictable rejection of invalid definitions. Preserving TOML kinds lets callers choose a separate and explicit conversion into JSON.

    Examples Parse a table and write its deterministic formAccept literal strings, multiline values, radix integers and datesReject malformed numeric spellings and repeated definitionsReturn line and scalar column in a TOML error

    Source evidence

    Parse a table and write its deterministic form

    Link

    run · running · Verification: not-run

    main.tpzParse a table and write its deterministic formOpen in Playground
    1. import std.toml
    2. import std.test
    3. import std.io
    4. let value = test.assertOk(toml.parse("title = \"Topaz\"\ncount = 6\nactive = true\n[page]\nwidth = 210\n"))
    5. io.writeLine(test.assertOk(toml.stringify(value)))
    6. let empty = test.assertOk(toml.parse(" # comment\n"))
    7. test.assertEq(test.assertOk(toml.stringify(empty)), "")
    Expected outputexit 0
    active = true
count = 6
title = "Topaz"

[page]
width = 210
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. active = true
    2. count = 6
    3. title = "Topaz"
    5. [page]
    6. width = 210

    This exact example has not been executed.

    Source evidence

    Accept literal strings, multiline values, radix integers and dates

    Link

    run · running · Verification: not-run

    main.tpzAccept literal strings, multiline values, radix integers and datesOpen in Playground
    1. import std.toml
    2. import std.io
    3. for text in (["title = 'ink#paper'\n", "text = \"\"\"\nfirst\nsecond\"\"\"\n", "value = 0xff\n", "date = 1979-05-27T07:32:00Z\n", "value = inf\n", "value = nan\n"]) {
    4. match (toml.parse(text)) {
    5. case Ok(_) => io.writeLine("accepted")
    6. case Err(_) => io.writeLine("rejected")
    7. }
    8. }
    Expected outputexit 0
    accepted
accepted
accepted
accepted
accepted
accepted
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. accepted
    2. accepted
    3. accepted
    4. accepted
    5. accepted
    6. accepted

    This exact example has not been executed.

    Source evidence

    Reject malformed numeric spellings and repeated definitions

    Link

    run · running · Verification: not-run

    main.tpzReject malformed numeric spellings and repeated definitionsOpen in Playground
    1. import std.toml
    2. import std.io
    3. for text in (["n = 1__0\n", "n = 01\n", "[a]\nx = 1\n[a]\ny = 2\n", "x = 1\nx = 2\n"]) {
    4. match (toml.parse(text)) {
    5. case Ok(_) => io.writeLine("accepted")
    6. case Err(_) => io.writeLine("invalid")
    7. }
    8. }
    Expected outputexit 0
    invalid
invalid
invalid
invalid
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. invalid
    2. invalid
    3. invalid
    4. invalid

    This exact example has not been executed.

    Source evidence

    Return line and scalar column in a TOML error

    Link

    run · running · Verification: not-run

    main.tpzReturn line and scalar column in a TOML errorOpen in Playground
    1. import std.toml
    2. import std.test
    3. import std.io
    4. let error = test.assertErr(toml.parse("x = ?"))
    5. test.assertContains(error, "line 1")
    6. test.assertContains(error, "column 5")
    7. io.writeLine("located")
    Expected outputexit 0
    located
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. located

    This exact example has not been executed.

    Source evidence

    Menu

    Download