glue 0.4.1

Glue is a parser combinator library that is designed for parsing text based formats with speed and efficiency.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# Glue

[![Build Status](https://travis-ci.org/anarchistmae/glue-rs.svg?branch=master)](https://travis-ci.org/anarchistmae/glue-rs)
[![Latest Version](https://img.shields.io/crates/v/glue.svg)](https://crates.io/crates/glue)
[![Documentation](https://docs.rs/glue/badge.svg)](https://docs.rs/glue)
![Minimum rustc version](https://img.shields.io/badge/rustc-1.32+-yellow.svg)
[![License:MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
![lines of code](https://tokei.rs/b1/github/anarchistmae/glue-rs)

Glue is a parser combinator framework that is designed for parsing text based formats, it is easy to use and relatively efficient.

## Usage

```rust
use glue::prelude::*;

match merge(one_or_more(is(alphabetic))).parse("foobar") {
    Ok((result, _)) => {
        println!("Found: {}", result);
    },
    Err(_) => {
        println!("Nothing found!");
    }
}
```

### Writing your own parser functions

```rust
use glue::prelude::*;

#[derive(Debug, PartialEq)]
enum Token {
    Identifier(String),
}

fn identifier<I: Parsable>() -> impl Parser<I, Token> {
    move |input: I| {
        let (token, input) = merge(one_or_more(is(alphabetic))).parse(input)?;

        Ok((Token::Identifier(token.to_string()), input))
    }
}

assert_eq!(identifier().parse("foobar"), Ok((
    Token::Identifier("foobar".into()),
    ""
)));
```

### Pretty human readable error messages

Glue does the hard work of implementing error messages for you, have a look at [this example] which created the following message:

```
   1 │ foo xxx
   · │       ┃
   · ┢━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
   · ┃ Unexpected 'xxx'                                                       ┃
   · ┃ Expected bar                                                           ┃
   · ┃ At 1:7 of path/to/file                                                 ┃
     ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```

For more detailed examples, look in the [examples directory] in the [git repository].

[git repository]: https://github.com/anarchistmae/glue-rs
[examples directory]: https://github.com/anarchistmae/glue-rs/tree/master/examples
[this example]: https://github.com/anarchistmae/glue-rs/blob/master/examples/printable_error.rs


### List of parsers and combinators
#### Branches

<dl>
    <dt><code>all((Parser, ...))</code></dt>
    <dd>Run each of the provided parsers and return the first that is successful.</dd>
    <dt><code>either(Parser, Parser)</code></dt>
    <dd>Run either parser returning whichever succeeds.</dd>
    <dt><code>optional()</code></dt>
    <dd>Run a parser and return its result on success or an empty result on failure.</dd>
</dl>

#### Matches

<dl>
    <dt><code>empty()</code></dt>
    <dd>Matches nothing and always succeeds, useful as a placeholder in tuples</dd>
    <dt><code>is(Testable)</code></dt>
    <dd>Match a character using a callback, string or anything that implements `Testable`.</dd>
    <dt><code>isnt(Testable)</code></dt>
    <dd>Match negatively, a character using a callback, string or anything that implements `Testable`.</dd>
    <dt><code>literal(match: &str)</code></dt>
    <dd>Match a literal string.</dd>
    <dt><code>take(number: usize)</code></dt>
    <dd>Match a specific number of characters.</dd>
</dl>

#### Repeaters

<dl>
    <dt><code>min_to_max(minimum: usize, maximum: usize, Parser)</code></dt>
    <dd>Run a parser a minimum number of times and up to a maximum.</dd>
    <dt><code>min_or_more(minimum: usize, Parser)</code></dt>
    <dd>Run a parser a minimum number or more times.</dd>
    <dt><code>zero_to_max(maximum: usize, Parser)</code></dt>
    <dd>Run a parser zero to a maximum number of times.</dd>
    <dt><code>zero_or_more(Parser)</code></dt>
    <dd>Run a parser zero or more times until it has matched everything it can.</dd>
    <dt><code>one_to_max(maximum: usize, Parser)</code></dt>
    <dd>Run a parser one to a maximum number of times.</dd>
    <dt><code>one_or_more(Parser)</code></dt>
    <dd>Run a parser one or more times until it has matched everything it can.</dd>
    <dt><code>merge(Parser)</code></dt>
    <dd>Run a parsers that return multiple results and turns them into a single result.</dd>
</dl>

#### Sequences

<dl>
    <dt><code>both(Parser, Parser)</code></dt>
    <dd>Run both parsers where one must follow the other.</dd>
    <dt><code>all((Parser, ...))</code></dt>
    <dd>Run each of the provided parsers and in the specified order and return all of the results.</dd>
</dl>

#### Structures

<dl>
    <dt><code>separated_list(separator: Parser, Parser)</code></dt>
    <dd>Run a parser many times, separated by another parser.</dd>
</dl>