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:

• twikishell

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	Shows a detailed help of the specified command
help	Shows a detailed help of the specified subcommand
exit, q , quit	Quits the shell
import	Imports a perl module and scan it for new commands to be added to the shell
verbose	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 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
run_	SubCommand? 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

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:

   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

Bundled CommandSets

TWikiShellContrib is distributed with some CommandSets aimed at TWiki:Codev.TWikiExtension development.

TWiki::Contrib::CommandSet::Dump

This is a sample CommandSet. Used to dump various debug informations:

Command	Description
dump	Shows the help for the dump subcommands
dump config	Dumps the config
dump handlers	Dumps the registered handlers

TWiki::Contrib::CommandSet::Apache

Used to manipulate the apache config file that needs to be modified to install twiki (usually the httpd.conf, but can be any file)

Command	Description
apache	Shows the summary for the apache subcommands
apache add	Adds a TWiki configuration to Apache
apache delete	Removes a TWiki configuration from Apache

apache add

SYNOPSIS
     apache add <basepath>

DESCRIPTION
      This command will install the current $TWIKI_ROOT
     in the Apache config file specified during TWikiShell 
     configuration. The installed TWiki will be under 
     <basepath>
      It scans the file for the =<IfModule mod_alias.c>= line
     to determine where to put the install information.
     This command creates a tipical *secured* twiki install,
     that is, only bin and pub will be visible from the browser.

EXAMPLE
     twikishell apache add MyTWikiInstall

        Will add the following lines to the Apache config file:

        ##################################BEGIN MyTWikiInstall
        alias /MyTWikiInstall/pub $TWIKI_ROOT/pub

        <Directory "$TWIKI_ROOT/pub">
             AllowOverride All
             Allow From All
        </Directory>

        alias /MyTWikiInstall/bin $TWIKI_ROOT/bin

        <Directory "$TWIKI_ROOT/bin">
             AllowOverride All
             Allow From All
            Options ExecCGI
            SetHandler cgi-script
        </Directory>
        #################################################

        Thus installing $TWIKI_ROOT in the /MyTWikiInstall path

apache delete

SYNOPSIS
     apache delete <basepath>

DESCRIPTION
     This command will delete from the Apache config file the install
     created by =apache add= that is pointed by <basepath>.

     It will look for the first line created by the =apache add= subcommand.
     A backup of the original file is made before the changes are applied.

EXAMPLE
     twikishell apache delete MyTWikiInstall

        Will look for the line
            ##################################BEGIN MyTWikiInstall

        and delete that installation.

TWiki::Contrib::CommandSet::TWiki

This CommandSet doesn't have any commands. It exists only to discover all the information about the TWiki installation where TWikiShell? resides, and make it available through the TWikiShellConfigObject.

TWiki::Contrib::CommandSet::Package

Generates a tarball from all the files in the TWikiExtension? directory. ONLY WORKS ON LINUX Use the TWiki::Contrib::CommandSet::Build package to do a proper packaging for release.

Command	Description
package	Generates a tarball for the TWikiExtension?

package

SYNOPSIS
     package <TWikiExtension>

DESCRIPTION
 Generates a tarball from all the files in the TWikiExtension directory.
 
EXAMPLE
    twikishell package TWikiShellContrib

        Will package all the files under twikiplugins/TWikiShellContrib
        in a tar file..

TWiki::Contrib::CommandSet::Plugin

TWikiExtension? Management CommandSet

Command	Description
plugin create	Creates the suggested directory structure for a TWikiExtension?
plugin develop	Prepares the file of a TWikiExtension? for development
plugin putback	Put back TWikiExtension? files into their checkout area

plugin create

SYNOPSIS
     plugin create <TWikiExtension>

DESCRIPTION
     This command will creates the directory twikiplugins/<Plugin/Contrib>
     with the following structure;
      twikiplugins/
         <TWikiExtension>/
            data/
               TWiki/
                  <TWikiExtension>.txt
            lib/
               TWiki/
                  [Plugin|Contrib]/
                     <TWikiExtension>.pm
                     <TWikiExtension>/
                        build.pl
            pub/
               TWiki/
                  <TWikiExtension>/

     To create the files, this command uses the templates distributed
     in lib/TWiki/Contrib/CommandSet/Plugin/Create and the EmptyPlugin.pm file.

plugin develop

SYNOPSIS plugin develop <Plugin/Contrib>

DESCRIPTION This command will copy all the related files for a Plugin/Contrib from the ${TWIKIROOT}/twikiplugins directory to the proper place under the ${TWIKIROOT} directory, while creating a manifest file in ${TWIKIROOT} with all the files copied. This is an alternative to the mklinks.sh -copy command.

EXAMPLE twikishell plugin develop TWikiShellContrib

Will copy all the files from twikiplugins/TWihiShellContrib to their proper place and create the TWikiShellContrib.MF file under ${TWIKIROOT}.

plugin putback

SYNOPSIS plugin putback <Plugin/Contrib>

DESCRIPTION This command will copy the files listed in the .MF file back to the twikiplugins/ directory, to be able to update the sources in the repository and/or run the build.pl script from there.

EXAMPLE twikishell plugin putback TWikiShellContrib

Will copy all the files listed in TWikiShellContrib.MF to the from twikiplugins/TWihiShellContrib directory.

TWiki::Contrib::CommandSet::Build

build

SYNOPSIS build - executes build.pl for the given plugin passing the specified

DESCRIPTION This command provides an interface to the build.pl script. It assumes that the script is somewhere along the following path:

${TROOT}/twikiplugins//lib/TWiki/[Plugin|Contrib]/

The parameter can be any valid target for the build.pl script.

Config Object

The config object provides a centralized place where CommandSet can store their settings. It's a blessed hash with the following published subs

• sub save : Save the configuration to the .twikishellrc file, using Data::Dumper
• sub saveAndDispose: Clean up the configuration and save it as per save sub.

Also, the configuration will always have the following variables set:

• verbosity : Last verbosity set
• configFileName : The name of the config file
• debug : if debug is enabled or not.

Also, unless the TWiki CommandSet is uninstalled, a hash containing the lib, bin, pub, and root directories for the installation is available under the key TWIKI (ie: $config->{TWIKI}{root} has the absolute path to the root of the twiki installation).

Any CommandSet that wants to store a setting in the config object must call the save method.

It's recommended that CommandSets using the config object to store settings must create a namespace using a hash for the settings so they won't conflict with others. Example:

The TWiki::Contrib::TWikiReleaseTrackerCommand may store its settings in $config->{TWikiReleaseTrackerCommand}, so its settings are accessed using $config->{TWikiReleaseTrackerCommand}{setting_name}

Services

The "services" are sets of common functionality than can be reused across CommandSets.

TWiki::Contrib::TWikiShellContrib::Zip

unzip($config,$sourceFile,$targetDir)

Unzips $sourceFile to $targetDir. It uses CPAN:Archive::Zip if installed, or the configured unzip program othewise.

TWiki::Contrib::TWikiShellContrib::DirHandling

Provides services to manipulate zip files.

makepath($path)

Creates the directory structure leading to $path. Examples:

makepath("/lib/TWiki/Plugin/NewPlugin/NewPlugin.pm");

will try to create the following directories if they don't exist:

/lib
/lib/TWiki
/lib/TWiki/Plugin
/lib/TWiki/Plugin/NewPlugin

makepath("/pub/SomeDir/SomeSubDir");

will try to create the following directories if they don't exist:

/pub
/pub/SomeDir

cd($dir)

Change to the given directory

dirEntries($dir) -> @entries

Returns the list of names for the entries in the given dir.

TWiki::Contrib::TWikiShellContrib::Common

Useful fuctions to be used in CommandSets. All the functions in this package are exported.

extractPackageFromSub($sub)-> $package

Receives the fully qualified name of a sub (ie: TWiki::writeDebug) and returns only the package (ie: TWiki).

askUser($value,$default,$prompt,\&checkOk,$allwaysAsk)->$userInput

Ask the user for an input, providing a default value to be used if no input is received. The parameters are:

• $value: Value to be checked. If undef or empty, it'll be set to $default;
• $default: A default to be suggested to the user.
• $prompt: the message to be displayed to the user.
• \&checkOk: A function used to check if the user input is valid or not.
• $allwaysAsk: By default, askUser verifies if the provided $value (or $default) pass the \&checkOk test. If it pass, the user is not asked. By passing 1 in $allwaysAsk, this check is not performed and the user is always asked for an input.

The result is a $userInput that satisfies the \&checkOk check.

checkIfDir($dir)

Convenience function that checks if the given parameter is a directory. Designed to be used with askUser

sys_action($cmd)

Perform a "system" command.

findRelativeTo($startdir, $name) -> $path

Look for $name starting in $startdir, and moving up in the path until $name if found.

Returns the path to $name or undef if not found.

TWiki::Contrib::TWikiShellContrib::Help

assembleHelp(\%doco,@order) -> $helpText

Assembles a help text from the provided hash.

• \%doco: A hash containing the help sections and their corresponding texts.
• @order: A list with the name of the sections, ordered in the way they should be displayed.

Example:

Given the following hash (from TWiki::Contrib::CommandSet::Plugin::Develop):

my $doco = {
   "SYNOPSIS" =>" plugin develop <Plugin/Contrib> - Copies the files for the Plugin/Contrib into the twiki root for development",
   "DESCRIPTION" =>
" This command will copy all the related files for a Plugin/Contrib
 from the \${TWIKIROOT}/twikiplugins directory to the proper place 
 under the \${TWIKIROOT} directory, while creating a manifest file 
 with all the files copied.
 This is an alternative to the =mklinks -copy=  command, with the
 added value that it creates a manifest file that can be used by 
 the Package CommandSet or the BuildContrib-based =build.pl= 
 script to create a release version.

",
   "EXAMPLE" =>
" twikishell plugin develop TWikiShellContrib

    Will copy all the files from twikiplugins/TWihiShellContrib to
    their proper place and create the TWikiShellContrib.MF file 
    under \${TWIKIROOT}.   
"};

the call assembleHelp($doco,"SYNOPSIS","DESCRIPTION","EXAMPLE") will produce:

SYNOPSIS
     plugin develop <Plugin/Contrib> - Copies the files for the Plugin/Contrib 
into the twiki root for development

DESCRIPTION
     This command will copy all the related files for a Plugin/Contrib
     from the ${TWIKIROOT}/twikiplugins directory to the proper place
     under the ${TWIKIROOT} directory, while creating a manifest file
     with all the files copied.
     This is an alternative to the =mklinks -copy=  command, with the
     added value that it creates a manifest file that can be used by
     the Package CommandSet or the BuildContrib-based =build.pl=
     script to create a release version.

EXAMPLE
     twikishell plugin develop TWikiShellContrib

        Will copy all the files from twikiplugins/TWihiShellContrib to
        their proper place and create the TWikiShellContrib.MF file
        under ${TWIKIROOT}.

The programmer is responsible of the formating of the text.

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:

%$MANIFEST%

If you have a non-standard installation, then move the files wherever you need them to be.

Settings

• Name of the perl package
  • Set STUB = TWiki::Contrib::TWikiShellContrib

Contrib Info

Authors:	TWiki:Main.MartinCleaver, TWiki:Main.RafaelAlvarez
Copyright ©:	2004,2005 Crawford Currie, Rafael Alvarez, and Martin Cleaver
License:	GPL
Dependencies:	CPAN:Term::Shell
10/08/2005	2.0 Removed reload and register commands. Major overhaul of the code. Added new CommandSets
02/11/04	1.1 Added reload and register commands
21/10/04	1.000 Initial release, based on the work of TWiki:Main.MartinCleaver
Home:	http://TWiki.org/cgi-bin/view/Plugins/TWikiShellContrib
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/TWikiShellContribDev

Related Topics: TWiki:Main.TWikiShell