Parseff

Parseff is a direct-style parser combinator library for OCaml 5 where parsers are plain functions (unit -> 'a), errors are typed via polymorphic variants, and the runtime handles control flow, backtracking, and streaming input. Designed for performance with zero-copy span APIs and fused operations.

Documentation

Installation

$ opam install parseff -y

Example

let number () =
  let digits = Parseff.many ~at_least:1 Parseff.digit () in
  let n = List.fold_left (fun acc d -> (acc * 10) + d) 0 digits in
  if n >= 0 && n <= 255 then n
  else Parseff.error (`Out_of_range n)

let ip_address () =
  let a = number () in
  let _ = Parseff.char '.' in
  let b = number () in
  let _ = Parseff.char '.' in
  let c = number () in
  let _ = Parseff.char '.' in
  let d = number () in
  Parseff.end_of_input ();
  (a, b, c, d)

let () =
  match Parseff.parse "192.168.1.1" ip_address with
  | Ok ((a, b, c, d)) ->
      Printf.printf "Parsed: %d.%d.%d.%d\n" a b c d
  | Error { pos; error = `Out_of_range n } ->
      Printf.printf "Error at %d: %d out of range (0-255)\n" pos n
  | Error { pos; error = `Unexpected_end_of_input } ->
      Printf.printf "Error at %d: unexpected end of input\n" pos
  | Error { pos; error = `Expected msg } ->
      Printf.printf "Error at %d: %s\n" pos msg
  | Error { pos; error = `Failure msg } ->
      Printf.printf "Error at %d: %s\n" pos msg
  | Error { pos; error = `Depth_limit_exceeded msg } ->
      Printf.printf "Error at %d: %s\n" pos msg

Features

• Build parsers with direct-style and compose with Parseff combinators
• API is designed to be expressive enough to not need monadic operators (>>=, >>|, *>), nor binding operators (let*, let+, and+)
• Typed domain errors via polymorphic variants
• Automatic backtracking with Parseff.or_
• Minimal dependency footprint only re for regex support and uucp for Unicode support
• Streaming support
• Domain-safe each Parseff.parse / Parseff.parse_source call is self-contained with no global mutable state, so independent parses can run in parallel across domains
• Zero-copy span APIs for low-allocation parsing
• Fused operations for hot paths

Performance

Parseff is built for throughput and low allocation: in the current benchmark suite, the generic Parseff parsers are up to ~1.5x faster than Angstrom's baselines, and its fused zero-copy paths roughly ~3x faster.

Even against Angstrom's optimized JSON parser, Parseff's optimized path is still ~1.5x faster while cutting minor allocations from ~11.1 GB to ~1.3 GB; against Angstrom's generic JSON parser, the generic / optimized Parseff paths land at ~800 MB / ~1.3 GB versus ~5.9 GB.

See the full comparison for the methodology and results, bench/bench_json.ml for the JSON benchmark, and bench/ for the full suite.

Documentation

• Quick start
• API overview
• Your first parser
• Error handling
• Making parsers fast
• Comparison with Angstrom
• A JSON parser
• Expressions with precedence

Contributing

• Open an issue to discuss proposed changes
• Write tests for new features
• Run make fmt before submitting
• Ensure all tests pass with make test

License

MIT. See LICENSE for details.