116 lines
5.9 KiB
HTML
116 lines
5.9 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - regsub manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="regsub.htm#M2" NAME="L968">NAME</A>
|
|
<DL><DD>regsub - Perform substitutions based on regular expression pattern matching</DL>
|
|
<DD><A HREF="regsub.htm#M3" NAME="L969">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>regsub </B>?<I>switches</I>? <I>exp string subSpec varName</I>
|
|
</DL>
|
|
<DD><A HREF="regsub.htm#M4" NAME="L970">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="regsub.htm#M5" NAME="L971"><B>-all</B></A>
|
|
<DD><A HREF="regsub.htm#M6" NAME="L972"><B>-expanded</B></A>
|
|
<DD><A HREF="regsub.htm#M7" NAME="L973"><B>-line</B></A>
|
|
<DD><A HREF="regsub.htm#M8" NAME="L974"><B>-linestop</B></A>
|
|
<DD><A HREF="regsub.htm#M9" NAME="L975"><B>-lineanchor</B></A>
|
|
<DD><A HREF="regsub.htm#M10" NAME="L976"><B>-nocase</B></A>
|
|
<DD><A HREF="regsub.htm#M11" NAME="L977"><B>-start</B> <I>index</I></A>
|
|
<DD><A HREF="regsub.htm#M12" NAME="L978"><B>- -</B></A>
|
|
</DL>
|
|
<DD><A HREF="regsub.htm#M13" NAME="L979">SEE ALSO</A>
|
|
<DD><A HREF="regsub.htm#M14" NAME="L980">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
regsub - Perform substitutions based on regular expression pattern matching
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>regsub </B>?<I>switches</I>? <I>exp string subSpec varName</I><BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command matches the regular expression <I>exp</I> against
|
|
<I>string</I>,
|
|
and it copies <I>string</I> to the variable whose name is
|
|
given by <I>varName</I>.
|
|
(Regular expression matching is described in the <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
|
reference page.)
|
|
If there is a match, then while copying <I>string</I> to <I>varName</I>
|
|
the portion of <I>string</I> that
|
|
matched <I>exp</I> is replaced with <I>subSpec</I>.
|
|
If <I>subSpec</I> contains a ``&'' or ``\0'', then it is replaced
|
|
in the substitution with the portion of <I>string</I> that
|
|
matched <I>exp</I>.
|
|
If <I>subSpec</I> contains a ``\<I>n</I>'', where <I>n</I> is a digit
|
|
between 1 and 9, then it is replaced in the substitution with
|
|
the portion of <I>string</I> that matched the <I>n</I>-th
|
|
parenthesized subexpression of <I>exp</I>.
|
|
Additional backslashes may be used in <I>subSpec</I> to prevent special
|
|
interpretation of ``&'' or ``\0'' or ``\<I>n</I>'' or
|
|
backslash.
|
|
The use of backslashes in <I>subSpec</I> tends to interact badly
|
|
with the Tcl parser's use of backslashes, so it's generally
|
|
safest to enclose <I>subSpec</I> in braces if it includes
|
|
backslashes.
|
|
<P>
|
|
If the initial arguments to <B><A HREF="../TkCmd/regexp.htm">regexp</A></B> start with <B>-</B> then
|
|
they are treated as switches. The following switches are
|
|
currently supported:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>-all</B></A><DD>
|
|
All ranges in <I>string</I> that match <I>exp</I> are found and
|
|
substitution is performed for each of these ranges.
|
|
Without this switch only the first
|
|
matching range is found and substituted.
|
|
If <B>-all</B> is specified, then ``&'' and ``\<I>n</I>''
|
|
sequences are handled for each substitution using the information
|
|
from the corresponding match.
|
|
<P><DT><A NAME="M6"><B>-expanded</B></A><DD>
|
|
Enables use of the expanded regular expression syntax where
|
|
whitespace and comments are ignored. This is the same as specifying
|
|
the <B>(?x)</B> embedded option (see METASYNTAX, below).
|
|
<P><DT><A NAME="M7"><B>-line</B></A><DD>
|
|
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 <B>-linestop</B> and <B>-lineanchor</B>, or the
|
|
<B>(?n)</B> embedded option (see METASYNTAX, below).
|
|
<P><DT><A NAME="M8"><B>-linestop</B></A><DD>
|
|
Changes the behavior of `[^' bracket expressions and `.' so that they
|
|
stop at newlines. This is the same as specifying the <B>(?p)</B>
|
|
embedded option (see METASYNTAX, below).
|
|
<P><DT><A NAME="M9"><B>-lineanchor</B></A><DD>
|
|
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 <B>(?w)</B> embedded option (see METASYNTAX, below).
|
|
<P><DT><A NAME="M10"><B>-nocase</B></A><DD>
|
|
Upper-case characters in <I>string</I> will be converted to lower-case
|
|
before matching against <I>exp</I>; however, substitutions specified
|
|
by <I>subSpec</I> use the original unconverted form of <I>string</I>.
|
|
<P><DT><A NAME="M11"><B>-start</B> <I>index</I></A><DD>
|
|
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 <I>index</I>.
|
|
<I>index</I> will be constrained to the bounds of the input string.
|
|
<P><DT><A NAME="M12"><B>- -</B></A><DD>
|
|
Marks the end of switches. The argument following this one will
|
|
be treated as <I>exp</I> even if it starts with a <B>-</B>.
|
|
<P></DL>
|
|
<P>
|
|
The command returns a count of the number of matching ranges that
|
|
were found and replaced.
|
|
See the manual entry for <B><A HREF="../TkCmd/regexp.htm">regexp</A></B> for details on the interpretation
|
|
of regular expressions.
|
|
|
|
<H3><A NAME="M13">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/regexp.htm">regexp</A></B>, <B><A HREF="../TkCmd/re_syntax.htm">re_syntax</A></B>
|
|
<H3><A NAME="M14">KEYWORDS</A></H3>
|
|
<A href="../Keywords/M.htm#match">match</A>, <A href="../Keywords/P.htm#pattern">pattern</A>, <A href="../Keywords/R.htm#regular expression">regular expression</A>, <A href="../Keywords/S.htm#substitute">substitute</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 2000 Scriptics Corporation.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|