yapcol 0.3.0

Yet Another Parser Combinator Library - YAPCoL
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

use crate::{InputToken, Parser};

/// Creates a parser that makes another parser optional.
///
/// # Outcome
///
/// This combinator succeeds if:
/// - The input parser succeeds. In this case, its result is wrapped in `Some`.
/// - The argument parser fails **without consuming any input**. In this case, this combinator
///   succeeds and returns `None`.
///
/// This combinator fails if the argument parser fails **while consuming input**.
///
/// # Input consumption
///
/// This combinator consumes input if:
/// - It succeeds while returning `Some` value, and its argument parser consumes input upon success.
/// - It fails, and its argument parser consumes input upon failure.
///
/// # Look-ahead and backtracking
///
/// This combinator doesn't perform any lookahead and won't backtrack upon failure.
///
/// # Shortcut
///
/// This combinator has a shortcut version: [`Parser::maybe`].
///
/// # Arguments
///
/// - `parser`: The parser to make optional.
///
/// # Examples
///
/// ```
/// use yapcol::{Input, any, is, maybe};
///
/// let mut input = Input::new_from_chars("hello".chars(), None);
/// let ph = is('h');
/// let parser = maybe(&ph);
/// assert_eq!(parser(&mut input).unwrap(), Some('h'));
///
/// let mut input = Input::new_from_chars("world".chars(), None);
/// assert_eq!(parser(&mut input).unwrap(), None);
/// assert_eq!(any()(&mut input), Ok('w')); // Input was not consumed.
/// ```
pub fn maybe<P, IT, O>(parser: &P) -> impl Parser<IT, Option<O>>
where
	P: Parser<IT, O>,
	IT: InputToken,
{
	|input| {
		let initial_length = input.consumed_count();
		match parser(input) {
			Ok(token) => Ok(Some(token)),
			Err(_) if input.consumed_count() == initial_length => Ok(None),
			Err(e) => Err(e),
		}
	}
}

#[cfg(test)]
mod tests {
	use crate::input::Position;
	use crate::input::StringInput;
	use crate::*;

	#[test]
	fn empty() {
		let parser = is('h');
		let mut input = Input::new_from_chars("".chars(), None);
		let parser_maybe = maybe(&parser);
		assert_eq!(parser_maybe(&mut input), Ok(None));
		assert!(end_of_input()(&mut input).is_ok()); // Ensure that the input was consumed.
	}

	#[test]
	fn empty_shortcut() {
		let parser = is('h').maybe();
		let mut input = Input::new_from_chars("".chars(), None);
		assert_eq!(parser(&mut input), Ok(None));
		assert!(end_of_input()(&mut input).is_ok()); // Ensure that the input was consumed.
	}

	#[test]
	fn success() {
		let parser = is('h');
		let mut input = Input::new_from_chars("h".chars(), None);
		let parser_maybe = maybe(&parser);
		assert_eq!(parser_maybe(&mut input), Ok(Some('h')));
		assert!(end_of_input()(&mut input).is_ok()); // Ensure that the input was consumed.
	}

	#[test]
	fn success_shortcut() {
		let parser = is('h').maybe();
		let mut input = Input::new_from_chars("h".chars(), None);
		assert_eq!(parser(&mut input), Ok(Some('h')));
		assert!(end_of_input()(&mut input).is_ok()); // Ensure that the input was consumed.
	}

	#[test]
	fn fail_non_consuming() {
		let parser = is('h');
		let mut input = Input::new_from_chars("j".chars(), None);
		let parser_maybe = maybe(&parser);
		assert_eq!(parser_maybe(&mut input), Ok(None));
		assert!(end_of_input()(&mut input).is_err()); // Ensure that the input was NOT consumed.
	}

	#[test]
	fn fail_consuming() {
		let parser = |input: &mut StringInput| match any()(input) {
			Ok(token) => {
				if token == 'h' {
					Ok(1)
				} else {
					Err(Error::UnexpectedToken(None, Position::new(1, 1), None))
				}
			}
			Err(e) => Err(e),
		};
		let mut input = Input::new_from_chars("j".chars(), None);
		let parser_maybe = maybe(&parser);
		assert_eq!(
			parser_maybe(&mut input),
			Err(Error::UnexpectedToken(None, Position::new(1, 1), None))
		);
		assert!(end_of_input()(&mut input).is_ok()); // Ensure that the input was consumed.
	}
}