tcl7.6 User Commands - package






NAME

     package - Facilities for package loading and version control


SYNOPSIS

     package forget package
     package ifneeded package version ?script?
     package names
     package provide package ?version?
     package require ?-exact? package ?version?
     package unknown ?command?
     package vcompare version1 version2
     package versions package
     package vsatisfies version1 version2





DESCRIPTION

     This command keeps a simple database of the packages  avail-
     able for use by the current interpreter and how to load them
     into the interpreter.  It supports multiple versions of each
     package and arranges for the correct version of a package to
     be loaded based on what is needed by the application.   This
     command  also  detects  and  reports version clashes.  Typi-
     cally, only the package require and package provide commands
     are  invoked  in normal Tcl scripts;  the other commands are
     used primarily by system scripts that maintain  the  package
     database.

     The behavior of the package command  is  determined  by  its
     first argument.  The following forms are permitted:

     package forget package
          Removes all information about package from this  inter-
          preter,  including information provided by both package
          ifneeded and package provide.

     package ifneeded package version ?script?
          This command typically appears only  in  system  confi-
          guration  scripts  to  set up the package database.  It
          indicates that a particular  version  of  a  particular
          package  is  available  if needed, and that the package
          can be added to the interpreter  by  executing  script.
          The script is saved in a database for use by subsequent
          package require commands;  typically,  script  sets  up
          auto-loading  for the commands in the package (or calls
          load and/or source directly), then invokes package pro-
          vide  to  indicate  that the package is present.  There
          may be information in the  database  for  several  dif-
          ferent  versions  of a single package.  If the database
          already contains information for package  and  version,
          the  new  script  replaces  the  existing  one.  If the
          script argument is omitted, the current script for ver-
          sion  version  of  package  package  is returned, or an
          empty string if no package ifneeded  command  has  been
          invoked for this package and version.

     package names
          Returns a list of the names  of  all  packages  in  the
          interpreter  for which a version has been provided (via
          package provide) or for which a package ifneeded script
          is  available.   The  order  of elements in the list is
          arbitrary.

     package provide package ?version?
          This command is invoked to indicate that  version  ver-
          sion  of  package  package is now present in the inter-
          preter.  It is typically invoked once  as  part  of  an
          ifneeded  script,  and again by the package itself when
          it is finally loaded.  An error occurs if  a  different
          version  of  package  has  been  provided by a previous
          package provide command.  If the  version  argument  is
          omitted,  then  the  command returns the version number
          that is currently provided, or an empty  string  if  no
          package provide command has been invoked for package in
          this interpreter.

     package require ?-exact? package ?version?
          This command is typically  invoked  by  Tcl  code  that
          wishes  to  use  a  particular  version of a particular
          package.   The  arguments  indicate  which  package  is
          wanted, and the command ensures that a suitable version
          of the package is loaded into the interpreter.  If  the
          command succeeds, it returns the version number that is
          loaded;  otherwise it generates an error.  If both  the
          - exact  switch  and the version argument are specified
          then only the given version is acceptable.  If  - exact
          is  omitted  but  version  is  specified, then versions
          later than version are also acceptable as long as  they
          have the same major version number as version.  If both
          -exact and version are omitted then any version whatso-
          ever  is  acceptable.   If  a  version  of  package has
          already been provided (by invoking the package  provide
          command), then its version number must satisfy the cri-
          teria given by - exact  and  version  and  the  command
          returns  immediately.   Otherwise, the command searches
          the database of information provided by previous  pack-
          age  ifneeded  commands to see if an acceptable version
          of the package is available.  If so, the script for the
          highest  acceptable  version number is invoked; it must
          do whatever is necessary to load the package, including
          calling  package provide for the package.  If the pack-
          age ifneeded database does not  contain  an  acceptable
          version  of  the  package and a package unknown command
          has been specified for the interpreter then  that  com-
          mand  is  invoked;  when it completes, Tcl checks again
          to see if the package is now provided or if there is  a
          package  ifneeded script for it.  If all of these steps
          fail to provide an acceptable version of  the  package,
          then the command returns an error.

     package unknown ?command?
          This command supplies  a  ``last  resort''  command  to
          invoke during package require if no suitable version of
          a package can be found in the  package  ifneeded  data-
          base.  If the command argument is supplied, it contains
          the first part of  a  command;   when  the  command  is
          invoked  during  a package require command, Tcl appends
          two additional arguments  giving  the  desired  package
          name  and  version.  For example, if command is foo bar
          and later the  command  package  require  test  2.4  is
          invoked, then Tcl will execute the command foo bar test
          2.4 to load the package.  If no version number is  sup-
          plied  to the package require command, then the version
          argument for the  invoked  command  will  be  an  empty
          string.   If  the  package  unknown  command is invoked
          without a command argument, then  the  current  package
          unknown script is returned, or an empty string if there
          is none.  If command is specified as an  empty  string,
          then  the current package unknown script is removed, if
          there is one.

     package vcompare version1 version2
          Compares the two version numbers given by version1  and
          version2.  Returns -1 if version1 is an earlier version
          than version2, 0 if they are equal, and 1  if  version1
          is later than version2.

     package versions package
          Returns a list of all the version  numbers  of  package
          for  which  information  has  been  provided by package
          ifneeded commands.

     package vsatisfies version1 version2
          Returns 1 if scripts written  for  version2  will  work
          unchanged  with  version1 (i.e. version1 is equal to or
          greater than version2 and they both have the same major
          version number), 0 otherwise.



VERSION NUMBERS

     Version numbers consist  of  one  or  more  decimal  numbers
     separated  by  dots,  such  as  2 or 1.162 or 3.1.13.1.  The
     first number is called the  major  version  number.   Larger
     numbers  correspond  to  later  versions  of a package, with
     leftmost numbers having greater significance.  For  example,
     version  2.1  is  later  than 1.3 and version 3.4.6 is later
     than 3.3.5.  Missing fields are equivalent to zeroes:   ver-
     sion  1.3 is the same as version 1.3.0 and 1.3.0.0, so it is
     earlier than 1.3.1 or 1.3.0.2.  A later  version  number  is
     assumed  to  be  upwards  compatible with an earlier version
     number as long as both versions have the same major  version
     number.  For example, Tcl scripts written for version 2.3 of
     a package should work unchanged under versions  2.3.2,  2.4,
     and  2.5.1.   Changes  in  the  major version number signify
     incompatible changes:  if code is written to use version 2.1
     of  a  package, it is not guaranteed to work unmodified with
     either version 1.7.3 or version 3.1.



PACKAGE INDICES

     The recommended way to use packages  in  Tcl  is  to  invoke
     package require and package provide commands in scripts, and
     use the procedure pkg_mkIndex to create package index files.
     Once you've done this, packages will be loaded automatically
     in response to package require commands.  See the documenta-
     tion for pkg_mkIndex for details.



KEYWORDS

     package, version