SimpleDeclare v1.0 

 The Simple Development Library packages and procedures declaration 

Project: the Simple Development Library.

Table of contents

1. Package description

Synopsis: the Simple Development Library packages and procedures declaration.

Keywords: package, procedure and declaration.

1.1 Overview

This package provides a way to declare packages and procedures in an homogeneous, easily parseable, fully introspectable way. It allows to substitute the comment block which is usually placed on top of each declaration (as this very same overview!) by Tcl-handled text.

Both items (packages and procedures) can be declared with a single command (declare-package or declare-proc, respectively). Every single component needed to either make the item work (such as a procedure argument default value) or to document it (metadata, such as a procedure argument textual description) is provided as arguments to that command. Both items and components can be fully introspected, but metadata is only available if The Simple Development Library -storemetadata option is set when the item is declared.

1.2 Usage

Use declare-package to declare a package. Declared packages metadata can be obtained via the ::Simple::Package::information metadata procedure. Use ::Simple::Package::undeclare to undeclare the package.

The declare-package command encompasses the funcionality provided by the ::Simple::Package::declare command of the SimpleDeclare package, so it is recommended not to directly use the later.

Use declare-proc to declare a procedure. Declared procedures metadata given to declare-proc can be obtained via the ::Simple::Proc::information metadata procedure. Use ::Simple::Proc::delete to delete the procedure.

The declare-proc command encompasses the funcionality provided by the proc-ext command of the SimpleProc package, so it is recommended not to use the later. Further, the -command flag of declare-package allows to declare package commands from within the package declaration, so that declare-proc should only be used for declaration of commands outside packages, should that be needed.

1.3 Examples

# Install the package
package require SimplePackage
::Simple::Package::require-and-install SimpleDeclare

# Let's store the metadata
::Simple::configure -storemetadata true

# Declare a package which declares a procedure
declare-package {

   Package

} -synopsis {

   This is the package synopsis.

} -namespaces {

   ::Namespace

} -variable {

   {
      ::Namespace::Variable
   } -description {
      This is a package variable
   } -value 50

} -error {

   {
      ::Namespace::Error
   } -message {
      Package error
   } -explanation {
      This is a package error.
   }

} -command {

   {

      ::Namespace::procedure

   } -synopsis {

      This is the procedure synopsis.

   } -arguments {
      {-modify     boolflag   {Whether to modify the package variable}}
      { variable   integer    {New package variable value}}
   } -effects {

      * Modifies the package variable if -modify is given.

   } -body {

      # Must modify the package variable
      if {[::Simple::Argument::information flaggiven -modify]} {

         # Modify it
         set ::Namespace::Variable $variable
      }

      # Package variable value too big
      if {$::Namespace::Variable > 99} {

         # Throw the package error
         ::Simple::Error::throw ::Namespace::Error

      # Correct package variable value
      } else {

         # Display it
         puts "Package variable = $::Namespace::Variable"
      }
   }
}

# Install the package
::Simple::Package::install Package

# Invoke the package procedure

# This displays the following:
#   |Package variable = 50
::Namespace::procedure 77

# This displays the following:
#   |Package variable = 88
::Namespace::procedure -modify 88

# This displays the following:
#   |Package error (::Namespace::Error)
catch {::Namespace::procedure -modify 120} result
puts "$result ($::errorCode)"

# Obtain the package metadata
# This displays the following:
#   |-assumptions = 
#   |  -copyright = 
#   |    -details = 
#   |    -effects = * Modifies the package variable if -modify is given.
#   |   -examples = 
#   |    -history = 
#   |   -keywords = 
#   |-limitations = 
#   |   -overview = 
#   |    -project = 
#   | -references = 
#   |    -remarks = 
#   |  -resources = 
#   |    -returns = 
#   |   -synopsis = This is the procedure synopsis.
#   |       -todo = 
#   |    -version = 1.0
array set metadata [::Simple::Proc::information metadata ::Namespace::procedure]
foreach element [lsort [array names metadata]] {
   puts [format {%12s = %s} -$element $metadata($element)]
}

1.4 History

1.5 Copyright

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

2. Package public API

Paradigm: procedural.

Requisites: SimpleProc.

2.1 Types

None.

2.2 Options

None.

2.3 Namespaces

1. ::Simple::Declare

2. ::Simple::Declare::Priv

2.4 Commands

2.4.1 ::Simple::Declare::cget

Synopsis: gets the package options.

Details: see section 4.1.

2.4.2 ::Simple::Declare::configure

Synopsis: configures the package options.

Details: see section 4.2.

2.4.3 declare-package package ?-version version? ?-project string? ?-synopsis string? ?-module choice? ?-overview string? ?-usage string? ?-api string? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-keywords list? ?-examples string? ?-paradigm choice? ?-namespaces namespace-list? ?-error declaration? ?-type declaration? ?-class declaration? ?-variable declaration? ?-command declaration? ?-option declaration? ?-requisites packagerequisite-list? ?-assumptions string? ?-resources string? ?-limitations string? ?-effects string? ?-details string? ?-references string? ?-remarks string? ?-todo string? ?-cmid string? ?-sprs string? ?-smrs string? ?-history string? ?-copyright string? ?-install script? ?-uninstall script? ?-firsttimeinstall script?

Synopsis: declares a package.

Details: see section 4.3.

2.4.4 declare-proc procedure ?-version version? ?-project string? ?-synopsis string? ?-overview string? ?-access choice? ?-alias name? ?-arguments extendedarg-list? ?-returns string? ?-parseflags extbool? ?-checktype extbool? ?-keywords list? ?-examples string? ?-assumptions string? ?-resources string? ?-limitations string? ?-effects string? ?-details string? ?-references string? ?-remarks string? ?-todo string? ?-history string? ?-copyright string? ?-body script?

Synopsis: declares a procedure.

Details: see section 4.4.

2.5 Errors

2.5.1 ::Simple::Declare::REQUIRES-NAMESPACES

Message: flag requires -namespaces.

Explanation: giving the flag flag requires giving the -namespaces flag also.

Corrective action: provide the -namespaces flag in the package declaration.

2.5.2 ::Simple::Declare::OPTION-ARRAY

Message: derived array type "type" for option "option".

Explanation: option option has a derived array type type, but that is not allowed.

2.5.3 ::Simple::Declare::PRIV-PROC-IN-NON-PRIV-NAMESPACE

Message: private procedure "procedure" can't live in non-private namespace "namespace".

Explanation: the procedure procedure is private because its access mode is "private", but it is living in a non-private namespace namespace not-matching the pattern *::Priv*.

Corrective action: either declare the procedure as non-private or place it in a private namespace.

2.5.4 ::Simple::Declare::NON-PRIV-PROC-IN-PRIV-NAMESPACE

Message: non-private procedure "procedure" can't live in private namespace "namespace".

Explanation: the procedure procedure is non-private because its access mode is not "private", but it is living in a private namespace namespace matching the pattern *::Priv*.

Corrective action: either declare the procedure as private or place it in a non-private namespace.

2.5.5 ::Simple::Declare::EXPORTED-OR-ALIASED-GLOBAL-PROC

Message: exported or aliased global namespace procedure "procedure".

Explanation: a procedure is trying to be exported or aliased from the global namespace, but that is not allowed.

2.5.6 ::Simple::Declare::NOT-DECLARED-AS-EXPORTED

Message: package "package" declaration does not include "procedure" as an exported command.

Explanation: exported procedure procedure belongs to package package (because the procedure namespace belongs to the package), but it was not specified as an exported command when the package was declared (flag -exportedcommands of ::Simple::Package::declare or declare-package).

Corrective action: either declare the procedure non-exported, add the command to the -exportedcommands list in the package declaration or remove the -exportedcommands flag.

2.5.7 ::Simple::Declare::DECLARED-AS-EXPORTED

Message: package "package" declaration includes "procedure" as an exported command.

Explanation: non-exported procedure procedure belongs to package package (because the procedure namespace belongs to the package), but it was specified as an exported command when the package was declared (flag -exportedcommands of ::Simple::Package::declare or declare-package).

Corrective action: either declare the procedure exported, delete the command from the -exportedcommands list in the package declaration or remove the -exportedcommands flag.

2.5.8 ::Simple::Declare::NOT-DECLARED-AS-ALIAS

Message: package "package" declaration does not include "alias" as an alias for command "procedure".

Explanation: procedure procedure belongs to package package (because the procedure namespace belongs to the package) and it is declared with an alias for alias, but this alias was not specified when the package was declared (flag -aliases of ::Simple::Package::declare or declare-package).

Corrective action: either declare the procedure non-aliased, add the alias to the -aliases list in the package declaration or remove the -aliases flag.

2.5.9 ::Simple::Declare::DECLARED-AS-ALIAS

Message: package "package" declaration includes "alias" as an alias for command "procedure".

Explanation: procedure procedure belongs to package package (because the procedure namespace belongs to the package) and it is declared with no alias, but alias alias was specified when the package was declared (flag -aliases of ::Simple::Package::declare or declare-package).

Corrective action: either declare the procedure as aliased, delete the alias from the -aliases list in the package declaration or remove the -aliases flag.

2.5.10 ::Simple::Declare::ALIAS-NAMESPACE-NOT-THAT-OF-THE-COMMAND

Message: alias namespace "command alias" is not that of the command "command".

Explanation: a command alias is qualified with a namespace which is not that of the command, but that is not allowed.

Corrective action: either make the alias unqualified or use the command namespace.

2.5.11 ::Simple::Declare::NON-EXISTING-OPTION

Message: package "package" doesn't have an option "bad option".

Explanation: package package does not have an option named bad option.

Corrective action: provide an option from the package list of options.

2.5.12 ::Simple::Declare::CLASS-IN-NON-OBJECT-PACKAGE

Message: class declaration in non-object package.

Explanation: a class has tried to be declared in a package whose paradigm is not object.

Corrective action: either delete the -class flags in the package declaration or ensure its -paradigm is "object".

2.5.13 ::Simple::Declare::NO-NON-EXTRA-PACKAGE

Message: non-extra package "package" is not declared.

Explanation: an extra package is being declared, but the non-extra one, package, has not been declared before.

Corrective action: ensure the non-extra package is declared before the extra one.

2.5.14 ::Simple::Declare::FLAG-NOT-ALLOWED-EXTRA

Message: flag "flag" not allowed in extra package.

Explanation: the flag flag is not allowed in extra packages.

2.5.15 ::Simple::Declare::NAMESPACE-NOT-OWNED

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

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

Corrective action: either place the class in a different namespace, add the namespace to the package namespaces or add the package owning the namespace to the package list of requisites.

3. Package further information

None.

4. Package command details

4.1 ::Simple::Declare::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::Declare::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 declare-package package ?-version version? ?-project string? ?-synopsis string? ?-module choice? ?-overview string? ?-usage string? ?-api string? ?-exportedcommands qualifiedname-list? ?-aliases list-list? ?-keywords list? ?-examples string? ?-paradigm choice? ?-namespaces namespace-list? ?-error declaration? ?-type declaration? ?-class declaration? ?-variable declaration? ?-command declaration? ?-option declaration? ?-requisites packagerequisite-list? ?-assumptions string? ?-resources string? ?-limitations string? ?-effects string? ?-details string? ?-references string? ?-remarks string? ?-todo string? ?-cmid string? ?-sprs string? ?-smrs string? ?-history string? ?-copyright string? ?-install script? ?-uninstall script? ?-firsttimeinstall script?

(Exported from ::Simple::Declare).

4.3.1 Command description

Synopsis: declares a package.

Access mode: exported.

Keywords: package and declaration.

4.3.1.1 Overview

This procedure provides a way to declare packages. It acts as an interface to ::Simple::Package::declare to which the package, -version, -requisites, -namespaces, -exportedcommands, -aliases, -install, -uninstall and -firsttimeinstall arguments are passed.

The -synopsis flag is mandatory.

The -module flag can be set to either "implementation", "test", "extra" or "demonstration", specifying whether the Tcl package is the actual package implementation, the test package (see simpletest), the extra package or a demonstration package. For extra packages, several flags are forbidden. In addition, extra packages classes can live in and aliases can point to the namespaces of the non-extra one plus those of its directly required packages.

The -paradigm flag can be set to either "procedural" or "object". Object packages imply the loading of SimpleClass, and allow the declaration of package classes.

The -variable flag allows to create package variables. Its argument is a variable declaration intended to be the arguments of a call to ::Simple::Variable::declare. This flag can be given multiple times.

The -option flag allows to create package options. Its argument is an option declaration. The first element is the option flag and the rest is intended to be the arguments of a call to ::Simple::Variable::declare but for the variable name. A value is required for each option, so that option declarations must have a -value flag. Derived array types are not allowed for options. Options are internally stored in the package main namespace (that is the first namespace in the list of the package namespaces). For this reason, giving the -option flag requires the -namespaces flag also. This flag can be given multiple times. The package options values are configured and got via the configure and cget package commands, respectively. These two procedures must currently be created by the user.

The -type flag allows to declare package types. Its argument is a type declaration intended to be the arguments of a call to ::Simple::Type::declare. This flag can be given multiple times.

The -error flag allows to declare package errors. Its argument is an error declaration intended to be the arguments of a call to ::Simple::Error::declare. This flag can be given multiple times.

The -command flag allows to declare package commands. Its argument is a command declaration intended to be the arguments of a call to ::Simple::Declare::declare-proc. This flag can be given multiple times.

The -class flag allows to declare package classes. Its argument is a class declaration intended to be the arguments of a call to ::Simple::Class::declare-class. This flag can be given multiple times. The classes must live in either one of the package namespaces or to in a namespace belonging to one of the package direct requisites.

The variables, options, types and errors are created in the package install script and deleted in the package uninstall script, so that uninstalling and then reinstalling a package resets them all. Uninstalling a package also deletes all the objects of the package classes.

The commands and classes are created in the package first time install script, so that they are deleted upon deleting the corresponding namespaces, which is only done when the package is undeclared.

All other arguments are metadata, and are stored or ignored depending on whether The Simple Development Library -storemetadata option is set when the package is declared, but for the -api and -firsttimeinstall flags which are never stored.

4.3.2 Command public API

Arguments: (flag parsing disabled)

Returns: the empty string.

Effects:

• Creates the package namespaces.

• Requires the required packages.

• Exports exported commands from their namespaces.

• Provides the package.

4.3.3 Command further information

4.3.3.1 Details

• Package options are stored in a variable named %Options%(flag) (where flag is the option flag) in the package main namespace.

4.3.3.2 References

• The ::Simple::Package::declare procedure.

4.3.3.3 Remarks

• The -namespaces, -exportedcommands, -aliases, -requisites and -option flags are forbidden for "extra" packages.

• The -aliases and -exportedcommands are optional but, if given, their contents must exactly match the actual aliases and exported commands within the package, respectively.

• The order of the flags is irrelevant but their parameters can not start by an hyphen.

4.4 declare-proc procedure ?-version version? ?-project string? ?-synopsis string? ?-overview string? ?-access choice? ?-alias name? ?-arguments extendedarg-list? ?-returns string? ?-parseflags extbool? ?-checktype extbool? ?-keywords list? ?-examples string? ?-assumptions string? ?-resources string? ?-limitations string? ?-effects string? ?-details string? ?-references string? ?-remarks string? ?-todo string? ?-history string? ?-copyright string? ?-body script?

(Exported from ::Simple::Declare).

4.4.1 Command description

Synopsis: declares a procedure.

Access mode: exported.

Keywords: procedure and declaration.

4.4.1.1 Overview

This procedure provides a way to declare other procedures. It acts as an interface to ::Simple::Proc::create to which the -parseflags, -checktype, procedure, -arguments and -body arguments are passed.

The -synopsis flag is mandatory.

If -access is not given, it is set to either "private" or "public" depending on whether the namespace is private or not, respectively; private namespaces are those matching the pattern *::Priv. If given, an error is thrown if a public procedure is placed in a private namespace or viceversa.

If the -access mode is "exported" and the procedure namespace is not the global one, the procedure must be exported from its namespace and imported into the global one. If the procedure does not belong to a declared package (because the command namespace does not belong to any declared package), the export and import into the global namespace is performed here; otherwise it is the package declaration responsibility to perform the import and the export, and the procedure must have been specified as an exported command when the package was declared (flag -exportedcommands of ::Simple::Package::declare or declare-package; the flag is optional in the later case), otherwise an error is thrown. If a command was included in the -exportedcommands list of its package declaration but it is not declared as exported here, an error is thrown as well.

If the -alias flag is given, an alias for the procedure must be created. If the procedure does not belong to a declared package (because the command namespace does not belong to any declared package), the alias is created here; otherwise it is the package declaration responsibility to create the alias, and the alias must have been specified when the package was declared (flag -aliases of ::Simple::Package::declare or declare-package; the flag is optional in the later case), otherwise an error is thrown. In any case, the alias must be unqualified or qualified, but in the later case the namespace must be that of the command.

All other arguments are metadata, and are ignored or stored depending on whether The Simple Development Library -storemetadata option is set when the package is declared.

4.4.1.2 Examples

# A procedure exported into the global namespace
declare-proc {
   ::foo::bar
} -synopsis {
   An example of exported procedure.
} -access {
   exported
} -arguments {
   { int1             integer        {First argument}}
   {-flag             float 1.0      {A flag}}
   { int2             integer        {Second argument}}
   { int3             integer        {Third argument}}
} -checktype {
   true
} -body {
   exported
   puts "int1      = <$int1>"
   puts "flag      = <$flag> "
   puts "int2      = <$int2>"
   puts "int3      = <$int3>"
}

4.4.2 Command public API

Arguments: (flag parsing disabled)

Returns: a list with the following elements:

Effects:

• Creates the procedure named procedure.

• If the procedure -access mode is "exported", the procedure namespace is not the global one and the procedure does not belong to a declared package, the procedure is exported from its namespace and imported into the global one.

• If the -alias flag is given and the procedure does not belong to a declared package, an alias for the procedure is created.

4.4.3 Command further information

4.4.3.1 References

• The ::Simple::Proc::create procedure.

4.4.3.2 Remarks

• The order of the -parseflags and -checktype flags is irrelevant but must appear before the procedure name.

• The order of the other flags is irrelevant also but must appear after the procedure name and their parameters can not start by an hyphen.