ebnsf 0.1.2

A CLI to generate railroad (syntax) diagrams from EBNF specs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

# EBNSF
> Extended Backus-Naur Syntax FDiagrams

Create railroad diagrams from EBNF

## Usage
```
Usage: ebnsf [OPTIONS] <INPUT>

Arguments:
  <INPUT>  File to read EBNF spec from

Options:
  -o, --output <OUTPUT>  Where to save the rendered SVG
  -h, --help             Print help
```

## Example
Run `ebnsf ./test/bnf.ebnf -o ./doc/bnf.svg` to turn

```ebnf
<syntax>         ::= <rule>+
<rule>           ::= <opt_whitespace> "<" <rule_name> ">" <opt_whitespace> "::=" <opt_whitespace> <group> <line_end>
<opt_whitespace> ::= " "*
<expression>     ::= <list> (<opt_whitespace> "|" <opt_whitespace> <expression>)?
<group>          ::= "(" <expression> ")" | <expression>
<line_end>       ::= <opt_whitespace> "\n"+
<list>           ::= <term> | <term> <opt_whitespace> <list>
<term>           ::= <literal> | "<" <rule_name> ">"
<literal>        ::= '"' <text> '"'
<text>           ::= <character>+
<character>      ::= <letter> | <digit>
<letter>         ::= "[A-Za-z]"
<digit>          ::= "[0-9]"
<rule_name>      ::= <letter> <rule_char>*
<rule_char>      ::= <letter> | <digit> | "_"
```
into
![bnf syntax diagram](https://github.com/user-attachments/assets/6efcc0dd-3734-41c6-a08d-facec4b3bd7d)
## Todo
- [x] support repitition specifiers and ranges (i.e. [a-z], +, *)
    - `?`, `+`, and `*` now supported
    - ranges can be specified by cheating and treating them as literals, e.g. "[a-z]".
      first-class support for ranges without wrapping them in quotes will be added later
      (but they probably won't be validated).
- [x] support grouping
    - grouping now supported (with repitition modifiers) using parenthesis
- [ ] support rules spanning multiple lines
- [ ] decide on the full syntax I want to use/support for EBNF.
    See dwheeler.com, grammarware.net, w3.org, and cl.cam.ac.uk links below.
- [ ] figure out if/how I want to handle bounded repitition
- [ ] figure out if/how I want to handle negation
- [x] support escape characters
    - supports escaping nested quotes and backslashes
- [ ] decide what comment syntax to use

## Credit
- Initial parser and `grammars/bnf.ebnf` file based on from BNF specification in EBNF form from https://bnfplayground.pauliankline.com/ > Examples > BNF
- `grammars/semver.ebnf` from https://semver.org/spec/v2.0.0.html#backusnaur-form-grammar-for-valid-semver-versions

Additional reading on EBNF syntax:

- https://www.cl.cam.ac.uk/~mgk25/iso-14977.pdf
- https://dwheeler.com/essays/dont-use-iso-14977-ebnf.html
- https://www.grammarware.net/text/2012/bnf-was-here.pdf
- https://www.w3.org/TR/xml/#sec-notation