parcours 0.3.0

Parser Combinators for Unique Results
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

//! Parsers for [`&str`] input.

use crate::{from_fn, Combinator, Parser};

/// Collect longest prefix of a [`&str`] whose bytes satisfy the given condition.
pub fn take_while<S, F: FnMut(&u8, &mut S) -> bool>(f: F) -> TakeWhile<F> {
    TakeWhile(f)
}

/// A parser returned by [`take_while`].
#[derive(Clone)]
pub struct TakeWhile<F>(F);

impl<'a, S, F: FnMut(&u8, &mut S) -> bool> Parser<&'a str, S> for TakeWhile<F> {
    type O = &'a str;

    fn parse(mut self, input: &'a str, state: &mut S) -> Option<(Self::O, &'a str)> {
        let len = input.bytes().take_while(|c| self.0(c, state)).count();
        Some((&input[..len], &input[len..]))
    }
}

type TakeWhile1<F> = crate::combinator::Filter<TakeWhile<F>, fn(&&str) -> bool>;

/// Collect longest *non-empty* prefix of a [`&str`] whose bytes satisfy the given condition.
///
/// If the prefix is empty, this returns no output, unlike [`take_while`].
pub fn take_while1<S, F: FnMut(&u8, &mut S) -> bool>(f: F) -> TakeWhile1<F> {
    take_while(f).filter(|n| !n.is_empty())
}

/// If the input starts with the given string, return `()` and remove the string from the input.
pub fn matches<'a, 'i: 'a, S>(x: &'a str) -> impl Parser<&'i str, S, O = ()> + Clone + 'a {
    from_fn(move |input: &str, _| Some(((), input.strip_prefix(x)?)))
}

/// Subtract one string slice from another.
///
/// Case 1 (reading from the left; most frequent):
///
/// ~~~ text
///        large
/// -------------------
///             small
///        ------------===
/// \-----/
///    | what we want
/// ~~~
///
/// Case 2 (reading from the right):
///
/// ~~~ text
///           large
///    -------------------
///      small
/// ===------------
///                \-----/
///                   | what we want
/// ~~~
///
/// Here, the parts indicated by `===` are anomalies that are not expected to occur,
/// but which are supported nonetheless by this function.
///
fn minus<'a>(large: &'a str, small: &'a str) -> Option<&'a str> {
    let small_start = small.as_ptr() as usize;
    let large_start = large.as_ptr() as usize;
    let small_end = small_start.wrapping_add(small.len());
    let large_end = large_start.wrapping_add(large.len());

    if small_start >= large_start && small_end >= large_end {
        Some(&large[..small_start.wrapping_sub(large_start)])
    } else if small_start <= large_start && small_end <= large_end {
        Some(&large[small_end.wrapping_sub(large_start)..])
    } else {
        None
    }
}

/// If the beginning of `inner` lies inside `outer`, return its offset.
///
/// Example:
///
/// ~~~
/// let outer = "Hello world!";
/// assert_eq!(parcours::str::offset(outer, &outer[6..]), Some(6));
/// // here, `inner` exceeds `outer`, but it's okay, because
/// // the start of `inner` still lies within `outer`
/// assert_eq!(parcours::str::offset(&outer[..7], &outer[6..]), Some(6));
/// assert_eq!(parcours::str::offset(outer, "something else"), None);
/// ~~~
pub fn offset<'a>(outer: &'a str, inner: &'a str) -> Option<usize> {
    let outer_ptr = outer.as_ptr() as usize;
    let inner_ptr = inner.as_ptr() as usize;
    if inner_ptr < outer_ptr || inner_ptr > outer_ptr.wrapping_add(outer.len()) {
        None
    } else {
        Some(inner_ptr.wrapping_sub(outer_ptr))
    }
}

/// Run the given parser and combine its output with the slice of the input string it consumed.
///
/// You can use this to find out via [`offset`] the span of the parsed element.
///
/// Example:
///
/// ~~~
/// # use parcours::str::{take_while, with_consumed};
/// # use parcours::{Parser, Combinator};
/// let digits = take_while(|c, _| c.is_ascii_digit());
/// let alphas = take_while(|c, _| c.is_ascii_alphabetic());
/// let parser = with_consumed(digits.then(alphas));
/// let input = "123abcäöü";
/// let result = ("123", "abc");
/// let consumed = "123abc";
/// let rest = "äöü";
/// assert_eq!(parser.parse(input, &mut ()), Some(((result, consumed), rest)));
///
/// ~~~
pub fn with_consumed<'a, S, P: Parser<&'a str, S>>(p: P) -> WithConsumed<P> {
    WithConsumed(p)
}

/// A parser returned by [`with_consumed`].
#[derive(Clone)]
pub struct WithConsumed<P>(P);

impl<'a, S, P: Parser<&'a str, S>> Parser<&'a str, S> for WithConsumed<P> {
    type O = (P::O, &'a str);

    fn parse(self, input: &'a str, state: &mut S) -> Option<(Self::O, &'a str)> {
        let (y, rest) = self.0.parse(input, state)?;
        Some(((y, minus(input, rest)?), rest))
    }
}