Crate neotoma

Crate neotoma 

Source
Expand description

§Neotoma - Flexible Parser Combinator Library

Neotoma is a Rust parsing library that provides a flexible, cached parser combinator framework. It’s designed to parse structured data from any source implementing Read + Seek traits, with built-in memoization and backtracking capabilities.

§Key Features

  • Composable parsers: Build complex parsers from simple building blocks
  • Automatic memoization: Built-in caching prevents redundant parsing work
  • Backtracking support: Automatic position management for failed parses
  • UTF-8 aware: Comprehensive Unicode handling with ASCII optimization
  • Thread-safe: Uses efficient synchronization primitives from parking_lot
  • Generic input: Works with any Read + Seek source

§Quick Start

use neotoma::prelude::*;
use neotoma::{seq, oneof};
use std::io::Cursor;

// Build a parser for "hello" followed by optional whitespace and "world"
let parser = seq![
    Literal::from_str("hello"),
    Optional::new(Utf8Class::whitespace()),
    Literal::from_str("world")
];

let input = Cursor::new(b"hello world");
let mut source = Source::new(input);

let result = parse(parser, &mut source);
assert!(result.is_ok());

§Core Concepts

§Parser Trait

All parsers implement the Parser trait, which provides:

  • read(): Implement your parsing logic here
  • parse(): Public API that handles caching and backtracking automatically
  • id(): Must be overridden for parameterized parsers to avoid cache conflicts

§Composition

Build complex parsers using composition macros:

  • seq! for sequential parsing
  • oneof! for alternative choices

§Common Parser Types

  • Literal: Match exact byte sequences or strings
  • Class: Match character classes (byte-level)
  • Utf8Class: Match Unicode character classes
  • Repeat: Match repeated patterns with optional separators
  • Optional: Match zero or one occurrence

§Architecture

The library uses a Template Method Pattern for the Parser trait, where parse() handles caching and backtracking, while implementations provide custom logic in read(). The caching system uses a Strategy Pattern allowing different cache implementations.

Re-exports§

pub use parser::Parser;
pub use parser::Source;
pub use parser::parse;
pub use result::Error;
pub use result::ParseResult;
pub use class::Class;
pub use literal::Literal;
pub use utf8class::Utf8Class;
pub use eof::EndOfFile;
pub use optional::Optional;
pub use recursive::Recursive;
pub use repeat::Repeat;
pub use grammar::GrammarParser;

Modules§

cache
Parser caching system for memoization.
class
Byte-level character class parsing.
either
Alternative parser combinator and the oneof! macro.
eof
End-of-file detection for complete input consumption.
grammar
Grammar Syntax
literal
Literal string and byte sequence parsing.
optional
Optional parser combinator for zero-or-one matching.
parser
Core parser traits and utilities.
prelude
Commonly used imports for parser development
recursive
Self-referential parser support through deferred construction.
repeat
Repetition parser combinator for matching repeated patterns.
result
Error types and result handling for parsing operations.
sequence
Sequential parser composition and the seq! macro.
until
Conditional parsing with until combinators.
utf8class
UTF-8 character class parsing with Unicode support.
utf8util
UTF-8 decoding utilities for character-level parsing.

Macros§

oneof
Macro for creating Either parsers with multiple alternatives.
seq
Create a sequence parser from multiple parsers.