From 9a9ee3d9ab8ce435d743d293ec43075151370200 Mon Sep 17 00:00:00 2001 From: Roberto Ierusalimschy Date: Mon, 19 Jun 2023 11:14:02 -0300 Subject: Some fixes in vibibility check for back captures --- lpeg.html | 75 +++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 31 deletions(-) (limited to 'lpeg.html') diff --git a/lpeg.html b/lpeg.html index 9faa1c7..c9bd9f9 100644 --- a/lpeg.html +++ b/lpeg.html @@ -608,17 +608,17 @@ The following table summarizes the basic captures: lpeg.Carg(n) the value of the nth extra argument to lpeg.match (matches the empty string) -lpeg.Cb(name) +lpeg.Cb(key) the values produced by the previous - group capture named name + group capture named key (matches the empty string) lpeg.Cc(values) the given values (matches the empty string) lpeg.Cf(patt, func) a folding of the captures from patt -lpeg.Cg(patt [, name]) +lpeg.Cg(patt [, key]) the values produced by patt, - optionally tagged with name + optionally tagged with key lpeg.Cp() the current position (matches the empty string) lpeg.Cs(patt) @@ -639,9 +639,10 @@ or no value when number is zero. the returns of function applied to the captures of patt patt % function - the return of function applied to the previous - capture plus the captures of patt; - the returned value becomes the value of the previous capture + produces no value; + it accummulates the captures from patt + into the previous capture through function + lpeg.Cmt(patt, function) the returns of function applied to the captures of patt; the application is done at match time @@ -699,24 +700,25 @@ argument given in the call to lpeg.match.

-

lpeg.Cb (name)

+

lpeg.Cb (key)

Creates a back capture. This pattern matches the empty string and produces the values produced by the most recent -group capture named name -(where name can be any Lua value). +group capture named key +(where key can be any Lua value).

Most recent means the last complete outermost -group capture with the given name. +group capture with the given key. A Complete capture means that the entire pattern -corresponding to the capture has matched. +corresponding to the capture has matched; +in other words, the back capture is not nested inside the group. An Outermost capture means that the capture is not inside -another complete capture. +another complete capture that does not contain the back capture itself.

@@ -785,13 +787,13 @@ print(sum:match("10,30,43")) --> 83 -

lpeg.Cg (patt [, name])

+

lpeg.Cg (patt [, key])

Creates a group capture. It groups all values returned by patt into a single capture. -The group may be anonymous (if no name is given) -or named with the given name +The group may be anonymous (if no key is given) +or named with the given key (which can be any non-nil Lua value).

@@ -837,7 +839,7 @@ starting at 1. Moreover, for each named capture group created by patt, the first value of the group is put into the table -with the group name as its key. +with the group key as its key. The captured value is only the table.

@@ -897,12 +899,14 @@ there is no captured value.

Creates an accumulator capture. This pattern behaves similarly to a -function capture, +function capture, with the following differences: The last captured value is added as a first argument to the call; the return of the function is adjusted to one single value; -that value becomes the last captured value. +that value replaces the last captured value. +Note that the capture itself produces no values; +it only changes the value of its previous capture.

@@ -929,6 +933,12 @@ changed to upper case; that value then becomes the first and only capture value created by the match.

+ +

+As another example, +let us consider the problem of adding a list of numbers. +

+
 -- matches a numeral and captures its numerical value
 number = lpeg.R"09"^1 / tonumber
 
@@ -944,11 +954,11 @@ print(sum:match("10,30,43"))   --> 83
 

 First, the initial number captures a number;
 that first capture will play the role of an accumulator.
-Then, each time number matches inside the loop
-there is a accumulator capture:
+Then, each time the sequence comma-number
+matches inside the loop there is an accumulator capture:
 It calls add with the current value of the accumulator
 and the value of the new number,
-and their sum replaces the value of the accumulator.
+and the result of the call (their sum) replaces the value of the accumulator.
 At the end of the match,
 the accumulator with all sums is the final value.
 

@@ -956,9 +966,12 @@ the accumulator with all sums is the final value.
 

 Due to the nature of this capture,
 you should avoid using it in places where it is not clear
-what is its "previous" capture.
+what is its "previous" capture
+(e.g., directly nested in a string capture
+or a numbered capture).
 Due to implementation details,
-you should not use this capture inside a substitution capture.
+you should not use this capture directly nested in a
+substitution capture.
 

 
 
@@ -1014,9 +1027,9 @@ local lpeg = require "lpeg"
 -- matches a word followed by end-of-string
 p = lpeg.R"az"^1 * -1
 
-print(p:match("hello"))        --> 6
-print(lpeg.match(p, "hello"))  --> 6
-print(p:match("1 hello"))      --> nil
+print(p:match("hello"))        --> 6
+print(lpeg.match(p, "hello"))  --> 6
+print(p:match("1 hello"))      --> nil

The pattern is simply a sequence of one or more lower-case letters @@ -1043,7 +1056,7 @@ local name = lpeg.C(lpeg.alpha^1) * space local sep = lpeg.S(",;") * space local pair = name * "=" * space * name * sep^-1 local list = lpeg.Ct("") * (pair % rawset)^0 -t = list:match("a=b, c = hi; next = pi") --> { a = "b", c = "hi", next = "pi" } +t = list:match("a=b, c = hi; next = pi") --> { a = "b", c = "hi", next = "pi" }

Each pair has the format name = name followed by @@ -1135,7 +1148,7 @@ function anywhere (p) return lpeg.P{ I * p * I + 1 * lpeg.V(1) } end -print(anywhere("world"):match("hello world!")) -> 7 12 +print(anywhere("world"):match("hello world!")) --> 7 12

@@ -1344,7 +1357,7 @@ function evalExp (s) end -- small example -print(evalExp"3 + 5*9 / (1+1) - 12") --> 13.5 +print(evalExp"3 + 5*9 / (1+1) - 12") --> 13.5

@@ -1372,7 +1385,7 @@ G = lpeg.P{ "Exp", } -- small example -print(lpeg.match(G, "3 + 5*9 / (1+1) - 12")) --> 13.5 +print(lpeg.match(G, "3 + 5*9 / (1+1) - 12")) --> 13.5

Note the use of the accumulator capture. -- cgit v1.2.3-55-g6feb