# Simple parser package.
This package provides a `Parser` which allows you to peek at characters to see what's coming
next in a character stream, and to read expected characters. For example, methods include:
* `peek()` - return the next character from the stream without removing it;
* `require(&str)` - returns an error if the given sequence is not found next in the stream;
* `skip_while(Fn(char)->bool)` - keep removing characters while the predicate is satisfied;
* `read_up_to(char)` - take characters from the stream up to (but not including) the given
character;
* `accept(char)` - skips the given character if it is found next in the stream.
All fallible methods return a `Result` and no method in this package should ever panic.
Parsing relies on a `ByteBuffer` which wraps around a byte stream, and on a decoder such as
`Utf8Decoder` which wraps around a `ByteBuffer` and decodes bytes into characters. Finally a
`Parser` is created by wrapping a decoder. The end result is a `Parser` which lets you peek and
read characters.
## Examples
### Acornsoft Logo parser
Suppose you want to parse a (simplified) set of Acornsoft Logo instructions, such that you only
want to accept the "FORWARD", "LEFT", and "RIGHT" instructions, and each instruction must come
on a line of its own (separated by a newline character), and each instruction is followed by any
number of space characters, which is then followed by a numeric amount. Example input might look
like this:
```text
FORWARD 10
RIGHT 45
FORWARD 20
RIGHT 10
FORWARD 5
LEFT 3
```
You could use sipp to parse these instructions using code like this:
```rust
let input =
"FORWARD 10\nRIGHT 45\nFORWARD 20\nRIGHT 10\nFORWARD 5\nLEFT 3";
// We know that Rust strings are UTF-8 encoded, so wrap the input
// bytes with a Utf8Decoder.
let decoder = Utf8Decoder::wrap(input.as_bytes());
// Now wrap the decoder with a Parser to give us useful methods
// for reading through the input.
let mut parser = Parser::wrap(decoder);
// Keep reading while there is still input available.
while parser.has_more()? {
// Read the command by reading everything up to (but not
// including) the next space.
let command = parser.read_up_to(' ')?;
// Skip past the (one or more) space character.
parser.skip_while(|c| c == ' ')?;
// Read until the next newline (or the end of input, whichever
// comes first).
let number = parser.read_up_to('\n')?;
// Now either there is no further input, or the next character
// must be a newline. If the next character is a newline, skip
// past it.
parser.accept('\n')?;
}
```
### Comma-separated list parser
Given a hardcoded string which represents a comma-separated list, you could use this package to
parse it like so:
```rust
let input = "first value,second value,third,fourth,fifth,etc";
let buffer = ByteBuffer::wrap(input.as_bytes());
let decoder = Utf8Decoder::wrap_buffer(buffer);
let mut parser = Parser::wrap(decoder);
let mut value_list = Vec::new();
// Keep reading while input is available.
while parser.has_more()? {
// Read up to the next comma, or until the end of input
// (whichever comes first).
let value = parser.read_up_to(',')?;
value_list.push(value);
// Now either there is no further input, or the next character
// must be a comma. If the next character is a comma, skip
// past it.
parser.accept(',')?;
}
assert_eq!(value_list
.iter()
.map(|s| s.to_string())
.collect::<Vec<String>>(),
vec!["first value",
"second value",
"third",
"fourth",
"fifth",
"etc"]);
```
## Release notes
### 0.1.0
Initial release.
### 0.1.1
* Added `has_more` method to Parser.
* Adjusted rustdoc based on advice found in
[Rust API Guidelines](https://rust-lang.github.io/api-guidelines/), primarily in separating out
error descriptions from the lede and moving them into a dedicated "Errors" section within each
method's rustdoc comment.
### 0.2.0
Altered return type of public method `Parser.read_up_to(char)` so that it now returns `None`
instead of an empty `String`. Adjusted examples and unit tests accordingly.