Struct chomp::Input

#[must_use]
pub struct Input<'a, I: 'a>(_, _);

Linear type containing the parser state, this type is threaded though bind and is also the initial type passed to a parser.

Coupled with the ParseResult type it forms the parser monad:

Fn*(Input<I>, ...) -> ParseResult<I, T, E>;

where Fn* is the appropriate closure/function trait, I the input token type (usually something like u8), ... additional parameters to the parser, T the carried type and E the potential error type.

Methods

impl<'a, I> Input<'a, I>

fn new(b: &'a [I]) -> Self

Creates a new Input to start parsing with.

Deprecated

Use parse_only or buffer::SliceStream to parse a slice instead. For any advanced usage create an Input using primitives::input::new.

Note

This should only be used for simple examples, for anything more advanced look at the buffer module.

fn ret<T, E = ()>(self, t: T) -> ParseResult<'a, I, T, E>

Returns t as a success value in the parsing context.

Equivalent to Haskell's return function in the Monad typeclass.

Example

use chomp::parse_only;

let r = parse_only(|i|
    // Annotate the error type
    i.ret::<_, ()>("Wohoo, success!"),
    b"some input");

assert_eq!(r, Ok("Wohoo, success!"));

fn err<T, E>(self, e: E) -> ParseResult<'a, I, T, E>

Returns e as an error value in the parsing context.

A more general version of Haskell's fail function in the Monad typeclass.

Example

use chomp::{ParseError, parse_only};

let r = parse_only(|i|
    // Annotate the value type
    i.err::<(), _>("Something went wrong"),
    b"some input");

assert_eq!(r, Err(ParseError::Error(b"some input", "Something went wrong")));

fn incomplete<T, E>(self, n: usize) -> ParseResult<'a, I, T, E>

Notifies that a parser has reached the end of the currently supplied slice but requires more data.

Primitive

Only used by fundamental parsers and combinators.

fn from_result<T, E>(self, r: Result<T, E>) -> ParseResult<'a, I, T, E>

Converts a Result into a ParseResult, preserving parser state.

To convert an Option into a ParseResult it is recommended to use Option::ok_or or Option::ok_or_else in combination with this method.

Examples

use chomp::{ParseError, parse_only};

let r = parse_only(|i| i.from_result::<_, ()>(Ok("foo")), b"test");

assert_eq!(r, Ok("foo"));

let r = parse_only(|i| i.from_result::<(), _>(Err("error message")), b"test");

assert_eq!(r, Err(ParseError::Error(&b"test"[..], "error message")));

Trait Implementations

impl<'a, I: Hash + 'a> Hash for Input<'a, I>

fn hash<__HI: Hasher>(&self, __arg_0: &mut __HI)

Feeds this value into the state given, updating the hasher as necessary.

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher

Feeds a slice of this type into the state provided.

impl<'a, I: PartialOrd + 'a> PartialOrd for Input<'a, I>

fn partial_cmp(&self, __arg_0: &Input<'a, I>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, __arg_0: &Input<'a, I>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, __arg_0: &Input<'a, I>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, __arg_0: &Input<'a, I>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, __arg_0: &Input<'a, I>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, I: Ord + 'a> Ord for Input<'a, I>

fn cmp(&self, __arg_0: &Input<'a, I>) -> Ordering

This method returns an Ordering between self and other.

impl<'a, I: PartialEq + 'a> PartialEq for Input<'a, I>

fn eq(&self, __arg_0: &Input<'a, I>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &Input<'a, I>) -> bool

This method tests for !=.

impl<'a, I: Eq + 'a> Eq for Input<'a, I>

impl<'a, I: Debug + 'a> Debug for Input<'a, I>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a, I: 'a> InputClone for Input<'a, I>

Trait limiting the use of Clone for Input.

Primitive

Only used by fundamental parsers and combinators.

Motivation

The Input type is supposed to be an approximation of a linear type when observed in the monadic parser context. This means that it should not be possible to duplicate or accidentally throw it away as well as restrict when and where an Input can be constructed. Not implementing Clone or Copy solves the first issue.

However, cloning an Input is necessary for backtracking and also allows for slightly more efficient iteration in combinators. This trait allows us to enable cloning selectively.

fn clone(&self) -> Self

Creates a clone of the instance.

impl<'a, I: 'a> InputBuffer<'a> for Input<'a, I>

Trait exposing the buffer of Input.

Primitive

Only used by fundamental parsers and combinators.

Motivation

The Input type is supposed to be an approximation of a linear type when observed in the monadic parser context. This means that it should not be possible to duplicate or accidentally throw it away as well as restrict when and where an Input can be constructed. Not exposing the constructor (to allow destructuring) as well as using #[must_use] solves the second issue.

But to be able to parse data the contents of the Input type must be exposed in at least one point, so that data can be examined, and this trait that makes it possible.

Example

use chomp::take;
use chomp::primitives::input;
use chomp::primitives::{InputBuffer, IntoInner, State};

let i = input::new(input::END_OF_INPUT, b"Testing");

assert_eq!(i.buffer(), b"Testing");
assert_eq!(i.is_last_slice(), true);

let b = i.buffer();
let j = i.replace(&b[..4]);

let r = take(j, 4);

assert_eq!(r.into_inner(), State::Data(input::new(input::END_OF_INPUT, b""), &b"Test"[..]));

type Item = I

fn buffer(&self) -> &'a [Self::Item]

Reveals the internal buffer containig the remainder of the input.

fn replace(self, b: &'a [Self::Item]) -> Self

Modifies the inner data without leaving the Input context.

fn is_last_slice(&self) -> bool

Returns true if this is the last available slice of the input.