key Log In or Register to edit

TWiki Shell

Purpose

T Wiki Shell Contrib 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 Calendar Plugin

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 Command Set to reconfigure themselves.

On a bare installation (without any Command Sets 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

Command Set

Command Sets are the extension point for T Wiki Shell Contrib. Without them, it's only an empty shell (no pun intended)

Creation

Command Sets 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_ Sub 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

There are several ways to implement Command Set. 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 Command Set can be on any TWiki subpackage and can be imported using the import command. The special case are Command Set under the TWiki::Contrib::CommandSet package (anywhere in @INC) which are "discovered" and imported at startup.

Check the bundled Command Sets for examples on how to implement them.

Initializing Command Set

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

onImport($shell,$config)

Called when the Command Set is being imported.

Loading a Command Set to the Shell

To load a Command Set, use: 

   import <command>

or 

   import <CommandSet_module_without_prefix>

if it's a core Command Set, or 

   import <CommandSet_module>

if not.

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

Command Set 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 Command Sets

T Wiki Shell Contrib is distributed with some Command Sets aimed at TWiki:Codev.TWikiExtension development.

TWiki::Contrib::CommandSet::Dump

This is a sample Command Set. 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 Command Set doesn't have any commands. It exists only to discover all the information about the TWiki installation where T Wiki Shell? resides, and make it available through the T Wiki Shell Config Object.

TWiki::Contrib::CommandSet::Package

Generates a tarball from all the files in the T Wiki Extension? 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 T Wiki Extension?

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

T Wiki Extension? Management Command Set

Command Description
plugin create Creates the suggested directory structure for a T Wiki Extension?
plugin develop Prepares the file of a T Wiki Extension? for development
plugin putback Put back T Wiki Extension? 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 T Wiki Shell Contrib

Will copy all the files from twikiplugins/TWihiShellContrib to their proper place and create the T Wiki Shell Contrib.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 T Wiki Shell Contrib

Will copy all the files listed in T Wiki Shell Contrib.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 Command Set 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 Command Set 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 Command Set that wants to store a setting in the config object must call the save method.

It's recommended that Command Sets 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 Command Sets.

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 Command Sets. 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 instalation, 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 Command Sets
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

Printable copy

 
Ad Sponsor
Back to Redbourn
Copyright © We make no guarantee of the correctness of the content of this site. All material on this collaboration platform is the property of Martin Cleaver and the contributing authors.