|
::Simple
namespace. Each command has one access type, either
exported, public or private:
::Simple::*::Priv
.
configure
command in
the package main namespace and queried via the cget
command in the
same namespace.
Each Simple Library package is a single Tcl file. Each file is divided into
two sections: the package definition and the regression testing sections.
The package definition contains the package declaration together with its
options, variables, errors and procedures. The regression testing section
contains a collection of test cases intended to fully test the functionality
provided by the package. More sections may be added in the future, for
exaple one for benchmarking the package.Each package file is structured as follows:
if {[string compare $::SIMPLE(PackageMode,package) test]} {
Package definition section
} else {
Regression testing section
}
where package
is the name of the package. This way,
either the regression testing or the package definition section is exposed
depending on whether the package mode (stored in the global array
SIMPLE
, first index PackageMode
, indexed through the
second index by package name) is definition
or test
,
respectively. The Simple Library pkgIndex.tcl
file sets each
element of the package mode array to definition
or
test
depending on whether the required package is named
package
or package-test
, respectively,
as expected by simpletest, the
regression testing utility.
|
Tag | Program | Package | Command | Description |
program | Program name | |||
package | Package name | |||
command | Command name | |||
version | Component version | |||
purpose | Component one line description | |||
access | Command access mode [1] | |||
alias | Command alias | |||
overview | Component multi-line overview | |||
usage | Component usage [2] | |||
arguments | Command arguments | |||
returns | Command return value | |||
keywords | Component keywords | |||
examples | Examples on how to use the component | |||
namespaces | Package list of namespaces | |||
commands | Package list of commands | |||
variables | Package list of variables | |||
options | Package list of options | |||
requires | Component list of required packages | |||
assumes | Component assumptions | |||
resources | Resources required by the component | |||
limitations | Component limitations | |||
effects | Command effects [3] | |||
diagnostics | Program list of error messages and explanations | |||
details | Component implementation details | |||
seealso | Component references | |||
remarks | Component important remarks | |||
todo | Component to do list | |||
bugs | Component known bugs | |||
history | Component history | |||
copyright | Component copyright notice | |||
[1] Exported, public or private.
[2] A short usage message for programs, a longer usage description
for packages and commands.
[3] Command effects outside its package scope, such as variables modified
thorugh upvar , those of evaluated scripts, or items (command,
variables, namespaces, aliases, ...) creations or deletions.
|
|
command subcommand
).
FOO_BAR_GEE
.
implicitCheckType
.
ArgumentNames
.
::Simple::ScriptHead
.
parse-qualify-name
.
importedinto
.
SimpleExtProc
.
-storedetails
.
###
), and the
code is commented in such as way that each procedure pseudocode is exposed
when deleting everything in its body but the triple hash comments.
set foo bar
is used instead of set foo
"bar"
.
set foo {bar gee}
is used instead of set foo "bar
gee"
(but, of course, set foo "bar $gee"
).
variable
command is never used.
information
and move
commands resembling the
info
and rename
Tcl intrinsic commands.
set foo [list]
is used when an empty list is needed, but
set foo {}
when the null string is wanted.
string compare
is used to check the equality of strings instead of
==
.
[llength $list] == 0
is used to check for an empty list.
format
command is sometimes used to escape from
quoting hell. For example,
set subexpression [format {$%s == %s} $number $atom]
instead of
set subexpression "\$$number == $atom"
.
(for a much better example, see the
::Simple::Subcommand::Priv::create-base-command
in the
SimpleSubcommand package, where
some twenty lines of code are escpaed with this method).
Although this is slower, the improved legibility pays off in non-critical
procedures
return
is avoided unless strictly necessary. Most
procedures return to its caller by exiting through the end of its body, that
is, multiple return points are avoided. When a value must be returned, the
return value of the procedure body last command is implicitely used. Many
times a local variable named answer
is set to contain the
procedure return value, and the last command of the procedure body is
set answer
. This is also against what is generally considered
good style, but return
is slow, and I prefer to avoid it.