Consider an EBNF grammar, at least in docs

[gilch]

Some notes from a private chat with @brandonwillard who seems to think this would help with tooling.

Hebigo uses Python's expression syntax (but not statements), so that would have to be copied for a complete grammar. Note that Python expressions in Hebigo must be simple literals or "bracketed" somehow. Parentheses work for anything, but if it already has {}, [], or valid Python quotation marks, that's also enough. (Including things like f"", b"", etc.)

Hebigo translates very directly to Hissp tuples.

In Lisp, the head of the list is the function/macro, and the rest are arguments. The head is almost always a symbol.

In Hebigo, you make a "list" (tuple) with a hotword: a symbol ending in a colon, like foo:.
The hotword is the "head" of the "list". The expressions following that are the arguments. The layout determines where the "list" ends, much like Python.

I designed the layout rules to make Hebigo easy to edit with a minimal editor. Hotwords can be either unary or polyary. Unary has no whitespace after the colon and attaches directly to its single argument, like a tag. The hotword becomes the "head" of the tuple. A polyary tuple extends to the end of the line, or in the case of the first polyary hotword of the line, it also includes the indented block below it. (As a matter of style, simple function invocations would use either arguments on the same line as the hotword or in the block beneath it, but not both. Macros, on the other hand, may use both.)

There's also an "empty" hotword ::. It uses its first argument as its "head". You can use this to make an empty tuple, or a tuple that has a complex expression as its head (instead of a simple symbol.) You can also use :: stylistically in cases when the tuple is just grouping things and isn't an invocation where the head is special.

Unary hotwords fill in for tag macros and such. (There are no reader macros in Hebigo.) A common use would be quote:

There are a lot of examples in the tests. Any grammar would, at minimum, have to pass those tests. But I wasn't really testing the Python expression grammar there. Any grammar would pretty much have to be machine-checked before I'd trust it to be accurate. Lark is an option. But indented blocks aren't even context-free without some preprocessing. This doesn't look easy.

[brandonwillard]

I love the idea of having a concise abstract grammar available for a language!