-
Notifications
You must be signed in to change notification settings - Fork 10
/
lpeg.html
1439 lines (1238 loc) · 42.2 KB
/
lpeg.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>LPeg - Parsing Expression Grammars For Lua</title>
<link rel="stylesheet"
href="http://www.inf.puc-rio.br/~roberto/lpeg/doc.css"
type="text/css"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<!-- $Id: lpeg.html $ -->
<div id="container">
<div id="product">
<div id="product_logo">
<a href="http://www.inf.puc-rio.br/~roberto/lpeg/">
<img alt="LPeg logo" src="lpeg-128.gif"/></a>
</div>
<div id="product_name"><big><strong>LPeg</strong></big></div>
<div id="product_description">
Parsing Expression Grammars For Lua, version 1.0
</div>
</div> <!-- id="product" -->
<div id="main">
<div id="navigation">
<h1>LPeg</h1>
<ul>
<li><strong>Home</strong>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#func">Functions</a></li>
<li><a href="#basic">Basic Constructions</a></li>
<li><a href="#grammar">Grammars</a></li>
<li><a href="#captures">Captures</a></li>
<li><a href="#ex">Some Examples</a></li>
<li><a href="re.html">The <code>re</code> Module</a></li>
<li><a href="#download">Download</a></li>
<li><a href="#license">License</a></li>
</ul>
</li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2><a name="intro">Introduction</a></h2>
<p>
<em>LPeg</em> is a new pattern-matching library for Lua,
based on
<a href="http://pdos.csail.mit.edu/%7Ebaford/packrat/">
Parsing Expression Grammars</a> (PEGs).
This text is a reference manual for the library.
For a more formal treatment of LPeg,
as well as some discussion about its implementation,
see
<a href="http://www.inf.puc-rio.br/~roberto/docs/peg.pdf">
A Text Pattern-Matching Tool based on Parsing Expression Grammars</a>.
(You may also be interested in my
<a href="http://vimeo.com/1485123">talk about LPeg</a>
given at the III Lua Workshop.)
</p>
<p>
Following the Snobol tradition,
LPeg defines patterns as first-class objects.
That is, patterns are regular Lua values
(represented by userdata).
The library offers several functions to create
and compose patterns.
With the use of metamethods,
several of these functions are provided as infix or prefix
operators.
On the one hand,
the result is usually much more verbose than the typical
encoding of patterns using the so called
<em>regular expressions</em>
(which typically are not regular expressions in the formal sense).
On the other hand,
first-class patterns allow much better documentation
(as it is easy to comment the code,
to break complex definitions in smaller parts, etc.)
and are extensible,
as we can define new functions to create and compose patterns.
</p>
<p>
For a quick glance of the library,
the following table summarizes its basic operations
for creating patterns:
</p>
<table border="1">
<tbody><tr><td><b>Operator</b></td><td><b>Description</b></td></tr>
<tr><td><a href="#op-p"><code>lpeg.P(string)</code></a></td>
<td>Matches <code>string</code> literally</td></tr>
<tr><td><a href="#op-p"><code>lpeg.P(n)</code></a></td>
<td>Matches exactly <code>n</code> characters</td></tr>
<tr><td><a href="#op-s"><code>lpeg.S(string)</code></a></td>
<td>Matches any character in <code>string</code> (Set)</td></tr>
<tr><td><a href="#op-r"><code>lpeg.R("<em>xy</em>")</code></a></td>
<td>Matches any character between <em>x</em> and <em>y</em> (Range)</td></tr>
<tr><td><a href="#op-pow"><code>patt^n</code></a></td>
<td>Matches at least <code>n</code> repetitions of <code>patt</code></td></tr>
<tr><td><a href="#op-pow"><code>patt^-n</code></a></td>
<td>Matches at most <code>n</code> repetitions of <code>patt</code></td></tr>
<tr><td><a href="#op-mul"><code>patt1 * patt2</code></a></td>
<td>Matches <code>patt1</code> followed by <code>patt2</code></td></tr>
<tr><td><a href="#op-add"><code>patt1 + patt2</code></a></td>
<td>Matches <code>patt1</code> or <code>patt2</code>
(ordered choice)</td></tr>
<tr><td><a href="#op-sub"><code>patt1 - patt2</code></a></td>
<td>Matches <code>patt1</code> if <code>patt2</code> does not match</td></tr>
<tr><td><a href="#op-unm"><code>-patt</code></a></td>
<td>Equivalent to <code>("" - patt)</code></td></tr>
<tr><td><a href="#op-len"><code>#patt</code></a></td>
<td>Matches <code>patt</code> but consumes no input</td></tr>
<tr><td><a href="#op-behind"><code>lpeg.B(patt)</code></a></td>
<td>Matches <code>patt</code> behind the current position,
consuming no input</td></tr>
</tbody></table>
<p>As a very simple example,
<code>lpeg.R("09")^1</code> creates a pattern that
matches a non-empty sequence of digits.
As a not so simple example,
<code>-lpeg.P(1)</code>
(which can be written as <code>lpeg.P(-1)</code>,
or simply <code>-1</code> for operations expecting a pattern)
matches an empty string only if it cannot match a single character;
so, it succeeds only at the end of the subject.
</p>
<p>
LPeg also offers the <a href="re.html"><code>re</code> module</a>,
which implements patterns following a regular-expression style
(e.g., <code>[09]+</code>).
(This module is 260 lines of Lua code,
and of course it uses LPeg to parse regular expressions and
translate them to regular LPeg patterns.)
</p>
<h2><a name="func">Functions</a></h2>
<h3><a name="f-match"></a><code>lpeg.match (pattern, subject [, init])</code></h3>
<p>
The matching function.
It attempts to match the given pattern against the subject string.
If the match succeeds,
returns the index in the subject of the first character after the match,
or the <a href="#captures">captured values</a>
(if the pattern captured any value).
</p>
<p>
An optional numeric argument <code>init</code> makes the match
start at that position in the subject string.
As usual in Lua libraries,
a negative value counts from the end.
</p>
<p>
Unlike typical pattern-matching functions,
<code>match</code> works only in <em>anchored</em> mode;
that is, it tries to match the pattern with a prefix of
the given subject string (at position <code>init</code>),
not with an arbitrary substring of the subject.
So, if we want to find a pattern anywhere in a string,
we must either write a loop in Lua or write a pattern that
matches anywhere.
This second approach is easy and quite efficient;
see <a href="#ex">examples</a>.
</p>
<h3><a name="f-type"></a><code>lpeg.type (value)</code></h3>
<p>
If the given value is a pattern,
returns the string <code>"pattern"</code>.
Otherwise returns nil.
</p>
<h3><a name="f-version"></a><code>lpeg.version ()</code></h3>
<p>
Returns a string with the running version of LPeg.
</p>
<h3><a name="f-setstack"></a><code>lpeg.setmaxstack (max)</code></h3>
<p>
Sets a limit for the size of the backtrack stack used by LPeg to
track calls and choices.
(The default limit is 400.)
Most well-written patterns need little backtrack levels and
therefore you seldom need to change this limit;
before changing it you should try to rewrite your
pattern to avoid the need for extra space.
Nevertheless, a few useful patterns may overflow.
Also, with recursive grammars,
subjects with deep recursion may also need larger limits.
</p>
<h2><a name="basic">Basic Constructions</a></h2>
<p>
The following operations build patterns.
All operations that expect a pattern as an argument
may receive also strings, tables, numbers, booleans, or functions,
which are translated to patterns according to
the rules of function <a href="#op-p"><code>lpeg.P</code></a>.
</p>
<h3><a name="op-p"></a><code>lpeg.P (value)</code></h3>
<p>
Converts the given value into a proper pattern,
according to the following rules:
</p>
<ul>
<li><p>
If the argument is a pattern,
it is returned unmodified.
</p></li>
<li><p>
If the argument is a string,
it is translated to a pattern that matches the string literally.
</p></li>
<li><p>
If the argument is a non-negative number <em>n</em>,
the result is a pattern that matches exactly <em>n</em> characters.
</p></li>
<li><p>
If the argument is a negative number <em>-n</em>,
the result is a pattern that
succeeds only if the input string has less than <em>n</em> characters left:
<code>lpeg.P(-n)</code>
is equivalent to <code>-lpeg.P(n)</code>
(see the <a href="#op-unm">unary minus operation</a>).
</p></li>
<li><p>
If the argument is a boolean,
the result is a pattern that always succeeds or always fails
(according to the boolean value),
without consuming any input.
</p></li>
<li><p>
If the argument is a table,
it is interpreted as a grammar
(see <a href="#grammar">Grammars</a>).
</p></li>
<li><p>
If the argument is a function,
returns a pattern equivalent to a
<a href="#matchtime">match-time capture</a> over the empty string.
</p></li>
</ul>
<h3><a name="op-behind"></a><code>lpeg.B(patt)</code></h3>
<p>
Returns a pattern that
matches only if the input string at the current position
is preceded by <code>patt</code>.
Pattern <code>patt</code> must match only strings
with some fixed length,
and it cannot contain captures.
</p>
<p>
Like the <a href="#op-len">and predicate</a>,
this pattern never consumes any input,
independently of success or failure.
</p>
<h3><a name="op-r"></a><code>lpeg.R ({range})</code></h3>
<p>
Returns a pattern that matches any single character
belonging to one of the given <em>ranges</em>.
Each <code>range</code> is a string <em>xy</em> of length 2,
representing all characters with code
between the codes of <em>x</em> and <em>y</em>
(both inclusive).
</p>
<p>
As an example, the pattern
<code>lpeg.R("09")</code> matches any digit,
and <code>lpeg.R("az", "AZ")</code> matches any ASCII letter.
</p>
<h3><a name="op-s"></a><code>lpeg.S (string)</code></h3>
<p>
Returns a pattern that matches any single character that
appears in the given string.
(The <code>S</code> stands for <em>Set</em>.)
</p>
<p>
As an example, the pattern
<code>lpeg.S("+-*/")</code> matches any arithmetic operator.
</p>
<p>
Note that, if <code>s</code> is a character
(that is, a string of length 1),
then <code>lpeg.P(s)</code> is equivalent to <code>lpeg.S(s)</code>
which is equivalent to <code>lpeg.R(s..s)</code>.
Note also that both <code>lpeg.S("")</code> and <code>lpeg.R()</code>
are patterns that always fail.
</p>
<h3><a name="op-v"></a><code>lpeg.V (v)</code></h3>
<p>
This operation creates a non-terminal (a <em>variable</em>)
for a grammar.
The created non-terminal refers to the rule indexed by <code>v</code>
in the enclosing grammar.
(See <a href="#grammar">Grammars</a> for details.)
</p>
<h3><a name="op-locale"></a><code>lpeg.locale ([table])</code></h3>
<p>
Returns a table with patterns for matching some character classes
according to the current locale.
The table has fields named
<code>alnum</code>,
<code>alpha</code>,
<code>cntrl</code>,
<code>digit</code>,
<code>graph</code>,
<code>lower</code>,
<code>print</code>,
<code>punct</code>,
<code>space</code>,
<code>upper</code>, and
<code>xdigit</code>,
each one containing a correspondent pattern.
Each pattern matches any single character that belongs to its class.
</p>
<p>
If called with an argument <code>table</code>,
then it creates those fields inside the given table and
returns that table.
</p>
<h3><a name="op-len"></a><code>#patt</code></h3>
<p>
Returns a pattern that
matches only if the input string matches <code>patt</code>,
but without consuming any input,
independently of success or failure.
(This pattern is called an <em>and predicate</em>
and it is equivalent to
<em>&patt</em> in the original PEG notation.)
</p>
<p>
This pattern never produces any capture.
</p>
<h3><a name="op-unm"></a><code>-patt</code></h3>
<p>
Returns a pattern that
matches only if the input string does not match <code>patt</code>.
It does not consume any input,
independently of success or failure.
(This pattern is equivalent to
<em>!patt</em> in the original PEG notation.)
</p>
<p>
As an example, the pattern
<code>-lpeg.P(1)</code> matches only the end of string.
</p>
<p>
This pattern never produces any captures,
because either <code>patt</code> fails
or <code>-patt</code> fails.
(A failing pattern never produces captures.)
</p>
<h3><a name="op-add"></a><code>patt1 + patt2</code></h3>
<p>
Returns a pattern equivalent to an <em>ordered choice</em>
of <code>patt1</code> and <code>patt2</code>.
(This is denoted by <em>patt1 / patt2</em> in the original PEG notation,
not to be confused with the <code>/</code> operation in LPeg.)
It matches either <code>patt1</code> or <code>patt2</code>,
with no backtracking once one of them succeeds.
The identity element for this operation is the pattern
<code>lpeg.P(false)</code>,
which always fails.
</p>
<p>
If both <code>patt1</code> and <code>patt2</code> are
character sets,
this operation is equivalent to set union.
</p>
<pre class="example">
lower = lpeg.R("az")
upper = lpeg.R("AZ")
letter = lower + upper
</pre>
<h3><a name="op-sub"></a><code>patt1 - patt2</code></h3>
<p>
Returns a pattern equivalent to <em>!patt2 patt1</em>.
This pattern asserts that the input does not match
<code>patt2</code> and then matches <code>patt1</code>.
</p>
<p>
When successful,
this pattern produces all captures from <code>patt1</code>.
It never produces any capture from <code>patt2</code>
(as either <code>patt2</code> fails or
<code>patt1 - patt2</code> fails).
</p>
<p>
If both <code>patt1</code> and <code>patt2</code> are
character sets,
this operation is equivalent to set difference.
Note that <code>-patt</code> is equivalent to <code>"" - patt</code>
(or <code>0 - patt</code>).
If <code>patt</code> is a character set,
<code>1 - patt</code> is its complement.
</p>
<h3><a name="op-mul"></a><code>patt1 * patt2</code></h3>
<p>
Returns a pattern that matches <code>patt1</code>
and then matches <code>patt2</code>,
starting where <code>patt1</code> finished.
The identity element for this operation is the
pattern <code>lpeg.P(true)</code>,
which always succeeds.
</p>
<p>
(LPeg uses the <code>*</code> operator
[instead of the more obvious <code>..</code>]
both because it has
the right priority and because in formal languages it is
common to use a dot for denoting concatenation.)
</p>
<h3><a name="op-pow"></a><code>patt^n</code></h3>
<p>
If <code>n</code> is nonnegative,
this pattern is
equivalent to <em>patt<sup>n</sup> patt*</em>:
It matches <code>n</code> or more occurrences of <code>patt</code>.
</p>
<p>
Otherwise, when <code>n</code> is negative,
this pattern is equivalent to <em>(patt?)<sup>-n</sup></em>:
It matches at most <code>|n|</code>
occurrences of <code>patt</code>.
</p>
<p>
In particular, <code>patt^0</code> is equivalent to <em>patt*</em>,
<code>patt^1</code> is equivalent to <em>patt+</em>,
and <code>patt^-1</code> is equivalent to <em>patt?</em>
in the original PEG notation.
</p>
<p>
In all cases,
the resulting pattern is greedy with no backtracking
(also called a <em>possessive</em> repetition).
That is, it matches only the longest possible sequence
of matches for <code>patt</code>.
</p>
<h2><a name="grammar">Grammars</a></h2>
<p>
With the use of Lua variables,
it is possible to define patterns incrementally,
with each new pattern using previously defined ones.
However, this technique does not allow the definition of
recursive patterns.
For recursive patterns,
we need real grammars.
</p>
<p>
LPeg represents grammars with tables,
where each entry is a rule.
</p>
<p>
The call <code>lpeg.V(v)</code>
creates a pattern that represents the nonterminal
(or <em>variable</em>) with index <code>v</code> in a grammar.
Because the grammar still does not exist when
this function is evaluated,
the result is an <em>open reference</em> to the respective rule.
</p>
<p>
A table is <em>fixed</em> when it is converted to a pattern
(either by calling <code>lpeg.P</code> or by using it wherein a
pattern is expected).
Then every open reference created by <code>lpeg.V(v)</code>
is corrected to refer to the rule indexed by <code>v</code> in the table.
</p>
<p>
When a table is fixed,
the result is a pattern that matches its <em>initial rule</em>.
The entry with index 1 in the table defines its initial rule.
If that entry is a string,
it is assumed to be the name of the initial rule.
Otherwise, LPeg assumes that the entry 1 itself is the initial rule.
</p>
<p>
As an example,
the following grammar matches strings of a's and b's that
have the same number of a's and b's:
</p>
<pre class="example">
equalcount = lpeg.P{
"S"; -- initial rule name
S = "a" * lpeg.V"B" + "b" * lpeg.V"A" + "",
A = "a" * lpeg.V"S" + "b" * lpeg.V"A" * lpeg.V"A",
B = "b" * lpeg.V"S" + "a" * lpeg.V"B" * lpeg.V"B",
} * -1
</pre>
<p>
It is equivalent to the following grammar in standard PEG notation:
</p>
<pre class="example">
S <- 'a' B / 'b' A / ''
A <- 'a' S / 'b' A A
B <- 'b' S / 'a' B B
</pre>
<h2><a name="captures">Captures</a></h2>
<p>
A <em>capture</em> is a pattern that produces values
(the so called <em>semantic information</em>)
according to what it matches.
LPeg offers several kinds of captures,
which produces values based on matches and combine these values to
produce new values.
Each capture may produce zero or more values.
</p>
<p>
The following table summarizes the basic captures:
</p>
<table border="1">
<tbody><tr><td><b>Operation</b></td><td><b>What it Produces</b></td></tr>
<tr><td><a href="#cap-c"><code>lpeg.C(patt)</code></a></td>
<td>the match for <code>patt</code> plus all captures
made by <code>patt</code></td></tr>
<tr><td><a href="#cap-arg"><code>lpeg.Carg(n)</code></a></td>
<td>the value of the n<sup>th</sup> extra argument to
<code>lpeg.match</code> (matches the empty string)</td></tr>
<tr><td><a href="#cap-b"><code>lpeg.Cb(name)</code></a></td>
<td>the values produced by the previous
group capture named <code>name</code>
(matches the empty string)</td></tr>
<tr><td><a href="#cap-cc"><code>lpeg.Cc(values)</code></a></td>
<td>the given values (matches the empty string)</td></tr>
<tr><td><a href="#cap-f"><code>lpeg.Cf(patt, func)</code></a></td>
<td>a <em>folding</em> of the captures from <code>patt</code></td></tr>
<tr><td><a href="#cap-g"><code>lpeg.Cg(patt [, name])</code></a></td>
<td>the values produced by <code>patt</code>,
optionally tagged with <code>name</code></td></tr>
<tr><td><a href="#cap-p"><code>lpeg.Cp()</code></a></td>
<td>the current position (matches the empty string)</td></tr>
<tr><td><a href="#cap-s"><code>lpeg.Cs(patt)</code></a></td>
<td>the match for <code>patt</code>
with the values from nested captures replacing their matches</td></tr>
<tr><td><a href="#cap-t"><code>lpeg.Ct(patt)</code></a></td>
<td>a table with all captures from <code>patt</code></td></tr>
<tr><td><a href="#cap-string"><code>patt / string</code></a></td>
<td><code>string</code>, with some marks replaced by captures
of <code>patt</code></td></tr>
<tr><td><a href="#cap-num"><code>patt / number</code></a></td>
<td>the n-th value captured by <code>patt</code>,
or no value when <code>number</code> is zero.</td></tr>
<tr><td><a href="#cap-query"><code>patt / table</code></a></td>
<td><code>table[c]</code>, where <code>c</code> is the (first)
capture of <code>patt</code></td></tr>
<tr><td><a href="#cap-func"><code>patt / function</code></a></td>
<td>the returns of <code>function</code> applied to the captures
of <code>patt</code></td></tr>
<tr><td><a href="#matchtime"><code>lpeg.Cmt(patt, function)</code></a></td>
<td>the returns of <code>function</code> applied to the captures
of <code>patt</code>; the application is done at match time</td></tr>
</tbody></table>
<p>
A capture pattern produces its values only when it succeeds.
For instance,
the pattern <code>lpeg.C(lpeg.P"a"^-1)</code>
produces the empty string when there is no <code>"a"</code>
(because the pattern <code>"a"?</code> succeeds),
while the pattern <code>lpeg.C("a")^-1</code>
does not produce any value when there is no <code>"a"</code>
(because the pattern <code>"a"</code> fails).
A pattern inside a loop or inside a recursive structure
produces values for each match.
</p>
<p>
Usually,
LPeg does not specify when (and if) it evaluates its captures.
(As an example,
consider the pattern <code>lpeg.P"a" / func / 0</code>.
Because the "division" by 0 instructs LPeg to throw away the
results from the pattern,
LPeg may or may not call <code>func</code>.)
Therefore, captures should avoid side effects.
Moreover,
most captures cannot affect the way a pattern matches a subject.
The only exception to this rule is the
so-called <a href="#matchtime"><em>match-time capture</em></a>.
When a match-time capture matches,
it forces the immediate evaluation of all its nested captures
and then calls its corresponding function,
which defines whether the match succeeds and also
what values are produced.
</p>
<h3><a name="cap-c"></a><code>lpeg.C (patt)</code></h3>
<p>
Creates a <em>simple capture</em>,
which captures the substring of the subject that matches <code>patt</code>.
The captured value is a string.
If <code>patt</code> has other captures,
their values are returned after this one.
</p>
<h3><a name="cap-arg"></a><code>lpeg.Carg (n)</code></h3>
<p>
Creates an <em>argument capture</em>.
This pattern matches the empty string and
produces the value given as the n<sup>th</sup> extra
argument given in the call to <code>lpeg.match</code>.
</p>
<h3><a name="cap-b"></a><code>lpeg.Cb (name)</code></h3>
<p>
Creates a <em>back capture</em>.
This pattern matches the empty string and
produces the values produced by the <em>most recent</em>
<a href="#cap-g">group capture</a> named <code>name</code>
(where <code>name</code> can be any Lua value).
</p>
<p>
<em>Most recent</em> means the last
<em>complete</em>
<em>outermost</em>
group capture with the given name.
A <em>Complete</em> capture means that the entire pattern
corresponding to the capture has matched.
An <em>Outermost</em> capture means that the capture is not inside
another complete capture.
</p>
<p>
In the same way that LPeg does not specify when it evaluates captures,
it does not specify whether it reuses
values previously produced by the group
or re-evaluates them.
</p>
<h3><a name="cap-cc"></a><code>lpeg.Cc ([value, ...])</code></h3>
<p>
Creates a <em>constant capture</em>.
This pattern matches the empty string and
produces all given values as its captured values.
</p>
<h3><a name="cap-f"></a><code>lpeg.Cf (patt, func)</code></h3>
<p>
Creates a <em>fold capture</em>.
If <code>patt</code> produces a list of captures
<em>C<sub>1</sub> C<sub>2</sub> ... C<sub>n</sub></em>,
this capture will produce the value
<em>func(...func(func(C<sub>1</sub>, C<sub>2</sub>), C<sub>3</sub>)...,
C<sub>n</sub>)</em>,
that is, it will <em>fold</em>
(or <em>accumulate</em>, or <em>reduce</em>)
the captures from <code>patt</code> using function <code>func</code>.
</p>
<p>
This capture assumes that <code>patt</code> should produce
at least one capture with at least one value (of any type),
which becomes the initial value of an <em>accumulator</em>.
(If you need a specific initial value,
you may prefix a <a href="#cap-cc">constant capture</a> to <code>patt</code>.)
For each subsequent capture,
LPeg calls <code>func</code>
with this accumulator as the first argument and all values produced
by the capture as extra arguments;
the first result from this call
becomes the new value for the accumulator.
The final value of the accumulator becomes the captured value.
</p>
<p>
As an example,
the following pattern matches a list of numbers separated
by commas and returns their addition:
</p>
<pre class="example">
-- matches a numeral and captures its numerical value
number = lpeg.R"09"^1 / tonumber
-- matches a list of numbers, capturing their values
list = number * ("," * number)^0
-- auxiliary function to add two numbers
function add (acc, newvalue) return acc + newvalue end
-- folds the list of numbers adding them
sum = lpeg.Cf(list, add)
-- example of use
print(sum:match("10,30,43")) --> 83
</pre>
<h3><a name="cap-g"></a><code>lpeg.Cg (patt [, name])</code></h3>
<p>
Creates a <em>group capture</em>.
It groups all values returned by <code>patt</code>
into a single capture.
The group may be anonymous (if no name is given)
or named with the given name
(which can be any non-nil Lua value).
</p>
<p>
An anonymous group serves to join values from several captures into
a single capture.
A named group has a different behavior.
In most situations, a named group returns no values at all.
Its values are only relevant for a following
<a href="#cap-b">back capture</a> or when used
inside a <a href="#cap-t">table capture</a>.
</p>
<h3><a name="cap-p"></a><code>lpeg.Cp ()</code></h3>
<p>
Creates a <em>position capture</em>.
It matches the empty string and
captures the position in the subject where the match occurs.
The captured value is a number.
</p>
<h3><a name="cap-s"></a><code>lpeg.Cs (patt)</code></h3>
<p>
Creates a <em>substitution capture</em>,
which captures the substring of the subject that matches <code>patt</code>,
with <em>substitutions</em>.
For any capture inside <code>patt</code> with a value,
the substring that matched the capture is replaced by the capture value
(which should be a string).
The final captured value is the string resulting from
all replacements.
</p>
<h3><a name="cap-t"></a><code>lpeg.Ct (patt)</code></h3>
<p>
Creates a <em>table capture</em>.
This capture returns a table with all values from all anonymous captures
made by <code>patt</code> inside this table in successive integer keys,
starting at 1.
Moreover,
for each named capture group created by <code>patt</code>,
the first value of the group is put into the table
with the group name as its key.
The captured value is only the table.
</p>
<h3><a name="cap-string"></a><code>patt / string</code></h3>
<p>
Creates a <em>string capture</em>.
It creates a capture string based on <code>string</code>.
The captured value is a copy of <code>string</code>,
except that the character <code>%</code> works as an escape character:
any sequence in <code>string</code> of the form <code>%<em>n</em></code>,
with <em>n</em> between 1 and 9,
stands for the match of the <em>n</em>-th capture in <code>patt</code>.
The sequence <code>%0</code> stands for the whole match.
The sequence <code>%%</code> stands for a single <code>%</code>.
</p>
<h3><a name="cap-num"></a><code>patt / number</code></h3>
<p>
Creates a <em>numbered capture</em>.
For a non-zero number,
the captured value is the n-th value
captured by <code>patt</code>.
When <code>number</code> is zero,
there are no captured values.
</p>
<h3><a name="cap-query"></a><code>patt / table</code></h3>
<p>
Creates a <em>query capture</em>.
It indexes the given table using as key the first value captured by
<code>patt</code>,
or the whole match if <code>patt</code> produced no value.
The value at that index is the final value of the capture.
If the table does not have that key,
there is no captured value.
</p>
<h3><a name="cap-func"></a><code>patt / function</code></h3>
<p>
Creates a <em>function capture</em>.
It calls the given function passing all captures made by
<code>patt</code> as arguments,
or the whole match if <code>patt</code> made no capture.
The values returned by the function
are the final values of the capture.
In particular,
if <code>function</code> returns no value,
there is no captured value.
</p>
<h3><a name="matchtime"></a><code>lpeg.Cmt(patt, function)</code></h3>
<p>
Creates a <em>match-time capture</em>.
Unlike all other captures,
this one is evaluated immediately when a match occurs
(even if it is part of a larger pattern that fails later).
It forces the immediate evaluation of all its nested captures
and then calls <code>function</code>.
</p>
<p>
The given function gets as arguments the entire subject,
the current position (after the match of <code>patt</code>),
plus any capture values produced by <code>patt</code>.
</p>
<p>
The first value returned by <code>function</code>
defines how the match happens.
If the call returns a number,
the match succeeds
and the returned number becomes the new current position.
(Assuming a subject <em>s</em> and current position <em>i</em>,
the returned number must be in the range <em>[i, len(s) + 1]</em>.)
If the call returns <b>true</b>,
the match succeeds without consuming any input.
(So, to return <b>true</b> is equivalent to return <em>i</em>.)
If the call returns <b>false</b>, <b>nil</b>, or no value,
the match fails.
</p>
<p>
Any extra values returned by the function become the
values produced by the capture.
</p>
<h2><a name="ex">Some Examples</a></h2>
<h3>Using a Pattern</h3>
<p>
This example shows a very simple but complete program
that builds and uses a pattern:
</p>
<pre class="example">
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
</pre>
<p>
The pattern is simply a sequence of one or more lower-case letters
followed by the end of string (-1).
The program calls <code>match</code> both as a method
and as a function.
In both sucessful cases,
the match returns
the index of the first character after the match,
which is the string length plus one.
</p>
<h3>Name-value lists</h3>
<p>
This example parses a list of name-value pairs and returns a table
with those pairs:
</p>
<pre class="example">
lpeg.locale(lpeg) -- adds locale entries into 'lpeg' table
local space = lpeg.space^0
local name = lpeg.C(lpeg.alpha^1) * space
local sep = lpeg.S(",;") * space
local pair = lpeg.Cg(name * "=" * space * name) * sep^-1
local list = lpeg.Cf(lpeg.Ct("") * pair^0, rawset)
t = list:match("a=b, c = hi; next = pi") --> { a = "b", c = "hi", next = "pi" }
</pre>
<p>
Each pair has the format <code>name = name</code> followed by
an optional separator (a comma or a semicolon).
The <code>pair</code> pattern encloses the pair in a group pattern,
so that the names become the values of a single capture.
The <code>list</code> pattern then folds these captures.
It starts with an empty table,
created by a table capture matching an empty string;
then for each capture (a pair of names) it applies <code>rawset</code>
over the accumulator (the table) and the capture values (the pair of names).
<code>rawset</code> returns the table itself,
so the accumulator is always the table.
</p>
<h3>Splitting a string</h3>
<p>
The following code builds a pattern that
splits a string using a given pattern
<code>sep</code> as a separator:
</p>
<pre class="example">
function split (s, sep)
sep = lpeg.P(sep)
local elem = lpeg.C((1 - sep)^0)
local p = elem * (sep * elem)^0
return lpeg.match(p, s)
end
</pre>
<p>
First the function ensures that <code>sep</code> is a proper pattern.
The pattern <code>elem</code> is a repetition of zero of more
arbitrary characters as long as there is not a match against
the separator.
It also captures its match.
The pattern <code>p</code> matches a list of elements separated
by <code>sep</code>.
</p>