Seth Woolley's Man Viewer

regsub(n) - regsub, regsub - Perform substitutions based on regular expression pattern matching - man n regsub

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

regsub(n)                    Tcl Built-In Commands                   regsub(n)



NAME
       regsub  -  Perform  substitutions  based  on regular expression pattern
       matching

SYNOPSIS
       regsub ?switches? exp string(3,n) subSpec ?varName?


DESCRIPTION
       This command matches the regular expression  exp  against  string(3,n),  and
       either  copies string(3,n) to the variable whose name is given by varName or
       returns string(3,n) if(3,n) varName is not present.  (Regular expression matching
       is  described  in(1,8)  the re_syntax reference page.)  If there is a match,
       then while copying string(3,n) to varName (or to the result of this  command
       if(3,n)  varName  is  not present) the portion of string(3,n) that matched exp is
       replaced with subSpec.  If subSpec contains a ``&'' or ``\0'', then  it
       is replaced in(1,8) the substitution with the portion of string(3,n) that matched
       exp.  If subSpec contains a ``\n'', where n is a digit between 1 and 9,
       then it is replaced in(1,8) the substitution with the portion of string(3,n) that
       matched the n-th parenthesized subexpression of exp.  Additional  back-
       slashes  may  be  used  in(1,8) subSpec to prevent special interpretation of
       ``&'' or ``\0'' or ``\n'' or backslash.  The use of backslashes in(1,8) sub-
       Spec  tends to interact badly with the Tcl parser's use of backslashes,
       so it's generally safest to enclose subSpec in(1,8) braces  if(3,n)  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(1,8) string(3,n) that match exp are found  and  substitu-
                 tion  is  performed  for  each of these ranges.  Without this
                 switch(1,n) only the first matching range  is  found  and  substi-
                 tuted.  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 mean-
                      ing.  With this flag, `[^' bracket expressions  and  `.'
                      never  match  newline, `^' matches an empty string(3,n) after
                      any newline in(1,8) addition to its normal function, and  `$'
                      matches  an  empty string(3,n) before any newline in(1,8) 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(1,8) string(3,n) will be converted  to  lower-
                 case  before  matching  against  exp;  however, substitutions
                 specified by subSpec use the  original  unconverted  form  of
                 string(3,n).

       -start index
                 Specifies  a  character index offset into the string(3,n) to start
                 matching the regular expression at.  When using this  switch(1,n),
                 `^'  will  not  match  the beginning of the line, and \A will
                 still match the start of the string(3,n) 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(3,n) 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(3,n)
       after replacement is returned.  See the manual  entry  for  regexp(3,n)  for
       details on the interpretation of regular expressions.


SEE ALSO
       regexp(3,n)(n), re_syntax(n)


KEYWORDS
       match, pattern, regular expression, substitute



Tcl                                   8.3                            regsub(n)

References for this manual (incoming links)