If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rust-bakery/nom shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 8mo ago
• 56+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 8mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rust-bakery/nom repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rust-bakery/nom.

What it runs against: a local clone of rust-bakery/nom — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rust-bakery/nom | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 284 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rust-bakery/nom. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rust-bakery/nom.git
#   cd nom
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rust-bakery/nom and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rust-bakery/nom(\\.git)?\\b" \\
  && ok "origin remote is rust-bakery/nom" \\
  || miss "origin remote is not rust-bakery/nom (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/traits.rs" \\
  && ok "src/traits.rs" \\
  || miss "missing critical file: src/traits.rs"
test -f "src/combinator/mod.rs" \\
  && ok "src/combinator/mod.rs" \\
  || miss "missing critical file: src/combinator/mod.rs"
test -f "src/bytes/mod.rs" \\
  && ok "src/bytes/mod.rs" \\
  || miss "missing critical file: src/bytes/mod.rs"
test -f "src/sequence/mod.rs" \\
  && ok "src/sequence/mod.rs" \\
  || miss "missing critical file: src/sequence/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 284 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~254d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rust-bakery/nom"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

nom is a Rust parser combinator library that builds safe, zero-copy parsers by composing small functions into larger ones. It handles binary formats (MP4, images), text formats (JSON, INI, HTTP), and programming languages without requiring macros for basic parsing, using Rust's type system and memory safety to eliminate runtime errors while maintaining speed. Monorepo structure: src/bytes/, src/branch/, src/sequence/, src/combinator/ contain the core parser combinators organized by category; src/error/ handles error types; benchmarks/ has real-world parser examples (JSON, HTTP, INI); examples/ has standalone runnable parsers; tests/ contains comprehensive test suites; doc/ holds upgrade guides and tutorials.

Rust developers building parsers for binary protocols, configuration files, network protocols, or domain-specific languages who need both safety guarantees and performance without hand-writing state machines or using heavyweight parser generators.

Production-ready and actively maintained. The project is at version 8.0.0 with comprehensive test coverage (test/ directory with 15+ test suites), multiple CI workflows (ci.yml, cifuzz.yml, codspeed.yml), detailed documentation in doc/, and working examples. This is a stable, widely-adopted library in the Rust ecosystem.

Low risk. The dependency surface is minimal (only memchr v2.3 at runtime, plus doc-comment and proptest for dev). The MSRV is pinned to Rust 1.65.0 for stability. No signs of abandonment—the project has structured CI/CD, detailed CONTRIBUTING.md, and organized issue templates. Single-maintainer-like activity, but well-documented conventions in CODEOWNERS.

The project recently released v8.0.0 (current in Cargo.toml). Active CI/CD with coverage monitoring (coveralls integration) and continuous benchmarking (codspeed.yml). The CHANGELOG.md and doc/upgrading_to_nom_5.md suggest ongoing feature development. Fuzz testing infrastructure (fuzz/.gitignore) indicates active hardening.

git clone https://github.com/rust-bakery/nom.git
cd nom
cargo build
cargo test
cargo run --example json # or json2, custom_error, s_expression, etc.

Daily commands:

cargo build          # Debug build
cargo build --release  # Optimized
cargo test           # Run all test suites
cargo bench --bench json  # Run JSON parser benchmark
cargo doc --open     # Build and view docs

• src/lib.rs — Main library entry point exposing the public API, traits, and module organization for the entire parser combinator framework.
• src/traits.rs — Defines core traits (Input, Parser, etc.) that form the foundation of the combinator abstraction; understanding these is essential for extending nom.
• src/combinator/mod.rs — Implements fundamental parser combinators (map, flat_map, and, or, etc.) that users chain together to build parsers.
• src/bytes/mod.rs — Byte-level parsers (tag, take, is_a, etc.) that are the most commonly used low-level building blocks.
• src/sequence/mod.rs — Sequence combinators (tuple, pair, delimited, etc.) that compose multiple parsers in specific patterns.
• src/multi/mod.rs — Repetition combinators (many, many1, separated_list, fold, etc.) essential for parsing variable-length structures.
• src/error.rs — Error types and handling abstractions (ParseError trait) that define how parsing failures are reported and constructed.

Add a New Parser Combinator

1. Implement the combinator function in src/combinator/mod.rs, following the pattern of existing combinators like map or flat_map. (src/combinator/mod.rs)
2. Add unit tests in src/combinator/tests.rs, testing both success and error cases. (src/combinator/tests.rs)
3. Export the function in src/lib.rs if it's public API. (src/lib.rs)
4. Document with examples showing usage patterns. (src/combinator/mod.rs)

Add a New Byte-Level Parser

1. Implement the parser in both src/bytes/streaming.rs and src/bytes/complete.rs, ensuring consistent behavior except for Incomplete vs Error. (src/bytes/streaming.rs)
2. Add comprehensive tests in src/bytes/tests.rs covering edge cases. (src/bytes/tests.rs)
3. Re-export from src/bytes/mod.rs. (src/bytes/mod.rs)
4. Add documentation with examples to the function signature. (src/bytes/streaming.rs)

Create a Custom Error Type

1. Define a struct implementing the ParseError trait from src/error.rs. (src/error.rs)
2. Implement required methods: append, from_error_kind, from_char, compare, position. (src/error.rs)
3. See examples/custom_error.rs for a complete reference implementation. (examples/custom_error.rs)

Add a New Example Parser

1. Create examples/{parser_name}.rs with a complete, documented parser implementation. (examples/json.rs)
2. Include test cases and example input/output in the file. (examples/json.rs)
3. Update doc/nom_recipes.md with a recipe link if the pattern is generalizable. (doc/nom_recipes.md)

• Rust generics & trait system — Enables zero-copy, type-safe parser combinators that work over any input type (bytes, strings, custom) and error type without runtime overhead.
• IResult enum (Result<(I, O), E>) — Encodes both the parsed output and remaining input in the type system, making the parse flow explicit and composable.
• Dual streaming/complete modules — Allows the same logic to handle both incremental/streaming input (networks, files) and complete input (in-memory) with appropriate error semantics.
• Combinator higher-order functions — Provides a declarative, composable DSL for parsing without macros (though macros are also provided), reducing boilerplate and enabling complex parsers from simple primitives.

• Zero-copy design with lifetime constraints

  • Why: Nom avoids allocation and copying to achieve maximum performance; the trade-off is that parsers return references into the input, constraining lifetimes.
  • Consequence: Users must structure their code to accept borrowed data rather than owned, which can be less ergonomic but guarantees safety and speed.

• Dual streaming/complete implementations

  • Why: Different use cases require different error handling (streaming allows Incomplete, complete treats it as error).
  • Consequence: Code duplication and larger binary size, but necessary for correctness across deployment scenarios.

• Generic over input and error types via traits

  • Why: Maximum flexibility for users to implement custom input types and error handling.
  • Consequence: Higher complexity for library design and documentation; steep learning curve for advanced use cases.

• Parser combinators as closures/functions over traits

  • Why: Avoids monadic abstractions (Monad trait) which are less idiomatic in Rust.
  • Consequence: Less power than Haskell-style parser combinators, but better readability and performance for Rust users.

• Does not provide AST construction or semantic analysis—purely syntactic parsing.
• Not a parser generator (no grammar DSL like YACC/Bison)—parsers are hand-written in Rust code.
• Does not handle left-recursive grammars natively; users must restructure grammars or use workarounds.
• Not optimized for error recovery; focuses on fail-fast with precise error context.
• Does not provide built-in support for custom operator precedence parsing (see nom-language crate for that).

1) Streaming vs. Complete modes: src/bytes/streaming.rs differs from src/bytes/complete.rs in how they handle EOF. Streaming returns Incomplete on truncated input; Complete assumes input is full. Mix them and parsers behave unexpectedly. 2) The Parser trait is not Auto for all types: Custom parsers must explicitly implement Parser or use existing combinators to get trait bounds right. 3) alloc feature is required for many tests: Tests in tests/json.rs, tests/ini.rs require ["alloc"] in Cargo.toml—they will silently not run without it. 4) Error type must implement FromExternalError: Custom errors need nom::error::FromExternalError trait for map_res to work. 5) No built-in whitespace skipping: Unlike some parsers, nom requires explicit whitespace handling—benchmarks/benches/json.rs shows this pattern.

• Parser Combinators — The entire nom library is built on composing small, reusable parser functions into larger ones without boilerplate—understanding this pattern is essential to using nom effectively
• Zero-Copy Parsing — nom returns references (&'a str, &'a [u8]) to the original input rather than copying—critical for performance in nom and why the API uses lifetimes extensively
• Streaming vs. Complete Parsing — nom provides two modes (src/bytes/complete.rs and src/bytes/streaming.rs) with different EOF handling—choosing wrong breaks real-world parsers that receive partial input
• Algebraic Data Types (Sum Types) — nom's error handling (ErrorKind enum) and parser return types (IResult) use Rust enums as sum types; understanding pattern matching is necessary for error recovery
• Trait Bounds and Higher-Order Functions — nom combinators like map_res, fold, and the Parser trait use generic trait bounds to work with any parser—grasping this pattern is key to extending nom
• Streaming Algorithms — The streaming mode in src/bytes/streaming.rs handles incomplete input; understanding backtracking and lookahead is essential for parsing network protocols incrementally
• Nom Macros vs. Function API — nom v7+ deprecated macros in favor of function traits; old code uses do_parse! and others, but modern code uses .parse() method and combinator functions—knowing both for legacy compatibility

• pest-parser/pest — Alternative Rust parser generator using PEG syntax; heavier than nom but more declarative for complex grammars
• lalrpop/lalrpop — LALR parser generator for Rust; competes with nom for language parsing; more suitable for grammar-heavy use cases
• tamasfe/taplo — Real-world nom-based parser for TOML files; demonstrates production patterns and idiomatic error handling
• serde-rs/serde — Serialization framework that often pairs with nom parsers for converting parsed data into Rust structs; many examples use both together
• rust-bakery/cookiefactory — Sibling nom-ecosystem library for parsers written in reverse (serialization); mirrors nom's combinator philosophy for writers

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive streaming vs complete parser comparison tests

The repo has proptest regression files for character and number modules (proptest-regressions/character/ and proptest-regressions/number/) but only for 'complete.txt' and 'streaming.txt'. There's no systematic test suite comparing streaming parser behavior against complete parsers across different input types. Given nom's dual focus on streaming and complete parsing modes, adding a dedicated test file (tests/streaming_vs_complete.rs) would validate that both modes handle edge cases consistently and catch regressions in either mode.

• [ ] Create tests/streaming_vs_complete.rs with paired tests for core combinators
• [ ] Test across multiple input types: bytes, strings, custom inputs (referencing doc/custom_input_types.md patterns)
• [ ] Compare behavior on partial inputs, incomplete data, and error conditions
• [ ] Run proptest against both modes to generate regression files in proptest-regressions/streaming_vs_complete/

Implement missing benchmark for streaming JSON parser

The benchmarks/ directory has benchmarks/benches/json.rs and benchmarks/benches/json_streaming.rs, but examining the file structure suggests json_streaming.rs may not have full parity with json.rs or may be incomplete. Additionally, the repo lacks a streaming variant benchmark for other formats like arithmetic and ini. Adding comprehensive streaming benchmarks (benchmarks/benches/arithmetic_streaming.rs and benchmarks/benches/ini_streaming.rs) would help contributors understand performance characteristics and catch regressions in streaming implementations.

• [ ] Create benchmarks/benches/arithmetic_streaming.rs mirroring benchmarks/benches/arithmetic.rs but using streaming combinators
• [ ] Create benchmarks/benches/ini_streaming.rs for streaming INI parsing
• [ ] Ensure each benchmark uses criterion or existing bench framework consistently
• [ ] Document in benchmarks/README.md the differences between streaming and complete variants
• [ ] Run benchmarks locally to establish baselines

Add integration tests for custom error types with all parser modes

The repo has tests/custom_errors.rs and examples/custom_error.rs, but custom error handling is only documented in doc/error_management.md. There's no systematic test coverage validating custom error types work correctly across streaming, complete, and bit-level parsers. Adding tests/custom_error_integration.rs would ensure custom error implementations are fully compatible with nom's different parsing modes and would serve as a template for users implementing custom errors.

• [ ] Create tests/custom_error_integration.rs with test cases for custom error types in streaming mode (using nom::Needed)
• [ ] Test custom errors with complete parsers (no Needed)
• [ ] Test custom errors with bit-level parsers from nom::bits module
• [ ] Verify error recovery and composition works across all modes
• [ ] Reference and improve doc/error_management.md with examples from the test suite

• Add streaming parsers for common protocols: src/bytes/streaming.rs lacks some combinators present in src/bytes/complete.rs (e.g. take_until). Port 3-5 missing functions and add tests in tests/ following the pattern in tests/json.rs. Difficulty: medium, high-value for streaming data users.
• Expand documentation examples in doc/nom_recipes.md: Add a concrete recipe for parsing CSV with quoted fields and escaped delimiters (similar to the hex_color example in README but more complex). Include both complete and streaming versions. Difficulty: easy, high visibility.
• Add edge case tests for error messages: The benchmarks/benches/ parsers are untested for malformed input. Create a new test file tests/error_messages.rs that validates error::Error and error::ErrorKind generation for invalid JSON, HTTP, and INI. Difficulty: easy-medium, improves robustness.

The nom repository demonstrates strong security posture. It is a well-maintained parser combinator library with no critical vulnerabilities detected in the provided configuration. The codebase follows Rust best practices with proper use of safe abstractions, no hardcoded secrets detected, and minimal external dependencies. The project uses CI/CD workflows (evident from .github/workflows), maintains comprehensive testing, and includes fuzzing infrastructure (fuzz/ directory). Minor recommendations involve version pinning strategies for development dependencies. The MSRV (Minimum Supported Rust Version) of 1.65.0 is reasonably recent, indicating security updates are incorporated.

• Low · Pinned Proptest Version — Cargo.toml - dev-dependencies section. The dev-dependency proptest is pinned to an exact version (=1.0.0) rather than using a caret or tilde constraint. While this ensures reproducible builds, it may prevent security updates from being automatically applied during development. Fix: Consider using proptest = "1" or proptest = "1.0" to allow patch-level security updates while maintaining compatibility.
• Low · Memchr Default Features Disabled — Cargo.toml - memchr dependency. The memchr dependency has default-features = false, which disables standard library features. While intentional for no_std support, this should be reviewed to ensure it doesn't disable critical security features for the use case. Fix: Verify that disabling default features on memchr doesn't impact security or functionality. Document the rationale for this configuration.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.