'''scanmatch''' is a part of a set of commands (in the [TclX] package) that can be used to look through an open file for regular expressions and, when finding those expressions, cause some action to take place.

    :   '''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 ''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 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 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.




----
'''scanmatch''' is the command which the programmer uses to define the relationship between regular expression and tcl code to execute.
----
See also [scancontext] and [scanfile].
----
!!!!!!
%| [Category Command] | [Category TclX] |%
!!!!!!