# Glue v0.8 <img src="https://gitlab.com/glue-for-rust/brands/raw/master/glue-512.png" align="right" width="128" height="128" />
Glue is a parser combinator framework for parsing text based formats, it is easy to use and relatively fast too.
## Usage
Use the `test` method to see if your input matches a parser:
```rust
use glue::prelude::*;
if take(1.., is(alphabetic)).test("foobar") {
println!("One or more alphabetic characters found!");
}
```
Use the `parse` method to extract information from your input:
```rust
use glue::prelude::*;
assert_eq!(take(1.., is(alphabetic)).parse("foobar"), Ok((
ParserContext {
input: "foobar",
bounds: 0..6,
},
"foobar"
)))
```
Write your own parser functions:
```rust
use glue::prelude::*;
#[derive(Debug, PartialEq)]
enum Token<'a> {
Identifier(&'a str),
}
fn identifier<'a>() -> impl Parser<'a, Token<'a>> {
move |ctx| {
take(1.., is(alphabetic)).parse(ctx)
.map_result(|token| Token::Identifier(token))
}
}
assert_eq!(identifier().parse("foobar"), Ok((
ParserContext {
input: "foobar",
bounds: 0..6,
},
Token::Identifier("foobar")
)));
```
For more information, look in the [examples directory] in the [git repository].
## Cheat Sheet
### Finders
Parser combinators for matching arbitrary types.
#### `find(repetitions: RangeBounds, parser: impl Parser)`
Run a parser a minimum number of times and up to a maximum and capture its results.
See the [API documentation][find].
#### `find_all((impl Parser, ...))`
Run each of the provided parsers and in the specified order and return all of the results.
See the [API documentation][find_all].
#### `find_any((impl Parser, ...))`
Run each of the provided parsers and return the first that is successful.
See the [API documentation][find_any].
#### `find_until(predicate: impl Parser, parser: impl Parser)`
Run a parser until a predicate is reached and capture its results.
See the [API documentation][find_until].
#### `find_separated(repetitions: RangeBounds, parser: Parser, separator: Parser)`
Parse a structure that consists of multiple parsers separated by another.
See the [API documentation][find_separated].
#### `find_when(predicate: Parser, parser: Parser)`
Run a parser, and if it is successful, run another parser and return its results.
See the [API documentation][find_when].
#### `find_when_not(predicate: Parser, result: Parser)`
Run a parser, and if it is not successful, run another parser and return its results.
See the [API documentation][find_when_not].
### Takers
Parser combinators for matching strings.
#### `take(repetitions: RangeBounds, parser: impl Parser)`
Run a parser a minimum number of times and up to a maximum and capture the input it parsed.
See the [API documentation][take].
#### `take_all((impl Parser, ...))`
Run each of the provided parsers and in the specified order and return all of the matched input.
See the [API documentation][take_all].
#### `take_any((impl Parser, ...))`
Run each of the provided parsers until one is successful and return the input it parsed.
See the [API documentation][take_any].
#### `take_until(repetitions: RangeBounds, predicate: impl Parser, parser: Parser)`
Run a parser until a predicate is reached and capture the input it parsed.
See the [API documentation][take_until].
### Matchers
Parser combinators for matching literals.
#### `empty()`
Matches nothing and always succeeds, useful as a placeholder in tuples.
See the [API documentation][empty].
#### `eoi()`
Matches the end of input.
See the [API documentation][eoi].
#### `is(test: impl Tester)`
Match using a string or character literal, callback or implementation of `Tester`.
See Testers[testers] below or the [API documentation][is].
#### `isnt(test: impl Tester)`
Match negatively using a string or character literal, callback or implementation of `Tester`.
See Testers[testers] below or the [API documentation][isnt].
#### `one_of(test: &str)`
Match the next character against one of these characters.
See Testers[testers] below or the [API documentation][one_of].
#### `soi()`
Matches the start of input.
See the [API documentation][soi].
### Mappers
Parser combinators for mapping one thing to another.
#### `map_error(parser: impl Parser, map: FnMut)`
Run a parser and map the error it returns on failure to a different error.
See the [API documentation][map_error].
#### `map_result(parser: impl Parser, map: FnMut)`
Run a parser and map the data it returns on success.
See the [API documentation][map_result].
#### `optional(parser: impl Parser)`
Run a parser and return `Some` on success or `None` on failure.
See the [API documentation][optional].
### Structures
Parser combinators for matching structures. Not part of the default prelude, include these combinators manually:
```rust
use glue::combinators::structures::*;
```
#### `delimited(prefix: impl Parser, parser: impl Parser, suffix: impl Parser)`
Match a structure surrounded by balanced delimiters.
See the [API documentation][delimited].
#### `left_delimited(prefix: impl Parser, parser: impl Parser)`
Match a structure with left hand delimiter.
See the [API documentation][left_delimited].
#### `right_delimited(parser: impl Parser, suffix: impl Parser)`
Match a structure with right hand delimiter.
See the [API documentation][right_delimited].
#### `separated(left: impl Parser, separator: impl Parser, right: impl Parser)`
Match a structure that consists of two parsers separated by another.
See the [API documentation][separated].
### Whitespace
Parser combinators for working with whitespace. Not part of the default prelude, include these combinators manually:
```rust
use glue::combinators::whitespace::*;
```
#### `space(repititions: RangeBounds)`
A shorthand for matching whitespace characters.
See the [API documentation][space].
#### `trim(parser: impl Parser)`
Trim preceding and following whitespace from a parser.
See the [API documentation][trim].
### Characters
Character matching methods that implement `Tester` for use with the `is` and `isnt` parser combinators.
#### `any`
Match any character.
#### `one_of("abc")` or `"abc".chars()`
Match the next character against one of these characters.
#### `alphabetic`
Match any alphabetic character.
#### `alphanumeric`
Match any alphanumeric character.
#### `numeric`
Match any numeric character.
#### `digit`
Match any decimal digit.
#### `hex_digit`
Match any hexidecimal digit.
#### `whitespace`
Match any whitespace character.
[git repository]: https://gitlab.com/glue-for-rust/glue-rs
[examples directory]: https://gitlab.com/glue-for-rust/glue-rs/tree/release/0.8.x/examples
[find]: https://docs.rs/glue/latest/glue/combinators/finders/fn.find.html
[find_all]: https://docs.rs/glue/latest/glue/combinators/finders/fn.find_all.html
[find_any]: https://docs.rs/glue/latest/glue/combinators/finders/fn.find_any.html
[find_until]: https://docs.rs/glue/latest/glue/combinators/finders/fn.find_until.html
[find_separated]: https://docs.rs/glue/latest/glue/combinators/finders/fn.find_separated.html
[find_when]: https://docs.rs/glue/latest/glue/combinators/finders/fn.find_when.html
[find_when_not]: https://docs.rs/glue/latest/glue/combinators/finders/fn.find_when_not.html
[take]: https://docs.rs/glue/latest/glue/combinators/takers/fn.take.html
[take_any]: https://docs.rs/glue/latest/glue/combinators/takers/fn.take_any.html
[take_all]: https://docs.rs/glue/latest/glue/combinators/takers/fn.take_all.html
[take_until]: https://docs.rs/glue/latest/glue/combinators/takers/fn.take_until.html
[empty]: https://docs.rs/glue/latest/glue/combinators/matchers/fn.empty.html
[eoi]: https://docs.rs/glue/latest/glue/combinators/matchers/fn.eoi.html
[is]: https://docs.rs/glue/latest/glue/combinators/matchers/fn.is.html
[isnt]: https://docs.rs/glue/latest/glue/combinators/matchers/fn.isnt.html
[one_of]: https://docs.rs/glue/latest/glue/combinators/matchers/fn.one_of.html
[soi]: https://docs.rs/glue/latest/glue/combinators/matchers/fn.soi.html
[map_error]: https://docs.rs/glue/latest/glue/combinators/mappers/fn.map_error.html
[map_result]: https://docs.rs/glue/latest/glue/combinators/mappers/fn.map_result.html
[optional]: https://docs.rs/glue/latest/glue/combinators/mappers/fn.optional.html
[delimited]: https://docs.rs/glue/latest/glue/combinators/structures/fn.delimited.html
[left_delimited]: https://docs.rs/glue/latest/glue/combinators/structures/fn.left_delimited.html
[right_delimited]: https://docs.rs/glue/latest/glue/combinators/structures/fn.right_delimited.html
[separated]: https://docs.rs/glue/latest/glue/combinators/structures/fn.separated.html
[space]: https://docs.rs/glue/latest/glue/combinators/whitespace/fn.space.html
[trim]: https://docs.rs/glue/latest/glue/combinators/whitespace/fn.trim.html