/ 
Term-CmdLine-2.00
/ Term::CmdLine

NAME CmdLine

Library to implement generic command line interface

VERSION

Author

Andrew DeFaria <Andrew@DeFaria.com>

Created

Fri May 13 15:23:37 PDT 2011

SYNOPSIS

Provides an interface to a command line utilizing Term::ReadLine and Term::ReadLine::Gnu. Note, the latter is not part of Perl core and must be downloaded from CPAN. Without Term::ReadLine::Gnu a lot of functionality doesn't work.

CmdLine uses a hash to describe what your valid commands are along with help and longer help, i.e. description strings. If you do not define your commands then no command name completion nor help will be available.

use FindBin;
use CmdLine;

my %cmds = (
 list => (
    help        => 'help [<cmd>]',
    description => 'This is a longer description of the list command',
 ),
 execute => (
    help        => 'execute <cmd>',
    description => 'Longer description of the execute command',
 ),
);

# Create a new cmdline:
my $cmdline = Term::CmdLine->new ($FindBin::Script, %cmds);

while (my $cmd = $cmdline->get) {
  ...
} # while

DESCRIPTION

This module implements a command line stack using Term::ReadLine and Term::ReadLine::Gnu. If Term::ReadLine::Gnu is not installed then many of the functions do not work. Command completion if commands are defined with a hash as shown above.

DEFAULT COMMANDS

The for a list of the builtin commands see %builtin_cmds below

Additionally !<n> will re-exeucte a comand from history and !<cmd> will execute <cmd> as a shell command.

new ()

Construct a new CmdLine object. Note there is already a default CmdLine object created named $cmdline. You should use that unless you have good reason to instantiate another CmdLine object.

Parameters:

$histfile

Set to a file name where to write the history file. If not defined no history is kept.

%cmds

A hash describing the valid commands and their help/description strings.

my %cmds = (
 'list' => {
    help        => 'List all known commands',
    description => 'This is a longer description
                    of the list command',
 },
 'help' => {
    help        => 'This is a help command',
    description => 'help <cmd>
                    Longer description of help',
 },
);

Returns:

CmdLine object

get

Retrieves a command line

Parameters:

None

Returns:

$cmds

set_cmds

Sets the cmds

Parameters:

%cmds

New commands to use

Returns:

Nothing

set_prompt

Sets the prompt

Parameters:

$new_prompt

New commands to use

Returns:

$old_prompt

set_histfile

Sets the histfile

Parameters:

$histfile

New commands to use

Returns:

Nothing

set_eval

Sets the eval function pointer

Parameters:

[\&function]

Function to set eval to. This function will be called with the command line as the only paramter and it should return a result.

Returns:

\&old_eval

help [<cmd>]

Displays help

Note that the user does not need to explicitly call help - Term::CmdLine's get method will already sense that the builtin help command was invoked and handle it. This method is provided if the caller wishes to call this internally for some reason.

Parameters:

$cmd

Optional command help

Returns:

Nothing

history <action> [<file>] [<start> <end>]

This method lists, saves or executes (redo) a command from the history stack. <action> can be one of 'list', 'save' or 'redo'. If listing history one can specify the optional <start> and <end> parameters. If saving then <file> must be specified and optionally <start> and <end>. If redoing a command then only <start> or the command number should be specified.

Note that the user does not need to explicitly call history - CmdLine's get method will already sense that the builtin history command was invoked and handle it. This method is provided if the caller wishes to call this internally for some reason.

Parameters:

$action

One of 'list', 'save' or 'redo'

Returns:

Nothing

_get ($name)

This method gets a variable to a value stored in the Term::CmdLine object.

Parameters:

$name

Name of the variable

Returns:

$value

_set ($name, $value)

This method sets a variable to a value stored in the Term::CmdLine object. Note $value will be evaluated if eval is set.

Parameters:

$name

Name of the variable

$value

Value of the variable

Returns:

$oldvalue

vars ($name)

This method will print out all known variables

Parameters:

none

Returns:

Nothing

handleOutput ($line, @output)

This method will handle outputing the array @output. It also handles redirection (currently only output redirection) and piping

Parameters:

$line

The command line used to produce @output. This method parses out redirection (i.e. > and >>) and piping (|) from $cmd

@output

The output produced by the command to redirect or pipe. (Note this isn't true piping in that command must run first and produce all of @output before we are called. Need to look into how to use Perl's pipe command here).

Returns:

Nothing

source <file>

This method opens a file and sources it's content by executing each line. Note that the user must have set $self->{eval} to a function pointer. The function will be called with one parameter - the command line to execute. The function will return the result from the execution of the final command.

Note that the user does not need to explicitly call source - CmdLine's get method will already sense that the builtin source command was invoked and handle it. This method is provided if the caller wishes to call this internally for some reason.

Parameters:

$file

Filename to source

Returns:

Returns the result of the last command executed

DEPENDENCIES

Perl Modules

CPAN Perl Modules

Term::ReadLine

Term::ANSIColor

Term::ReadLine::Gnu (optional, but recommended for full functionality)

BUGS AND LIMITATIONS

There are no known bugs in this module `` Please report problems to Andrew DeFaria <Andrew@DeFaria.com>.

LICENSE AND COPYRIGHT