Doc/libre.tex

   1 \section{Built-in Module \module{re}}
   2 \label{module-re}
   3
   4 \bimodindex{re}
   5
   6 This module provides regular expression matching operations similar to
   7 those found in Perl.  It's 8-bit clean: the strings being processed
   8 may contain both null bytes and characters whose high bit is set.  Regular
   9 expression patterns may not contain null bytes, but they may contain
  10 characters with the high bit set.  The \module{re} module is always
  11 available.
  12
  13 Regular expressions use the backslash character (\character{\e}) to
  14 indicate special forms or to allow special characters to be used
  15 without invoking their special meaning.  This collides with Python's
  16 usage of the same character for the same purpose in string literals;
  17 for example, to match a literal backslash, one might have to write
  18 \code{'\e\e\e\e'} as the pattern string, because the regular expression
  19 must be \samp{\e\e}, and each backslash must be expressed as
  20 \samp{\e\e} inside a regular Python string literal.
  21
  22 The solution is to use Python's raw string notation for regular
  23 expression patterns; backslashes are not handled in any special way in
  24 a string literal prefixed with \character{r}.  So \code{r"\e n"} is a
  25 two-character string containing \character{\e} and \character{n},
  26 while \code{"\e n"} is a one-character string containing a newline.
  27 Usually patterns will be expressed in Python code using this raw
  28 string notation.
  29
  30 \subsection{Regular Expression Syntax}
  31
  32 A regular expression (or RE) specifies a set of strings that matches
  33 it; the functions in this module let you check if a particular string
  34 matches a given regular expression (or if a given regular expression
  35 matches a particular string, which comes down to the same thing).
  36
  37 Regular expressions can be concatenated to form new regular
  38 expressions; if \emph{A} and \emph{B} are both regular expressions,
  39 then \emph{AB} is also an regular expression.  If a string \emph{p}
  40 matches A and another string \emph{q} matches B, the string \emph{pq}
  41 will match AB.  Thus, complex expressions can easily be constructed
  42 from simpler primitive expressions like the ones described here.  For
  43 details of the theory and implementation of regular expressions,
  44 consult the Friedl book referenced below, or almost any textbook about
  45 compiler construction.
  46
  47 A brief explanation of the format of regular expressions follows.
  48 %For further information and a gentler presentation, consult XXX somewhere.
  49
  50 Regular expressions can contain both special and ordinary characters.
  51 Most ordinary characters, like \character{A}, \character{a}, or \character{0},
  52 are the simplest regular expressions; they simply match themselves.
  53 You can concatenate ordinary characters, so \regexp{last} matches the
  54 string \code{'last'}.  (In the rest of this section, we'll write RE's in
  55 \regexp{this special style}, usually without quotes, and strings to be
  56 matched \code{'in single quotes'}.)
  57
  58 Some characters, like \character{|} or \character{(}, are special.  Special
  59 characters either stand for classes of ordinary characters, or affect
  60 how the regular expressions around them are interpreted.
  61
  62 The special characters are:
  63 % define these since they're used twice:
  64 \newcommand{\MyLeftMargin}{0.7in}
  65 \newcommand{\MyLabelWidth}{0.65in}
  66 \begin{list}{}{\leftmargin \MyLeftMargin \labelwidth \MyLabelWidth}
  67 \item[\character{.}] (Dot.)  In the default mode, this matches any
  68 character except a newline.  If the \constant{DOTALL} flag has been
  69 specified, this matches any character including a newline.
  70 %
  71 \item[\character{\^}] (Caret.)  Matches the start of the string, and in
  72 \constant{MULTILINE} mode also matches immediately after each newline.
  73 %
  74 \item[\character{\$}] Matches the end of the string, and in
  75 \constant{MULTILINE} mode also matches before a newline.
  76 \regexp{foo} matches both 'foo' and 'foobar', while the regular
  77 expression \regexp{foo\$} matches only 'foo'.
  78 %
  79 \item[\character{*}] Causes the resulting RE to
  80 match 0 or more repetitions of the preceding RE, as many repetitions
  81 as are possible.  \regexp{ab*} will
  82 match 'a', 'ab', or 'a' followed by any number of 'b's.
  83 %
  84 \item[\character{+}] Causes the
  85 resulting RE to match 1 or more repetitions of the preceding RE.
  86 \regexp{ab+} will match 'a' followed by any non-zero number of 'b's; it
  87 will not match just 'a'.
  88 %
  89 \item[\character{?}] Causes the resulting RE to
  90 match 0 or 1 repetitions of the preceding RE.  \regexp{ab?} will
  91 match either 'a' or 'ab'.
  92 \item[\code{*?}, \code{+?}, \code{??}] The \character{*}, \character{+}, and
  93 \character{?} qualifiers are all \dfn{greedy}; they match as much text as
  94 possible.  Sometimes this behaviour isn't desired; if the RE
  95 \regexp{<.*>} is matched against \code{'<H1>title</H1>'}, it will match the
  96 entire string, and not just \code{'<H1>'}.
  97 Adding \character{?} after the qualifier makes it perform the match in
  98 \dfn{non-greedy} or \dfn{minimal} fashion; as \emph{few} characters as
  99 possible will be matched.  Using \regexp{.*?} in the previous
 100 expression will match only \code{'<H1>'}.
 101 %
 102 \item[\code{\{\var{m},\var{n}\}}] Causes the resulting RE to match from
 103 \var{m} to \var{n} repetitions of the preceding RE, attempting to
 104 match as many repetitions as possible.   For example, \regexp{a\{3,5\}}
 105 will match from 3 to 5 \character{a} characters.  Omitting \var{m} is the same
 106 as specifying 0 for the lower bound; omitting \var{n} specifies an
 107 infinite upper bound.
 108 %
 109 \item[\code{\{\var{m},\var{n}\}?}] Causes the resulting RE to
 110 match from \var{m} to \var{n} repetitions of the preceding RE,
 111 attempting to match as \emph{few} repetitions as possible.  This is
 112 the non-greedy version of the previous qualifier.  For example, on the
 113 6-character string \code{'aaaaaa'}, \regexp{a\{3,5\}} will match 5 \character{a}
 114 characters, while \regexp{a\{3,5\}?} will only match 3 characters.
 115 %
 116 \item[\character{\e}] Either escapes special characters (permitting you to match
 117 characters like \character{*}, \character{?}, and so forth), or
 118 signals a special sequence; special sequences are discussed below.
 119
 120 If you're not using a raw string to
 121 express the pattern, remember that Python also uses the
 122 backslash as an escape sequence in string literals; if the escape
 123 sequence isn't recognized by Python's parser, the backslash and
 124 subsequent character are included in the resulting string.  However,
 125 if Python would recognize the resulting sequence, the backslash should
 126 be repeated twice.  This is complicated and hard to understand, so
 127 it's highly recommended that you use raw strings for all but the
 128 simplest expressions.
 129 %
 130 \item[\code{[]}] Used to indicate a set of characters.  Characters can
 131 be listed individually, or a range of characters can be indicated by
 132 giving two characters and separating them by a \character{-}.  Special
 133 characters are not active inside sets.  For example, \regexp{[akm\$]}
 134 will match any of the characters \character{a}, \character{k},
 135 \character{m}, or \character{\$}; \regexp{[a-z]}
 136 will match any lowercase letter, and \code{[a-zA-Z0-9]} matches any
 137 letter or digit.  Character classes such as \code{\e w} or \code {\e
 138 S} (defined below) are also acceptable inside a range.  If you want to
 139 include a \character{]} or a \character{-} inside a set, precede it with a
 140 backslash, or place it as the first character.  The
 141 pattern \regexp{[]]} will match \code{']'}, for example.
 142
 143 You can match the characters not within a range by \dfn{complementing}
 144 the set.  This is indicated by including a
 145 \character{\^} as the first character of the set; \character{\^} elsewhere will
 146 simply match the \character{\^} character.  For example, \regexp{[\^5]}
 147 will match any character except \character{5}.
 148
 149 %
 150 \item[\character{|}]\code{A|B}, where A and B can be arbitrary REs,
 151 creates a regular expression that will match either A or B.  This can
 152 be used inside groups (see below) as well.  To match a literal \character{|},
 153 use \regexp{\e|}, or enclose it inside a character class, as in  \regexp{[|]}.
 154 %
 155 \item[\code{(...)}] Matches whatever regular expression is inside the
 156 parentheses, and indicates the start and end of a group; the contents
 157 of a group can be retrieved after a match has been performed, and can
 158 be matched later in the string with the \regexp{\e \var{number}} special
 159 sequence, described below.  To match the literals \character{(} or \character{')},
 160 use \regexp{\e(} or \regexp{\e)}, or enclose them inside a character
 161 class: \regexp{[(] [)]}.
 162 %
 163 \item[\code{(?...)}] This is an extension notation (a \character{?} following a
 164 \character{(} is not meaningful otherwise).  The first character after
 165 the \character{?}
 166 determines what the meaning and further syntax of the construct is.
 167 Extensions usually do not create a new group;
 168 \regexp{(?P<\var{name}>...)} is the only exception to this rule.
 169 Following are the currently supported extensions.
 170 %
 171 \item[\code{(?iLmsx)}] (One or more letters from the set \character{i},
 172 \character{L}, \character{m}, \character{s}, \character{x}.)  The group matches
 173 the empty string; the letters set the corresponding flags
 174 (\constant{re.I}, \constant{re.L}, \constant{re.M}, \constant{re.S},
 175 \constant{re.X}) for the entire regular expression.  This is useful if
 176 you wish to include the flags as part of the regular expression, instead
 177 of passing a \var{flag} argument to the \function{compile()} function.
 178 %
 179 \item[\code{(?:...)}] A non-grouping version of regular parentheses.
 180 Matches whatever regular expression is inside the parentheses, but the
 181 substring matched by the
 182 group \emph{cannot} be retrieved after performing a match or
 183 referenced later in the pattern.
 184 %
 185 \item[\code{(?P<\var{name}>...)}] Similar to regular parentheses, but
 186 the substring matched by the group is accessible via the symbolic group
 187 name \var{name}.  Group names must be valid Python identifiers.  A
 188 symbolic group is also a numbered group, just as if the group were not
 189 named.  So the group named 'id' in the example above can also be
 190 referenced as the numbered group 1.
 191
 192 For example, if the pattern is
 193 \regexp{(?P<id>[a-zA-Z_]\e w*)}, the group can be referenced by its
 194 name in arguments to methods of match objects, such as \code{m.group('id')}
 195 or \code{m.end('id')}, and also by name in pattern text
 196 (e.g. \regexp{(?P=id)}) and replacement text (e.g. \code{\e g<id>}).
 197 %
 198 \item[\code{(?P=\var{name})}] Matches whatever text was matched by the
 199 earlier group named \var{name}.
 200 %
 201 \item[\code{(?\#...)}] A comment; the contents of the parentheses are
 202 simply ignored.
 203 %
 204 \item[\code{(?=...)}] Matches if \regexp{...} matches next, but doesn't
 205 consume any of the string.  This is called a lookahead assertion.  For
 206 example, \regexp{Isaac (?=Asimov)} will match \code{'Isaac~'} only if it's
 207 followed by \code{'Asimov'}.
 208 %
 209 \item[\code{(?!...)}] Matches if \regexp{...} doesn't match next.  This
 210 is a negative lookahead assertion.  For example,
 211 \regexp{Isaac (?!Asimov)} will match \code{'Isaac~'} only if it's \emph{not}
 212 followed by \code{'Asimov'}.
 213
 214 \end{list}
 215
 216 The special sequences consist of \character{\e} and a character from the
 217 list below.  If the ordinary character is not on the list, then the
 218 resulting RE will match the second character.  For example,
 219 \regexp{\e\$} matches the character \character{\$}.
 220
 221 \begin{list}{}{\leftmargin \MyLeftMargin \labelwidth \MyLabelWidth}
 222
 223 %
 224 \item[\code{\e \var{number}}] Matches the contents of the group of the
 225 same number.  Groups are numbered starting from 1.  For example,
 226 \regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not
 227 \code{'the end'} (note
 228 the space after the group).  This special sequence can only be used to
 229 match one of the first 99 groups.  If the first digit of \var{number}
 230 is 0, or \var{number} is 3 octal digits long, it will not be interpreted
 231 as a group match, but as the character with octal value \var{number}.
 232 Inside the \character{[} and \character{]} of a character class, all numeric
 233 escapes are treated as characters.
 234 %
 235 \item[\code{\e A}] Matches only at the start of the string.
 236 %
 237 \item[\code{\e b}] Matches the empty string, but only at the
 238 beginning or end of a word.  A word is defined as a sequence of
 239 alphanumeric characters, so the end of a word is indicated by
 240 whitespace or a non-alphanumeric character.  Inside a character range,
 241 \regexp{\e b} represents the backspace character, for compatibility with
 242 Python's string literals.
 243 %
 244 \item[\code{\e B}] Matches the empty string, but only when it is
 245 \emph{not} at the beginning or end of a word.
 246 %
 247 \item[\code{\e d}]Matches any decimal digit; this is
 248 equivalent to the set \regexp{[0-9]}.
 249 %
 250 \item[\code{\e D}]Matches any non-digit character; this is
 251 equivalent to the set \regexp{[\^0-9]}.
 252 %
 253 \item[\code{\e s}]Matches any whitespace character; this is
 254 equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}.
 255 %
 256 \item[\code{\e S}]Matches any non-whitespace character; this is
 257 equivalent to the set \regexp{[\^\ \e t\e n\e r\e f\e v]}.
 258 %
 259 \item[\code{\e w}]When the \constant{LOCALE} flag is not specified,
 260 matches any alphanumeric character; this is equivalent to the set
 261 \regexp{[a-zA-Z0-9_]}.  With \constant{LOCALE}, it will match the set
 262 \regexp{[0-9_]} plus whatever characters are defined as letters for the
 263 current locale.
 264 %
 265 \item[\code{\e W}]When the \constant{LOCALE} flag is not specified,
 266 matches any non-alphanumeric character; this is equivalent to the set
 267 \regexp{[\^a-zA-Z0-9_]}.   With \constant{LOCALE}, it will match any
 268 character not in the set \regexp{[0-9_]}, and not defined as a letter
 269 for the current locale.
 270
 271 \item[\code{\e Z}]Matches only at the end of the string.
 272 %
 273
 274 \item[\code{\e \e}] Matches a literal backslash.
 275
 276 \end{list}
 277
 278 \subsection{Module Contents}
 279 \nodename{Contents of Module re}
 280
 281 The module defines the following functions and constants, and an exception:
 282
 283
 284 \begin{funcdesc}{compile}{pattern\optional{, flags}}
 285   Compile a regular expression pattern into a regular expression
 286   object, which can be used for matching using its \function{match()} and
 287   \function{search()} methods, described below.
 288
 289   The expression's behaviour can be modified by specifying a
 290   \var{flags} value.  Values can be any of the following variables,
 291   combined using bitwise OR (the \code{|} operator).
 292
 293 The sequence
 294
 295 \begin{verbatim}
 296 prog = re.compile(pat)
 297 result = prog.match(str)
 298 \end{verbatim}
 299
 300 is equivalent to
 301
 302 \begin{verbatim}
 303 result = re.match(pat, str)
 304 \end{verbatim}
 305
 306 but the version using \function{compile()} is more efficient when the
 307 expression will be used several times in a single program.
 308 %(The compiled version of the last pattern passed to
 309 %\function{regex.match()} or \function{regex.search()} is cached, so
 310 %programs that use only a single regular expression at a time needn't
 311 %worry about compiling regular expressions.)
 312 \end{funcdesc}
 313
 314 \begin{datadesc}{I}
 315 \dataline{IGNORECASE}
 316 Perform case-insensitive matching; expressions like \regexp{[A-Z]} will match
 317 lowercase letters, too.  This is not affected by the current locale.
 318 \end{datadesc}
 319
 320 \begin{datadesc}{L}
 321 \dataline{LOCALE}
 322 Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b},
 323 \regexp{\e B}, dependent on the current locale.
 324 \end{datadesc}
 325
 326 \begin{datadesc}{M}
 327 \dataline{MULTILINE}
 328 When specified, the pattern character \character{\^} matches at the
 329 beginning of the string and at the beginning of each line
 330 (immediately following each newline); and the pattern character
 331 \character{\$} matches at the end of the string and at the end of each line
 332 (immediately preceding each newline).
 333 By default, \character{\^} matches only at the beginning of the string, and
 334 \character{\$} only at the end of the string and immediately before the
 335 newline (if any) at the end of the string.
 336 \end{datadesc}
 337
 338 \begin{datadesc}{S}
 339 \dataline{DOTALL}
 340 Make the \character{.} special character match any character at all, including a
 341 newline; without this flag, \character{.} will match anything \emph{except}
 342 a newline.
 343 \end{datadesc}
 344
 345 \begin{datadesc}{X}
 346 \dataline{VERBOSE}
 347 This flag allows you to write regular expressions that look nicer.
 348 Whitespace within the pattern is ignored,
 349 except when in a character class or preceded by an unescaped
 350 backslash, and, when a line contains a \character{\#} neither in a character
 351 class or preceded by an unescaped backslash, all characters from the
 352 leftmost such \character{\#} through the end of the line are ignored.
 353 % XXX should add an example here
 354 \end{datadesc}
 355
 356
 357 \begin{funcdesc}{escape}{string}
 358   Return \var{string} with all non-alphanumerics backslashed; this is
 359   useful if you want to match an arbitrary literal string that may have
 360   regular expression metacharacters in it.
 361 \end{funcdesc}
 362
 363 \begin{funcdesc}{match}{pattern, string\optional{, flags}}
 364   If zero or more characters at the beginning of \var{string} match
 365   the regular expression \var{pattern}, return a corresponding
 366   \class{MatchObject} instance.  Return \code{None} if the string does not
 367   match the pattern; note that this is different from a zero-length
 368   match.
 369 \end{funcdesc}
 370
 371 \begin{funcdesc}{search}{pattern, string\optional{, flags}}
 372   Scan through \var{string} looking for a location where the regular
 373   expression \var{pattern} produces a match, and return a
 374   corresponding \class{MatchObject} instance.
 375   Return \code{None} if no
 376   position in the string matches the pattern; note that this is
 377   different from finding a zero-length match at some point in the string.
 378 \end{funcdesc}
 379
 380 \begin{funcdesc}{split}{pattern, string, \optional{, maxsplit\code{ = 0}}}
 381   Split \var{string} by the occurrences of \var{pattern}.  If
 382   capturing parentheses are used in pattern, then occurrences of
 383   patterns or subpatterns are also returned.
 384   If \var{maxsplit} is nonzero, at most \var{maxsplit} splits
 385   occur, and the remainder of the string is returned as the final
 386   element of the list.  (Incompatibility note: in the original Python
 387   1.5 release, \var{maxsplit} was ignored.  This has been fixed in
 388   later releases.)
 389 %
 390 \begin{verbatim}
 391 >>> re.split('[\W]+', 'Words, words, words.')
 392 ['Words', 'words', 'words', '']
 393 >>> re.split('([\W]+)', 'Words, words, words.')
 394 ['Words', ', ', 'words', ', ', 'words', '.', '']
 395 >>> re.split('[\W]+', 'Words, words, words.', 1)
 396 ['Words', 'words, words.']
 397 \end{verbatim}
 398 %
 399   This function combines and extends the functionality of
 400   the old \function{regsub.split()} and \function{regsub.splitx()}.
 401 \end{funcdesc}
 402
 403 \begin{funcdesc}{sub}{pattern, repl, string\optional{, count\code{ = 0}}}
 404 Return the string obtained by replacing the leftmost non-overlapping
 405 occurrences of \var{pattern} in \var{string} by the replacement
 406 \var{repl}.  If the pattern isn't found, \var{string} is returned
 407 unchanged.  \var{repl} can be a string or a function; if a function,
 408 it is called for every non-overlapping occurance of \var{pattern}.
 409 The function takes a single match object argument, and returns the
 410 replacement string.  For example:
 411 %
 412 \begin{verbatim}
 413 >>> def dashrepl(matchobj):
 414 ....    if matchobj.group(0) == '-': return ' '
 415 ....    else: return '-'
 416 >>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
 417 'pro--gram files'
 418 \end{verbatim}
 419 %
 420 The pattern may be a string or a
 421 regex object; if you need to specify
 422 regular expression flags, you must use a regex object, or use
 423 embedded modifiers in a pattern; e.g.
 424 \samp{sub("(?i)b+", "x", "bbbb BBBB")} returns \code{'x x'}.
 425
 426 The optional argument \var{count} is the maximum number of pattern
 427 occurrences to be replaced; \var{count} must be a non-negative integer, and
 428 the default value of 0 means to replace all occurrences.
 429
 430 Empty matches for the pattern are replaced only when not adjacent to a
 431 previous match, so \samp{sub('x*', '-', 'abc')} returns \code{'-a-b-c-'}.
 432
 433 If \var{repl} is a string, any backslash escapes in it are processed.
 434 That is, \samp{\e n} is converted to a single newline character,
 435 \samp{\e r} is converted to a linefeed, and so forth.  Unknown escapes
 436 such as \samp{\e j} are left alone.  Backreferences, such as \samp{\e 6}, are
 437 replaced with the substring matched by group 6 in the pattern.
 438
 439 In addition to character escapes and backreferences as described
 440 above, \samp{\e g<name>} will use the substring matched by the group
 441 named \samp{name}, as defined by the \regexp{(?P<name>...)} syntax.
 442 \samp{\e g<number>} uses the corresponding group number; \samp{\e
 443 g<2>} is therefore equivalent to \samp{\e 2}, but isn't ambiguous in a
 444 replacement such as \samp{\e g<2>0}.  \samp{\e 20} would be
 445 interpreted as a reference to group 20, not a reference to group 2
 446 followed by the literal character \character{0}.
 447 \end{funcdesc}
 448
 449 \begin{funcdesc}{subn}{pattern, repl, string\optional{, count\code{ = 0}}}
 450 Perform the same operation as \function{sub()}, but return a tuple
 451 \code{(\var{new_string}, \var{number_of_subs_made})}.
 452 \end{funcdesc}
 453
 454 \begin{excdesc}{error}
 455   Exception raised when a string passed to one of the functions here
 456   is not a valid regular expression (e.g., unmatched parentheses) or
 457   when some other error occurs during compilation or matching.  It is
 458   never an error if a string contains no match for a pattern.
 459 \end{excdesc}
 460
 461 \subsection{Regular Expression Objects}
 462 Compiled regular expression objects support the following methods and
 463 attributes:
 464
 465 \begin{methoddesc}[RegexObject]{match}{string\optional{, pos}\optional{,
 466                                        endpos}}
 467   If zero or more characters at the beginning of \var{string} match
 468   this regular expression, return a corresponding
 469   \class{MatchObject} instance.  Return \code{None} if the string does not
 470   match the pattern; note that this is different from a zero-length
 471   match.
 472
 473   The optional second parameter \var{pos} gives an index in the string
 474   where the search is to start; it defaults to \code{0}.  The
 475   \character{\^} pattern character will not match at the index where the
 476   search is to start.
 477
 478   The optional parameter \var{endpos} limits how far the string will
 479   be searched; it will be as if the string is \var{endpos} characters
 480   long, so only the characters from \var{pos} to \var{endpos} will be
 481   searched for a match.
 482 \end{methoddesc}
 483
 484 \begin{methoddesc}[RegexObject]{search}{string\optional{, pos}\optional{,
 485                                         endpos}}
 486   Scan through \var{string} looking for a location where this regular
 487   expression produces a match.  Return \code{None} if no
 488   position in the string matches the pattern; note that this is
 489   different from finding a zero-length match at some point in the string.
 490
 491   The optional \var{pos} and \var{endpos} parameters have the same
 492   meaning as for the \method{match()} method.
 493 \end{methoddesc}
 494
 495 \begin{methoddesc}[RegexObject]{split}{string, \optional{,
 496                                        maxsplit\code{ = 0}}}
 497 Identical to the \function{split()} function, using the compiled pattern.
 498 \end{methoddesc}
 499
 500 \begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}}
 501 Identical to the \function{sub()} function, using the compiled pattern.
 502 \end{methoddesc}
 503
 504 \begin{methoddesc}[RegexObject]{subn}{repl, string\optional{,
 505                                       count\code{ = 0}}}
 506 Identical to the \function{subn()} function, using the compiled pattern.
 507 \end{methoddesc}
 508
 509
 510 \begin{memberdesc}[RegexObject]{flags}
 511 The flags argument used when the regex object was compiled, or
 512 \code{0} if no flags were provided.
 513 \end{memberdesc}
 514
 515 \begin{memberdesc}[RegexObject]{groupindex}
 516 A dictionary mapping any symbolic group names defined by
 517 \regexp{(?P<\var{id}>)} to group numbers.  The dictionary is empty if no
 518 symbolic groups were used in the pattern.
 519 \end{memberdesc}
 520
 521 \begin{memberdesc}[RegexObject]{pattern}
 522 The pattern string from which the regex object was compiled.
 523 \end{memberdesc}
 524
 525 \subsection{Match Objects}
 526
 527 \class{MatchObject} instances support the following methods and attributes:
 528
 529 \begin{methoddesc}[MatchObject]{group}{\optional{group1, group2, ...}}
 530 Returns one or more subgroups of the match.  If there is a single
 531 argument, the result is a single string; if there are
 532 multiple arguments, the result is a tuple with one item per argument.
 533 Without arguments, \var{group1} defaults to zero (i.e. the whole match
 534 is returned).
 535 If a \var{groupN} argument is zero, the corresponding return value is the
 536 entire matching string; if it is in the inclusive range [1..99], it is
 537 the string matching the the corresponding parenthesized group.  If a
 538 group number is negative or larger than the number of groups defined
 539 in the pattern, an \exception{IndexError} exception is raised.
 540 If a group is contained in a part of the pattern that did not match,
 541 the corresponding result is \code{None}.  If a group is contained in a
 542 part of the pattern that matched multiple times, the last match is
 543 returned.
 544
 545 If the regular expression uses the \regexp{(?P<\var{name}>...)} syntax,
 546 the \var{groupN} arguments may also be strings identifying groups by
 547 their group name.  If a string argument is not used as a group name in
 548 the pattern, an \exception{IndexError} exception is raised.
 549
 550 A moderately complicated example:
 551
 552 \begin{verbatim}
 553 m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14')
 554 \end{verbatim}
 555
 556 After performing this match, \code{m.group(1)} is \code{'3'}, as is
 557 \code{m.group('int')}, and \code{m.group(2)} is \code{'14'}.
 558 \end{methoddesc}
 559
 560 \begin{methoddesc}[MatchObject]{groups}{}
 561 Return a tuple containing all the subgroups of the match, from 1 up to
 562 however many groups are in the pattern.  Groups that did not
 563 participate in the match have values of \code{None}.  (Incompatibility
 564 note: in the original Python 1.5 release, if the tuple was one element
 565 long, a string would be returned instead.  In later versions, a
 566 singleton tuple is returned in such cases.)
 567 \end{methoddesc}
 568
 569 \begin{methoddesc}[MatchObject]{start}{\optional{group}}
 570 \funcline{end}{\optional{group}}
 571 Return the indices of the start and end of the substring
 572 matched by \var{group}; \var{group} defaults to zero (meaning the whole
 573 matched substring).
 574 Return \code{None} if \var{group} exists but
 575 did not contribute to the match.  For a match object
 576 \var{m}, and a group \var{g} that did contribute to the match, the
 577 substring matched by group \var{g} (equivalent to
 578 \code{\var{m}.group(\var{g})}) is
 579
 580 \begin{verbatim}
 581 m.string[m.start(g):m.end(g)]
 582 \end{verbatim}
 583
 584 Note that
 585 \code{m.start(\var{group})} will equal \code{m.end(\var{group})} if
 586 \var{group} matched a null string.  For example, after \code{\var{m} =
 587 re.search('b(c?)', 'cba')}, \code{\var{m}.start(0)} is 1,
 588 \code{\var{m}.end(0)} is 2, \code{\var{m}.start(1)} and
 589 \code{\var{m}.end(1)} are both 2, and \code{\var{m}.start(2)} raises
 590 an \exception{IndexError} exception.
 591 \end{methoddesc}
 592
 593 \begin{methoddesc}[MatchObject]{span}{\optional{group}}
 594 For \class{MatchObject} \var{m}, return the 2-tuple
 595 \code{(\var{m}.start(\var{group}), \var{m}.end(\var{group}))}.
 596 Note that if \var{group} did not contribute to the match, this is
 597 \code{(None, None)}.  Again, \var{group} defaults to zero.
 598 \end{methoddesc}
 599
 600 \begin{memberdesc}[MatchObject]{pos}
 601 The value of \var{pos} which was passed to the
 602 \function{search()} or \function{match()} function.  This is the index into
 603 the string at which the regex engine started looking for a match.
 604 \end{memberdesc}
 605
 606 \begin{memberdesc}[MatchObject]{endpos}
 607 The value of \var{endpos} which was passed to the
 608 \function{search()} or \function{match()} function.  This is the index into
 609 the string beyond which the regex engine will not go.
 610 \end{memberdesc}
 611
 612 \begin{memberdesc}[MatchObject]{re}
 613 The regular expression object whose \method{match()} or
 614 \method{search()} method produced this \class{MatchObject} instance.
 615 \end{memberdesc}
 616
 617 \begin{memberdesc}[MatchObject]{string}
 618 The string passed to \function{match()} or \function{search()}.
 619 \end{memberdesc}
 620
 621 \begin{seealso}
 622 \seetext{Jeffrey Friedl, \emph{Mastering Regular Expressions},
 623 O'Reilly.  The Python material in this book dates from before the
 624 \module{re} module, but it covers writing good regular expression
 625 patterns in great detail.}
 626 \end{seealso}
 627