Struct atoms::Parser

pub struct Parser<R> { /* fields omitted */ }

A parser for a particular str

Parsing expressions requires a parser to be attached to the given string.

use atoms::{Parser, StringValue};
let text = "(this is a series of symbols)";
let parser = Parser::new(&text);
let parsed = parser.parse_basic().unwrap();
assert_eq!(
    StringValue::into_list(
        vec!["this", "is", "a", "series", "of", "symbols"], 
        |s| StringValue::symbol(s).unwrap()
    ),
    parsed
);

The type parameter given to Parser::parse is to inform the parser of how to evaluate symbols. Any type that implements ToString and FromStr reflexively can be used here. String is just one such, however it would be trivial to create an enum that restricted parsing to pre-defined symbols.

A parser has to be attached to a particular str to parse it. Really, this is to allow us to make sane error messages.

Methods

impl<'a> Parser<&'a [u8]>

fn new<'b>(source: &'b AsRef<[u8]>) -> Parser<&'b [u8]>

Create a new parser for a single expression

impl<R: Read> Parser<R>

fn reader(source: R) -> Parser<R>

Create a new parser for a reader.

The reader can can be a source of series of discrete expressions, each to be read one at a time.

fn read<Sym: FromStr>(&mut self) -> ParseResult<Value<Sym>>

Read the next expression.

use atoms::{Parser, Value};
let text = r#"
    (this is a series of symbols)
    (this is another sexpression)
    mono ;Single expression on its own line
    (this expression
          spans lines)
    (these expressions) (share lines)
"#;
let mut parser = Parser::new(&text);
assert_eq!(
    parser.read::<String>().unwrap(),
    Value::into_list(
        vec!["this", "is", "a", "series", "of", "symbols"], 
        |s| Value::symbol(s).unwrap()
    )
);
assert_eq!(
    parser.read::<String>().unwrap(),
    Value::into_list(
        vec!["this", "is", "another", "sexpression"], 
        |s| Value::symbol(s).unwrap()
    )
);
assert_eq!(
    parser.read::<String>().unwrap(),
    Value::symbol("mono").unwrap()
);
assert_eq!(
    parser.read::<String>().unwrap(),
    Value::into_list(
        vec!["this", "expression", "spans", "lines"], 
        |s| Value::symbol(s).unwrap()
    )
);
assert_eq!(
    parser.read::<String>().unwrap(),
    Value::into_list(
        vec!["these", "expressions"], 
        |s| Value::symbol(s).unwrap()
    )
);
assert_eq!(
    parser.read::<String>().unwrap(),
    Value::into_list(
        vec!["share", "lines"], 
        |s| Value::symbol(s).unwrap()
    )
);

This parser must be informed of how to represent symbols when they are parsed. The Sym type parameter must implement FromStr and ToString reflexively (i.e. the output of ToString::to_string for a given value must produce the same value when used with FromStr::from_str and visa versa such that the value can be encoded and decoded the same way). If no special treatment of symbols is required, parse_basic should be used.

This will produce parsing errors when FromStr::from_str fails when being used to create symbols.

fn parse<Sym: FromStr>(self) -> ParseResult<Value<Sym>>

Parse the given expression. Consumes the parser.

If you want to pass a series of expressions, use read instead.

use atoms::{Parser, Value};
let text = "(this is a series of symbols)";
let parser = Parser::new(&text);
let parsed = parser.parse::<String>().unwrap();
assert_eq!(
    Value::into_list(
        vec!["this", "is", "a", "series", "of", "symbols"], 
        |s| Value::symbol(s).unwrap()
    ),
    parsed
);

Similar to read, the parser must be informed of the type to be used for expressing symbols.

fn parse_basic(self) -> ParseResult<StringValue>

Parse the given str storing symbols as Strings. Consumes the parser.

use atoms::{Parser, StringValue};
let text = "(this is a series of symbols)";
let parser = Parser::new(&text);
let parsed = parser.parse::<String>().unwrap();
assert_eq!(
    StringValue::into_list(
        vec!["this", "is", "a", "series", "of", "symbols"], 
        |s| StringValue::symbol(s).unwrap()
    ),
    parsed
);

In cases where no special behaviour for symbols is needed, parse_basic will resolve all symbols as Strings.