aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergio Queiroz <sqmedeiros@gmail.com>2017-01-03 11:06:56 -0300
committerSergio Queiroz <sqmedeiros@gmail.com>2017-01-03 11:06:56 -0300
commite0feb1b3a659411d53b231d24929c4b7b4d92431 (patch)
treee6d1624f75d68d53f8a7c91f198d6854993f3f4a
parent92029acf2072fbbd29271c68e601832f9a7c832d (diff)
downloadlpeglabel-e0feb1b3a659411d53b231d24929c4b7b4d92431.tar.gz
lpeglabel-e0feb1b3a659411d53b231d24929c4b7b4d92431.tar.bz2
lpeglabel-e0feb1b3a659411d53b231d24929c4b7b4d92431.zip
Updating README to mention the farthest failure position feature
-rw-r--r--README.md33
1 files changed, 23 insertions, 10 deletions
diff --git a/README.md b/README.md
index 5deec35..907802f 100644
--- a/README.md
+++ b/README.md
@@ -9,27 +9,38 @@
9LPegLabel is a conservative extension of the 9LPegLabel is a conservative extension of the
10[LPeg](http://www.inf.puc-rio.br/~roberto/lpeg) 10[LPeg](http://www.inf.puc-rio.br/~roberto/lpeg)
11library that provides an implementation of Parsing 11library that provides an implementation of Parsing
12Expression Grammars (PEGs) with labeled failures. 12Expression Grammars (PEGs) with labeled failures.
13Labels can be used to signal different kinds of errors 13Labels can be used to signal different kinds of errors
14and to specify which recovery pattern should handle a 14and to specify which recovery pattern should handle a
15given label. Labels can also be combined with the standard 15given label. Labels can also be combined with the standard
16patterns of LPeg. 16patterns of LPeg.
17
18Besides that, LPegLabel also reports the farthest
19failure position in case of an ordinary failure
20(which is represented by label **0**).
17 21
18This document describes the new functions available 22This document describes the new functions available
19in LpegLabel and presents some examples of usage. 23in LpegLabel and presents some examples of usage.
20 24
25With labeled failures it is possible to distinguish
26between an ordinary failure and an error. Usually, an
27ordinary failure is produced when the matching of a
28character fails, and this failure is caught by ordered choice.
29An error (a non-ordinary failure), by its turn, is produced
30by the throw operator and may be caught by the recovery operator.
31
21In LPegLabel, the result of an unsuccessful matching 32In LPegLabel, the result of an unsuccessful matching
22is a triple **nil, lab, sfail**, where **lab** 33is a triple **nil, lab, sfail**, where **lab**
23is the label associated with the failure, and 34is the label associated with the failure, and
24**sfail** is the suffix input being matched when 35**sfail** is the suffix input being matched when
25**lab** was thrown. 36**lab** was thrown.
26 37
27With labeled failures it is possible to distinguish 38When **lab** is an ordinary failure and no error was thrown before,
28between a regular failure and an error. Usually, a 39**sfail** is formed according to the farthest position where an
29regular failure is produced when the matching of a 40ordinary failure occurred.
30character fails, and it is caught by an ordered choice. 41In case **lab** is an ordinary failure and an error
31An error, by its turn, is produced by the throw operator 42was thrown before, **sfail** is the farthest suffix
32and may be caught by the recovery operator. 43where an ordinary failure occurred after the last error.
33 44
34Below there is a brief summary of the new functions provided by LpegLabel: 45Below there is a brief summary of the new functions provided by LpegLabel:
35 46
@@ -60,10 +71,13 @@ Below there is a brief summary of the new functions provided by LpegLabel:
60 71
61#### <a name="f-t"></a><code>lpeglabel.T(l)</code> 72#### <a name="f-t"></a><code>lpeglabel.T(l)</code>
62 73
63
64Returns a pattern that throws the label `l`. 74Returns a pattern that throws the label `l`.
65A label must be an integer between 1 and 255. 75A label must be an integer between 1 and 255.
66 76
77This pattern always causes a failure, whose associated
78position will be used to set **sfail**, no matter
79whether this is the farthest failure position or not.
80
67 81
68#### <a name="f-rec"></a><code>lpeglabel.Rec(p1, p2, l1, ..., ln)</code> 82#### <a name="f-rec"></a><code>lpeglabel.Rec(p1, p2, l1, ..., ln)</code>
69 83
@@ -73,7 +87,6 @@ then the matching of `p2` is tried from the failure position of `p1`.
73Otherwise, the result of the matching of `p1` is the pattern's result. 87Otherwise, the result of the matching of `p1` is the pattern's result.
74 88
75 89
76
77#### <a name="re-t"></a><code>%{l}</code> 90#### <a name="re-t"></a><code>%{l}</code>
78 91
79Syntax of *relabel* module. Equivalent to `lpeg.T(l)`. 92Syntax of *relabel* module. Equivalent to `lpeg.T(l)`.