From 3330ceb7b848bdeae00357efab0af0e9b646d60a Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Sat, 30 Jan 2016 18:03:11 -0800 Subject: [PATCH 1/2] Docs: try to explain error messages (#368) --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index c7f0043..47730ca 100644 --- a/README.md +++ b/README.md @@ -438,6 +438,47 @@ Try to match the first expression, if it does not succeed, try the second one, etc. Return the match result of the first successfully matched expression. If no expression matches, consider the match failed. +Error Messages +-------------- + +As described above, you can annotate your grammar rules with human-readable +names that will be used in error messages. For example, this production: + + integer "integer" + = digits:[0-9]+ + +will produce an error message like: + +> Expected integer but "a" found. + +when parsing a non-number, referencing the human-readable name "integer." +Without the human-readable name, PEG.js instead uses a description of the +character class that failed to match: + +> Expected [0-9] but "a" found. + +Aside from the text content of messages, human-readable names also have a +subtler effect on *where* errors are reported. PEG.js prefers shorter matches +for named rules and longer matches for unnamed rules. For example, for this +rule matching a comma-separated list of integers: + + seq + = integer ("," integer)* + +an input like `1,2,a` produces this error message: + +> Expected integer but "a" found. + +But if we add a human-readable name to the `seq` production: + + seq "list of numbers" + = integer ("," integer)* + +then PEG.js prefers an error message that implies a smaller attempted parse +tree: + +> Expected end of input but "," found. + Compatibility ------------- From ceebc8cda1a653465a7146e09abe2f8ac1addb8d Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Sun, 31 Jan 2016 12:19:35 -0800 Subject: [PATCH 2/2] Better error position explanation Based on @Mingun's help. --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 47730ca..4f2ebea 100644 --- a/README.md +++ b/README.md @@ -458,9 +458,12 @@ character class that failed to match: > Expected [0-9] but "a" found. Aside from the text content of messages, human-readable names also have a -subtler effect on *where* errors are reported. PEG.js prefers shorter matches -for named rules and longer matches for unnamed rules. For example, for this -rule matching a comma-separated list of integers: +subtler effect on *where* errors are reported. PEG.js prefers to match +named rules completely or not at all, but not partially. Unnamed rules, +on the other hand, can produce an error in the middle of their +subexpressions. + +For example, for this rule matching a comma-separated list of integers: seq = integer ("," integer)*