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
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
Man(1) output converted with
man2html