Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{re} --- |
Fred Drake | 062ea2e | 2000-10-06 19:59:22 +0000 | [diff] [blame] | 2 | Regular expression operations} |
Fred Drake | 66da9d6 | 1998-08-07 18:57:18 +0000 | [diff] [blame] | 3 | \declaremodule{standard}{re} |
Fredrik Lundh | e7c38d4 | 2002-10-19 20:22:56 +0000 | [diff] [blame] | 4 | \moduleauthor{Fredrik Lundh}{fredrik@pythonware.com} |
Andrew M. Kuchling | 3adefcc | 2002-10-30 21:08:34 +0000 | [diff] [blame] | 5 | \sectionauthor{Andrew M. Kuchling}{amk@amk.ca} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 6 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 7 | |
Fred Drake | 062ea2e | 2000-10-06 19:59:22 +0000 | [diff] [blame] | 8 | \modulesynopsis{Regular expression search and match operations with a |
| 9 | Perl-style expression syntax.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 10 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 11 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 12 | This module provides regular expression matching operations similar to |
Fred Drake | 062ea2e | 2000-10-06 19:59:22 +0000 | [diff] [blame] | 13 | those found in Perl. Regular expression pattern strings may not |
| 14 | contain null bytes, but can specify the null byte using the |
| 15 | \code{\e\var{number}} notation. Both patterns and strings to be |
| 16 | searched can be Unicode strings as well as 8-bit strings. The |
| 17 | \module{re} module is always available. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 18 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 19 | Regular expressions use the backslash character (\character{\e}) to |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 20 | indicate special forms or to allow special characters to be used |
| 21 | without invoking their special meaning. This collides with Python's |
| 22 | usage of the same character for the same purpose in string literals; |
| 23 | for example, to match a literal backslash, one might have to write |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 24 | \code{'\e\e\e\e'} as the pattern string, because the regular expression |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 25 | must be \samp{\e\e}, and each backslash must be expressed as |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 26 | \samp{\e\e} inside a regular Python string literal. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 27 | |
| 28 | The solution is to use Python's raw string notation for regular |
| 29 | expression patterns; backslashes are not handled in any special way in |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 30 | a string literal prefixed with \character{r}. So \code{r"\e n"} is a |
| 31 | two-character string containing \character{\e} and \character{n}, |
| 32 | while \code{"\e n"} is a one-character string containing a newline. |
| 33 | Usually patterns will be expressed in Python code using this raw |
| 34 | string notation. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 35 | |
Fred Drake | e20bd19 | 2001-04-12 16:47:17 +0000 | [diff] [blame] | 36 | \begin{seealso} |
| 37 | \seetitle{Mastering Regular Expressions}{Book on regular expressions |
Andrew M. Kuchling | 69700ef | 2003-03-04 14:17:05 +0000 | [diff] [blame] | 38 | by Jeffrey Friedl, published by O'Reilly. The second |
| 39 | edition of the book no longer covers Python at all, |
| 40 | but the first edition covered writing good regular expression |
Fred Drake | e20bd19 | 2001-04-12 16:47:17 +0000 | [diff] [blame] | 41 | patterns in great detail.} |
| 42 | \end{seealso} |
| 43 | |
| 44 | |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 45 | \subsection{Regular Expression Syntax \label{re-syntax}} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 46 | |
| 47 | A regular expression (or RE) specifies a set of strings that matches |
| 48 | it; the functions in this module let you check if a particular string |
| 49 | matches a given regular expression (or if a given regular expression |
| 50 | matches a particular string, which comes down to the same thing). |
| 51 | |
| 52 | Regular expressions can be concatenated to form new regular |
| 53 | expressions; if \emph{A} and \emph{B} are both regular expressions, |
Raymond Hettinger | 5bcc933 | 2003-09-10 18:45:12 +0000 | [diff] [blame] | 54 | then \emph{AB} is also a regular expression. In general, if a string |
| 55 | \emph{p} matches \emph{A} and another string \emph{q} matches \emph{B}, |
| 56 | the string \emph{pq} will match AB. This holds unless \emph{A} or |
| 57 | \emph{B} contain low precedence operations; boundary conditions between |
| 58 | \emph{A} and \emph{B}; or have numbered group references. Thus, complex |
Fred Drake | 51629c2 | 2001-08-02 20:52:00 +0000 | [diff] [blame] | 59 | expressions can easily be constructed from simpler primitive |
| 60 | expressions like the ones described here. For details of the theory |
| 61 | and implementation of regular expressions, consult the Friedl book |
Andrew M. Kuchling | 69700ef | 2003-03-04 14:17:05 +0000 | [diff] [blame] | 62 | referenced above, or almost any textbook about compiler construction. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 63 | |
Andrew M. Kuchling | c1cea20 | 1998-10-28 15:44:14 +0000 | [diff] [blame] | 64 | A brief explanation of the format of regular expressions follows. For |
| 65 | further information and a gentler presentation, consult the Regular |
| 66 | Expression HOWTO, accessible from \url{http://www.python.org/doc/howto/}. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 67 | |
| 68 | Regular expressions can contain both special and ordinary characters. |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 69 | Most ordinary characters, like \character{A}, \character{a}, or |
| 70 | \character{0}, are the simplest regular expressions; they simply match |
| 71 | themselves. You can concatenate ordinary characters, so \regexp{last} |
| 72 | matches the string \code{'last'}. (In the rest of this section, we'll |
| 73 | write RE's in \regexp{this special style}, usually without quotes, and |
| 74 | strings to be matched \code{'in single quotes'}.) |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 75 | |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 76 | Some characters, like \character{|} or \character{(}, are special. |
| 77 | Special characters either stand for classes of ordinary characters, or |
| 78 | affect how the regular expressions around them are interpreted. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 79 | |
| 80 | The special characters are: |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 81 | |
Fred Drake | 1e270f0 | 1998-11-30 22:58:12 +0000 | [diff] [blame] | 82 | \begin{list}{}{\leftmargin 0.7in \labelwidth 0.65in} |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 83 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 84 | \item[\character{.}] (Dot.) In the default mode, this matches any |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 85 | character except a newline. If the \constant{DOTALL} flag has been |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 86 | specified, this matches any character including a newline. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 87 | |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 88 | \item[\character{\textasciicircum}] (Caret.) Matches the start of the |
| 89 | string, and in \constant{MULTILINE} mode also matches immediately |
| 90 | after each newline. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 91 | |
Fred Drake | c547b46 | 2001-07-23 21:14:59 +0000 | [diff] [blame] | 92 | \item[\character{\$}] Matches the end of the string or just before the |
| 93 | newline at the end of the string, and in \constant{MULTILINE} mode |
| 94 | also matches before a newline. \regexp{foo} matches both 'foo' and |
| 95 | 'foobar', while the regular expression \regexp{foo\$} matches only |
Fred Drake | b6b2aa6 | 2002-02-25 18:56:45 +0000 | [diff] [blame] | 96 | 'foo'. More interestingly, searching for \regexp{foo.\$} in |
Fred Drake | c547b46 | 2001-07-23 21:14:59 +0000 | [diff] [blame] | 97 | 'foo1\textbackslash nfoo2\textbackslash n' matches 'foo2' normally, |
| 98 | but 'foo1' in \constant{MULTILINE} mode. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 99 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 100 | \item[\character{*}] Causes the resulting RE to |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 101 | match 0 or more repetitions of the preceding RE, as many repetitions |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 102 | as are possible. \regexp{ab*} will |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 103 | match 'a', 'ab', or 'a' followed by any number of 'b's. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 104 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 105 | \item[\character{+}] Causes the |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 106 | resulting RE to match 1 or more repetitions of the preceding RE. |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 107 | \regexp{ab+} will match 'a' followed by any non-zero number of 'b's; it |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 108 | will not match just 'a'. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 109 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 110 | \item[\character{?}] Causes the resulting RE to |
| 111 | match 0 or 1 repetitions of the preceding RE. \regexp{ab?} will |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 112 | match either 'a' or 'ab'. |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 113 | |
| 114 | \item[\code{*?}, \code{+?}, \code{??}] The \character{*}, |
| 115 | \character{+}, and \character{?} qualifiers are all \dfn{greedy}; they |
| 116 | match as much text as possible. Sometimes this behaviour isn't |
| 117 | desired; if the RE \regexp{<.*>} is matched against |
| 118 | \code{'<H1>title</H1>'}, it will match the entire string, and not just |
| 119 | \code{'<H1>'}. Adding \character{?} after the qualifier makes it |
| 120 | perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as |
| 121 | \emph{few} characters as possible will be matched. Using \regexp{.*?} |
| 122 | in the previous expression will match only \code{'<H1>'}. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 123 | |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 124 | \item[\code{\{\var{m}\}}] |
| 125 | Specifies that exactly \var{m} copies of the previous RE should be |
| 126 | matched; fewer matches cause the entire RE not to match. For example, |
| 127 | \regexp{a\{6\}} will match exactly six \character{a} characters, but |
| 128 | not five. |
| 129 | |
Guido van Rossum | 0148bbf | 1997-12-22 22:41:40 +0000 | [diff] [blame] | 130 | \item[\code{\{\var{m},\var{n}\}}] Causes the resulting RE to match from |
| 131 | \var{m} to \var{n} repetitions of the preceding RE, attempting to |
Andrew M. Kuchling | c1cea20 | 1998-10-28 15:44:14 +0000 | [diff] [blame] | 132 | match as many repetitions as possible. For example, \regexp{a\{3,5\}} |
Andrew M. Kuchling | 02a0b3b | 2003-03-04 14:12:24 +0000 | [diff] [blame] | 133 | will match from 3 to 5 \character{a} characters. Omitting \var{m} |
| 134 | specifies a lower bound of zero, |
| 135 | and omitting \var{n} specifies an infinite upper bound. As an |
| 136 | example, \regexp{a\{4,\}b} will match \code{aaaab} or a thousand |
Fred Drake | 51629c2 | 2001-08-02 20:52:00 +0000 | [diff] [blame] | 137 | \character{a} characters followed by a \code{b}, but not \code{aaab}. |
| 138 | The comma may not be omitted or the modifier would be confused with |
| 139 | the previously described form. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 140 | |
Guido van Rossum | 0148bbf | 1997-12-22 22:41:40 +0000 | [diff] [blame] | 141 | \item[\code{\{\var{m},\var{n}\}?}] Causes the resulting RE to |
| 142 | match from \var{m} to \var{n} repetitions of the preceding RE, |
| 143 | attempting to match as \emph{few} repetitions as possible. This is |
| 144 | the non-greedy version of the previous qualifier. For example, on the |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 145 | 6-character string \code{'aaaaaa'}, \regexp{a\{3,5\}} will match 5 |
| 146 | \character{a} characters, while \regexp{a\{3,5\}?} will only match 3 |
| 147 | characters. |
| 148 | |
| 149 | \item[\character{\e}] Either escapes special characters (permitting |
| 150 | you to match characters like \character{*}, \character{?}, and so |
| 151 | forth), or signals a special sequence; special sequences are discussed |
| 152 | below. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 153 | |
| 154 | If you're not using a raw string to |
| 155 | express the pattern, remember that Python also uses the |
| 156 | backslash as an escape sequence in string literals; if the escape |
| 157 | sequence isn't recognized by Python's parser, the backslash and |
| 158 | subsequent character are included in the resulting string. However, |
| 159 | if Python would recognize the resulting sequence, the backslash should |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 160 | be repeated twice. This is complicated and hard to understand, so |
| 161 | it's highly recommended that you use raw strings for all but the |
| 162 | simplest expressions. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 163 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 164 | \item[\code{[]}] Used to indicate a set of characters. Characters can |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 165 | be listed individually, or a range of characters can be indicated by |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 166 | giving two characters and separating them by a \character{-}. Special |
| 167 | characters are not active inside sets. For example, \regexp{[akm\$]} |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 168 | will match any of the characters \character{a}, \character{k}, |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 169 | \character{m}, or \character{\$}; \regexp{[a-z]} |
| 170 | will match any lowercase letter, and \code{[a-zA-Z0-9]} matches any |
Fred Drake | 1e270f0 | 1998-11-30 22:58:12 +0000 | [diff] [blame] | 171 | letter or digit. Character classes such as \code{\e w} or \code{\e S} |
| 172 | (defined below) are also acceptable inside a range. If you want to |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 173 | include a \character{]} or a \character{-} inside a set, precede it with a |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 174 | backslash, or place it as the first character. The |
| 175 | pattern \regexp{[]]} will match \code{']'}, for example. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 176 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 177 | You can match the characters not within a range by \dfn{complementing} |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 178 | the set. This is indicated by including a |
| 179 | \character{\textasciicircum} as the first character of the set; |
| 180 | \character{\textasciicircum} elsewhere will simply match the |
| 181 | \character{\textasciicircum} character. For example, |
| 182 | \regexp{[{\textasciicircum}5]} will match |
| 183 | any character except \character{5}, and |
| 184 | \regexp{[\textasciicircum\code{\textasciicircum}]} will match any character |
| 185 | except \character{\textasciicircum}. |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 186 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 187 | \item[\character{|}]\code{A|B}, where A and B can be arbitrary REs, |
Fred Drake | 062ea2e | 2000-10-06 19:59:22 +0000 | [diff] [blame] | 188 | creates a regular expression that will match either A or B. An |
| 189 | arbitrary number of REs can be separated by the \character{|} in this |
Raymond Hettinger | bed92ee | 2003-09-10 03:54:50 +0000 | [diff] [blame] | 190 | way. This can be used inside groups (see below) as well. As the target |
| 191 | string is scanned, REs separated by \character{|} are tried from left to |
| 192 | right. When one pattern completely matches, that branch is accepted. |
| 193 | This means that once \code{A} matches, \code{B} will not be tested further, |
| 194 | even if it would produce a longer overall match. In other words, the |
| 195 | \character{|} operator is never greedy. To match a literal \character{|}, |
| 196 | use \regexp{\e|}, or enclose it inside a character class, as in \regexp{[|]}. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 197 | |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 198 | \item[\code{(...)}] Matches whatever regular expression is inside the |
| 199 | parentheses, and indicates the start and end of a group; the contents |
| 200 | of a group can be retrieved after a match has been performed, and can |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 201 | be matched later in the string with the \regexp{\e \var{number}} special |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 202 | sequence, described below. To match the literals \character{(} or |
Fred Drake | 2c4f554 | 2000-10-10 22:00:03 +0000 | [diff] [blame] | 203 | \character{)}, use \regexp{\e(} or \regexp{\e)}, or enclose them |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 204 | inside a character class: \regexp{[(] [)]}. |
| 205 | |
| 206 | \item[\code{(?...)}] This is an extension notation (a \character{?} |
| 207 | following a \character{(} is not meaningful otherwise). The first |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 208 | character after the \character{?} |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 209 | determines what the meaning and further syntax of the construct is. |
Guido van Rossum | e9625e8 | 1998-04-02 01:32:24 +0000 | [diff] [blame] | 210 | Extensions usually do not create a new group; |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 211 | \regexp{(?P<\var{name}>...)} is the only exception to this rule. |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 212 | Following are the currently supported extensions. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 213 | |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 214 | \item[\code{(?iLmsux)}] (One or more letters from the set \character{i}, |
| 215 | \character{L}, \character{m}, \character{s}, \character{u}, |
| 216 | \character{x}.) The group matches the empty string; the letters set |
| 217 | the corresponding flags (\constant{re.I}, \constant{re.L}, |
| 218 | \constant{re.M}, \constant{re.S}, \constant{re.U}, \constant{re.X}) |
| 219 | for the entire regular expression. This is useful if you wish to |
| 220 | include the flags as part of the regular expression, instead of |
| 221 | passing a \var{flag} argument to the \function{compile()} function. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 222 | |
Fred Drake | 062ea2e | 2000-10-06 19:59:22 +0000 | [diff] [blame] | 223 | Note that the \regexp{(?x)} flag changes how the expression is parsed. |
| 224 | It should be used first in the expression string, or after one or more |
| 225 | whitespace characters. If there are non-whitespace characters before |
| 226 | the flag, the results are undefined. |
| 227 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 228 | \item[\code{(?:...)}] A non-grouping version of regular parentheses. |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 229 | Matches whatever regular expression is inside the parentheses, but the |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 230 | substring matched by the |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 231 | group \emph{cannot} be retrieved after performing a match or |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 232 | referenced later in the pattern. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 233 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 234 | \item[\code{(?P<\var{name}>...)}] Similar to regular parentheses, but |
Guido van Rossum | e9625e8 | 1998-04-02 01:32:24 +0000 | [diff] [blame] | 235 | the substring matched by the group is accessible via the symbolic group |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 236 | name \var{name}. Group names must be valid Python identifiers, and |
| 237 | each group name must be defined only once within a regular expression. A |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 238 | symbolic group is also a numbered group, just as if the group were not |
| 239 | named. So the group named 'id' in the example above can also be |
| 240 | referenced as the numbered group 1. |
| 241 | |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 242 | For example, if the pattern is |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 243 | \regexp{(?P<id>[a-zA-Z_]\e w*)}, the group can be referenced by its |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 244 | name in arguments to methods of match objects, such as |
| 245 | \code{m.group('id')} or \code{m.end('id')}, and also by name in |
| 246 | pattern text (for example, \regexp{(?P=id)}) and replacement text |
| 247 | (such as \code{\e g<id>}). |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 248 | |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 249 | \item[\code{(?P=\var{name})}] Matches whatever text was matched by the |
| 250 | earlier group named \var{name}. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 251 | |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 252 | \item[\code{(?\#...)}] A comment; the contents of the parentheses are |
| 253 | simply ignored. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 254 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 255 | \item[\code{(?=...)}] Matches if \regexp{...} matches next, but doesn't |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 256 | consume any of the string. This is called a lookahead assertion. For |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 257 | example, \regexp{Isaac (?=Asimov)} will match \code{'Isaac~'} only if it's |
| 258 | followed by \code{'Asimov'}. |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 259 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 260 | \item[\code{(?!...)}] Matches if \regexp{...} doesn't match next. This |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 261 | is a negative lookahead assertion. For example, |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 262 | \regexp{Isaac (?!Asimov)} will match \code{'Isaac~'} only if it's \emph{not} |
| 263 | followed by \code{'Asimov'}. |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 264 | |
Andrew M. Kuchling | 9351dd2 | 2000-10-05 15:22:28 +0000 | [diff] [blame] | 265 | \item[\code{(?<=...)}] Matches if the current position in the string |
| 266 | is preceded by a match for \regexp{...} that ends at the current |
Fred Drake | f275803 | 2002-03-16 05:58:12 +0000 | [diff] [blame] | 267 | position. This is called a \dfn{positive lookbehind assertion}. |
| 268 | \regexp{(?<=abc)def} will find a match in \samp{abcdef}, since the |
| 269 | lookbehind will back up 3 characters and check if the contained |
| 270 | pattern matches. The contained pattern must only match strings of |
| 271 | some fixed length, meaning that \regexp{abc} or \regexp{a|b} are |
| 272 | allowed, but \regexp{a*} and \regexp{a\{3,4\}} are not. Note that |
| 273 | patterns which start with positive lookbehind assertions will never |
| 274 | match at the beginning of the string being searched; you will most |
| 275 | likely want to use the \function{search()} function rather than the |
| 276 | \function{match()} function: |
| 277 | |
| 278 | \begin{verbatim} |
| 279 | >>> import re |
Fred Drake | 8e0c82a | 2002-03-16 14:01:12 +0000 | [diff] [blame] | 280 | >>> m = re.search('(?<=abc)def', 'abcdef') |
Fred Drake | f275803 | 2002-03-16 05:58:12 +0000 | [diff] [blame] | 281 | >>> m.group(0) |
| 282 | 'def' |
| 283 | \end{verbatim} |
| 284 | |
| 285 | This example looks for a word following a hyphen: |
| 286 | |
| 287 | \begin{verbatim} |
| 288 | >>> m = re.search('(?<=-)\w+', 'spam-egg') |
| 289 | >>> m.group(0) |
| 290 | 'egg' |
| 291 | \end{verbatim} |
Andrew M. Kuchling | 9351dd2 | 2000-10-05 15:22:28 +0000 | [diff] [blame] | 292 | |
| 293 | \item[\code{(?<!...)}] Matches if the current position in the string |
Fred Drake | f275803 | 2002-03-16 05:58:12 +0000 | [diff] [blame] | 294 | is not preceded by a match for \regexp{...}. This is called a |
| 295 | \dfn{negative lookbehind assertion}. Similar to positive lookbehind |
Andrew M. Kuchling | 9351dd2 | 2000-10-05 15:22:28 +0000 | [diff] [blame] | 296 | assertions, the contained pattern must only match strings of some |
Fred Drake | f275803 | 2002-03-16 05:58:12 +0000 | [diff] [blame] | 297 | fixed length. Patterns which start with negative lookbehind |
Fred Drake | a8b6638 | 2002-03-18 16:45:01 +0000 | [diff] [blame] | 298 | assertions may match at the beginning of the string being searched. |
Andrew M. Kuchling | 9351dd2 | 2000-10-05 15:22:28 +0000 | [diff] [blame] | 299 | |
Gustavo Niemeyer | ad3fc44 | 2003-10-17 22:13:16 +0000 | [diff] [blame] | 300 | \item[\code{(?(\var{id/name})yes-pattern|no-pattern)}] Will try to match |
| 301 | with \regexp{yes-pattern} if the group with given \var{id} or \var{name} |
| 302 | exists, and with \regexp{no-pattern} if it doesn't. \regexp{|no-pattern} |
| 303 | is optional and can be omitted. For example, |
| 304 | \regexp{(<)?(\e w+@\e w+(?:\e .\e w+)+)(?(1)>)} is a poor email matching |
| 305 | pattern, which will match with \code{'<user@host.com>'} as well as |
| 306 | \code{'user@host.com'}, but not with \code{'<user@host.com'}. |
Gustavo Niemeyer | d969775 | 2003-10-18 15:28:22 +0000 | [diff] [blame] | 307 | \versionadded{2.4} |
Gustavo Niemeyer | ad3fc44 | 2003-10-17 22:13:16 +0000 | [diff] [blame] | 308 | |
Fred Drake | 2705e80 | 1998-02-16 21:21:13 +0000 | [diff] [blame] | 309 | \end{list} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 310 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 311 | The special sequences consist of \character{\e} and a character from the |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 312 | list below. If the ordinary character is not on the list, then the |
| 313 | resulting RE will match the second character. For example, |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 314 | \regexp{\e\$} matches the character \character{\$}. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 315 | |
Fred Drake | 1e270f0 | 1998-11-30 22:58:12 +0000 | [diff] [blame] | 316 | \begin{list}{}{\leftmargin 0.7in \labelwidth 0.65in} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 317 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 318 | \item[\code{\e \var{number}}] Matches the contents of the group of the |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 319 | same number. Groups are numbered starting from 1. For example, |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 320 | \regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 321 | \code{'the end'} (note |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 322 | the space after the group). This special sequence can only be used to |
| 323 | match one of the first 99 groups. If the first digit of \var{number} |
| 324 | is 0, or \var{number} is 3 octal digits long, it will not be interpreted |
| 325 | as a group match, but as the character with octal value \var{number}. |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 326 | Inside the \character{[} and \character{]} of a character class, all numeric |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 327 | escapes are treated as characters. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 328 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 329 | \item[\code{\e A}] Matches only at the start of the string. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 330 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 331 | \item[\code{\e b}] Matches the empty string, but only at the |
| 332 | beginning or end of a word. A word is defined as a sequence of |
Skip Montanaro | 2c0d322 | 2002-09-07 18:48:14 +0000 | [diff] [blame] | 333 | alphanumeric or underscore characters, so the end of a word is indicated by |
| 334 | whitespace or a non-alphanumeric, non-underscore character. Note that |
| 335 | {}\code{\e b} is defined as the boundary between \code{\e w} and \code{\e |
| 336 | W}, so the precise set of characters deemed to be alphanumeric depends on the |
| 337 | values of the \code{UNICODE} and \code{LOCALE} flags. Inside a character |
| 338 | range, \regexp{\e b} represents the backspace character, for compatibility |
| 339 | with Python's string literals. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 340 | |
Skip Montanaro | 2c0d322 | 2002-09-07 18:48:14 +0000 | [diff] [blame] | 341 | \item[\code{\e B}] Matches the empty string, but only when it is \emph{not} |
| 342 | at the beginning or end of a word. This is just the opposite of {}\code{\e |
| 343 | b}, so is also subject to the settings of \code{LOCALE} and \code{UNICODE}. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 344 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 345 | \item[\code{\e d}]Matches any decimal digit; this is |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 346 | equivalent to the set \regexp{[0-9]}. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 347 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 348 | \item[\code{\e D}]Matches any non-digit character; this is |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 349 | equivalent to the set \regexp{[{\textasciicircum}0-9]}. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 350 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 351 | \item[\code{\e s}]Matches any whitespace character; this is |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 352 | equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 353 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 354 | \item[\code{\e S}]Matches any non-whitespace character; this is |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 355 | equivalent to the set \regexp{[\textasciicircum\ \e t\e n\e r\e f\e v]}. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 356 | |
| 357 | \item[\code{\e w}]When the \constant{LOCALE} and \constant{UNICODE} |
Fred Drake | 3d03968 | 2002-11-12 23:12:54 +0000 | [diff] [blame] | 358 | flags are not specified, matches any alphanumeric character and the |
| 359 | underscore; this is equivalent to the set |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 360 | \regexp{[a-zA-Z0-9_]}. With \constant{LOCALE}, it will match the set |
Fred Drake | 3d03968 | 2002-11-12 23:12:54 +0000 | [diff] [blame] | 361 | \regexp{[0-9_]} plus whatever characters are defined as alphanumeric for |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 362 | the current locale. If \constant{UNICODE} is set, this will match the |
| 363 | characters \regexp{[0-9_]} plus whatever is classified as alphanumeric |
| 364 | in the Unicode character properties database. |
| 365 | |
| 366 | \item[\code{\e W}]When the \constant{LOCALE} and \constant{UNICODE} |
| 367 | flags are not specified, matches any non-alphanumeric character; this |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 368 | is equivalent to the set \regexp{[{\textasciicircum}a-zA-Z0-9_]}. With |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 369 | \constant{LOCALE}, it will match any character not in the set |
Fred Drake | 3d03968 | 2002-11-12 23:12:54 +0000 | [diff] [blame] | 370 | \regexp{[0-9_]}, and not defined as alphanumeric for the current locale. |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 371 | If \constant{UNICODE} is set, this will match anything other than |
Fred Drake | 3d03968 | 2002-11-12 23:12:54 +0000 | [diff] [blame] | 372 | \regexp{[0-9_]} and characters marked as alphanumeric in the Unicode |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 373 | character properties database. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 374 | |
| 375 | \item[\code{\e Z}]Matches only at the end of the string. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 376 | |
Fred Drake | 2705e80 | 1998-02-16 21:21:13 +0000 | [diff] [blame] | 377 | \end{list} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 378 | |
Fred Drake | 57f8e06 | 2002-03-25 20:22:59 +0000 | [diff] [blame] | 379 | Most of the standard escapes supported by Python string literals are |
| 380 | also accepted by the regular expression parser: |
| 381 | |
| 382 | \begin{verbatim} |
| 383 | \a \b \f \n |
| 384 | \r \t \v \x |
| 385 | \\ |
| 386 | \end{verbatim} |
| 387 | |
Martin v. Löwis | 81bdc93 | 2002-04-11 12:24:12 +0000 | [diff] [blame] | 388 | Octal escapes are included in a limited form: If the first digit is a |
| 389 | 0, or if there are three octal digits, it is considered an octal |
| 390 | escape. Otherwise, it is a group reference. |
Fred Drake | 57f8e06 | 2002-03-25 20:22:59 +0000 | [diff] [blame] | 391 | |
Fred Drake | 42de185 | 1998-04-20 16:28:44 +0000 | [diff] [blame] | 392 | |
Fred Drake | 5b11bdd | 2002-07-30 17:51:20 +0000 | [diff] [blame] | 393 | % Note the lack of a period in the section title; it causes problems |
| 394 | % with readers of the GNU info version. See http://www.python.org/sf/581414. |
| 395 | \subsection{Matching vs Searching \label{matching-searching}} |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 396 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 397 | |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 398 | Python offers two different primitive operations based on regular |
| 399 | expressions: match and search. If you are accustomed to Perl's |
| 400 | semantics, the search operation is what you're looking for. See the |
| 401 | \function{search()} function and corresponding method of compiled |
| 402 | regular expression objects. |
| 403 | |
| 404 | Note that match may differ from search using a regular expression |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 405 | beginning with \character{\textasciicircum}: |
| 406 | \character{\textasciicircum} matches only at the |
Fred Drake | 3d0971e | 1999-06-29 21:21:19 +0000 | [diff] [blame] | 407 | start of the string, or in \constant{MULTILINE} mode also immediately |
| 408 | following a newline. The ``match'' operation succeeds only if the |
| 409 | pattern matches at the start of the string regardless of mode, or at |
| 410 | the starting position given by the optional \var{pos} argument |
| 411 | regardless of whether a newline precedes it. |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 412 | |
| 413 | % Examples from Tim Peters: |
| 414 | \begin{verbatim} |
| 415 | re.compile("a").match("ba", 1) # succeeds |
| 416 | re.compile("^a").search("ba", 1) # fails; 'a' not at start |
| 417 | re.compile("^a").search("\na", 1) # fails; 'a' not at start |
| 418 | re.compile("^a", re.M).search("\na", 1) # succeeds |
| 419 | re.compile("^a", re.M).search("ba", 1) # fails; no preceding \n |
| 420 | \end{verbatim} |
| 421 | |
| 422 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 423 | \subsection{Module Contents} |
Fred Drake | 78f8e98 | 1997-12-29 21:39:39 +0000 | [diff] [blame] | 424 | \nodename{Contents of Module re} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 425 | |
| 426 | The module defines the following functions and constants, and an exception: |
| 427 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 428 | |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 429 | \begin{funcdesc}{compile}{pattern\optional{, flags}} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 430 | Compile a regular expression pattern into a regular expression |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 431 | object, which can be used for matching using its \function{match()} and |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 432 | \function{search()} methods, described below. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 433 | |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 434 | The expression's behaviour can be modified by specifying a |
| 435 | \var{flags} value. Values can be any of the following variables, |
| 436 | combined using bitwise OR (the \code{|} operator). |
| 437 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 438 | The sequence |
| 439 | |
| 440 | \begin{verbatim} |
| 441 | prog = re.compile(pat) |
| 442 | result = prog.match(str) |
| 443 | \end{verbatim} |
| 444 | |
| 445 | is equivalent to |
| 446 | |
| 447 | \begin{verbatim} |
| 448 | result = re.match(pat, str) |
| 449 | \end{verbatim} |
| 450 | |
| 451 | but the version using \function{compile()} is more efficient when the |
| 452 | expression will be used several times in a single program. |
| 453 | %(The compiled version of the last pattern passed to |
Fred Drake | 895aa9d | 2001-04-18 17:26:20 +0000 | [diff] [blame] | 454 | %\function{re.match()} or \function{re.search()} is cached, so |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 455 | %programs that use only a single regular expression at a time needn't |
| 456 | %worry about compiling regular expressions.) |
| 457 | \end{funcdesc} |
| 458 | |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 459 | \begin{datadesc}{I} |
| 460 | \dataline{IGNORECASE} |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 461 | Perform case-insensitive matching; expressions like \regexp{[A-Z]} |
| 462 | will match lowercase letters, too. This is not affected by the |
| 463 | current locale. |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 464 | \end{datadesc} |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 465 | |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 466 | \begin{datadesc}{L} |
| 467 | \dataline{LOCALE} |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 468 | Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, and |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 469 | \regexp{\e B} dependent on the current locale. |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 470 | \end{datadesc} |
Guido van Rossum | a42c178 | 1997-12-09 20:41:47 +0000 | [diff] [blame] | 471 | |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 472 | \begin{datadesc}{M} |
| 473 | \dataline{MULTILINE} |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 474 | When specified, the pattern character \character{\textasciicircum} |
| 475 | matches at the beginning of the string and at the beginning of each |
| 476 | line (immediately following each newline); and the pattern character |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 477 | \character{\$} matches at the end of the string and at the end of each |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 478 | line (immediately preceding each newline). By default, |
| 479 | \character{\textasciicircum} matches only at the beginning of the |
| 480 | string, and \character{\$} only at the end of the string and |
| 481 | immediately before the newline (if any) at the end of the string. |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 482 | \end{datadesc} |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 483 | |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 484 | \begin{datadesc}{S} |
| 485 | \dataline{DOTALL} |
Fred Drake | e53793b | 2000-09-25 17:52:40 +0000 | [diff] [blame] | 486 | Make the \character{.} special character match any character at all, |
| 487 | including a newline; without this flag, \character{.} will match |
| 488 | anything \emph{except} a newline. |
| 489 | \end{datadesc} |
| 490 | |
| 491 | \begin{datadesc}{U} |
| 492 | \dataline{UNICODE} |
| 493 | Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, and |
| 494 | \regexp{\e B} dependent on the Unicode character properties database. |
| 495 | \versionadded{2.0} |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 496 | \end{datadesc} |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 497 | |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 498 | \begin{datadesc}{X} |
| 499 | \dataline{VERBOSE} |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 500 | This flag allows you to write regular expressions that look nicer. |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 501 | Whitespace within the pattern is ignored, |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 502 | except when in a character class or preceded by an unescaped |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 503 | backslash, and, when a line contains a \character{\#} neither in a |
| 504 | character class or preceded by an unescaped backslash, all characters |
| 505 | from the leftmost such \character{\#} through the end of the line are |
| 506 | ignored. |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 507 | % XXX should add an example here |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 508 | \end{datadesc} |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 509 | |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 510 | |
Guido van Rossum | 7d447aa | 1998-10-13 16:03:52 +0000 | [diff] [blame] | 511 | \begin{funcdesc}{search}{pattern, string\optional{, flags}} |
| 512 | Scan through \var{string} looking for a location where the regular |
| 513 | expression \var{pattern} produces a match, and return a |
| 514 | corresponding \class{MatchObject} instance. |
| 515 | Return \code{None} if no |
| 516 | position in the string matches the pattern; note that this is |
| 517 | different from finding a zero-length match at some point in the string. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 518 | \end{funcdesc} |
| 519 | |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 520 | \begin{funcdesc}{match}{pattern, string\optional{, flags}} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 521 | If zero or more characters at the beginning of \var{string} match |
| 522 | the regular expression \var{pattern}, return a corresponding |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 523 | \class{MatchObject} instance. Return \code{None} if the string does not |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 524 | match the pattern; note that this is different from a zero-length |
| 525 | match. |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 526 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 527 | \note{If you want to locate a match anywhere in |
| 528 | \var{string}, use \method{search()} instead.} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 529 | \end{funcdesc} |
| 530 | |
Fred Drake | 77a6c9e | 2000-09-07 14:00:51 +0000 | [diff] [blame] | 531 | \begin{funcdesc}{split}{pattern, string\optional{, maxsplit\code{ = 0}}} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 532 | Split \var{string} by the occurrences of \var{pattern}. If |
Andrew M. Kuchling | d22e250 | 1998-08-14 14:49:20 +0000 | [diff] [blame] | 533 | capturing parentheses are used in \var{pattern}, then the text of all |
| 534 | groups in the pattern are also returned as part of the resulting list. |
Guido van Rossum | 9754639 | 1998-01-12 18:58:53 +0000 | [diff] [blame] | 535 | If \var{maxsplit} is nonzero, at most \var{maxsplit} splits |
| 536 | occur, and the remainder of the string is returned as the final |
| 537 | element of the list. (Incompatibility note: in the original Python |
| 538 | 1.5 release, \var{maxsplit} was ignored. This has been fixed in |
| 539 | later releases.) |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 540 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 541 | \begin{verbatim} |
Andrew M. Kuchling | d22e250 | 1998-08-14 14:49:20 +0000 | [diff] [blame] | 542 | >>> re.split('\W+', 'Words, words, words.') |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 543 | ['Words', 'words', 'words', ''] |
Andrew M. Kuchling | d22e250 | 1998-08-14 14:49:20 +0000 | [diff] [blame] | 544 | >>> re.split('(\W+)', 'Words, words, words.') |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 545 | ['Words', ', ', 'words', ', ', 'words', '.', ''] |
Andrew M. Kuchling | d22e250 | 1998-08-14 14:49:20 +0000 | [diff] [blame] | 546 | >>> re.split('\W+', 'Words, words, words.', 1) |
Guido van Rossum | 9754639 | 1998-01-12 18:58:53 +0000 | [diff] [blame] | 547 | ['Words', 'words, words.'] |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 548 | \end{verbatim} |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 549 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 550 | This function combines and extends the functionality of |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 551 | the old \function{regsub.split()} and \function{regsub.splitx()}. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 552 | \end{funcdesc} |
| 553 | |
Guido van Rossum | 6c373f7 | 1998-06-29 22:48:01 +0000 | [diff] [blame] | 554 | \begin{funcdesc}{findall}{pattern, string} |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 555 | Return a list of all non-overlapping matches of \var{pattern} in |
| 556 | \var{string}. If one or more groups are present in the pattern, |
| 557 | return a list of groups; this will be a list of tuples if the |
| 558 | pattern has more than one group. Empty matches are included in the |
Raymond Hettinger | 2f3e548 | 2003-08-31 05:29:02 +0000 | [diff] [blame] | 559 | result unless they touch the beginning of another match. |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 560 | \versionadded{1.5.2} |
Guido van Rossum | 6c373f7 | 1998-06-29 22:48:01 +0000 | [diff] [blame] | 561 | \end{funcdesc} |
| 562 | |
Fred Drake | 57f8e06 | 2002-03-25 20:22:59 +0000 | [diff] [blame] | 563 | \begin{funcdesc}{finditer}{pattern, string} |
| 564 | Return an iterator over all non-overlapping matches for the RE |
| 565 | \var{pattern} in \var{string}. For each match, the iterator returns |
Raymond Hettinger | 2f3e548 | 2003-08-31 05:29:02 +0000 | [diff] [blame] | 566 | a match object. Empty matches are included in the result unless they |
| 567 | touch the beginning of another match. |
Fred Drake | 57f8e06 | 2002-03-25 20:22:59 +0000 | [diff] [blame] | 568 | \versionadded{2.2} |
| 569 | \end{funcdesc} |
| 570 | |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 571 | \begin{funcdesc}{sub}{pattern, repl, string\optional{, count}} |
| 572 | Return the string obtained by replacing the leftmost non-overlapping |
| 573 | occurrences of \var{pattern} in \var{string} by the replacement |
| 574 | \var{repl}. If the pattern isn't found, \var{string} is returned |
| 575 | unchanged. \var{repl} can be a string or a function; if it is a |
| 576 | string, any backslash escapes in it are processed. That is, |
| 577 | \samp{\e n} is converted to a single newline character, \samp{\e r} |
| 578 | is converted to a linefeed, and so forth. Unknown escapes such as |
| 579 | \samp{\e j} are left alone. Backreferences, such as \samp{\e6}, are |
| 580 | replaced with the substring matched by group 6 in the pattern. For |
| 581 | example: |
| 582 | |
| 583 | \begin{verbatim} |
| 584 | >>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):', |
| 585 | ... r'static PyObject*\npy_\1(void)\n{', |
| 586 | ... 'def myfunc():') |
| 587 | 'static PyObject*\npy_myfunc(void)\n{' |
| 588 | \end{verbatim} |
| 589 | |
| 590 | If \var{repl} is a function, it is called for every non-overlapping |
| 591 | occurrence of \var{pattern}. The function takes a single match |
| 592 | object argument, and returns the replacement string. For example: |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 593 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 594 | \begin{verbatim} |
Barry Warsaw | 4552f3d | 1997-11-20 00:15:13 +0000 | [diff] [blame] | 595 | >>> def dashrepl(matchobj): |
Guido van Rossum | e9625e8 | 1998-04-02 01:32:24 +0000 | [diff] [blame] | 596 | .... if matchobj.group(0) == '-': return ' ' |
| 597 | .... else: return '-' |
Barry Warsaw | 4552f3d | 1997-11-20 00:15:13 +0000 | [diff] [blame] | 598 | >>> re.sub('-{1,2}', dashrepl, 'pro----gram-files') |
| 599 | 'pro--gram files' |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 600 | \end{verbatim} |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 601 | |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 602 | The pattern may be a string or an RE object; if you need to specify |
| 603 | regular expression flags, you must use a RE object, or use embedded |
| 604 | modifiers in a pattern; for example, \samp{sub("(?i)b+", "x", "bbbb |
| 605 | BBBB")} returns \code{'x x'}. |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 606 | |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 607 | The optional argument \var{count} is the maximum number of pattern |
| 608 | occurrences to be replaced; \var{count} must be a non-negative |
| 609 | integer. If omitted or zero, all occurrences will be replaced. |
| 610 | Empty matches for the pattern are replaced only when not adjacent to |
| 611 | a previous match, so \samp{sub('x*', '-', 'abc')} returns |
| 612 | \code{'-a-b-c-'}. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 613 | |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 614 | In addition to character escapes and backreferences as described |
| 615 | above, \samp{\e g<name>} will use the substring matched by the group |
| 616 | named \samp{name}, as defined by the \regexp{(?P<name>...)} syntax. |
| 617 | \samp{\e g<number>} uses the corresponding group number; |
| 618 | \samp{\e g<2>} is therefore equivalent to \samp{\e 2}, but isn't |
| 619 | ambiguous in a replacement such as \samp{\e g<2>0}. \samp{\e 20} |
| 620 | would be interpreted as a reference to group 20, not a reference to |
Eric S. Raymond | 46ccd1d | 2001-08-28 12:50:03 +0000 | [diff] [blame] | 621 | group 2 followed by the literal character \character{0}. The |
| 622 | backreference \samp{\e g<0>} substitutes in the entire substring |
| 623 | matched by the RE. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 624 | \end{funcdesc} |
| 625 | |
Fred Drake | e74f8de | 2001-08-01 16:56:51 +0000 | [diff] [blame] | 626 | \begin{funcdesc}{subn}{pattern, repl, string\optional{, count}} |
| 627 | Perform the same operation as \function{sub()}, but return a tuple |
| 628 | \code{(\var{new_string}, \var{number_of_subs_made})}. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 629 | \end{funcdesc} |
| 630 | |
Guido van Rossum | 7d447aa | 1998-10-13 16:03:52 +0000 | [diff] [blame] | 631 | \begin{funcdesc}{escape}{string} |
| 632 | Return \var{string} with all non-alphanumerics backslashed; this is |
| 633 | useful if you want to match an arbitrary literal string that may have |
| 634 | regular expression metacharacters in it. |
| 635 | \end{funcdesc} |
| 636 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 637 | \begin{excdesc}{error} |
| 638 | Exception raised when a string passed to one of the functions here |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 639 | is not a valid regular expression (for example, it might contain |
| 640 | unmatched parentheses) or when some other error occurs during |
| 641 | compilation or matching. It is never an error if a string contains |
| 642 | no match for a pattern. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 643 | \end{excdesc} |
| 644 | |
Fred Drake | 42de185 | 1998-04-20 16:28:44 +0000 | [diff] [blame] | 645 | |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 646 | \subsection{Regular Expression Objects \label{re-objects}} |
Fred Drake | 42de185 | 1998-04-20 16:28:44 +0000 | [diff] [blame] | 647 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 648 | Compiled regular expression objects support the following methods and |
| 649 | attributes: |
| 650 | |
Fred Drake | 77a6c9e | 2000-09-07 14:00:51 +0000 | [diff] [blame] | 651 | \begin{methoddesc}[RegexObject]{match}{string\optional{, pos\optional{, |
| 652 | endpos}}} |
Guido van Rossum | eb53ae4 | 1997-10-05 18:54:07 +0000 | [diff] [blame] | 653 | If zero or more characters at the beginning of \var{string} match |
| 654 | this regular expression, return a corresponding |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 655 | \class{MatchObject} instance. Return \code{None} if the string does not |
Guido van Rossum | eb53ae4 | 1997-10-05 18:54:07 +0000 | [diff] [blame] | 656 | match the pattern; note that this is different from a zero-length |
| 657 | match. |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 658 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 659 | \note{If you want to locate a match anywhere in |
| 660 | \var{string}, use \method{search()} instead.} |
Fred Drake | 768ac6b | 1998-12-22 18:19:45 +0000 | [diff] [blame] | 661 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 662 | The optional second parameter \var{pos} gives an index in the string |
Andrew M. Kuchling | 65b7863 | 1998-06-22 15:02:42 +0000 | [diff] [blame] | 663 | where the search is to start; it defaults to \code{0}. This is not |
Fred Drake | 7bc6f7a | 2002-02-14 15:19:30 +0000 | [diff] [blame] | 664 | completely equivalent to slicing the string; the |
| 665 | \code{'\textasciicircum'} pattern |
Andrew M. Kuchling | 65b7863 | 1998-06-22 15:02:42 +0000 | [diff] [blame] | 666 | character matches at the real beginning of the string and at positions |
| 667 | just after a newline, but not necessarily at the index where the search |
| 668 | is to start. |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 669 | |
| 670 | The optional parameter \var{endpos} limits how far the string will |
| 671 | be searched; it will be as if the string is \var{endpos} characters |
Fred Drake | ffefb1d | 2002-08-20 13:57:47 +0000 | [diff] [blame] | 672 | long, so only the characters from \var{pos} to \code{\var{endpos} - |
| 673 | 1} will be searched for a match. If \var{endpos} is less than |
| 674 | \var{pos}, no match will be found, otherwise, if \var{rx} is a |
| 675 | compiled regular expression object, |
| 676 | \code{\var{rx}.match(\var{string}, 0, 50)} is equivalent to |
| 677 | \code{\var{rx}.match(\var{string}[:50], 0)}. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 678 | \end{methoddesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 679 | |
Andrew M. Kuchling | c85bf58 | 2003-05-13 14:40:24 +0000 | [diff] [blame] | 680 | \begin{methoddesc}[RegexObject]{search}{string\optional{, pos\optional{, |
| 681 | endpos}}} |
| 682 | Scan through \var{string} looking for a location where this regular |
| 683 | expression produces a match, and return a |
| 684 | corresponding \class{MatchObject} instance. Return \code{None} if no |
| 685 | position in the string matches the pattern; note that this is |
| 686 | different from finding a zero-length match at some point in the string. |
| 687 | |
| 688 | The optional \var{pos} and \var{endpos} parameters have the same |
| 689 | meaning as for the \method{match()} method. |
| 690 | \end{methoddesc} |
| 691 | |
Fred Drake | 77a6c9e | 2000-09-07 14:00:51 +0000 | [diff] [blame] | 692 | \begin{methoddesc}[RegexObject]{split}{string\optional{, |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 693 | maxsplit\code{ = 0}}} |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 694 | Identical to the \function{split()} function, using the compiled pattern. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 695 | \end{methoddesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 696 | |
Guido van Rossum | 6c373f7 | 1998-06-29 22:48:01 +0000 | [diff] [blame] | 697 | \begin{methoddesc}[RegexObject]{findall}{string} |
| 698 | Identical to the \function{findall()} function, using the compiled pattern. |
| 699 | \end{methoddesc} |
| 700 | |
Fred Drake | 57f8e06 | 2002-03-25 20:22:59 +0000 | [diff] [blame] | 701 | \begin{methoddesc}[RegexObject]{finditer}{string} |
| 702 | Identical to the \function{finditer()} function, using the compiled pattern. |
| 703 | \end{methoddesc} |
| 704 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 705 | \begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}} |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 706 | Identical to the \function{sub()} function, using the compiled pattern. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 707 | \end{methoddesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 708 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 709 | \begin{methoddesc}[RegexObject]{subn}{repl, string\optional{, |
| 710 | count\code{ = 0}}} |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 711 | Identical to the \function{subn()} function, using the compiled pattern. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 712 | \end{methoddesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 713 | |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 714 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 715 | \begin{memberdesc}[RegexObject]{flags} |
Fred Drake | 895aa9d | 2001-04-18 17:26:20 +0000 | [diff] [blame] | 716 | The flags argument used when the RE object was compiled, or |
Fred Drake | 013ad98 | 1998-03-08 07:38:27 +0000 | [diff] [blame] | 717 | \code{0} if no flags were provided. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 718 | \end{memberdesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 719 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 720 | \begin{memberdesc}[RegexObject]{groupindex} |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 721 | A dictionary mapping any symbolic group names defined by |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 722 | \regexp{(?P<\var{id}>)} to group numbers. The dictionary is empty if no |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 723 | symbolic groups were used in the pattern. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 724 | \end{memberdesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 725 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 726 | \begin{memberdesc}[RegexObject]{pattern} |
Fred Drake | 895aa9d | 2001-04-18 17:26:20 +0000 | [diff] [blame] | 727 | The pattern string from which the RE object was compiled. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 728 | \end{memberdesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 729 | |
Fred Drake | 42de185 | 1998-04-20 16:28:44 +0000 | [diff] [blame] | 730 | |
Fred Drake | d16d498 | 1998-09-10 20:21:00 +0000 | [diff] [blame] | 731 | \subsection{Match Objects \label{match-objects}} |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 732 | |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 733 | \class{MatchObject} instances support the following methods and |
| 734 | attributes: |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 735 | |
Andrew M. Kuchling | 7a90db6 | 2000-10-05 12:35:29 +0000 | [diff] [blame] | 736 | \begin{methoddesc}[MatchObject]{expand}{template} |
| 737 | Return the string obtained by doing backslash substitution on the |
| 738 | template string \var{template}, as done by the \method{sub()} method. |
| 739 | Escapes such as \samp{\e n} are converted to the appropriate |
Fred Drake | f4bdb57 | 2001-07-12 14:13:43 +0000 | [diff] [blame] | 740 | characters, and numeric backreferences (\samp{\e 1}, \samp{\e 2}) and |
| 741 | named backreferences (\samp{\e g<1>}, \samp{\e g<name>}) are replaced |
| 742 | by the contents of the corresponding group. |
Andrew M. Kuchling | 7a90db6 | 2000-10-05 12:35:29 +0000 | [diff] [blame] | 743 | \end{methoddesc} |
| 744 | |
Fred Drake | 77a6c9e | 2000-09-07 14:00:51 +0000 | [diff] [blame] | 745 | \begin{methoddesc}[MatchObject]{group}{\optional{group1, \moreargs}} |
Guido van Rossum | 4650392 | 1998-01-19 23:14:17 +0000 | [diff] [blame] | 746 | Returns one or more subgroups of the match. If there is a single |
| 747 | argument, the result is a single string; if there are |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 748 | multiple arguments, the result is a tuple with one item per argument. |
Fred Drake | 907e76b | 2001-07-06 20:30:11 +0000 | [diff] [blame] | 749 | Without arguments, \var{group1} defaults to zero (the whole match |
Guido van Rossum | 4650392 | 1998-01-19 23:14:17 +0000 | [diff] [blame] | 750 | is returned). |
| 751 | If a \var{groupN} argument is zero, the corresponding return value is the |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 752 | entire matching string; if it is in the inclusive range [1..99], it is |
Raymond Hettinger | f17d65d | 2003-08-12 00:01:16 +0000 | [diff] [blame] | 753 | the string matching the corresponding parenthesized group. If a |
Guido van Rossum | 791468f | 1998-04-03 20:07:37 +0000 | [diff] [blame] | 754 | group number is negative or larger than the number of groups defined |
| 755 | in the pattern, an \exception{IndexError} exception is raised. |
| 756 | If a group is contained in a part of the pattern that did not match, |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 757 | the corresponding result is \code{None}. If a group is contained in a |
Guido van Rossum | 791468f | 1998-04-03 20:07:37 +0000 | [diff] [blame] | 758 | part of the pattern that matched multiple times, the last match is |
| 759 | returned. |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 760 | |
Andrew M. Kuchling | 2533281 | 1998-04-09 14:56:04 +0000 | [diff] [blame] | 761 | If the regular expression uses the \regexp{(?P<\var{name}>...)} syntax, |
Guido van Rossum | 4650392 | 1998-01-19 23:14:17 +0000 | [diff] [blame] | 762 | the \var{groupN} arguments may also be strings identifying groups by |
Tim Peters | 7533587 | 2001-11-03 19:35:43 +0000 | [diff] [blame] | 763 | their group name. If a string argument is not used as a group name in |
Guido van Rossum | 791468f | 1998-04-03 20:07:37 +0000 | [diff] [blame] | 764 | the pattern, an \exception{IndexError} exception is raised. |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 765 | |
| 766 | A moderately complicated example: |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 767 | |
| 768 | \begin{verbatim} |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 769 | m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14') |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 770 | \end{verbatim} |
| 771 | |
| 772 | After performing this match, \code{m.group(1)} is \code{'3'}, as is |
Guido van Rossum | 4650392 | 1998-01-19 23:14:17 +0000 | [diff] [blame] | 773 | \code{m.group('int')}, and \code{m.group(2)} is \code{'14'}. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 774 | \end{methoddesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 775 | |
Guido van Rossum | 6c373f7 | 1998-06-29 22:48:01 +0000 | [diff] [blame] | 776 | \begin{methoddesc}[MatchObject]{groups}{\optional{default}} |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 777 | Return a tuple containing all the subgroups of the match, from 1 up to |
Guido van Rossum | 6c373f7 | 1998-06-29 22:48:01 +0000 | [diff] [blame] | 778 | however many groups are in the pattern. The \var{default} argument is |
| 779 | used for groups that did not participate in the match; it defaults to |
| 780 | \code{None}. (Incompatibility note: in the original Python 1.5 |
| 781 | release, if the tuple was one element long, a string would be returned |
| 782 | instead. In later versions (from 1.5.1 on), a singleton tuple is |
| 783 | returned in such cases.) |
| 784 | \end{methoddesc} |
| 785 | |
| 786 | \begin{methoddesc}[MatchObject]{groupdict}{\optional{default}} |
| 787 | Return a dictionary containing all the \emph{named} subgroups of the |
| 788 | match, keyed by the subgroup name. The \var{default} argument is |
| 789 | used for groups that did not participate in the match; it defaults to |
| 790 | \code{None}. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 791 | \end{methoddesc} |
Guido van Rossum | 48d0437 | 1997-12-11 20:19:08 +0000 | [diff] [blame] | 792 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 793 | \begin{methoddesc}[MatchObject]{start}{\optional{group}} |
Fred Drake | a5a173e | 2002-11-13 17:48:15 +0000 | [diff] [blame] | 794 | \methodline{end}{\optional{group}} |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 795 | Return the indices of the start and end of the substring |
Guido van Rossum | 4650392 | 1998-01-19 23:14:17 +0000 | [diff] [blame] | 796 | matched by \var{group}; \var{group} defaults to zero (meaning the whole |
| 797 | matched substring). |
Fred Drake | 77a6c9e | 2000-09-07 14:00:51 +0000 | [diff] [blame] | 798 | Return \code{-1} if \var{group} exists but |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 799 | did not contribute to the match. For a match object |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 800 | \var{m}, and a group \var{g} that did contribute to the match, the |
| 801 | substring matched by group \var{g} (equivalent to |
| 802 | \code{\var{m}.group(\var{g})}) is |
| 803 | |
| 804 | \begin{verbatim} |
| 805 | m.string[m.start(g):m.end(g)] |
| 806 | \end{verbatim} |
| 807 | |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 808 | Note that |
| 809 | \code{m.start(\var{group})} will equal \code{m.end(\var{group})} if |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 810 | \var{group} matched a null string. For example, after \code{\var{m} = |
| 811 | re.search('b(c?)', 'cba')}, \code{\var{m}.start(0)} is 1, |
| 812 | \code{\var{m}.end(0)} is 2, \code{\var{m}.start(1)} and |
| 813 | \code{\var{m}.end(1)} are both 2, and \code{\var{m}.start(2)} raises |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 814 | an \exception{IndexError} exception. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 815 | \end{methoddesc} |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 816 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 817 | \begin{methoddesc}[MatchObject]{span}{\optional{group}} |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 818 | For \class{MatchObject} \var{m}, return the 2-tuple |
Fred Drake | 023f87f | 1998-01-12 19:16:24 +0000 | [diff] [blame] | 819 | \code{(\var{m}.start(\var{group}), \var{m}.end(\var{group}))}. |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 820 | Note that if \var{group} did not contribute to the match, this is |
Fred Drake | 77a6c9e | 2000-09-07 14:00:51 +0000 | [diff] [blame] | 821 | \code{(-1, -1)}. Again, \var{group} defaults to zero. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 822 | \end{methoddesc} |
Guido van Rossum | e4eb223 | 1997-12-17 00:23:39 +0000 | [diff] [blame] | 823 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 824 | \begin{memberdesc}[MatchObject]{pos} |
Andrew M. Kuchling | c85bf58 | 2003-05-13 14:40:24 +0000 | [diff] [blame] | 825 | The value of \var{pos} which was passed to the \function{search()} or |
| 826 | \function{match()} method of the \class{RegexObject}. This is the |
| 827 | index into the string at which the RE engine started looking for a |
| 828 | match. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 829 | \end{memberdesc} |
Guido van Rossum | 0b33410 | 1997-12-08 17:33:40 +0000 | [diff] [blame] | 830 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 831 | \begin{memberdesc}[MatchObject]{endpos} |
Andrew M. Kuchling | c85bf58 | 2003-05-13 14:40:24 +0000 | [diff] [blame] | 832 | The value of \var{endpos} which was passed to the \function{search()} |
| 833 | or \function{match()} method of the \class{RegexObject}. This is the |
| 834 | index into the string beyond which the RE engine will not go. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 835 | \end{memberdesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 836 | |
Gustavo Niemeyer | cf146d3 | 2003-04-20 01:48:59 +0000 | [diff] [blame] | 837 | \begin{memberdesc}[MatchObject]{lastindex} |
| 838 | The integer index of the last matched capturing group, or \code{None} |
| 839 | if no group was matched at all. For example, the expressions |
| 840 | \regexp{(a)b}, \regexp{((a)(b))}, and \regexp{((ab))} will have |
| 841 | \code{lastindex == 1} if applyied to the string \code{'ab'}, |
| 842 | while the expression \regexp{(a)(b)} will have \code{lastindex == 2}, |
| 843 | if applyied to the same string. |
| 844 | \end{memberdesc} |
| 845 | |
Andrew M. Kuchling | 75afc0b | 2000-10-18 23:08:13 +0000 | [diff] [blame] | 846 | \begin{memberdesc}[MatchObject]{lastgroup} |
| 847 | The name of the last matched capturing group, or \code{None} if the |
| 848 | group didn't have a name, or if no group was matched at all. |
| 849 | \end{memberdesc} |
| 850 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 851 | \begin{memberdesc}[MatchObject]{re} |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 852 | The regular expression object whose \method{match()} or |
| 853 | \method{search()} method produced this \class{MatchObject} instance. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 854 | \end{memberdesc} |
Guido van Rossum | 1acceb0 | 1997-08-14 23:12:18 +0000 | [diff] [blame] | 855 | |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 856 | \begin{memberdesc}[MatchObject]{string} |
Fred Drake | 20e0196 | 1998-02-19 15:09:35 +0000 | [diff] [blame] | 857 | The string passed to \function{match()} or \function{search()}. |
Fred Drake | 76547c5 | 1998-04-03 05:59:05 +0000 | [diff] [blame] | 858 | \end{memberdesc} |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 859 | |
| 860 | \subsection{Examples} |
| 861 | |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 862 | \leftline{\strong{Simulating \cfunction{scanf()}}} |
| 863 | |
| 864 | Python does not currently have an equivalent to \cfunction{scanf()}. |
| 865 | \ttindex{scanf()} |
| 866 | Regular expressions are generally more powerful, though also more |
| 867 | verbose, than \cfunction{scanf()} format strings. The table below |
| 868 | offers some more-or-less equivalent mappings between |
| 869 | \cfunction{scanf()} format tokens and regular expressions. |
| 870 | |
| 871 | \begin{tableii}{l|l}{textrm}{\cfunction{scanf()} Token}{Regular Expression} |
| 872 | \lineii{\code{\%c}} |
| 873 | {\regexp{.}} |
| 874 | \lineii{\code{\%5c}} |
| 875 | {\regexp{.\{5\}}} |
| 876 | \lineii{\code{\%d}} |
Fred Drake | 7af24bd | 2002-12-03 18:49:17 +0000 | [diff] [blame] | 877 | {\regexp{[-+]?\e d+}} |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 878 | \lineii{\code{\%e}, \code{\%E}, \code{\%f}, \code{\%g}} |
Raymond Hettinger | dfa7bd9 | 2003-09-09 01:30:13 +0000 | [diff] [blame] | 879 | {\regexp{[-+]?(\e d+(\e.\e d*)?|\e d*\e.\e d+)([eE][-+]?\e d+)?}} |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 880 | \lineii{\code{\%i}} |
Fred Drake | 7af24bd | 2002-12-03 18:49:17 +0000 | [diff] [blame] | 881 | {\regexp{[-+]?(0[xX][\e dA-Fa-f]+|0[0-7]*|\e d+)}} |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 882 | \lineii{\code{\%o}} |
| 883 | {\regexp{0[0-7]*}} |
| 884 | \lineii{\code{\%s}} |
Fred Drake | ed0a719 | 2001-11-29 20:23:14 +0000 | [diff] [blame] | 885 | {\regexp{\e S+}} |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 886 | \lineii{\code{\%u}} |
| 887 | {\regexp{\e d+}} |
| 888 | \lineii{\code{\%x}, \code{\%X}} |
Fred Drake | 53540ab | 2002-06-22 01:07:37 +0000 | [diff] [blame] | 889 | {\regexp{0[xX][\e dA-Fa-f]+}} |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 890 | \end{tableii} |
| 891 | |
| 892 | To extract the filename and numbers from a string like |
| 893 | |
| 894 | \begin{verbatim} |
| 895 | /usr/sbin/sendmail - 0 errors, 4 warnings |
| 896 | \end{verbatim} |
| 897 | |
| 898 | you would use a \cfunction{scanf()} format like |
| 899 | |
| 900 | \begin{verbatim} |
| 901 | %s - %d errors, %d warnings |
| 902 | \end{verbatim} |
| 903 | |
| 904 | The equivalent regular expression would be |
| 905 | |
| 906 | \begin{verbatim} |
Skip Montanaro | a8e1d81 | 2002-03-04 23:08:28 +0000 | [diff] [blame] | 907 | (\S+) - (\d+) errors, (\d+) warnings |
Fred Drake | 1cec7fa | 2001-11-29 08:45:22 +0000 | [diff] [blame] | 908 | \end{verbatim} |
| 909 | |
Martin v. Löwis | 7829e56 | 2003-05-03 10:57:53 +0000 | [diff] [blame] | 910 | \leftline{\strong{Avoiding recursion}} |
Skip Montanaro | a8e1d81 | 2002-03-04 23:08:28 +0000 | [diff] [blame] | 911 | |
Martin v. Löwis | 7829e56 | 2003-05-03 10:57:53 +0000 | [diff] [blame] | 912 | If you create regular expressions that require the engine to perform a |
| 913 | lot of recursion, you may encounter a RuntimeError exception with |
| 914 | the message \code{maximum recursion limit} exceeded. For example, |
Skip Montanaro | a8e1d81 | 2002-03-04 23:08:28 +0000 | [diff] [blame] | 915 | |
| 916 | \begin{verbatim} |
Martin v. Löwis | 7829e56 | 2003-05-03 10:57:53 +0000 | [diff] [blame] | 917 | >>> import re |
| 918 | >>> s = 'Begin ' + 1000*'a very long string ' + 'end' |
| 919 | >>> re.match('Begin (\w| )*? end', s).end() |
Fred Drake | 9479c95 | 2002-03-05 04:02:39 +0000 | [diff] [blame] | 920 | Traceback (most recent call last): |
| 921 | File "<stdin>", line 1, in ? |
| 922 | File "/usr/local/lib/python2.3/sre.py", line 132, in match |
| 923 | return _compile(pattern, flags).match(string) |
| 924 | RuntimeError: maximum recursion limit exceeded |
Skip Montanaro | a8e1d81 | 2002-03-04 23:08:28 +0000 | [diff] [blame] | 925 | \end{verbatim} |
| 926 | |
Martin v. Löwis | 7829e56 | 2003-05-03 10:57:53 +0000 | [diff] [blame] | 927 | You can often restructure your regular expression to avoid recursion. |
| 928 | |
Fred Drake | 788617f | 2003-07-16 16:19:08 +0000 | [diff] [blame] | 929 | Starting with Python 2.3, simple uses of the \regexp{*?} pattern are |
Martin v. Löwis | 7829e56 | 2003-05-03 10:57:53 +0000 | [diff] [blame] | 930 | special-cased to avoid recursion. Thus, the above regular expression |
Fred Drake | 788617f | 2003-07-16 16:19:08 +0000 | [diff] [blame] | 931 | can avoid recursion by being recast as |
| 932 | \regexp{Begin [a-zA-Z0-9_ ]*?end}. As a further benefit, such regular |
| 933 | expressions will run faster than their recursive equivalents. |