%META:TOPICINFO{author="TWikiGuest" date="1099288894" format="1.0" version="1.1"}%
---+ CommandSet

CommandSets are the extension point for TWikiShellContrib. Without them, it's only an empty shell (no pun intended)

---++ Creation

CommandSets are perl modules that define one or more of the following subs:

| *Sub* | *Description*|
| run | Command execution |
| smry | One-line help to be used by "help" to sumarize all the commands |
| help | Complete help to be shown by the "help <command>" command |
| run_<subcommand> | SubCommand execution |
| smry_<subcommand> | One-line help to be used by "help" to sumarize all the commands |
| help_<subcommand> | Complete help to be shown by the "help <command> <subcommand>" command |

There are several ways to implement CommandSet. The first thing to understand is how the commands map to perl modules and handler subs. See the following table:

| *command/subcommand* | *Module Name* | *Implemented Handlers * |
| dump | Dump | run, smry, help |
| dump config | Dump | run_config, smry_config, help_config |
|^ | Dump::Config | run, smry, help |
| dump handlers | Dump | run_handlers, smry_handlers, help_handlers |
|^ | Dump::Handlers | run, smry, help |


The CommandSet can be on any TWiki subpackage and can be imported using the =import= command. The special case are CommandSet under the TWiki::Contrib::CommandSet package (anywhere in @INC) which are "discovered" and imported at startup.

Check the bundled CommandSets for examples on how to implement them.

---++ Initializing CommandSet

Any CommandSet that needs an special initialization when imported can use the following hook:

---+++ onImport($shell,$config)
Called when the CommandSet is being imported.

---++ Loading a CommandSet to the Shell

To load a CommandSet, use:

<verbatim>
	import <command>
</verbatim>

or

<verbatim>
	import <CommandSet_module_without_prefix>
</verbatim>

if it's a core CommandSet, or 

<verbatim>
	import <CommandSet_module>
</verbatim>

if not.

Also, if the CommandSet is in the package TWiki::Contrib::CommandSet it will be imported automatically on it first invocation (for example, the Dump CommandSet will be loaded automatically when the dump, dump config or dump handlers commands are called). 

---++ CommandSet contract

All the handlers (run, help and smry) will be called with the following parameters (in order):

|*Parameter*|*Description*|
|$shell| A reference to the shell object |
|$config| A reference to the config object|
|@args| The list of parameters passed to the command|
