NAME

       regsub - Perform substitutions based on regular expression pattern matching

SYNOPSIS

       regsub ?switches? exp string subSpec ?varName?
________________________________________________________________________________________________________________

DESCRIPTION

       This  command matches the regular expression exp against string, and either copies string to the variable
       whose name is given by varName or returns string if varName is not present.  (Regular expression matching
       is described in the re_syntax reference page.)  If there is a match, then while copying string to varName
       (or to the result of this command if varName is not present) the portion of string that  matched  exp  is
       replaced  with  subSpec.  If subSpec contains a “&” or “\0”, then it is replaced in the substitution with
       the portion of string that matched exp.  If subSpec contains a “\n”, where n is a digit between 1 and  9,
       then  it  is  replaced in the substitution with the portion of string that matched the n'th parenthesized
       subexpression of exp.  Additional backslashes may be used in subSpec to prevent special interpretation of
       “&”,  “\0”, “\n” and backslashes.  The use of backslashes in subSpec tends to interact badly with the Tcl
       parser's use of backslashes, so it is generally safest to  enclose  subSpec  in  braces  if  it  includes
       backslashes.

       If  the  initial  arguments  to  regsub  start  with  - then they are treated as switches.  The following
       switches are currently supported:

       -all      All ranges in string that match exp are found and substitution is performed for each  of  these
                 ranges.   Without  this switch only the first matching range is found and substituted.  If -all
                 is specified, then “&”  and  “\n”  sequences  are  handled  for  each  substitution  using  the
                 information from the corresponding match.

       -expanded      Enables  use  of  the expanded regular expression syntax where whitespace and comments are
                      ignored.  This is the same as specifying the  (?x)  embedded  option  (see  the  re_syntax
                      manual page).

       -line          Enables  newline-sensitive  matching.   By  default,  newline  is  a  completely  ordinary
                      character with no special meaning.  With this  flag,  “[^”  bracket  expressions  and  “.”
                      never  match  newline,  “^”  matches  an empty string after any newline in addition to its
                      normal function, and “$” matches an empty string before any newline  in  addition  to  its
                      normal function.  This flag is equivalent to specifying both -linestop and -lineanchor, or
                      the (?n) embedded option (see the re_syntax manual page).

       -linestop      Changes the behavior of “[^” bracket expressions and “.”  so that they stop  at  newlines.
                      This is the same as specifying the (?p) embedded option (see the re_syntax manual page).

       -lineanchor    Changes the behavior of “^” and “$” (the “anchors”) so they match the beginning and end of
                      a line respectively.  This is the same as specifying the (?w)  embedded  option  (see  the
                      re_syntax manual page).

       -nocase   Upper-case  characters  in  string will be converted to lower-case before matching against exp;
                 however, substitutions specified by subSpec use the original unconverted form of string.

       -start index
                 Specifies a character index offset into the string to start matching the regular expression at. │
                 The  index value is interpreted in the same manner as the index argument to string index.  When
                 using this switch, “^” will not match the beginning of the line, and \A will  still  match  the
                 start of the string at index.  index will be constrained to the bounds of the input string.

       --        Marks  the  end of switches.  The argument following this one will be treated as exp even if it
                 starts with a -.

       If varName is supplied, the command returns a count of the number of matching ranges that were found  and
       replaced,  otherwise  the  string  after  replacement  is  returned.  See the manual entry for regexp for
       details on the interpretation of regular expressions.

EXAMPLES

       Replace (in the string in variable string) every instance of foo which is a word by itself with bar:
              regsub -all {\mfoo\M} $string bar string
       or (using the “basic regular expression” syntax):
              regsub -all {(?b)\<foo\>} $string bar string

       Insert double-quotes around the first instance of the word interesting, however it is capitalized.
              regsub -nocase {\yinteresting\y} $string {"&"} string

       Convert all non-ASCII and Tcl-significant characters into \u escape sequences by using regsub  and  subst
       in combination:
              # This RE is just a character class for almost everything "bad"
              set RE {[][{};#\\\$ \r\t\u0080-\uffff]}

              # We will substitute with a fragment of Tcl script in brackets
              set substitution {[format \\\\u%04x [scan "\\&" %c]]}

              # Now we apply the substitution to get a subst-string that
              # will perform the computational parts of the conversion. Note
              # that newline is handled specially through string map since
              # backslash-newline is a special sequence.
              set quoted [subst [string map {\n {\\u000a}} \
                      [regsub -all $RE $string $substitution]]]

SEE ALSO

       regexp(3tcl), re_syntax(3tcl), subst(3tcl), string(3tcl)                                                  │

KEYWORDS

       match, pattern, quoting, regular expression, substitute