YAPCoL

Yet Another Parser Combinator Library.

yapcol is a flexible and simple-to-use parser combinator library for Rust. It allows you to build complex parsers by combining smaller, simpler ones. The library is designed to be easy to understand and use, while still providing powerful features like arbitrary lookahead and nested parsers.

Features

• Arbitrary Lookahead: easily backtrack and try alternative parsers using attempt and look_ahead.
• Generic Input: works with any iterator whose items implement the InputToken trait.
• Zero Dependencies: yapcol has no dependencies besides Rust's standard library.

Installation

Add YAPCoL to your Cargo.toml:

[dependencies]
yapcol = "0.5.0"

Or use cargo add:

cargo add yapcol

Supported Combinators

yapcol provides a wide range of built-in combinators:

• Basic: is, satisfy, any, end_of_input, success.
• Choice and Optional: choice, maybe, either.
• Repetition: at_least, count, many, many_until, once_or_more, once_up_to, up_to, and variations that collect the matches.
• Lookahead and Backtracking: attempt, look_ahead, not_followed_by.
• Grouping: between, separated_by0, separated_by1.
• Associativity: chain_left, chain_right.

Usage

Using Combinators

The most convenient approach to YAPCoL is to use the built-in combinators to create your parsers:

use yapcol::{Input, Parser};
use yapcol::{is, many_collect};

let mut input = Input::new_from_chars("aaab".chars(), None);

// Combine 'is' and 'many_collect' to parse multiple 'a's
let is_a = is('a');
let parser = many_collect(&is_a);

let result = parser(&mut input);
assert_eq!(result, Ok(vec!['a', 'a', 'a']));

// Shortcuts methods are available for some combinators:
let mut input = Input::new_from_chars("aaab".chars(), None);
let parser = is('a').many_collect();
let result = parser(&mut input);
assert_eq!(result, Ok(vec!['a', 'a', 'a']));

Using Custom Parsers

You might also define your own custom parsers as functions. Any function of the following Fn trait automatically implements the Parser trait:

Fn(&mut Input<IT>) -> Result<O, Error>

For example:

use yapcol::is;
use yapcol::{Error, Input, StringInput};

fn my_custom_parser(input: &mut StringInput) -> Result<String, Error> {
	let a = is('a')(input)?;
	let b = is('b')(input)?;
	Ok(format!("{}{}", a, b))
}

let mut input = Input::new_from_chars("ab".chars(), None);
assert_eq!(my_custom_parser(&mut input), Ok("ab".to_string()));

Error Handling

Every parser returns a Result<O, Error>. When parsing fails, the Err variant contains the following errors, defined in the yapcol::error::Error enum:

• UnexpectedToken: the parser encountered a token that did not satisfy its requirements.
• EndOfInput: the input stream was exhausted before the parser could match.
• NonConsumingLoop: a repetition parser detected that the inner parser succeeded without consuming any input, which would cause an infinite loop.

The code below showcases all error variants in a simple character-based parsing example:

use yapcol::input::Position;
use yapcol::{Error, Input, Mismatch, any, is, many, success};

let source_name = Some(String::from("file.txt"));
let mut input = Input::new_from_chars(vec!['a'], source_name.clone());
let parser = is('b');
let output = parser(&mut input);

// Fails with UnexpectedToken when the token does not match.
let position = Position::new(1, 1); // The position of the error on the input.
let mismatch = Mismatch::new('b', 'a'); // The mismatch (expected, found).
assert_eq!(
	output,
	Err(Error::UnexpectedToken(
		source_name,
		position,
		Some(mismatch)
	))
);

// Consume the only token, then try to read more.
is('a')(&mut input).unwrap();
assert_eq!(any()(&mut input), Err(Error::EndOfInput(None)));

// The `success` combinator always succeeds without consuming any input, so `many_collect` detects the
// loop.
let parser = success(());
let mut input = Input::new_from_chars("abc".chars(), None);
assert_eq!(
	many(&parser)(&mut input),
	Err(Error::NonConsumingLoop(None, Position::new(1, 1)))
);

The Error type implements Display, so you can print human-readable error messages:

use yapcol::input::Position;
use yapcol::{Error, Mismatch};

let source = "file.txt".to_string();
let position = Position::new(3, 12); // The position of the error on the input.
// UnexpectedToken with mismatch data
let mismatch = Mismatch::new("expression", "operator"); // The mismatch (expected, found).
let error = Error::UnexpectedToken(Some(source), position, Some(mismatch));
assert_eq!(
	error.to_string(),
	"Unexpected token at file.txt:3:12. Expected: expression, found: operator"
);

// UnexpectedToken without mismatch data
let source = "file.txt".to_string();
let error = Error::UnexpectedToken(Some(source), position, None);
assert_eq!(error.to_string(), "Unexpected token at file.txt:3:12.");

// EndOfInput
let expected = Box::new("expression");
let error = Error::EndOfInput(Some(expected));
assert_eq!(
	error.to_string(),
	"End of input reached when expected expression."
);

// NonConsumingLoop
let error = Error::NonConsumingLoop(Some("file.txt".to_string()), Position::new(3, 12));
assert_eq!(
	error.to_string(),
	"Non-consuming parser loop at file.txt:3:12."
);

Examples

Real-world examples are available in the examples/ directory, including an arithmetic expression evaluator. There are two different implementations:

• String-based: parses text directly from a stream of characters.
• Token-based: uses a lexer to tokenize the input before parsing.

For more details on how to run and understand these examples, check the Examples README.

Contributing

If you would like to report a bug, please create an issue. If you would like to contribute with bug fixing or small improvements, please open a Pull Request. If you would like to contribute with a new feature (regardless if it's in the roadmap or not), contact the developer.

License

YAPCoL is distributed under the terms of the MIT license. For more information, check the LICENSE file in this repository.