Quick start

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.

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
• 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.

Installation

with opam

opam install parseff -y

with dune package management

Add parseff to your dune-project:

(package
 (name my_project)
 (depends
  (ocaml (>= 5.3))
  (parseff (>= 0.1))))

Then lock and build:

dune pkg lock
dune build

From source

git clone https://github.com/davesnx/parseff.git
cd parseff
make init
make build
dune install

Add to your dune file

(executable
 (name my_parser)
 (libraries parseff))

Example

Here’s a small parser that validates IPv4 addresses 192.168.1.1 or 0.0.0.0. A detailed explanation of the IPv4 addresses parser:

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 = `Expected msg } ->
      Printf.printf "Error at %d: %s\n" pos msg

API organization

Section	Combinators
Core	consume, char, satisfy, take_while, skip_while, match_regex, fail, error, end_of_input
Combinators	or_, one_of, one_of_labeled, optional, look_ahead, expect, rec_
Repetition and separation	many, count, sep_by, between, end_by, fold_left, fold_right
Convenience	digit, letter, alphanum, any_char, is_whitespace, whitespace, skip_whitespace
Errors	fail, error, expect
Diagnostics	warn, warn_at, parse_until_end, parse_source_until_end
Zero-copy and fused operations	take_while_span, sep_by_take_span, sep_by_take, fused_sep_take, skip_while_then_char
Streaming	Source.of_string, Source.of_channel, Source.of_function, parse_source, parse_source_until_end