The pego Command

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]
pego fmt [-w] [-l] [grammar.pego ...]
pego convert [-to pego|json] [-o output] grammar.pego|grammar.json|grammar.pegoc
pego gen -g grammar.pego -pkg name [-s main] [-o parser.go] [-types] [-recognize] [-nodoc]
pego gen -lang ts -g grammar.pego [-s main] [-o parser.ts] [-recognize]
pego compile -g grammar.pego [-s main] [-no-ast] -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 lsp

Usage

pego <command> [flags] [arguments]

A <grammar> is PEGO source (.pego), a grammar in JSON (.json), or 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]

Parse the input with a grammar and print the syntax tree. Without -i, the input is read from standard input.

Flag	Default	Description
`-backend string`		execution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar)
`-check`		only check that the input matches the grammar, without building a tree, and print ok if it does
`-f string`	`"json"`	output format: json or sexpr
`-g string`		grammar file (.pego, .json, or .pegoc)
`-i string`		input string (default: standard input)
`-s string`		start rule name (default: the one saved in a .pegoc, otherwise main)
`-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

pego fmt

pego fmt [-w] [-l] [<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.

Flag	Default	Description
`-l`		list the files whose formatting differs
`-w`		write the result to the file instead of standard output

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 and is required for compiled grammars.

Flag	Default	Description
`-o string`		output file (default: standard output)
`-to string`		output format, pego or json (default: the other format of the input)

pego gen

pego gen -g <grammar> -pkg <package> [-s <rule>] [-o <file>] [-types] [-recognize]
     [-nodoc]
pego gen -lang ts -g <grammar> [-s <rule>] [-o <file>] [-recognize]

Generate a Go parser (or, with -lang ts, a TypeScript module) from a grammar. Without -o, the code is written to standard output. With -types, Go types for the grammar's types and ParseAST, which returns the result as values of those types, are generated too (Go only); with -recognize, Recognize (recognize in TypeScript), which checks input without building a tree. -nodoc leaves out the package comment of the Go code, for a package documented in another file.

Flag	Default	Description
`-g string`		grammar file (.pego, .json, or .pegoc)
`-lang string`	`"go"`	language of the generated code: go or ts (TypeScript)
`-nodoc`		leave out the package comment (Go)
`-o string`		output file (default: standard output)
`-pkg string`		package name of the generated code (Go)
`-recognize`		also generate Recognize, which checks input without building a tree
`-s string`		start rule of the generated Parse function (default: the one saved in a .pegoc, otherwise main)
`-types`		also generate Go types for the grammar's types and ParseAST (Go)

pego compile

pego compile -g <grammar> [-s <rule>] [-no-ast] -o <file.pegoc>

Compile a grammar and save it. The result can be used as <grammar> by the other commands. With -no-ast, the grammar AST is omitted; the result then runs only on the bytecode backends and cannot be converted back to a grammar.

Flag	Default	Description
`-g string`		grammar file (.pego, .json, or .pegoc)
`-no-ast`		omit the grammar AST (the result runs only on the bytecode backends)
`-o string`		output file (.pegoc)
`-s string`		start rule saved as the default (default: the one saved in a .pegoc, otherwise main)

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

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 (.pego, .json, or .pegoc)
`-i string`		input string (default: standard input)
`-max-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
`-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 .pegoc, otherwise main)
`-unit string`	`"codepoints"`	unit of positions: codepoints or bytes

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.

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 (.pego, .json, or .pegoc)
`-i string`		input string (default: standard input)
`-n int`	`30`	number of rules to show (0 shows all)
`-s string`		start rule name (default: the one saved in a .pegoc, otherwise main)
`-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

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.

Flag	Default	Description
`-backend string`		execution backend: closure, bytecode, or bytecode-iterative (default: chosen for the grammar)
`-g string`		grammar file (.pego, .json, or .pegoc)
`-i string`		input string (default: standard input)
`-n int`	`10`	most calls to show per error (0 shows all)
`-s string`		start rule name (default: the one saved in a .pegoc, otherwise main)
`-unit string`	`"codepoints"`	unit of positions: codepoints or bytes

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.

Flag	Default	Description
`-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 (.pego, .json, or .pegoc with the AST)
`-list`		list the checks and exit
`-s string`		start rule (default: the one saved in a .pegoc, otherwise main)
`-strict`		fail on warnings too, not only on errors

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.

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 (.pego, .json, or .pegoc with the AST)
`-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 one saved in a .pegoc, otherwise main)
`-seed uint`		seed of the random decisions; the same seed gives the same inputs

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.

Flag	Default	Description
`-stdio`	`true`	communicate over standard input and output (the only transport)

The pego Command

#Overview

#Usage

#Commands

#pego parse

#pego fmt

#pego convert

#pego gen

#pego compile

#pego trace

#pego profile

#pego explain

#pego lint

#pego sample

#pego lsp