# 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