https://github.com/estudio-hawara/choo-choo
Railroad-diagram library: manual construction plus pluggable grammar parsers.
https://github.com/estudio-hawara/choo-choo
bnf railroad-diagrams typescript
Last synced: about 2 months ago
JSON representation
Railroad-diagram library: manual construction plus pluggable grammar parsers.
- Host: GitHub
- URL: https://github.com/estudio-hawara/choo-choo
- Owner: estudio-hawara
- License: mit
- Created: 2026-04-18T10:14:18.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-18T12:38:54.000Z (about 2 months ago)
- Last Synced: 2026-04-18T13:06:04.041Z (about 2 months ago)
- Topics: bnf, railroad-diagrams, typescript
- Language: TypeScript
- Homepage: https://estudio-hawara.github.io/choo-choo/
- Size: 255 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: docs/roadmap/0.1.md
Awesome Lists containing this project
README
# choo-choo
A TypeScript library for railroad diagrams — built by hand or generated from grammars. Ships as a pure SVG renderer with pluggable parsers and first-class bindings for **React**, **Vue**, **Astro**, and **Vanilla JS**.
Docs:
## Quick start
End-to-end walkthrough from `pnpm init` to a diagram in a browser: **[docs/quickstart](./docs/quickstart/index.md)**.
The shortest API shape — vanilla binding with an EBNF grammar — looks like this:
```html
digit = ? 0-9 ?;
number = digit , { digit };
```
```ts
import "@choo-choo/vanilla";
import "@choo-choo/vanilla/styles.css";
import { ebnfParser } from "@choo-choo/parser-ebnf";
document.querySelector("choo-choo")!.parser = ebnfParser;
```
Equivalent components exist for React, Vue, and Astro — see each binding's README.
## Packages
| Package | Purpose |
|--------------------------------------------------------------------------------|-----------------------------------------------------------|
| [`@choo-choo/core`](./packages/core) | IR, manual builder, and SVG renderer. Zero runtime deps. |
| [`@choo-choo/parser-utils`](./packages/parser-utils) | Shared reader / tokenizer primitives for grammar parsers. |
| [`@choo-choo/parser-ebnf`](./packages/parser-ebnf) | ISO/IEC 14977 EBNF parser. |
| [`@choo-choo/parser-antlr`](./packages/parser-antlr) | ANTLR4 grammar parser. |
| [`@choo-choo/parser-peg`](./packages/parser-peg) | PEG (peggy / PEG.js dialect) parser. |
| [`@choo-choo/vanilla`](./packages/vanilla) | `` custom element + imperative `mount()`. |
| [`@choo-choo/react`](./packages/react) | React `` component, SSR-safe. |
| [`@choo-choo/vue`](./packages/vue) | Vue 3 `` component, SSR-safe. |
| [`@choo-choo/astro`](./packages/astro) | Astro `` component, SSR-only. |
## Repository map
- [`docs/quickstart/`](./docs/quickstart/index.md) — from `pnpm init` to a diagram in a browser.
- [`docs/architecture.md`](./docs/architecture.md) — target architecture and module boundaries.
- [`docs/development.md`](./docs/development.md) — development workflow and tooling.
- [`docs/contributing.md`](./docs/contributing.md) — how to contribute.
- [`docs/releasing.md`](./docs/releasing.md) — versioning policy and publish flow.
- [`docs/roadmap/`](./docs/roadmap/) — milestones for each release.
## Inspiration
### Railroad Diagrams
> [!NOTE]
> This project is an evolution of [Railroad Diagrams](https://github.com/tabatkins/railroad-diagrams) by [@tabatkins](https://github.com/tabatkins/), with the addition of the (E)BNF parsers that simplify the construction of the diagrams when you already have a defined grammar.
### Parser from Scratch
> [!NOTE]
> I started writing this library while studying the [Parser from scratch](http://dmitrysoshnikov.com/courses/parser-from-scratch/) course from [@dmitrysoshnikov](https://github.com/dmitrysoshnikov/), so you may find several similarities with his approach to recursive descent parser. Following his courses will definitely help you understanding this codebase.
## License
[MIT](./LICENSE) © [Estudio Hawara](https://hawara.es).