tcl7.6 User Commands - unknown






NAME

     unknown - Handle attempts to use non-existent commands


SYNOPSIS

     unknown cmdName ?arg arg ...?





DESCRIPTION

     This command is invoked by the Tcl  interpreter  whenever  a
     script  tries  to  invoke a command that doesn't exist.  The
     implementation of  unknown  isn't  part  of  the  Tcl  core;
     instead,  it  is a library procedure defined by default when
     Tcl starts up.  You can  override  the  default  unknown  to
     change its functionality.

     If the Tcl interpreter encounters a command name  for  which
     there  is  not  a  defined  command, then Tcl checks for the
     existence of a command named unknown.  If there is  no  such
     command,  then  the  interpreter  returns  an error.  If the
     unknown command exists, then it is  invoked  with  arguments
     consisting  of  the fully-substituted name and arguments for
     the original non-existent command.  The unknown command typ-
     ically  does  things  like  searching through library direc-
     tories for a command procedure with  the  name  cmdName,  or
     expanding  abbreviated  command  names  to  full-length,  or
     automatically executing unknown commands  as  sub-processes.
     In some cases (such as expanding abbreviations) unknown will
     change the original command slightly and  then  (re-)execute
     it.  The result of the unknown command is used as the result
     for the original non-existent command.

     The default implementation of unknown  behaves  as  follows.
     It  first  calls the auto_load library procedure to load the
     command.  If this succeeds, then it  executes  the  original
     command with its original arguments.  If the auto-load fails
     then unknown calls auto_execok to see if there is an execut-
     able  file  by the name cmd.  If so, it invokes the Tcl exec
     command with cmd and all the  args  as  arguments.   If  cmd
     can't be auto-executed, unknown checks to see if the command
     was invoked at top-level and outside of any script.  If  so,
     then  unknown takes two additional steps.  First, it sees if
     cmd has one of the following three forms:   !!,  !event,  or
     ^old^new?^?.   If  so, then unknown carries out history sub-
     stitution in the same way that  csh  would  for  these  con-
     structs.   Finally, unknown checks to see if cmd is a unique
     abbreviation for an existing Tcl command.  If so, it expands
     the  command name and executes the command with the original
     arguments.  If none of the above efforts has  been  able  to
     execute  the command, unknown generates an error return.  If
     the global variable auto_noload is defined, then  the  auto-
     load step is skipped.  If the global variable auto_noexec is
     defined then the auto-exec step is  skipped.   Under  normal
     circumstances  the  return  value from unknown is the return
     value from the command that was eventually executed.

     Many extensions redefine  the  unknown  command  to  include
     their  own  special  command  processing.   If more than one
     extension tries to do this, however, the  results  conflict.
     The  standard  unknown  command is now set up to handle this
     correctly.  Each extension  can  register  its  own  command
     handler using the following command:
          unknown_handler name command ?arg arg ...?
     Here, name is a symbolic name identifying the handler.   The
     command  string  and  any extra arg arguments are integrated
     into the unknown command.

     Each time an unknown command is  encountered,  the  list  of
     handlers  is  consulted  to determine how to handle the com-
     mand.  If a handler recognizes the command, then  it  should
     load,  define,  or  otherwise handle the command and return.
     Otherwise, it should return "-code  continue",  which  tells
     the  unknown  facility  to  continue  with  another handler.
     Handlers registered first are  consulted  last.   This  way,
     extensions  that  are  loaded later have higher priority for
     handling special cases.

     Usually command is the name of a  handling  procedure.   But
     extra  arg  arguments  can  be specified when the handler is
     registered, and these will be kept as part of  the  handler.
     The  actual  unknown  command and its arguments are appended
     after these when the handler is invoked.



KEYWORDS

     error, non-existent command