Updating the examples since lpeglabel now returns an error position instead of a string and p^lab is syntatic sugar

9 files changed, 90 insertions, 40 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
 by the throw operator and may be caught by the recovery operator. 
 
 In LPegLabel, the result of an unsuccessful matching
-is a triple **nil, lab, sfail**, where **lab**
+is a triple **nil, lab, errpos**, where **lab**
 is the label associated with the failure, and
-**sfail** is the suffix input being matched when
+**errpos** is the input position being matched when
 **lab** was thrown. 
 
 When **lab** is an ordinary failure and no error was thrown before,
-**sfail** is formed according to the farthest position where an
-ordinary failure occurred. 
+**errpos** is the farthest position where an ordinary failure occurred. 
 In case **lab** is an ordinary failure and an error
-was thrown before, **sfail** is the farthest suffix
+was thrown before, **errpos** is the farthest input position
 where an ordinary failure occurred after the last error. 
  
 Below 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:
 <tr><td><a href="#f-rec"><code>lpeglabel.Rec (p1, p2, l1 [, l2, ..., ln])</code></a></td>
   <td>Specifies a recovery pattern <code>p2</code> for <code>p1</code>,
  when the matching of <code>p1</code> gives one of the labels l1, ..., ln.</td></tr>
+<tr><td><a href="#f-lc"><code>lpeglabel.Lc (p1, p2, l1, ..., ln)</code></a></td>
+  <td>Matches <code>p1</code> and tries to match <code>p2</code>
+      if the matching of <code>p1</code> gives one of l<sub>1</sub>, ..., l<sub>n</sub> 
+      </td></tr>
 <tr><td><a href="#re-t"><code>%{l}</code></a></td>
   <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeglabel.T(l)</code>
       </td></tr>
+<tr><td><a href="#re-pow"><code>p^l</code></a></td>
+  <td>Syntax sugar available at <em>relabel</em> for <code>p / %{l}</code>
+      </td></tr>
 <tr><td><a href="#re-rec"><code>p1 //{l1 [, l2, ..., ln} p2</code></a></td>
   <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeglabel.Rec(p1, p2, l1, ..., ln)</code>
       </td></tr>
+<tr><td><a href="#re-lc"><code>p1 /{l1, ..., ln} p2</code></a></td>
+  <td>Syntax of <em>relabel</em> module. Equivalent to <code>lpeg.Lc(p1, p2, l1, ..., ln)</code>
+      </td></tr>
 <tr><td><a href="#re-line"><code>relabel.calcline(subject, i)</code></a></td>
   <td>Calculates line and column information regarding position <i>i</i> of the subject</code>
       </td></tr>
@@ -75,7 +84,7 @@ Returns a pattern that throws the label `l`.
 A label must be an integer between 1 and 255.
 
 This pattern always causes a failure, whose associated
-position will be used to set **sfail**, no matter
+position will be used to set **errpos**, no matter
 whether this is the farthest failure position or not. 
 
 
@@ -87,18 +96,45 @@ then the matching of `p2` is tried from the failure position of `p1`.
 Otherwise, the result of the matching of `p1` is the pattern's result.
 
 
+#### <a name="f-lc"></a><code>lpeglabel.Lc(p1, p2, l1, ..., ln)</code>
+
+Returns a pattern equivalent to a *labeled ordered choice*.
+If the matching of `p1` gives one of the labels `l1, ..., ln`,
+then the matching of `p2` is tried from the same position. Otherwise,
+the result of the matching of `p1` is the pattern's result.
+
+<!---
+The labeled ordered choice `lpeg.Lc(p1, p2, 0)` is equivalent to the
+regular ordered choice `p1 / p2`.
+-->
+
+Although PEG's ordered choice is associative, the labeled ordered choice is not.
+When using this function, the user should take care to build a left-associative
+labeled ordered choice pattern.
+
+
 #### <a name="re-t"></a><code>%{l}</code>
 
 Syntax of *relabel* module. Equivalent to `lpeg.T(l)`.
 
 
-#### <a name="re-lc"></a><code>p1 //{l1, ..., ln} p2</code>
+#### <a name="re-rec"></a><code>p1 //{l1, ..., ln} p2</code>
 
 Syntax of *relabel* module. Equivalent to `lpeglabel.Rec(p1, p2, l1, ..., ln)`.
 
 The `//{}` operator is left-associative. 
 
 
+#### <a name="re-lc"></a><code>p1 /{l1, ..., ln} p2</code>
+
+Syntax of *relabel* module. Equivalent to `lpeg.Lc(p1, p2, l1, ..., ln)`.
+
+The `/{}` operator is left-associative. 
+
+A grammar can use both choice operators (`/` and `/{}`),
+but a single choice can not mix them. That is, the parser of `relabel`
+module will not recognize a pattern as `p1 / p2 /{l1} p3`.
+
 
 #### <a name="re-line"></a><code>relabel.calcline (subject, i)</code>
 
@@ -124,24 +160,25 @@ in the *examples* directory.
 This example illustrates the new values returned
 by the *match* function in case of an unsuccessful
 matching. As no error is thrown, when the matching
-fails *sfail* represents the farthest suffix where
+fails *errpos* represents the farthest suffix where
 an ordinary failure occurred.
 
 ```lua
 local m = require'lpeglabel'
 
 function matchPrint(p, s)
-  local r, lab, sfail = p:match(s)
-  print("r: ", r, "lab: ", lab, "sfail: ", sfail)
+  local r, lab, errpos = p:match(s)
+  print("r: ", r, "lab: ", lab, "errpos: ", errpos)
 end
 
 local p = m.P"a"^0 * m.P"b" + m.P"c"
-matchPrint(p, "abc")  --> r:    3       lab:    nil     sfail:  nil
-matchPrint(p, "c")    --> r:    2       lab:    nil     sfail:  nil
-matchPrint(p, "aac")  --> r:    nil     lab:    0       sfail:  c
-matchPrint(p, "xxc")  --> r:    nil     lab:    0       sfail:  xxc
+matchPrint(p, "abc")  --> r: 3    lab: nil  errpos: nil
+matchPrint(p, "c")    --> r: 2    lab: nil  errpos: nil
+matchPrint(p, "aac")  --> r: nil        lab: 0    errpos: 3
+matchPrint(p, "xxc")  --> r: nil        lab: 0    errpos: 1
 ```
 
+
 #### Matching a list of identifiers separated by commas
 
 The following example defines a grammar that matches
diff --git a/examples/farthest.lua b/examples/farthest.lua
index 692390f..9cbe03d 100644
--- a/examples/farthest.lua
+++ b/examples/farthest.lua
@@ -1,14 +1,27 @@
 local m = require'lpeglabel'
 
 function matchPrint(p, s)
-        local r, lab, sfail = p:match(s)
-        print("r: ", r, "lab: ", lab, "sfail: ", sfail)
+        local r, lab, errpos = p:match(s)
+        print("r: ", r, "lab: ", lab, "errpos: ", errpos)
+end
+
+function getSub (s, i)
+        if i then return s:sub(i) else return nil end
+end
+
+function matchPrint2(p, s)
+        local r, lab, ifail = p:match(s)
+        print("r: ", r, "lab: ", lab, "sfail: ", getSub(s, ifail))
 end
 
 local p = m.P"a"^0 * m.P"b" + m.P"c"
-matchPrint(p, "abc")  --> r:    3       lab:    nil     sfail:  nil
-matchPrint(p, "c")    --> r:    2       lab:    nil     sfail:  nil
-matchPrint(p, "aac")  --> r:    nil     lab:    0       sfail:  c
-matchPrint(p, "xxc")  --> r:    nil     lab:    0       sfail:  xxc
+matchPrint(p, "abc")  --> r: 3    lab: nil  errpos: nil
+matchPrint(p, "c")    --> r: 2    lab: nil  errpos: nil
+matchPrint(p, "aac")  --> r: nil        lab: 0    errpos: 3
+matchPrint(p, "xxc")  --> r: nil        lab: 0    errpos: 1
 
 
+matchPrint2(p, "abc")  --> r:   3       lab:    nil     sfail:  nil
+matchPrint2(p, "c")    --> r:   2       lab:    nil     sfail:  nil
+matchPrint2(p, "aac")  --> r:   nil     lab:    0       sfail:  c
+matchPrint2(p, "xxc")  --> r:   nil     lab:    0       sfail:  xxc
diff --git a/examples/listId1.lua b/examples/listId1.lua
index b7943c1..9bba783 100644
--- a/examples/listId1.lua
+++ b/examples/listId1.lua
@@ -13,14 +13,14 @@ local g = m.P{
 }
 
 function mymatch (g, s)
-  local r, e, sfail = g:match(s)
+  local r, e, pos = g:match(s)
   if not r then
-    local line, col = re.calcline(s, #s - #sfail)
+    local line, col = re.calcline(s, pos)
     local msg = "Error at line " .. line .. " (col " .. col .. ")"
     if e == 1 then
-      return r, msg .. ": expecting an identifier before '" .. sfail .. "'"
+      return r, msg .. ": expecting an identifier before '" .. s:sub(pos) .. "'"
     elseif e == 2 then
-      return r, msg .. ": expecting ',' before '" .. sfail .. "'"
+      return r, msg .. ": expecting ',' before '" .. s:sub(pos) .. "'"
     else
       return r, msg
     end
diff --git a/examples/listId2.lua b/examples/listId2.lua
index 3ee89da..592dae3 100644
--- a/examples/listId2.lua
+++ b/examples/listId2.lua
@@ -25,11 +25,11 @@ local g = m.P{
 
 
 function mymatch (g, s)
-  local r, e, sfail = g:match(s)
+  local r, e, pos = g:match(s)
   if not r then
-    local line, col = re.calcline(s, #s - #sfail)
+    local line, col = re.calcline(s, pos)
     local msg = "Error at line " .. line .. " (col " .. col .. "): "
-    return r, msg .. terror[e] .. " before '" .. sfail .. "'"
+    return r, msg .. terror[e] .. " before '" .. s:sub(pos) .. "'"
   end
   return r
 end
diff --git a/examples/listIdRe1.lua b/examples/listIdRe1.lua
index 3098c66..d60706a 100644
--- a/examples/listIdRe1.lua
+++ b/examples/listIdRe1.lua
@@ -9,14 +9,14 @@ local g = re.compile[[
 ]]
 
 function mymatch (g, s)
-  local r, e, sfail = g:match(s)
+  local r, e, pos = g:match(s)
   if not r then
-    local line, col = re.calcline(s, #s - #sfail)
+    local line, col = re.calcline(s, pos)
     local msg = "Error at line " .. line .. " (col " .. col .. ")"
     if e == 1 then
-      return r, msg .. ": expecting an identifier before '" .. sfail .. "'"
+      return r, msg .. ": expecting an identifier before '" .. s:sub(pos) .. "'"
     elseif e == 2 then
-      return r, msg .. ": expecting ',' before '" .. sfail .. "'"
+      return r, msg .. ": expecting ',' before '" .. s:sub(pos) .. "'"
     else
       return r, msg
     end
diff --git a/examples/tiny.lua b/examples/tiny.lua
index 734536c..cc718e7 100644
--- a/examples/tiny.lua
+++ b/examples/tiny.lua
@@ -90,9 +90,9 @@ local g = re.compile[[
 
 
 local function mymatch(g, s)
-        local r, e, sfail = g:match(s)
+        local r, e, pos = g:match(s)
   if not r then
-    local line, col = re.calcline(s, #s - #sfail)
+    local line, col = re.calcline(s, pos)
     local msg = "Error at line " .. line .. " (col " .. col .. "): "
                 return r, msg .. terror[e].msg
         end 
diff --git a/examples/typedlua/tlparser.lua b/examples/typedlua/tlparser.lua
index a301fa6..2ede2eb 100644
--- a/examples/typedlua/tlparser.lua
+++ b/examples/typedlua/tlparser.lua
@@ -226,9 +226,9 @@ end
 function tlparser.parse (subject, filename, strict, integer)
   local errorinfo = {}
   lpeg.setmaxstack(1000)
-  local ast, label, suffix = lpeg.match(G, subject, nil, errorinfo, strict, integer)
+  local ast, label, pos = lpeg.match(G, subject, nil, errorinfo, strict, integer)
   if not ast then
-    local line, col = lineno(subject, string.len(subject) - string.len(suffix))
+    local line, col = lineno(subject, pos)
     local error_msg = string.format("%s:%d:%d: ", filename, line, col)
     if label ~= 0 then
       error_msg = error_msg .. tlerror.errors[label].msg
diff --git a/relabel.lua b/relabel.lua
index 642b0fe..abb3c7f 100644
--- a/relabel.lua
+++ b/relabel.lua
@@ -45,7 +45,7 @@ local errinfo = {
 
   {"ExpPattOrClose", "expected a pattern or closing '}' after '{'"},
 
-  {"ExpNum", "expected a number after '^', '+' or '-' (no space)"},
+  {"ExpNumName", "expected a number, '+', '-' or a name (no space) after '^'"},
   {"ExpCap", "expected a string, number, '{}' or name after '->'"},
 
   {"ExpName1", "expected the name of a rule after '=>'"},
@@ -245,7 +245,7 @@ local function getlab (f)
         if not tlabels[f] then
     error("undefined label: " .. f)
         end
-        return mm.T(tlabels[f])
+        return tlabels[f]
 end
 
 local exp = m.P{ "Exp",
@@ -269,7 +269,7 @@ local exp = m.P{ "Exp",
                               + m.Cg(m.C(m.S"+-" * m.R"09"^1) * m.Cc(mt.__pow)
                               + name * m.Cc"lab"
                               ),
-                          "ExpNum")
+                          "ExpNumName")
                 + "->" * expect(S * ( m.Cg((String + num) * m.Cc(mt.__div))
                                     + m.P"{}" * m.Cc(nil, m.Ct)
                                     + m.Cg(Def / getdef * m.Cc(mt.__div))
@@ -278,7 +278,7 @@ local exp = m.P{ "Exp",
                 + "=>" * expect(S * m.Cg(Def / getdef * m.Cc(m.Cmt)),
                            "ExpName1")
                 )
-          )^0, function (a,b,f) if f == "lab" then return a + getlab(b) else return f(a,b) end end );
+          )^0, function (a,b,f) if f == "lab" then return a + mm.T(getlab(b)) else return f(a,b) end end );
   Primary = "(" * expect(m.V"Exp", "ExpPatt4") * expect(S * ")", "MisClose1")
           + String / mm.P
           + Class
diff --git a/testlabel.lua b/testlabel.lua
index d3d95b1..1be1343 100644
--- a/testlabel.lua
+++ b/testlabel.lua
@@ -1336,7 +1336,7 @@ g = re.compile([[
   WRITE      <- Sp 'write'
   RESERVED   <- (IF / ELSE / END / READ / REPEAT / THEN / UNTIL / WRITE) ![a-z]+
   Sp         <- (%s / %nl)*  
-]], terror)
+]])
 
 s = [[
 n := 5;]]