Move to new return type

Author: kw217

README.md

@@ -30,11 +30,11 @@ peg::parser!{
 }
 
 pub fn main() {
-    assert_eq!(list_parser::list("[1,1,2,3,5,8]"), Ok(vec![1, 1, 2, 3, 5, 8]));
+    assert_eq!(list_parser::list("[1,1,2,3,5,8]").into_result(), Ok(vec![1, 1, 2, 3, 5, 8]));
 }
 ```
 
-[See the tests for more examples](./tests/run-pass/)  
+[See the tests for more examples](./tests/run-pass/)
 [Grammar rule syntax reference in rustdoc](https://docs.rs/peg)
 
 ## Comparison with similar parser generators
@@ -60,6 +60,12 @@ pub fn main() {
 [annotate-snippets]: https://crates.io/crates/annotate-snippets
 [codespan-reporting]: https://crates.io/crates/codespan-reporting
 [codemap-diagnostic]: https://crates.io/crates/codemap-diagnostic
+
+## Upgrade guide
+
+The rule return type has changed between 0.8 to 0.9.
+To upgrade, add a call to `.into_result()` to convert the new rule return type
+to a simple `Result`.
 ## Development
 
 The `rust-peg` grammar is written in `rust-peg`: `peg-macros/grammar.rustpeg`. To avoid the circular dependency, a precompiled grammar is checked in as `peg-macros/grammar.rs`. To regenerate this, run the `./bootstrap.sh` script.

peg-macros/bin.rs

@@ -42,7 +42,7 @@ fn main() {
 
     let source_tokens = source.parse().expect("Error tokenizing input");
     let input_tokens = tokens::FlatTokenStream::new(source_tokens);
-    let grammar = match grammar::peg::peg_grammar(&input_tokens) {
+    let grammar = match grammar::peg::peg_grammar(&input_tokens).into_result() {
         Ok(g) => g,
         Err(err) => {
             eprintln!("Failed to parse grammar: expected {}", err.expected);

peg-macros/lib.rs

@@ -20,7 +20,7 @@ mod translate;
 #[proc_macro]
 pub fn parser(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let tokens = tokens::FlatTokenStream::new(input.into());
-    let grammar = match grammar::peg::peg_grammar(&tokens) {
+    let grammar = match grammar::peg::peg_grammar(&tokens).into_result() {
         Ok(g) => g,
         Err(err) => {
             let msg = format!("expected {}", err.expected);

peg-macros/translate.rs

@@ -308,7 +308,7 @@ fn compile_rule(context: &Context, rule: &Rule) -> TokenStream {
 }
 
 /// Compile a rule into the parsing function which will be exported.
-/// Returns `Result<T, ParseError>`.
+/// Returns `ParseResults<T, L>`.
 fn compile_rule_export(context: &Context, rule: &Rule) -> TokenStream {
     let span = rule.span.resolved_at(Span::mixed_site());
 
@@ -339,15 +339,15 @@ fn compile_rule_export(context: &Context, rule: &Rule) -> TokenStream {
 
     quote_spanned! { span =>
         #doc
-        #visibility fn #name<'input #(, #grammar_lifetime_params)* #(, #ty_params)*>(__input: #input_ty #extra_args_def #(, #rule_params)*) -> ::std::result::Result<#ret_ty, ::peg::error::ParseError<PositionRepr<#(#grammar_lifetime_params),*>>> {
+        #visibility fn #name<'input #(, #grammar_lifetime_params)* #(, #ty_params)*>(__input: #input_ty #extra_args_def #(, #rule_params)*) -> ::peg::ParseResults<#ret_ty, PositionRepr<#(#grammar_lifetime_params),*>> {
             #![allow(non_snake_case, unused)]
 
             let mut __err_state = ::peg::error::ErrorState::new(::peg::Parse::start(__input));
             let mut __state = ParseState::new();
             match #parse_fn(__input, &mut __state, &mut __err_state, ::peg::Parse::start(__input) #extra_args_call #(, #rule_params_call)*) {
                 ::peg::RuleResult::Matched(__pos, __value) => {
                     if #eof_check {
-                        return Ok(__value)
+                        return __err_state.into_matched(__value, __input)
                     } else {
                         __err_state.mark_failure(__pos, "EOF");
                     }
@@ -356,7 +356,7 @@ fn compile_rule_export(context: &Context, rule: &Rule) -> TokenStream {
             }
 
             __state = ParseState::new();
-            __err_state.reparse_for_error();
+            __err_state.reparse_for_failure();
 
             match #parse_fn(__input, &mut __state, &mut __err_state, ::peg::Parse::start(__input) #extra_args_call #(, #rule_params_call)*) {
                 ::peg::RuleResult::Matched(__pos, __value) => {
@@ -369,7 +369,7 @@ fn compile_rule_export(context: &Context, rule: &Rule) -> TokenStream {
                 _ => ()
             }
 
-            Err(__err_state.into_parse_error(__input))
+            __err_state.into_failure(__input)
         }
     }
 }
@@ -431,7 +431,7 @@ fn compile_expr_continuation(context: &Context, e: &SpannedExpr, result_name: Op
 fn compile_literal_expr(s: &Literal, continuation: TokenStream) -> TokenStream {
     let span = s.span().resolved_at(Span::mixed_site());
     let escaped_str = s.to_string();
-    quote_spanned! { span => 
+    quote_spanned! { span =>
             match ::peg::ParseLiteral::parse_string_literal(__input, __pos, #s) {
             ::peg::RuleResult::Matched(__pos, __val) => { #continuation }
             ::peg::RuleResult::Failed => { __err_state.mark_failure(__pos, #escaped_str); ::peg::RuleResult::Failed }
@@ -456,7 +456,7 @@ fn compile_pattern_expr(pattern_group: &Group, result_name: Ident, success_res:
                 #pattern => #in_set,
                 _ => #not_in_set,
             }
-            ::peg::RuleResult::Failed => { __err_state.mark_failure(__pos, #pat_str); ::peg::RuleResult::Failed }
+            ::peg::RuleResult::Failed => { __err_state.mark_failure(__pos, #pat_str); ::peg::RuleResult::Failed },
         }
     }
 }
@@ -683,7 +683,7 @@ fn compile_expr(context: &Context, e: &SpannedExpr, result_used: bool) -> TokenS
                 __err_state.suppress_fail -= 1;
                 match __assert_res {
                     ::peg::RuleResult::Failed => ::peg::RuleResult::Matched(__pos, ()),
-                    ::peg::RuleResult::Matched(..) => ::peg::RuleResult::Failed,
+                    ::peg::RuleResult::Matched(..) => __err_state.mark_failure(__pos, "mismatch"),
                 }
             }}
         }

peg-runtime/error.rs

@@ -1,6 +1,6 @@
 //! Parse error reporting
 
-use crate::{Parse, RuleResult};
+use crate::{Parse, RuleResult, ParseResults, ParseResult};
 use std::collections::HashSet;
 use std::fmt::{self, Debug, Display};
 
@@ -15,6 +15,13 @@ impl ExpectedSet {
     pub fn tokens<'a>(&'a self) -> impl Iterator<Item = &'static str> + 'a {
         self.expected.iter().map(|x| *x)
     }
+
+    /// Construct a new singleton set.
+    pub(crate) fn singleton(error: &'static str) -> Self {
+        let mut expected = HashSet::new();
+        expected.insert(error);
+        ExpectedSet { expected }
+    }
 }
 
 impl Display for ExpectedSet {
@@ -65,6 +72,7 @@ impl<L: Display + Debug> ::std::error::Error for ParseError<L> {
 }
 
 #[doc(hidden)]
+#[derive(Debug)]
 pub struct ErrorState {
     /// Furthest failure we've hit so far.
     pub max_err_pos: usize,
@@ -75,9 +83,9 @@ pub struct ErrorState {
 
     /// Are we reparsing after a failure? If so, compute and store expected set of all alternative expectations
     /// when we are at offset `max_err_pos`.
-    pub reparsing_on_error: bool,
+    pub reparsing_on_failure: bool,
 
-    /// The set of tokens we expected to find when we hit the failure. Updated when `reparsing_on_error`.
+    /// The set of tokens we expected to find when we hit the failure. Updated when `reparsing_on_failure`.
     pub expected: ExpectedSet,
 }
 
@@ -86,21 +94,21 @@ impl ErrorState {
         ErrorState {
             max_err_pos: initial_pos,
             suppress_fail: 0,
-            reparsing_on_error: false,
+            reparsing_on_failure: false,
             expected: ExpectedSet {
                 expected: HashSet::new(),
             },
         }
     }
 
     /// Set up for reparsing to record the details of the furthest failure.
-    pub fn reparse_for_error(&mut self) {
+    pub fn reparse_for_failure(&mut self) {
         self.suppress_fail = 0;
-        self.reparsing_on_error = true;
+        self.reparsing_on_failure = true;
     }
 
     #[inline(never)]
-    pub fn mark_failure_slow_path(&mut self, pos: usize, expected: &'static str) {
+    fn mark_failure_slow_path(&mut self, pos: usize, expected: &'static str) {
         if pos == self.max_err_pos {
             self.expected.expected.insert(expected);
         }
@@ -110,7 +118,7 @@ impl ErrorState {
     #[inline(always)]
     pub fn mark_failure(&mut self, pos: usize, expected: &'static str) -> RuleResult<()> {
         if self.suppress_fail == 0 {
-            if self.reparsing_on_error {
+            if self.reparsing_on_failure {
                 self.mark_failure_slow_path(pos, expected);
             } else if pos > self.max_err_pos {
                 self.max_err_pos = pos;
@@ -119,10 +127,25 @@ impl ErrorState {
         RuleResult::Failed
     }
 
-    pub fn into_parse_error<I: Parse + ?Sized>(self, input: &I) -> ParseError<I::PositionRepr> {
-        ParseError {
-            location: Parse::position_repr(input, self.max_err_pos.into()),
-            expected: self.expected,
+        }
+    }
+
+    /// Build `Matched` parse result.
+    pub fn into_matched<T, I: Parse + ?Sized>(self, v: T, input: &I) -> ParseResults<T, I::PositionRepr> {
+        ParseResults {
+            result: ParseResult::Matched(v),
+            errors: errors_positioned_in(self.errors, input),
+        }
+    }
+
+    /// Build `Failed` parse result.
+    pub fn into_failure<T, I: Parse + ?Sized>(self, input: &I) -> ParseResults<T, I::PositionRepr> {
+        ParseResults {
+            result: ParseResult::Failed(ParseError {
+                expected: self.expected,
+                location: input.position_repr(self.max_err_pos)
+            }),
+            errors: errors_positioned_in(self.errors, input),
         }
     }
 }

peg-runtime/lib.rs

@@ -4,10 +4,64 @@ pub mod error;
 mod slice;
 pub mod str;
 
+
+/// The public API of a parser: the result of the parse.
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct ParseResults<T, L> {
+    /// The result of the parse.
+    pub result: ParseResult<T, L>,
+}
+
+impl<T: Display, L: Display> Display for ParseResults<T, L> {
+    fn fmt(&self, fmt: &mut ::std::fmt::Formatter) -> Result<(), ::std::fmt::Error> {
+        write!(fmt, "{}", self.result)
+    }
+}
+
+impl<T, L> ParseResults<T, L> {
+    /// Convert into a simple `Result`.
+    pub fn into_result(self) -> Result<T, error::ParseError<L>> {
+        match self.result {
+            ParseResult::Matched(v) => Ok(v),
+            ParseResult::Failed(e) => Err(e),
+        }
+    }
+}
+
+impl<T, L: Display> ParseResults<T, L> {
+    /// Return the contained match, or panic on failure.
+    pub fn unwrap(self) -> T {
+        match self.result {
+            ParseResult::Matched(v) => v,
+            ParseResult::Failed(e) => panic!("parse failed: {}", e),
+        }
+    }
+}
+
+/// The public result of a parser.
+/// A parse may succeed or fail.
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub enum ParseResult<T, L> {
+    /// Success
+    Matched(T),
+
+    /// Failure
+    Failed(error::ParseError<L>),
+}
+
+impl<T: Display, L: Display> Display for ParseResult<T, L> {
+    fn fmt(&self, fmt: &mut ::std::fmt::Formatter) -> Result<(), ::std::fmt::Error> {
+        match self {
+            ParseResult::Matched(v) => write!(fmt, "{}", v),
+            ParseResult::Failed(e) => write!(fmt, "{}", e),
+        }
+    }
+}
+
 /// The result type used internally in the parser.
 ///
 /// You'll only need this if implementing the `Parse*` traits for a custom input
-/// type. The public API of a parser adapts errors to `std::result::Result`.
+/// type.
 #[derive(Clone, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
 pub enum RuleResult<T> {
     /// Success, with final location

src/lib.rs

@@ -33,9 +33,12 @@
 //!
 //! The macro expands to a Rust `mod` containing a function for each rule marked
 //! `pub` in the grammar. To parse an input sequence, call one of these
-//! functions. The call returns a `Result<T, ParseError>` carrying either the
-//! successfully parsed value returned by the rule, or a `ParseError` containing
-//! the failure position and the set of tokens expected there.
+//! functions. The call returns a `ParseResults<T,L>`, which carries either the
+//! successfully parsed value or the furthest failure.
+//!
+//! * Use `unwrap()` to obtain the successful `T` or panic.
+//! * Use `into_result()` to obtain a `Result<T, _>`.
+//! * For full details, match on the `result` field.
 //!
 //! ## Example
 //!
@@ -53,7 +56,7 @@
 //! }
 //!
 //! pub fn main() {
-//!     assert_eq!(list_parser::list("[1,1,2,3,5,8]"), Ok(vec![1, 1, 2, 3, 5, 8]));
+//!     assert_eq!(list_parser::list("[1,1,2,3,5,8]").into_result(), Ok(vec![1, 1, 2, 3, 5, 8]));
 //! }
 //! ```
 //!

tests/run-pass/arithmetic.rs

@@ -22,12 +22,12 @@ peg::parser!( grammar arithmetic() for str {
 });
 
 fn main() {
-    assert_eq!(expression("1+1"), Ok(2));
-    assert_eq!(expression("5*5"), Ok(25));
-    assert_eq!(expression("222+3333"), Ok(3555));
-    assert_eq!(expression("2+3*4"), Ok(14));
-    assert_eq!(expression("(2+2)*3"), Ok(12));
-    assert!(expression("(22+)+1").is_err());
-    assert!(expression("1++1").is_err());
-    assert!(expression("3)+1").is_err());
+    assert_eq!(expression("1+1").into_result(), Ok(2));
+    assert_eq!(expression("5*5").into_result(), Ok(25));
+    assert_eq!(expression("222+3333").into_result(), Ok(3555));
+    assert_eq!(expression("2+3*4").into_result(), Ok(14));
+    assert_eq!(expression("(2+2)*3").into_result(), Ok(12));
+    assert!(expression("(22+)+1").into_result().is_err());
+    assert!(expression("1++1").into_result().is_err());
+    assert!(expression("3)+1").into_result().is_err());
 }

tests/run-pass/arithmetic_ast.rs

@@ -35,29 +35,29 @@ grammar arithmetic() for str {
 }}
 
 fn main() {
-    assert_eq!(arithmetic::expression("1+1"), Ok(Expression::Sum(
+    assert_eq!(arithmetic::expression("1+1").into_result(), Ok(Expression::Sum(
         Box::new(Expression::Number(1)),
         Box::new(Expression::Number(1)))
     ));
-    assert_eq!(arithmetic::expression("5*5"), Ok(Expression::Product(
+    assert_eq!(arithmetic::expression("5*5").into_result(), Ok(Expression::Product(
         Box::new(Expression::Number(5)),
         Box::new(Expression::Number(5)))
     ));
-    assert_eq!(arithmetic::expression("2+3*4"), Ok(Expression::Sum(
+    assert_eq!(arithmetic::expression("2+3*4").into_result(), Ok(Expression::Sum(
         Box::new(Expression::Number(2)),
         Box::new(Expression::Product(
             Box::new(Expression::Number(3)),
             Box::new(Expression::Number(4))
         )),
     )));
-    assert_eq!(arithmetic::expression("(2+3) * 4"), Ok(Expression::Product(
+    assert_eq!(arithmetic::expression("(2+3) * 4").into_result(), Ok(Expression::Product(
         Box::new(Expression::Sum(
             Box::new(Expression::Number(2)),
             Box::new(Expression::Number(3)),
         )),
         Box::new(Expression::Number(4))
     )));
-    assert!(arithmetic::expression("(22+)+1").is_err());
-    assert!(arithmetic::expression("1++1").is_err());
-    assert!(arithmetic::expression("3)+1").is_err());
+    assert!(arithmetic::expression("(22+)+1").into_result().is_err());
+    assert!(arithmetic::expression("1++1").into_result().is_err());
+    assert!(arithmetic::expression("3)+1").into_result().is_err());
 }

tests/run-pass/arithmetic_infix.rs

@@ -22,10 +22,10 @@ peg::parser!( grammar arithmetic() for str {
 });
 
 fn main() {
-    assert_eq!(arithmetic::calculate("3+3*3+3"), Ok(15));
-    assert_eq!(arithmetic::calculate("2+2^2^2^2/2+2"), Ok(32772));
-    assert_eq!(arithmetic::calculate("1024/2/2/2+1"), Ok(129));
-    assert_eq!(arithmetic::calculate("1024/(1+1)/2/2+1"), Ok(129));
-    assert_eq!(arithmetic::calculate("-1-2*-2"), Ok(3));
-    assert_eq!(arithmetic::calculate("1+3!+1"), Ok(8));
+    assert_eq!(arithmetic::calculate("3+3*3+3").into_result(), Ok(15));
+    assert_eq!(arithmetic::calculate("2+2^2^2^2/2+2").into_result(), Ok(32772));
+    assert_eq!(arithmetic::calculate("1024/2/2/2+1").into_result(), Ok(129));
+    assert_eq!(arithmetic::calculate("1024/(1+1)/2/2+1").into_result(), Ok(129));
+    assert_eq!(arithmetic::calculate("-1-2*-2").into_result(), Ok(3));
+    assert_eq!(arithmetic::calculate("1+3!+1").into_result(), Ok(8));
 }