diff options
author | Roberto Ierusalimschy <roberto@inf.puc-rio.br> | 2023-06-23 14:55:48 -0300 |
---|---|---|
committer | Roberto Ierusalimschy <roberto@inf.puc-rio.br> | 2023-06-23 14:55:48 -0300 |
commit | 8bc00db24975f52b52e6ef8184c216ce2feae9fd (patch) | |
tree | b085c7baa0a36104621845c74877b0726faca9ef /lpeg.html | |
parent | 7d43b367e7a89369c1302124677a305aa0d070c7 (diff) | |
download | lpeg-8bc00db24975f52b52e6ef8184c216ce2feae9fd.tar.gz lpeg-8bc00db24975f52b52e6ef8184c216ce2feae9fd.tar.bz2 lpeg-8bc00db24975f52b52e6ef8184c216ce2feae9fd.zip |
Fold capture deprecated
Diffstat (limited to 'lpeg.html')
-rw-r--r-- | lpeg.html | 68 |
1 files changed, 16 insertions, 52 deletions
@@ -444,7 +444,8 @@ letter = lower + upper | |||
444 | 444 | ||
445 | <h3><a name="op-sub"></a><code>patt1 - patt2</code></h3> | 445 | <h3><a name="op-sub"></a><code>patt1 - patt2</code></h3> |
446 | <p> | 446 | <p> |
447 | Returns a pattern equivalent to <em>!patt2 patt1</em>. | 447 | Returns a pattern equivalent to <em>!patt2 patt1</em> |
448 | in the origial PEG notation. | ||
448 | This pattern asserts that the input does not match | 449 | This pattern asserts that the input does not match |
449 | <code>patt2</code> and then matches <code>patt1</code>. | 450 | <code>patt2</code> and then matches <code>patt1</code>. |
450 | </p> | 451 | </p> |
@@ -615,7 +616,7 @@ The following table summarizes the basic captures: | |||
615 | <tr><td><a href="#cap-cc"><code>lpeg.Cc(values)</code></a></td> | 616 | <tr><td><a href="#cap-cc"><code>lpeg.Cc(values)</code></a></td> |
616 | <td>the given values (matches the empty string)</td></tr> | 617 | <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> | 618 | <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> | 619 | <td>folding capture (<em>deprecated</em>)</td></tr> |
619 | <tr><td><a href="#cap-g"><code>lpeg.Cg(patt [, key])</code></a></td> | 620 | <tr><td><a href="#cap-g"><code>lpeg.Cg(patt [, key])</code></a></td> |
620 | <td>the values produced by <code>patt</code>, | 621 | <td>the values produced by <code>patt</code>, |
621 | optionally tagged with <code>key</code></td></tr> | 622 | optionally tagged with <code>key</code></td></tr> |
@@ -638,7 +639,7 @@ or no value when <code>number</code> is zero.</td></tr> | |||
638 | <tr><td><a href="#cap-func"><code>patt / function</code></a></td> | 639 | <tr><td><a href="#cap-func"><code>patt / function</code></a></td> |
639 | <td>the returns of <code>function</code> applied to the captures | 640 | <td>the returns of <code>function</code> applied to the captures |
640 | of <code>patt</code></td></tr> | 641 | of <code>patt</code></td></tr> |
641 | <tr><td><a href="#cap-rep"><code>patt % function</code></a></td> | 642 | <tr><td><a href="#cap-acc"><code>patt % function</code></a></td> |
642 | <td>produces no value; | 643 | <td>produces no value; |
643 | it <em>accummulates</em> the captures from <code>patt</code> | 644 | it <em>accummulates</em> the captures from <code>patt</code> |
644 | into the previous capture through <code>function</code> | 645 | into the previous capture through <code>function</code> |
@@ -739,52 +740,12 @@ produces all given values as its captured values. | |||
739 | <h3><a name="cap-f"></a><code>lpeg.Cf (patt, func)</code></h3> | 740 | <h3><a name="cap-f"></a><code>lpeg.Cf (patt, func)</code></h3> |
740 | <p> | 741 | <p> |
741 | Creates a <em>fold capture</em>. | 742 | Creates a <em>fold capture</em>. |
742 | If <code>patt</code> produces a list of captures | 743 | This construction is deprecated; |
743 | <em>C<sub>1</sub> C<sub>2</sub> ... C<sub>n</sub></em>, | 744 | use an <a href="#cap-acc">accumulator pattern</a> instead. |
744 | this capture will produce the value | 745 | In general, a fold like |
745 | <em>func(...func(func(C<sub>1</sub>, C<sub>2</sub>), C<sub>3</sub>)..., | 746 | <code>lpeg.Cf(p1 * p2^0, func)</code> |
746 | C<sub>n</sub>)</em>, | 747 | can be translated to |
747 | that is, it will <em>fold</em> | 748 | <code>(p1 * (p2 % func)^0)</code>. |
748 | (or <em>accumulate</em>, or <em>reduce</em>) | ||
749 | the captures from <code>patt</code> using function <code>func</code>. | ||
750 | </p> | ||
751 | |||
752 | <p> | ||
753 | This capture assumes that <code>patt</code> should produce | ||
754 | at least one capture with at least one value (of any type), | ||
755 | which becomes the initial value of an <em>accumulator</em>. | ||
756 | (If you need a specific initial value, | ||
757 | you may prefix a <a href="#cap-cc">constant capture</a> to <code>patt</code>.) | ||
758 | For each subsequent capture, | ||
759 | LPeg calls <code>func</code> | ||
760 | with this accumulator as the first argument and all values produced | ||
761 | by the capture as extra arguments; | ||
762 | the first result from this call | ||
763 | becomes the new value for the accumulator. | ||
764 | The final value of the accumulator becomes the captured value. | ||
765 | </p> | ||
766 | |||
767 | <p> | ||
768 | As an example, | ||
769 | the following pattern matches a list of numbers separated | ||
770 | by commas and returns their addition: | ||
771 | </p> | ||
772 | <pre class="example"> | ||
773 | -- matches a numeral and captures its numerical value | ||
774 | number = lpeg.R"09"^1 / tonumber | ||
775 | |||
776 | -- matches a list of numbers, capturing their values | ||
777 | list = number * ("," * number)^0 | ||
778 | |||
779 | -- auxiliary function to add two numbers | ||
780 | function add (acc, newvalue) return acc + newvalue end | ||
781 | |||
782 | -- folds the list of numbers adding them | ||
783 | sum = lpeg.Cf(list, add) | ||
784 | |||
785 | -- example of use | ||
786 | print(sum:match("10,30,43")) --> 83 | ||
787 | </pre> | ||
788 | 749 | ||
789 | 750 | ||
790 | <h3><a name="cap-g"></a><code>lpeg.Cg (patt [, key])</code></h3> | 751 | <h3><a name="cap-g"></a><code>lpeg.Cg (patt [, key])</code></h3> |
@@ -895,7 +856,7 @@ there is no captured value. | |||
895 | </p> | 856 | </p> |
896 | 857 | ||
897 | 858 | ||
898 | <h3><a name="cap-rep"></a><code>patt % function</code></h3> | 859 | <h3><a name="cap-acc"></a><code>patt % function</code></h3> |
899 | <p> | 860 | <p> |
900 | Creates an <em>accumulator capture</em>. | 861 | Creates an <em>accumulator capture</em>. |
901 | This pattern behaves similarly to a | 862 | This pattern behaves similarly to a |
@@ -977,7 +938,10 @@ all their subcaptures to compute their results.) | |||
977 | Moreover, due to implementation details, | 938 | Moreover, due to implementation details, |
978 | you should not use this capture directly nested in a | 939 | you should not use this capture directly nested in a |
979 | <a href="#cap-s">substitution capture</a>. | 940 | <a href="#cap-s">substitution capture</a>. |
980 | A simple and effective way to avoid these issues is | 941 | You should also avoid a direct nesting of this capture inside |
942 | a <a href="#cap-f">folding capture</a> (deprecated), | ||
943 | as the folding will try to fold each individual accumulator capture. | ||
944 | A simple and effective way to avoid all these issues is | ||
981 | to enclose the whole accumulation composition | 945 | to enclose the whole accumulation composition |
982 | (including the capture that generates the initial value) | 946 | (including the capture that generates the initial value) |
983 | into an anonymous <a href="#cap-g">group capture</a>. | 947 | into an anonymous <a href="#cap-g">group capture</a>. |
@@ -1411,7 +1375,7 @@ and the new term for each repetition. | |||
1411 | <h2><a name="download"></a>Download</h2> | 1375 | <h2><a name="download"></a>Download</h2> |
1412 | 1376 | ||
1413 | <p>LPeg | 1377 | <p>LPeg |
1414 | <a href="http://www.inf.puc-rio.br/~roberto/lpeg/lpeg-1.0.2.tar.gz">source code</a>.</p> | 1378 | <a href="http://www.inf.puc-rio.br/~roberto/lpeg/lpeg-1.1.0.tar.gz">source code</a>.</p> |
1415 | 1379 | ||
1416 | <p> | 1380 | <p> |
1417 | Probably, the easiest way to install LPeg is with | 1381 | Probably, the easiest way to install LPeg is with |