# Simple parser package.
This package provides a `ByteBuffer` which wraps around a byte stream, and decoders such as
`Utf8Decoder` which can wrap around a `ByteBuffer`, and a `Parser` which can be wrapped around a
decoder. The end result is a `Parser` which lets you peek at characters to see what's coming next,
and then read expected characters. All fallible methods return a `Result` and no method in this
package should ever panic.
## 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:
```
# use sipp::{parser::Parser, decoder::Utf8Decoder,
# decoder::ByteStreamCharDecoder, buffer::ByteBuffer};
# use std::io::{Error, ErrorKind};
# fn main() -> Result<(), Error> {
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);
# let mut compressed_instructions = String::with_capacity(16);
// Keep reading while there is still input available.
while let Some(_) = parser.peek()? {
// Read the command by reading everything up to (but not including) the next space.
let command = parser.read_up_to(' ')?;
# match command.as_str() {
# "FORWARD" => compressed_instructions.push('F'),
# "RIGHT" => compressed_instructions.push('R'),
# "LEFT" => compressed_instructions.push('L'),
# _ => {return Err(Error::new(ErrorKind::InvalidData, "Invalid Logo instruction!"));}
# }
// 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')?;
# compressed_instructions.push_str(number.as_str());
// 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')?;
}
# assert_eq!(compressed_instructions, "F10R45F20R10F5L3");
# Ok(())
# }
```
### Comma-separated list parser
Given a hardcoded string which represents a comma-separated list, you could use this package to
parse it like so:
```
# use sipp::{parser::Parser, decoder::Utf8Decoder,
# decoder::ByteStreamCharDecoder, buffer::ByteBuffer};
# fn main() -> Result<(), std::io::Error> {
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 let Some(_) = parser.peek()? {
// 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(',')?;
}
# Ok(())
# }
```