SimpleSubcommand v1.0
The Simple Development Library subcommand procedures handling
Project: the Simple Development Library.
::Simple::Subcommand::cget::Simple::Subcommand::configureproc-sub procedure arguments body::Simple::Subcommand::delete procedure::Simple::Subcommand::information exists command::Simple::Subcommand::information subcommands command::Simple::Subcommand::move sourceProcedure targetProcedure::Simple::Subcommand::CANT-CREATE::Simple::Subcommand::CANT-DELETE-OR-RENAME::Simple::Subcommand::NON-EXISTING-COMMAND::Simple::Subcommand::cget::Simple::Subcommand::configureproc-sub procedure arguments body::Simple::Subcommand::delete procedure::Simple::Subcommand::information exists command::Simple::Subcommand::information subcommands command::Simple::Subcommand::move sourceProcedure targetProcedureSynopsis: the Simple Development Library subcommand procedures handling.
Keywords: procedure, command, subcommand, family, composite and ensemble.
This package allows to handle subcommand procedures. Subcommands is The Simple Development Library term for the concept named ensemble commands, command families or composite commands in other contexts. Basically one can define the foo bar and foo gee commands, which are subcommands bar and gee for the foo base command; each subcommand has its own arguments.
Procedures are provided to create, delete, copy, rename and get information about subcommand procedures.
Subcommand procedures are create via the proc-sub command. Such subcommand procedures behave similarly to the built-in Tcl commands with subcommands (such as string or array):
They are called simply by providing the command and subcommand name, such as foo bar.
When invoking a base command with no subcommand, an error is thrown informing of the allowed subcommands.
When called with a bad number of arguments for a particular subcommand, an error is thrown informing of the argument list for that subcommand.
Subcommand procedures can be deleted via ::Simple::Subcommand::delete or renamed via ::Simple::Subcommand::move. The ::Simple::Subcommand::information procedure provides several subcommands to query information about subcommand procedures: exists and subcommands.
# Install the package
package require SimplePackage
::Simple::Package::require-and-install SimpleSubcommand
# Create some subcommands
proc-sub {foo bar} arg1 {}
proc-sub {foo gee} arg1 {}
# Assess whether foo is a subcommand base command
# This displays the following:
# |Yes, foo is a subcommand base command
if {[::Simple::Subcommand::information exists foo]} {
puts {Yes, foo is a subcommand base command}
} else {
puts {No, foo is not a subcommand base command}
}
# Display the list of subcommands for foo
# This displays the following:
# |gee bar
puts [::Simple::Subcommand::information subcommands foo]
# Delete the "foo bar" subcommand
::Simple::Subcommand::delete {foo bar}
# Display the list of subcommands for foo
# This displays the following:
# |gee
puts [::Simple::Subcommand::information subcommands foo]
# Rename the "foo gee" subcommand to "foo bar"
::Simple::Subcommand::move {foo gee} {foo bar}
# Display the list of subcommands for foo
# This displays the following:
# |bar
puts [::Simple::Subcommand::information subcommands foo]
# Rename the "foo bar" subcommand to "zoo fii"
::Simple::Subcommand::move {foo bar} {zoo fii}
# Assess whether foo is a subcommand base command
# This displays the following:
# |No, foo is not a subcommand base command
if {[::Simple::Subcommand::information exists foo]} {
puts {Yes, foo is a subcommand base command}
} else {
puts {No, foo is not a subcommand base command}
}
| Date | Reason |
| 23-apr-2000 | First public release, version 0.2 |
| 10-sep-2001 | Second public release, version 0.4 |
| 17-feb-2003 | Third public release, version 0.5 |
| 29-mar-2003 | Extra package, version 0.5.1 |
| 24-oct-2004 | Bug 8 correction, version 0.5.2 |
| 24-oct-2004 | Copy functionality deleted, version 0.5.3 |
| 10-feb-2005 | Bug 9 correction, version 0.5.4 |
| 22-jun-2005 | The Simple Development Library version 1.0 |
Copyright (C) 1999-2005, Juan C. Gil (jgil@gmv.es).
Paradigm: procedural.
Requisites: SimpleNamespace 1.0.
None.
None.
::Simple::Subcommand
::Simple::Subcommand::Priv
::Simple::Subcommand::cgetSynopsis: gets the package options.
Details: see section 4.1.
::Simple::Subcommand::configureSynopsis: configures the package options.
Details: see section 4.2.
proc-sub procedure arguments bodySynopsis: creates a subcommand procedure.
Details: see section 4.3.
::Simple::Subcommand::delete procedureSynopsis: deletes a subcommand procedure.
Details: see section 4.4.
::Simple::Subcommand::information exists commandSynopsis: returns whether a procedure is a base command procedure.
Details: see section 4.5.
::Simple::Subcommand::information subcommands commandSynopsis: returns a base command procedure subcommand list.
Details: see section 4.6.
::Simple::Subcommand::move sourceProcedure targetProcedureSynopsis: renames a subcommand procedure.
Details: see section 4.7.
::Simple::Subcommand::CANT-CREATEMessage: can't create subcommand "command subcommand": procedure "command" already exists.
Explanation: the subcommand procedure "command subcommand" could not be created because a procedure named as the subcommand base command (command) already exists.
Corrective action: either delete that procedure or choose another name for the subcommand base command.
::Simple::Subcommand::CANT-DELETE-OR-RENAMEMessage: can't delete or rename "procedure": command doesn't exist.
Explanation: the procedure "procedure" could not be delete or renamed because it does not exist.
::Simple::Subcommand::NON-EXISTING-COMMANDMessage: "command" isn't a subcommand base command procedure.
Explanation: the subcommand list could not be retrieved because command is not a subcommand base command procedure. Either it is a regular procedure, a subcommand procedure or does not exist.
Subcommand procedures are implemented with the aid of a base procedure named as the command. That is, if a subcommand procedure named foo bar is created, two procedures are actually created: the subcommand procedure itself (named foo bar) and the base command (named foo). The base command simply acts as a dispatcher for the actual subcommand procedures. It also catches the subcommand procedure errors and throws explanation errors when appropriate.
For this reason, it is slightly faster to invoke a subcommand procedure as {foo bar} or foo\ bar instead of foo bar, as the dispatch from the base command is avoided.
::Simple::Subcommand::cgetSynopsis: gets the package options.
Access mode: public.
Arguments: none.
Returns: the requested option value or the whole list of options if none specified.
::Simple::Subcommand::configureSynopsis: configures the package options.
Access mode: public.
Arguments: none.
Returns: the "package with no options" error is thrown.
proc-sub procedure arguments body(Alias for ::Simple::Subcommand::create).
Synopsis: creates a subcommand procedure.
Access mode: public.
Keywords: procedure, command, subcommand, family, composite and ensemble.
This procedure acts as an interface to the proc command to create subcommand procedures. Such subcommand procedures behave similarly to Tcl subcommands (such as string or array) in terms of error handling: if the base command is invoked with an incorrect subcommand, an error is thrown informing of the allowed subcommands; also, when a subcommand is called with a bad number of arguments, an error is thrown informing of the argument list for that subcommand.
The syntax for the argument list is identical to that accepted by the proc command.
# Create some subcommands
proc-sub {foo bar} arg1 {puts $arg1}
proc-sub {foo gee} {arg1 {arg2 99} args} {puts "$arg1 $arg2 $args"}
Arguments:
| Argument | Type | Default value/ choices | Description |
| procedure | commandname | (n/a) | Base command and subcommand pair |
| arguments | canonicalarg-list | (n/a) | Subcommand procedure argument list |
| body | script | (n/a) | Subcommand procedure body |
Returns: the empty string.
Effects:
Creates a command named procedure.
Creates a base command procedure should this be the first subcommand.
A base command is created with the given base command name. The base command body simply calls the ::Simple::Subcommand::Priv::base-command procedure passing all arguments received. The actual subcommand procedure is then created with the name command subcommand where command is the base command name and subcommand is the subcommand name.
The proc-ext procedure.
::Simple::Subcommand::delete procedureSynopsis: deletes a subcommand procedure.
Access mode: public.
This command is similar to the rename command when its second argument is empty, but works for subcommand procedures only.
Arguments:
| Argument | Type | Default value/ choices | Description |
| procedure | commandname | (n/a) | Base command and subcommand pair |
Returns: the empty string.
Effects:
Deletes the procedure named procedure.
The subcommand procedure is deleted and, should it be the last one, the base command is deleted as well.
::Simple::Subcommand::information exists commandSynopsis: returns whether a procedure is a base command procedure.
Access mode: public.
Arguments:
| Argument | Type | Default value/ choices | Description |
| command | name | (n/a) | Base command name |
Returns: whether the procedure is a base command procedure.
A command is considered a base command procedure if its body contains the base command given by ::Simple::BaseCommandTag.
The ::Simple::Proc::information issubcommand procedure.
::Simple::Subcommand::information subcommands commandSynopsis: returns a base command procedure subcommand list.
Access mode: public.
Arguments:
| Argument | Type | Default value/ choices | Description |
| command | name | (n/a) | Base command name |
Returns: the base command procedure subcommand list.
The ::Simple::Proc::information subcommands procedure.
The returned list does not contain subcommands with a percent sign in its name are those are assumed to be internal to The Simple Development Library.
::Simple::Subcommand::move sourceProcedure targetProcedureSynopsis: renames a subcommand procedure.
Access mode: public.
This command is similar to the rename command when its second argument is non-empty, but works for subcommand procedures only.
Arguments:
| Argument | Type | Default value/ choices | Description |
| sourceProcedure | name | (n/a) | Source base command and subcommand pair |
| targetProcedure | name | (n/a) | Target base command and subcommand pair |
Returns: the empty string.
Effects:
Renames the procedure named sourceProcedure to targetProcedure.
The source subcommand procedure is deleted and the target is created.
If the target procedure namespace does not exists, it is created. This mimics the behaviour of the rename command.
Allow to rename from subcommand to regular procedure and viceversa.