NAME
Agent::TCLI::Control - Manage TCLI commands
SYNOPSIS
Controls are spawned from within Transports.
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.
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.
hostname
The hostname being used by the control.
poe_debug
A flag to set whether to enable poe debugging if installed
METHODS
spawn
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, rather than a RawCommands hash. Currenly this is reserved for future use.
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.
help
A POE event to handle some help requests. It expects a request object parameter.
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 ('/') context depth wil return 0 even though context [0] is populated with '/'.
_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.