Merge branch 'master' of https://github.com/sqmedeiros/lpeglabel

3 files changed, 293 insertions, 0 deletions

diff --git a/examples/expect.lua b/examples/expect.lua
index 2b7e904..cb68d38 100644
--- a/examples/expect.lua
+++ b/examples/expect.lua
@@ -2,6 +2,9 @@ local lpeg = require"lpeglabel"
 
 local R, S, P, V, C, Ct, T = lpeg.R, lpeg.S, lpeg.P, lpeg.V, lpeg.C, lpeg.Ct, lpeg.T
 
+-- The `labels` table contains the list of labels that we will be using
+-- as well as the corresponding error message for each label, which will
+-- be used in our error reporting later on.
 local labels = {
   {"NoExp",     "no expression found"},
   {"Extra",     "extra characters found after the expression"},
@@ -10,6 +13,11 @@ local labels = {
   {"MisClose",  "missing a closing ')' after the expression"},
 }
 
+-- The `expect` function takes a pattern and a label defined in
+-- the `labels` table and returns a pattern that throws the specified
+-- label if the original pattern fails to match.
+-- Note: LPegLabel requires us to use integers for the labels, so we
+-- use the index of the label in the `labels` table to represent it.
 local function expect(patt, labname)
   for i, elem in ipairs(labels) do
     if elem[1] == labname then
@@ -23,6 +31,9 @@ end
 local num = R("09")^1 / tonumber
 local op = S("+-*/")
 
+-- The `compute` function takes an alternating list of numbers and
+-- operators and computes the result of applying the operations
+-- to the numbers in a left to right order (no operator precedence).
 local function compute(tokens)
   local result = tokens[1]
   for i = 2, #tokens, 2 do
@@ -41,6 +52,9 @@ local function compute(tokens)
   return result
 end
 
+-- Our grammar is a simple arithmetic expression of integers that
+-- does not take operator precedence into account but allows grouping
+-- via parenthesis.
 local g = P {
   "Exp",
   Exp = Ct(V"Term" * (C(op) * expect(V"Term", "ExpTerm"))^0) / compute;
@@ -50,6 +64,10 @@ local g = P {
 
 g = expect(g, "NoExp") * expect(-P(1), "Extra")
 
+-- The `eval` function takes an input string to match against the grammar
+-- we've just defined. If the input string matches, then the result of the
+-- computation is returned, otherwise we return the error message and
+-- position of the first failure encountered.
 local function eval(input)
   local result, label, suffix = g:match(input)
   if result ~= nil then
diff --git a/examples/recovery.lua b/examples/recovery.lua
new file mode 100644
index 0000000..3272ae7
--- /dev/null
+++ b/examples/recovery.lua
@@ -0,0 +1,134 @@
+local lpeg = require"lpeglabel"
+
+local R, S, P, V = lpeg.R, lpeg.S, lpeg.P, lpeg.V
+local C, Cc, Ct, Cmt = lpeg.C, lpeg.Cc, lpeg.Ct, lpeg.Cmt
+local T, Lc = lpeg.T, lpeg.Lc
+
+-- The `labels` table contains the list of labels that we will be using
+-- as well as the corresponding error message for each label, which will
+-- be used in our error reporting later on.
+local labels = {
+  {"NoExp",     "no expression found"},
+  {"Extra",     "extra characters found after the expression"},
+  {"ExpTerm",   "expected a term after the operator"},
+  {"ExpExp",    "expected an expression after the parenthesis"},
+  {"MisClose",  "missing a closing ')' after the expression"},
+}
+
+-- The `labelindex` function gives us the index of a label in the
+-- `labels` table, which serves as the integer representation of the label.
+-- We need this because LPegLabel requires us to use integers for the labels.
+local function labelindex(labname)
+  for i, elem in ipairs(labels) do
+    if elem[1] == labname then
+      return i
+    end
+  end
+  error("could not find label: " .. labname)
+end
+
+-- The `errors` table will hold the list of errors recorded during parsing
+local errors = {}
+
+-- The `expect` function takes a pattern and a label and returns a pattern
+-- that throws the specified label if the original pattern fails to match.
+-- Before throwing the label, it records the label to be thrown along with
+-- the position of the failure (index in input string) into the `errors` table.
+local function expect(patt, labname)
+  local i = labelindex(labname)
+  function recorderror(input, pos)
+    table.insert(errors, {i, pos})
+    return true
+  end
+  return patt + Cmt("", recorderror) * T(i)
+end
+
+local num = R("09")^1 / tonumber
+local op = S("+-*/")
+
+-- The `compute` function takes an alternating list of numbers and
+-- operators and computes the result of applying the operations
+-- to the numbers in a left to right order (no operator precedence).
+local function compute(tokens)
+  local result = tokens[1]
+  for i = 2, #tokens, 2 do
+    if tokens[i] == '+' then
+      result = result + tokens[i+1]
+    elseif tokens[i] == '-' then
+      result = result - tokens[i+1]
+    elseif tokens[i] == '*' then
+      result = result * tokens[i+1]
+    elseif tokens[i] == '/' then
+      result = result / tokens[i+1]
+    else
+      error('unknown operation: ' .. tokens[i])
+    end
+  end
+  return result
+end
+
+-- Our grammar is a simple arithmetic expression of integers that
+-- does not take operator precedence into account but allows grouping
+-- via parenthesis. We have incorporated some error recovery startegies
+-- to our grammar so that it may resume parsing even after encountering
+-- an error, which allows us to report more errors.
+local g = P {
+  "Exp",
+  Exp = Ct(V"Term" * (C(op) * V"OpRecov")^0) / compute;
+  -- `OpRecov` handles missing terms/operands by returning a dummy (zero).
+  OpRecov = Lc(V"Operand", Cc(0), labelindex("ExpTerm"));
+  Operand = expect(V"Term", "ExpTerm");
+  Term = num + V"Group";
+  -- `Group` handles missing closing parenthesis by simply ignoring it.
+  -- Like all the others, the error is still recorded of course.
+  Group = "(" * V"InnerExp" * Lc(expect(")", "MisClose"), P"", labelindex("MisClose"));
+  -- `InnerExp` handles missing expressions by skipping to the next closing
+  -- parenthesis. A dummy (zero) is returned in place of the expression.
+  InnerExp = Lc(expect(V"Exp", "ExpExp"), (P(1) - ")")^0 * Cc(0), labelindex("ExpExp"));
+}
+
+g = expect(g, "NoExp") * expect(-P(1), "Extra")
+
+-- The `eval` function takes an input string to match against the grammar
+-- we've just defined. If the input string matches, then the result of the
+-- computation is returned, otherwise we return the error messages and
+-- positions of all the failures encountered.
+local function eval(input)
+  local result, label, suffix = g:match(input)
+  if #errors == 0 then
+    return result
+  else
+    local out = {}
+    for i, err in ipairs(errors) do
+      local pos = err[2]
+      local msg = labels[err[1]][2]
+      table.insert(out, "syntax error: " .. msg .. " (at index " .. pos .. ")")
+    end
+    errors = {}
+    return nil, table.concat(out, "\n")
+  end
+end
+
+print(eval "98-76*(54/32)")
+--> 37.125
+
+print(eval "(1+1-1*2/2")
+--> syntax error: missing a closing ')' after the expression (at index 11)
+
+print(eval "(1+)-1*(2/2)")
+--> syntax error: expected a term after the operator (at index 4)
+
+print(eval "(1+1)-1*(/2)")
+--> syntax error: expected an expression after the parenthesis (at index 10)
+
+print(eval "1+(1-(1*2))/2x")
+--> syntax error: extra chracters found after the expression (at index 14)
+
+print(eval "-1+(1-(1*2))/2")
+--> syntax error: no expression found (at index 1)
+
+print(eval "(1+1-1*(2/2+)-():")
+--> syntax error: expected a term after the operator (at index 13)
+--> syntax error: expected an expression after the parenthesis (at index 16)
+--> syntax error: missing a closing ')' after the expression (at index 17)
+--> syntax error: extra characters found after the expression (at index 17)
diff --git a/examples/recoveryRe.lua b/examples/recoveryRe.lua
new file mode 100644
index 0000000..3b83d88
--- /dev/null
+++ b/examples/recoveryRe.lua
@@ -0,0 +1,141 @@
+local re = require"relabel"
+
+-- The `errinfo` table contains the list of labels that we will be using
+-- as well as the corresponding error message for each label, which will
+-- be used in our error reporting later on.
+local errinfo = {
+  {"NoExp",     "no expression found"},
+  {"Extra",     "extra characters found after the expression"},
+  {"ExpTerm",   "expected a term after the operator"},
+  {"ExpExp",    "expected an expression after the parenthesis"},
+  {"MisClose",  "missing a closing ')' after the expression"},
+}
+
+-- We split the errinfo table into two tables: `labels` which is a
+-- mapping from the label names to its integer representation, and
+-- `errmsgs` which is a mapping from the label names to its
+-- corresponding error message.
+local labels = {}
+local errmsgs = {}
+
+for i, err in ipairs(errinfo) do
+  labels[err[1]] = i
+  errmsgs[err[1]] = err[2]
+end
+
+-- The `labels` table is especially useful for making our re grammar more
+-- readable through the use of the `setlabels` function which allows us
+-- to use the label names directly in the re grammar instead of the integers.
+re.setlabels(labels)
+
+-- The `errors` table will hold the list of errors recorded during parsing
+local errors = {}
+
+-- The `recorderror` function simply records the label and position of
+-- the failure (index in input string) into the `errors` table.
+-- Note: The unused `input` parameter is necessary, as this will be called
+-- by LPeg's match-time capture.
+local function recorderror(input, pos, label)
+  table.insert(errors, {label, pos})
+  return true
+end
+
+-- The `compute` function takes an alternating list of numbers and
+-- operators and computes the result of applying the operations
+-- to the numbers in a left to right order (no operator precedence).
+local function compute(tokens)
+  local result = tokens[1]
+  for i = 2, #tokens, 2 do
+    if tokens[i] == '+' then
+      result = result + tokens[i+1]
+    elseif tokens[i] == '-' then
+      result = result - tokens[i+1]
+    elseif tokens[i] == '*' then
+      result = result * tokens[i+1]
+    elseif tokens[i] == '/' then
+      result = result / tokens[i+1]
+    else
+      error('unknown operation: ' .. tokens[i])
+    end
+  end
+  return result
+end
+
+-- Our grammar is a simple arithmetic expression of integers that
+-- does not take operator precedence into account but allows grouping
+-- via parenthesis. We have incorporated some error recovery startegies
+-- to our grammar so that it may resume parsing even after encountering
+-- an error, which allows us to report more errors.
+local g = re.compile([[
+  S         <- (Exp / ErrNoExp) (!. / ErrExtra)
+  Exp       <- {| Term (op Operand)* |} -> compute
+  --  If we encounter a missing term/operand, we return a dummy instead.
+  Operand   <- Term / ErrExpTerm /{ExpTerm} dummy
+  Term      <- num / Group
+  -- If we encounter a missing closing parenthesis, we ignore it.
+  Group     <- "(" InnerExp (")" / ErrMisClose /{MisClose} "")
+  -- If we encounter a missing inner expression, we skip to the next
+  -- closing parenthesis, and return a dummy in its place.
+  InnerExp  <- Exp / ErrExpExp /{ExpExp} [^)]* dummy
+
+  op   <- {[-+*/]}
+  num  <- [0-9]+ -> tonumber
+
+  -- Before throwing an error, we make sure to record it first.
+  ErrNoExp     <- ("" -> "NoExp"     => recorderror) %{NoExp}
+  ErrExtra     <- ("" -> "Extra"     => recorderror) %{Extra}
+  ErrExpTerm   <- ("" -> "ExpTerm"   => recorderror) %{ExpTerm}
+  ErrExpExp    <- ("" -> "ExpExp"    => recorderror) %{ExpExp}
+  ErrMisClose  <- ("" -> "MisClose"  => recorderror) %{MisClose}
+
+  dummy <- "" -> "0" -> tonumber
+]], {
+  compute = compute;
+  recorderror = recorderror;
+  tonumber = tonumber;
+})
+
+-- The `eval` function takes an input string to match against the grammar
+-- we've just defined. If the input string matches, then the result of the
+-- computation is returned, otherwise we return the error messages and
+-- positions of all the failures encountered.
+local function eval(input)
+  local result, label, suffix = g:match(input)
+  if #errors == 0 then
+    return result
+  else
+    local out = {}
+    for i, err in ipairs(errors) do
+      local pos = err[2]
+      local msg = errmsgs[err[1]]
+      local line, col = re.calcline(input, pos)
+      table.insert(out, "syntax error: " .. msg .. " (line " .. line .. ", col " .. col .. ")")
+    end
+    errors = {}
+    return nil, table.concat(out, "\n")
+  end
+end
+
+print(eval "98-76*(54/32)")
+--> 37.125
+
+print(eval "(1+1-1*2/2")
+--> syntax error: missing a closing ')' after the expression (line 1, col 10)
+
+print(eval "(1+)-1*(2/2)")
+--> syntax error: expected a term after the operator (line 1, col 4)
+
+print(eval "(1+1)-1*(/2)")
+--> syntax error: expected an expression after the parenthesis (line 1, col 10)
+
+print(eval "1+(1-(1*2))/2x")
+--> syntax error: extra characters found after the expression (line 1, col 14)
+
+print(eval "-1+(1-(1*2))/2")
+--> syntax error: no expression found (line 1, col 1)
+
+print(eval "(1+1-1*(2/2+)-():")
+--> syntax error: expected a term after the operator (line 1, col 13)
+--> syntax error: expected an expression after the parenthesis (line 1, col 16)
+--> syntax error: missing a closing ')' after the expression (line 1, col 17)
+--> syntax error: extra characters found after the expression (line 1, col 17)