Adding to README an example about farthest failure

2 files changed, 37 insertions, 0 deletions

diff --git a/README.md b/README.md
index 907802f..ddad3c8 100644
--- a/README.md
+++ b/README.md
@@ -119,6 +119,29 @@ The code of these and of other examples is available
 in the *examples* directory. 
 
 
+#### Reporting the farthest failure
+
+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
+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)
+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
+```
+
 #### 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
new file mode 100644
index 0000000..692390f
--- /dev/null
+++ b/examples/farthest.lua
@@ -0,0 +1,14 @@
+local m = require'lpeglabel'
+
+function matchPrint(p, s)
+        local r, lab, sfail = p:match(s)
+        print("r: ", r, "lab: ", lab, "sfail: ", sfail)
+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
+
+