/ 
Agent-TCLI-0.03
River stage one • 1 direct dependent • 1 total dependent
/ Agent::TCLI::Parameter

NAME

Agent::TCLI::Parameter - A Parameter class for TCLI.

SYNOPSIS

	#within a Agent::TCLI::Package module that
	#inherits from Agent::TCLI::Package::Base

	use Agent::TCLI::Parameter

	sub _init :Init{
		$self->LoadYaml(<<'...');
	---
	Agent::TCLI::Parameter:
	  name: test_verbose
  	constraints:
	    - UINT
  	help: an integer for verbosity
	  manual: >
	    This debugging parameter can be used to adjust the verbose setting
	    for the test transport.
	  type: counter
	...
	}

DESCRIPTION

Parameters are the arguements supplied with a command. TCLI defines them as objects to make it easier to provide several necessary interface features in a consistent manner. One can use the new function to create Parameters to load into a package, but the author prefers the YAML syntax as it is easier to work with.

Arguement parsing may be done with Getopt::Lucid. One should define the type if using the provided parsing.

Arguement validation may be performed using FormValidator::Simple constraints as defined in the parameter. Otherwise it should be performed within the Package subroutine handling the command.

Typically each Package will have a field defined with a standard accessor/mutator that represents the default value to be used for the parameter when the command the command is called. This field can be manually defined in the Package, or it can be autocreated upon parameter loading within the Package. If necessary, the class filed may be used to set the Object::InsideOut type to be used for the field.

The reason for the use of Parameter and Command objects is to push a Package to be as data driven as possible, with only the only code being the actual command logic. It was decided that it would be best to evolve towards that goal, rather than try to get it right from the outset. So what you see what you get.

INTERFACE

ATTRIBUTES

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

name

The name of the parameter. The name is what the user supplies as an argument to the Command. The name will also be used as the hash key when loaded into the Package, so it must be unique within the set of all other Parameter names in a package.

The parameter name is also specified in the Command definition within a module, so the Parameter must be defined and loaded first.

If one desires to use the same name but needs different Parameter definitions within a Package, one should consider whether use of the same name for different things will lead to confusion for the users. If still convinced, then use aliases or separate packages.

name should only contain scalar values.

aliases

The aliases will be used by Getopt::Lucid in addition to the name when parsing the arguments to a command. This allows one to create variations on the argument name. This is useful for verbose and other times when names might clash. One can name the argument command_verbose and create an alias of verbose.

If aliases are defined, they will be appended to the name in the Getopt::Lucid specification. aliases should being with an alias with each subsequent alias separated by the vertical bar character. E.g.:

name: command_verbose
aliases: "verbose|v"

means name "command_verbose", alias "verbose" and alias "v"

aliases should only contain scalar values. When represented in YAML, they should be quoted to keep YAML from trying to interpret the bars.

type

The type will be used by Getopt::Lucid to parse the arguments into the parameters. It will also be used in a future HTTP inerface to determine what type of form field to present to the user. Refer to Getopt::Lucid for the complete details on how it works. A summary of the Getopt::Lucid supported types:

Switch -- a true/fals value
Counter -- a numerical counter
Param -- a variable taking an argument
List -- like param with list values
Keypair -- a variable taking an argument pair

The use of a Keypair probably indicates the overloading of a single command syntax and is discouraged. Instead, break the command into subcommands if at all possible, and the resulting structure will likely be easier for users.

type should only contain scalar values.

help

A short description of the parameter. This should be a one-liner that is used when the user asks for help on a particular command. help should only contain scalar values.

manual

A longer description of the parameter. This is displayed to the user when the ask for a manual of a command. Currently, constraints are not automatically used to generate additional manual content, but that is a desired feature.

manual should only contain scalar values.

constraints

An array of constraints for the parameter. This will be fed to FormValidator::Simple. constraints should only contain array values.

default

The default value that the parameter has upon creation in the package.

class

The class is used as the Object::InsideOut type if this parameter's field is autocreated in the package when loaded. If the field already exists in the Package, it will not be redefined and this won't be used. class should only contain scalar values.

show_method

If this parameter is stored within the Package as an object, an array of objects, or a hash of objects, show_method can be used to specify the object method that will be used when 'show' is requested on the parameter. This will hopefully allow the base show to cover 95% of all needs and reduce the need for Package authors from having to write their own package->show. show_method should only contain scalar values.

cl_option

The cl_options is the command line option that is used when the command using this parameter is just a front for another command line tool. This allows an automated translation instead of having to script it for each case. cl_option should only contain scalar values.

METHODS

new ( hash of attributes )

See the attributes above for a description of the available attributes.

The preferred method of creating a Parameter object for a Package module is to use the LoadYaml command in the module. This will create the object, and insert it correctly into the Package parameter store.

Alias ()

Alias simply returns the name and aliases joined togetehr with a bar for use in Getopt::Lucid or a regular expression. If the name of the parameter is foo, and the aliases is bar, then $param->alias returns foo|bar.

BuildCommandParam (<param_hash>)

Takes a param_hash and builds the appropriate command line value from the cl_option and type fields. If the type is Switch, it will return just the cl_option. If the type is Counter, it will return the cl_option repeated for the correct number of times. If the type is Param, it will return the cl_option followed by a space and a double-quoted value of the parameter. If the value already contains a double-quote it will not quote the value.

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 parametersit is easy to accidentally duplicate names and cause problems. 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.

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.