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.

    Tools

    parse

    Parses a Topaz source file and reports whether its syntax is accepted.

    Invocation, options and results

    Link

    topaz parse

    Synopsis
    1. topaz parse <file>

    Input

    Supply exactly one file operand. The file must be readable UTF-8 and fit the source size limit. An unreadable file, malformed encoding, invalid syntax, unsupported language mode, or unavailable selected compiler fails.

    Compiler selection, verbosity, language selection, and positive compiler resource budgets use the listed options. A missing operand, extra operand, unknown option, unsupported format selector, joined option value, or repeated option is rejected before parsing.

    Options and conflicts

    OptionDefaultContractConflicts
    --compiler rust|selfself

    compiler selector (default self); rust selects the reference compiler Also rejects combination with --producer, --self-source.

    		None listed
    --verbosefalse

    Reports the selected compiler and whether it was explicit or the default. For version, prints the detailed release report.

    		None listed
    --language-version <5.21>5.21

    language version selector

    		None listed
    --compiler-memory-mib <MiB>8192

    self compiler worker memory budget (8192); overrides TOPAZ_COMPILER_MEMORY_MIB A positive integer is required. Environment input: TOPAZ_COMPILER_MEMORY_MIB.

    		None listed
    --compiler-time-ms <ms>1800000

    self compilation wall-clock budget (1800000); overrides TOPAZ_COMPILER_TIME_MS A positive integer is required. Environment input: TOPAZ_COMPILER_TIME_MS.

    		None listed

    Output channels

    stdout

    stderr

    Exit status

    0

    The complete source file has valid syntax.

    1

    Argument validation, source loading, parsing, compiler selection, or compiler execution fails.

    Effects

    The command reads the named source and installed compiler resources. It does not modify source, package files, lockfiles, or vendor content. A compiler may create and remove its owned temporary workspace.

    The command performs no network access and does not fetch dependencies.

    With the same source bytes, path spelling, language mode, compiler identity, resource settings, and diagnostic presentation settings, parsing produces the same verdict and report. Host I/O errors and resource exhaustion depend on the host.

    A file is parsed independently of package resolution. The command does not load imports, regenerate a lock, or resolve registry versions.

    Operation

    Link

    Use parse to isolate syntax problems before name resolution and type checking.

    Option conditions

    Link

    --compiler cannot be combined with bootstrap --producer or --self-source

    Behavior contract

    Link
    Ruletools-commands-parse.rule.behavior

    Command behavior

    Arguments and rejection

    Supply exactly one file operand. The file must be readable UTF-8 and fit the source size limit. An unreadable file, malformed encoding, invalid syntax, unsupported language mode, or unavailable selected compiler fails.

    Compiler selection, verbosity, language selection, and positive compiler resource budgets use the listed options. A missing operand, extra operand, unknown option, unsupported format selector, joined option value, or repeated option is rejected before parsing.

    Output

    Successful parsing writes the input path followed by parse-ok and a newline to standard output. Diagnostics and a failure count use standard error. Verbose compiler selection also uses standard error.

    --format json is rejected. This command has no selectable machine report. A syntax failure never emits the success line.

    Exit status

    Exit 0 means the parser accepted the file. Exit 1 covers argument validation, loading, parser diagnostics, unsupported compiler selection, and worker failure or exhausted budget.

    Filesystem effects

    The command reads the named source and installed compiler resources. It does not modify source, package files, lockfiles, or vendor content. A compiler may create and remove its owned temporary workspace.

    Network access

    The command performs no network access and does not fetch dependencies.

    Reproducibility

    With the same source bytes, path spelling, language mode, compiler identity, resource settings, and diagnostic presentation settings, parsing produces the same verdict and report. Host I/O errors and resource exhaustion depend on the host.

    Packages and locks

    A file is parsed independently of package resolution. The command does not load imports, regenerate a lock, or resolve registry versions.

    Why

    Parsing answers whether a file has valid syntax before any dependency, type, or runtime obligation is considered. Its report must not imply those later checks succeeded.

    Examples Small source invocation

    Source evidence

    The linked public CLI recipe checks one valid generic declaration, exit 0, its exact success line, and empty standard error.

    The existing safe recipe covers a valid generic declaration. Missing files, invalid syntax, resource failures, and alternate options require argument vectors outside that allowlist.

    Example contract

    Link
    Ruletools-commands-parse.rule.invocation

    Example contract

    The invocation topaz parse main.tpz --language-version 5.21 is expected to exit with 0.

    The current SELF parser accepts the complete generic declaration. It prints the fixture path followed by parse-ok.

    Why

    A generic declaration is ordinary Topaz syntax. Parsing it does not require choosing concrete type arguments or calling the function.

    Examples Small source invocation

    Source evidence

    Example

    Link

    Small source invocation

    Link

    parse · parsing · Verification: not-run

    main.tpzSmall source invocationOpen in Playground
    1. function identity<T>(value: T) -> T {
    2. value
    3. }
    Expected outputexit 0
    main.tpz: parse-ok
    $ topaz parse main.tpz --language-version 5.21 · target product 5.21.3
    Expected result

    Expected result

    Parsing accepts the program. Exit code 0.

    No stderr.

    Expected stdout
    1. main.tpz: parse-ok

    This exact example has not been executed.

    The current SELF parser accepts the complete generic declaration. It prints the fixture path followed by parse-ok.

    Source evidence

    Verification scope

    Link

    Observed with Topaz 5.21.3 on 2026-11-06T08:36:29.642Z. This invocation passed; exit 0. 3 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation. That record uses the earlier fixture revision. The current recipe has not been run.

    Related references

    Link

    Compiler selection

    Packages, locks and targets

    Menu

    Download