NAME

Agent::TCLI::Control - Manage TCLI commands

SYNOPSIS

Controls are spawned from within Transports. One does not need to manipulate to create typical Agents. Control is very poorly documented at this point. I apologize for the inconvenience.

DESCRIPTION

Why is it that people like GUIs so much? One of the reasons is because a good GUI allows people to spend less time memorizing the syntax and language specifics within a program. If one has no clue what a particular command is, one can still check out all the menus until something is found.

With a command line, this type of hunt and peck is more difficult, but not impossible. The command line must be command contextual to do this. A typical operating system interface maintains a file system context and not a command context. Cisco IOS and other network equipment often use a command contextual interface, and this is sometimes called Cisco-like. Network equipment usually has a much simpler file system and Network Administrators are usually forced to manage many more types of devices than System Administrators. Network Systems also generally require much less daily contact, so it is important for the user interface to be as helpful as possible, because the operator has likely forgotten half of the command syntax.

For functional quality assurance testing, the demands are much more in line with Network Administration. One will need to plug in a module that tests some sort of capability, write and run some tests, and then do something else for a bit while the developers/integrators fix the problems. Thus TCLI attempts to use the Cisco-like contextual paradigm to provide a user interface to support testers.

INTERFACE

ATTRIBUTES

The following attributes are accessible through standard accessor/mutator methods and may be set as a parameter to new unless otherwise noted.

id

ID of control. MUST be unique to all other controls and is the POE kernel alias.

commands

The collection of registered commands in the control library. Commands may not be set, but must added with the register method.

auth

Authorization for the user for this control. Must be separate from the auth in the user object since that might not be the only factor at all times.

type

Type of conversation. MUST be one of these values: instant => one time (or not specified) chat => peer to peer chat group => group chatroom

context

Contains the context of the current Command application for the control.

owner

Contains the owning session of the control. This allows the control to be passed around between sessions and whatever session that has it can send back to the top level originating session.

prompt

The promt that the control is displaying, when appropriate.

local_address

The local IP address of the system

hostname

The hostname being used by the control.

poe_debug

A flag to set whether to enable poe debugging if installed

METHODS

_init

Private. Used by OIO to initialize the Control object.

Register

Register is an internal object method used to register commands with the Control.

RegisterContexts

RegisterCotexts is an internal object method used to register contexts for commands with the Control.

FindCommand

FindCommand is an internal object method used to parse the command line arguments and determine the appropriate command handler.

SortCommands

SortCommands is an internal object method used to sort the commands available in a context. It returns an array of arrays of alias => cmd object.

ListCommands

ListCommands is an internal object method used to list the commands available in a context. It calls SortCommands once it has found the right context.

RegisterCommand

RegisterCommand is an internal object method used to Register Agent::TCLI::Package::Command objects directly.

RegisterPackage

RegisterPackage is an internal object method used to register and entire package of commands. It calls the Package's RawCommands method to get the list of commands that need to be registered.

_start

POE event to load up any initialization routines for commands.

stop

Poe state that is mostly just a placeholder.

shutdown

POE event to forcibly shutdown the CLI control. It will call the stops for all registered commnds that requested them. This probably is not necessary, as their sessions will clean up after themselves.

ControlAddState

POE Event handler that allows new state registrations.

ChangeContext

Poe state that is used the handle all context changes. If a Command needs to change the context, this is how to do it. The only argument is a string instructing how to change the context.

'/' changes to root context. '..' goes back one context <string> adds <string> to the current context.

No verification is done to see that a reasonable context results from this.

Usually there is no need for a command to directly access change context, as the Command::Base establish_context state will be able to handle most needs.

control_presence

This is very transport specific, and I'm not sure how to handle presence quite yet.

Execute

POE event Execute is the main event handler for incoming reuqests. Transports should send command requests to Execute. The can be either plain text as entered by the user or request objects.

Usage:

$kernel->post( 'Control' => 'Execute' => $input );

DoSub

This internal object method performs the actual execution of commands that are only small subs.

AsYouWished

This POE state takes a text reply to a transaction and returns it to the proper transport for sending to the user. This has been somewhat deprecated by the Respond method in request objects.

Commands that are executed as sessions may use this as a return and should not try to interact with the transports directly. It is called by run for legacy command calls.

It prefers a response object, but will wrap plain text into a response object for consistent transport handling.

general

A POE event to handle some general commands such as context and status. It expects a request object parameter.

net

A POE event to execute the net commands. Takes a request object as an ARG0. The only command it handles currently is ip. This will respond with the local_address if defined.

help

A POE event to execute the help command. Takes a request object as an ARG0. Responds with the properly formatted help output.

manual

A POE event to execute the manual command. Takes a request object as an ARG0. Responds with the properl formatted manual output.

exit

A POE event to handle context shift commands exit and /. It expects a request object parameter.

dumpcmd

A POE event to handle some debugging in band. It expects a request object parameter.

print_context

An object method to get the current context in string form. It has no parameters.

push_context

An private object method to push onto the current context. It has no parameters.

pop_context

An private object method to pop from the current context. It has no parameters.

depth_context

An object method to return the context depth. It has no parameters. If the context is root ('ROOT') context depth wil return 0 even though context [0] is populated with 'ROOT'.

_default

A POE event handler to handle events gone astray. Only does something when verbose is turned on.

_default_commands

A private object method that has all the default commands. The ones we just can't live without. Well, maybe not all the ones we can't live without, but all the ones that have actually be written so far.

_automethod

Some transports may need to store extra state information related to the control. Rather than force them to maintain some sort of lookup table, the Control object can have attributes generated on the fly. This operates the same as for Request objects and within the transports themselves. It is exected that the Transport documentation will describe what is being stored in the Control.

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

SHOULDS and MUSTS are currently not enforced.

Test scripts not thorough enough.

Probably many 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.