Nre Package Commands


NAME

nresub - Perform substitutions based on regular expression pattern matching

SYNOPSIS

package require nre ?3.0?
nresub ?switches? exp string subSpec varName
nresub -eval ?switches? exp string subSpec varName evalName

DESCRIPTION

This command matches the regular expression exp against string, and it copies string to the variable whose name is given by varName. If there is a match, then while copying string to varName the portion of string that matched exp is replaced with subSpec. Instead of using the standard regular expression package it uses the package described in the nrematch man page.

If the initial arguments to nresub start with - then they are treated as switches. The following switches are currently 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 the subSpec expansion is handled for each substitution using the information from the corresponding match.

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

-eval
Evaluate subSpec for each successful match of exp and use the result of evaluation as the string to replace the text matched by the regular expression. The text matched by the regular expression can be accessed from within the subSpec by extracting it from the evalName variable. nresub sets the evalName variable to a value after each successful match of exp. If the exp has no subexpression then the value is a simple string contained the matched text. Otherwise the value is a list whose first element is a string containing the portion of string that matched exp. Additional list elements correspond to the portion of string that matched a parenthesized subexpression of exp. Note that if -eval is used then the subSpec is just normal Tcl code; the special nresub characters ``&'' and ``\n'' are treated normally.If return is executed during the evaluation then the returned value used to replace the text matched by the regular expression.If break is executed during the evaluation then nresub acts as if the current match did not happen and that no more matches occur in string. If continue is executed during the evaluation then nresub acts as if the current match did not happen and continues on looking for matches in the rest of string. If an error occurs during the evaluation then nresub does not set varName. The list value of evalName will only contain as many elements as the exp has subexpressions. Note that if the exp has more than nine subexpressions then -eval is the only way to access them from the subSpec.

--
Marks the end of switches. The argument following 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 man page for nrematch for details on the interpretation of regular expressions.

SUBSPEC SYNTAX

If the -eval switch is used then the subSpec is evaluated as normal Tcl code. See the description of the -eval switch for details. Otherwise if subSpec 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 parenthesized 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.

KEYWORDS

match, nre, pattern, regular expression, substitute

Last change: 3.0

[ nre3.0 ]

Copyright © 1997 Darrel Schneider.