From e0feb1b3a659411d53b231d24929c4b7b4d92431 Mon Sep 17 00:00:00 2001 From: Sergio Queiroz Date: Tue, 3 Jan 2017 11:06:56 -0300 Subject: Updating README to mention the farthest failure position feature --- README.md | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5deec35..907802f 100644 --- a/README.md +++ b/README.md @@ -9,27 +9,38 @@ LPegLabel is a conservative extension of the [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg) library that provides an implementation of Parsing -Expression Grammars (PEGs) with labeled failures. +Expression Grammars (PEGs) with labeled failures. Labels can be used to signal different kinds of errors and to specify which recovery pattern should handle a given label. Labels can also be combined with the standard -patterns of LPeg. +patterns of LPeg. + +Besides that, LPegLabel also reports the farthest +failure position in case of an ordinary failure +(which is represented by label **0**). This document describes the new functions available in LpegLabel and presents some examples of usage. +With labeled failures it is possible to distinguish +between an ordinary failure and an error. Usually, an +ordinary failure is produced when the matching of a +character fails, and this failure is caught by ordered choice. +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 the label associated with the failure, and **sfail** is the suffix input being matched when **lab** was thrown. -With labeled failures it is possible to distinguish -between a regular failure and an error. Usually, a -regular failure is produced when the matching of a -character fails, and it is caught by an ordered choice. -An error, by its turn, is produced by the throw operator -and may be caught by the recovery operator. +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. +In case **lab** is an ordinary failure and an error +was thrown before, **sfail** is the farthest suffix +where an ordinary failure occurred after the last error. Below there is a brief summary of the new functions provided by LpegLabel: @@ -60,10 +71,13 @@ Below there is a brief summary of the new functions provided by LpegLabel: #### lpeglabel.T(l) - 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 +whether this is the farthest failure position or not. + #### lpeglabel.Rec(p1, p2, l1, ..., ln) @@ -73,7 +87,6 @@ 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. - #### %{l} Syntax of *relabel* module. Equivalent to `lpeg.T(l)`. -- cgit v1.2.3-55-g6feb