Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Agent::TCLI::Base
Base object for other TCLI objects

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.

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.

cl_options
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.

METHODS

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.

Usages ( context )
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.

Aliases ( context_hash_key )
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.

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.

Validate( <kernel>, <request>, <package> )
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.

ApplyDefaults( <param_hash>, <package>, <input> )
Returns a hash keyed on parameter after the defaults from the Package attributes have been applied. This is used during the Validate method.

BuildCommandLine( <param_hash>, <with_cmd> )
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.

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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy