# gbnf
> A library for parsing GBNF grammars
Latest version **0.1.41** (published 2025-01-07) · MIT license · 0 weekly downloads
## Install
```sh
npm install gbnf
pnpm add gbnf
yarn add gbnf
bun add gbnf
```
## Health
**Score 45/100 (D)** — status: stable.
Positive: esm support; no vulnerabilities; has provenance.
Warnings: low downloads; no types; pre 1.0.
Negative: stale.
## Facts
| | |
|---|---|
| Version | 0.1.41 |
| Published | 2025-01-07 |
| First published | 2024-09-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 263 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Author | Ambient Labs |
| Maintainers | ambient-labs |
| Keywords | gbnf, grammar, grammar-parser |
## Links
- npm: https://www.npmjs.com/package/gbnf
- Repository: https://github.com/ambient-labs/GBNF
- Homepage: https://github.com/ambient-labs/GBNF#readme
- Issues: https://github.com/ambient-labs/GBNF/issues
- npm.io page: https://npm.io/package/gbnf
## Recent versions
- 0.1.41 (latest) — 2025-01-07
- 0.1.40 — 2025-01-05
- 0.1.39 — 2025-01-05
- 0.1.38 — 2025-01-02
- 0.1.37 — 2024-11-24
- 0.1.36 — 2024-10-09
- 0.1.35 — 2024-10-09
- 0.1.34 — 2024-10-09
- 0.1.33 — 2024-10-09
- 0.1.32 — 2024-10-09
- 0.1.31 — 2024-10-09
- 0.1.30 — 2024-10-09
- 0.1.29 — 2024-10-09
- 0.1.28 — 2024-10-08
- 0.1.27 — 2024-10-08
- … 8 more at https://npm.io/package/gbnf/versions
## README
# GBNF
A library for parsing `.gbnf` grammar files in Javascript.
## Install
```bash
npm install gbnf
```
## Usage
Pass your grammar to `GBNF`:
```javascript
import GBNF from 'gbnf';
const state = GBNF(`
root ::= "yes" | "no"
`)
```
If the grammar is invalid, `GBNF` will throw.
`GBNF` returns a state representing the parsed state:
```javascript
import GBNF from 'gbnf';
const state = GBNF(`
root ::= "yes" | "no"
`)
for (const rule of state) {
console.log(rule);
// { type: "CHAR", value: ["y".charCodeAt(0)]}
// { type: "CHAR", value: ["n".charCodeAt(0)]}
}
```
`state` can be iterated over. (You can also call the iterator method directly with `state.rules()`). `state` cannot be indexed directly, but can easily be cast to an array with `[...state]` and indexed that way.
States are _immutable_. To parse a new token, call `state.add()`:
```javascript
import GBNF from 'gbnf';
let state = GBNF(`
root ::= "I like green eggs and ham"
`)
console.log([...state]); // [{ type: "CHAR", value: ["I".charCodeAt(0)]}]
state = state.add("I li");
console.log([...state]); // [{ type: "CHAR", value: ["k".charCodeAt(0)]}]
state = state.add("ke gree");
console.log([...state]); // [{ type: "CHAR", value: ["n".charCodeAt(0)]}]
```
The possible rules returned include:
- `CHAR` - contains an array of either numbers representing code points to match, _or_ an array of two numbers denoting a range within which a code point may appear.
- `CHAR_EXCLUDED` - contains an array of numbers representing code points _not_ to match, _or_ an array of two numbers denoting a range within which a code point may _not_ appear.
- `END` - denotes a valid end of a string.
---
_Source: https://npm.io/package/gbnf · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._