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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.8: http://docutils.sourceforge.net/" />
<title>Using the pyparsing module</title>
<meta name="author" content="Paul McGuire" />
<meta name="date" content="June, 2011" />
<meta name="copyright" content="Copyright © 2003-2011 Paul McGuire." />
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 6387 2010-08-13 12:23:41Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
overflow: hidden;
}
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left, object.align-left {
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right, object.align-right {
clear: right ;
float: right ;
margin-left: 1em }
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
/* reset inner alignment in figures */
div.align-right {
text-align: left }
/* div.align-center * { */
/* text-align: left } */
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="using-the-pyparsing-module">
<h1 class="title">Using the pyparsing module</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Paul McGuire</td></tr>
<tr><th class="docinfo-name">Address:</th>
<td><pre class="address">
<a class="first last reference external" href="mailto:ptmcg@users.sourceforge.net">ptmcg@users.sourceforge.net</a>
</pre>
</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>2.0.1</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>July, 2013</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright © 2003-2013 Paul McGuire.</td></tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">abstract:</th><td class="field-body">This document provides how-to instructions for the
pyparsing library, an easy-to-use Python module for constructing
and executing basic text parsers. The pyparsing module is useful
for evaluating user-definable
expressions, processing custom application language commands, or
extracting data from formatted reports.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#steps-to-follow" id="id1">1 Steps to follow</a><ul class="auto-toc">
<li><a class="reference internal" href="#hello-world" id="id2">1.1 Hello, World!</a></li>
<li><a class="reference internal" href="#usage-notes" id="id3">1.2 Usage notes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#classes" id="id4">2 Classes</a><ul class="auto-toc">
<li><a class="reference internal" href="#classes-in-the-pyparsing-module" id="id5">2.1 Classes in the pyparsing module</a></li>
<li><a class="reference internal" href="#basic-parserelement-subclasses" id="id6">2.2 Basic ParserElement subclasses</a></li>
<li><a class="reference internal" href="#expression-subclasses" id="id7">2.3 Expression subclasses</a></li>
<li><a class="reference internal" href="#expression-operators" id="id8">2.4 Expression operators</a></li>
<li><a class="reference internal" href="#positional-subclasses" id="id9">2.5 Positional subclasses</a></li>
<li><a class="reference internal" href="#converter-subclasses" id="id10">2.6 Converter subclasses</a></li>
<li><a class="reference internal" href="#special-subclasses" id="id11">2.7 Special subclasses</a></li>
<li><a class="reference internal" href="#other-classes" id="id12">2.8 Other classes</a></li>
<li><a class="reference internal" href="#exception-classes-and-troubleshooting" id="id13">2.9 Exception classes and Troubleshooting</a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous-attributes-and-methods" id="id14">3 Miscellaneous attributes and methods</a><ul class="auto-toc">
<li><a class="reference internal" href="#helper-methods" id="id15">3.1 Helper methods</a></li>
<li><a class="reference internal" href="#helper-parse-actions" id="id16">3.2 Helper parse actions</a></li>
<li><a class="reference internal" href="#common-string-and-token-constants" id="id17">3.3 Common string and token constants</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="steps-to-follow">
<h1><a class="toc-backref" href="#id1">1 Steps to follow</a></h1>
<p>To parse an incoming data string, the client code must follow these steps:</p>
<ol class="arabic simple">
<li>First define the tokens and patterns to be matched, and assign
this to a program variable. Optional results names or parsing
actions can also be defined at this time.</li>
<li>Call <tt class="docutils literal">parseString()</tt> or <tt class="docutils literal">scanString()</tt> on this variable, passing in
the string to
be parsed. During the matching process, whitespace between
tokens is skipped by default (although this can be changed).
When token matches occur, any defined parse action methods are
called.</li>
<li>Process the parsed results, returned as a list of strings.
Matching results may also be accessed as named attributes of
the returned results, if names are defined in the definition of
the token pattern, using <tt class="docutils literal">setResultsName()</tt>.</li>
</ol>
<div class="section" id="hello-world">
<h2><a class="toc-backref" href="#id2">1.1 Hello, World!</a></h2>
<p>The following complete Python program will parse the greeting "Hello, World!",
or any other greeting of the form "<salutation>, <addressee>!":</p>
<pre class="literal-block">
from pyparsing import Word, alphas
greet = Word( alphas ) + "," + Word( alphas ) + "!"
greeting = greet.parseString( "Hello, World!" )
print greeting
</pre>
<p>The parsed tokens are returned in the following form:</p>
<pre class="literal-block">
['Hello', ',', 'World', '!']
</pre>
</div>
<div class="section" id="usage-notes">
<h2><a class="toc-backref" href="#id3">1.2 Usage notes</a></h2>
<ul>
<li><p class="first">The pyparsing module can be used to interpret simple command
strings or algebraic expressions, or can be used to extract data
from text reports with complicated format and structure ("screen
or report scraping"). However, it is possible that your defined
matching patterns may accept invalid inputs. Use pyparsing to
extract data from strings assumed to be well-formatted.</p>
</li>
<li><p class="first">To keep up the readability of your code, use <a class="reference internal" href="#operators">operators</a> such as <tt class="docutils literal">+</tt>, <tt class="docutils literal">|</tt>,
<tt class="docutils literal">^</tt>, and <tt class="docutils literal">~</tt> to combine expressions. You can also combine
string literals with ParseExpressions - they will be
automatically converted to Literal objects. For example:</p>
<pre class="literal-block">
integer = Word( nums ) # simple unsigned integer
variable = Word( alphas, max=1 ) # single letter variable, such as x, z, m, etc.
arithOp = Word( "+-*/", max=1 ) # arithmetic operators
equation = variable + "=" + integer + arithOp + integer # will match "x=2+2", etc.
</pre>
<p>In the definition of <tt class="docutils literal">equation</tt>, the string <tt class="docutils literal">"="</tt> will get added as
a <tt class="docutils literal"><span class="pre">Literal("=")</span></tt>, but in a more readable way.</p>
</li>
<li><p class="first">The pyparsing module's default behavior is to ignore whitespace. This is the
case for 99% of all parsers ever written. This allows you to write simple, clean,
grammars, such as the above <tt class="docutils literal">equation</tt>, without having to clutter it up with
extraneous <tt class="docutils literal">ws</tt> markers. The <tt class="docutils literal">equation</tt> grammar will successfully parse all of the
following statements:</p>
<pre class="literal-block">
x=2+2
x = 2+2
a = 10 * 4
r= 1234/ 100000
</pre>
<p>Of course, it is quite simple to extend this example to support more elaborate expressions, with
nesting with parentheses, floating point numbers, scientific notation, and named constants
(such as <tt class="docutils literal">e</tt> or <tt class="docutils literal">pi</tt>). See <tt class="docutils literal">fourFn.py</tt>, included in the examples directory.</p>
</li>
<li><p class="first">To modify pyparsing's default whitespace skipping, you can use one or
more of the following methods:</p>
<ul>
<li><p class="first">use the static method <tt class="docutils literal">ParserElement.setDefaultWhitespaceChars</tt>
to override the normal set of whitespace chars (' tn'). For instance
when defining a grammar in which newlines are significant, you should
call <tt class="docutils literal">ParserElement.setDefaultWhitespaceChars(' \t')</tt> to remove
newline from the set of skippable whitespace characters. Calling
this method will affect all pyparsing expressions defined afterward.</p>
</li>
<li><p class="first">call <tt class="docutils literal">leaveWhitespace()</tt> on individual expressions, to suppress the
skipping of whitespace before trying to match the expression</p>
</li>
<li><p class="first">use <tt class="docutils literal">Combine</tt> to require that successive expressions must be
adjacent in the input string. For instance, this expression:</p>
<pre class="literal-block">
real = Word(nums) + '.' + Word(nums)
</pre>
<p>will match "3.14159", but will also match "3 . 12". It will also
return the matched results as ['3', '.', '14159']. By changing this
expression to:</p>
<pre class="literal-block">
real = Combine( Word(nums) + '.' + Word(nums) )
</pre>
<p>it will not match numbers with embedded spaces, and it will return a
single concatenated string '3.14159' as the parsed token.</p>
</li>
</ul>
</li>
<li><p class="first">Repetition of expressions can be indicated using the '*' operator. An
expression may be multiplied by an integer value (to indicate an exact
repetition count), or by a tuple containing
two integers, or None and an integer, representing min and max repetitions
(with None representing no min or no max, depending whether it is the first or
second tuple element). See the following examples, where n is used to
indicate an integer value:</p>
<ul class="simple">
<li><tt class="docutils literal">expr*3</tt> is equivalent to <tt class="docutils literal">expr + expr + expr</tt></li>
<li><tt class="docutils literal"><span class="pre">expr*(2,3)</span></tt> is equivalent to <tt class="docutils literal">expr + expr + Optional(expr)</tt></li>
<li><tt class="docutils literal"><span class="pre">expr*(n,None)</span></tt> or <tt class="docutils literal"><span class="pre">expr*(n,)</span></tt> is equivalent
to <tt class="docutils literal">expr*n + ZeroOrMore(expr)</tt> (read as "at least n instances of expr")</li>
<li><tt class="docutils literal"><span class="pre">expr*(None,n)</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">expr*(0,n)</span></tt>
(read as "0 to n instances of expr")</li>
<li><tt class="docutils literal"><span class="pre">expr*(None,None)</span></tt> is equivalent to <tt class="docutils literal">ZeroOrMore(expr)</tt></li>
<li><tt class="docutils literal"><span class="pre">expr*(1,None)</span></tt> is equivalent to <tt class="docutils literal">OneOrMore(expr)</tt></li>
</ul>
<p>Note that <tt class="docutils literal"><span class="pre">expr*(None,n)</span></tt> does not raise an exception if
more than n exprs exist in the input stream; that is,
<tt class="docutils literal"><span class="pre">expr*(None,n)</span></tt> does not enforce a maximum number of expr
occurrences. If this behavior is desired, then write
<tt class="docutils literal"><span class="pre">expr*(None,n)</span> + ~expr</tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal">MatchFirst</tt> expressions are matched left-to-right, and the first
match found will skip all later expressions within, so be sure
to define less-specific patterns after more-specific patterns.
If you are not sure which expressions are most specific, use Or
expressions (defined using the <tt class="docutils literal">^</tt> operator) - they will always
match the longest expression, although they are more
compute-intensive.</p>
</li>
<li><p class="first"><tt class="docutils literal">Or</tt> expressions will evaluate all of the specified subexpressions
to determine which is the "best" match, that is, which matches
the longest string in the input data. In case of a tie, the
left-most expression in the <tt class="docutils literal">Or</tt> list will win.</p>
</li>
<li><p class="first">If parsing the contents of an entire file, pass it to the
<tt class="docutils literal">parseFile</tt> method using:</p>
<pre class="literal-block">
expr.parseFile( sourceFile )
</pre>
</li>
<li><p class="first"><tt class="docutils literal">ParseExceptions</tt> will report the location where an expected token
or expression failed to match. For example, if we tried to use our
"Hello, World!" parser to parse "Hello World!" (leaving out the separating
comma), we would get an exception, with the message:</p>
<pre class="literal-block">
pyparsing.ParseException: Expected "," (6), (1,7)
</pre>
<p>In the case of complex
expressions, the reported location may not be exactly where you
would expect. See more information under <a class="reference internal" href="#parseexception">ParseException</a> .</p>
</li>
<li><p class="first">Use the <tt class="docutils literal">Group</tt> class to enclose logical groups of tokens within a
sublist. This will help organize your results into more
hierarchical form (the default behavior is to return matching
tokens as a flat list of matching input strings).</p>
</li>
<li><p class="first">Punctuation may be significant for matching, but is rarely of
much interest in the parsed results. Use the <tt class="docutils literal">suppress()</tt> method
to keep these tokens from cluttering up your returned lists of
tokens. For example, <tt class="docutils literal">delimitedList()</tt> matches a succession of
one or more expressions, separated by delimiters (commas by
default), but only returns a list of the actual expressions -
the delimiters are used for parsing, but are suppressed from the
returned output.</p>
</li>
<li><p class="first">Parse actions can be used to convert values from strings to
other data types (ints, floats, booleans, etc.).</p>
</li>
<li><p class="first">Results names are recommended for retrieving tokens from complex
expressions. It is much easier to access a token using its field
name than using a positional index, especially if the expression
contains optional elements. You can also shortcut
the <tt class="docutils literal">setResultsName</tt> call:</p>
<pre class="literal-block">
stats = "AVE:" + realNum.setResultsName("average") + \
"MIN:" + realNum.setResultsName("min") + \
"MAX:" + realNum.setResultsName("max")
</pre>
<p>can now be written as this:</p>
<pre class="literal-block">
stats = "AVE:" + realNum("average") + \
"MIN:" + realNum("min") + \
"MAX:" + realNum("max")
</pre>
</li>
<li><p class="first">Be careful when defining parse actions that modify global variables or
data structures (as in <tt class="docutils literal">fourFn.py</tt>), especially for low level tokens
or expressions that may occur within an <tt class="docutils literal">And</tt> expression; an early element
of an <tt class="docutils literal">And</tt> may match, but the overall expression may fail.</p>
</li>
<li><p class="first">Performance of pyparsing may be slow for complex grammars and/or large
input strings. The <a class="reference external" href="http://psyco.sourceforge.net/">psyco</a> package can be used to improve the speed of the
pyparsing module with no changes to grammar or program logic - observed
improvments have been in the 20-50% range.</p>
</li>
</ul>
</div>
</div>
<div class="section" id="classes">
<h1><a class="toc-backref" href="#id4">2 Classes</a></h1>
<div class="section" id="classes-in-the-pyparsing-module">
<h2><a class="toc-backref" href="#id5">2.1 Classes in the pyparsing module</a></h2>
<p><tt class="docutils literal">ParserElement</tt> - abstract base class for all pyparsing classes;
methods for code to use are:</p>
<ul>
<li><p class="first"><tt class="docutils literal">parseString( sourceString, parseAll=False )</tt> - only called once, on the overall
matching pattern; returns a <a class="reference internal" href="#parseresults">ParseResults</a> object that makes the
matched tokens available as a list, and optionally as a dictionary,
or as an object with named attributes; if parseAll is set to True, then
parseString will raise a ParseException if the grammar does not process
the complete input string.</p>
</li>
<li><p class="first"><tt class="docutils literal">parseFile( sourceFile )</tt> - a convenience function, that accepts an
input file object or filename. The file contents are passed as a
string to <tt class="docutils literal">parseString()</tt>. <tt class="docutils literal">parseFile</tt> also supports the <tt class="docutils literal">parseAll</tt> argument.</p>
</li>
<li><p class="first"><tt class="docutils literal">scanString( sourceString )</tt> - generator function, used to find and
extract matching text in the given source string; for each matched text,
returns a tuple of:</p>
<ul class="simple">
<li>matched tokens (packaged as a <a class="reference internal" href="#parseresults">ParseResults</a> object)</li>
<li>start location of the matched text in the given source string</li>
<li>end location in the given source string</li>
</ul>
<p><tt class="docutils literal">scanString</tt> allows you to scan through the input source string for
random matches, instead of exhaustively defining the grammar for the entire
source text (as would be required with <tt class="docutils literal">parseString</tt>).</p>
</li>
<li><p class="first"><tt class="docutils literal">transformString( sourceString )</tt> - convenience wrapper function for
<tt class="docutils literal">scanString</tt>, to process the input source string, and replace matching
text with the tokens returned from parse actions defined in the grammar
(see <a class="reference internal" href="#setparseaction">setParseAction</a>).</p>
</li>
<li><p class="first"><tt class="docutils literal">searchString( sourceString )</tt> - another convenience wrapper function for
<tt class="docutils literal">scanString</tt>, returns a list of the matching tokens returned from each
call to <tt class="docutils literal">scanString</tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal">setName( name )</tt> - associate a short descriptive name for this
element, useful in displaying exceptions and trace information</p>
</li>
<li><p class="first"><tt class="docutils literal">setResultsName( string, listAllMatches=False )</tt> - name to be given
to tokens matching
the element; if multiple tokens within
a repetition group (such as <tt class="docutils literal">ZeroOrMore</tt> or <tt class="docutils literal">delimitedList</tt>) the
default is to return only the last matching token - if listAllMatches
is set to True, then a list of all the matching tokens is returned.
(New in 1.5.6 - a results name with a trailing '*' character will be
interpreted as setting listAllMatches to True.)
Note:
<tt class="docutils literal">setResultsName</tt> returns a <em>copy</em> of the element so that a single
basic element can be referenced multiple times and given
different names within a complex grammar.</p>
</li>
</ul>
<ul id="setparseaction">
<li><p class="first"><tt class="docutils literal">setParseAction( *fn )</tt> - specify one or more functions to call after successful
matching of the element; each function is defined as <tt class="docutils literal">fn( s,
loc, toks )</tt>, where:</p>
<ul class="simple">
<li><tt class="docutils literal">s</tt> is the original parse string</li>
<li><tt class="docutils literal">loc</tt> is the location in the string where matching started</li>
<li><tt class="docutils literal">toks</tt> is the list of the matched tokens, packaged as a <a class="reference internal" href="#parseresults">ParseResults</a> object</li>
</ul>
<p>Multiple functions can be attached to a ParserElement by specifying multiple
arguments to setParseAction, or by calling setParseAction multiple times.</p>
<p>Each parse action function can return a modified <tt class="docutils literal">toks</tt> list, to perform conversion, or
string modifications. For brevity, <tt class="docutils literal">fn</tt> may also be a
lambda - here is an example of using a parse action to convert matched
integer tokens from strings to integers:</p>
<pre class="literal-block">
intNumber = Word(nums).setParseAction( lambda s,l,t: [ int(t[0]) ] )
</pre>
<p>If <tt class="docutils literal">fn</tt> does not modify the <tt class="docutils literal">toks</tt> list, it does not need to return
anything at all.</p>
</li>
<li><p class="first"><tt class="docutils literal">setBreak( breakFlag=True )</tt> - if breakFlag is True, calls pdb.set_break()
as this expression is about to be parsed</p>
</li>
<li><p class="first"><tt class="docutils literal">copy()</tt> - returns a copy of a ParserElement; can be used to use the same
parse expression in different places in a grammar, with different parse actions
attached to each</p>
</li>
<li><p class="first"><tt class="docutils literal">leaveWhitespace()</tt> - change default behavior of skipping
whitespace before starting matching (mostly used internally to the
pyparsing module, rarely used by client code)</p>
</li>
<li><p class="first"><tt class="docutils literal">setWhitespaceChars( chars )</tt> - define the set of chars to be ignored
as whitespace before trying to match a specific ParserElement, in place of the
default set of whitespace (space, tab, newline, and return)</p>
</li>
<li><p class="first"><tt class="docutils literal">setDefaultWhitespaceChars( chars )</tt> - class-level method to override
the default set of whitespace chars for all subsequently created ParserElements
(including copies); useful when defining grammars that treat one or more of the
default whitespace characters as significant (such as a line-sensitive grammar, to
omit newline from the list of ignorable whitespace)</p>
</li>
<li><p class="first"><tt class="docutils literal">suppress()</tt> - convenience function to suppress the output of the
given element, instead of wrapping it with a Suppress object.</p>
</li>
<li><p class="first"><tt class="docutils literal">ignore( expr )</tt> - function to specify parse expression to be
ignored while matching defined patterns; can be called
repeatedly to specify multiple expressions; useful to specify
patterns of comment syntax, for example</p>
</li>
<li><p class="first"><tt class="docutils literal">setDebug( dbgFlag=True )</tt> - function to enable/disable tracing output
when trying to match this element</p>
</li>
<li><p class="first"><tt class="docutils literal">validate()</tt> - function to verify that the defined grammar does not
contain infinitely recursive constructs</p>
</li>
</ul>
<ul class="simple" id="parsewithtabs">
<li><tt class="docutils literal">parseWithTabs()</tt> - function to override default behavior of converting
tabs to spaces before parsing the input string; rarely used, except when
specifying whitespace-significant grammars using the <a class="reference internal" href="#white">White</a> class.</li>
<li><tt class="docutils literal">enablePackrat()</tt> - a class-level static method to enable a memoizing
performance enhancement, known as "packrat parsing". packrat parsing is
disabled by default, since it may conflict with some user programs that use
parse actions. To activate the packrat feature, your
program must call the class method ParserElement.enablePackrat(). If
your program uses psyco to "compile as you go", you must call
enablePackrat before calling psyco.full(). If you do not do this,
Python will crash. For best results, call enablePackrat() immediately
after importing pyparsing.</li>
</ul>
</div>
<div class="section" id="basic-parserelement-subclasses">
<h2><a class="toc-backref" href="#id6">2.2 Basic ParserElement subclasses</a></h2>
<ul class="simple">
<li><tt class="docutils literal">Literal</tt> - construct with a string to be matched exactly</li>
<li><tt class="docutils literal">CaselessLiteral</tt> - construct with a string to be matched, but
without case checking; results are always returned as the
defining literal, NOT as they are found in the input string</li>
<li><tt class="docutils literal">Keyword</tt> - similar to Literal, but must be immediately followed by
whitespace, punctuation, or other non-keyword characters; prevents
accidental matching of a non-keyword that happens to begin with a
defined keyword</li>
<li><tt class="docutils literal">CaselessKeyword</tt> - similar to Keyword, but with caseless matching
behavior</li>
</ul>
<ul id="word">
<li><p class="first"><tt class="docutils literal">Word</tt> - one or more contiguous characters; construct with a
string containing the set of allowed initial characters, and an
optional second string of allowed body characters; for instance,
a common Word construct is to match a code identifier - in C, a
valid identifier must start with an alphabetic character or an
underscore ('_'), followed by a body that can also include numeric
digits. That is, <tt class="docutils literal">a</tt>, <tt class="docutils literal">i</tt>, <tt class="docutils literal">MAX_LENGTH</tt>, <tt class="docutils literal">_a1</tt>, <tt class="docutils literal">b_109_</tt>, and
<tt class="docutils literal">plan9FromOuterSpace</tt>
are all valid identifiers; <tt class="docutils literal">9b7z</tt>, <tt class="docutils literal">$a</tt>, <tt class="docutils literal">.section</tt>, and <tt class="docutils literal">0debug</tt>
are not. To
define an identifier using a Word, use either of the following:</p>
<pre class="literal-block">
- Word( alphas+"_", alphanums+"_" )
- Word( srange("[a-zA-Z_]"), srange("[a-zA-Z0-9_]") )
</pre>
<p>If only one
string given, it specifies that the same character set defined
for the initial character is used for the word body; for instance, to
define an identifier that can only be composed of capital letters and
underscores, use:</p>
<pre class="literal-block">
- Word( "ABCDEFGHIJKLMNOPQRSTUVWXYZ_" )
- Word( srange("[A-Z_]") )
</pre>
<p>A Word may
also be constructed with any of the following optional parameters:</p>
<ul class="simple">
<li><tt class="docutils literal">min</tt> - indicating a minimum length of matching characters</li>
<li><tt class="docutils literal">max</tt> - indicating a maximum length of matching characters</li>
<li><tt class="docutils literal">exact</tt> - indicating an exact length of matching characters</li>
</ul>
<p>If exact is specified, it will override any values for min or max.</p>
<p>New in 1.5.6 - Sometimes you want to define a word using all
characters in a range except for one or two of them; you can do this
with the new <tt class="docutils literal">excludeChars</tt> argument. This is helpful if you want to define
a word with all printables except for a single delimiter character, such
as '.'. Previously, you would have to create a custom string to pass to <tt class="docutils literal">Word</tt>.
With this change, you can just create <tt class="docutils literal">Word(printables, <span class="pre">excludeChars='.')</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal">CharsNotIn</tt> - similar to <a class="reference internal" href="#word">Word</a>, but matches characters not
in the given constructor string (accepts only one string for both
initial and body characters); also supports min, max, and exact
optional parameters.</p>
</li>
<li><p class="first"><tt class="docutils literal">Regex</tt> - a powerful construct, that accepts a regular expression
to be matched at the current parse position; accepts an optional
flags parameter, corresponding to the flags parameter in the re.compile
method; if the expression includes named sub-fields, they will be
represented in the returned <a class="reference internal" href="#parseresults">ParseResults</a></p>
</li>
<li><p class="first"><tt class="docutils literal">QuotedString</tt> - supports the definition of custom quoted string
formats, in addition to pyparsing's built-in dblQuotedString and
sglQuotedString. QuotedString allows you to specify the following
parameters:</p>
<ul class="simple">
<li><tt class="docutils literal">quoteChar</tt> - string of one or more characters defining the quote delimiting string</li>
<li><tt class="docutils literal">escChar</tt> - character to escape quotes, typically backslash (default=None)</li>
<li><tt class="docutils literal">escQuote</tt> - special quote sequence to escape an embedded quote string (such as SQL's "" to escape an embedded ") (default=None)</li>
<li><tt class="docutils literal">multiline</tt> - boolean indicating whether quotes can span multiple lines (default=<tt class="docutils literal">False</tt>)</li>
<li><tt class="docutils literal">unquoteResults</tt> - boolean indicating whether the matched text should be unquoted (default=<tt class="docutils literal">True</tt>)</li>
<li><tt class="docutils literal">endQuoteChar</tt> - string of one or more characters defining the end of the quote delimited string (default=None => same as quoteChar)</li>
</ul>
</li>
<li><p class="first"><tt class="docutils literal">SkipTo</tt> - skips ahead in the input string, accepting any
characters up to the specified pattern; may be constructed with
the following optional parameters:</p>
<ul class="simple">
<li><tt class="docutils literal">include</tt> - if set to true, also consumes the match expression
(default is <tt class="docutils literal">False</tt>)</li>
<li><tt class="docutils literal">ignore</tt> - allows the user to specify patterns to not be matched,
to prevent false matches</li>
<li><tt class="docutils literal">failOn</tt> - if a literal string or expression is given for this argument, it defines an expression that
should cause the <tt class="docutils literal">SkipTo</tt> expression to fail, and not skip over that expression</li>
</ul>
</li>
</ul>
<ul class="simple" id="white">
<li><tt class="docutils literal">White</tt> - also similar to <a class="reference internal" href="#word">Word</a>, but matches whitespace
characters. Not usually needed, as whitespace is implicitly
ignored by pyparsing. However, some grammars are whitespace-sensitive,
such as those that use leading tabs or spaces to indicating grouping
or hierarchy. (If matching on tab characters, be sure to call
<a class="reference internal" href="#parsewithtabs">parseWithTabs</a> on the top-level parse element.)</li>
<li><tt class="docutils literal">Empty</tt> - a null expression, requiring no characters - will always
match; useful for debugging and for specialized grammars</li>
<li><tt class="docutils literal">NoMatch</tt> - opposite of Empty, will never match; useful for debugging
and for specialized grammars</li>
</ul>
</div>
<div class="section" id="expression-subclasses">
<h2><a class="toc-backref" href="#id7">2.3 Expression subclasses</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal">And</tt> - construct with a list of ParserElements, all of which must
match for And to match; can also be created using the '+'
operator; multiple expressions can be Anded together using the '*'
operator as in:</p>
<pre class="literal-block">
ipAddress = Word(nums) + ('.'+Word(nums))*3
</pre>
<p>A tuple can be used as the multiplier, indicating a min/max:</p>
<pre class="literal-block">
usPhoneNumber = Word(nums) + ('-'+Word(nums))*(1,2)
</pre>
<p>A special form of <tt class="docutils literal">And</tt> is created if the '-' operator is used
instead of the '+' operator. In the ipAddress example above, if
no trailing '.' and Word(nums) are found after matching the initial
Word(nums), then pyparsing will back up in the grammar and try other
alternatives to ipAddress. However, if ipAddress is defined as:</p>
<pre class="literal-block">
strictIpAddress = Word(nums) - ('.'+Word(nums))*3
</pre>
<p>then no backing up is done. If the first Word(nums) of strictIpAddress
is matched, then any mismatch after that will raise a ParseSyntaxException,
which will halt the parsing process immediately. By careful use of the
'-' operator, grammars can provide meaningful error messages close to
the location where the incoming text does not match the specified
grammar.</p>
</li>
<li><p class="first"><tt class="docutils literal">Or</tt> - construct with a list of ParserElements, any of which must
match for Or to match; if more than one expression matches, the
expression that makes the longest match will be used; can also
be created using the '^' operator</p>
</li>
<li><p class="first"><tt class="docutils literal">MatchFirst</tt> - construct with a list of ParserElements, any of
which must match for MatchFirst to match; matching is done
left-to-right, taking the first expression that matches; can
also be created using the '|' operator</p>
</li>
<li><p class="first"><tt class="docutils literal">Each</tt> - similar to And, in that all of the provided expressions
must match; however, Each permits matching to be done in any order;
can also be created using the '&' operator</p>
</li>
<li><p class="first"><tt class="docutils literal">Optional</tt> - construct with a ParserElement, but this element is
not required to match; can be constructed with an optional <tt class="docutils literal">default</tt> argument,
containing a default string or object to be supplied if the given optional
parse element is not found in the input string; parse action will only
be called if a match is found, or if a default is specified</p>
</li>
<li><p class="first"><tt class="docutils literal">ZeroOrMore</tt> - similar to Optional, but can be repeated</p>
</li>
<li><p class="first"><tt class="docutils literal">OneOrMore</tt> - similar to ZeroOrMore, but at least one match must
be present</p>
</li>
<li><p class="first"><tt class="docutils literal">FollowedBy</tt> - a lookahead expression, requires matching of the given
expressions, but does not advance the parsing position within the input string</p>
</li>
<li><p class="first"><tt class="docutils literal">NotAny</tt> - a negative lookahead expression, prevents matching of named
expressions, does not advance the parsing position within the input string;
can also be created using the unary '~' operator</p>
</li>
</ul>
</div>
<div class="section" id="expression-operators">
<span id="operators"></span><h2><a class="toc-backref" href="#id8">2.4 Expression operators</a></h2>
<ul class="simple">
<li><tt class="docutils literal">~</tt> - creates NotAny using the expression after the operator</li>
<li><tt class="docutils literal">+</tt> - creates And using the expressions before and after the operator</li>
<li><tt class="docutils literal">|</tt> - creates MatchFirst (first left-to-right match) using the expressions before and after the operator</li>
<li><tt class="docutils literal">^</tt> - creates Or (longest match) using the expressions before and after the operator</li>
<li><tt class="docutils literal">&</tt> - creates Each using the expressions before and after the operator</li>
<li><tt class="docutils literal">*</tt> - creates And by multiplying the expression by the integer operand; if
expression is multiplied by a 2-tuple, creates an And of (min,max)
expressions (similar to "{min,max}" form in regular expressions); if
min is None, intepret as (0,max); if max is None, interpret as
expr*min + ZeroOrMore(expr)</li>
<li><tt class="docutils literal">-</tt> - like <tt class="docutils literal">+</tt> but with no backup and retry of alternatives</li>
<li><tt class="docutils literal">*</tt> - repetition of expression</li>
<li><tt class="docutils literal">==</tt> - matching expression to string; returns True if the string matches the given expression</li>
<li><tt class="docutils literal"><<=</tt> - inserts the expression following the operator as the body of the
Forward expression before the operator (formerly <<, which is now deprecated)</li>
</ul>
</div>
<div class="section" id="positional-subclasses">
<h2><a class="toc-backref" href="#id9">2.5 Positional subclasses</a></h2>
<ul class="simple">
<li><tt class="docutils literal">StringStart</tt> - matches beginning of the text</li>
<li><tt class="docutils literal">StringEnd</tt> - matches the end of the text</li>
<li><tt class="docutils literal">LineStart</tt> - matches beginning of a line (lines delimited by <tt class="docutils literal">\n</tt> characters)</li>
<li><tt class="docutils literal">LineEnd</tt> - matches the end of a line</li>
<li><tt class="docutils literal">WordStart</tt> - matches a leading word boundary</li>
<li><tt class="docutils literal">WordEnd</tt> - matches a trailing word boundary</li>
</ul>
</div>
<div class="section" id="converter-subclasses">
<h2><a class="toc-backref" href="#id10">2.6 Converter subclasses</a></h2>
<ul class="simple">
<li><tt class="docutils literal">Upcase</tt> - converts matched tokens to uppercase (deprecated -
use <tt class="docutils literal">upcaseTokens</tt> parse action instead)</li>
<li><tt class="docutils literal">Combine</tt> - joins all matched tokens into a single string, using
specified joinString (default <tt class="docutils literal"><span class="pre">joinString=""</span></tt>); expects
all matching tokens to be adjacent, with no intervening
whitespace (can be overridden by specifying <tt class="docutils literal">adjacent=False</tt> in constructor)</li>
<li><tt class="docutils literal">Suppress</tt> - clears matched tokens; useful to keep returned
results from being cluttered with required but uninteresting
tokens (such as list delimiters)</li>
</ul>
</div>
<div class="section" id="special-subclasses">
<h2><a class="toc-backref" href="#id11">2.7 Special subclasses</a></h2>
<ul class="simple">
<li><tt class="docutils literal">Group</tt> - causes the matched tokens to be enclosed in a list;
useful in repeated elements like <tt class="docutils literal">ZeroOrMore</tt> and <tt class="docutils literal">OneOrMore</tt> to
break up matched tokens into groups for each repeated pattern</li>
<li><tt class="docutils literal">Dict</tt> - like <tt class="docutils literal">Group</tt>, but also constructs a dictionary, using the
[0]'th elements of all enclosed token lists as the keys, and
each token list as the value</li>
<li><tt class="docutils literal">SkipTo</tt> - catch-all matching expression that accepts all characters
up until the given pattern is found to match; useful for specifying
incomplete grammars</li>
<li><tt class="docutils literal">Forward</tt> - placeholder token used to define recursive token
patterns; when defining the actual expression later in the
program, insert it into the <tt class="docutils literal">Forward</tt> object using the <tt class="docutils literal"><<=</tt>
operator (see <tt class="docutils literal">fourFn.py</tt> for an example).</li>
</ul>
</div>
<div class="section" id="other-classes">
<h2><a class="toc-backref" href="#id12">2.8 Other classes</a></h2>
<ul id="parseresults">
<li><p class="first"><tt class="docutils literal">ParseResults</tt> - class used to contain and manage the lists of tokens
created from parsing the input using the user-defined parse
expression. ParseResults can be accessed in a number of ways:</p>
<ul class="simple">
<li>as a list<ul>
<li>total list of elements can be found using len()</li>
<li>individual elements can be found using [0], [1], [-1], etc.</li>
<li>elements can be deleted using <tt class="docutils literal">del</tt></li>
<li>the -1th element can be extracted and removed in a single operation
using <tt class="docutils literal">pop()</tt>, or any element can be extracted and removed
using <tt class="docutils literal">pop(n)</tt></li>
</ul>
</li>
<li>as a dictionary<ul>
<li>if <tt class="docutils literal">setResultsName()</tt> is used to name elements within the
overall parse expression, then these fields can be referenced
as dictionary elements or as attributes</li>
<li>the Dict class generates dictionary entries using the data of the
input text - in addition to ParseResults listed as <tt class="docutils literal">[ [ a1, b1, c1, <span class="pre">...],</span> [ a2, b2, c2, <span class="pre">...]</span> ]</tt>
it also acts as a dictionary with entries defined as <tt class="docutils literal">{ a1 : [ b1, c1, ... ] }, { a2 : [ b2, c2, ... ] }</tt>;
this is especially useful when processing tabular data where the first column contains a key
value for that line of data</li>
<li>list elements that are deleted using <tt class="docutils literal">del</tt> will still be accessible by their
dictionary keys</li>
<li>supports <tt class="docutils literal">get()</tt>, <tt class="docutils literal">items()</tt> and <tt class="docutils literal">keys()</tt> methods, similar to a dictionary</li>
<li>a keyed item can be extracted and removed using <tt class="docutils literal">pop(key)</tt>. Here
key must be non-numeric (such as a string), in order to use dict
extraction instead of list extraction.</li>
<li>new named elements can be added (in a parse action, for instance), using the same
syntax as adding an item to a dict (<tt class="docutils literal"><span class="pre">parseResults["X"]="new</span> item"</tt>); named elements can be removed using <tt class="docutils literal">del <span class="pre">parseResults["X"]</span></tt></li>
</ul>
</li>
<li>as a nested list<ul>
<li>results returned from the Group class are encapsulated within their
own list structure, so that the tokens can be handled as a hierarchical
tree</li>
</ul>
</li>
</ul>
<p>ParseResults can also be converted to an ordinary list of strings
by calling <tt class="docutils literal">asList()</tt>. Note that this will strip the results of any
field names that have been defined for any embedded parse elements.
(The <tt class="docutils literal">pprint</tt> module is especially good at printing out the nested contents
given by <tt class="docutils literal">asList()</tt>.)</p>
<p>Finally, ParseResults can be converted to an XML string by calling <tt class="docutils literal">asXML()</tt>. Where
possible, results will be tagged using the results names defined for the respective
ParseExpressions. <tt class="docutils literal">asXML()</tt> takes two optional arguments:</p>
<ul class="simple">
<li><tt class="docutils literal">doctagname</tt> - for ParseResults that do not have a defined name, this argument
will wrap the resulting XML in a set of opening and closing tags <tt class="docutils literal"><doctagname></tt>
and <tt class="docutils literal"></doctagname></tt>.</li>
<li><tt class="docutils literal">namedItemsOnly</tt> (default=<tt class="docutils literal">False</tt>) - flag to indicate if the generated XML should
skip items that do not have defined names. If a nested group item is named, then all
embedded items will be included, whether they have names or not.</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="exception-classes-and-troubleshooting">
<h2><a class="toc-backref" href="#id13">2.9 Exception classes and Troubleshooting</a></h2>
<ul id="parseexception">
<li><p class="first"><tt class="docutils literal">ParseException</tt> - exception returned when a grammar parse fails;
ParseExceptions have attributes loc, msg, line, lineno, and column; to view the
text line and location where the reported ParseException occurs, use:</p>
<pre class="literal-block">
except ParseException, err:
print err.line
print " "*(err.column-1) + "^"
print err
</pre>
</li>
<li><p class="first"><tt class="docutils literal">RecursiveGrammarException</tt> - exception returned by <tt class="docutils literal">validate()</tt> if
the grammar contains a recursive infinite loop, such as:</p>
<pre class="literal-block">
badGrammar = Forward()
goodToken = Literal("A")
badGrammar <<= Optional(goodToken) + badGrammar
</pre>
</li>
<li><p class="first"><tt class="docutils literal">ParseFatalException</tt> - exception that parse actions can raise to stop parsing
immediately. Should be used when a semantic error is found in the input text, such
as a mismatched XML tag.</p>
</li>
<li><p class="first"><tt class="docutils literal">ParseSyntaxException</tt> - subclass of <tt class="docutils literal">ParseFatalException</tt> raised when a
syntax error is found, based on the use of the '-' operator when defining
a sequence of expressions in an <tt class="docutils literal">And</tt> expression.</p>
</li>
</ul>
<p>You can also get some insights into the parsing logic using diagnostic parse actions,
and setDebug(), or test the matching of expression fragments by testing them using
scanString().</p>
</div>
</div>
<div class="section" id="miscellaneous-attributes-and-methods">
<h1><a class="toc-backref" href="#id14">3 Miscellaneous attributes and methods</a></h1>
<div class="section" id="helper-methods">
<h2><a class="toc-backref" href="#id15">3.1 Helper methods</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal">delimitedList( expr, <span class="pre">delim=',')</span></tt> - convenience function for
matching one or more occurrences of expr, separated by delim.
By default, the delimiters are suppressed, so the returned results contain
only the separate list elements. Can optionally specify <tt class="docutils literal">combine=True</tt>,
indicating that the expressions and delimiters should be returned as one
combined value (useful for scoped variables, such as "a.b.c", or
"a::b::c", or paths such as "a/b/c").</p>
</li>
<li><p class="first"><tt class="docutils literal">countedArray( expr )</tt> - convenience function for a pattern where an list of
instances of the given expression are preceded by an integer giving the count of
elements in the list. Returns an expression that parses the leading integer,
reads exactly that many expressions, and returns the array of expressions in the
parse results - the leading integer is suppressed from the results (although it
is easily reconstructed by using len on the returned array).</p>
</li>
<li><p class="first"><tt class="docutils literal">oneOf( string, caseless=False )</tt> - convenience function for quickly declaring an
alternative set of <tt class="docutils literal">Literal</tt> tokens, by splitting the given string on
whitespace boundaries. The tokens are sorted so that longer
matches are attempted first; this ensures that a short token does
not mask a longer one that starts with the same characters. If <tt class="docutils literal">caseless=True</tt>,
will create an alternative set of CaselessLiteral tokens.</p>
</li>
<li><p class="first"><tt class="docutils literal">dictOf( key, value )</tt> - convenience function for quickly declaring a
dictionary pattern of <tt class="docutils literal">Dict( ZeroOrMore( Group( key + value ) ) )</tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal">makeHTMLTags( tagName )</tt> and <tt class="docutils literal">makeXMLTags( tagName )</tt> - convenience
functions to create definitions of opening and closing tag expressions. Returns
a pair of expressions, for the corresponding <tag> and </tag> strings. Includes
support for attributes in the opening tag, such as <tag attr1="abc"> - attributes
are returned as keyed tokens in the returned ParseResults. <tt class="docutils literal">makeHTMLTags</tt> is less
restrictive than <tt class="docutils literal">makeXMLTags</tt>, especially with respect to case sensitivity.</p>
</li>
<li><p class="first"><tt class="docutils literal">infixNotation(baseOperand, operatorList)</tt> - (formerly named <tt class="docutils literal">operatorPrecedence</tt>) convenience function to define a
grammar for parsing infix notation
expressions with a hierarchical precedence of operators. To use the <tt class="docutils literal">infixNotation</tt>
helper:</p>
<ol class="arabic simple">
<li>Define the base "atom" operand term of the grammar.
For this simple grammar, the smallest operand is either
and integer or a variable. This will be the first argument
to the <tt class="docutils literal">infixNotation</tt> method.</li>
<li>Define a list of tuples for each level of operator
precendence. Each tuple is of the form
<tt class="docutils literal">(opExpr, numTerms, rightLeftAssoc, parseAction)</tt>, where:<ul>
<li><tt class="docutils literal">opExpr</tt> is the pyparsing expression for the operator;
may also be a string, which will be converted to a Literal; if
None, indicates an empty operator, such as the implied
multiplication operation between 'm' and 'x' in "y = mx + b".
If <tt class="docutils literal">numTerms</tt> parameter is 3, this must be a 2-tuple containing the 2 delimiting operators.</li>
<li><tt class="docutils literal">numTerms</tt> is the number of terms for this operator (must
be 1,2, or 3)</li>
<li><tt class="docutils literal">rightLeftAssoc</tt> is the indicator whether the operator is
right or left associative, using the pyparsing-defined
constants <tt class="docutils literal">opAssoc.RIGHT</tt> and <tt class="docutils literal">opAssoc.LEFT</tt>.</li>
<li><tt class="docutils literal">parseAction</tt> is the parse action to be associated with
expressions matching this operator expression (the
parse action tuple member may be omitted)</li>
</ul>
</li>
<li>Call <tt class="docutils literal">infixNotation</tt> passing the operand expression and
the operator precedence list, and save the returned value
as the generated pyparsing expression. You can then use
this expression to parse input strings, or incorporate it
into a larger, more complex grammar.</li>
</ol>
</li>
<li><p class="first"><tt class="docutils literal">matchPreviousLiteral</tt> and <tt class="docutils literal">matchPreviousExpr</tt> - function to define and
expression that matches the same content
as was parsed in a previous parse expression. For instance:</p>
<pre class="literal-block">
first = Word(nums)
matchExpr = first + ":" + matchPreviousLiteral(first)
</pre>
<p>will match "1:1", but not "1:2". Since this matches at the literal
level, this will also match the leading "1:1" in "1:10".</p>
<p>In contrast:</p>
<pre class="literal-block">
first = Word(nums)
matchExpr = first + ":" + matchPreviousExpr(first)
</pre>
<p>will <em>not</em> match the leading "1:1" in "1:10"; the expressions are
evaluated first, and then compared, so "1" is compared with "10".</p>
</li>
<li><p class="first"><tt class="docutils literal">nestedExpr(opener, closer, content=None, ignoreExpr=quotedString)</tt> - method for defining nested
lists enclosed in opening and closing delimiters.</p>
<ul class="simple">
<li><tt class="docutils literal">opener</tt> - opening character for a nested list (default="("); can also be a pyparsing expression</li>
<li><tt class="docutils literal">closer</tt> - closing character for a nested list (default=")"); can also be a pyparsing expression</li>
<li><tt class="docutils literal">content</tt> - expression for items within the nested lists (default=None)</li>
<li><tt class="docutils literal">ignoreExpr</tt> - expression for ignoring opening and closing delimiters (default=quotedString)</li>
</ul>
<p>If an expression is not provided for the content argument, the nested
expression will capture all whitespace-delimited content between delimiters
as a list of separate values.</p>
<p>Use the <tt class="docutils literal">ignoreExpr</tt> argument to define expressions that may contain
opening or closing characters that should not be treated as opening
or closing characters for nesting, such as quotedString or a comment
expression. Specify multiple expressions using an Or or MatchFirst.
The default is quotedString, but if no expressions are to be ignored,
then pass None for this argument.</p>
</li>
<li><p class="first"><tt class="docutils literal">indentedBlock( statementExpr, indentationStackVar, indent=True)</tt> -
function to define an indented block of statements, similar to
indentation-based blocking in Python source code:</p>
<ul class="simple">
<li><tt class="docutils literal">statementExpr</tt> - the expression defining a statement that
will be found in the indented block; a valid indentedBlock
must contain at least 1 matching statementExpr</li>
<li><tt class="docutils literal">indentationStackVar</tt> - a Python list variable; this variable
should be common to all <tt class="docutils literal">indentedBlock</tt> expressions defined
within the same grammar, and should be reinitialized to [1]
each time the grammar is to be used</li>
<li><tt class="docutils literal">indent</tt> - a boolean flag indicating whether the expressions
within the block must be indented from the current parse
location; if using indentedBlock to define the left-most
statements (all starting in column 1), set indent to False</li>
</ul>
</li>
</ul>
<ul id="originaltextfor">
<li><p class="first"><tt class="docutils literal">originalTextFor( expr )</tt> - helper function to preserve the originally parsed text, regardless of any
token processing or conversion done by the contained expression. For instance, the following expression:</p>
<pre class="literal-block">
fullName = Word(alphas) + Word(alphas)
</pre>
<p>will return the parse of "John Smith" as ['John', 'Smith']. In some applications, the actual name as it
was given in the input string is what is desired. To do this, use <tt class="docutils literal">originalTextFor</tt>:</p>
<pre class="literal-block">
fullName = originalTextFor(Word(alphas) + Word(alphas))
</pre>
</li>
<li><p class="first"><tt class="docutils literal">ungroup( expr )</tt> - function to "ungroup" returned tokens; useful
to undo the default behavior of And to always group the returned tokens, even
if there is only one in the list. (New in 1.5.6)</p>
</li>
<li><p class="first"><tt class="docutils literal">lineno( loc, string )</tt> - function to give the line number of the
location within the string; the first line is line 1, newlines
start new rows</p>
</li>
<li><p class="first"><tt class="docutils literal">col( loc, string )</tt> - function to give the column number of the
location within the string; the first column is column 1,
newlines reset the column number to 1</p>
</li>
<li><p class="first"><tt class="docutils literal">line( loc, string )</tt> - function to retrieve the line of text
representing <tt class="docutils literal">lineno( loc, string )</tt>; useful when printing out diagnostic
messages for exceptions</p>
</li>
<li><p class="first"><tt class="docutils literal">srange( rangeSpec )</tt> - function to define a string of characters,
given a string of the form used by regexp string ranges, such as <tt class="docutils literal"><span class="pre">"[0-9]"</span></tt> for
all numeric digits, <tt class="docutils literal"><span class="pre">"[A-Z_]"</span></tt> for uppercase characters plus underscore, and
so on (note that rangeSpec does not include support for generic regular
expressions, just string range specs)</p>
</li>
<li><p class="first"><tt class="docutils literal">getTokensEndLoc()</tt> - function to call from within a parse action to get
the ending location for the matched tokens</p>
</li>
<li><p class="first"><tt class="docutils literal">traceParseAction(fn)</tt> - decorator function to debug parse actions. Lists
each call, called arguments, and return value or exception</p>
</li>
</ul>
</div>
<div class="section" id="helper-parse-actions">
<h2><a class="toc-backref" href="#id16">3.2 Helper parse actions</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal">removeQuotes</tt> - removes the first and last characters of a quoted string;
useful to remove the delimiting quotes from quoted strings</p>
</li>
<li><p class="first"><tt class="docutils literal">replaceWith(replString)</tt> - returns a parse action that simply returns the
replString; useful when using transformString, or converting HTML entities, as in:</p>
<pre class="literal-block">
nbsp = Literal("&nbsp;").setParseAction( replaceWith("<BLANK>") )
</pre>
</li>
<li><p class="first"><tt class="docutils literal">keepOriginalText</tt>- (deprecated, use <a class="reference internal" href="#originaltextfor">originalTextFor</a> instead) restores any internal whitespace or suppressed
text within the tokens for a matched parse
expression. This is especially useful when defining expressions
for scanString or transformString applications.</p>
</li>
<li><p class="first"><tt class="docutils literal">withAttribute( *args, **kwargs )</tt> - helper to create a validating parse action to be used with start tags created
with <tt class="docutils literal">makeXMLTags</tt> or <tt class="docutils literal">makeHTMLTags</tt>. Use <tt class="docutils literal">withAttribute</tt> to qualify a starting tag
with a required attribute value, to avoid false matches on common tags such as
<tt class="docutils literal"><TD></tt> or <tt class="docutils literal"><DIV></tt>.</p>
<p><tt class="docutils literal">withAttribute</tt> can be called with:</p>
<ul class="simple">
<li>keyword arguments, as in <tt class="docutils literal"><span class="pre">(class="Customer",align="right")</span></tt>, or</li>
<li>a list of name-value tuples, as in <tt class="docutils literal">( ("ns1:class", <span class="pre">"Customer"),</span> <span class="pre">("ns2:align","right")</span> )</tt></li>
</ul>
<p>An attribute can be specified to have the special value
<tt class="docutils literal">withAttribute.ANY_VALUE</tt>, which will match any value - use this to
ensure that an attribute is present but any attribute value is
acceptable.</p>
</li>
<li><p class="first"><tt class="docutils literal">downcaseTokens</tt> - converts all matched tokens to lowercase</p>
</li>
<li><p class="first"><tt class="docutils literal">upcaseTokens</tt> - converts all matched tokens to uppercase</p>
</li>
<li><p class="first"><tt class="docutils literal">matchOnlyAtCol( columnNumber )</tt> - a parse action that verifies that
an expression was matched at a particular column, raising a
ParseException if matching at a different column number; useful when parsing
tabular data</p>
</li>
</ul>
</div>
<div class="section" id="common-string-and-token-constants">
<h2><a class="toc-backref" href="#id17">3.3 Common string and token constants</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal">alphas</tt> - same as <tt class="docutils literal">string.letters</tt></p>
</li>
<li><p class="first"><tt class="docutils literal">nums</tt> - same as <tt class="docutils literal">string.digits</tt></p>
</li>
<li><p class="first"><tt class="docutils literal">alphanums</tt> - a string containing <tt class="docutils literal">alphas + nums</tt></p>
</li>
<li><p class="first"><tt class="docutils literal">alphas8bit</tt> - a string containing alphabetic 8-bit characters:</p>
<pre class="literal-block">
ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþ
</pre>
</li>
<li><p class="first"><tt class="docutils literal">printables</tt> - same as <tt class="docutils literal">string.printable</tt>, minus the space (<tt class="docutils literal">' '</tt>) character</p>
</li>
<li><p class="first"><tt class="docutils literal">empty</tt> - a global <tt class="docutils literal">Empty()</tt>; will always match</p>
</li>
<li><p class="first"><tt class="docutils literal">sglQuotedString</tt> - a string of characters enclosed in 's; may
include whitespace, but not newlines</p>
</li>
<li><p class="first"><tt class="docutils literal">dblQuotedString</tt> - a string of characters enclosed in "s; may
include whitespace, but not newlines</p>
</li>
<li><p class="first"><tt class="docutils literal">quotedString</tt> - <tt class="docutils literal">sglQuotedString | dblQuotedString</tt></p>
</li>
<li><p class="first"><tt class="docutils literal">cStyleComment</tt> - a comment block delimited by <tt class="docutils literal"><span class="pre">'/*'</span></tt> and <tt class="docutils literal"><span class="pre">'*/'</span></tt> sequences; can span
multiple lines, but does not support nesting of comments</p>
</li>
<li><p class="first"><tt class="docutils literal">htmlComment</tt> - a comment block delimited by <tt class="docutils literal"><span class="pre">'<!--'</span></tt> and <tt class="docutils literal"><span class="pre">'-->'</span></tt> sequences; can span
multiple lines, but does not support nesting of comments</p>
</li>
<li><p class="first"><tt class="docutils literal">commaSeparatedList</tt> - similar to <tt class="docutils literal">delimitedList</tt>, except that the
list expressions can be any text value, or a quoted string; quoted strings can
safely include commas without incorrectly breaking the string into two tokens</p>
</li>
<li><p class="first"><tt class="docutils literal">restOfLine</tt> - all remaining printable characters up to but not including the next
newline</p>
</li>
</ul>
</div>
</div>
</div>
</body>
</html>
|
