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 it copies string to the variable whose name is
       given  by  varName.   (Regular  expression   matching   is
       described in the re_syntax reference page.)  If there is a
       match, then while copying string to varName the portion of
       string that matched exp is replaced with subSpec.  If sub-
       Spec 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 parenthe-
       sized subexpression of exp.  Additional backslashes may be
       used in subSpec to prevent special interpretation of ``&''
       or  ``\0'' or ``\n'' or backslash.  The use of backslashes
       in subSpec tends to interact badly with the  Tcl  parser's
       use  of  backslashes,  so it's generally safest to enclose
       subSpec in braces if it includes backslashes.

       If the initial arguments to regexp start with - then  they
       are  treated as switches.  The following switches are cur-
       rently 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 expres-
                      sion syntax where whitespace  and  comments
                      are  ignored.  This is the same as specify-
                      ing the (?x) embedded option (see  METASYN-
                      TAX, below).

       -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 equiva-
                      lent to specifying both -linestop and -lin-
                      eanchor,  or  the (?n) embedded option (see
                      METASYNTAX, below).

       -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 METASYNTAX,
                      below).

       -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 METASYNTAX, below).

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

       -start index
                 Specifies a  character  index  offset  into  the
                 string  to start matching the regular expression
                 at.  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 follow-
                 ing  this  one will be treated as exp even if it
                 starts with a -.

       The command returns a count  of  the  number  of  matching
       ranges that were found and replaced.  See the manual entry
       for regexp for details on the  interpretation  of  regular
       expressions.


SEE ALSO
       regexp(n), re_syntax(n)


KEYWORDS
       match, pattern, regular expression, substitute
