Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libregex.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents eae8ab3d24e0
children b218f294b726
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
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2448
diff changeset
25 \emph{quadruple} it. 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
26 \ldots}\}} headers from a document, you can use this pattern:
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
27 \code{'\e \e \e \e section\{\e (.*\e )\}'}. \emph{Another exception:}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
28 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
29 (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
30 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
31 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
32 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
33 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
34
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
35 \subsection{Regular Expressions}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
36
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
37 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
38 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
39 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
40 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
41
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
42 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
43 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
44 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
45 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
46 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
47 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
48 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
49 any textbook about compiler construction.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
50
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
51 % 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
52 % "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
53 % 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
54
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
55 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
56
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
57 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
58 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
59 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
60 can concatenate ordinary characters, so '\code{last}' matches the
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
61 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
62 \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
63 matched 'in single quotes'.)
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
64
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
65 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
66 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
67
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
68 The special characters are:
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
69 \begin{itemize}
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
70 \item[\code{.}]{(Dot.) Matches any character except a newline.}
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
71 \item[\code{\^}]{(Caret.) Matches the start of the string.}
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
72 \item[\code{\$}]{Matches the end of the string.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
73 \code{foo} matches both 'foo' and 'foobar', while the regular
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
74 expression '\code{foo\$}' matches only 'foo'.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
75 \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
76 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
77 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
78 \item[\code{+}] Causes the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
79 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
80 \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
81 will not match just 'a'.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
82 \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
83 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
84 match either 'a' or 'ab'.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
85
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
86 \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
87 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
88 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
89 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
90 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
91 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
92 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
93 be repeated twice.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
94
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
95 \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
96 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
97 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
98 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
99 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
100 match any lowercase letter.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
101
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
102 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
103 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
104 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
105
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
106 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
107 \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
108 simply match the '\code{\^}' character.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
109 \end{itemize}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
110
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
111 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
112 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
113 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
114 \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
115 should be doubled are indicated.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
116
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
117 \begin{itemize}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
118 \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
119 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
120 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
121 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
122 \item[\code{\e( \e)}]{Indicates the start and end of a group; the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
123 contents of a group can be matched later in the string with the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
124 \code{\e \[1-9]} special sequence, described next.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
125 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
126 {\fulllineitems\item[\code{\e \e 1, ... \e \e 7, \e 8, \e 9}]
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
127 {Matches the contents of the group of the same
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
128 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
129 '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
130 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
131 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
132 sequence. (\code{\e 8} and \code{\e 9} don't need a double backslash
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
133 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
134 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
135 \item[\code{\e \e b}]{Matches the empty string, but only at the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
136 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
137 alphanumeric characters, so the end of a word is indicated by
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
138 whitespace or a non-alphanumeric character.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
139 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
140 \item[\code{\e B}]{Matches the empty string, but when it is \emph{not} at the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
141 beginning or end of a word.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
142 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
143 \item[\code{\e v}]{Must be followed by a two digit decimal number, and
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
144 matches the contents of the group of the same number. The group number must be between 1 and 99, inclusive.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
145 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
146 \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
147 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
148 %
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
149 \item[\code{\e W}]{Matches any non-alphanumeric character; this is
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
150 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
151 \item[\code{\e <}]{Matches the empty string, but only at the beginning of a
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
152 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
153 the end of a word is indicated by whitespace or a non-alphanumeric
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
154 character.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
155 \item[\code{\e >}]{Matches the empty string, but only at the end of a
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
156 word.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
157
4496
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
158 \item[\code{\e \e \e \e}]{Matches a literal backslash.}
eae8ab3d24e0 Small nits only.
Guido van Rossum <guido@python.org>
parents: 3721
diff changeset
159
3721
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
160 % 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
161 % Python they seem to be synonyms for ^$.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
162 \item[\code{\e `}]{Like \code{\^}, this only matches at the start of the
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
163 string.}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
164 \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
165 string.
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
166 % end of buffer
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
167 \end{itemize}
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
168
322f61e4c387 Added Andrew Kuchling's explanation of regexp's.
Guido van Rossum <guido@python.org>
parents: 2964
diff changeset
169 \subsection{Module Contents}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
170
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
171 The module defines these functions, and an exception:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 \renewcommand{\indexsubitem}{(in module regex)}
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
174
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 \begin{funcdesc}{match}{pattern\, string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176 Return how many characters at the beginning of \var{string} match
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
177 the regular expression \var{pattern}. Return \code{-1} if the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 string does not match the pattern (this is different from a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
179 zero-length match!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 \begin{funcdesc}{search}{pattern\, string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 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
184 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
185 matches the pattern (this is different from a zero-length match
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 anywhere!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
188
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1476
diff changeset
189 \begin{funcdesc}{compile}{pattern\optional{\, translate}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
190 Compile a regular expression pattern into a regular expression
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
191 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
192 \code{search} methods, described below. The optional argument
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 \var{translate}, if present, must be a 256-character string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 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
195 be matched) are translated before comparing them; the \code{i}-th
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
196 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
197 \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
198 case-insensitive matching; see the \code{casefold} data item below.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
199
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
200 The sequence
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
201
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
202 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
203 prog = regex.compile(pat)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
204 result = prog.match(str)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205 \end{verbatim}\ecode
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
206
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 is equivalent to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
208
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
209 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 result = regex.match(pat, str)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
211 \end{verbatim}\ecode
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
212
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
213 but the version using \code{compile()} is more efficient when multiple
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 regular expressions are used concurrently in a single program. (The
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
215 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
216 \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
217 regular expression at a time needn't worry about compiling regular
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
218 expressions.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
220
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 \begin{funcdesc}{set_syntax}{flags}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 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
223 \code{match} and \code{search}. (Already compiled expression objects
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 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
225 several flag bits. The return value is the previous value of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
226 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
227 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
228 more information.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
229 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
230
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1476
diff changeset
231 \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
232 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
233 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
234 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
235 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
236 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
237 \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
238 and \code{'_'} only.
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
239 \end{funcdesc}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
240
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
241 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
242 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
243 is not a valid regular expression (e.g., unmatched parentheses) or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
244 when some other error occurs during compilation or matching. (It is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
245 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
246 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
247
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
248 \begin{datadesc}{casefold}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
249 A string suitable to pass as \var{translate} argument to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
250 \code{compile} to map all upper case characters to their lowercase
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
251 equivalents.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
252 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
253
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
254 \noindent
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
255 Compiled regular expression objects support these methods:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
256
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
257 \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
258 \begin{funcdesc}{match}{string\optional{\, pos}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
259 Return how many characters at the beginning of \var{string} match
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
260 the compiled regular expression. Return \code{-1} if the string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
261 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
262 match!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
263
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
264 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
265 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
266 completely equivalent to slicing the string; the \code{'\^'} pattern
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
267 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
268 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
269 is to start.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
270 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
271
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1476
diff changeset
272 \begin{funcdesc}{search}{string\optional{\, pos}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
273 Return the first position in \var{string} that matches the regular
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
274 expression \code{pattern}. Return \code{-1} if no position in the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
275 string matches the pattern (this is different from a zero-length
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
276 match anywhere!).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
277
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
278 The optional second parameter has the same meaning as for the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
279 \code{match} method.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
280 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
281
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
282 \begin{funcdesc}{group}{index\, index\, ...}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
283 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
284 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
285 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
286 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
287 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
288 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
289 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
290 the corresponding parenthesized group (using the default syntax,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
291 groups are parenthesized using \code{\\(} and \code{\\)}). If no
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
292 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
293
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
294 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
295 \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
296 identifying groups by their group name.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
297 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
298
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
299 \noindent
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
300 Compiled regular expressions support these data attributes:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
301
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
302 \renewcommand{\indexsubitem}{(regex attribute)}
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
303
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
304 \begin{datadesc}{regs}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
305 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
306 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
307 beginning and end of all parenthesized groups in the pattern. Indices
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
308 are relative to the string argument passed to \code{match} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
309 \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
310 whole pattern. When the last match or search failed, this is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
311 \code{None}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
312 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
313
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
314 \begin{datadesc}{last}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
315 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
316 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
317 last match or search failed, this is \code{None}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
318 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
319
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
320 \begin{datadesc}{translate}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
321 This is the value of the \var{translate} argument to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
322 \code{regex.compile} that created this regular expression object. If
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
323 the \var{translate} argument was omitted in the \code{regex.compile}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
324 call, this is \code{None}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
325 \end{datadesc}
1476
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
326
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
327 \begin{datadesc}{givenpat}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
328 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
329 \code{symcomp}.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
330 \end{datadesc}
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}{realpat}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
333 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
334 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
335 otherwise.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
336 \end{datadesc}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
337
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
338 \begin{datadesc}{groupindex}
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
339 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
340 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
341 \code{None} otherwise.
48141e68b369 Added symcomp and resulting new data items
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
342 \end{datadesc}