summaryrefslogtreecommitdiffstats
path: root/doc/regsub.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/regsub.n')
-rw-r--r--doc/regsub.n72
1 files changed, 72 insertions, 0 deletions
diff --git a/doc/regsub.n b/doc/regsub.n
new file mode 100644
index 0000000..62720ac
--- /dev/null
+++ b/doc/regsub.n
@@ -0,0 +1,72 @@
+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" SCCS: @(#) regsub.n 1.9 96/08/26 13:00:11
+'\"
+.so man.macros
+.TH regsub n 7.4 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+regsub \- Perform substitutions based on regular expression pattern matching
+.SH SYNOPSIS
+\fBregsub \fR?\fIswitches\fR? \fIexp string subSpec varName\fR
+.BE
+
+.SH DESCRIPTION
+.PP
+This command matches the regular expression \fIexp\fR against
+\fIstring\fR,
+and it copies \fIstring\fR to the variable whose name is
+given by \fIvarName\fR.
+If there is a match, then while copying \fIstring\fR to \fIvarName\fR
+the portion of \fIstring\fR that
+matched \fIexp\fR is replaced with \fIsubSpec\fR.
+If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
+in the substitution with the portion of \fIstring\fR that
+matched \fIexp\fR.
+If \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit
+between 1 and 9, then it is replaced in the substitution with
+the portion of \fIstring\fR that matched the \fIn\fR-th
+parenthesized subexpression of \fIexp\fR.
+Additional backslashes may be used in \fIsubSpec\fR to prevent special
+interpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or
+backslash.
+The use of backslashes in \fIsubSpec\fR tends to interact badly
+with the Tcl parser's use of backslashes, so it's generally
+safest to enclose \fIsubSpec\fR in braces if it includes
+backslashes.
+.LP
+If the initial arguments to \fBregexp\fR start with \fB\-\fR then
+they are treated as switches. The following switches are
+currently supported:
+.TP 10
+\fB\-all\fR
+All ranges in \fIstring\fR that match \fIexp\fR are found and
+substitution is performed for each of these ranges.
+Without this switch only the first
+matching range is found and substituted.
+If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR''
+sequences are handled for each substitution using the information
+from the corresponding match.
+.TP 10
+\fB\-nocase\fR
+Upper-case characters in \fIstring\fR will be converted to lower-case
+before matching against \fIexp\fR; however, substitutions specified
+by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
+.TP 10
+\fB\-\|\-\fR
+Marks the end of switches. The argument following this one will
+be treated as \fIexp\fR even if it starts with a \fB\-\fR.
+.PP
+The command returns a count of the number of matching ranges that
+were found and replaced.
+See the manual entry for \fBregexp\fR for details on the interpretation
+of regular expressions.
+
+.SH KEYWORDS
+match, pattern, regular expression, substitute