Struct pest::inputs::Position

pub struct Position<I: Input> { /* fields omitted */ }

A struct containing a position that is tied to an Input which provides useful methods to manually parse it. This leads to an API largely based on the standard Result.

Methods

impl<I: Input> Position<I>

fn from_start(input: Rc<I>) -> Position<I>

Creates starting Position from an Rc<Input>.

Examples

let input = Rc::new(StringInput::new("".to_owned()));

Position::from_start(input);

fn pos(&self) -> usize

Returns the current position as a usize.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(start.pos(), 0);
assert_eq!(start.match_string("ab").unwrap().pos(), 2);

fn span(self, other: Position<I>) -> Span<I>

Creates a Span from two Positions.

Panics

Panics when the positions come from different inputs.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);
let end = start.clone().match_string("ab").unwrap();
let span = start.span(end);

assert_eq!(span.start(), 0);
assert_eq!(span.end(), 2);

fn line_col(&self) -> (usize, usize)

Returns the line - and column number pair of the current Position.

Examples

let input = Rc::new(StringInput::new("\na".to_owned()));
let start = Position::from_start(input);
let pos = start.match_string("\na").unwrap();

assert_eq!(pos.line_col(), (2, 2));

fn line_of(&self) -> &str

Returns the actual line of the current Position.

Examples

let input = Rc::new(StringInput::new("\na".to_owned()));
let start = Position::from_start(input);
let pos = start.match_string("\na").unwrap();

assert_eq!(pos.line_of(), "a");

fn at_start(self) -> Result<Position<I>, Position<I>>

Returns Ok with the current Position if it is at the start of its Input or Err of the same Position otherwise.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);
let end = start.clone().match_string("ab").unwrap();

assert_eq!(start.clone().at_start(), Ok(start));
assert_eq!(end.clone().at_start(), Err(end));

fn at_end(self) -> Result<Position<I>, Position<I>>

Returns Ok with the current Position if it is at the end of its Input or Err of the same Position otherwise.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);
let end = start.clone().match_string("ab").unwrap();

assert_eq!(start.clone().at_end(), Err(start));
assert_eq!(end.clone().at_end(), Ok(end));

fn skip(self, n: usize) -> Result<Position<I>, Position<I>>

Skips n chars from the Position and returns Ok with the new Position if the skip was possible or Err with the current Position otherwise.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(start.clone().skip(2).unwrap().pos(), 2);
assert_eq!(start.clone().skip(3), Err(start));

fn match_string(self, string: &str) -> Result<Position<I>, Position<I>>

Matches string from the Position and returns Ok with the new Position if a match was made or Err with the current Position otherwise.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(start.clone().match_string("ab").unwrap().pos(), 2);
assert_eq!(start.clone().match_string("ac"), Err(start));

fn match_insensitive(self, string: &str) -> Result<Position<I>, Position<I>>

Case-insensitively matches string from the Position and returns Ok with the new Position if a match was made or Err with the current Position otherwise.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(start.clone().match_insensitive("AB").unwrap().pos(), 2);
assert_eq!(start.clone().match_insensitive("AC"), Err(start));

fn match_range(self, range: Range<char>) -> Result<Position<I>, Position<I>>

Matches char range from the Position and returns Ok with the new Position if a match was made or Err with the current Position otherwise.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(start.clone().match_range('a'..'z').unwrap().pos(), 1);
assert_eq!(start.clone().match_range('A'..'Z'), Err(start));

fn sequence<F>(self, f: F) -> Result<Position<I>, Position<I>> where
    F: FnOnce(Position<I>) -> Result<Position<I>, Position<I>>, 

Starts a sequence of transformations provided by f from the Position. It returns the same Result returned by f in the case of an Ok or Err with the current Position otherwise.

This method is useful to parse sequences that only match together which usually come in the form of chained Results with Result::and_then. Such chains should always be wrapped up in ParserState::sequence if they can create Tokens before being wrapped in Position::sequence.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(
    start.clone().sequence(|p| {
        p.match_string("a").and_then(|p| {
            p.match_string("b")
        })
    }).unwrap().pos(),
    2
);
assert_eq!(
    start.clone().sequence(|p| {
        p.match_string("a").and_then(|p| {
            p.match_string("c")
        })
    }),
    Err(start)
);

fn lookahead<F>(
    self,
    is_positive: bool,
    f: F
) -> Result<Position<I>, Position<I>> where
    F: FnOnce(Position<I>) -> Result<Position<I>, Position<I>>, 

Starts a lookahead transformation provided by f from the Position. It returns Ok with the current position if f also returns an Ok or Err with the current Position otherwise.

If is_positive is false, it swaps the Ok and Err together, negating the Result. It should always be wrapped up in ParserState::lookahead if it can create Tokens before being wrapped in Position::lookahead.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(
    start.clone().lookahead(true, |p| {
        p.match_string("ab")
    }),
    Ok(start.clone())
);
assert_eq!(
    start.clone().lookahead(true, |p| {
        p.match_string("ac")
    }),
    Err(start.clone())
);
assert_eq!(
    start.clone().lookahead(false, |p| {
        p.match_string("ac")
    }),
    Ok(start)
);

fn optional<F>(self, f: F) -> Result<Position<I>, Position<I>> where
    F: FnOnce(Position<I>) -> Result<Position<I>, Position<I>>, 

Optionally applies the transformation provided by f from the Position. It returns Ok with the Position returned by f regardless of the Result.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(
    start.clone().optional(|p| {
        p.match_string("a").and_then(|p| {
            p.match_string("b")
        })
    }).unwrap().pos(),
    2
);
assert_eq!(
    start.clone().sequence(|p| {
        p.match_string("a").and_then(|p| {
            p.match_string("c")
        })
    }),
    Err(start)
);

fn repeat<F>(self, f: F) -> Result<Position<I>, Position<I>> where
    F: FnMut(Position<I>) -> Result<Position<I>, Position<I>>, 

Repeatedly applies the transformation provided by f from the Position. It returns Ok with the first Position returned by f which is wrapped up in an Err.

Examples

let input = Rc::new(StringInput::new("ab".to_owned()));
let start = Position::from_start(input);

assert_eq!(
    start.clone().repeat(|p| {
        p.match_string("a")
    }).unwrap().pos(),
    1
);
assert_eq!(
    start.repeat(|p| {
        p.match_string("b")
    }).unwrap().pos(),
    0
);

Trait Implementations

impl<I: Input> Debug for Position<I>

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

Formats the value using the given formatter.

impl<I: Input> Clone for Position<I>

fn clone(&self) -> Position<I>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<I: Input> PartialEq for Position<I>

fn eq(&self, other: &Position<I>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<I: Input> Eq for Position<I>

impl<I: Input> PartialOrd for Position<I>

fn partial_cmp(&self, other: &Position<I>) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl<I: Input> Ord for Position<I>

fn cmp(&self, other: &Position<I>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

🔬 This is a nightly-only experimental API. (ord_max_min)

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

🔬 This is a nightly-only experimental API. (ord_max_min)

Compares and returns the minimum of two values.

impl<I: Input> Hash for Position<I>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].