Summary
I want to generate Markdown documentation/specifications for my DSL and JBeam languages directly from the Haskell parsers.
I already have working Megaparsec parsers for both jbfl and JBeam, and I’m considering writing code that introspects or parses the parser definitions themselves to extract a BNF-like AST. From that AST, I could automatically produce Markdown documentation (grammar specs, examples, etc).
Motivation
I don’t want to maintain language specifications manually.
Manual specs inevitably drift out of sync with the actual implementation — especially when experimenting with syntax, adding new features, or refactoring parsers.
Right now, the parser code is the source of truth for what the language actually is.
So the ideal workflow is:
- The parser defines the grammar.
- The documentation is generated from the parser.
- The spec is always up-to-date by construction.
Alternatives considered
-
Write BNF first and generate parsers from it
Possible, but I’d lose many of the benefits of Megaparsec — composability, type safety, and great error handling.
-
Maintain Markdown specs manually
Not sustainable, and quickly diverges from the implementation.
-
Generate Haddock documentation
Haddock is useful for API docs, but not ideal for describing grammars.
It still requires keeping comments in sync manually, and anyone reading the docs needs to understand Haddock’s structure.
So the “truth” still lives in two places: the parser code and the comments.
Goals
- Keep the Haskell parsers as the single source of truth.
- Automatically generate Markdown documentation/specs from them.
- Optionally visualize or export the grammar as BNF/EBNF.
Open questions
- How practical is it to introspect Megaparsec parser definitions automatically?
- Would
ghc-lib-parser be suitable for extracting structure?
- How to represent combinators and alternatives in a readable BNF-like form?
Current specs
Official JBeam spec: https://documentation.beamng.com/modding/vehicle/intro_jbeam/jbeamsyntax/
Current version of jbeam-edit jbfl DSL spec: https://github.com/webdevred/jbeam_edit/blob/master/JBFL_DOCS.md
Summary
I want to generate Markdown documentation/specifications for my DSL and JBeam languages directly from the Haskell parsers.
I already have working Megaparsec parsers for both jbfl and JBeam, and I’m considering writing code that introspects or parses the parser definitions themselves to extract a BNF-like AST. From that AST, I could automatically produce Markdown documentation (grammar specs, examples, etc).
Motivation
I don’t want to maintain language specifications manually.
Manual specs inevitably drift out of sync with the actual implementation — especially when experimenting with syntax, adding new features, or refactoring parsers.
Right now, the parser code is the source of truth for what the language actually is.
So the ideal workflow is:
Alternatives considered
Write BNF first and generate parsers from it
Possible, but I’d lose many of the benefits of Megaparsec — composability, type safety, and great error handling.
Maintain Markdown specs manually
Not sustainable, and quickly diverges from the implementation.
Generate Haddock documentation
Haddock is useful for API docs, but not ideal for describing grammars.
It still requires keeping comments in sync manually, and anyone reading the docs needs to understand Haddock’s structure.
So the “truth” still lives in two places: the parser code and the comments.
Goals
Open questions
ghc-lib-parserbe suitable for extracting structure?Current specs
Official JBeam spec: https://documentation.beamng.com/modding/vehicle/intro_jbeam/jbeamsyntax/
Current version of jbeam-edit jbfl DSL spec: https://github.com/webdevred/jbeam_edit/blob/master/JBFL_DOCS.md