distrib/share/tcl/help/tcl/libraries/unknown

   1 NAME
   2        unknown - Handle attempts to use non-existent commands
   3
   4 SYNOPSIS
   5        unknown cmdName ?arg arg ...?
   6
   7
   8 DESCRIPTION
   9        This  command is invoked by the Tcl interpreter whenever a script tries
  10        to invoke a command that doesn't exist.  The default implementation  of
  11        unknown  is  a library procedure defined when Tcl initializes an inter-
  12        preter.  You can override the default unknown to change its functional-
  13        ity.  Note that there is no default implementation of unknown in a safe
  14        interpreter.
  15
  16        If the Tcl interpreter encounters a command name for which there is not
  17        a defined command, then Tcl checks for the existence of a command named
  18        unknown.  If there is no such command, then the interpreter returns  an
  19        error.   If  the  unknown command exists, then it is invoked with argu-
  20        ments consisting of the fully-substituted name and  arguments  for  the
  21        original  non-existent  command.   The  unknown  command typically does
  22        things like searching through library directories for a command  proce-
  23        dure  with  the name cmdName, or expanding abbreviated command names to
  24        full-length, or automatically executing unknown  commands  as  sub-pro-
  25        cesses.   In  some cases (such as expanding abbreviations) unknown will
  26        change the original command slightly and  then  (re-)execute  it.   The
  27        result  of  the  unknown command is used as the result for the original
  28        non-existent command.
  29
  30        The default implementation of unknown behaves  as  follows.   It  first
  31        calls  the  auto_load  library  procedure to load the command.  If this
  32        succeeds, then it executes the original command with its original argu-
  33        ments.  If the auto-load fails then unknown calls auto_execok to see if
  34        there is an executable file by the name cmd.  If so, it invokes the Tcl
  35        exec  command  with cmd and all the args as arguments.  If cmd can't be
  36        auto-executed, unknown checks to see if the command was invoked at top-
  37        level  and  outside of any script.  If so, then unknown takes two addi-
  38        tional steps.  First, it sees if cmd has one  of  the  following  three
  39        forms:  !!,  !event,  or  ^old^new?^?.  If so, then unknown carries out
  40        history substitution in the same way that  csh  would  for  these  con-
  41        structs.   Finally,  unknown checks to see if cmd is a unique abbrevia-
  42        tion for an existing Tcl command.  If so, it expands the  command  name
  43        and  executes  the command with the original arguments.  If none of the
  44        above efforts has been able to execute the command,  unknown  generates
  45        an  error  return.  If the global variable auto_noload is defined, then
  46        the auto-load step is skipped.  If the global variable  auto_noexec  is
  47        defined then the auto-exec step is skipped.  Under normal circumstances
  48        the return value from unknown is the return value from the command that
  49        was eventually executed.
  50
  51 EXAMPLE
  52        Arrange  for  the  unknown command to have its standard behavior except
  53        for first logging the fact that a command was not found:
  54
  55               # Save the original one so we can chain to it
  56               rename unknown _original_unknown
  57
  58               # Provide our own implementation
  59               proc unknown args {
  60                   puts stderr "WARNING: unknown command: $args"
  61                   uplevel 1 [list _original_unknown {expand}$args]
  62               }
  63
  64
  65 SEE ALSO
  66        info(n), proc(n), interp(n), library(n)
  67
  68
  69 KEYWORDS