Skip to content

Commit dbbe517

Browse files
J-F-LiuJ-F-Liu
committed
Update README
1 parent 286828f commit dbbe517

File tree

1 file changed

+44
-43
lines changed

1 file changed

+44
-43
lines changed

‎README.md

+44-43
Original file line numberDiff line numberDiff line change
@@ -38,46 +38,47 @@ Aside from build issues (and the usual issues around error messages and debuggab
3838

3939
## List of predefined parsers and combinators
4040

41-
|Basic Parsers|Description|
42-
| --- | --- |
43-
|empty()|Always succeeds, consume no input.|
44-
|end() |Match end of input.|
45-
|sym(t)|Match a single terminal symbol *t*.|
46-
|seq(s) |Match sequence of symbols.|
47-
|list(p,s) |Match list of *p*, separated by *s*.|
48-
|one_of(set) |Success when current input symbol is one of the set.|
49-
|none_of(set)|Success when current input symbol is none of the set.|
50-
|is_a(predicate) |Success when predicate return true on current input symbol.|
51-
|not_a(predicate)|Success when predicate return false on current input symbol.|
52-
|take(n)|Read *n* symbols.|
53-
|skip(n)|Skip *n* symbols.|
54-
|call(pf)|Call a parser factory, can be used to create recursive parsers.|
55-
56-
|Parser Combinators|Description|
57-
| --- | --- |
58-
| p | q | Match p or q, return result of the first success. |
59-
| p + q | Match p and q, if both succeed return a pair of results. |
60-
| p - q | Match p and q, if both succeed return result of p. |
61-
| p * q | Match p and q, if both succeed return result of q. |
62-
| p >> q | Parse p and get result P, then parse q and return result of q(P). |
63-
| -p | Success when p succeeds, doesn't consume input. |
64-
| !p | Success when p fails, doesn't consume input. |
65-
|p.opt()|Make parser optional. Returns an `Option`.|
66-
|p.repeat(m..n)| `p.repeat(0..)` repeat p zero or more times<br>`p.repeat(1..)` repeat p one or more times<br>`p.repeat(1..4)` match p at least 1 and at most 3 times<br>`p.repeat(5)` repeat p exactly 5 times|
67-
|p.map(f)|Convert parser result to desired value.|
68-
|p.convert(f)|Convert parser result to desired value, fails in case of conversion error.|
69-
|p.pos() |Get input position after matching p.|
70-
|p.collect()|Collect all matched input symbols.|
71-
|p.discard()|Discard parser output.|
72-
|p.name(_)|Give parser a name to identify parsing errors.|
73-
|p.expect(_)|Mark parser as expected, abort early when failed in ordered choice.|
41+
| Basic Parsers | Description |
42+
| ---------------- | --------------------------------------------------------------- |
43+
| empty() | Always succeeds, consume no input. |
44+
| end() | Match end of input. |
45+
| sym(t) | Match a single terminal symbol _t_. |
46+
| seq(s) | Match sequence of symbols. |
47+
| list(p,s) | Match list of _p_, separated by _s_. |
48+
| one_of(set) | Success when current input symbol is one of the set. |
49+
| none_of(set) | Success when current input symbol is none of the set. |
50+
| is_a(predicate) | Success when predicate return true on current input symbol. |
51+
| not_a(predicate) | Success when predicate return false on current input symbol. |
52+
| take(n) | Read _n_ symbols. |
53+
| skip(n) | Skip _n_ symbols. |
54+
| call(pf) | Call a parser factory, can be used to create recursive parsers. |
55+
56+
| Parser Combinators | Description |
57+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58+
| p &#124; q | Match p or q, return result of the first success. |
59+
| p + q | Match p and q, if both succeed return a pair of results. |
60+
| p - q | Match p and q, if both succeed return result of p. |
61+
| p \* q | Match p and q, if both succeed return result of q. |
62+
| p >> q | Parse p and get result P, then parse q and return result of q(P). |
63+
| -p | Success when p succeeds, doesn't consume input. |
64+
| !p | Success when p fails, doesn't consume input. |
65+
| p.opt() | Make parser optional. Returns an `Option`. |
66+
| p.repeat(m..n) | `p.repeat(0..)` repeat p zero or more times<br>`p.repeat(1..)` repeat p one or more times<br>`p.repeat(1..4)` match p at least 1 and at most 3 times<br>`p.repeat(5)` repeat p exactly 5 times |
67+
| p.map(f) | Convert parser result to desired value. |
68+
| p.convert(f) | Convert parser result to desired value, fails in case of conversion error. |
69+
| p.pos() | Get input position after matching p. |
70+
| p.collect() | Collect all matched input symbols. |
71+
| p.discard() | Discard parser output. |
72+
| p.name(\_) | Give parser a name to identify parsing errors. |
73+
| p.expect(\_) | Mark parser as expected, abort early when failed in ordered choice. |
7474

7575
The choice of operators is established by their operator precedence, arity and "meaning".
7676
Use `*` to ignore the result of first operand on the start of an expression, `+` and `-` can fulfill the need on the rest of the expression.
7777

7878
For example, `A * B * C - D + E - F` will return the results of C and E as a pair.
7979

8080
## Example code
81+
8182
```rust
8283
extern crate pom;
8384
use pom::parser::*;
@@ -89,6 +90,7 @@ assert_eq!(output, Ok( (b'b', vec![b'd', b'e']) ) );
8990
```
9091

9192
### Example JSON parser
93+
9294
```rust
9395
extern crate pom;
9496
use pom::parser::*;
@@ -175,27 +177,28 @@ fn main() {
175177
println!("{:?}", json().parse(input));
176178
}
177179
```
180+
178181
You can run this example with the following command:
182+
179183
```
180184
cargo run --example json
181185
```
182186

183187
## Benchmark
184188

185-
| Parser | Time to parse the same JSON file |
186-
|------------------|----------------------------------|
187-
| pom: json_byte | 621,319 ns/iter (+/- 20,318) |
188-
| pom: json_char | 627,110 ns/iter (+/- 11,463) |
189-
| [pest](https://github.com/dragostis/pest): json_char | 13,359 ns/iter (+/- 811)|
190-
189+
| Parser | Time to parse the same JSON file |
190+
| ---------------------------------------------------- | -------------------------------- |
191+
| pom: json_byte | 621,319 ns/iter (+/- 20,318) |
192+
| pom: json_char | 627,110 ns/iter (+/- 11,463) |
193+
| [pest](https://github.com/dragostis/pest): json_char | 13,359 ns/iter (+/- 811) |
191194

192195
### Lifetimes and files
193196

194197
String literals have a static lifetime so they can work with the static version of Parser
195198
imported from `pom::Parser`. Input read from a file has a shorter lifetime. In this case you
196199
should import `pom::parser::Parser` and declare lifetimes on your parser functions. So
197200

198-
```javascript
201+
```rust
199202
fn space() -> Parser<u8, ()> {
200203
one_of(b" \t\r\n").repeat(0..).discard()
201204
}
@@ -204,10 +207,8 @@ fn space() -> Parser<u8, ()> {
204207

205208
would become
206209

207-
```javascript
210+
```rust
208211
fn space<'a>() -> Parser<'a, u8, ()> {
209212
one_of(b" \t\r\n").repeat(0..).discard()
210213
}
211214
```
212-
213-

0 commit comments

Comments
 (0)