CLI Reference

go install syntaxir.dev/sxir/cmd/sxir@latest

Overview

Command sxir is a command-line tool for working with SyntaxIR grammars.

Usage:

sxir parse -g grammar.sxir [-s main] [-i input] [-f json|sexpr] [-stream] [-unit u] [-backend b] [-source-info] [-default-value] [-max-compute n] [-max-memory n] [-max-input n] [-max-depth n]
sxir test -f suite.json [-format text|json] [-backend closure,bytecode] [-equivalence] [-update] [-max-compute n] [-max-memory n] [-max-input n] [-max-depth n]
sxir fmt [-w] [-l] [-check] [-syntax] [grammar.sxir ...]
sxir convert [-to sxir|json] [-o output] grammar.sxir|grammar.json
sxir gen -g grammar.sxir -module path -o dir [-pkg name] [-lib embed|import|only] [-s main] [-types] [-document] [-stream] [-recognize] [-observability] [-no-limits] [-typed-only] [-recognize-only] [-nodoc] [-max-depth n] [-source-info] [-default-value] [-expectations] [-optimize profile] [-opt names] [-no-opt names] [-print-before passes] [-print-after passes] [-print-changed] [-verify-each] [-stats] [-time-passes] [-opt-bisect-limit n]
sxir gen -lang ts -g grammar.sxir -o dir [-lib embed|import|only] [-lib-module specifier] [-s main] [-types] [-recognize] [-observability] [-no-limits] [-max-depth n] [-source-info] [-default-value] [-expectations] [-optimize profile] [-opt names] [-no-opt names] [-print-before passes] [-print-after passes] [-print-changed] [-verify-each] [-stats] [-time-passes] [-opt-bisect-limit n]
sxir compile -g grammar.sxir [-s main] [-mode parse|recognize|document] [-source-info] [-default-value] -o grammar.sxirc
sxir trace -g grammar.sxir [-s main] [-i input] [-show-depth n] [-rule name] [-failures] [-f text|json] [-max-compute n] [-max-memory n] [-max-input n] [-max-depth n]
sxir profile -g grammar.sxir [-s main] [-i input] [-sort column] [-n rows] [-f text|json] [-max-compute n] [-max-memory n] [-max-input n] [-max-depth n]
sxir explain -g grammar.sxir [-s main] [-i input] [-n calls] [-max-compute n] [-max-memory n] [-max-input n] [-max-depth n]
sxir lint -g grammar.sxir [-s main] [-f text|json] [-disable checks] [-strict] [-classify] [-list]
sxir sample -g grammar.sxir [-s main] [-n 10] [-seed N] [-max-depth D] [-max-repeat R] [-max-len L] [-budget B]
            [-coverage] [-invalid] [-f lines|json]
sxir schema -g grammar.sxir [-s main] [-all-rules] [-o schema.json]
sxir schema diff [-s main] [-all-rules] [-f text|json] before after
sxir edit-fuzz -g grammar.sxir [-s main] [-backend names] [-unit names] [-seed N] [-corpus path] [-sequences n]
               [-operations n] [-save-failures dir] [-minimize] [-max-attempts n] [-max-compute n] [-max-memory n] [-max-input n] [-max-depth n]
sxir edit-fuzz -g grammar.sxir -replay sequence.json [-minimize] [-save-failures dir] [-max-compute n] [-max-memory n] [-max-input n] [-max-depth n]
sxir lsp

Usage

sxir <command> [flags] [arguments]

Limits: parse, test, trace, profile, explain and edit-fuzz take -max-compute, -max-memory, -max-input and -max-depth. -max-compute bounds the cost of a parse in units; 0, the default, selects max(2^20, 1024 times the input length). -max-memory bounds the bytes of storage the parser holds for the parse; 0, the default, sets no bound. -max-input bounds the length of the input in the position unit; 0, the default, sets no bound. -max-depth bounds the nesting of recursive rule calls; 0, the default, selects 100000, or 10000000 for bytecode-iterative. Each also takes the word unlimited, which disables the limit; an unlimited depth needs bytecode-iterative. A parse that reaches a limit prints the message of the limit error and exits with status 1, like any other failure.

A <grammar> is SyntaxIR source (.sxir), a grammar in JSON (.json), or, for parse, trace, profile, explain and compile, a grammar compiled with sxir compile (.sxirc). A file with another extension is JSON when its first character other than white space is {, and SyntaxIR source otherwise.

Run "sxir <command> -h" for the flags of a command.

This reference is generated from the output of sxir and sxir <command> -h.

Commands

sxir parse

sxir parse -g <grammar> [-s <rule>] [-i <input>] [-f json|sexpr] [-stream] [-recognize]
     [-unit codepoints|bytes] [-backend closure|bytecode|bytecode-iterative] [-source-info]
     [-default-value] [-max-compute <n>] [-max-memory <n>] [-max-input <n>] [-max-depth <n>]

Parse the input with a grammar and print the syntax tree. Without -i, the input is read from standard input. -source-info also prints the rule of each node and the names of captures. -default-value drops value actions and declared rule types (predicates still run) and prints the default node tree. -recognize checks the syntax without building a tree and prints ok if the input matches. -max-compute, -max-memory, -max-input and -max-depth bound the parse: see Limits below.

FlagDefaultDescription
-backend stringexecution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar)
-default-valuedrop value actions and declared rule types, and print the default node tree (predicates still run)
-f string"json"output format: json or sexpr
-g stringgrammar file (.sxir, .json, or .sxirc)
-i stringinput string (default: standard input)
-max-compute valuelimit on the cost of the parse: a number of units, 0 for the default of max(2^20, 1024 times the input length), or unlimited
-max-depth valuelimit on the nesting of recursive rule calls: a number, 0 for the backend's default (100000; 10000000 for bytecode-iterative), or unlimited (bytecode-iterative only)
-max-input valuelongest input accepted, in the position unit: a number, 0 or unlimited for no bound
-max-memory valuelimit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound
-recognizecheck the syntax of the input without building a tree, and print ok if it matches the grammar
-s stringstart rule name (default: the one saved in a .sxirc, otherwise the grammar's default start rule)
-source-inforecord the rule of each node and the names of captures, and print them
-streamprint each #stream element of the start rule on its own line as soon as it matches
-unit string"codepoints"unit of positions: codepoints or bytes

sxir test

sxir test -f <suite.json> [-format text|json] [-backend <names>] [-equivalence] [-update]

[-max-compute <n>] [-max-memory <n>] [-max-input <n>] [-max-depth <n>] Run a versioned JSON fixture suite. Outcomes distinguish accepted, recovered, and rejected parses; selected backend equivalence is reported separately. -update refreshes node and location goldens for one backend.

FlagDefaultDescription
-backend stringcomma-separated execution backends (default: those in the suite)
-equivalencecompare selected backends independently of fixture expectations
-f stringfixture suite JSON file
-format string"text"report format: text or json
-max-compute valuelimit on the cost of the parse: a number of units, 0 for the default of max(2^20, 1024 times the input length), or unlimited
-max-depth valuelimit on the nesting of recursive rule calls: a number, 0 for the backend's default (100000; 10000000 for bytecode-iterative), or unlimited (bytecode-iterative only)
-max-input valuelongest input accepted, in the position unit: a number, 0 or unlimited for no bound
-max-memory valuelimit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound
-updateupdate node and location goldens for one selected backend

sxir fmt

sxir fmt [-w] [-l] [-check] [-syntax] [<file.sxir> ...]

Format SyntaxIR source files, keeping comments. Without files, standard input is formatted. -w rewrites the files in place; -l lists the files whose formatting differs. -check lists them too and exits with status 1 if there are any, or 2 if a file cannot be formatted. -syntax prints a simplified syntax view and cannot be combined with -w, -l or -check.

FlagDefaultDescription
-checklist the files whose formatting differs and exit with status 1 if there are any, or 2 if a file cannot be formatted
-llist the files whose formatting differs
-syntaxprint a simplified grammar syntax view (cannot combine with -w, -l or -check)
-wwrite the result to the file instead of standard output

sxir convert

sxir convert [-to sxir|json] [-o <file>] <grammar>

Convert a grammar between SyntaxIR source and JSON. -to defaults to the other format of the input.

FlagDefaultDescription
-o stringoutput file (default: standard output)
-to stringoutput format, sxir or json (default: the other format of the input)

sxir gen

sxir gen -g <grammar> -module <import path> -o <dir> [-pkg <package>] [-lib embed|import|only] [-s <rule>] [-types]
     [-document] [-stream] [-recognize] [-observability] [-no-limits] [-typed-only] [-recognize-only] [-max-depth <n>] [-nodoc] [-source-info] [-default-value]
     [-expectations] [-optimize <profile>] [-opt <names>] [-no-opt <names>]
     [-print-before <passes>] [-print-after <passes>] [-print-changed] [-verify-each] [-stats]
     [-time-passes] [-opt-bisect-limit <n>]
sxir gen -lib only -o <dir>
sxir gen -lang ts -g <grammar> -o <dir> [-lib embed|import|only] [-lib-module <specifier>] [-s <rule>] [-types]
     [-recognize] [-observability] [-no-limits] [-max-depth <n>] [-source-info] [-default-value]
     [-expectations] [-optimize <profile>] [-opt <names>] [-no-opt <names>]
     [-print-before <passes>] [-print-after <passes>] [-print-changed] [-verify-each] [-stats]
     [-time-passes] [-opt-bisect-limit <n>]
sxir gen -lang ts -lib only -o <dir>

Generate a Go parser (or, with -lang ts, TypeScript modules) from a grammar. A Go parser is a package: parser.go, api.go and, with -lib embed (the default), a copy of the library in internal/libgo, all written below the directory -o (created if missing). -module is the import path of that package; the package name is its last element without a major version suffix, or -pkg. -lib import makes the parser import syntaxir.dev/sxir/pkg/runtime/libgo instead, and needs only -pkg or -module. Either way the parser imports the runtime packages under syntaxir.dev/sxir/pkg/runtime. -lib only writes just internal/libgo, to refresh a package generated with embed; it takes no grammar and no other generation flags. A file in -o that lacks the "Code generated by sxir" header is never overwritten, and earlier generated files that the new mode does not produce are removed. A TypeScript parser is the files parser.ts, with -types types.ts, and, with -lib embed (the default), lib.ts, a copy of the library that does not depend on the grammar, all written to -o. -lib import leaves lib.ts out and imports the library from the module -lib-module (required), such as ../shared/lib.ts; -lib only writes just lib.ts, to share it or to refresh the copy. With -types, types for the grammar's types and ParseValue (parseValue in TypeScript), which returns the result as typed values, are generated too. -document adds an incremental Document; with -types it also provides Document.ParseValue (parseValue in TypeScript). With -no-limits the Document runs without budget charges. -stream adds Go ParseStream, which reads an io.Reader and passes each committed element of the start rule's #stream repetition to a callback. It cannot be combined with -types or -lang ts. -observability emits opt-in rule tracing and profiling for Go batch parsing and Documents, and TypeScript batch parsing, including typed entry points. Generated parsers have limit controls by default: they support WithContext and finite Compute and Memory limits (signal and the compute limit in TypeScript) and apply the default limits to a parse that sets none. -no-limits generates the ordinary form instead: it is smaller and faster, WithContext is not exported, the generated code does not spend budget, and a parse that passes a context or a finite Compute or Memory limit fails. The Input and Depth limits work either way. A parser has one form only: generate a second parser with the other setting to have both. -typed-only generates only the typed entry points (ParseValue and its siblings), without Parse and ParseRule. It needs -types and cannot be combined with -document, -stream or -lang ts. -recognize-only generates only Recognize, without Parse, ParseRule or typed entry points; it cannot be combined with -types, -typed-only, -document, -stream or -lang ts. With -recognize, Recognize (recognize in TypeScript) checks input without building a tree. -nodoc leaves out the package comment of the Go code, for a package documented in another file. -max-depth sets the generated default nested recursive rule-call limit (0 selects 100000). -source-info makes the parser record the rule of each node and the names of captures. -default-value drops value actions and declared rule types, so the parser returns the default node tree; it cannot be combined with -types. -expectations makes the parser record what a syntax error expects. -optimize selects an optimization profile (speed, memory or size); -opt and -no-opt turn single optimizations on, off or to a count after the profile is applied. No optimization option changes what the parser returns: "sxir gen -h" lists the profiles, the optimizations and the pass names. -print-after writes the Core IR or Code IR to standard error after the named steps and passes, -print-before before the named passes, -print-changed after each pass that changed it, -verify-each verifies it after every pass, and -stats and -time-passes write the statistics and times of the passes after the build. They debug the generator and change no generated file. -opt-bisect-limit n runs only the first n runs of optional passes and reports each decision, to find the pass that breaks a parser; it generates once, keeping rules that a build would leave out. Their output is not stable and may change in any version.

FlagDefaultDescription
-charge-units string
-default-valuemake the generated parser drop value actions and declared rule types and return the default node tree (incompatible with -types)
-documentalso generate an incremental Document (typed ParseValue with -types)
-expectationsgenerate a parser that records what a syntax error expects (the expected list and @error messages); without it the error reports only the farthest failure position
-g stringgrammar file (.sxir or .json)
-lang string"go"language of the generated code: go or ts (TypeScript)
-lib string"embed"how generated code reaches the library: embed (a copy: internal/libgo in Go, lib.ts in TypeScript), import (syntaxir.dev/sxir/pkg/runtime/libgo in Go; the module of -lib-module in TypeScript) or only (just the embedded copy)
-lib-module stringmodule specifier a TypeScript parser imports its library from with -lib import, such as ../shared/lib.ts
-max-depth intgenerated default nested recursive rule-call limit (0 selects 100000)
-module stringimport path of the generated Go package
-no-limitsgenerate the ordinary form of the parser, without limit controls: it is smaller and faster, and a parse that passes a context or a finite Compute or Memory limit (signal and the compute limit in TypeScript) fails
-no-opt stringoptimizations to turn off after the profile is applied, separated by commas, for isolating a miscompilation or measuring one optimization; the optimizations, with kind and default: guards (pass, on), scans (pass, on), field-compare (lowering, on), text-dispatch (lowering, on), class-runs (flow pass, on), class-tables (flow pass, off; count), guarded-classes (flow pass, on), inline-literals (flow pass, 4; count), terminals (flow pass, on), ts-merged-records (exec pass, on), ts-spend-runs (exec pass, on), ts-tested-inits (exec pass, on), canonicalize (code pass, on), drop-after-exit (pattern, on), drop-unused-labels (pattern, on), fold-branches (pattern, on), fold-constants (pattern, on), splice-blocks (pattern, on), literal-sharing (printer, on), method-sharing (printer, on), ts-literal-sharing (printer, off), used-features (printer, on), sparse-memo (runtime, on), typed-list-slabs (runtime, on), typed-object-slabs (runtime, on), typed-output-bootstrap (runtime, on)
-nodocleave out the package comment (Go)
-o stringoutput directory
-observabilityemit opt-in rule tracing and profiling for Go batch/Documents and TypeScript batch parsing, including typed entry points
-opt stringoptimizations to give a value, separated by commas, as name or name=count: a name alone turns on an optimization that the profile leaves off, and 0 turns one off; applied after the profile and before -no-opt; the optimizations, with kind and default: guards (pass, on), scans (pass, on), field-compare (lowering, on), text-dispatch (lowering, on), class-runs (flow pass, on), class-tables (flow pass, off; count), guarded-classes (flow pass, on), inline-literals (flow pass, 4; count), terminals (flow pass, on), ts-merged-records (exec pass, on), ts-spend-runs (exec pass, on), ts-tested-inits (exec pass, on), canonicalize (code pass, on), drop-after-exit (pattern, on), drop-unused-labels (pattern, on), fold-branches (pattern, on), fold-constants (pattern, on), splice-blocks (pattern, on), literal-sharing (printer, on), method-sharing (printer, on), ts-literal-sharing (printer, off), used-features (printer, on), sparse-memo (runtime, on), typed-list-slabs (runtime, on), typed-object-slabs (runtime, on), typed-output-bootstrap (runtime, on)
-opt-bisect-limit intrun only the runs of optional passes, and the applications of their patterns, numbered up to n in pipeline order, skip the later ones and write each decision to standard error; the required steps always run, and the generator generates once
-optimize stringoptimization profile: speed (the fastest parse that does not cost generated code or memory out of proportion; the default); memory (typed values are allocated one by one: fewer bytes allocated and less live heap, with many more allocations); size (smaller generated Go source and binaries, for a little parse time); no profile changes what the parser returns
-pkg stringpackage name of the generated code (Go; default: the last element of -module without a major version suffix)
-print-after stringwrite the IR to standard error after the named steps and passes, separated by commas: elaborate and the Core passes print the Core IR of each table, flowlower, the Flow passes and flow-finish each function printed from Flow IR, execlower and the Exec passes each function printed from Exec IR; a pass that does not apply to the parser prints nothing: elaborate, guards, scans, plan, flowlower, terminals, guarded-classes, class-runs, class-tables, inline-literals, canonicalize, flow-finish, execlower, ts-spend-runs, ts-merged-records, ts-tested-inits, all
-print-before stringwrite the IR to standard error before the runs of the named passes, separated by commas, as -print-after writes it; the required steps are no passes to print before: guards, scans, plan, terminals, guarded-classes, class-runs, class-tables, inline-literals, canonicalize, ts-spend-runs, ts-merged-records, ts-tested-inits, all
-print-changedwrite the IR to standard error after each pass that changed it, and once before the first change of each unit what the pass received
-recognizealso generate Recognize, which checks input without building a tree
-recognize-onlygenerate only Recognize, without Parse, ParseRule or typed entry points (Go only; not with -types, -typed-only, -document or -stream)
-s stringstart rule of the generated Parse function (default: the grammar's default start rule)
-source-infomake the generated parser record the rule of each node and the names of captures
-statswrite to standard error, after the build, the statistics of each pass that ran: units it ran on, units it changed, its counters and the applications of its patterns
-streamalso generate Go ParseStream and Iterate for the start rule's #stream repetition (and their typed forms with -types; incompatible with -lang ts)
-time-passeswrite to standard error, after the build, the time of each pass and step that ran, summed over its units, with its share of the total
-typed-onlygenerate only the typed entry points (ParseValue and siblings), without Parse, ParseRule and Recognize (needs -types)
-typesalso generate typed values and ParseValue (parseValue in TypeScript)
-verify-eachverify the IR after every pass and step, so that an error names the first pass that broke it

sxir compile

sxir compile -g <grammar> [-s <rule>] [-mode parse|recognize|document] [-source-info] [-default-value] -o <file.sxirc>

Compile a grammar and save the bytecode of one mode. The result runs on the bytecode backends as the <grammar> of parse, trace, profile and explain, for the parses of its mode only: parse (the default) serves parse and parse -stream; recognize serves parse -recognize; document serves trace, profile and explain. The commands that need the grammar itself (convert, gen, lint, sample, schema) take the source. A compiled grammar given as <grammar> is saved again only in its own mode. With -source-info, its parses record the rule of each node and the names of captures. With -default-value, value actions and declared rule types are dropped (predicates still run), so its parses return the default node tree.

FlagDefaultDescription
-default-valuedrop value actions and declared rule types, so parses return the default node tree
-g stringgrammar file (.sxir, .json, or a .sxirc to save again in its own mode)
-mode string"parse"the parses the result serves: parse, recognize (parse -recognize) or document (Documents, trace, profile)
-o stringoutput file (.sxirc)
-s stringstart rule saved as the default (default: the one saved in a .sxirc, otherwise the grammar's default start rule)
-source-inforecord the rule of each node and the names of captures in parse results

sxir trace

sxir trace -g <grammar> [-s <rule>] [-i <input>] [-show-depth <n>] [-rule <name>]
     [-failures] [-f text|json] [-unit u] [-backend b] [-max-compute <n>] [-max-memory <n>] [-max-input <n>] [-max-depth <n>]

Parse the input and print every rule call as an indented call tree with positions, results and memo hits (-f json: one event per line). -show-depth hides calls nested deeper than n below the top call shown.

FlagDefaultDescription
-backend stringexecution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar)
-f string"text"output format: text (an indented call tree) or json (one event per line)
-failuresshow what was expected where each failed call failed
-g stringgrammar file (.sxir, .json, or .sxirc)
-i stringinput string (default: standard input)
-max-compute valuelimit on the cost of the parse: a number of units, 0 for the default of max(2^20, 1024 times the input length), or unlimited
-max-depth valuelimit on the nesting of recursive rule calls: a number, 0 for the backend's default (100000; 10000000 for bytecode-iterative), or unlimited (bytecode-iterative only)
-max-input valuelongest input accepted, in the position unit: a number, 0 or unlimited for no bound
-max-memory valuelimit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound
-rule valueshow only the calls of this rule and the calls nested in them (repeatable, or comma-separated)
-s stringstart rule name (default: the one saved in a .sxirc, otherwise the grammar's default start rule)
-show-depth intshow calls nested at most this deep, counting from the top call shown (1), which is the start rule or a call of a -rule rule; 0 shows all
-unit string"codepoints"unit of positions: codepoints or bytes

sxir profile

sxir profile -g <grammar> [-s <rule>] [-i <input>] [-sort <column>] [-n <rows>]
     [-f text|json] [-unit u] [-backend b] [-max-compute <n>] [-max-memory <n>] [-max-input <n>] [-max-depth <n>]

Parse the input and print the cost of each rule, with hints on where the grammar does more work than it needs to.

FlagDefaultDescription
-backend stringexecution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar)
-f string"text"output format: text or json
-g stringgrammar file (.sxir, .json, or .sxirc)
-i stringinput string (default: standard input)
-max-compute valuelimit on the cost of the parse: a number of units, 0 for the default of max(2^20, 1024 times the input length), or unlimited
-max-depth valuelimit on the nesting of recursive rule calls: a number, 0 for the backend's default (100000; 10000000 for bytecode-iterative), or unlimited (bytecode-iterative only)
-max-input valuelongest input accepted, in the position unit: a number, 0 or unlimited for no bound
-max-memory valuelimit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound
-n int30number of rules to show (0 shows all)
-s stringstart rule name (default: the one saved in a .sxirc, otherwise the grammar's default start rule)
-sort string"self"column to sort by: self, time, calls, evals, memo, failed, repeats, consumed, wasted, or name
-unit string"codepoints"unit of positions: codepoints or bytes

sxir explain

sxir explain -g <grammar> [-s <rule>] [-i <input>] [-n <calls>] [-unit u] [-backend b]
     [-max-compute <n>] [-max-memory <n>] [-max-input <n>] [-max-depth <n>]

Parse the input and, for a syntax error, print the rule calls that recorded what it says was expected, each with the calls it was nested in.

FlagDefaultDescription
-backend stringexecution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar)
-g stringgrammar file (.sxir, .json, or .sxirc)
-i stringinput string (default: standard input)
-max-compute valuelimit on the cost of the parse: a number of units, 0 for the default of max(2^20, 1024 times the input length), or unlimited
-max-depth valuelimit on the nesting of recursive rule calls: a number, 0 for the backend's default (100000; 10000000 for bytecode-iterative), or unlimited (bytecode-iterative only)
-max-input valuelongest input accepted, in the position unit: a number, 0 or unlimited for no bound
-max-memory valuelimit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound
-n int10most calls to show per error (0 shows all)
-s stringstart rule name (default: the one saved in a .sxirc, otherwise the grammar's default start rule)
-unit string"codepoints"unit of positions: codepoints or bytes

sxir lint

sxir lint -g <grammar> [-s <rule>] [-f text|json] [-disable <checks>] [-strict]

[-classify] [-list] Report likely mistakes in a grammar: alternatives and expressions that can never match or have no effect, unused captures and rules, and shapes that slow down incremental parsing. Fails if an error is found (with -strict, also a warning). -classify also classifies the cost of the grammar from the start rule and runs the super-linear check. -list lists the checks.

FlagDefaultDescription
-classifyclassify the cost of the grammar from the start rule and run the super-linear check
-disable valuecomma-separated checks not to run (the flag can be repeated)
-f string"text"output format: text or json
-g stringgrammar file (.sxir or .json)
-listlist the checks and exit
-s stringstart rule (default: the grammar's default start rule)
-strictfail on warnings too, not only on errors

sxir sample

sxir sample -g <grammar> [-s <rule>] [-n <count>] [-seed <n>] [-max-depth <d>]
     [-max-repeat <r>] [-max-len <bytes>] [-budget <steps>] [-coverage] [-invalid]
     [-f lines|json]

Generate distinct inputs that the grammar accepts, for tests and fuzz corpora, each printed as a quoted string on its own line. -coverage prefers rules and alternatives not exercised yet and reports what was missed; -invalid generates near-miss inputs that the grammar rejects.

FlagDefaultDescription
-budget int20000steps one attempt may take before it gives up
-coverageprefer rules and alternatives not exercised yet, and report the coverage
-f string"lines"output format: lines (one quoted input per line) or json
-g stringgrammar file (.sxir or .json)
-invalidgenerate near-miss inputs that the grammar rejects instead
-max-depth int5recursion depth beyond which the generator finishes the input the shortest way
-max-len int512soft limit on the length of an input in bytes
-max-repeat int3iterations beyond the minimum that a repetition aims for, at most
-n int10number of distinct inputs to generate
-s stringstart rule (default: the grammar's default start rule)
-seed uintseed of the random decisions; the same seed gives the same inputs

sxir schema

sxir schema -g <grammar> [-s <rule>] [-all-rules] [-o <file>]
sxir schema diff [-s <rule>] [-all-rules] [-f text|json] <before> <after>

Print the output schema of a grammar as JSON, without parsing an input. By default the schema holds the start rule and the rules it calls; -all-rules includes every rule and declared type. schema diff compares two schemas and prints the added, removed and changed types and rules. Each operand is a schema JSON file, as written by schema, or a grammar, whose schema is exported with -s and -all-rules. The exit status is 0 whenever both operands are valid, whether or not they differ.

FlagDefaultDescription
-all-rulesinclude unreachable rules and all declared types, not only those the start rule uses
-g stringgrammar file (.sxir or .json)
-o stringoutput file (default: standard output)
-s stringstart rule (default: the grammar's default start rule)

sxir edit-fuzz

sxir edit-fuzz -g <grammar.sxir> [-s <rule>] [-backend <names>] [-unit <names>] [-seed <n>]
     [-corpus <path>] [-sequences <n>] [-operations <n>] [-save-failures <dir>]
     [-minimize] [-max-attempts <n>] [-max-compute <n>] [-max-memory <n>] [-max-input <n>] [-max-depth <n>]
sxir edit-fuzz -g <grammar.sxir> -replay <sequence.json> [-minimize] [-save-failures <dir>]
     [-max-compute <n>] [-max-memory <n>] [-max-input <n>] [-max-depth <n>]

Apply generated edit, undo and redo sequences to incremental Documents and compare each checkpoint with a fresh parse, on every backend and unit unless limited. A failing sequence is saved as a JSON file that -replay runs exactly; -minimize also saves a shortened sequence that fails the same way. The limits apply to every Document and fresh parse; a saved sequence does not record them, so pass them again to -replay.

FlagDefaultDescription
-backend string"closure,bytecode,bytecode-iterative"comma-separated backends to fuzz
-corpus stringinitial texts: a file, or a directory whose files are read in name order (default: inputs generated from the grammar)
-g stringgrammar source file (.sxir); sequences record a hash of its exact bytes
-max-attempts int2000replays that -minimize tries at most
-max-compute valuelimit on the cost of the parse: a number of units, 0 for the default of max(2^20, 1024 times the input length), or unlimited
-max-depth valuelimit on the nesting of recursive rule calls: a number, 0 for the backend's default (100000; 10000000 for bytecode-iterative), or unlimited (bytecode-iterative only)
-max-input valuelongest input accepted, in the position unit: a number, 0 or unlimited for no bound
-max-memory valuelimit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound
-minimizeminimize a failing sequence and save the result too
-operations int32operations in each sequence
-replay stringreplay a saved sequence instead of generating sequences
-s stringstart rule (default: the grammar's default start rule)
-save-failures stringdirectory where a failing sequence is saved, required with -minimize (with -replay -minimize: default the replayed file's directory)
-seed uintseed of the generated sequences
-sequences int100sequences to run for each backend and unit
-unit string"codepoints,bytes"comma-separated position units to fuzz

sxir lsp

sxir lsp

Run a Language Server Protocol server for .sxir files on standard input and output, for editors: diagnostics, formatting, go to definition, references, hover, rename and completion.

FlagDefaultDescription
-stdiotruecommunicate over standard input and output (the only transport)