bparse/lib.rs
1#![warn(missing_docs)]
2//! ## Overview
3//!
4//! Parsing usually involves going through a sequence of bytes and branching off based on what was seen.
5//! This crate simplifies the task of recognizing complex patterns in a byte slices.
6//!
7//! It is made up of three parts:
8//! 1. The [`Pattern`] trait: represents the pattern to be recognized.
9//! 1. A list of common functions and combinators for composing `Patterns` together.
10//! 1. The [`Buf`] struct; a [`Cursor`](std::io::Cursor)-like wrapper around an input slice that uses patterns to advance its position.
11//!
12//! # Example
13//!
14//! Recognizing JSON numbers can get tricky.
15//! The [spec](https://www.json.org/json-en.html) allows for numbers like `12`, `-398.42`, and even `12.4e-3`.
16//! Here we incrementally build up a pattern called `number` that can recognizes all JSON number forms.
17//!
18//! ```
19//! use bparse::{Buf, Pattern, range, at_least, optional, oneof, end};
20//!
21//! let sign = optional(oneof(b"-+"));
22//! let onenine = range(b'1', b'9');
23//! let digit = "0".or(onenine);
24//! let digits = at_least(1, digit);
25//! let fraction = optional(".".then(digits));
26//! let exponent = optional("E".then(sign).then(digits).or("e".then(sign).then(digits)));
27//! let integer = onenine
28//! .then(digits)
29//! .or("-".then(onenine).then(digits))
30//! .or("-".then(digit))
31//! .or(digit);
32//! let number = integer.then(fraction).then(exponent);
33//!
34//! let input = "234||344.5||0.43e12";
35//!
36//! let mut buf = Buf::from(input);
37//!
38//! let Some(b"234") = buf.consume(number) else {
39//! panic!();
40//! };
41//!
42//! assert!(buf.skip("||"));
43//!
44//! let Some(b"344.5") = buf.consume(number) else {
45//! panic!();
46//! };
47//!
48//! assert!(buf.skip("||"));
49//!
50//! let Some(b"0.43e12") = buf.consume(number) else {
51//! panic!();
52//! };
53//!
54//! assert!(buf.consume(end()).is_some());
55//! ```
56
57mod buf;
58mod pattern;
59
60pub use buf::Buf;
61pub use pattern::*;
62
63#[cfg(doctest)]
64#[doc = include_str!("../README.md")]
65pub struct ReadmeDocTests;