parser-lang 1.0.0

Recursive-descent + Pratt parser infrastructure with error recovery.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# parser-lang v1.0.0 — API freeze

**Stable.** v1.0.0 freezes the public API. The cursor and Pratt engine built in
0.2.0 are now under a Semantic Versioning promise: no breaking change before `2.0`,
additions only in minor releases, MSRV (Rust 1.85) rising only in a minor. There
are no functional API changes from `0.2.0`; this release is the commitment.

## What is parser-lang?

The parsing toolkit of the `-lang` family: a token cursor a recursive-descent
grammar threads, a Pratt precedence engine for expressions, and error recovery that
emits source-annotated diagnostics. It owns no grammar and no AST — the grammar's
own functions build whatever output they like — so one toolkit serves every
language. It consumes [`token-lang`] tokens and reports [`diag-lang`] diagnostics.

## The frozen surface

- **`Parser<'t, K>`** — the cursor: `peek` / `bump` / `eat` / `expect`, error
  reporting and `recover`, `repeated` / `separated`, `checkpoint` / `rewind`, and
  the collected-diagnostics accessors. Trivia is skipped automatically; kinds are
  matched by predicate.
- **`Checkpoint`** — an opaque snapshot for speculative parsing.
- **`Pratt`** — a precedence-climbing trait (`prefix` / `infix_binding` / `infix`)
  with a provided `expression` / `parse` driver.
- **Re-exports** — `Token`, `TokenKind`, `Span` (token-lang) and `Diagnostic`
  (diag-lang).

The full reference, the SemVer promise, and what is deliberately left out (an
`ast-lang` dependency, a combinator layer, a depth guard — all addable later) are
in [`docs/API.md`](https://github.com/jamesgober/parser-lang/blob/main/docs/API.md).

## Guarantees

- **Total cursor.** Navigation never panics and never reads past the end, on any
  token slice — empty, unterminated, or hostile. Held by a property test over
  arbitrary streams.
- **Correct precedence.** The Pratt engine groups operators exactly as an
  independent shunting-yard oracle does, for every random operator sequence —
  precedence and associativity both.
- **Recovery makes progress.** `recover`, `repeated`, and `separated` cannot loop
  without consuming input; errors are collected so one run reports many.
- **Speculation rolls back cleanly.** A `rewind` restores the cursor and drops any
  diagnostics recorded since the checkpoint.
- **`no_std`** with `alloc`; `#![forbid(unsafe_code)]`; no `unwrap`/`expect`/`todo!`
  in shipping code.

## Breaking changes

**None.** Identical API to `0.2.0`. From here, breaking changes require `2.0`.

## Verification

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --no-default-features -- -D warnings
cargo test
cargo test --all-features
cargo build --no-default-features
cargo +1.85 build --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo audit
cargo deny check
```

All green. Counts: 12 unit + 9 calculator + 2 property + 13 doctests.

## Installation

```toml
[dependencies]
parser-lang = "1"
```

MSRV: Rust 1.85.

---

**Full diff:** [`v0.2.0...v1.0.0`](https://github.com/jamesgober/parser-lang/compare/v0.2.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/parser-lang/blob/main/CHANGELOG.md#100---2026-06-28).