Agent::TCLI::Base - Base object for other TCLI objects
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
$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 ... }
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.
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.
The following attributes are accessible through standard named accessor/mutator methods unless otherwise noted
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.
The general topic heading that the command will be listed under. Most applicable to help menus. set_topic will only accept SCALAR type values.
Brief text to decribe the function of the command. This should be a one line description. set_help will only accept SCALAR type values.
Brief illustration of usage. Complex commands may want to show how to call help / manual instead. set_usage will only accept SCALAR type values.
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.
A reference to the sub routine that will execute the command or the name of the package session that will run the command.
Deprecated: A reference to a subroutine that is necessary to intialize the command at control startup. start will only accept CODE type values.
Deprecated: A code reference for shutting down anything as the control shuts down. stop will only accept CODE type values.
A code reference for a response handler if necessary for a POE event driven command
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.
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.
A hash of parameter objects that the command accepts. parameters will only contain hash values.
A hash containing the names of the required parameters. required will only contain HASH values.
These are command line options that will be issued every time the command is called. They will begin the value returned by BuildCommandLine. Make sure that they are not available as parameters for this command. There is no checking for duplicates and that will likely cause errors. cl_options should only contain scalar values.
These methods assist Package authors in common functioanlity needed to support a command. In some cases they are used internally by other parts of the Agent::TCLI system.
Get a list of how this command is called in the given context.
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.
Return aliases for specific context hash key.
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.
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.
Returns a hash keyed on parameter after the arguments have been parsed by Getopt::Lucid and validated by FormValidator::Simple as per the constraints specified in the Parameter or Command definitions. Will respond itself if there is an error and return nothing.
Takes the POE Kernel, the Request, and the Package as args.
Returns a hash keyed on parameter after the defaults from the Package attributes have been applied. This is used during the Validate method.
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.
Eric Hacker <hacker at cpan.org>
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.
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.
To install Agent::TCLI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Agent::TCLI
CPAN shell
perl -MCPAN -e shell install Agent::TCLI
For more information on module installation, please visit the detailed CPAN module installation guide.