NAME
Agent::TCLI::Base - Base object for other TCLI objects
SYNOPSIS
Tedious method:
package Agent::TCLI::Package::MyCommand
sub _init { my $self = shift;
my $test_verbose = Agent::TCLI::Parameter->new(
constraints => ['UINT'],
help => "an integer for verbosity",
manual => 'The verbose manual.',
name => 'test_verbose',
aliases => 'verbose|v',
type => 'Counter',
);
my $paramint = Agent::TCLI::Parameter->new(
constraints => ['UINT'],
help => "an integer for a parameter",
manual => 'The integer parameter.',
name => 'paramint',
type => 'Param',
);
my $cmd1 = Agent::TCLI::Command->new(
'name' => 'cmd1',
'contexts' => {'/' => 'cmd1'},
'help' => 'cmd1 help',
'usage' => 'cmd1 usage',
'topic' => 'test',
'call_style'=> 'session',
'command' => 'test1',
'handler' => 'cmd1',
'parameters' => {
'test_verbose' => $test_verbose
'paramint' => $paramint,
},
'verbose' => 0,
);
$self->parameters->{'test_verbose'} = $test_verbose;
$self->parameters->{'paramint'} = $paramint;
$self->commands->{'cmd1'} = $cmd1;
}Easier method
package Agent::TCLI::Package::MyCommand
sub _init { my $self = shift;
$self->LoadYaml(<<'...');
---
Agent::TCLI::Parameter:
name: test_verbose
constraints: UINT
help: an integer for verbosity
manual >
The verbose manual.
name: test_verbose
aliases: verbose|v
type: Counter
---
Agent::TCLI::Parameter:
name: paramint
constraints: UINT
help: an integer for a parameter
manual >
The integer parameter.
type => Param
---
Agent::TCLI::Command:
name: cmd1
contexts:
'/' : cmd1
help: cmd1 help
usage: cmd1 usage
topic: test
call_style: session
command: test1
handler: cmd1
parameters:
test_verbose: verbose
paramint: paramint
...
}DESCRIPTION
Base object for Commands. May be used directly in a command collection or may be extended for special functionality. Note that the Control and other components will not recognize any class extension without also being modified.
INTERFACE
Commands are usually loaded into Packages to provide their functionality. One Package may have many commands and parameters. Rather than writing these as separate object new statements, one can use YAML to load in batches of Parameters and Commands into the Package. Order is important, be sure to load or define Parameters before Commands that use them.
ATTRIBUTES
The following attributes are accessible through standard named accessor/mutator methods unless otherwise noted
name
The name of the command. This is the word that is used to call the command. It should be long enough to be descriptive. Use aliases for shortenned versions or abbreviations.
The name is also the key used in a Package's commands hash. Thus is must be unique within a package.
set_name will only accept SCALAR type values.
topic
The general topic heading that the command will be listed under. Most applicable to help menus. set_topic will only accept SCALAR type values.
help
Brief text to decribe the function of the command. This should be a one line description. set_help will only accept SCALAR type values.
usage
Brief illustration of usage. Complex commands may want to show how to call help / manual instead. set_usage will only accept SCALAR type values.
manual
A long desciption of the command and its use. This text will be followed by the command's parameter's manul sections if provided. manual will only contain scalar values.
command
A reference to the sub routine that will execute the command or the name of the package session that will run the command.
start
Deprecated: A reference to a subroutine that is necessary to intialize the command at control startup. start will only accept CODE type values.
stop
Deprecated: A code reference for shutting down anything as the control shuts down. stop will only accept CODE type values.
handler
A code reference for a response handler if necessary for a POE event driven command
call_style
This is a holdover to facilitate migration from the older style method of calling commands with an oob, to the new POE parameter use. The value 'poe' means the command is called directly with the normal POE KERNEL HEAP and ARGs. 'session' means that a POE event handler is called. call_style will only accept SCALAR type values.
contexts
A hash of the contexts that the command may be called from. This needs to be written up much better in a separate section, as it is very complicated. contexts will only accept hash type values.
parameters
A hash of parameter objects that the command accepts. parameters will only contain hash values.
required
A hash containing the names of the required parameters. required will only contain HASH values.
Usages ( context )
Get a list of how this coommand is called in the given context.
Description
A command may be aliased to several different terms in a given context or it may be aliased to different terms in different contexts. This method takes a context and returns the list of aliases for the command. It is used internally to support help.
Usage
$cmd->Usages( \@context )
Aliases ( context_hash_key )
Return aliases for specific context hash key.
Description
An internal method that takes a context hash key and returns all the aliases for that specific key. The aliases could be an array, hash or scalar and this function simplifies that logic. It returns a hash keyed on aliases of the command object.
If one has only a context, then use Usages which will call Aliases correctly.
Usage
$self->Aliases( $self->contexts->{'this'}{'that'} )
GetoptLucid( $kernel, $request)
Returns an option hash keyed on parameter after the arguments have bee parsed by Getopt::Lucid. Will respond itself if there is an error and return nothing.
Takes the POE Kernel and the request as args.
INHERITED METHODS
This module is an Object::InsideOut object that inherits from Agent::TCLI::Base. It inherits methods from both. Please refer to their documentation for more details.
AUTHOR
Eric Hacker <hacker at cpan.org>
BUGS
When naming commands in the preinit commands hash or loading from loadyaml() it is easy to accidentally duplicate names and cause commands not to load. The author expects that when he makes this a habit, he'll try to fix it by doing something better than a loading a hash with no validation.
Most command packages process args in an eval statement which will sometimes return rather gnarly detailed traces back to the user. This is not a security issue because open source software is not a black box where such obscurity might be relied upon (albeit ineffectively), but it is a bug.
SHOULDS and MUSTS are currently not always enforced.
Test scripts not thorough enough.
Probably many others.
LICENSE
Copyright (c) 2007, Alcatel Lucent, All rights resevred.
This package is free software; you may redistribute it and/or modify it under the same terms as Perl itself.