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

    Compiler selection

    Select the compiler and language mode for a Topaz invocation, then confirm the selection in the command output.

    Select a compiler

    Link

    Run topaz compiler status --format json to inspect the installed compiler before choosing an implementation. Run topaz version to identify the product release.

    An explicit --compiler self selects SELF. An explicit --compiler rust selects the reference compiler for verification. When the selector is absent, compiler-bearing commands use SELF. A rejected operation does not silently switch to the reference compiler.

    Default selection source · Selection validation source

    Compiler selection and artifact selection answer different questions. --compiler rust chooses an implementation. emit --target rust requests Rust source. A native build target can use SELF. Read the command reference for the supported combinations.

    Select the language mode

    Link

    For an entry-file invocation, the current language mode is used when --language-version is absent. The public 5.21.x CLI accepts the current 5.21 mode. A product patch version such as 5.21.3 identifies a release, not a separate language mode.

    Language selector source

    During package-mode compilation, [package].language in topaz.toml supplies the language mode before entry-source loading. An explicit language selector must agree with the manifest. A different manifest mode or a conflicting selector is rejected.

    Package selection source

    Keep the selected package root consistent across check, run, and build invocations. An entry operand normally selects an entry-file route. The test command also preserves package context when its selected root contains a manifest.

    Command scope

    Link

    Compiler selection applies to parse, dump-ast, check, run, test, fmt, lsp, emit, build, doc, bench, and compiler observe.

    Compiler-bearing command source

    Package management, storage, embedded Lispex, lookup, metadata, and compiler inspection commands use their own command contracts. They reject an explicit --compiler selector. This includes compiler preview, compiler status, compiler validate, and compiler compare.

    Selector applicability source

    compiler preview selects its producer through its preview options. Combining --compiler with --producer or --self-source is rejected. Producer selection does not change the default used by a later check or build invocation.

    Confirm the selection

    Link

    Add --verbose to a compiler-bearing invocation to report the selected compiler on standard error. The report distinguishes an explicit choice from the current default with explicit and current-default.

    Selection report source

    An LSP session may receive its package root during initialize. Its compiler selection is reported after the workspace supplies the language mode.

    topaz compiler status --format json returns installed compiler identity, the default and reference selectors, and command support conditions. Read that inventory alongside the command's options and conflicts. Status output describes the installed tool. A successful status request is not a successful check or build.

    Status output source

    Usage profiles

    Link

    A check usage profile adds checks for an intended use. The check contract defines its inputs, diagnostics, and reports. Installed profile availability remains a distribution evidence question.

    Type checking without a mode flag

    Link
    Ruletopaz.tools.types-option.rule

    Type checking without a mode flag

    Use topaz check <entry> for type checking. --types is rejected during command validation.

    Why

    The check command performs type checking with or without the ineffective flag. Both spellings request the same operation, so the flag has no separate intent to preserve.

    Examples Reject the unused types optionCheck with the canonical command

    Diagnostics Type checking without a mode flag rejection

    Source evidence

    Type checking without a mode flag rejection

    Family
    topaz-cli
    Phase
    command
    Operation
    argument-validation
    Category
    types-option

    Cause and conditions

    Use topaz check <entry> for type checking. --types is rejected during command validation.

    Related rule: Type checking without a mode flag

    Response

    Run topaz check <entry> without --types.

    Source evidence

    Type checking without a mode flag examples

    Link

    Reject the unused types option

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject the unused types optionOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz check main.tpz --format json --types · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Check with the canonical command

    Link

    check · command-validation · Verification: not-run

    main.tpzCheck with the canonical commandOpen in Playground
    1. let value = 1
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Named metadata commands and long options

    Link
    Ruletopaz.tools.metadata-spellings.rule

    Named metadata commands and long options

    Use topaz version for the installed release report. topaz --version and topaz -V are rejected during command validation.

    Use --verbose for additional command details. -v is rejected during command validation.

    Why

    The version aliases request the same installed release report as the version command. The short verbosity alias requests the same additional detail as the verbose option. Neither alias expresses a different intent.

    Examples Reject the version flag aliasReject the short version aliasReject the short detail aliasRead the installed releaseRequest the detailed release report

    Diagnostics Named metadata commands and long options rejection

    Source evidence

    Named metadata commands and long options rejection

    Family
    topaz-cli
    Phase
    command
    Operation
    argument-validation
    Category
    metadata-spellings

    Cause and conditions

    Use topaz version for the installed release report. topaz --version and topaz -V are rejected during command validation.

    Use --verbose for additional command details. -v is rejected during command validation.

    Related rule: Named metadata commands and long options

    Use topaz version for the installed release report. topaz --version and topaz -V are rejected during command validation.

    Use --verbose for additional command details. -v is rejected during command validation.

    Related rule: Named metadata commands and long options

    Response

    Use topaz version and add --verbose when a detailed report is needed.

    Source evidence

    Named metadata commands and long options examples

    Link

    Reject the version flag alias

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject the version flag aliasOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz --version · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject the short version alias

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject the short version aliasOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz -V · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject the short detail alias

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject the short detail aliasOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz version -v · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Read the installed release

    Link

    check · command-validation · Verification: not-run

    main.tpzRead the installed releaseOpen in Playground
    1. let value = 1
    Expected outputexit 0
    Topaz 5.21.3
    $ topaz version · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    Expected stdout
    1. Topaz 5.21.3

    This exact example has not been executed.

    Source evidence

    Request the detailed release report

    Link

    check · command-validation · Verification: not-run

    main.tpzRequest the detailed release reportOpen in Playground
    1. let value = 1
    Expected outputexit 0
    $ topaz version --verbose · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    This exact example has not been executed.

    Source evidence

    Separate option values

    Link
    Ruletopaz.tools.value-separator.rule

    Separate option values

    An option and its value occupy separate arguments, as in --format json. The --option=value form is rejected during command validation.

    This rule applies to CLI options. Arguments after -- are program data and preserve their spelling.

    Why

    The joined and separate forms supply the same value to the same option. A separate argument preserves that intent with one spelling and matches the command synopsis.

    Examples Reject an equals format valueReject an equals language valuePass values as separate arguments

    Diagnostics Separate option values rejection

    Source evidence

    Separate option values rejection

    Family
    topaz-cli
    Phase
    command
    Operation
    argument-validation
    Category
    value-separator

    Cause and conditions

    An option and its value occupy separate arguments, as in --format json. The --option=value form is rejected during command validation.

    Related rule: Separate option values

    Response

    Pass each option and its value as separate arguments, such as --format json.

    Source evidence

    Separate option values examples

    Link

    Reject an equals format value

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject an equals format valueOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz check main.tpz --format=json · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject an equals language value

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject an equals language valueOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz check main.tpz --format json --language-version=5.21 · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Pass values as separate arguments

    Link

    check · command-validation · Verification: not-run

    main.tpzPass values as separate argumentsOpen in Playground
    1. let value = 1
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --language-version 5.21 --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    One occurrence of each option

    Link
    Ruletopaz.tools.option-occurrence.rule

    One occurrence of each option

    An option appears at most once in an invocation. Repeated occurrences are rejected even when their values agree. The order of conflicting values does not select a winner.

    Repeated options are rejected as unexpected arguments. This rule does not reinterpret program arguments after --.

    Why

    Each option selects one value or behavior. Rejecting repeated selectors prevents argument order from changing that choice and applies equally when the values agree.

    Examples Reject a repeated language selectorReject conflicting formats in one orderReject conflicting formats in the other orderGive each option onceReject a repeated boolean option

    Diagnostics One occurrence of each option rejection

    Source evidence

    One occurrence of each option rejection

    Family
    topaz-cli
    Phase
    command
    Operation
    argument-validation
    Category
    option-occurrence

    Cause and conditions

    An option appears at most once in an invocation. Repeated occurrences are rejected even when their values agree. The order of conflicting values does not select a winner.

    Related rule: One occurrence of each option

    Response

    Give each CLI option once and resolve conflicting choices before invoking Topaz.

    Source evidence

    One occurrence of each option examples

    Link

    Reject a repeated language selector

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject a repeated language selectorOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz check main.tpz --format json --language-version 5.21 --language-version 5.21 · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject conflicting formats in one order

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject conflicting formats in one orderOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz check main.tpz --format json --format human · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject conflicting formats in the other order

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject conflicting formats in the other orderOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz check main.tpz --format human --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Give each option once

    Link

    check · command-validation · Verification: not-run

    main.tpzGive each option onceOpen in Playground
    1. let value = 1
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --language-version 5.21 --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject a repeated boolean option

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject a repeated boolean optionOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz check main.tpz --format json --verbose --verbose · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    One JSON format selector

    Link
    Ruletopaz.tools.json-format.rule

    One JSON format selector

    Use --format json for JSON output from check, compiler status, explain, bench, lispex embed info. --json is rejected during command validation. lispex embed info requires --format json and does not accept a human output format. Each command retains its own output fields and streams.

    The format selector changes the representation of a command result. It does not merge the different records. check writes its diagnostic JSON to standard error. The other listed commands write one report to standard output. lispex embed info requires JSON. The other listed commands retain their human output format. Timing values vary between benchmark executions.

    Why

    The old JSON switch and the format selector request the same report representation. The shared selector preserves that intent while each command retains its own report. Export inspection and diagnostic reporting remain distinct operations.

    Examples Reject --json for compiler statusSelect JSON for compiler statusReject --json for diagnostic explanationSelect JSON for diagnostic explanationReject --json for benchmark reportBenchmark JSON with --format jsonReject --json for embedded component reportSelect JSON for embedded component reportKeep the check diagnostic format

    Diagnostics One JSON format selector rejection

    Source evidence

    One JSON format selector rejection

    Family
    topaz-cli
    Phase
    command
    Operation
    argument-validation
    Category
    json-format

    Cause and conditions

    Use --format json for JSON output from check, compiler status, explain, bench, lispex embed info. --json is rejected during command validation. lispex embed info requires --format json and does not accept a human output format. Each command retains its own output fields and streams.

    Related rule: One JSON format selector

    Response

    Use --format json with a CLI that implements the Topaz 6.0 output selector.

    Source evidence

    One JSON format selector examples

    Link

    Reject --json for compiler status

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject --json for compiler statusOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz compiler status --json · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Select JSON for compiler status

    Link

    check · command-validation · Verification: not-run

    main.tpzSelect JSON for compiler statusOpen in Playground
    1. let value = 1
    Expected outputexit 0
    $ topaz compiler status --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    Standard output is a JSON object. Its complete schema is not specified.

    This exact example has not been executed.

    Source evidence

    Reject --json for diagnostic explanation

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject --json for diagnostic explanationOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz explain TPZ4002 --json · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Select JSON for diagnostic explanation

    Link

    check · command-validation · Verification: not-run

    main.tpzSelect JSON for diagnostic explanationOpen in Playground
    1. let value = 1
    Expected outputexit 0
    $ topaz explain TPZ4002 --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    Standard output is a JSON object. Its complete schema is not specified.

    This exact example has not been executed.

    Source evidence

    Reject --json for benchmark report

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject --json for benchmark reportOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz bench main.tpz --language-version 5.21 --json · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Benchmark JSON with --format json

    Link

    check · command-validation · Verification: not-run

    main.tpzBenchmark JSON with --format jsonOpen in Playground
    1. function identity<T>(value: T) -> T {
    2. value
    3. }
    Expected outputexit 0
    $ topaz bench main.tpz --language-version 5.21 --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    Standard output is a JSON object. Its complete schema is not specified.

    This exact example has not been executed.

    The benchmark checks the fixture without running it and writes a JSON report. Timing values vary between executions.

    Source evidence

    Reject --json for embedded component report

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject --json for embedded component reportOpen in Playground
    1. let value = 1
    Expected outputNonzero exit
    No stdout.
    $ topaz lispex embed info --json · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Nonzero exit.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Select JSON for embedded component report

    Link

    check · command-validation · Verification: not-run

    main.tpzSelect JSON for embedded component reportOpen in Playground
    1. let value = 1
    Expected outputexit 0
    $ topaz lispex embed info --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    Standard output is a JSON object. Its complete schema is not specified.

    This exact example has not been executed.

    Source evidence

    Keep the check diagnostic format

    Link

    check · command-validation · Verification: not-run

    main.tpzKeep the check diagnostic formatOpen in Playground
    1. let value = 1
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --language-version 5.21 --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    A command is required

    Link
    Ruletopaz.tools.command-presence.rule

    Name the help command

    Use topaz help for command and option help. topaz is rejected during command validation.

    An invocation must name a command. A missing command is a usage error with exit status 1 and empty standard output. The CLI reports the missing command on standard error and directs the user to topaz help. This textual failure has no TPZ code or source location.

    Why

    An explicit help command requests the command reference. An omitted command supplies no operation and can result from a missing script argument. Requiring an explicit request keeps that mistake observable.

    Examples Reject an invocation without a commandRequest help by name

    Diagnostics Missing command

    Source evidence

    Missing command

    Family
    topaz-cli
    Phase
    command
    Operation
    argument-validation
    Category
    missing-command

    Cause and conditions

    Use topaz help for command and option help. topaz is rejected during command validation.

    Related rule: Name the help command

    Response

    Supply the command to run. Use topaz help to read the command and option help.

    Source evidence

    Request help explicitly

    Link

    Reject an invocation without a command

    Link

    reject · command-validation · Verification: not-run

    main.tpzReject an invocation without a commandOpen in Playground
    1. let value = 1
    Expected outputexit 1
    No stdout.
    $ topaz · target product 5.21.3
    Expected result

    Expected result

    Rejection during command. Exit code 1.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Request help by name

    Link

    check · command-validation · Verification: not-run

    main.tpzRequest help by nameOpen in Playground
    1. let value = 1
    Expected outputexit 0
    $ topaz help · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    This exact example has not been executed.

    topaz help prints the installed command and option help. Its wording and command inventory can grow. This example checks successful completion and an empty standard error stream.

    Source evidence

    Related commands and configuration

    Link

    compiler status

    Packages, locks and targets

    check

    Menu

    Download