CLI Reference

go install github.com/ornew/pego/cmd/pego@latest

#Overview

Command pego is a command-line tool for working with PEGO grammars.

Usage:

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

#Usage

pego <command> [flags] [arguments]

A <grammar> is PEGO source (.pego), a grammar in JSON (.json), or, for parse, trace, profile, explain and compile, a grammar compiled with pego compile (.pegoc).

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

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

#Commands

#pego parse

pego parse -g <grammar> [-s <rule>] [-i <input>] [-f json|sexpr] [-stream] [-check]
     [-unit codepoints|bytes] [-backend closure|bytecode|bytecode-iterative] [-source-info]
     [-default-value]

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.

#pego test

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

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.

#pego fmt

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

Format PEGO 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.

#pego fix

pego fix [-w] [-l] [<file.pego> ...]

Rewrite PEGO source written in earlier syntax to the current syntax, changing only the rewritten tokens. Without files, standard input is rewritten. -w rewrites the files in place; -l lists the files that need rewriting.

#pego convert

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

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

#pego gen

pego gen -g <grammar> -module <import path> -o <dir> [-pkg <package>] [-runtime embed|import|only] [-s <rule>] [-types]
     [-document] [-stream] [-recognize] [-observability] [-work-controls] [-typed-only] [-max-depth <n>] [-nodoc] [-source-info] [-default-value]
pego gen -runtime only -o <dir>
pego gen -lang ts -g <grammar> -o <dir> [-runtime embed|import|only] [-runtime-module <specifier>] [-s <rule>] [-types]
     [-recognize] [-observability] [-max-depth <n>] [-source-info] [-default-value]
pego gen -lang ts -runtime 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 -runtime embed (the default), a copy of the runtime in internal/runtime, 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. -runtime import makes the parser import github.com/ornew/pego/runtime instead, and needs only -pkg or -module. -runtime only writes just internal/runtime, 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 pego" 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 -runtime embed (the default), runtime.ts, a copy of the runtime that does not depend on the grammar, all written to -o. -runtime import leaves runtime.ts out and imports the runtime from the module -runtime-module (required), such as ../shared/runtime.ts; -runtime only writes just runtime.ts, to share it or to refresh the copy. With -types, types for the grammar's types and ParseAST (parseAST in TypeScript), which returns the result as typed values, are generated too. -document adds a Go incremental Document; with -types it also provides Document.ParseAST. Without -work-controls the Document runs without work charges. It cannot be combined with -lang ts. -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. -work-controls generates the work-controlled form of the parser, which supports WithContext and WithWorkLimits (signal, maxInputWork and maxSteps in TypeScript); without it those options are not exported, the generated code does not charge work, and a parse that passes them fails. The parser has this one form only: a parse that sets no limit runs the same code. Generate a second parser without the option to have the plain form too. -typed-only generates only the typed entry points (ParseAST and its siblings), without Parse, ParseRule and Recognize. It needs -types and cannot be combined with -recognize, -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 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.

#pego compile

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

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 -check; 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.

#pego trace

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

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).

#pego profile

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

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

#pego explain

pego explain -g <grammar> [-s <rule>] [-i <input>] [-n <calls>] [-unit u] [-backend b]

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.

#pego lint

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

[-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). -list lists the checks.

#pego sample

pego 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.

#pego schema

pego schema -g <grammar> [-s <rule>] [-all-rules] [-o <file>]
pego 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.

#pego edit-fuzz

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

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.

#pego lsp

pego lsp

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