blob: 1d9c987c1cdc866f3f66bdb5e56c1ef8d6675e21 [file] [log] [blame]
Guido van Rossum7627c0d2000-03-31 14:58:54 +00001#
2# Secret Labs' Regular Expression Engine
Guido van Rossum7627c0d2000-03-31 14:58:54 +00003#
4# re-compatible interface for the sre matching engine
5#
Fredrik Lundh770617b2001-01-14 15:06:11 +00006# Copyright (c) 1998-2001 by Secret Labs AB. All rights reserved.
Guido van Rossum7627c0d2000-03-31 14:58:54 +00007#
Fredrik Lundh29c4ba92000-08-01 18:20:07 +00008# This version of the SRE library can be redistributed under CNRI's
9# Python 1.6 license. For any other use, please contact Secret Labs
10# AB (info@pythonware.com).
11#
Guido van Rossum7627c0d2000-03-31 14:58:54 +000012# Portions of this engine have been developed in cooperation with
Fredrik Lundh29c4ba92000-08-01 18:20:07 +000013# CNRI. Hewlett-Packard provided funding for 1.6 integration and
Guido van Rossum7627c0d2000-03-31 14:58:54 +000014# other compatibility work.
15#
16
Fred Drake9f5b8222001-09-04 19:20:06 +000017r"""Support for regular expressions (RE).
Fred Drakeb8f22742001-09-04 19:10:20 +000018
19This module provides regular expression matching operations similar to
Fredrik Lundhdac58492001-10-21 21:48:30 +000020those found in Perl. It supports both 8-bit and Unicode strings; both
21the pattern and the strings being processed can contain null bytes and
22characters outside the US ASCII range.
Fred Drakeb8f22742001-09-04 19:10:20 +000023
Fredrik Lundhdac58492001-10-21 21:48:30 +000024Regular expressions can contain both special and ordinary characters.
25Most ordinary characters, like "A", "a", or "0", are the simplest
26regular expressions; they simply match themselves. You can
Fred Drakeb8f22742001-09-04 19:10:20 +000027concatenate ordinary characters, so last matches the string 'last'.
28
29The special characters are:
30 "." Matches any character except a newline.
31 "^" Matches the start of the string.
Georg Brandle4216912008-01-21 17:29:23 +000032 "$" Matches the end of the string or just before the newline at
33 the end of the string.
Fred Drakeb8f22742001-09-04 19:10:20 +000034 "*" Matches 0 or more (greedy) repetitions of the preceding RE.
35 Greedy means that it will match as many repetitions as possible.
36 "+" Matches 1 or more (greedy) repetitions of the preceding RE.
37 "?" Matches 0 or 1 (greedy) of the preceding RE.
38 *?,+?,?? Non-greedy versions of the previous three special characters.
39 {m,n} Matches from m to n repetitions of the preceding RE.
40 {m,n}? Non-greedy version of the above.
Georg Brandl42231992008-01-26 11:00:18 +000041 "\\" Either escapes special characters or signals a special sequence.
Fred Drakeb8f22742001-09-04 19:10:20 +000042 [] Indicates a set of characters.
43 A "^" as the first character indicates a complementing set.
44 "|" A|B, creates an RE that will match either A or B.
45 (...) Matches the RE inside the parentheses.
46 The contents can be retrieved or matched later in the string.
Fredrik Lundhdac58492001-10-21 21:48:30 +000047 (?iLmsux) Set the I, L, M, S, U, or X flag for the RE (see below).
Fred Drakeb8f22742001-09-04 19:10:20 +000048 (?:...) Non-grouping version of regular parentheses.
49 (?P<name>...) The substring matched by the group is accessible by name.
50 (?P=name) Matches the text matched earlier by the group named name.
51 (?#...) A comment; ignored.
52 (?=...) Matches if ... matches next, but doesn't consume the string.
53 (?!...) Matches if ... doesn't match next.
Georg Brandl42231992008-01-26 11:00:18 +000054 (?<=...) Matches if preceded by ... (must be fixed length).
55 (?<!...) Matches if not preceded by ... (must be fixed length).
56 (?(id/name)yes|no) Matches yes pattern if the group with id/name matched,
57 the (optional) no pattern otherwise.
Fred Drakeb8f22742001-09-04 19:10:20 +000058
59The special sequences consist of "\\" and a character from the list
Fredrik Lundhdac58492001-10-21 21:48:30 +000060below. If the ordinary character is not on the list, then the
Fred Drakeb8f22742001-09-04 19:10:20 +000061resulting RE will match the second character.
Fred Drake9f5b8222001-09-04 19:20:06 +000062 \number Matches the contents of the group of the same number.
63 \A Matches only at the start of the string.
64 \Z Matches only at the end of the string.
65 \b Matches the empty string, but only at the start or end of a word.
66 \B Matches the empty string, but not at the start or end of a word.
67 \d Matches any decimal digit; equivalent to the set [0-9].
68 \D Matches any non-digit character; equivalent to the set [^0-9].
69 \s Matches any whitespace character; equivalent to [ \t\n\r\f\v].
70 \S Matches any non-whitespace character; equiv. to [^ \t\n\r\f\v].
71 \w Matches any alphanumeric character; equivalent to [a-zA-Z0-9_].
Fred Drakeb8f22742001-09-04 19:10:20 +000072 With LOCALE, it will match the set [0-9_] plus characters defined
73 as letters for the current locale.
Fred Drake9f5b8222001-09-04 19:20:06 +000074 \W Matches the complement of \w.
75 \\ Matches a literal backslash.
Fred Drakeb8f22742001-09-04 19:10:20 +000076
77This module exports the following functions:
78 match Match a regular expression pattern to the beginning of a string.
79 search Search a string for the presence of a pattern.
80 sub Substitute occurrences of a pattern found in a string.
81 subn Same as sub, but also return the number of substitutions made.
82 split Split a string by the occurrences of a pattern.
83 findall Find all occurrences of a pattern in a string.
Georg Brandl42231992008-01-26 11:00:18 +000084 finditer Return an iterator yielding a match object for each match.
Fred Drakeb8f22742001-09-04 19:10:20 +000085 compile Compile a pattern into a RegexObject.
86 purge Clear the regular expression cache.
Fred Drakeb8f22742001-09-04 19:10:20 +000087 escape Backslash all non-alphanumerics in a string.
88
89Some of the functions in this module takes flags as optional parameters:
90 I IGNORECASE Perform case-insensitive matching.
91 L LOCALE Make \w, \W, \b, \B, dependent on the current locale.
Georg Brandle4216912008-01-21 17:29:23 +000092 M MULTILINE "^" matches the beginning of lines (after a newline)
93 as well as the string.
94 "$" matches the end of lines (before a newline) as well
95 as the end of the string.
Fred Drakeb8f22742001-09-04 19:10:20 +000096 S DOTALL "." matches any character at all, including the newline.
97 X VERBOSE Ignore whitespace and comments for nicer looking RE's.
Fredrik Lundh21009b92001-09-18 18:47:09 +000098 U UNICODE Make \w, \W, \b, \B, dependent on the Unicode locale.
Fred Drakeb8f22742001-09-04 19:10:20 +000099
100This module also defines an exception 'error'.
101
102"""
Fredrik Lundh21009b92001-09-18 18:47:09 +0000103
Fredrik Lundh703ce812001-10-24 22:16:30 +0000104import sys
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000105import sre_compile
Fredrik Lundh436c3d52000-06-29 08:58:44 +0000106import sre_parse
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000107
Fredrik Lundhf2989b22001-02-18 12:05:16 +0000108# public symbols
109__all__ = [ "match", "search", "sub", "subn", "split", "findall",
110 "compile", "purge", "template", "escape", "I", "L", "M", "S", "X",
111 "U", "IGNORECASE", "LOCALE", "MULTILINE", "DOTALL", "VERBOSE",
112 "UNICODE", "error" ]
113
Fredrik Lundhbec95b92001-10-21 16:47:57 +0000114__version__ = "2.2.1"
Fredrik Lundhb25e1ad2001-03-22 15:50:10 +0000115
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000116# flags
Fredrik Lundh770617b2001-01-14 15:06:11 +0000117I = IGNORECASE = sre_compile.SRE_FLAG_IGNORECASE # ignore case
118L = LOCALE = sre_compile.SRE_FLAG_LOCALE # assume current 8-bit locale
119U = UNICODE = sre_compile.SRE_FLAG_UNICODE # assume unicode locale
120M = MULTILINE = sre_compile.SRE_FLAG_MULTILINE # make anchors look for newline
121S = DOTALL = sre_compile.SRE_FLAG_DOTALL # make dot match newline
122X = VERBOSE = sre_compile.SRE_FLAG_VERBOSE # ignore whitespace and comments
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000123
Fredrik Lundh770617b2001-01-14 15:06:11 +0000124# sre extensions (experimental, don't rely on these)
125T = TEMPLATE = sre_compile.SRE_FLAG_TEMPLATE # disable backtracking
126DEBUG = sre_compile.SRE_FLAG_DEBUG # dump pattern after compilation
Fredrik Lundh436c3d52000-06-29 08:58:44 +0000127
128# sre exception
Fredrik Lundhbe2211e2000-06-29 16:57:40 +0000129error = sre_compile.error
Fredrik Lundh436c3d52000-06-29 08:58:44 +0000130
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000131# --------------------------------------------------------------------
132# public interface
133
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000134def match(pattern, string, flags=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000135 """Try to apply the pattern at the start of the string, returning
136 a match object, or None if no match was found."""
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000137 return _compile(pattern, flags).match(string)
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000138
139def search(pattern, string, flags=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000140 """Scan through string looking for a match to the pattern, returning
141 a match object, or None if no match was found."""
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000142 return _compile(pattern, flags).search(string)
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000143
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000144def sub(pattern, repl, string, count=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000145 """Return the string obtained by replacing the leftmost
146 non-overlapping occurrences of the pattern in string by the
Andrew M. Kuchling43ab0cd2004-08-07 17:41:54 +0000147 replacement repl. repl can be either a string or a callable;
148 if a callable, it's passed the match object and must return
149 a replacement string to be used."""
Fredrik Lundh7898c3e2000-08-07 20:59:04 +0000150 return _compile(pattern, 0).sub(repl, string, count)
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000151
152def subn(pattern, repl, string, count=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000153 """Return a 2-tuple containing (new_string, number).
154 new_string is the string obtained by replacing the leftmost
155 non-overlapping occurrences of the pattern in the source
156 string by the replacement repl. number is the number of
Andrew M. Kuchling43ab0cd2004-08-07 17:41:54 +0000157 substitutions that were made. repl can be either a string or a
158 callable; if a callable, it's passed the match object and must
159 return a replacement string to be used."""
Fredrik Lundh7898c3e2000-08-07 20:59:04 +0000160 return _compile(pattern, 0).subn(repl, string, count)
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000161
162def split(pattern, string, maxsplit=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000163 """Split the source string by the occurrences of the pattern,
164 returning a list containing the resulting substrings."""
Fredrik Lundh7898c3e2000-08-07 20:59:04 +0000165 return _compile(pattern, 0).split(string, maxsplit)
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000166
Raymond Hettinger596ba4d2004-09-24 03:41:05 +0000167def findall(pattern, string, flags=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000168 """Return a list of all non-overlapping matches in the string.
169
170 If one or more groups are present in the pattern, return a
171 list of groups; this will be a list of tuples if the pattern
172 has more than one group.
173
174 Empty matches are included in the result."""
Raymond Hettinger596ba4d2004-09-24 03:41:05 +0000175 return _compile(pattern, flags).findall(string)
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000176
Fredrik Lundh703ce812001-10-24 22:16:30 +0000177if sys.hexversion >= 0x02020000:
Guido van Rossum0d976552002-10-14 12:22:17 +0000178 __all__.append("finditer")
Raymond Hettinger596ba4d2004-09-24 03:41:05 +0000179 def finditer(pattern, string, flags=0):
Fredrik Lundhb7747e22001-10-28 20:15:40 +0000180 """Return an iterator over all non-overlapping matches in the
181 string. For each match, the iterator returns a match object.
Fredrik Lundh703ce812001-10-24 22:16:30 +0000182
183 Empty matches are included in the result."""
Raymond Hettinger596ba4d2004-09-24 03:41:05 +0000184 return _compile(pattern, flags).finditer(string)
Fredrik Lundh703ce812001-10-24 22:16:30 +0000185
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000186def compile(pattern, flags=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000187 "Compile a regular expression pattern, returning a pattern object."
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000188 return _compile(pattern, flags)
189
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000190def purge():
Fredrik Lundh770617b2001-01-14 15:06:11 +0000191 "Clear the regular expression cache"
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000192 _cache.clear()
Fredrik Lundhb25e1ad2001-03-22 15:50:10 +0000193 _cache_repl.clear()
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000194
Fredrik Lundh436c3d52000-06-29 08:58:44 +0000195def template(pattern, flags=0):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000196 "Compile a template pattern, returning a pattern object"
Fredrik Lundh436c3d52000-06-29 08:58:44 +0000197 return _compile(pattern, flags|T)
198
Raymond Hettingerebb7f302005-09-12 22:50:37 +0000199_alphanum = {}
200for c in 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890':
201 _alphanum[c] = 1
202del c
203
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000204def escape(pattern):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000205 "Escape all non-alphanumeric characters in pattern."
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000206 s = list(pattern)
Raymond Hettingerebb7f302005-09-12 22:50:37 +0000207 alphanum = _alphanum
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000208 for i in range(len(pattern)):
209 c = pattern[i]
Raymond Hettingerebb7f302005-09-12 22:50:37 +0000210 if c not in alphanum:
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000211 if c == "\000":
212 s[i] = "\\000"
213 else:
214 s[i] = "\\" + c
Barry Warsaw8bee7612004-08-25 02:22:30 +0000215 return pattern[:0].join(s)
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000216
217# --------------------------------------------------------------------
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000218# internals
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000219
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000220_cache = {}
Fredrik Lundhb25e1ad2001-03-22 15:50:10 +0000221_cache_repl = {}
222
Fredrik Lundh397a6542001-10-18 19:30:16 +0000223_pattern_type = type(sre_compile.compile("", 0))
224
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000225_MAXCACHE = 100
Guido van Rossum7627c0d2000-03-31 14:58:54 +0000226
Fredrik Lundh7898c3e2000-08-07 20:59:04 +0000227def _compile(*key):
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000228 # internal: compile pattern
Hye-Shik Chang0f5bf1e2004-04-20 21:11:11 +0000229 cachekey = (type(key[0]),) + key
230 p = _cache.get(cachekey)
Fredrik Lundh7898c3e2000-08-07 20:59:04 +0000231 if p is not None:
232 return p
233 pattern, flags = key
Just van Rossum12723ba2003-07-02 20:03:04 +0000234 if isinstance(pattern, _pattern_type):
Raymond Hettinger80016c92007-12-19 18:13:31 +0000235 if flags:
236 raise ValueError('Cannot process flags argument with a compiled pattern')
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000237 return pattern
Just van Rossum74902502003-07-02 21:37:16 +0000238 if not sre_compile.isstring(pattern):
Fredrik Lundh397a6542001-10-18 19:30:16 +0000239 raise TypeError, "first argument must be string or compiled pattern"
Fredrik Lundhe1869832000-08-01 22:47:49 +0000240 try:
241 p = sre_compile.compile(pattern, flags)
242 except error, v:
243 raise error, v # invalid expression
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000244 if len(_cache) >= _MAXCACHE:
245 _cache.clear()
Hye-Shik Chang0f5bf1e2004-04-20 21:11:11 +0000246 _cache[cachekey] = p
Jeremy Hyltonb1aa1952000-06-01 17:39:12 +0000247 return p
248
Fredrik Lundhb25e1ad2001-03-22 15:50:10 +0000249def _compile_repl(*key):
250 # internal: compile replacement pattern
251 p = _cache_repl.get(key)
252 if p is not None:
253 return p
254 repl, pattern = key
255 try:
256 p = sre_parse.parse_template(repl, pattern)
257 except error, v:
258 raise error, v # invalid expression
259 if len(_cache_repl) >= _MAXCACHE:
260 _cache_repl.clear()
261 _cache_repl[key] = p
262 return p
263
Fredrik Lundh5644b7f2000-09-21 17:03:25 +0000264def _expand(pattern, match, template):
265 # internal: match.expand implementation hook
266 template = sre_parse.parse_template(template, pattern)
267 return sre_parse.expand_template(template, match)
268
Fredrik Lundhbec95b92001-10-21 16:47:57 +0000269def _subx(pattern, template):
270 # internal: pattern.sub/subn implementation helper
Fredrik Lundhdac58492001-10-21 21:48:30 +0000271 template = _compile_repl(template, pattern)
272 if not template[0] and len(template[1]) == 1:
Fredrik Lundhbec95b92001-10-21 16:47:57 +0000273 # literal replacement
Fredrik Lundhdac58492001-10-21 21:48:30 +0000274 return template[1][0]
275 def filter(match, template=template):
276 return sre_parse.expand_template(template, match)
277 return filter
Fredrik Lundh0640e112000-06-30 13:55:15 +0000278
279# register myself for pickling
280
281import copy_reg
282
283def _pickle(p):
284 return _compile, (p.pattern, p.flags)
285
Fredrik Lundh397a6542001-10-18 19:30:16 +0000286copy_reg.pickle(_pattern_type, _pickle, _compile)
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000287
288# --------------------------------------------------------------------
289# experimental stuff (see python-dev discussions for details)
290
291class Scanner:
Fredrik Lundh1296a8d2001-10-21 18:04:11 +0000292 def __init__(self, lexicon, flags=0):
Fredrik Lundh29c4ba92000-08-01 18:20:07 +0000293 from sre_constants import BRANCH, SUBPATTERN
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000294 self.lexicon = lexicon
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000295 # combine phrases into a compound pattern
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000296 p = []
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000297 s = sre_parse.Pattern()
Fredrik Lundh1296a8d2001-10-21 18:04:11 +0000298 s.flags = flags
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000299 for phrase, action in lexicon:
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000300 p.append(sre_parse.SubPattern(s, [
Fredrik Lundh1296a8d2001-10-21 18:04:11 +0000301 (SUBPATTERN, (len(p)+1, sre_parse.parse(phrase, flags))),
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000302 ]))
Guido van Rossum212861c2008-02-05 17:32:15 +0000303 s.groups = len(p)+1
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000304 p = sre_parse.SubPattern(s, [(BRANCH, (None, p))])
Fredrik Lundh8a3ebf82000-07-23 21:46:17 +0000305 self.scanner = sre_compile.compile(p)
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000306 def scan(self, string):
307 result = []
308 append = result.append
Fredrik Lundh1296a8d2001-10-21 18:04:11 +0000309 match = self.scanner.scanner(string).match
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000310 i = 0
311 while 1:
Fredrik Lundh1296a8d2001-10-21 18:04:11 +0000312 m = match()
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000313 if not m:
314 break
315 j = m.end()
316 if i == j:
317 break
Fredrik Lundh1296a8d2001-10-21 18:04:11 +0000318 action = self.lexicon[m.lastindex-1][1]
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000319 if callable(action):
Fredrik Lundh770617b2001-01-14 15:06:11 +0000320 self.match = m
Fredrik Lundh7cafe4d2000-07-02 17:33:27 +0000321 action = action(self, m.group())
322 if action is not None:
323 append(action)
324 i = j
325 return result, string[i:]