Parse ABNF grammars

For more information on the flavor of ABNF
(Augmented Backus-Naur Form) supported by this project,
see RFC 5234
and RFC 7405.

Installation:

npm install -g abnf

Example:

import { parseFile } from "abnf";
const rules = await parseFile("myfile.abnf");

CLI

There are a few binaries included:

$3

Check the given ABNF file for correctness.

``txt
Usage: abnf_check [options] [abnfFile...]

Check ABNF files for syntax, unused rules, and undefined rules

Options:
-h, --help display help for command
`

$3

Output the generated abstract syntax tree for the ABNF input. This output is
mostly diagnostic in nature, not really meant to be parsed.

`txt
Usage: abnf_ast [options] [abnfFile...]

Output all of the rules derived from a given ABNF file

Options:
-l,--location don't remove location information
-h, --help display help for command
`

$3

Generate a Peggy or Pest grammar
from the ABNF. The idea is that you could then annotate this grammar with
actions in order to create a useful parser.

`txt
Usage: abnf_gen [options] [abnfFile...]

Create a grammar from an ABNF file

Arguments:
abnfFile ABNF files to turn into grammars.

Options:
-f, --format Output format (choices: "peggy", "pest", default:
"peggy")
-s, --startRule Start rule for generated grammar. Defaults to
first rule in ABNF grammar. Can be specified
multiple times.
--stubs Generate stubs for rules that do not exist, rather
than failing.
-o, --output Output grammar file name. Derived from input file
name if not specified. (default: "stdin.peggy")
-u, --unused Output rules that are not reachable from the start
rule
-c, --core Include core rules from RFC 5234, Appendix B.
-h, --help display help for command
`

$3

Using an ABNF, test inputs to see if they match. Returns the Peggy parse
tree, which will likely be somewhat confusing until you're familiar with Peggy.

`txt
Usage: abnf_test [options] [abnfFile...]

Send test inputs to an ABNF grammar

Arguments:
abnfFile The ABNF to test.

Options:
-o, --output Output grammar source, if not testing. Generated
from peggyFile name if needed.
-s, --startRule When testing, use this as the start rule.
-t, --test String to check against grammar.
-T, --testFile File contents to check against grammar.
--trace Turn on peggy tracing
-h, --help display help for command
`

Suggested Workflow

`sh
$ cat << EOF > foo.abnf
f = "abc"
EOF
$ abnf_gen foo.abnf
$ cat foo.peggy
f
= "abc"i
$ abnf_test foo.abnf -t abc
'abc'
$ abnf_test foo.peggy -t ab
Error: Expected "abc" but "a" found.
--> command line:1:1
|
1 | ab
| ^
`

API

$3

Parse the file with the given name, returning a promise for a Rules object.

$3

Parse the given string and return a Rules object. The grammarSource is
the name of the file that the input came from.

$3

Read the stream, parse it, and return a promise for a Rules object. The
grammarSource is the name of the file that the input came from.

$3

This is used by the abnf_check` utility, and returns null if there are no reference errors, otherwise returns an array of error strings. Checks for unused or undefined rules.

Returned Rules object shape

$3

The name of the first rule in the input grammar.

$3

A hash of Rule objects indexed by uppercase rulename.

$3

An array of RuleRef objects.

$3

The name of the rule

$3

The Peggy location in the input file where the rule name was defined

$3

The definition of the rule. More information forthcoming.

$3

The name of the rule that was referenced

$3

The Peggy location in the input file where the rule name was referenced.

---