Crate gramex 

gramex

grammer expressions, a common language for advance parsers.

gramex is a library and a simple language for building parsers, tokenizers and other forms of grammer based transformers.

it simplify parsing by transforming a simple yet expressive grammer declerations into efficient reusable matcher functions.

features

• type agnostic matching: parse str, byte slices ([u8]), or custom token streams.
• zero cost abstractions: grammers compile down to highly optimized, near metal matcher functions.
• rich grammar syntax: native support for repetitions, alternations (|), intersections (&), ranges (..), lookahead peeks (~), and negations (!).
• powerful capturing & mapping: extract sections, nested or enumerated, and map them into custom types.
• extensible throught code: just drop your custom matcher inside {} block.
• term based grammer defenition thought gramex, or inlined expression matching through matches and try_match
• batteries included: comes with various built-in helpers and standard patterns.

quick guide

// quick matching can be done using `matches` macro
// matches agianst items by literals, path or blocks
assert!(matches!("abc": str, "abc"));
let pat = "abc";
assert!(matches!("abc": str, pat));
assert!(matches!("bc": str, { &pat[1..] }));

// patterns are separated by whitespace
assert!(matches!("abc": str, 'a' 'b' 'c'));

// `?`: optional, `*`: +0 repetition, `+`: +1 repetition
// `[count]`: exact repetition, `[min..max]`: ranged repetition
assert!(matches!("abbccc": str, 'a'? 'b'+ 'c'[3]));

// `!`: matches one item if pattern doesnt match
// `~`: matches a pattern without advancing
assert!(matches!("cba": str, !'a' ~'b' "ba"));

// `_`: matches any, `..` range match
assert!(matches!("abc": str, 'a'..'z' _ 'c'));

// `|`: match any of the pattern
// `&`: match if all patterns matches
assert!(matches!("b": str, 'a' | 'b' | 'c'));
assert!(matches!("b": str, 'a'..'z' & !'c'));

// `cond -> expr` matches `expr` if `cond` matches
assert!(matches!("ad": str, 'a' ('b' -> "bc") 'd'));

// capture are done using `(name = pattern)`
assert!(try_match!("abc": str, 'a' (bc = "bc")).is_ok_and(|v| v.bc == "bc"));

other documentations

• grammer reference: documenting the grammer language syntax and its behaviours.
• glossary: glossary of terms and concepts.

Modules

bits

bytes matching

docs

str

str implementation

Macros

gramex

declare a grammer module.

matcher

create a Matcher from an inline expression.

matches

check if a MatchAble matches an inline expression.

try_match

match a MatchAble against an inline expression.

Structs

MatchError

an error encountered during matching.

MatchStatus

the status of matching.

Enums

MatchSignal

the result status of matching operation

Traits

MatchAble

a type that can be matched by gramex

MatchBy

handle matching by a specific type

Matcher

a function that matches a MatchAble.

Functions

a

matches a token using a predicate.

an

matches number of tokens using a predicate.

by

provide type inference for closures implementing Matcher.

consume

matches a MatchAble and return the matched and remaining sections.

eof

matches the end of the input.

fail

always fail with MatchSignal::MisMatched.

fail_with

always fail with a custom MatchSignal::Error message.

list

matches a sep separated list of item.

matcher_for

create a Matcher from a matching value.

matches

check if a MatchAble matches against a Matcher.

noop

matches nothing.

test

test a predicate without advancing the index.

touch

run a function at the current index.

Type Aliases

MatchResult

a Result type dedicated for matching.