Eric Hacker > Agent-TCLI-0.032 > Agent::TCLI::Base

Download:
Agent-TCLI-0.032.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.030.0059   Source  

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.

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.

syntax highlighting: