aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorSérgio Queiroz <sqmedeiros@gmail.com>2017-12-08 10:11:50 -0300
committerSérgio Queiroz <sqmedeiros@gmail.com>2017-12-08 10:11:50 -0300
commit5ffef3da93ad53069d2510a75b11ecbb1b6e8aa7 (patch)
treee98c59a9e0aae891638eca25a25558d933fdf44f /README.md
parent030df9b4a4f4dc3a2cc5775e032f83e92d3c0097 (diff)
downloadlpeglabel-5ffef3da93ad53069d2510a75b11ecbb1b6e8aa7.tar.gz
lpeglabel-5ffef3da93ad53069d2510a75b11ecbb1b6e8aa7.tar.bz2
lpeglabel-5ffef3da93ad53069d2510a75b11ecbb1b6e8aa7.zip
Updating the examples since lpeglabel now returns an error position instead of a string and p^lab is syntatic sugar
Diffstat (limited to 'README.md')
-rw-r--r--README.md65
1 files changed, 51 insertions, 14 deletions
diff --git a/README.md b/README.md
index 31cd43e..b8595ad 100644
--- a/README.md
+++ b/README.md
@@ -30,16 +30,15 @@ An error (a non-ordinary failure), by its turn, is produced
30by the throw operator and may be caught by the recovery operator. 30by the throw operator and may be caught by the recovery operator.
31 31
32In LPegLabel, the result of an unsuccessful matching 32In LPegLabel, the result of an unsuccessful matching
33is a triple **nil, lab, sfail**, where **lab** 33is a triple **nil, lab, errpos**, where **lab**
34is the label associated with the failure, and 34is the label associated with the failure, and
35**sfail** is the suffix input being matched when 35**errpos** is the input position being matched when
36**lab** was thrown. 36**lab** was thrown.
37 37
38When **lab** is an ordinary failure and no error was thrown before, 38When **lab** is an ordinary failure and no error was thrown before,
39**sfail** is formed according to the farthest position where an 39**errpos** is the farthest position where an ordinary failure occurred.
40ordinary failure occurred.
41In case **lab** is an ordinary failure and an error 40In case **lab** is an ordinary failure and an error
42was thrown before, **sfail** is the farthest suffix 41was thrown before, **errpos** is the farthest input position
43where an ordinary failure occurred after the last error. 42where an ordinary failure occurred after the last error.
44 43
45Below there is a brief summary of the new functions provided by LpegLabel: 44Below there is a brief summary of the new functions provided by LpegLabel:
@@ -51,12 +50,22 @@ Below there is a brief summary of the new functions provided by LpegLabel:
51<tr><td><a href="#f-rec"><code>lpeglabel.Rec (p1, p2, l1 [, l2, ..., ln])</code></a></td> 50<tr><td><a href="#f-rec"><code>lpeglabel.Rec (p1, p2, l1 [, l2, ..., ln])</code></a></td>
52 <td>Specifies a recovery pattern <code>p2</code> for <code>p1</code>, 51 <td>Specifies a recovery pattern <code>p2</code> for <code>p1</code>,
53 when the matching of <code>p1</code> gives one of the labels l1, ..., ln.</td></tr> 52 when the matching of <code>p1</code> gives one of the labels l1, ..., ln.</td></tr>
53<tr><td><a href="#f-lc"><code>lpeglabel.Lc (p1, p2, l1, ..., ln)</code></a></td>
54 <td>Matches <code>p1</code> and tries to match <code>p2</code>
55 if the matching of <code>p1</code> gives one of l<sub>1</sub>, ..., l<sub>n</sub>
56 </td></tr>
54<tr><td><a href="#re-t"><code>%{l}</code></a></td> 57<tr><td><a href="#re-t"><code>%{l}</code></a></td>
55 <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeglabel.T(l)</code> 58 <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeglabel.T(l)</code>
56 </td></tr> 59 </td></tr>
60<tr><td><a href="#re-pow"><code>p^l</code></a></td>
61 <td>Syntax sugar available at <em>relabel</em> for <code>p / %{l}</code>
62 </td></tr>
57<tr><td><a href="#re-rec"><code>p1 //{l1 [, l2, ..., ln} p2</code></a></td> 63<tr><td><a href="#re-rec"><code>p1 //{l1 [, l2, ..., ln} p2</code></a></td>
58 <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeglabel.Rec(p1, p2, l1, ..., ln)</code> 64 <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeglabel.Rec(p1, p2, l1, ..., ln)</code>
59 </td></tr> 65 </td></tr>
66<tr><td><a href="#re-lc"><code>p1 /{l1, ..., ln} p2</code></a></td>
67 <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeg.Lc(p1, p2, l1, ..., ln)</code>
68 </td></tr>
60<tr><td><a href="#re-line"><code>relabel.calcline(subject, i)</code></a></td> 69<tr><td><a href="#re-line"><code>relabel.calcline(subject, i)</code></a></td>
61 <td>Calculates line and column information regarding position <i>i</i> of the subject</code> 70 <td>Calculates line and column information regarding position <i>i</i> of the subject</code>
62 </td></tr> 71 </td></tr>
@@ -75,7 +84,7 @@ Returns a pattern that throws the label `l`.
75A label must be an integer between 1 and 255. 84A label must be an integer between 1 and 255.
76 85
77This pattern always causes a failure, whose associated 86This pattern always causes a failure, whose associated
78position will be used to set **sfail**, no matter 87position will be used to set **errpos**, no matter
79whether this is the farthest failure position or not. 88whether this is the farthest failure position or not.
80 89
81 90
@@ -87,18 +96,45 @@ then the matching of `p2` is tried from the failure position of `p1`.
87Otherwise, the result of the matching of `p1` is the pattern's result. 96Otherwise, the result of the matching of `p1` is the pattern's result.
88 97
89 98
99#### <a name="f-lc"></a><code>lpeglabel.Lc(p1, p2, l1, ..., ln)</code>
100
101Returns a pattern equivalent to a *labeled ordered choice*.
102If the matching of `p1` gives one of the labels `l1, ..., ln`,
103then the matching of `p2` is tried from the same position. Otherwise,
104the result of the matching of `p1` is the pattern's result.
105
106<!---
107The labeled ordered choice `lpeg.Lc(p1, p2, 0)` is equivalent to the
108regular ordered choice `p1 / p2`.
109-->
110
111Although PEG's ordered choice is associative, the labeled ordered choice is not.
112When using this function, the user should take care to build a left-associative
113labeled ordered choice pattern.
114
115
90#### <a name="re-t"></a><code>%{l}</code> 116#### <a name="re-t"></a><code>%{l}</code>
91 117
92Syntax of *relabel* module. Equivalent to `lpeg.T(l)`. 118Syntax of *relabel* module. Equivalent to `lpeg.T(l)`.
93 119
94 120
95#### <a name="re-lc"></a><code>p1 //{l1, ..., ln} p2</code> 121#### <a name="re-rec"></a><code>p1 //{l1, ..., ln} p2</code>
96 122
97Syntax of *relabel* module. Equivalent to `lpeglabel.Rec(p1, p2, l1, ..., ln)`. 123Syntax of *relabel* module. Equivalent to `lpeglabel.Rec(p1, p2, l1, ..., ln)`.
98 124
99The `//{}` operator is left-associative. 125The `//{}` operator is left-associative.
100 126
101 127
128#### <a name="re-lc"></a><code>p1 /{l1, ..., ln} p2</code>
129
130Syntax of *relabel* module. Equivalent to `lpeg.Lc(p1, p2, l1, ..., ln)`.
131
132The `/{}` operator is left-associative.
133
134A grammar can use both choice operators (`/` and `/{}`),
135but a single choice can not mix them. That is, the parser of `relabel`
136module will not recognize a pattern as `p1 / p2 /{l1} p3`.
137
102 138
103#### <a name="re-line"></a><code>relabel.calcline (subject, i)</code> 139#### <a name="re-line"></a><code>relabel.calcline (subject, i)</code>
104 140
@@ -124,24 +160,25 @@ in the *examples* directory.
124This example illustrates the new values returned 160This example illustrates the new values returned
125by the *match* function in case of an unsuccessful 161by the *match* function in case of an unsuccessful
126matching. As no error is thrown, when the matching 162matching. As no error is thrown, when the matching
127fails *sfail* represents the farthest suffix where 163fails *errpos* represents the farthest suffix where
128an ordinary failure occurred. 164an ordinary failure occurred.
129 165
130```lua 166```lua
131local m = require'lpeglabel' 167local m = require'lpeglabel'
132 168
133function matchPrint(p, s) 169function matchPrint(p, s)
134 local r, lab, sfail = p:match(s) 170 local r, lab, errpos = p:match(s)
135 print("r: ", r, "lab: ", lab, "sfail: ", sfail) 171 print("r: ", r, "lab: ", lab, "errpos: ", errpos)
136end 172end
137 173
138local p = m.P"a"^0 * m.P"b" + m.P"c" 174local p = m.P"a"^0 * m.P"b" + m.P"c"
139matchPrint(p, "abc") --> r: 3 lab: nil sfail: nil 175matchPrint(p, "abc") --> r: 3 lab: nil errpos: nil
140matchPrint(p, "c") --> r: 2 lab: nil sfail: nil 176matchPrint(p, "c") --> r: 2 lab: nil errpos: nil
141matchPrint(p, "aac") --> r: nil lab: 0 sfail: c 177matchPrint(p, "aac") --> r: nil lab: 0 errpos: 3
142matchPrint(p, "xxc") --> r: nil lab: 0 sfail: xxc 178matchPrint(p, "xxc") --> r: nil lab: 0 errpos: 1
143``` 179```
144 180
181
145#### Matching a list of identifiers separated by commas 182#### Matching a list of identifiers separated by commas
146 183
147The following example defines a grammar that matches 184The following example defines a grammar that matches