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

NAME

8       regsub  -  Perform  substitutions  based  on regular expression pattern
9       matching
10

SYNOPSIS

12       regsub ?switches? exp string subSpec ?varName?
13______________________________________________________________________________
14

DESCRIPTION

16       This command matches the regular expression  exp  against  string,  and
17       either  copies string to the variable whose name is given by varName or
18       returns string if varName is not present.  (Regular expression matching
19       is  described  in  the re_syntax reference page.)  If there is a match,
20       then while copying string to varName (or to the result of this  command
21       if  varName  is  not present) the portion of string that matched exp is
22       replaced with subSpec.  If subSpec contains a “&” or “\0”, then  it  is
23       replaced  in  the  substitution with the portion of string that matched
24       exp.  If subSpec contains a “\n”, where n is a digit between 1  and  9,
25       then it is replaced in the substitution with the portion of string that
26       matched the n'th parenthesized subexpression of exp.  Additional  back‐
27       slashes  may  be  used  in subSpec to prevent special interpretation of
28       “&”, “\0”, “\n” and backslashes.  The use  of  backslashes  in  subSpec
29       tends to interact badly with the Tcl parser's use of backslashes, so it
30       is generally safest to enclose subSpec in braces if it  includes  back‐
31       slashes.
32
33       If  the  initial arguments to regsub start with - then they are treated
34       as switches.  The following switches are currently supported:
35
36       -all   All ranges in string that match exp are found  and  substitution
37              is performed for each of these ranges.  Without this switch only
38              the first matching range is found and substituted.  If  -all  is
39              specified, then “&” and “\n” sequences are handled for each sub‐
40              stitution using the information from the corresponding match.
41
42       -expanded
43              Enables use of the  expanded  regular  expression  syntax  where
44              whitespace and comments are ignored.  This is the same as speci‐
45              fying the (?x) embedded option (see the re_syntax manual page).
46
47       -line  Enables newline-sensitive matching.  By default,  newline  is  a
48              completely  ordinary  character  with  no special meaning.  With
49              this flag, “[^” bracket expressions and “.”   never  match  new‐
50              line,  “^” matches an empty string after any newline in addition
51              to its normal function, and “$” matches an empty  string  before
52              any  newline  in  addition to its normal function.  This flag is
53              equivalent to specifying both -linestop and -lineanchor, or  the
54              (?n) embedded option (see the re_syntax manual page).
55
56       -linestop
57              Changes  the  behavior  of  “[^” bracket expressions and “.”  so
58              that they stop at newlines.  This is the same as specifying  the
59              (?p) embedded option (see the re_syntax manual page).
60
61       -lineanchor
62              Changes  the  behavior  of  “^”  and “$” (the “anchors”) so they
63              match the beginning and end of a line respectively.  This is the
64              same  as  specifying the (?w) embedded option (see the re_syntax
65              manual page).
66
67       -nocase
68              Upper-case characters in string will be converted to  lower-case
69              before  matching  against exp;  however, substitutions specified
70              by subSpec use the original unconverted form of string.
71
72       -start index
73              Specifies a character index offset  into  the  string  to  start
74              matching  the  regular expression at.  The index value is inter‐
75              preted in the same manner as the index argument to string index.
76              When  using this switch, “^” will not match the beginning of the
77              line, and \A will still match the start of the string at  index.
78              index will be constrained to the bounds of the input string.
79
80       --     Marks the end of switches.  The argument following this one will
81              be treated as exp even if it starts with a -.
82
83       If varName is supplied, the command returns a count of  the  number  of
84       matching  ranges  that  were  found  and replaced, otherwise the string
85       after replacement is returned.  See the manual  entry  for  regexp  for
86       details on the interpretation of regular expressions.
87

EXAMPLES

89       Replace  (in the string in variable string) every instance of foo which
90       is a word by itself with bar:
91
92              regsub -all {\mfoo\M} $string bar string
93
94       or (using the “basic regular expression” syntax):
95
96              regsub -all {(?b)\<foo\>} $string bar string
97
98       Insert double-quotes around the first instance of the word interesting,
99       however it is capitalized.
100
101              regsub -nocase {\yinteresting\y} $string {"&"} string
102
103       Convert  all  non-ASCII  and  Tcl-significant characters into \u escape
104       sequences by using regsub and subst in combination:
105
106              # This RE is just a character class for almost everything "bad"
107              set RE {[][{};#\\\$ \r\t\u0080-\uffff]}
108
109              # We will substitute with a fragment of Tcl script in brackets
110              set substitution {[format \\\\u%04x [scan "\\&" %c]]}
111
112              # Now we apply the substitution to get a subst-string that
113              # will perform the computational parts of the conversion. Note
114              # that newline is handled specially through string map since
115              # backslash-newline is a special sequence.
116              set quoted [subst [string map {\n {\\u000a}} \
117                      [regsub -all $RE $string $substitution]]]
118

SEE ALSO

120       regexp(n), re_syntax(n), subst(n), string(n)
121

KEYWORDS

123       match, pattern, quoting, regular expression, substitution
124
125
126
127Tcl                                   8.3                            regsub(n)
Impressum