aboutsummaryrefslogtreecommitdiff
path: root/lpeg.html
diff options
context:
space:
mode:
authorRoberto Ierusalimschy <roberto@inf.puc-rio.br>2023-06-19 11:14:02 -0300
committerRoberto Ierusalimschy <roberto@inf.puc-rio.br>2023-06-19 11:14:02 -0300
commit9a9ee3d9ab8ce435d743d293ec43075151370200 (patch)
tree445290bfa04c2cd30f514b65b90b1d8b973f21f1 /lpeg.html
parenta561630f17e61548193666abf9a8b20f20462558 (diff)
downloadlpeg-9a9ee3d9ab8ce435d743d293ec43075151370200.tar.gz
lpeg-9a9ee3d9ab8ce435d743d293ec43075151370200.tar.bz2
lpeg-9a9ee3d9ab8ce435d743d293ec43075151370200.zip
Some fixes in vibibility check for back captures
Diffstat (limited to 'lpeg.html')
-rw-r--r--lpeg.html75
1 files changed, 44 insertions, 31 deletions
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:
608<tr><td><a href="#cap-arg"><code>lpeg.Carg(n)</code></a></td> 608<tr><td><a href="#cap-arg"><code>lpeg.Carg(n)</code></a></td>
609 <td>the value of the n<sup>th</sup> extra argument to 609 <td>the value of the n<sup>th</sup> extra argument to
610 <code>lpeg.match</code> (matches the empty string)</td></tr> 610 <code>lpeg.match</code> (matches the empty string)</td></tr>
611<tr><td><a href="#cap-b"><code>lpeg.Cb(name)</code></a></td> 611<tr><td><a href="#cap-b"><code>lpeg.Cb(key)</code></a></td>
612 <td>the values produced by the previous 612 <td>the values produced by the previous
613 group capture named <code>name</code> 613 group capture named <code>key</code>
614 (matches the empty string)</td></tr> 614 (matches the empty string)</td></tr>
615<tr><td><a href="#cap-cc"><code>lpeg.Cc(values)</code></a></td> 615<tr><td><a href="#cap-cc"><code>lpeg.Cc(values)</code></a></td>
616 <td>the given values (matches the empty string)</td></tr> 616 <td>the given values (matches the empty string)</td></tr>
617<tr><td><a href="#cap-f"><code>lpeg.Cf(patt, func)</code></a></td> 617<tr><td><a href="#cap-f"><code>lpeg.Cf(patt, func)</code></a></td>
618 <td>a <em>folding</em> of the captures from <code>patt</code></td></tr> 618 <td>a <em>folding</em> of the captures from <code>patt</code></td></tr>
619<tr><td><a href="#cap-g"><code>lpeg.Cg(patt [, name])</code></a></td> 619<tr><td><a href="#cap-g"><code>lpeg.Cg(patt [, key])</code></a></td>
620 <td>the values produced by <code>patt</code>, 620 <td>the values produced by <code>patt</code>,
621 optionally tagged with <code>name</code></td></tr> 621 optionally tagged with <code>key</code></td></tr>
622<tr><td><a href="#cap-p"><code>lpeg.Cp()</code></a></td> 622<tr><td><a href="#cap-p"><code>lpeg.Cp()</code></a></td>
623 <td>the current position (matches the empty string)</td></tr> 623 <td>the current position (matches the empty string)</td></tr>
624<tr><td><a href="#cap-s"><code>lpeg.Cs(patt)</code></a></td> 624<tr><td><a href="#cap-s"><code>lpeg.Cs(patt)</code></a></td>
@@ -639,9 +639,10 @@ or no value when <code>number</code> is zero.</td></tr>
639 <td>the returns of <code>function</code> applied to the captures 639 <td>the returns of <code>function</code> applied to the captures
640 of <code>patt</code></td></tr> 640 of <code>patt</code></td></tr>
641<tr><td><a href="#cap-rep"><code>patt % function</code></a></td> 641<tr><td><a href="#cap-rep"><code>patt % function</code></a></td>
642 <td>the return of <code>function</code> applied to the previous 642 <td>produces no value;
643 capture plus the captures of <code>patt</code></td></tr>; 643 it <em>accummulates</em> the captures from <code>patt</code>
644 the returned value becomes the value of the previous capture 644 into the previous capture through <code>function</code>
645 </td></tr>
645<tr><td><a href="#matchtime"><code>lpeg.Cmt(patt, function)</code></a></td> 646<tr><td><a href="#matchtime"><code>lpeg.Cmt(patt, function)</code></a></td>
646 <td>the returns of <code>function</code> applied to the captures 647 <td>the returns of <code>function</code> applied to the captures
647 of <code>patt</code>; the application is done at match time</td></tr> 648 of <code>patt</code>; the application is done at match time</td></tr>
@@ -699,24 +700,25 @@ argument given in the call to <code>lpeg.match</code>.
699</p> 700</p>
700 701
701 702
702<h3><a name="cap-b"></a><code>lpeg.Cb (name)</code></h3> 703<h3><a name="cap-b"></a><code>lpeg.Cb (key)</code></h3>
703<p> 704<p>
704Creates a <em>back capture</em>. 705Creates a <em>back capture</em>.
705This pattern matches the empty string and 706This pattern matches the empty string and
706produces the values produced by the <em>most recent</em> 707produces the values produced by the <em>most recent</em>
707<a href="#cap-g">group capture</a> named <code>name</code> 708<a href="#cap-g">group capture</a> named <code>key</code>
708(where <code>name</code> can be any Lua value). 709(where <code>key</code> can be any Lua value).
709</p> 710</p>
710 711
711<p> 712<p>
712<em>Most recent</em> means the last 713<em>Most recent</em> means the last
713<em>complete</em> 714<em>complete</em>
714<em>outermost</em> 715<em>outermost</em>
715group capture with the given name. 716group capture with the given key.
716A <em>Complete</em> capture means that the entire pattern 717A <em>Complete</em> capture means that the entire pattern
717corresponding to the capture has matched. 718corresponding to the capture has matched;
719in other words, the back capture is not nested inside the group.
718An <em>Outermost</em> capture means that the capture is not inside 720An <em>Outermost</em> capture means that the capture is not inside
719another complete capture. 721another complete capture that does not contain the back capture itself.
720</p> 722</p>
721 723
722<p> 724<p>
@@ -785,13 +787,13 @@ print(sum:match("10,30,43")) --&gt; 83
785</pre> 787</pre>
786 788
787 789
788<h3><a name="cap-g"></a><code>lpeg.Cg (patt [, name])</code></h3> 790<h3><a name="cap-g"></a><code>lpeg.Cg (patt [, key])</code></h3>
789<p> 791<p>
790Creates a <em>group capture</em>. 792Creates a <em>group capture</em>.
791It groups all values returned by <code>patt</code> 793It groups all values returned by <code>patt</code>
792into a single capture. 794into a single capture.
793The group may be anonymous (if no name is given) 795The group may be anonymous (if no key is given)
794or named with the given name 796or named with the given key
795(which can be any non-nil Lua value). 797(which can be any non-nil Lua value).
796</p> 798</p>
797 799
@@ -837,7 +839,7 @@ starting at 1.
837Moreover, 839Moreover,
838for each named capture group created by <code>patt</code>, 840for each named capture group created by <code>patt</code>,
839the first value of the group is put into the table 841the first value of the group is put into the table
840with the group name as its key. 842with the group key as its key.
841The captured value is only the table. 843The captured value is only the table.
842</p> 844</p>
843 845
@@ -897,12 +899,14 @@ there is no captured value.
897<p> 899<p>
898Creates an <em>accumulator capture</em>. 900Creates an <em>accumulator capture</em>.
899This pattern behaves similarly to a 901This pattern behaves similarly to a
900<a href="cap-func">function capture</a>, 902<a href="#cap-func">function capture</a>,
901with the following differences: 903with the following differences:
902The last captured value is added as a first argument to 904The last captured value is added as a first argument to
903the call; 905the call;
904the return of the function is adjusted to one single value; 906the return of the function is adjusted to one single value;
905that value becomes the last captured value. 907that value replaces the last captured value.
908Note that the capture itself produces no values;
909it only changes the value of its previous capture.
906</p> 910</p>
907 911
908<p> 912<p>
@@ -929,6 +933,12 @@ changed to upper case;
929that value then becomes the first and only 933that value then becomes the first and only
930capture value created by the match. 934capture value created by the match.
931</p> 935</p>
936
937<p>
938As another example,
939let us consider the problem of adding a list of numbers.
940</p>
941<pre class="example">
932-- matches a numeral and captures its numerical value 942-- matches a numeral and captures its numerical value
933number = lpeg.R"09"^1 / tonumber 943number = lpeg.R"09"^1 / tonumber
934 944
@@ -944,11 +954,11 @@ print(sum:match("10,30,43")) --&gt; 83
944<p> 954<p>
945First, the initial <code>number</code> captures a number; 955First, the initial <code>number</code> captures a number;
946that first capture will play the role of an accumulator. 956that first capture will play the role of an accumulator.
947Then, each time <code>number</code> matches inside the loop 957Then, each time the sequence <code>comma-number</code>
948there is a accumulator capture: 958matches inside the loop there is an accumulator capture:
949It calls <code>add</code> with the current value of the accumulator 959It calls <code>add</code> with the current value of the accumulator
950and the value of the new number, 960and the value of the new number,
951and their sum replaces the value of the accumulator. 961and the result of the call (their sum) replaces the value of the accumulator.
952At the end of the match, 962At the end of the match,
953the accumulator with all sums is the final value. 963the accumulator with all sums is the final value.
954</p> 964</p>
@@ -956,9 +966,12 @@ the accumulator with all sums is the final value.
956<p> 966<p>
957Due to the nature of this capture, 967Due to the nature of this capture,
958you should avoid using it in places where it is not clear 968you should avoid using it in places where it is not clear
959what is its "previous" capture. 969what is its "previous" capture
970(e.g., directly nested in a <a href="#cap-string">string capture</a>
971or a <a href="#cap-num">numbered capture</a>).
960Due to implementation details, 972Due to implementation details,
961you should not use this capture inside a substitution capture. 973you should not use this capture directly nested in a
974<a href="#cap-s">substitution capture</a>.
962</p> 975</p>
963 976
964 977
@@ -1014,9 +1027,9 @@ local lpeg = require "lpeg"
1014-- matches a word followed by end-of-string 1027-- matches a word followed by end-of-string
1015p = lpeg.R"az"^1 * -1 1028p = lpeg.R"az"^1 * -1
1016 1029
1017print(p:match("hello")) --> 6 1030print(p:match("hello")) --&gt; 6
1018print(lpeg.match(p, "hello")) --> 6 1031print(lpeg.match(p, "hello")) --&gt; 6
1019print(p:match("1 hello")) --> nil 1032print(p:match("1 hello")) --&gt; nil
1020</pre> 1033</pre>
1021<p> 1034<p>
1022The pattern is simply a sequence of one or more lower-case letters 1035The pattern is simply a sequence of one or more lower-case letters
@@ -1043,7 +1056,7 @@ local name = lpeg.C(lpeg.alpha^1) * space
1043local sep = lpeg.S(",;") * space 1056local sep = lpeg.S(",;") * space
1044local pair = name * "=" * space * name * sep^-1 1057local pair = name * "=" * space * name * sep^-1
1045local list = lpeg.Ct("") * (pair % rawset)^0 1058local list = lpeg.Ct("") * (pair % rawset)^0
1046t = list:match("a=b, c = hi; next = pi") --> { a = "b", c = "hi", next = "pi" } 1059t = list:match("a=b, c = hi; next = pi") --&gt; { a = "b", c = "hi", next = "pi" }
1047</pre> 1060</pre>
1048<p> 1061<p>
1049Each pair has the format <code>name = name</code> followed by 1062Each pair has the format <code>name = name</code> followed by
@@ -1135,7 +1148,7 @@ function anywhere (p)
1135 return lpeg.P{ I * p * I + 1 * lpeg.V(1) } 1148 return lpeg.P{ I * p * I + 1 * lpeg.V(1) }
1136end 1149end
1137 1150
1138print(anywhere("world"):match("hello world!")) -> 7 12 1151print(anywhere("world"):match("hello world!")) --&gt; 7 12
1139</pre> 1152</pre>
1140 1153
1141<p> 1154<p>
@@ -1344,7 +1357,7 @@ function evalExp (s)
1344end 1357end
1345 1358
1346-- small example 1359-- small example
1347print(evalExp"3 + 5*9 / (1+1) - 12") --> 13.5 1360print(evalExp"3 + 5*9 / (1+1) - 12") --&gt; 13.5
1348</pre> 1361</pre>
1349 1362
1350<p> 1363<p>
@@ -1372,7 +1385,7 @@ G = lpeg.P{ "Exp",
1372} 1385}
1373 1386
1374-- small example 1387-- small example
1375print(lpeg.match(G, "3 + 5*9 / (1+1) - 12")) --> 13.5 1388print(lpeg.match(G, "3 + 5*9 / (1+1) - 12")) --&gt; 13.5
1376</pre> 1389</pre>
1377<p> 1390<p>
1378Note the use of the accumulator capture. 1391Note the use of the accumulator capture.