TWiki Shell
Purpose
TWikiShellContrib is a shell that can be use to replace all twiki command line scripts with a single interface. Each command available in the twikishell is also available as a command line option (i.e: to invoke the
help
command, type
twikishell help
)
Usage
In the TWiki home directory, there is an uber-command:
This will fire the shell. The following command line options are available:
Option |
Description |
-v |
Verbose mode (Verbosity level 1) (Default) |
-vv |
Very Verbose mode (Verbosity level 2) |
-q |
Quiet Operation (Verbosity level 0) |
-d |
Turns on debugging (prints debug statements to console) |
<command> |
Execute the specified command. Must be the last option in the cli. i.e: twikishell package CalendarPlugin |
Operation
When the shell starts, it first try to load the
.twikirc
file for the stored configuration. If it can't find it, it will create an empty configuration, and is up to each CommandSet to reconfigure themselves.
On a bare installation (without any CommandSets installed), you have the following available commands:
Command |
Description |
help |
Shows a list of available commands |
help <command> |
Shows a detailed help of the specified command |
help <command> <subcommand> |
Shows a detailed help of the specified subcommand |
exit , q , quit |
Quits the shell |
import <perl module> |
Imports a perl module and scan it for new commands to be added to the shell |
verbose <level> |
Changes the verbosity level to either 1 or 2 |
quiet |
Changes the verbosity level to 0 |
debug |
Set debugging On and Off. Usage: debug [on/off] |
The config file is a dump (using
CPAN:Data::Dumper) of the configuration object used internally
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 defines 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 initializacion 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:
import <command>
or
import <CommandSet_module_without_prefix>
if it's a core CommandSet, or
import <CommandSet_module>
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 |
Warning: Can't find topic Plugins.TWikiShellBundledCommandSets
Warning: Can't find topic Plugins.TWikiShellConfigObject
Warning: Can't find topic Plugins.TWikiShellServices
Installation
- Make sure that CPAN:Term::Shell is installed (either in the perl distribution or locally in twiki)
- Unzip
TWikiShellContrib.zip
in your twiki installation directory. Content: File: | Description: |
data/TWiki/CommandSet.txt | |
data/TWiki/TWikiShellBundledCommandSets.txt | |
data/TWiki/TWikiShellConfigObject.txt | |
data/TWiki/TWikiShellContrib.txt | |
data/TWiki/TWikiShellServices.txt | |
data/TWiki/UsingBuildContribAndTWikiShell.txt | |
lib/TWiki/Contrib/CommandSet/Apache.pm | |
lib/TWiki/Contrib/CommandSet/Apache/Conf.pm | |
lib/TWiki/Contrib/CommandSet/Apache/Httpd.pm | |
lib/TWiki/Contrib/CommandSet/Build.pm | |
lib/TWiki/Contrib/CommandSet/Dump.pm | |
lib/TWiki/Contrib/CommandSet/Package.pm | |
lib/TWiki/Contrib/CommandSet/Plugin.pm | |
lib/TWiki/Contrib/CommandSet/Plugin/Create.pm | |
lib/TWiki/Contrib/CommandSet/Plugin/Create/TWikiPlugin.txt_template | |
lib/TWiki/Contrib/CommandSet/Plugin/Create/build.pl_template | |
lib/TWiki/Contrib/CommandSet/Plugin/Develop.pm | |
lib/TWiki/Contrib/CommandSet/Plugin/PutBack.pm | |
lib/TWiki/Contrib/CommandSet/RunTest.pm | |
lib/TWiki/Contrib/CommandSet/RunTest/Conf.pm | |
lib/TWiki/Contrib/CommandSet/TWiki.pm | |
lib/TWiki/Contrib/CommandSet/TWiki/Conf.pm | |
lib/TWiki/Contrib/TWikiShellContrib/Common.pm | |
lib/TWiki/Contrib/TWikiShellContrib/Config.pm | |
lib/TWiki/Contrib/TWikiShellContrib/DirHandling.pm | |
lib/TWiki/Contrib/TWikiShellContrib/Help.pm | |
lib/TWiki/Contrib/TWikiShellContrib/Standard.pm | |
lib/TWiki/Contrib/TWikiShellContrib/TWikiShell.pm | |
lib/TWiki/Contrib/TWikiShellContrib/Zip.pm | |
twikishell | |
If you have a non-standard instalation, then move the files wherever you need them to be.
Settings
- Short description
- Set SHORTDESCRIPTION = TWiki shell to access TWiki from the command line
- Name of the perl package
- Set STUB = TWiki::Contrib::TWikiShellContrib
Contrib Info
Related Topics: TWiki:Codev.TWikiShell