Mercurial > cpython-lru_cache-weakref

annotate Doc/libregex.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents a16decbb9716
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{regex}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{regex}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module provides regular expression matching operations similar to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 those found in Emacs. It is always available.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
7 By default the patterns are Emacs-style regular expressions
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
8 (with one exception). There is
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 a way to change the syntax to match that of several well-known
2964
122d149fa801 warn about bacslash-s lacking
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
10 \UNIX{} utilities. The exception is that Emacs' \samp{\e s}
122d149fa801 warn about bacslash-s lacking
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
11 pattern is not supported, since the original implementation references
122d149fa801 warn about bacslash-s lacking
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
12 the Emacs syntax tables.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 This module is 8-bit clean: both patterns and strings may contain null
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 bytes and characters whose high bit is set.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
17 \strong{Please note:} There is a little-known fact about Python string
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
18 literals which means that you don't usually have to worry about
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
19 doubling backslashes, even though they are used to escape special
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
20 characters in string literals as well as in regular expressions. This
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
21 is because Python doesn't remove backslashes from string literals if
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
22 they are followed by an unrecognized escape character.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
23 \emph{However}, if you want to include a literal \dfn{backslash} in a
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
24 regular expression represented as a string literal, you have to
5186
a16decbb9716 Hint about [\] trick to avoid quad backslashes.
Guido van Rossum <guido@python.org>
parents: 5131
diff changeset
25 \emph{quadruple} it or enclose it in a singleton character class.
a16decbb9716 Hint about [\] trick to avoid quad backslashes.
Guido van Rossum <guido@python.org>
parents: 5131
diff changeset
26 E.g.\ to extract \LaTeX\ \samp{\e section\{{\rm
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
27 \ldots}\}} headers from a document, you can use this pattern:
5186
a16decbb9716 Hint about [\] trick to avoid quad backslashes.
Guido van Rossum <guido@python.org>
parents: 5131
diff changeset
28 \code{'[\e ] section\{\e (.*\e )\}'}. \emph{Another exception:}
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
29 the escape sequece \samp{\e b} is significant in string literals
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
30 (where it means the ASCII bell character) as well as in Emacs regular
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
31 expressions (where it stands for a word boundary), so in order to
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
32 search for a word boundary, you should use the pattern \code{'\e \e b'}.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
33 Similarly, a backslash followed by a digit 0-7 should be doubled to
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
34 avoid interpretation as an octal escape.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
35
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
36 \subsection{Regular Expressions}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
37
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
38 A regular expression (or RE) specifies a set of strings that matches
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
39 it; the functions in this module let you check if a particular string
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
40 matches a given regular expression (or if a given regular expression
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
41 matches a particular string, which comes down to the same thing).
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
42
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
43 Regular expressions can be concatenated to form new regular
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
44 expressions; if \emph{A} and \emph{B} are both regular expressions,
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
45 then \emph{AB} is also an regular expression. If a string \emph{p}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
46 matches A and another string \emph{q} matches B, the string \emph{pq}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
47 will match AB. Thus, complex expressions can easily be constructed
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
48 from simpler ones like the primitives described here. For details of
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
49 the theory and implementation of regular expressions, consult almost
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
50 any textbook about compiler construction.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
51
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
52 % XXX The reference could be made more specific, say to
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
53 % "Compilers: Principles, Techniques and Tools", by Alfred V. Aho,
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
54 % Ravi Sethi, and Jeffrey D. Ullman, or some FA text.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
55
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
56 A brief explanation of the format of regular expressions follows.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
57
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
58 Regular expressions can contain both special and ordinary characters.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
59 Ordinary characters, like '\code{A}', '\code{a}', or '\code{0}', are
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
60 the simplest regular expressions; they simply match themselves. You
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
61 can concatenate ordinary characters, so '\code{last}' matches the
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
62 characters 'last'. (In the rest of this section, we'll write RE's in
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
63 \code{this special font}, usually without quotes, and strings to be
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
64 matched 'in single quotes'.)
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
65
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
66 Special characters either stand for classes of ordinary characters, or
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
67 affect how the regular expressions around them are interpreted.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
68
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
69 The special characters are:
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
70 \begin{itemize}
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
71 \item[\code{.}] (Dot.) Matches any character except a newline.
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
72 \item[\code{\^}] (Caret.) Matches the start of the string.
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
73 \item[\code{\$}] Matches the end of the string.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
74 \code{foo} matches both 'foo' and 'foobar', while the regular
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
75 expression '\code{foo\$}' matches only 'foo'.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
76 \item[\code{*}] Causes the resulting RE to
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
77 match 0 or more repetitions of the preceding RE. \code{ab*} will
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
78 match 'a', 'ab', or 'a' followed by any number of 'b's.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
79 \item[\code{+}] Causes the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
80 resulting RE to match 1 or more repetitions of the preceding RE.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
81 \code{ab+} will match 'a' followed by any non-zero number of 'b's; it
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
82 will not match just 'a'.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
83 \item[\code{?}] Causes the resulting RE to
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
84 match 0 or 1 repetitions of the preceding RE. \code{ab?} will
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
85 match either 'a' or 'ab'.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
86
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
87 \item[\code{\e}] Either escapes special characters (permitting you to match
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
88 characters like '*?+\&\$'), or signals a special sequence; special
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
89 sequences are discussed below. Remember that Python also uses the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
90 backslash as an escape sequence in string literals; if the escape
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
91 sequence isn't recognized by Python's parser, the backslash and
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
92 subsequent character are included in the resulting string. However,
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
93 if Python would recognize the resulting sequence, the backslash should
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
94 be repeated twice.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
95
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
96 \item[\code{[]}] Used to indicate a set of characters. Characters can
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
97 be listed individually, or a range is indicated by giving two
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
98 characters and separating them by a '-'. Special characters are
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
99 not active inside sets. For example, \code{[akm\$]}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
100 will match any of the characters 'a', 'k', 'm', or '\$'; \code{[a-z]} will
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
101 match any lowercase letter.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
102
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
103 If you want to include a \code{]} inside a
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
104 set, it must be the first character of the set; to include a \code{-},
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
105 place it as the first or last character.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
106
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
107 Characters \emph{not} within a range can be matched by including a
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
108 \code{\^} as the first character of the set; \code{\^} elsewhere will
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
109 simply match the '\code{\^}' character.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
110 \end{itemize}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
111
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
112 The special sequences consist of '\code{\e}' and a character
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
113 from the list below. If the ordinary character is not on the list,
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
114 then the resulting RE will match the second character. For example,
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
115 \code{\e\$} matches the character '\$'. Ones where the backslash
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
116 should be doubled are indicated.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
117
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
118 \begin{itemize}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
119 \item[\code{\e|}]\code{A\e|B}, where A and B can be arbitrary REs,
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
120 creates a regular expression that will match either A or B. This can
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
121 be used inside groups (see below) as well.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
122 %
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
123 \item[\code{\e( \e)}] Indicates the start and end of a group; the
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
124 contents of a group can be matched later in the string with the
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
125 \code{\e [1-9]} special sequence, described next.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
126 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
127 {\fulllineitems\item[\code{\e \e 1, ... \e \e 7, \e 8, \e 9}]
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
128 Matches the contents of the group of the same
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
129 number. For example, \code{\e (.+\e ) \e \e 1} matches 'the the' or
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
130 '55 55', but not 'the end' (note the space after the group). This
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
131 special sequence can only be used to match one of the first 9 groups;
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
132 groups with higher numbers can be matched using the \code{\e v}
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
133 sequence. (\code{\e 8} and \code{\e 9} don't need a double backslash
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
134 because they are not octal digits.)}
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
135 %
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
136 \item[\code{\e \e b}] Matches the empty string, but only at the
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
137 beginning or end of a word. A word is defined as a sequence of
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
138 alphanumeric characters, so the end of a word is indicated by
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
139 whitespace or a non-alphanumeric character.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
140 %
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
141 \item[\code{\e B}] Matches the empty string, but when it is \emph{not} at the
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
142 beginning or end of a word.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
143 %
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
144 \item[\code{\e v}] Must be followed by a two digit decimal number, and
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
145 matches the contents of the group of the same number. The group number must be between 1 and 99, inclusive.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
146 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
147 \item[\code{\e w}]Matches any alphanumeric character; this is
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
148 equivalent to the set \code{[a-zA-Z0-9]}.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
149 %
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
150 \item[\code{\e W}] Matches any non-alphanumeric character; this is
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
151 equivalent to the set \code{[\^a-zA-Z0-9]}.
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
152 \item[\code{\e <}] Matches the empty string, but only at the beginning of a
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
153 word. A word is defined as a sequence of alphanumeric characters, so
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
154 the end of a word is indicated by whitespace or a non-alphanumeric
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
155 character.
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
156 \item[\code{\e >}] Matches the empty string, but only at the end of a
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
157 word.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
158
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
159 \item[\code{\e \e \e \e}] Matches a literal backslash.
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
160
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
161 % In Emacs, the following two are start of buffer/end of buffer. In
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
162 % Python they seem to be synonyms for ^$.
4728
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
163 \item[\code{\e `}] Like \code{\^}, this only matches at the start of the
b218f294b726 (lib<all sorts of stuff>.tex):
Fred Drake <fdrake@acm.org>
parents: 4496
diff changeset
164 string.
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
165 \item[\code{\e \e '}] Like \code{\$}, this only matches at the end of the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
166 string.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
167 % end of buffer
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
168 \end{itemize}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
169
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
170 \subsection{Module Contents}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
171
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172 The module defines these functions, and an exception:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
174 \renewcommand{\indexsubitem}{(in module regex)}
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
175
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176 \begin{funcdesc}{match}{pattern\, string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
177 Return how many characters at the beginning of \var{string} match
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 the regular expression \var{pattern}. Return \code{-1} if the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
179 string does not match the pattern (this is different from a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 zero-length match!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
182
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 \begin{funcdesc}{search}{pattern\, string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 Return the first position in \var{string} that matches the regular
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
185 expression \var{pattern}. Return \code{-1} if no position in the string
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 matches the pattern (this is different from a zero-length match
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 anywhere!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
189
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1476
diff changeset
190 \begin{funcdesc}{compile}{pattern\optional{\, translate}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
191 Compile a regular expression pattern into a regular expression
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
192 object, which can be used for matching using its \code{match} and
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
193 \code{search} methods, described below. The optional argument
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 \var{translate}, if present, must be a 256-character string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
195 indicating how characters (both of the pattern and of the strings to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
196 be matched) are translated before comparing them; the \code{i}-th
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
197 element of the string gives the translation for the character with
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
198 \ASCII{} code \code{i}. This can be used to implement
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
199 case-insensitive matching; see the \code{casefold} data item below.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
200
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
201 The sequence
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
202
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
203 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
204 prog = regex.compile(pat)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205 result = prog.match(str)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
206 \end{verbatim}\ecode
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
207
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
208 is equivalent to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
209
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
211 result = regex.match(pat, str)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
212 \end{verbatim}\ecode
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
213
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 but the version using \code{compile()} is more efficient when multiple
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
215 regular expressions are used concurrently in a single program. (The
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
216 compiled version of the last pattern passed to \code{regex.match()} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
217 \code{regex.search()} is cached, so programs that use only a single
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
218 regular expression at a time needn't worry about compiling regular
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219 expressions.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
220 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 \begin{funcdesc}{set_syntax}{flags}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
223 Set the syntax to be used by future calls to \code{compile},
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 \code{match} and \code{search}. (Already compiled expression objects
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
225 are not affected.) The argument is an integer which is the OR of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
226 several flag bits. The return value is the previous value of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
227 the syntax flags. Names for the flags are defined in the standard
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
228 module \code{regex_syntax}; read the file \file{regex_syntax.py} for
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
229 more information.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
230 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
231
5131
ec45276a6dad Document the new get_syntax() function.
Barry Warsaw <barry@python.org>
parents: 4728
diff changeset
232 \begin{funcdesc}{get_syntax}{}
ec45276a6dad Document the new get_syntax() function.
Barry Warsaw <barry@python.org>
parents: 4728
diff changeset
233 Returns the current value of the syntax flags as an integer.
ec45276a6dad Document the new get_syntax() function.
Barry Warsaw <barry@python.org>
parents: 4728
diff changeset
234 \end{funcdesc}
ec45276a6dad Document the new get_syntax() function.
Barry Warsaw <barry@python.org>
parents: 4728
diff changeset
235
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1476
diff changeset
236 \begin{funcdesc}{symcomp}{pattern\optional{\, translate}}
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
237 This is like \code{compile}, but supports symbolic group names: if a
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2448
diff changeset
238 parenthesis-enclosed group begins with a group name in angular
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
239 brackets, e.g. \code{'\e(<id>[a-z][a-z0-9]*\e)'}, the group can
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
240 be referenced by its name in arguments to the \code{group} method of
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
241 the resulting compiled regular expression object, like this:
2448
2c6565f1b7f8 document restriction on group names
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
242 \code{p.group('id')}. Group names may contain alphanumeric characters
2c6565f1b7f8 document restriction on group names
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
243 and \code{'_'} only.
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
244 \end{funcdesc}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
245
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
246 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
247 Exception raised when a string passed to one of the functions here
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
248 is not a valid regular expression (e.g., unmatched parentheses) or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
249 when some other error occurs during compilation or matching. (It is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
250 never an error if a string contains no match for a pattern.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
251 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
252
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
253 \begin{datadesc}{casefold}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
254 A string suitable to pass as \var{translate} argument to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
255 \code{compile} to map all upper case characters to their lowercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
256 equivalents.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
257 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
258
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
259 \noindent
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
260 Compiled regular expression objects support these methods:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
261
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
262 \renewcommand{\indexsubitem}{(regex method)}
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1476
diff changeset
263 \begin{funcdesc}{match}{string\optional{\, pos}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
264 Return how many characters at the beginning of \var{string} match
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
265 the compiled regular expression. Return \code{-1} if the string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
266 does not match the pattern (this is different from a zero-length
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
267 match!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
268
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
269 The optional second parameter \var{pos} gives an index in the string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
270 where the search is to start; it defaults to \code{0}. This is not
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
271 completely equivalent to slicing the string; the \code{'\^'} pattern
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
272 character matches at the real begin of the string and at positions
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
273 just after a newline, not necessarily at the index where the search
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
274 is to start.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
275 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
276
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1476
diff changeset
277 \begin{funcdesc}{search}{string\optional{\, pos}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
278 Return the first position in \var{string} that matches the regular
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
279 expression \code{pattern}. Return \code{-1} if no position in the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
280 string matches the pattern (this is different from a zero-length
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
281 match anywhere!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
282
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
283 The optional second parameter has the same meaning as for the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
284 \code{match} method.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
285 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
286
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
287 \begin{funcdesc}{group}{index\, index\, ...}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
288 This method is only valid when the last call to the \code{match}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
289 or \code{search} method found a match. It returns one or more
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
290 groups of the match. If there is a single \var{index} argument,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
291 the result is a single string; if there are multiple arguments, the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
292 result is a tuple with one item per argument. If the \var{index} is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
293 zero, the corresponding return value is the entire matching string; if
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
294 it is in the inclusive range [1..99], it is the string matching the
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
295 the corresponding parenthesized group (using the default syntax,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
296 groups are parenthesized using \code{\\(} and \code{\\)}). If no
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
297 such group exists, the corresponding result is \code{None}.
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
298
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
299 If the regular expression was compiled by \code{symcomp} instead of
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
300 \code{compile}, the \var{index} arguments may also be strings
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
301 identifying groups by their group name.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
302 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
303
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
304 \noindent
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
305 Compiled regular expressions support these data attributes:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
306
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
307 \renewcommand{\indexsubitem}{(regex attribute)}
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
308
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
309 \begin{datadesc}{regs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
310 When the last call to the \code{match} or \code{search} method found a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
311 match, this is a tuple of pairs of indices corresponding to the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
312 beginning and end of all parenthesized groups in the pattern. Indices
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
313 are relative to the string argument passed to \code{match} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
314 \code{search}. The 0-th tuple gives the beginning and end or the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
315 whole pattern. When the last match or search failed, this is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
316 \code{None}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
317 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
318
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
319 \begin{datadesc}{last}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
320 When the last call to the \code{match} or \code{search} method found a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
321 match, this is the string argument passed to that method. When the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
322 last match or search failed, this is \code{None}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
323 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
324
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
325 \begin{datadesc}{translate}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
326 This is the value of the \var{translate} argument to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
327 \code{regex.compile} that created this regular expression object. If
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
328 the \var{translate} argument was omitted in the \code{regex.compile}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
329 call, this is \code{None}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
330 \end{datadesc}
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
331
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
332 \begin{datadesc}{givenpat}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
333 The regular expression pattern as passed to \code{compile} or
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
334 \code{symcomp}.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
335 \end{datadesc}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
336
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
337 \begin{datadesc}{realpat}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
338 The regular expression after stripping the group names for regular
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
339 expressions compiled with \code{symcomp}. Same as \code{givenpat}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
340 otherwise.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
341 \end{datadesc}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
342
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
343 \begin{datadesc}{groupindex}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
344 A dictionary giving the mapping from symbolic group names to numerical
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
345 group indices for regular expressions compiled with \code{symcomp}.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
346 \code{None} otherwise.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
347 \end{datadesc}