SimplePackage v1.0
The Simple Development Library packages handling
Project: the Simple Development Library.
::Simple::Package::cget
::Simple::Package::configure
::Simple::Package::declare
package version ?-requisites packagerequisite-list? ?-namespaces namespace-list? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-install script? ?-uninstall script? ?-firsttimeinstall script?::Simple::Package::forget
package ?version?::Simple::Package::import
package namespace::Simple::Package::information aliases
package ?version?::Simple::Package::information aliasesall
package ?version?::Simple::Package::information api
package ?version?::Simple::Package::information classes
package ?version?::Simple::Package::information collisions
package ?namespace?::Simple::Package::information commands
?-noclasses? package ?version?::Simple::Package::information declared
?pattern?::Simple::Package::information declaredexportedcommands
package ?version?::Simple::Package::information errors
package ?version?::Simple::Package::information exportedcommands
package ?version?::Simple::Package::information exportedcommandsall
package ?version?::Simple::Package::information importedinto
package ?version?::Simple::Package::information install
package ?version?::Simple::Package::information installed
?pattern?::Simple::Package::information known
?pattern?::Simple::Package::information metadata
package ?version?::Simple::Package::information namespaces
package ?version?::Simple::Package::information optionchoices
package version flag::Simple::Package::information optiondescription
package version flag::Simple::Package::information options
package ?version?::Simple::Package::information optiontype
package version flag::Simple::Package::information optionvalue
package version flag::Simple::Package::information packagealias
alias::Simple::Package::information packageclass
class::Simple::Package::information packagecommand
command::Simple::Package::information packagenamespace
namespace::Simple::Package::information privatecommands
?-noclasses? package ?version?::Simple::Package::information publiccommands
?-noclasses? package ?version?::Simple::Package::information required
package ?version?::Simple::Package::information requiredall
package ?version?::Simple::Package::information requiredby
package ?version?::Simple::Package::information requisites
package ?version?::Simple::Package::information state
package ?version?::Simple::Package::information types
package ?version?::Simple::Package::information uninstall
package ?version?::Simple::Package::information uninstalled
?pattern?::Simple::Package::information variables
package ?version?::Simple::Package::install
package::Simple::Package::require
?-exact? package ?version?::Simple::Package::require-and-install
?-exact? package ?version?::Simple::Package::resync
::Simple::Package::undeclare
package::Simple::Package::unimport
package namespace::Simple::Package::uninstall
package::Simple::Package::uninstall-and-undeclare
package::Simple::Package::NAMESPACE-OR-CLASS-OWNED
::Simple::Package::NAMESPACE-OR-CLASS-NOT-OWNED
::Simple::Package::NAMESPACE-OR-CLASS-NOT-OWNED-NOR-REQUISITES
::Simple::Package::UNDECLARED
::Simple::Package::UNINSTALLED
::Simple::Package::INSTALLED
::Simple::Package::ERROR-EVAL-SCRIPT
::Simple::Package::ALREADY-DECLARED
::Simple::Package::COLLISION
::Simple::Package::COLLISION-BETWEEN-PACKAGES
::Simple::Package::ALREADY-IMPORTED
::Simple::Package::NOT-IMPORTED
::Simple::Package::EMPTY-NAMESPACES-LIST
::Simple::Package::cget
::Simple::Package::configure
::Simple::Package::declare
package version ?-requisites packagerequisite-list? ?-namespaces namespace-list? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-install script? ?-uninstall script? ?-firsttimeinstall script?::Simple::Package::forget
package ?version?::Simple::Package::import
package namespace::Simple::Package::information aliases
package ?version?::Simple::Package::information aliasesall
package ?version?::Simple::Package::information api
package ?version?::Simple::Package::information classes
package ?version?::Simple::Package::information collisions
package ?namespace?::Simple::Package::information commands
?-noclasses? package ?version?::Simple::Package::information declared
?pattern?::Simple::Package::information declaredexportedcommands
package ?version?::Simple::Package::information errors
package ?version?::Simple::Package::information exportedcommands
package ?version?::Simple::Package::information exportedcommandsall
package ?version?::Simple::Package::information importedinto
package ?version?::Simple::Package::information install
package ?version?::Simple::Package::information installed
?pattern?::Simple::Package::information known
?pattern?::Simple::Package::information metadata
package ?version?::Simple::Package::information namespaces
package ?version?::Simple::Package::information optionchoices
package version flag::Simple::Package::information optiondescription
package version flag::Simple::Package::information options
package ?version?::Simple::Package::information optiontype
package version flag::Simple::Package::information optionvalue
package version flag::Simple::Package::information packagealias
alias::Simple::Package::information packageclass
class::Simple::Package::information packagecommand
command::Simple::Package::information packagenamespace
namespace::Simple::Package::information privatecommands
?-noclasses? package ?version?::Simple::Package::information publiccommands
?-noclasses? package ?version?::Simple::Package::information required
package ?version?::Simple::Package::information requiredall
package ?version?::Simple::Package::information requiredby
package ?version?::Simple::Package::information requisites
package ?version?::Simple::Package::information state
package ?version?::Simple::Package::information types
package ?version?::Simple::Package::information uninstall
package ?version?::Simple::Package::information uninstalled
?pattern?::Simple::Package::information variables
package ?version?::Simple::Package::install
package::Simple::Package::require
?-exact? package ?version?::Simple::Package::require-and-install
?-exact? package ?version?::Simple::Package::resync
::Simple::Package::undeclare
package::Simple::Package::unimport
package namespace::Simple::Package::uninstall
package::Simple::Package::uninstall-and-undeclare
packageSynopsis: the Simple Development Library packages handling.
Keywords: package, alias, export, import, install, load, require and unknown.
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.
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:
.===========. .-----------. | unknown | | known | * `===========' `-----------' | | .===========. .-----------. | available | | provided | `===========' `-----------' | | .===========. .-----------. | declared | * |undeclared | `===========' `-----------' | | | .-----------. .===========. |uninstalled| * | installed | * `-----------' `==========='
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:
.===========. | unknown | ::S::P::forget .>`==========='-. OR package forget | | package ifneeded | | `-.===========.<' | available | .>`==========='-. ::S::P::require OR ::S::P:: | | package require OR uninstall-and-undeclare | | ::S::P::install-and-require `-.===========.<' | installed | `==========='
Second, for packages declared using The Simple Development Library:
.===========. | unknown | ::S::P::forget .>`==========='-. OR package forget | | package ifneeded | | `-.===========.<' | available | ,----------->-------------.>`==========='-.----------->-------------. | | | (::S::P::require OR | | ::S::P::undeclare | | package require) AND | | `-.===========.<' ::S::P::declare | ::S::P:: | declared | ::S::P:: uninstall-and-undeclare .>`==========='-. require-and-install | | | | | ::S::P::uninstall | | ::S::P::install | | `-.===========.<' | | | installed | | `-----------<---------------`==========='<------------<-------------'
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.
# Install the package package require SimplePackage # Create an ifneeded script for a package which does not declare it package ifneeded UndeclaredPackage 1.0 { package provide UndeclaredPackage 1.0 } # Create an ifneeded script for a package declaring it package ifneeded DeclaredPackage 1.0 { ::Simple::Package::declare DeclaredPackage 1.0 -requisites { {UndeclaredPackage 1.0} } -namespaces { ::Declared } -exportedcommands { ::Declared::export } -aliases { {alias ::Declared::public} } -install { puts {Installing DeclaredPackage 1.0} set ::Declared::PackageVariable 1 } -uninstall { puts {Uninstalling DeclaredPackage 1.0} } -firsttimeinstall { puts { for the first time!} proc ::Declared::export {} {puts export} proc ::Declared::public {} {puts public} } } # No packages initially installed # This displays the following: # |installed: {} puts "installed: {[::Simple::Package::information installed *eclared*]}" # Now require the declared package ::Simple::Package::require DeclaredPackage # The undeclared package has been installed # This displays the following: # |installed: {{UndeclaredPackage 1.0}} puts "installed: {[::Simple::Package::information installed *eclared*]}" # Create a couple of commands which would collide with the package exported # commands and aliases upon installing it proc export {} {} proc alias {} {} # Which commands are exported by the declared package ? # This displays the following: # |export: {export} puts "export: {[::Simple::Package::information\ exportedcommands DeclaredPackage]}" # Which commands are exported by the declared package ? # This displays the following: # |aliases: {{alias ::Declared::public}} puts "aliases: {[::Simple::Package::information aliases DeclaredPackage]}" # Would those command or aliases collide with other commands or aliases # in the global namespace ? # This displays the following: # |collisions: {::Declared::export alias} puts "collisions:\ {[::Simple::Package::information collisions DeclaredPackage]}" # Let's remove the colliding commands and assess again whether the # collisions remain rename export {} rename alias {} # This displays the following: # |collisions: {} puts "collisions:\ {[::Simple::Package::information collisions DeclaredPackage]}" # No collisions, we may safely install the declared package # This displays the following: # |Installing DeclaredPackage 1.0 # | for the first time! ::Simple::Package::install DeclaredPackage # Increase and display the package variable # This displays the following: # |2 puts [incr ::Declared::PackageVariable] # Into which namespaces has the declared package been imported ? # This displays the following: # |importedinto: {::} puts "importedinto:\ {[::Simple::Package::information importedinto DeclaredPackage]}" # Which commands are provided by the declared package ? # This displays the following: # |commands: {::Declared::export ::Declared::public} puts "commands:\ {[::Simple::Package::information commands DeclaredPackage]}" # Ok, use them # This displays the following: # |public ::Declared::public # This displays the following: # |export export # We are done, let's get rid of the declared package # This displays the following: # |Uninstalling DeclaredPackage 1.0 ::Simple::Package::uninstall DeclaredPackage # The package commands are no longer available # This displays the following: # |invalid command name "export" catch {export} result puts $result # The undeclared package remains installed # This displays the following: # |installed: {{UndeclaredPackage 1.0}} puts "installed: {[::Simple::Package::information installed *eclared*]}" # We need the declared package again! # This displays the following: # |Installing DeclaredPackage 1.0 ::Simple::Package::require-and-install DeclaredPackage # Verify that the package variable has its default value # This displays the following: # |1 puts $::Declared::PackageVariable
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 |
Copyright (C) 1999-2005, Juan C. Gil (jgil@gmv.es).
Paradigm: procedural.
Requisites: SimpleError 1.0
.
Description: package name: Tcl, ...
Description: package version: 1.1, ...
Description: package name and version as {package version}
: {Tcl 8.4}.
Description: package requisite as {?-exact? package ?requisiteVersion?}
: Tcl 8, -exact Tk 8.3, ...
None.
::Simple::Package
::Simple::Package::Priv
::
::Simple::Package::cget
Synopsis: gets the package options.
Details: see section 4.1.
::Simple::Package::configure
Synopsis: configures the package options.
Details: see section 4.2.
::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.
::Simple::Package::forget
package ?version?Synopsis: forgets a package version.
Details: see section 4.4.
::Simple::Package::import
package namespaceSynopsis: imports a package exported commands into a namespace.
Details: see section 4.5.
::Simple::Package::information aliases
package ?version?Synopsis: returns a declared package list of aliases.
Details: see section 4.6.
::Simple::Package::information aliasesall
package ?version?Synopsis: returns a declared package full list of aliases.
Details: see section 4.7.
::Simple::Package::information api
package ?version?Synopsis: returns a package public API signatures.
Details: see section 4.8.
::Simple::Package::information classes
package ?version?Synopsis: returns a declared package list of classes.
Details: see section 4.9.
::Simple::Package::information collisions
package ?namespace?Synopsis: returns the list of collisions upon importing a declared package.
Details: see section 4.10.
::Simple::Package::information commands
?-noclasses? package ?version?Synopsis: returns a declared package current list of public and exported commands.
Details: see section 4.11.
::Simple::Package::information declared
?pattern?Synopsis: returns the list of declared packages.
Details: see section 4.12.
::Simple::Package::information declaredexportedcommands
package ?version?Synopsis: returns a declared package declared list of exported commands.
Details: see section 4.13.
::Simple::Package::information errors
package ?version?Synopsis: returns a declared package list of errors.
Details: see section 4.14.
::Simple::Package::information exportedcommands
package ?version?Synopsis: returns a declared package current list of exported commands.
Details: see section 4.15.
::Simple::Package::information exportedcommandsall
package ?version?Synopsis: returns a declared package current full list of exported commands.
Details: see section 4.16.
::Simple::Package::information importedinto
package ?version?Synopsis: returns the namespaces into which a declared package has been imported.
Details: see section 4.17.
::Simple::Package::information install
package ?version?Synopsis: returns a declared package install script.
Details: see section 4.18.
::Simple::Package::information installed
?pattern?Synopsis: returns the list of installed packages.
Details: see section 4.19.
::Simple::Package::information known
?pattern?Synopsis: returns the list of known packages.
Details: see section 4.20.
::Simple::Package::information metadata
package ?version?Synopsis: returns a declared package metadata.
Details: see section 4.21.
::Simple::Package::information namespaces
package ?version?Synopsis: returns a declared package namespaces.
Details: see section 4.22.
::Simple::Package::information optionchoices
package version flagSynopsis: returns a declared package option choices.
Details: see section 4.23.
::Simple::Package::information optiondescription
package version flagSynopsis: returns a declared package option description.
Details: see section 4.24.
::Simple::Package::information options
package ?version?Synopsis: returns a declared package list of options.
Details: see section 4.25.
::Simple::Package::information optiontype
package version flagSynopsis: returns a declared package option type.
Details: see section 4.26.
::Simple::Package::information optionvalue
package version flagSynopsis: returns a declared package option value.
Details: see section 4.27.
::Simple::Package::information packagealias
aliasSynopsis: returns the declared package an alias belongs to.
Details: see section 4.28.
::Simple::Package::information packageclass
classSynopsis: returns the declared package a class belongs to.
Details: see section 4.29.
::Simple::Package::information packagecommand
commandSynopsis: returns the declared package a command belongs to.
Details: see section 4.30.
::Simple::Package::information packagenamespace
namespaceSynopsis: returns the declared package a namespace belongs to.
Details: see section 4.31.
::Simple::Package::information privatecommands
?-noclasses? package ?version?Synopsis: returns a declared package current list of private commands.
Details: see section 4.32.
::Simple::Package::information publiccommands
?-noclasses? package ?version?Synopsis: returns a declared package current list of public commands.
Details: see section 4.33.
::Simple::Package::information required
package ?version?Synopsis: returns a declared package list of required packages.
Details: see section 4.34.
::Simple::Package::information requiredall
package ?version?Synopsis: returns a declared package full list of required packages.
Details: see section 4.35.
::Simple::Package::information requiredby
package ?version?Synopsis: returns the list of declared packages which require a package.
Details: see section 4.36.
::Simple::Package::information requisites
package ?version?Synopsis: returns a declared package list of requisites.
Details: see section 4.37.
::Simple::Package::information state
package ?version?Synopsis: returns the state of a package.
Details: see section 4.38.
::Simple::Package::information types
package ?version?Synopsis: returns a declared package list of types.
Details: see section 4.39.
::Simple::Package::information uninstall
package ?version?Synopsis: returns a declared package uninstall script.
Details: see section 4.40.
::Simple::Package::information uninstalled
?pattern?Synopsis: returns the list of uninstalled packages.
Details: see section 4.41.
::Simple::Package::information variables
package ?version?Synopsis: returns a declared package list of variables.
Details: see section 4.42.
::Simple::Package::install
packageSynopsis: installs a package.
Details: see section 4.43.
::Simple::Package::require
?-exact? package ?version?Synopsis: requires a package.
Details: see section 4.44.
::Simple::Package::require-and-install
?-exact? package ?version?Synopsis: requires and installs a package.
Details: see section 4.45.
::Simple::Package::resync
Synopsis: resynchronizes the information about available packages.
Details: see section 4.46.
::Simple::Package::undeclare
packageSynopsis: undeclares a package.
Details: see section 4.47.
::Simple::Package::unimport
package namespaceSynopsis: unimports a package exported commands from a namespace.
Details: see section 4.48.
::Simple::Package::uninstall
packageSynopsis: uninstalls a package.
Details: see section 4.49.
::Simple::Package::uninstall-and-undeclare
packageSynopsis: uninstalls and undeclares a package.
Details: see section 4.50.
::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.
::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.
::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.
::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.
::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.
::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.
::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.
::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.
::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.
::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.
::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.
::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.
::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.
Currently all packages required by a given package are installed when that package is installed. It would be nice to have a mechanism so that packages not explicitly installed and no longer required by any other could be automatically uninstalled.
Provide a ::Simple::Package::reset
command to reset the state of an installed package by uninstalling and reinstalling it. If effect, this may reduce to evaluate the uninstall and install scripts in turn.
Provide something similar to ::Simple::Package::information collisions
but informing about the collisions when importing a namespace (instead of a package) into another namespace.
Allow a {package version}
pair where a package name is expected in the user procedures, so that it is possible to call the procedure either with a single argument {package version}
or package
or with two arguments package
and version
Detect circular dependencies.
Provide a ::Simple::Package::modify
command.
The install and uninstall package scripts should be stored as procedures instead as of variables in order to benefit from its byte compilation.
::Simple::Package::cget
Synopsis: gets the package options.
Access mode: public.
Arguments: none.
Returns: the requested option value or the whole list of options if none specified.
::Simple::Package::configure
Synopsis: configures the package options.
Access mode: public.
Arguments: none.
Returns: the "package with no options" error is thrown.
::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.
Access mode: public.
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.
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:
Creates the package namespaces.
Requires the required packages.
Exports exported commands from their namespaces.
Provides the package.
The order of the flags is irrelevant but their parameters can not start by an hyphen.
::Simple::Package::forget
package ?version?Synopsis: forgets a package version.
Access mode: public.
This command is similar to package forget
but accepts an aditional second argument which, when given, forgets that package version only.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
?version? | version | (n/a) | Package version |
Returns: the empty string.
Effects:
Forgets all versions of a package or a single version if given.
::Simple::Package::import
package namespaceSynopsis: imports a package exported commands into a namespace.
Access mode: public.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
namespace | namespace | (n/a) | Namespace |
Returns: the empty string.
Effects:
Imports a package exported commands into the given namespace.
::Simple::Package::information aliases
package ?version?Synopsis: returns a declared package list of aliases.
Access mode: public.
This procedure returns a package list of aliases as given to the -aliases flag when the package was declared.
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.
The ::Simple::Package::information aliasesall
command.
The ::Simple::Class::information aliases
command.
Both aliases in package namespaces and classes are taken into account.
::Simple::Package::information aliasesall
package ?version?Synopsis: returns a declared package full list of aliases.
Access mode: public.
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.
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.
The ::Simple::Package::information aliases
command.
Both aliases in package namespaces and classes are taken into account.
::Simple::Package::information api
package ?version?Synopsis: returns a package public API signatures.
Access mode: public.
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.
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:
Commands: <command 1 API> <command 2 API> ... Class <class 1> (extends <class list>) Class constructor: <class 1 constructor API> Class destructor: <class 1 destructor API> Class commands: <class 1 command 1 API> <class 1 command 2 API> ... Class methods: <class 1 method 1 API> <class 1 method 2 API> ... Class <class 2> ...
Limitations:
The package must be installed.
Effects:
Requires and installs the given package extra package, if any.
The ::Simple::Package::information commands
command.
The ::Simple::Class::information commands
command.
The ::Simple::Class::information methods
command.
The ::Simple::Class::information api
command.
If existing, aliases are used instead of the original command or method name.
The returned list does not contain base commands.
The returned list does not contain commands with a percent sign in its name are those are assumed to be internal to The Simple Development Library.
Includes the items in the given package extra package, if any.
::Simple::Package::information classes
package ?version?Synopsis: returns a declared package list of classes.
Access mode: public.
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.
The ::Simple::Package::information api
command.
The classes considered as belonging to a package are those given to the -class flag when the package was declared with declare-package
.
::Simple::Package::information collisions
package ?namespace?Synopsis: returns the list of collisions upon importing a declared package.
Access mode: public.
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.
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.
::Simple::Package::information commands
?-noclasses? package ?version?Synopsis: returns a declared package current list of public and exported commands.
Access mode: public.
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.
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.
The ::Simple::Package::information api
command.
The ::Simple::Class::information commands
command.
The ::Simple::Package::Priv::information-commands
command.
Both commands in package namespaces and classes are taken into account, unless the -noclasses flag is given, case in which only namespaces are considered.
The returned list does not contain base commands.
The returned list does not contain commands with a percent sign in its name are those are assumed to be internal to The Simple Development Library.
The returned list may contain commands created by an extra package in namespaces belonging to the non-extra package.
::Simple::Package::information declared
?pattern?Synopsis: returns the list of declared packages.
Access mode: public.
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.
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}
.
Use no pattern to get all declared packages.
::Simple::Package::information declaredexportedcommands
package ?version?Synopsis: returns a declared package declared list of exported commands.
Access mode: public.
This procedure returns a package list of exported commands as given when the package was declared.
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.
The ::Simple::Package::information exportedcommands
command.
The ::Simple::Package::information exportedcommandsall
command.
The ::Simple::Class::information exportedcommands
command.
Both commands in package namespaces and classes are taken into account.
The returned list does not contain base commands.
The returned list may contain commands with a percent sign in its name assumed to be internal to The Simple Development Library.
::Simple::Package::information errors
package ?version?Synopsis: returns a declared package list of errors.
Access mode: public.
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.
The ::Simple::Package::information api
command.
The errors considered as belonging to a package are those given to the -error flag when the package was declared with declare-package
.
::Simple::Package::information exportedcommands
package ?version?Synopsis: returns a declared package current list of exported commands.
Access mode: public.
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.
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.
The ::Simple::Package::information declaredexportedcommands
command.
The ::Simple::Package::information exportedcommandsall
command.
The ::Simple::Package::Priv::exported-commands
command.
Both commands in package namespaces and classes are taken into account.
The returned list may contain base commands.
The returned list may contain commands with a percent sign in its name are those are assumed to be internal to The Simple Development Library.
The returned list may contain commands exported by an extra package from namespaces belonging to the non-extra package.
::Simple::Package::information exportedcommandsall
package ?version?Synopsis: returns a declared package current full list of exported commands.
Access mode: public.
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.
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.
The ::Simple::Package::information declaredexportedcommands
command.
The ::Simple::Package::information exportedcommands
command.
Both commands in package namespaces and classes are taken into account.
The returned list may contain base commands.
The returned list may contain commands with a percent sign in its name are those are assumed to be internal to The Simple Development Library.
The returned list may contain commands exported by extra packages from namespaces belonging to non-extra packages.
::Simple::Package::information importedinto
package ?version?Synopsis: returns the namespaces into which a declared package has been imported.
Access mode: public.
This procedure returns the list of namespaces into which the given package has been imported or the empty list for uninstalled packages.
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.
::Simple::Package::information install
package ?version?Synopsis: returns a declared package install script.
Access mode: public.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
?version? | version | (n/a) | Package version |
Returns: the package install script.
::Simple::Package::information installed
?pattern?Synopsis: returns the list of installed packages.
Access mode: public.
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.
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}
.
Use no pattern to get all installed packages.
::Simple::Package::information known
?pattern?Synopsis: returns the list of known packages.
Access mode: public.
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.
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}
.
Use no pattern to get all packages.
::Simple::Package::information metadata
package ?version?Synopsis: returns a declared package metadata.
Access mode: public.
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.
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.
::Simple::Package::information namespaces
package ?version?Synopsis: returns a declared package namespaces.
Access mode: public.
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.
::Simple::Package::information optionchoices
package version flagSynopsis: returns a declared package option choices.
Access mode: public.
This procedure returns the choices of a declared package option.
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:
The package must be installed.
::Simple::Package::information optiondescription
package version flagSynopsis: returns a declared package option description.
Access mode: public.
This procedure returns the description of a declared package option.
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:
The package must be installed.
::Simple::Package::information options
package ?version?Synopsis: returns a declared package list of options.
Access mode: public.
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.
The ::Simple::Package::information api
command.
The options considered as belonging to a package are those given to the -option flag when the package was declared with declare-package
.
::Simple::Package::information optiontype
package version flagSynopsis: returns a declared package option type.
Access mode: public.
This procedure returns the type of a declared package option.
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:
The package must be installed.
::Simple::Package::information optionvalue
package version flagSynopsis: returns a declared package option value.
Access mode: public.
This procedure returns the value of a declared package option.
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:
The package must be installed.
::Simple::Package::information packagealias
aliasSynopsis: returns the declared package an alias belongs to.
Access mode: public.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
alias | commandname | (n/a) | Alias name |
Returns: the declared package an alias belongs to.
The aliases considered as belonging to a package are those given to the -aliases flag when the package was declared.
::Simple::Package::information packageclass
classSynopsis: returns the declared package a class belongs to.
Access mode: public.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
class | name | (n/a) | Class name |
Returns: the declared package a class belongs to.
::Simple::Package::information packagecommand
commandSynopsis: returns the declared package a command belongs to.
Access mode: public.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
command | unqualifiedname | (n/a) | Command name |
Returns: the declared package a command belongs to.
Limitations:
The command must exist.
::Simple::Package::information packagenamespace
namespaceSynopsis: returns the declared package a namespace belongs to.
Access mode: public.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
namespace | namespace | (n/a) | Namespace |
Returns: the declared package a namespace belongs to.
::Simple::Package::information privatecommands
?-noclasses? package ?version?Synopsis: returns a declared package current list of private commands.
Access mode: public.
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.
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.
The ::Simple::Package::Priv::information-commands
command.
Both commands in package namespaces and classes are taken into account, unless the -noclasses flag is given, case in which only namespaces are considered.
The returned list does not contain base commands.
The returned list does not contain commands with a percent sign in its name are those are assumed to be internal to The Simple Development Library.
The returned list may contain commands created by an extra package in namespaces belonging to the non-extra package.
::Simple::Package::information publiccommands
?-noclasses? package ?version?Synopsis: returns a declared package current list of public commands.
Access mode: public.
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.
The ::Simple::Package::Priv::information-commands
command.
Both commands in package namespaces and classes are taken into account, unless the -noclasses flag is given, case in which only namespaces are considered.
The returned list does not contain base commands.
The returned list does not contain commands with a percent sign in its name are those are assumed to be internal to The Simple Development Library.
The returned list may contain commands created by an extra package in namespaces belonging to the non-extra package.
::Simple::Package::information required
package ?version?Synopsis: returns a declared package list of required packages.
Access mode: public.
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}
.
::Simple::Package::information requiredall
package ?version?Synopsis: returns a declared package full list of required packages.
Access mode: public.
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.
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}
.
The ::Simple::Package::Priv::requiredall
command.
::Simple::Package::information requiredby
package ?version?Synopsis: returns the list of declared packages which require a package.
Access mode: public.
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}
.
The given package does not need to be declared.
::Simple::Package::information requisites
package ?version?Synopsis: returns a declared package list of requisites.
Access mode: public.
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.
::Simple::Package::information state
package ?version?Synopsis: returns the state of a package.
Access mode: public.
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.
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.
::Simple::Package::information types
package ?version?Synopsis: returns a declared package list of types.
Access mode: public.
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.
The ::Simple::Package::information api
command.
The types considered as belonging to a package are those given to the -type flag when the package was declared with declare-package
.
::Simple::Package::information uninstall
package ?version?Synopsis: returns a declared package uninstall script.
Access mode: public.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
?version? | version | (n/a) | Package version |
Returns: the package uninstall script.
::Simple::Package::information uninstalled
?pattern?Synopsis: returns the list of uninstalled packages.
Access mode: public.
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.
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}
.
Use no pattern to get all uninstalled packages.
::Simple::Package::information variables
package ?version?Synopsis: returns a declared package list of variables.
Access mode: public.
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.
The ::Simple::Package::information api
command.
The variables considered as belonging to a package are those given to the -variable flag when the package was declared with declare-package
.
::Simple::Package::install
packageSynopsis: installs a package.
Access mode: public.
This procedure installs a declared package.
The following tasks are performed in this same order:
All package required packages not previously installed are installed.
All package aliases are created.
The package install script is evaluated in the global namespace.
If this is the first time the package is installed after its declaration, the package first time install script is evaluated in the global namespace.
All package exported commands (either from the package itself or from any not previously installed package it may require) are imported into the global namespace.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
Returns: the empty string.
Effects:
Creates the package aliases.
Those of the evaluated scripts.
Imports the package exported commands into the global namespace.
::Simple::Package::require
?-exact? package ?version?Synopsis: requires a package.
Access mode: public.
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.
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.
::Simple::Package::require-and-install
?-exact? package ?version?Synopsis: requires and installs a package.
Access mode: public.
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.
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.
::Simple::Package::resync
Synopsis: resynchronizes the information about available packages.
Access mode: public.
This command resynchronizes the information about available packages by invoking the unknown
procedure.
Date | Reason |
10-may-2000 | Implementation by Don Porter (donald.porter@nist.gov) |
Arguments: none.
Returns: the empty string.
::Simple::Package::undeclare
packageSynopsis: undeclares a package.
Access mode: public.
This procedure undeclares a declared package.
An error is thrown if the package is installed; use ::Simple::Package::uninstall
to uninstall a package.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
Returns: the empty string.
Effects:
Deletes the package namespaces.
Deletes the classes of object packages declared with declare-package
.
Deletes the types of packages declared with declare-package
.
Forgets a package, but keeps the ifneeded
script, if any.
Notice that unlike ::Simple::Package::declare
which requires all packages required by the package being declared, ::Simple::Package::undeclare
undeclares the given package only.
::Simple::Package::unimport
package namespaceSynopsis: unimports a package exported commands from a namespace.
Access mode: public.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
namespace | namespace | (n/a) | Namespace |
Returns: the empty string.
Effects:
Unimports the package exported commands from the given namespace.
::Simple::Package::uninstall
packageSynopsis: uninstalls a package.
Access mode: public.
This procedure uninstalls a package previously installed via the ::Simple::Package::install
command. The following tasks are performed in this same order:
All package exported commands are unimported from all namespaces they were imported into.
The package uninstall script is executed in the global namespace.
All package aliases are deleted.
An error is thrown if the package is not installed.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
Returns: the empty string.
Effects:
Those of the evaluated script.
Deletes the package aliases.
Deletes the objects of the classes of object packages declared with declare-package
.
Unimports the package exported commands from the namespaces they were imported into.
Notice that unlike ::Simple::Package::install
which installs all packages required by the package being installed, ::Simple::Package::uninstall
uninstalls the given package only.
::Simple::Package::uninstall-and-undeclare
packageSynopsis: uninstalls and undeclares a package.
Access mode: public.
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.
Arguments:
Argument | Type | Default value/ choices | Description |
package | package | (n/a) | Package name |
Returns: the empty string.
Effects:
Forgets a package, but keeps its ifneeded
script, if any.
Notice that unlike ::Simple::Package::install
which installs all packages required by the package being installed, ::Simple::Package::uninstall-and-undeclare
uninstalls the given package only.