Written a docopt grammar, interested ?

[philip-h-dye]

Not seeing any references to an actual docopt formal grammar yet, I am writing a PEG grammar for use in Python with Tatsu (https://tatsu.readthedocs.io). I am hopeful that it will be usable with other PEG parser generators but am not well enough versed in the area to know by how much they differ in syntax.

I would like to work with others interested in developing a formal grammar for docopt. I'm not fixed on Tatsu or even PEG though I suspect PEG grammars will provide more accurate results for the corner cases.

I appended a sketch of the steps I believe necessary to develop the grammar. I've written a grammar for the usage examples section. Now I need to take a step back and write the frame work to snag each major section. Divide and conquer seemed like the best approach. In a day or so, I could post the grammar and test cases to github.

So, any information in this area or would anyone like to collaborate ?

Philip

---

Unix Utility Usage Grammar

Or, a formal grammar for the docopy language.

First identify which elements must be parsed and which (if any) may be discarded (or perhaps remain free form text).

Characterize the delineations of each section sufficiently to write regular expression matchers for their start and end, or span.

Write a grammar to parse to just the sections out as blocks of free form text. This forms the framework within which the section parsers will operate.

For each section independently write a grammar to parse the it.

One by one, incorporate the section parsers into the framework.

[philip-h-dye]

docopt-parser includes PEG grammar for the docopt language completed and working with Arpeggio's clean peg parser.

The grammar is docopt.peg. The python test code is parser.py.

[itdaniher]

Oohh Exciting! This was a big dream of mine when I was working with the codebase last, thanks!

[itdaniher]

This is so cool! I am extremely into this train of thought, the current parser is a nightmare - adding type hints and my 2019ish refactoring was an effort at adding sanity to a fundamentally insane-ish design. It's better than it was, but deserves more love - and a PEG sounds like just the thing.

[blaisep]

Hi @philip-h-dye , @itdaniher , I have a bit of time since I'm currently "available for employment" and new to jazzband. Is this issue stalled at some stage? What is missing for it to move forward? Is it a matter of including the grammar files from docopt-parser into a PR? RTFMs gratefully accepted....

[NickCrews]

@blaisep this is really late, but perhaps you or someone else still is motivated. I would totally merge this if it comes together fairly cleanly. I took a look at docopt-parser and it looks like it is a bit messy, so it won't be a simple matter of just copying stuff over.

I think steps would be:

• create a new branch
• add the .peg grammar files
• add scripts/whatever to make it easy/reproducible to generate the .py parser from the .peg files. The generated parser should also be checked into git. It will need to stay in sync with the grammar files.
• modify the existing docopt/__init__.py to use this generated parser instead of the custom parsing logic in there now.
• ensure all existing tests pass. Maybe add some more tests if you think you are finding a new edge case.
• submit a PR for this branch

I think you're going to have to be mostly self-directed for those stages, I can provide some help but don't really want to sink a ton of time into it.

[NickCrews]

See EBNF grammar from docopts port: https://github.com/docopt/docopts/wiki/Home/443b839150f8aec2fc581f5a7a70b8bb7648d5c2