SimplePackage v1.0 

 The Simple Development Library packages handling 

Project: the Simple Development Library.

Table of contents

1. Package description
   1.1 Overview
   1.2 Usage
   1.3 Examples
   1.4 History
   1.5 Copyright
2. Package public API
   2.1 Types
      2.1.1 package
      2.1.2 version
      2.1.3 nameandversion
      2.1.4 packagerequisite
   2.2 Options
   2.3 Namespaces
   2.4 Commands
      2.4.1 ::Simple::Package::cget
      2.4.2 ::Simple::Package::configure
      2.4.3 ::Simple::Package::declare package version ?-requisites packagerequisite-list? ?-namespaces namespace-list? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-install script? ?-uninstall script? ?-firsttimeinstall script?
      2.4.4 ::Simple::Package::forget package ?version?
      2.4.5 ::Simple::Package::import package namespace
      2.4.6 ::Simple::Package::information aliases package ?version?
      2.4.7 ::Simple::Package::information aliasesall package ?version?
      2.4.8 ::Simple::Package::information api package ?version?
      2.4.9 ::Simple::Package::information classes package ?version?
      2.4.10 ::Simple::Package::information collisions package ?namespace?
      2.4.11 ::Simple::Package::information commands ?-noclasses? package ?version?
      2.4.12 ::Simple::Package::information declared ?pattern?
      2.4.13 ::Simple::Package::information declaredexportedcommands package ?version?
      2.4.14 ::Simple::Package::information errors package ?version?
      2.4.15 ::Simple::Package::information exportedcommands package ?version?
      2.4.16 ::Simple::Package::information exportedcommandsall package ?version?
      2.4.17 ::Simple::Package::information importedinto package ?version?
      2.4.18 ::Simple::Package::information install package ?version?
      2.4.19 ::Simple::Package::information installed ?pattern?
      2.4.20 ::Simple::Package::information known ?pattern?
      2.4.21 ::Simple::Package::information metadata package ?version?
      2.4.22 ::Simple::Package::information namespaces package ?version?
      2.4.23 ::Simple::Package::information optionchoices package version flag
      2.4.24 ::Simple::Package::information optiondescription package version flag
      2.4.25 ::Simple::Package::information options package ?version?
      2.4.26 ::Simple::Package::information optiontype package version flag
      2.4.27 ::Simple::Package::information optionvalue package version flag
      2.4.28 ::Simple::Package::information packagealias alias
      2.4.29 ::Simple::Package::information packageclass class
      2.4.30 ::Simple::Package::information packagecommand command
      2.4.31 ::Simple::Package::information packagenamespace namespace
      2.4.32 ::Simple::Package::information privatecommands ?-noclasses? package ?version?
      2.4.33 ::Simple::Package::information publiccommands ?-noclasses? package ?version?
      2.4.34 ::Simple::Package::information required package ?version?
      2.4.35 ::Simple::Package::information requiredall package ?version?
      2.4.36 ::Simple::Package::information requiredby package ?version?
      2.4.37 ::Simple::Package::information requisites package ?version?
      2.4.38 ::Simple::Package::information state package ?version?
      2.4.39 ::Simple::Package::information types package ?version?
      2.4.40 ::Simple::Package::information uninstall package ?version?
      2.4.41 ::Simple::Package::information uninstalled ?pattern?
      2.4.42 ::Simple::Package::information variables package ?version?
      2.4.43 ::Simple::Package::install package
      2.4.44 ::Simple::Package::require ?-exact? package ?version?
      2.4.45 ::Simple::Package::require-and-install ?-exact? package ?version?
      2.4.46 ::Simple::Package::resync
      2.4.47 ::Simple::Package::undeclare package
      2.4.48 ::Simple::Package::unimport package namespace
      2.4.49 ::Simple::Package::uninstall package
      2.4.50 ::Simple::Package::uninstall-and-undeclare package
   2.5 Errors
      2.5.1 ::Simple::Package::NAMESPACE-OR-CLASS-OWNED
      2.5.2 ::Simple::Package::NAMESPACE-OR-CLASS-NOT-OWNED
      2.5.3 ::Simple::Package::NAMESPACE-OR-CLASS-NOT-OWNED-NOR-REQUISITES
      2.5.4 ::Simple::Package::UNDECLARED
      2.5.5 ::Simple::Package::UNINSTALLED
      2.5.6 ::Simple::Package::INSTALLED
      2.5.7 ::Simple::Package::ERROR-EVAL-SCRIPT
      2.5.8 ::Simple::Package::ALREADY-DECLARED
      2.5.9 ::Simple::Package::COLLISION
      2.5.10 ::Simple::Package::COLLISION-BETWEEN-PACKAGES
      2.5.11 ::Simple::Package::ALREADY-IMPORTED
      2.5.12 ::Simple::Package::NOT-IMPORTED
      2.5.13 ::Simple::Package::EMPTY-NAMESPACES-LIST
3. Package further information
   3.1 Todo
4. Package command details
   4.1 ::Simple::Package::cget
      4.1.1 Command description
      4.1.2 Command public API
   4.2 ::Simple::Package::configure
      4.2.1 Command description
      4.2.2 Command public API
   4.3 ::Simple::Package::declare package version ?-requisites packagerequisite-list? ?-namespaces namespace-list? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-install script? ?-uninstall script? ?-firsttimeinstall script?
      4.3.1 Command description
         4.3.1.1 Overview
      4.3.2 Command public API
      4.3.3 Command further information
         4.3.3.1 Remarks
   4.4 ::Simple::Package::forget package ?version?
      4.4.1 Command description
         4.4.1.1 Overview
      4.4.2 Command public API
   4.5 ::Simple::Package::import package namespace
      4.5.1 Command description
         4.5.1.1 Overview
      4.5.2 Command public API
   4.6 ::Simple::Package::information aliases package ?version?
      4.6.1 Command description
         4.6.1.1 Overview
      4.6.2 Command public API
      4.6.3 Command further information
         4.6.3.1 References
         4.6.3.2 Remarks
   4.7 ::Simple::Package::information aliasesall package ?version?
      4.7.1 Command description
         4.7.1.1 Overview
      4.7.2 Command public API
      4.7.3 Command further information
         4.7.3.1 References
         4.7.3.2 Remarks
   4.8 ::Simple::Package::information api package ?version?
      4.8.1 Command description
         4.8.1.1 Overview
      4.8.2 Command public API
      4.8.3 Command further information
         4.8.3.1 References
         4.8.3.2 Remarks
   4.9 ::Simple::Package::information classes package ?version?
      4.9.1 Command description
      4.9.2 Command public API
      4.9.3 Command further information
         4.9.3.1 References
         4.9.3.2 Remarks
   4.10 ::Simple::Package::information collisions package ?namespace?
      4.10.1 Command description
         4.10.1.1 Overview
      4.10.2 Command public API
   4.11 ::Simple::Package::information commands ?-noclasses? package ?version?
      4.11.1 Command description
         4.11.1.1 Overview
      4.11.2 Command public API
      4.11.3 Command further information
         4.11.3.1 References
         4.11.3.2 Remarks
   4.12 ::Simple::Package::information declared ?pattern?
      4.12.1 Command description
         4.12.1.1 Overview
      4.12.2 Command public API
      4.12.3 Command further information
         4.12.3.1 Remarks
   4.13 ::Simple::Package::information declaredexportedcommands package ?version?
      4.13.1 Command description
         4.13.1.1 Overview
      4.13.2 Command public API
      4.13.3 Command further information
         4.13.3.1 References
         4.13.3.2 Remarks
   4.14 ::Simple::Package::information errors package ?version?
      4.14.1 Command description
      4.14.2 Command public API
      4.14.3 Command further information
         4.14.3.1 References
         4.14.3.2 Remarks
   4.15 ::Simple::Package::information exportedcommands package ?version?
      4.15.1 Command description
         4.15.1.1 Overview
      4.15.2 Command public API
      4.15.3 Command further information
         4.15.3.1 References
         4.15.3.2 Remarks
   4.16 ::Simple::Package::information exportedcommandsall package ?version?
      4.16.1 Command description
         4.16.1.1 Overview
      4.16.2 Command public API
      4.16.3 Command further information
         4.16.3.1 References
         4.16.3.2 Remarks
   4.17 ::Simple::Package::information importedinto package ?version?
      4.17.1 Command description
         4.17.1.1 Overview
      4.17.2 Command public API
   4.18 ::Simple::Package::information install package ?version?
      4.18.1 Command description
      4.18.2 Command public API
   4.19 ::Simple::Package::information installed ?pattern?
      4.19.1 Command description
         4.19.1.1 Overview
      4.19.2 Command public API
      4.19.3 Command further information
         4.19.3.1 Remarks
   4.20 ::Simple::Package::information known ?pattern?
      4.20.1 Command description
         4.20.1.1 Overview
      4.20.2 Command public API
      4.20.3 Command further information
         4.20.3.1 Remarks
   4.21 ::Simple::Package::information metadata package ?version?
      4.21.1 Command description
         4.21.1.1 Overview
      4.21.2 Command public API
   4.22 ::Simple::Package::information namespaces package ?version?
      4.22.1 Command description
      4.22.2 Command public API
   4.23 ::Simple::Package::information optionchoices package version flag
      4.23.1 Command description
         4.23.1.1 Overview
      4.23.2 Command public API
   4.24 ::Simple::Package::information optiondescription package version flag
      4.24.1 Command description
         4.24.1.1 Overview
      4.24.2 Command public API
   4.25 ::Simple::Package::information options package ?version?
      4.25.1 Command description
      4.25.2 Command public API
      4.25.3 Command further information
         4.25.3.1 References
         4.25.3.2 Remarks
   4.26 ::Simple::Package::information optiontype package version flag
      4.26.1 Command description
         4.26.1.1 Overview
      4.26.2 Command public API
   4.27 ::Simple::Package::information optionvalue package version flag
      4.27.1 Command description
         4.27.1.1 Overview
      4.27.2 Command public API
   4.28 ::Simple::Package::information packagealias alias
      4.28.1 Command description
         4.28.1.1 Overview
      4.28.2 Command public API
      4.28.3 Command further information
         4.28.3.1 Remarks
   4.29 ::Simple::Package::information packageclass class
      4.29.1 Command description
         4.29.1.1 Overview
      4.29.2 Command public API
   4.30 ::Simple::Package::information packagecommand command
      4.30.1 Command description
         4.30.1.1 Overview
      4.30.2 Command public API
   4.31 ::Simple::Package::information packagenamespace namespace
      4.31.1 Command description
         4.31.1.1 Overview
      4.31.2 Command public API
   4.32 ::Simple::Package::information privatecommands ?-noclasses? package ?version?
      4.32.1 Command description
         4.32.1.1 Overview
      4.32.2 Command public API
      4.32.3 Command further information
         4.32.3.1 References
         4.32.3.2 Remarks
   4.33 ::Simple::Package::information publiccommands ?-noclasses? package ?version?
      4.33.1 Command description
      4.33.2 Command public API
      4.33.3 Command further information
         4.33.3.1 References
         4.33.3.2 Remarks
   4.34 ::Simple::Package::information required package ?version?
      4.34.1 Command description
      4.34.2 Command public API
   4.35 ::Simple::Package::information requiredall package ?version?
      4.35.1 Command description
         4.35.1.1 Overview
      4.35.2 Command public API
      4.35.3 Command further information
         4.35.3.1 References
   4.36 ::Simple::Package::information requiredby package ?version?
      4.36.1 Command description
      4.36.2 Command public API
      4.36.3 Command further information
         4.36.3.1 Remarks
   4.37 ::Simple::Package::information requisites package ?version?
      4.37.1 Command description
      4.37.2 Command public API
   4.38 ::Simple::Package::information state package ?version?
      4.38.1 Command description
         4.38.1.1 Overview
      4.38.2 Command public API
   4.39 ::Simple::Package::information types package ?version?
      4.39.1 Command description
      4.39.2 Command public API
      4.39.3 Command further information
         4.39.3.1 References
         4.39.3.2 Remarks
   4.40 ::Simple::Package::information uninstall package ?version?
      4.40.1 Command description
      4.40.2 Command public API
   4.41 ::Simple::Package::information uninstalled ?pattern?
      4.41.1 Command description
         4.41.1.1 Overview
      4.41.2 Command public API
      4.41.3 Command further information
         4.41.3.1 Remarks
   4.42 ::Simple::Package::information variables package ?version?
      4.42.1 Command description
      4.42.2 Command public API
      4.42.3 Command further information
         4.42.3.1 References
         4.42.3.2 Remarks
   4.43 ::Simple::Package::install package
      4.43.1 Command description
         4.43.1.1 Overview
      4.43.2 Command public API
   4.44 ::Simple::Package::require ?-exact? package ?version?
      4.44.1 Command description
         4.44.1.1 Overview
      4.44.2 Command public API
   4.45 ::Simple::Package::require-and-install ?-exact? package ?version?
      4.45.1 Command description
         4.45.1.1 Overview
      4.45.2 Command public API
   4.46 ::Simple::Package::resync
      4.46.1 Command description
         4.46.1.1 Overview
         4.46.1.2 History
      4.46.2 Command public API
   4.47 ::Simple::Package::undeclare package
      4.47.1 Command description
         4.47.1.1 Overview
      4.47.2 Command public API
      4.47.3 Command further information
         4.47.3.1 Remarks
   4.48 ::Simple::Package::unimport package namespace
      4.48.1 Command description
         4.48.1.1 Overview
      4.48.2 Command public API
   4.49 ::Simple::Package::uninstall package
      4.49.1 Command description
         4.49.1.1 Overview
      4.49.2 Command public API
      4.49.3 Command further information
         4.49.3.1 Remarks
   4.50 ::Simple::Package::uninstall-and-undeclare package
      4.50.1 Command description
         4.50.1.1 Overview
      4.50.2 Command public API
      4.50.3 Command further information
         4.50.3.1 Remarks

1. Package description

Synopsis: the Simple Development Library packages handling.

Keywords: package, alias, export, import, install, load, require and unknown.

1.1 Overview

This package improves the Tcl facilities for package loading and version control. It works by each package declaring itself. This declaration includes such information as the namespaces used by the package, its exported commands and aliases or its package requisites, so that this information can not only be queried later, but also used for other purposes. As an example, it is possible to obtain the list of exported commands from a package plus those exported from all packages it may require, recursively, before actually modifying any namespace not owned by it.

This package also augments unknown in order to autoload extra packages. An extra package works as a companion to a regular package. It is intended to contain the package functionality less frequently used. That way, when an application requires a package, only the regular package is actually loaded, leaving the functionality in the extra package to be autoloaded in case it becomes necessary. Nevertheless, extra packages live independently of the package they extend. For example, extra packages are not uninstalled when the non-extra package is uninstalled. The ::Simple::Package::information * commands do not, in general, return information about items in extra packages. Exceptions to this rule are the information commands which return a current snapshot of the package namespaces such as ::Simple::Package::information commands, as the extra package may add commands to those namespaces. Another exception is the ::Simple::Package::information api which provides a package full API, including its public items in its extra package, if any.

1.2 Usage

Packages may be either known or unknown to Tcl, depending on whether or not package ifneeded has been invoked for the package. In turn, known packages may be either available or provided, depending on whether or not package provide has been invoked for them. In turn, provided packages may be either declared or undeclared, depending on whether ::Simple::Package::declare (or, alternatively, declare-package if SimpleDeclare is used) have been invoked for them. Finally, all undeclared packages are considered to be installed (that is, ready to be used) but declared packages may be either installed or uninstalled, depending on whether or not ::Simple::Package::install has been invoked for them. The following drawing sketches the situation:

It is possible to get the list of packages in those states which have an asterisk by its box in the drawing above (known, declared, uninstalled and installed) via the ::Simple::Package::information state commands where state is the corresponding state.

Each package can be considered to be in one of the four main states depicted with double-line boxes in the drawing above (unknown, available, declared or installed). The ::Simple::Package::information state command returns the state of a package among these main four.

At the beginning, all packages are unknown. Where Tcl evaluates all of the pkgIndex.tcl files in the auto_path directories, package ifneeded is typically executed for some packages which become available. These packages can then be required with ::Simple::Package::require or package require, which should invoke package provide so that the packages become provided.

During this process, ::Simple::Package::declare can be either invoked or not. In the later case, the package is considered installed, although a full install might require manually importing the package namespaces via namespace import. In the former case, the package becomes declared, state in which many package details can be queried (see below) before actually installing the package using ::Simple::Package::install. With this, the declared package finally reaches the installed state.

Another possibility is to use ::Simple::Package::require-and-install which requires the package and, if declared, automatically installs it.

It is also possible to go backwards in the above described route by using ::Simple::Package::uninstall, ::Simple::Package::undeclare and ::Simple::Package::forget or package forget (or substituting the first two calls by ::Simple::Package::uninstall-and-undeclare). The following drawings sketches these transitions. In the drawings the prefix ::Simple::Package:: has been abbreviated to ::S::P::. First, for undeclared (regular Tcl) packages:

Second, for packages declared using The Simple Development Library:

Notice that in the case of undeclared (regular Tcl) packages, a full installation might require manually importing the package namespaces via namespace import and, conversely, a full uninstallation might require manually forgetting the package namespaces via namespace forget. This is not necessary for declared packages as the installation and uninstallation procedures take care of that.

The purpose of having declared and installed states is twofold. First, it is possible to require a package and get information about it without any effect in namespaces not owned by it until it is installed. Second, it is possible to reset the status of a package to its default configuration by uninstalling and reinstalling it.

The ::Simple::Package::information command provides a myriad of subcommands to query information about declared packages.

Notice that it is very easy to convert regular Tcl packages into declared ones, thus taking benefit of all the functionality provided by SimplePackage, by simply adding a proper call to ::Simple::Package::declare, for example in the corresponding entry of the pkgIndex.tcl file.

Upon requiring a package which gets declared in the process, all its required packages are also required, recursively. Something similar happens when installing a declared package, which results in all its required packages being installed as well, recursively. Notice, though, that the contrary is not true; that is, uninstalling a package does not uninstall any other package.

After a package has been installed, it is possible to import all its exported commands into another namespace via ::Simple::Package::import and unimport them via ::Simple::Package::unimport.

Finall, use ::Simple::Package::resync to resynchronize the information about available packages.

1.3 Examples

1.4 History

Date Reason
23-apr-2000 First public release, version 0.2
10-sep-2001 Second public release, version 0.4
23-apr-2002 "Extra" packages functionality, version 0.4.1
17-feb-2003 Third public release, version 0.5
29-mar-2003 Extra package, version 0.5.1
18-apr-2004 Alias can be qualified, version 0.5.2
22-jun-2005 The Simple Development Library version 1.0

1.5 Copyright

Copyright (C) 1999-2005, Juan C. Gil (jgil@gmv.es).

2. Package public API

Paradigm: procedural.

Requisites: SimpleError 1.0.

2.1 Types

2.1.1 package

Description: package name: Tcl, ...

2.1.2 version

Description: package version: 1.1, ...

2.1.3 nameandversion

Description: package name and version as {package version}: {Tcl 8.4}.

2.1.4 packagerequisite

Description: package requisite as {?-exact? package ?requisiteVersion?}: Tcl 8, -exact Tk 8.3, ...

2.2 Options

None.

2.3 Namespaces

  1. ::Simple::Package

  2. ::Simple::Package::Priv

  3. ::

2.4 Commands

2.4.1 ::Simple::Package::cget

Synopsis: gets the package options.

Details: see section 4.1.

2.4.2 ::Simple::Package::configure

Synopsis: configures the package options.

Details: see section 4.2.

2.4.3 ::Simple::Package::declare package version ?-requisites packagerequisite-list? ?-namespaces namespace-list? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-install script? ?-uninstall script? ?-firsttimeinstall script?

Synopsis: declares a package.

Details: see section 4.3.

2.4.4 ::Simple::Package::forget package ?version?

Synopsis: forgets a package version.

Details: see section 4.4.

2.4.5 ::Simple::Package::import package namespace

Synopsis: imports a package exported commands into a namespace.

Details: see section 4.5.

2.4.6 ::Simple::Package::information aliases package ?version?

Synopsis: returns a declared package list of aliases.

Details: see section 4.6.

2.4.7 ::Simple::Package::information aliasesall package ?version?

Synopsis: returns a declared package full list of aliases.

Details: see section 4.7.

2.4.8 ::Simple::Package::information api package ?version?

Synopsis: returns a package public API signatures.

Details: see section 4.8.

2.4.9 ::Simple::Package::information classes package ?version?

Synopsis: returns a declared package list of classes.

Details: see section 4.9.

2.4.10 ::Simple::Package::information collisions package ?namespace?

Synopsis: returns the list of collisions upon importing a declared package.

Details: see section 4.10.

2.4.11 ::Simple::Package::information commands ?-noclasses? package ?version?

Synopsis: returns a declared package current list of public and exported commands.

Details: see section 4.11.

2.4.12 ::Simple::Package::information declared ?pattern?

Synopsis: returns the list of declared packages.

Details: see section 4.12.

2.4.13 ::Simple::Package::information declaredexportedcommands package ?version?

Synopsis: returns a declared package declared list of exported commands.

Details: see section 4.13.

2.4.14 ::Simple::Package::information errors package ?version?

Synopsis: returns a declared package list of errors.

Details: see section 4.14.

2.4.15 ::Simple::Package::information exportedcommands package ?version?

Synopsis: returns a declared package current list of exported commands.

Details: see section 4.15.

2.4.16 ::Simple::Package::information exportedcommandsall package ?version?

Synopsis: returns a declared package current full list of exported commands.

Details: see section 4.16.

2.4.17 ::Simple::Package::information importedinto package ?version?

Synopsis: returns the namespaces into which a declared package has been imported.

Details: see section 4.17.

2.4.18 ::Simple::Package::information install package ?version?

Synopsis: returns a declared package install script.

Details: see section 4.18.

2.4.19 ::Simple::Package::information installed ?pattern?

Synopsis: returns the list of installed packages.

Details: see section 4.19.

2.4.20 ::Simple::Package::information known ?pattern?

Synopsis: returns the list of known packages.

Details: see section 4.20.

2.4.21 ::Simple::Package::information metadata package ?version?

Synopsis: returns a declared package metadata.

Details: see section 4.21.

2.4.22 ::Simple::Package::information namespaces package ?version?

Synopsis: returns a declared package namespaces.

Details: see section 4.22.

2.4.23 ::Simple::Package::information optionchoices package version flag

Synopsis: returns a declared package option choices.

Details: see section 4.23.

2.4.24 ::Simple::Package::information optiondescription package version flag

Synopsis: returns a declared package option description.

Details: see section 4.24.

2.4.25 ::Simple::Package::information options package ?version?

Synopsis: returns a declared package list of options.

Details: see section 4.25.

2.4.26 ::Simple::Package::information optiontype package version flag

Synopsis: returns a declared package option type.

Details: see section 4.26.

2.4.27 ::Simple::Package::information optionvalue package version flag

Synopsis: returns a declared package option value.

Details: see section 4.27.

2.4.28 ::Simple::Package::information packagealias alias

Synopsis: returns the declared package an alias belongs to.

Details: see section 4.28.

2.4.29 ::Simple::Package::information packageclass class

Synopsis: returns the declared package a class belongs to.

Details: see section 4.29.

2.4.30 ::Simple::Package::information packagecommand command

Synopsis: returns the declared package a command belongs to.

Details: see section 4.30.

2.4.31 ::Simple::Package::information packagenamespace namespace

Synopsis: returns the declared package a namespace belongs to.

Details: see section 4.31.

2.4.32 ::Simple::Package::information privatecommands ?-noclasses? package ?version?

Synopsis: returns a declared package current list of private commands.

Details: see section 4.32.

2.4.33 ::Simple::Package::information publiccommands ?-noclasses? package ?version?

Synopsis: returns a declared package current list of public commands.

Details: see section 4.33.

2.4.34 ::Simple::Package::information required package ?version?

Synopsis: returns a declared package list of required packages.

Details: see section 4.34.

2.4.35 ::Simple::Package::information requiredall package ?version?

Synopsis: returns a declared package full list of required packages.

Details: see section 4.35.

2.4.36 ::Simple::Package::information requiredby package ?version?

Synopsis: returns the list of declared packages which require a package.

Details: see section 4.36.

2.4.37 ::Simple::Package::information requisites package ?version?

Synopsis: returns a declared package list of requisites.

Details: see section 4.37.

2.4.38 ::Simple::Package::information state package ?version?

Synopsis: returns the state of a package.

Details: see section 4.38.

2.4.39 ::Simple::Package::information types package ?version?

Synopsis: returns a declared package list of types.

Details: see section 4.39.

2.4.40 ::Simple::Package::information uninstall package ?version?

Synopsis: returns a declared package uninstall script.

Details: see section 4.40.

2.4.41 ::Simple::Package::information uninstalled ?pattern?

Synopsis: returns the list of uninstalled packages.

Details: see section 4.41.

2.4.42 ::Simple::Package::information variables package ?version?

Synopsis: returns a declared package list of variables.

Details: see section 4.42.

2.4.43 ::Simple::Package::install package

Synopsis: installs a package.

Details: see section 4.43.

2.4.44 ::Simple::Package::require ?-exact? package ?version?

Synopsis: requires a package.

Details: see section 4.44.

2.4.45 ::Simple::Package::require-and-install ?-exact? package ?version?

Synopsis: requires and installs a package.

Details: see section 4.45.

2.4.46 ::Simple::Package::resync

Synopsis: resynchronizes the information about available packages.

Details: see section 4.46.

2.4.47 ::Simple::Package::undeclare package

Synopsis: undeclares a package.

Details: see section 4.47.

2.4.48 ::Simple::Package::unimport package namespace

Synopsis: unimports a package exported commands from a namespace.

Details: see section 4.48.

2.4.49 ::Simple::Package::uninstall package

Synopsis: uninstalls a package.

Details: see section 4.49.

2.4.50 ::Simple::Package::uninstall-and-undeclare package

Synopsis: uninstalls and undeclares a package.

Details: see section 4.50.

2.5 Errors

2.5.1 ::Simple::Package::NAMESPACE-OR-CLASS-OWNED

Message: namespace or class "namespace or class" owned by package "package".

Explanation: namespace or class namespace or class is already owned by package package and a namespace or class can not be shared by two packages.

2.5.2 ::Simple::Package::NAMESPACE-OR-CLASS-NOT-OWNED

Message: namespace or class "package" not owned by package "namespace or class".

Explanation: package package is using the namespace or class namespace or class as if it were its owner, but that is not the case.

2.5.3 ::Simple::Package::NAMESPACE-OR-CLASS-NOT-OWNED-NOR-REQUISITES

Message: namespace or class "package" not owned by package "namespace or class" nor any of its requisites.

Explanation: package package has tried to be declared with an alias in a namespace or class namespace or class not owned by the package nor any of its direct requisites.

2.5.4 ::Simple::Package::UNDECLARED

Message: undeclared package "package".

Explanation: package package is undeclared, but a declared package is required.

Corrective action: use ::Simple::Package::declare or declare-package to declare the package.

2.5.5 ::Simple::Package::UNINSTALLED

Message: uninstalled package "package".

Explanation: package package is uninstalled, but an installed package is required.

Corrective action: use ::Simple::Package::install to install the package.

2.5.6 ::Simple::Package::INSTALLED

Message: installed package "package".

Explanation: package package is installed, but an uninstalled package is required.

Corrective action: use ::Simple::Package::uninstall to uninstall the package.

2.5.7 ::Simple::Package::ERROR-EVAL-SCRIPT

Message: error evaluating package "package" install, first time install or uninstall script: error.

Explanation: error error was thrown when evaluating the install, first time install or uninstall script for package package.

Corrective action: correct the corresponding script.

2.5.8 ::Simple::Package::ALREADY-DECLARED

Message: package "package version" already declared.

Explanation: version version of package package has already been declared via ::Simple::Package::declare or declare-package.

Corrective action: use ::Simple::Package::undeclare to undeclare the package.

2.5.9 ::Simple::Package::COLLISION

Message: couldn't import or install package "package": command (or alias) "command or alias" in namespace collides with command or alias "exported command or alias" (package "colliding package").

Explanation: it was impossible to import or install package package because the existing command or alias command or alias in namespace namespace collides (that is, their names are identical) with command or alias exported command or alias from package colliding package. This last package either is the one being imported or installed or is required by it.

Corrective action: either delete or rename the command or alias command or alias. Use ::Simple::Package::information collisions to ensure there are no collisions when importing or installing a package.

2.5.10 ::Simple::Package::COLLISION-BETWEEN-PACKAGES

Message: couldn't import or install package "package": command (or alias) "command or alias" is exported or created by both package "package 1" [(namespace "namespace 1")] and "package 2" [(namespace "namespace 2")].

Explanation: it was impossible to import or install package package because it exports (or creates) command (or alias) command or alias in two packages package 1 and package 2. This means that package package is badly formed.

Corrective action: correct package package.

2.5.11 ::Simple::Package::ALREADY-IMPORTED

Message: package "package" already imported into namespace "namespace".

Explanation: it was impossible to import package package into namespace namespace because it was already imported into it.

Corrective action: use ::Simple::Package::unimport to unimport the package from the namespace.

2.5.12 ::Simple::Package::NOT-IMPORTED

Message: package "package" not imported into namespace "namespace".

Explanation: it was impossible to unimport package package from namespace namespace because it was not imported into it.

Corrective action: use ::Simple::Package::import to import the package into the namespace.

2.5.13 ::Simple::Package::EMPTY-NAMESPACES-LIST

Message: empty namespaces list.

Explanation: the list of namespaces given in a package declaration is empty, but this is not allowed.

3. Package further information

3.1 Todo

4. Package command details

4.1 ::Simple::Package::cget

4.1.1 Command description

Synopsis: gets the package options.

Access mode: public.

4.1.2 Command public API

Arguments: none.

Returns: the requested option value or the whole list of options if none specified.

4.2 ::Simple::Package::configure

4.2.1 Command description

Synopsis: configures the package options.

Access mode: public.

4.2.2 Command public API

Arguments: none.

Returns: the "package with no options" error is thrown.

4.3 ::Simple::Package::declare package version ?-requisites packagerequisite-list? ?-namespaces namespace-list? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-install script? ?-uninstall script? ?-firsttimeinstall script?

4.3.1 Command description

Synopsis: declares a package.

Access mode: public.

4.3.1.1 Overview

This procedure is used to declare a package including its required packages (which are required), namespaces (which are created), exported commands (which are exported), aliases as well as the install, first time install and uninstall scripts.

The aliases are created when the package is installed via the ::Simple::Package::install command. The install, first time install and uninstall scripts are evaluated in the global namespace when the package is installed via the ::Simple::Package::install command, installed for the first time via the ::Simple::Package::install command, or uninstalled via the ::Simple::Package::uninstall command, respectively.

An error is thrown if the package is already declared; use ::Simple::Package::undeclare to undeclare a package.

Aliases can be qualified or not. Qualified aliases must point to either one of the package namespaces or to a namespace belonging to one of the package direct requisites.

The most prominent difference between an alias and an exported command is that the alias effect is interpreter-wide while that of the exported command is namespace-wide. As all package exported commands are imported into the global namespace upon installing a package, place in which are accessible even from other namespaces, that difference is in practice almost irrelevant. Aliases are thus provided by this package so that a command can be accessed through two names, as the ::Simple::Subcommand::create command which can also be accessed as proc-sub. Notice that the alias is valid to invoke the command only, not being a full-fledged substitute at all times when a command name is expected. Notice also that a command call through an alias is slightly slower than calling the command directly.

The first time install script should contain code intended to be evaluated once, when a package is installed for the first time, as it gets evaluated at that time and deleted afterwards. On the other hand, the install script is evaluated whenever a package is installed, including reinstallations. The rationale is that a package can be reset by uninstalling and uninstalling it back. The uninstall script is the opposite to the install script.

4.3.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
version version (n/a) Package version
?-requisites? packagerequisite-list (empty string) Package requisites
?-namespaces? namespace-list (empty string) Package namespaces
?-exportedcommands? qualifiedname-list (empty string) Package qualified exported commands
?-aliases? list-list (empty string) Package aliases in the format {aliasName aliasedCommand}
?-install? script (empty string) Package install script
?-uninstall? script (empty string) Package uninstall script
?-firsttimeinstall? script (empty string) Package first time install script

Returns: the empty string.

Effects:

4.3.3 Command further information

4.3.3.1 Remarks

4.4 ::Simple::Package::forget package ?version?

4.4.1 Command description

Synopsis: forgets a package version.

Access mode: public.

4.4.1.1 Overview

This command is similar to package forget but accepts an aditional second argument which, when given, forgets that package version only.

4.4.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the empty string.

Effects:

4.5 ::Simple::Package::import package namespace

4.5.1 Command description

Synopsis: imports a package exported commands into a namespace.

Access mode: public.

4.5.1.1 Overview

This procedure imports the given installed package exported commands into the given namespace.

An error is thrown if the package is not installed.

An error is thrown if the package has already been imported into the given namespace. This implies that the namespace can not be the global one, as any packages is imported into the global namespace upon installation.

An error is thrown if importing the package exported commands into the given namespace would result in a collision; use ::Simple::Package::information collisions to ensure there are no collisions.

4.5.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
namespace namespace (n/a) Namespace

Returns: the empty string.

Effects:

4.6 ::Simple::Package::information aliases package ?version?

4.6.1 Command description

Synopsis: returns a declared package list of aliases.

Access mode: public.

4.6.1.1 Overview

This procedure returns a package list of aliases as given to the -aliases flag when the package was declared.

4.6.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of aliases.

4.6.3 Command further information

4.6.3.1 References

4.6.3.2 Remarks

4.7 ::Simple::Package::information aliasesall package ?version?

4.7.1 Command description

Synopsis: returns a declared package full list of aliases.

Access mode: public.

4.7.1.1 Overview

This procedure returns the given package list of aliases plus those from all packages it may require. It only takes into account the required packages of declared packages.

For each package, the list of aliases is as given to the -aliases flag when the package was declared.

4.7.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package full list of aliases.

4.7.3 Command further information

4.7.3.1 References

4.7.3.2 Remarks

4.8 ::Simple::Package::information api package ?version?

4.8.1 Command description

Synopsis: returns a package public API signatures.

Access mode: public.

4.8.1.1 Overview

This procedure returns a string containing a package public API signatures. It is mainly intended for assessing a package public API in its test module.

Package public and exported commands are included, as well as package classes public and exported commands, public constructor, public destructor and public methods. If existing, aliases are used instead of the original command or method name.

4.8.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the given package public API signatures as follows:

Limitations:

Effects:

4.8.3 Command further information

4.8.3.1 References

4.8.3.2 Remarks

4.9 ::Simple::Package::information classes package ?version?

4.9.1 Command description

Synopsis: returns a declared package list of classes.

Access mode: public.

4.9.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of classes.

4.9.3 Command further information

4.9.3.1 References

4.9.3.2 Remarks

4.10 ::Simple::Package::information collisions package ?namespace?

4.10.1 Command description

Synopsis: returns the list of collisions upon importing a declared package.

Access mode: public.

4.10.1.1 Overview

This procedure returns the list of qualified exported commands and aliases (qualified or not) which would collide if the given package were imported into the given namespace. Collisions occur when one of the package exported commands is named as an already existing command in the target namespace or as a alias, or when one of the package aliases is named as an already existing global command or alias.

If no namespace is given, it defaults to the global one. If the target namespace is the global one, the list of collisions takes into account not only the exported command and aliases from the given package but also those from any not previously installed package it may require.

4.10.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?namespace? namespace :: Target namespace

Returns: the list of colliding qualified exported commands and aliases (qualified or not) upon importing the package.

4.11 ::Simple::Package::information commands ?-noclasses? package ?version?

4.11.1 Command description

Synopsis: returns a declared package current list of public and exported commands.

Access mode: public.

4.11.1.1 Overview

This procedure returns the given package list of commands currently available to the user. This list includes both the exported and public commands, both in namespaces and classes.

4.11.2 Command public API

Arguments:

Argument Type Default value/ choices Description
-noclasses boolflag (n/a) Whether not to include class commands
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package current list of qualified public and exported commands.

4.11.3 Command further information

4.11.3.1 References

4.11.3.2 Remarks

4.12 ::Simple::Package::information declared ?pattern?

4.12.1 Command description

Synopsis: returns the list of declared packages.

Access mode: public.

4.12.1.1 Overview

This procedure returns the list of declared packages (that is, those for which ::Simple::Package::declare has been invoked) and whose name matches the given pattern.

The returned packages can be in the declared or installed states.

4.12.2 Command public API

Arguments:

Argument Type Default value/ choices Description
?pattern? pattern (empty string) Pattern

Returns: the list of declared packages whose name matches the given pattern in the format {package version}.

4.12.3 Command further information

4.12.3.1 Remarks

4.13 ::Simple::Package::information declaredexportedcommands package ?version?

4.13.1 Command description

Synopsis: returns a declared package declared list of exported commands.

Access mode: public.

4.13.1.1 Overview

This procedure returns a package list of exported commands as given when the package was declared.

4.13.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of declared qualified exported commands.

4.13.3 Command further information

4.13.3.1 References

4.13.3.2 Remarks

4.14 ::Simple::Package::information errors package ?version?

4.14.1 Command description

Synopsis: returns a declared package list of errors.

Access mode: public.

4.14.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of errors.

4.14.3 Command further information

4.14.3.1 References

4.14.3.2 Remarks

4.15 ::Simple::Package::information exportedcommands package ?version?

4.15.1 Command description

Synopsis: returns a declared package current list of exported commands.

Access mode: public.

4.15.1.1 Overview

This procedure returns a package current list of exported commands as given by the namespace export command in each of its namespaces and classes, that is, a snapshot of the currently exported commands is taken. Thus, the returned list of exported commands might differ from the declared list of exported commands given when the package was declared in case any command was exported after the package declaration or if an extra package exports commands from namespaces belonging to the non-extra package.

4.15.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package current list of unqualified exported commands.

4.15.3 Command further information

4.15.3.1 References

4.15.3.2 Remarks

4.16 ::Simple::Package::information exportedcommandsall package ?version?

4.16.1 Command description

Synopsis: returns a declared package current full list of exported commands.

Access mode: public.

4.16.1.1 Overview

This procedure returns a package current list of exported commands plus those exported from all packages it may require. It only takes into account the required packages of declared packages.

For each package, the list of exported commands is as given by the namespace export command in each of its namespaces, that is, a snapshot of the exported commands is taken. Thus, the returned list of exported commands might differ from the declared list of exported commands given when the package was declared in case any command was exported after the package declaration or if an extra package exports commands from namespaces belonging to the non-extra package.

4.16.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package current full list of unqualified exported commands.

4.16.3 Command further information

4.16.3.1 References

4.16.3.2 Remarks

4.17 ::Simple::Package::information importedinto package ?version?

4.17.1 Command description

Synopsis: returns the namespaces into which a declared package has been imported.

Access mode: public.

4.17.1.1 Overview

This procedure returns the list of namespaces into which the given package has been imported or the empty list for uninstalled packages.

4.17.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the list of namespaces into which the package has been imported or the empty list for uninstalled packages.

4.18 ::Simple::Package::information install package ?version?

4.18.1 Command description

Synopsis: returns a declared package install script.

Access mode: public.

4.18.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package install script.

4.19 ::Simple::Package::information installed ?pattern?

4.19.1 Command description

Synopsis: returns the list of installed packages.

Access mode: public.

4.19.1.1 Overview

This procedure returns the list of installed packages (that is, those whose state is installed, either by having being required and not declared or required, declared and also installed) and whose name matches the given pattern.

All returned packages are in the installed state.

4.19.2 Command public API

Arguments:

Argument Type Default value/ choices Description
?pattern? pattern (empty string) Pattern

Returns: the list of installed packages whose name matches the given pattern in the format {package version}.

4.19.3 Command further information

4.19.3.1 Remarks

4.20 ::Simple::Package::information known ?pattern?

4.20.1 Command description

Synopsis: returns the list of known packages.

Access mode: public.

4.20.1.1 Overview

This procedure returns the list of known packages (that is, those for which package ifneeded and/or package provide has been invoked) and whose name matches the given pattern.

The returned packages can be in any state but unknown, that is, available, declared or installed.

4.20.2 Command public API

Arguments:

Argument Type Default value/ choices Description
?pattern? pattern (empty string) Pattern

Returns: the list of known packages whose name matches the given pattern in the format {package version}.

4.20.3 Command further information

4.20.3.1 Remarks

4.21 ::Simple::Package::information metadata package ?version?

4.21.1 Command description

Synopsis: returns a declared package metadata.

Access mode: public.

4.21.1.1 Overview

This procedure returns a list of pairs suitable to be given as argument to the array set command. Each element is one of the flags given to declare-package upon package declaration (with no hyphen), but for -api and -firsttimeinstall (which are not stored), the item declarations (-error, -type, -class, -variable, -command and -option; these are obtained using ::Simple::Package::information errors or equivalent) as well as the items stored by ::Simple::Package::declare (requisites, namespaces, exportedcommands and aliases; these are obtained using specific ::Simple::Package::information subcommands).

Thus, the actual list of flags is the following: -project, -synopsis, -module, -overview, -usage, -keywords, -examples, -paradigm, -assumptions, -resources, -limitations, -effects, -details, -references, -remarks, -todo, -cmid, -sprs, -smrs, -history and -copyright.

Notice that no data is returned unless The Simple Development Library -storemetadata option is set when the package was declared.

If a particular flag was not given in the package declaration, the empty string is returned as that flag contents.

4.21.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package metadata as an item/contents pairs list.

4.22 ::Simple::Package::information namespaces package ?version?

4.22.1 Command description

Synopsis: returns a declared package namespaces.

Access mode: public.

4.22.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of namespaces.

4.23 ::Simple::Package::information optionchoices package version flag

4.23.1 Command description

Synopsis: returns a declared package option choices.

Access mode: public.

4.23.1.1 Overview

This procedure returns the choices of a declared package option.

4.23.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
version version (n/a) Package version
flag flag (n/a) Option flag

Returns: the package option choices.

Limitations:

4.24 ::Simple::Package::information optiondescription package version flag

4.24.1 Command description

Synopsis: returns a declared package option description.

Access mode: public.

4.24.1.1 Overview

This procedure returns the description of a declared package option.

4.24.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
version version (n/a) Package version
flag flag (n/a) Option flag

Returns: the package option description.

Limitations:

4.25 ::Simple::Package::information options package ?version?

4.25.1 Command description

Synopsis: returns a declared package list of options.

Access mode: public.

4.25.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of options.

4.25.3 Command further information

4.25.3.1 References

4.25.3.2 Remarks

4.26 ::Simple::Package::information optiontype package version flag

4.26.1 Command description

Synopsis: returns a declared package option type.

Access mode: public.

4.26.1.1 Overview

This procedure returns the type of a declared package option.

4.26.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
version version (n/a) Package version
flag flag (n/a) Option flag

Returns: the package option type.

Limitations:

4.27 ::Simple::Package::information optionvalue package version flag

4.27.1 Command description

Synopsis: returns a declared package option value.

Access mode: public.

4.27.1.1 Overview

This procedure returns the value of a declared package option.

4.27.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
version version (n/a) Package version
flag flag (n/a) Option flag

Returns: the package option value.

Limitations:

4.28 ::Simple::Package::information packagealias alias

4.28.1 Command description

Synopsis: returns the declared package an alias belongs to.

Access mode: public.

4.28.1.1 Overview

This procedure returns the declared package the given alias belongs to, or the empty string if either no declared package owns the given alias or the alias does not exist.

4.28.2 Command public API

Arguments:

Argument Type Default value/ choices Description
alias commandname (n/a) Alias name

Returns: the declared package an alias belongs to.

4.28.3 Command further information

4.28.3.1 Remarks

4.29 ::Simple::Package::information packageclass class

4.29.1 Command description

Synopsis: returns the declared package a class belongs to.

Access mode: public.

4.29.1.1 Overview

This procedure returns the declared package the given class belongs to, or the empty string if either no declared package owns the given class or the class does not exist.

4.29.2 Command public API

Arguments:

Argument Type Default value/ choices Description
class name (n/a) Class name

Returns: the declared package a class belongs to.

4.30 ::Simple::Package::information packagecommand command

4.30.1 Command description

Synopsis: returns the declared package a command belongs to.

Access mode: public.

4.30.1.1 Overview

This procedure returns the declared package the given command belongs to, or the empty string if no declared package owns the given command. It works for either package commands used in their own namespace or for exported commands from other packages.

4.30.2 Command public API

Arguments:

Argument Type Default value/ choices Description
command unqualifiedname (n/a) Command name

Returns: the declared package a command belongs to.

Limitations:

4.31 ::Simple::Package::information packagenamespace namespace

4.31.1 Command description

Synopsis: returns the declared package a namespace belongs to.

Access mode: public.

4.31.1.1 Overview

This procedure returns the declared package the given namespace belongs to, or the empty string if either no declared package owns the given namespace or the namespace does not exist.

4.31.2 Command public API

Arguments:

Argument Type Default value/ choices Description
namespace namespace (n/a) Namespace

Returns: the declared package a namespace belongs to.

4.32 ::Simple::Package::information privatecommands ?-noclasses? package ?version?

4.32.1 Command description

Synopsis: returns a declared package current list of private commands.

Access mode: public.

4.32.1.1 Overview

This procedure returns a package current list of private commands. A private command is either one living in a private namespace (that is, one whose name matches the pattern *::Priv*), or a private class command.

4.32.2 Command public API

Arguments:

Argument Type Default value/ choices Description
-noclasses boolflag (n/a) Whether not to include class commands
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package current list of qualified private commands.

4.32.3 Command further information

4.32.3.1 References

4.32.3.2 Remarks

4.33 ::Simple::Package::information publiccommands ?-noclasses? package ?version?

4.33.1 Command description

Synopsis: returns a declared package current list of public commands.

Access mode: public.

4.33.2 Command public API

Arguments:

Argument Type Default value/ choices Description
-noclasses boolflag (n/a) Whether not to include class commands
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package current list of qualified public commands.

4.33.3 Command further information

4.33.3.1 References

4.33.3.2 Remarks

4.34 ::Simple::Package::information required package ?version?

4.34.1 Command description

Synopsis: returns a declared package list of required packages.

Access mode: public.

4.34.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of required packages in the format {package version}.

4.35 ::Simple::Package::information requiredall package ?version?

4.35.1 Command description

Synopsis: returns a declared package full list of required packages.

Access mode: public.

4.35.1.1 Overview

This procedure returns the given package list of required packages plus all packages it may require. It only takes into account the required packages of declared packages.

4.35.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package full list of required packages in the format {package version}.

4.35.3 Command further information

4.35.3.1 References

4.36 ::Simple::Package::information requiredby package ?version?

4.36.1 Command description

Synopsis: returns the list of declared packages which require a package.

Access mode: public.

4.36.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the list of declared packages which require the package in the format {package version}.

4.36.3 Command further information

4.36.3.1 Remarks

4.37 ::Simple::Package::information requisites package ?version?

4.37.1 Command description

Synopsis: returns a declared package list of requisites.

Access mode: public.

4.37.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of requisites.

4.38 ::Simple::Package::information state package ?version?

4.38.1 Command description

Synopsis: returns the state of a package.

Access mode: public.

4.38.1.1 Overview

This procedure returns the state of the given package, one of unknown, available, declared or installed. If no version is given, the returned state is that of the known package with higher version.

4.38.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the state of the given package, one of unknown, available, declared or installed.

4.39 ::Simple::Package::information types package ?version?

4.39.1 Command description

Synopsis: returns a declared package list of types.

Access mode: public.

4.39.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of types.

4.39.3 Command further information

4.39.3.1 References

4.39.3.2 Remarks

4.40 ::Simple::Package::information uninstall package ?version?

4.40.1 Command description

Synopsis: returns a declared package uninstall script.

Access mode: public.

4.40.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package uninstall script.

4.41 ::Simple::Package::information uninstalled ?pattern?

4.41.1 Command description

Synopsis: returns the list of uninstalled packages.

Access mode: public.

4.41.1.1 Overview

This procedure returns the list of uninstalled packages (that is, those for which ::Simple::Package::declare has been invoked but which have not been installed yet via ::Simple::Package::install) and whose name matches the given pattern.

All returned packages are in the declared state.

4.41.2 Command public API

Arguments:

Argument Type Default value/ choices Description
?pattern? pattern (empty string) Pattern

Returns: the list of uninstalled packages whose name matches the given pattern in the format {package version}.

4.41.3 Command further information

4.41.3.1 Remarks

4.42 ::Simple::Package::information variables package ?version?

4.42.1 Command description

Synopsis: returns a declared package list of variables.

Access mode: public.

4.42.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the package list of variables.

4.42.3 Command further information

4.42.3.1 References

4.42.3.2 Remarks

4.43 ::Simple::Package::install package

4.43.1 Command description

Synopsis: installs a package.

Access mode: public.

4.43.1.1 Overview

This procedure installs a declared package.

The following tasks are performed in this same order:

The install script is evaluated every time the package is installed, while the first time install script is only evaluated the first time the package is installed after its declaration; upon evaluation, the first time install script is deleted. The first time install script is intended for the initialization of the package static items, notably its commands. On the other hand, the install script is intended for the initialization of the package non-static items such as its variables. Notice that all the packages required by the package being installed are guaranteed to be installed when evaluating the install and first time install scripts.

An error is thrown if the package is already installed; use ::Simple::Package::uninstall to uninstall a package.

An error is thrown if importing the package into the global namespace would result in a collision; use ::Simple::Package::information collisions to ensure there are no collisions.

4.43.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name

Returns: the empty string.

Effects:

4.44 ::Simple::Package::require ?-exact? package ?version?

4.44.1 Command description

Synopsis: requires a package.

Access mode: public.

4.44.1.1 Overview

This procedure requires a package, that is, changes its state from available to either required or installed depending on whether the package is declared upon requiring it.

No error is thrown if the package is already provided.

An error is thrown if the package is not available.

4.44.2 Command public API

Arguments:

Argument Type Default value/ choices Description
-exact boolflag (n/a) Only the specified version is acceptable
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the required package version.

4.45 ::Simple::Package::require-and-install ?-exact? package ?version?

4.45.1 Command description

Synopsis: requires and installs a package.

Access mode: public.

4.45.1.1 Overview

This procedure changes a package state from available to installed. If the package is declared upon requiring it, the package is then installed. Notice that otherwise a full installation might require manually importing the package namespaces via namespace import.

No error is thrown if the package is already provided or installed.

An error is thrown if the package is not available.

4.45.2 Command public API

Arguments:

Argument Type Default value/ choices Description
-exact boolflag (n/a) Only the specified version is acceptable
package package (n/a) Package name
?version? version (n/a) Package version

Returns: the required package version.

4.46 ::Simple::Package::resync

4.46.1 Command description

Synopsis: resynchronizes the information about available packages.

Access mode: public.

4.46.1.1 Overview

This command resynchronizes the information about available packages by invoking the unknown procedure.

4.46.1.2 History

Date Reason
10-may-2000 Implementation by Don Porter (donald.porter@nist.gov)

4.46.2 Command public API

Arguments: none.

Returns: the empty string.

4.47 ::Simple::Package::undeclare package

4.47.1 Command description

Synopsis: undeclares a package.

Access mode: public.

4.47.1.1 Overview

This procedure undeclares a declared package.

An error is thrown if the package is installed; use ::Simple::Package::uninstall to uninstall a package.

4.47.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name

Returns: the empty string.

Effects:

4.47.3 Command further information

4.47.3.1 Remarks

4.48 ::Simple::Package::unimport package namespace

4.48.1 Command description

Synopsis: unimports a package exported commands from a namespace.

Access mode: public.

4.48.1.1 Overview

This procedure unimports the given package exported commands from the given namespace.

An error is thrown if the package is not installed.

An error is thrown if the package has not been imported into the given namespace.

4.48.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name
namespace namespace (n/a) Namespace

Returns: the empty string.

Effects:

4.49 ::Simple::Package::uninstall package

4.49.1 Command description

Synopsis: uninstalls a package.

Access mode: public.

4.49.1.1 Overview

This procedure uninstalls a package previously installed via the ::Simple::Package::install command. The following tasks are performed in this same order:

An error is thrown if the package is not installed.

4.49.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name

Returns: the empty string.

Effects:

4.49.3 Command further information

4.49.3.1 Remarks

4.50 ::Simple::Package::uninstall-and-undeclare package

4.50.1 Command description

Synopsis: uninstalls and undeclares a package.

Access mode: public.

4.50.1.1 Overview

This procedure changes a package state from installed to available. If the package was declared, it is first uninstalled and then undeclared; otherwise the package is simply unprovided. Notice that in the later case a full uninstallation might require manually forgeting the package namespaces via namespace forget.

An error is thrown if the package is not installed.

4.50.2 Command public API

Arguments:

Argument Type Default value/ choices Description
package package (n/a) Package name

Returns: the empty string.

Effects:

4.50.3 Command further information

4.50.3.1 Remarks