Specifies Tcl commands, to be evaluated when regexp is matched by a
scanfile command. The match is added to the scan context specified by
contexthandle. Any number of match statements may be
specified for a given 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 scan context.
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
matchInfo before the match code is
executed, a subsequent global will override the local variable).
The following array entries are available:
matchInfo(line)
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(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)
The characters matching the first parenthesized subexpression.
The second will be contained in submatch1, etc.
matchInfo(subindex0)
The 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
pattern.
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.