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