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.
| Flag | Default | Description |
|---|---|---|
-backend string | execution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar) | |
-default-value | drop value actions and declared rule types, and print the default node tree (predicates still run) | |
-f string | "json" | output format: json or sexpr |
-g string | grammar file (.sxir, .json, or .sxirc) | |
-i string | input string (default: standard input) | |
-max-compute value | limit 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 value | limit 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 value | longest input accepted, in the position unit: a number, 0 or unlimited for no bound | |
-max-memory value | limit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound | |
-recognize | check the syntax of the input without building a tree, and print ok if it matches the grammar | |
-s string | start rule name (default: the one saved in a .sxirc, otherwise the grammar's default start rule) | |
-source-info | record the rule of each node and the names of captures, and print them | |
-stream | print 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.
| Flag | Default | Description |
|---|---|---|
-backend string | comma-separated execution backends (default: those in the suite) | |
-equivalence | compare selected backends independently of fixture expectations | |
-f string | fixture suite JSON file | |
-format string | "text" | report format: text or json |
-max-compute value | limit 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 value | limit 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 value | longest input accepted, in the position unit: a number, 0 or unlimited for no bound | |
-max-memory value | limit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound | |
-update | update 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.
| Flag | Default | Description |
|---|---|---|
-check | list the files whose formatting differs and exit with status 1 if there are any, or 2 if a file cannot be formatted | |
-l | list the files whose formatting differs | |
-syntax | print a simplified grammar syntax view (cannot combine with -w, -l or -check) | |
-w | write 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.
| Flag | Default | Description |
|---|---|---|
-o string | output file (default: standard output) | |
-to string | output 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.
| Flag | Default | Description |
|---|---|---|
-charge-units string | ||
-default-value | make the generated parser drop value actions and declared rule types and return the default node tree (incompatible with -types) | |
-document | also generate an incremental Document (typed ParseValue with -types) | |
-expectations | generate 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 string | grammar 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 string | module specifier a TypeScript parser imports its library from with -lib import, such as ../shared/lib.ts | |
-max-depth int | generated default nested recursive rule-call limit (0 selects 100000) | |
-module string | import path of the generated Go package | |
-no-limits | generate 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 string | optimizations 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) | |
-nodoc | leave out the package comment (Go) | |
-o string | output directory | |
-observability | emit opt-in rule tracing and profiling for Go batch/Documents and TypeScript batch parsing, including typed entry points | |
-opt string | optimizations 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 int | run 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 string | optimization 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 string | package name of the generated code (Go; default: the last element of -module without a major version suffix) | |
-print-after string | write 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 string | write 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-changed | write the IR to standard error after each pass that changed it, and once before the first change of each unit what the pass received | |
-recognize | also generate Recognize, which checks input without building a tree | |
-recognize-only | generate only Recognize, without Parse, ParseRule or typed entry points (Go only; not with -types, -typed-only, -document or -stream) | |
-s string | start rule of the generated Parse function (default: the grammar's default start rule) | |
-source-info | make the generated parser record the rule of each node and the names of captures | |
-stats | write 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 | |
-stream | also generate Go ParseStream and Iterate for the start rule's #stream repetition (and their typed forms with -types; incompatible with -lang ts) | |
-time-passes | write 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-only | generate only the typed entry points (ParseValue and siblings), without Parse, ParseRule and Recognize (needs -types) | |
-types | also generate typed values and ParseValue (parseValue in TypeScript) | |
-verify-each | verify 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.
| Flag | Default | Description |
|---|---|---|
-default-value | drop value actions and declared rule types, so parses return the default node tree | |
-g string | grammar 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 string | output file (.sxirc) | |
-s string | start rule saved as the default (default: the one saved in a .sxirc, otherwise the grammar's default start rule) | |
-source-info | record 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.
| Flag | Default | Description |
|---|---|---|
-backend string | execution 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) |
-failures | show what was expected where each failed call failed | |
-g string | grammar file (.sxir, .json, or .sxirc) | |
-i string | input string (default: standard input) | |
-max-compute value | limit 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 value | limit 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 value | longest input accepted, in the position unit: a number, 0 or unlimited for no bound | |
-max-memory value | limit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound | |
-rule value | show only the calls of this rule and the calls nested in them (repeatable, or comma-separated) | |
-s string | start rule name (default: the one saved in a .sxirc, otherwise the grammar's default start rule) | |
-show-depth int | show 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.
| Flag | Default | Description |
|---|---|---|
-backend string | execution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar) | |
-f string | "text" | output format: text or json |
-g string | grammar file (.sxir, .json, or .sxirc) | |
-i string | input string (default: standard input) | |
-max-compute value | limit 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 value | limit 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 value | longest input accepted, in the position unit: a number, 0 or unlimited for no bound | |
-max-memory value | limit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound | |
-n int | 30 | number of rules to show (0 shows all) |
-s string | start 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.
| Flag | Default | Description |
|---|---|---|
-backend string | execution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar) | |
-g string | grammar file (.sxir, .json, or .sxirc) | |
-i string | input string (default: standard input) | |
-max-compute value | limit 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 value | limit 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 value | longest input accepted, in the position unit: a number, 0 or unlimited for no bound | |
-max-memory value | limit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound | |
-n int | 10 | most calls to show per error (0 shows all) |
-s string | start 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.
| Flag | Default | Description |
|---|---|---|
-classify | classify the cost of the grammar from the start rule and run the super-linear check | |
-disable value | comma-separated checks not to run (the flag can be repeated) | |
-f string | "text" | output format: text or json |
-g string | grammar file (.sxir or .json) | |
-list | list the checks and exit | |
-s string | start rule (default: the grammar's default start rule) | |
-strict | fail 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.
| Flag | Default | Description |
|---|---|---|
-budget int | 20000 | steps one attempt may take before it gives up |
-coverage | prefer rules and alternatives not exercised yet, and report the coverage | |
-f string | "lines" | output format: lines (one quoted input per line) or json |
-g string | grammar file (.sxir or .json) | |
-invalid | generate near-miss inputs that the grammar rejects instead | |
-max-depth int | 5 | recursion depth beyond which the generator finishes the input the shortest way |
-max-len int | 512 | soft limit on the length of an input in bytes |
-max-repeat int | 3 | iterations beyond the minimum that a repetition aims for, at most |
-n int | 10 | number of distinct inputs to generate |
-s string | start rule (default: the grammar's default start rule) | |
-seed uint | seed 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.
| Flag | Default | Description |
|---|---|---|
-all-rules | include unreachable rules and all declared types, not only those the start rule uses | |
-g string | grammar file (.sxir or .json) | |
-o string | output file (default: standard output) | |
-s string | start 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.
| Flag | Default | Description |
|---|---|---|
-backend string | "closure,bytecode,bytecode-iterative" | comma-separated backends to fuzz |
-corpus string | initial texts: a file, or a directory whose files are read in name order (default: inputs generated from the grammar) | |
-g string | grammar source file (.sxir); sequences record a hash of its exact bytes | |
-max-attempts int | 2000 | replays that -minimize tries at most |
-max-compute value | limit 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 value | limit 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 value | longest input accepted, in the position unit: a number, 0 or unlimited for no bound | |
-max-memory value | limit on the bytes of storage the parser holds for the parse: a number, 0 or unlimited for no bound | |
-minimize | minimize a failing sequence and save the result too | |
-operations int | 32 | operations in each sequence |
-replay string | replay a saved sequence instead of generating sequences | |
-s string | start rule (default: the grammar's default start rule) | |
-save-failures string | directory where a failing sequence is saved, required with -minimize (with -replay -minimize: default the replayed file's directory) | |
-seed uint | seed of the generated sequences | |
-sequences int | 100 | sequences 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.
| Flag | Default | Description |
|---|---|---|
-stdio | true | communicate over standard input and output (the only transport) |