diff options
author | Sergio Queiroz <sqmedeiros@gmail.com> | 2017-01-03 11:06:56 -0300 |
---|---|---|
committer | Sergio Queiroz <sqmedeiros@gmail.com> | 2017-01-03 11:06:56 -0300 |
commit | e0feb1b3a659411d53b231d24929c4b7b4d92431 (patch) | |
tree | e6d1624f75d68d53f8a7c91f198d6854993f3f4a | |
parent | 92029acf2072fbbd29271c68e601832f9a7c832d (diff) | |
download | lpeglabel-e0feb1b3a659411d53b231d24929c4b7b4d92431.tar.gz lpeglabel-e0feb1b3a659411d53b231d24929c4b7b4d92431.tar.bz2 lpeglabel-e0feb1b3a659411d53b231d24929c4b7b4d92431.zip |
Updating README to mention the farthest failure position feature
-rw-r--r-- | README.md | 33 |
1 files changed, 23 insertions, 10 deletions
@@ -9,27 +9,38 @@ | |||
9 | LPegLabel is a conservative extension of the | 9 | LPegLabel 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) |
11 | library that provides an implementation of Parsing | 11 | library that provides an implementation of Parsing |
12 | Expression Grammars (PEGs) with labeled failures. | 12 | Expression Grammars (PEGs) with labeled failures. |
13 | Labels can be used to signal different kinds of errors | 13 | Labels can be used to signal different kinds of errors |
14 | and to specify which recovery pattern should handle a | 14 | and to specify which recovery pattern should handle a |
15 | given label. Labels can also be combined with the standard | 15 | given label. Labels can also be combined with the standard |
16 | patterns of LPeg. | 16 | patterns of LPeg. |
17 | |||
18 | Besides that, LPegLabel also reports the farthest | ||
19 | failure position in case of an ordinary failure | ||
20 | (which is represented by label **0**). | ||
17 | 21 | ||
18 | This document describes the new functions available | 22 | This document describes the new functions available |
19 | in LpegLabel and presents some examples of usage. | 23 | in LpegLabel and presents some examples of usage. |
20 | 24 | ||
25 | With labeled failures it is possible to distinguish | ||
26 | between an ordinary failure and an error. Usually, an | ||
27 | ordinary failure is produced when the matching of a | ||
28 | character fails, and this failure is caught by ordered choice. | ||
29 | An error (a non-ordinary failure), by its turn, is produced | ||
30 | by the throw operator and may be caught by the recovery operator. | ||
31 | |||
21 | In LPegLabel, the result of an unsuccessful matching | 32 | In LPegLabel, the result of an unsuccessful matching |
22 | is a triple **nil, lab, sfail**, where **lab** | 33 | is a triple **nil, lab, sfail**, where **lab** |
23 | is the label associated with the failure, and | 34 | is 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 | ||
27 | With labeled failures it is possible to distinguish | 38 | When **lab** is an ordinary failure and no error was thrown before, |
28 | between a regular failure and an error. Usually, a | 39 | **sfail** is formed according to the farthest position where an |
29 | regular failure is produced when the matching of a | 40 | ordinary failure occurred. |
30 | character fails, and it is caught by an ordered choice. | 41 | In case **lab** is an ordinary failure and an error |
31 | An error, by its turn, is produced by the throw operator | 42 | was thrown before, **sfail** is the farthest suffix |
32 | and may be caught by the recovery operator. | 43 | where an ordinary failure occurred after the last error. |
33 | 44 | ||
34 | Below there is a brief summary of the new functions provided by LpegLabel: | 45 | Below 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 | |||
64 | Returns a pattern that throws the label `l`. | 74 | Returns a pattern that throws the label `l`. |
65 | A label must be an integer between 1 and 255. | 75 | A label must be an integer between 1 and 255. |
66 | 76 | ||
77 | This pattern always causes a failure, whose associated | ||
78 | position will be used to set **sfail**, no matter | ||
79 | whether 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`. | |||
73 | Otherwise, the result of the matching of `p1` is the pattern's result. | 87 | Otherwise, 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 | ||
79 | Syntax of *relabel* module. Equivalent to `lpeg.T(l)`. | 92 | Syntax of *relabel* module. Equivalent to `lpeg.T(l)`. |