scanmatch ?-nocase? contexthandle ?regexp? commands
Specify Tcl commands, to be evaluated when regexp
is matched by a scanfile command. The match is
added to the scan context specified by contex-
thandle. Any number of match statements may be
specified for a give context. Regexp is a regular
expression (see the regexp command). If -nocase is
specified as the first argument, the pattern is
matched regardless of alphabetic case.
If regexp is not specified, then a default match is
specified for the scan context. The default match
will be executed when a line of the file does not
match any of the regular expressions in the current
scancontext.
The array matchInfo is available to the Tcl code
that is executed when an expression matches (or
defaults). It contains information about the file
being scanned and where within it the expression
was matched.
matchInfo is local to the top level of the match
command unless declared global at that level by the
Tcl global command. If it is to be used as a
global, it must be declared global before scanfile
is called (since scanfile sets the matchInfo before
the match code is executed, a subsequent global
will override the local variable). The following
array entries are available:
matchInfo(line)
Contains the text of the line of the file that
was matched.
matchInfo(offset)
The byte offset into the file of the first
character of the line that was matched.
matchInfo(linenum)
The line number of the line that was matched.
This is relative to the first line scanned,
which is usually, but not necessarily, the
first line of the file. The first line is
line number one.
matchInfo(context)
The context handle of the context that this
scan is associated with.
matchInfo(handle)
The file id (handle) of the file currently
being scanned.
matchInfo(copyHandle)
The file id (handle) of the file specified by
the -copyfile option. The element does not
exist if -copyfile was not specified.
matchInfo(submatch0)
Will contain the characters matching the first
parenthesized subexpression. The second will
be contained in submatch1, etc.
matchInfo(subindex0)
Will contain the a list of the starting and
ending indices of the string matching the
first parenthesized subexpression. The second
will be contained in subindex1, etc.
All scanmatch patterns that match a line will be processed
in the order in which their specifications were added to
the scan context. The remainder of the scanmatch pattern-
command pairs may be skipped for a file line if a continue
is executed by the Tcl code of a preceding, matched pat-
tern.
If a return is executed in the body of the match command,
the scanfile command currently in progress returns, with
the value passed to return as its return value.
This command is provided by Extended Tcl.