1regexp(n)                    Tcl Built-In Commands                   regexp(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       regexp - Match a regular expression against a string
9

SYNOPSIS

11       regexp ?switches? exp string ?matchVar? ?subMatchVar subMatchVar ...?
12______________________________________________________________________________
13

DESCRIPTION

15       Determines  whether  the  regular expression exp matches part or all of
16       string and returns 1 if it does, 0 if it does not,  unless  -inline  is
17       specified  (see  below).   (Regular expression matching is described in
18       the re_syntax reference page.)
19
20       If additional arguments  are  specified  after  string  then  they  are
21       treated  as the names of variables in which to return information about
22       which part(s) of string matched exp.  MatchVar will be set to the range
23       of  string that matched all of exp.  The first subMatchVar will contain
24       the characters in string that matched the leftmost parenthesized subex‐
25       pression  within  exp, the next subMatchVar will contain the characters
26       that matched the next parenthesized subexpression to the right in  exp,
27       and so on.
28
29       If  the  initial arguments to regexp start with - then they are treated
30       as switches.  The following switches are currently supported:
31
32       -about         Instead of attempting to match the  regular  expression,
33                      returns  a list containing information about the regular
34                      expression.  The first element of the list is  a  subex‐
35                      pression  count.   The second element is a list of prop‐
36                      erty names that describe various attributes of the regu‐
37                      lar  expression.  This  switch is primarily intended for
38                      debugging purposes.
39
40       -expanded      Enables use of the expanded  regular  expression  syntax
41                      where  whitespace and comments are ignored.  This is the
42                      same as specifying the (?x)  embedded  option  (see  the
43                      re_syntax manual page).
44
45       -indices       Changes what is stored in the matchVar and subMatchVars.
46                      Instead of storing the matching characters from  string,
47                      each variable will contain a list of two decimal strings
48                      giving the indices in string of the first and last char‐
49                      acters in the matching range of characters.
50
51       -line          Enables newline-sensitive matching.  By default, newline
52                      is a completely ordinary character with no special mean‐
53                      ing.   With  this flag, “[^” bracket expressions and “.”
54                      never match newline, “^” matches an empty  string  after
55                      any  newline in addition to its normal function, and “$”
56                      matches an empty string before any newline  in  addition
57                      to  its  normal  function.   This  flag is equivalent to
58                      specifying both -linestop and -lineanchor, or  the  (?n)
59                      embedded option (see the re_syntax manual page).
60
61       -linestop      Changes the behavior of “[^” bracket expressions and “.”
62                      so that they stop at newlines.   This  is  the  same  as
63                      specifying  the  (?p) embedded option (see the re_syntax
64                      manual page).
65
66       -lineanchor    Changes the behavior of “^” and “$” (the  “anchors”)  so
67                      they match the beginning and end of a line respectively.
68                      This is the same as specifying the (?w) embedded  option
69                      (see the re_syntax manual page).
70
71       -nocase        Causes  upper-case characters in string to be treated as
72                      lower case during the matching process.
73
74       -all           Causes the regular expression  to  be  matched  as  many
75                      times  as  possible  in  the string, returning the total
76                      number of matches found.   If  this  is  specified  with
77                      match  variables,  they will contain information for the
78                      last match only.
79
80       -inline        Causes the command to return, as a list, the  data  that
81                      would  otherwise  be  placed  in  match variables.  When
82                      using -inline, match variables may not be specified.  If
83                      used  with  -all,  the list will be concatenated at each
84                      iteration, such that a flat  list  is  always  returned.
85                      For  each  match  iteration, the command will append the
86                      overall match data, plus one element for each subexpres‐
87                      sion in the regular expression.  Examples are:
88
89                             regexp -inline -- {\w(\w)} " inlined "
90                                    in n
91                             regexp -all -inline -- {\w(\w)} " inlined "
92                                    in n li i ne e
93
94       -start index   Specifies  a  character  index offset into the string to
95                      start matching the regular  expression  at.   The  index
96                      value  is  interpreted  in  the same manner as the index
97                      argument to string index.  When using this  switch,  “^”
98                      will  not  match  the beginning of the line, and \A will
99                      still match the  start  of  the  string  at  index.   If
100                      -indices  is  specified,  the  indices  will  be indexed
101                      starting  from  the  absolute  beginning  of  the  input
102                      string.   index will be constrained to the bounds of the
103                      input string.
104
105       --             Marks the end of switches.  The argument following  this
106                      one will be treated as exp even if it starts with a -.
107
108       If there are more subMatchVars than parenthesized subexpressions within
109       exp, or if a particular subexpression in exp does not match the  string
110       (e.g.  because  it  was  in  a  portion  of the expression that was not
111       matched), then the corresponding subMatchVar will be set to “-1 -1”  if
112       -indices has been specified or to an empty string otherwise.
113

EXAMPLES

115       Find  the first occurrence of a word starting with foo in a string that
116       is not actually an instance of foobar, and get the letters following it
117       up to the end of the word into a variable:
118
119              regexp {\mfoo(?!bar\M)(\w*)} $string -> restOfWord
120
121       Note  that  the whole matched substring has been placed in the variable
122->”, which is a name chosen to look nice given that we are  not  actu‐
123       ally interested in its contents.
124
125       Find  the  index  of  the word badger (in any case) within a string and
126       store that in the variable location:
127
128              regexp -indices {(?i)\mbadger\M} $string location
129
130       This could also be written as a basic regular expression (as opposed to
131       using the default syntax of advanced regular expressions) match by pre‐
132       fixing the expression with a suitable flag:
133
134              regexp -indices {(?ib)\<badger\>} $string location
135
136       This counts the number of octal digits in a string:
137
138              regexp -all {[0-7]} $string
139
140       This lists all words (consisting of  all  sequences  of  non-whitespace
141       characters)  in  a  string, and is useful as a more powerful version of
142       the split command:
143
144              regexp -all -inline {\S+} $string
145

SEE ALSO

147       re_syntax(n), regsub(n), string(n)
148

KEYWORDS

150       match, parsing, pattern, regular expression, splitting, string
151
152
153
154Tcl                                   8.3                            regexp(n)
Impressum