Path

ez components / documentation / api reference / 2007.2.1 / consoletools

eZ Components 2007.2.1

ConsoleTools: ezcConsoleInput

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcConsoleInput

The ezcConsoleInput class handles the given options and arguments on the console. [source]
This class allows the complete handling of options and arguments submitted to a console based application.
The next example demonstrate how to capture the console options:
 1.  $optionHandler = new ezcConsoleInput();
 2.  
 3.  // Register simple parameter -h/--help
 4.   $optionHandler->registerOption( new ezcConsoleOption( 'h', 'help' ) );
 5.  
 6.  // Register complex parameter -f/--file
 7.   $file = new ezcConsoleOption(
 8.   'f',
 9.   'file',
10.   ezcConsoleInput::TYPE_STRING,
11.   null,
12.   false,
13.   'Process a file.',
14.   'Processes a single file.'
15.  );
16.  $optionHandler->registerOption( $file );
17.  
18.  // Manipulate parameter -f/--file after registration
19.   $file->multiple = true;
20.  
21.  // Register another complex parameter that depends on -f and excludes -h
22.   $dir = new ezcConsoleOption(
23.   'd',
24.   'dir',
25.   ezcConsoleInput::TYPE_STRING,
26.   null,
27.   true,
28.   'Process a directory.',
29.   'Processes a complete directory.',
30.   array( new ezcConsoleOptionRule( $optionHandler->getOption( 'f' ) ) ),
31.   array( new ezcConsoleOptionRule( $optionHandler->getOption( 'h' ) ) )
32.  );
33.  $optionHandler->registerOption( $dir );
34.  
35.  // Register an alias for this parameter
36.   $optionHandler->registerAlias( 'e', 'extended-dir', $dir );
37.  
38.  // Process registered parameters and handle errors
39.   try
40.  {
41.       $optionHandler->process( array( 'example_input.php', '-h' ) );
42.  }
43.  catch ( ezcConsoleOptionException $e )
44.  {
45.       echo $e->getMessage();
46.       exit( 1 );
47.  }
48.  
49.  // Process a single parameter
50.   $file = $optionHandler->getOption( 'f' );
51.  if ( $file->value === false )
52.  {
53.       echo "Parameter -{$file->short}/--{$file->long} was not submitted.\n";
54.  }
55.  elseif ( $file->value === true )
56.  {
57.       echo "Parameter -{$file->short}/--{$file->long} was submitted without value.\n";
58.  }
59.  else
60.  {
61.       echo "Parameter -{$file->short}/--{$file->long} was submitted with value '".var_export($file->value, true)."'.\n";
62.  }
63.  
64.  // Process all parameters at once:
65.   foreach ( $optionHandler->getOptionValues() as $paramShort => $val )
66.  {
67.       switch ( true )
68.       {
69.           case $val === false:
70.               echo "Parameter $paramShort was not submitted.\n";
71.               break;
72.           case $val === true:
73.               echo "Parameter $paramShort was submitted without a value.\n";
74.               break;
75.           case is_array( $val ):
76.               echo "Parameter $paramShort was submitted multiple times with value: '".implode(', ', $val)."'.\n";
77.               break;
78.           default:
79.               echo "Parameter $paramShort was submitted with value: '$val'.\n";
80.               break;
81.       }
82.  }

Constants

TYPE_INT = 2 Option takes an integer value.
TYPE_NONE = 1 Option does not carry a value.
TYPE_STRING = 3 Option takes a string value.

Properties

ezcConsoleArguments read/write  $argumentDefinition
Optional argument definition.

Member Variables

protected mixed $properties = array()
Collection of arguments.

Method Summary

public ezcConsoleInput __construct( )
Creates an input handler.
protected bool argumentsAllowed( )
Returns if arguments are allowed with the current option submition.
protected string createOptionSynopsis( $option, &$usedOptions, [$depth = 0], $usedOptions )
Returns the synopsis string for a single option and its dependencies.
public array(int=>string) getArguments( )
Returns arguments provided to the program.
public array(int=>array(int=>string)) getHelp( [$long = false], [$params = array()] )
Get help information for your options.
public ezcConsoleTable getHelpTable( $table, [$long = false], [$params = array()] )
Get help information for your options as a table.
public string getHelpText( $programDesc, [$width = 80], [$long = false], [$params = null] )
Returns a standard help output for your program.
public ezcConsoleOption getOption( $name )
Returns the definition object for the option with the name $name.
public array(string=>ezcConsoleOption) getOptions( )
Returns an array of all registered options.
public array(string=>mixed) getOptionValues( [$longnames = false] )
Returns the values of all submitted options.
public string getSynopsis( [$optionNames = null] )
Returns the synopsis string for the program.
public bool hasOption( $name )
Returns true if an option with the given name exists, otherwise false.
public bool helpOptionSet( )
Returns if a help option was set.
public void process( [$args = null] )
Process the input parameters.
public void registerAlias( $short, $long, $option, $option )
Registers an alias for an option.
public ezcConsoleOption registerOption( $option, $option )
Registers the new option $option.
public void registerOptionString( $optionDef )
Registers options according to a string specification.
public void reset( )
Resets all option and argument values.
public void unregisterAlias( $short, $long )
Removes an alias to an option.
public void unregisterOption( $option )
Removes an option.

Methods

__construct

ezcConsoleInput __construct( )
Creates an input handler.

argumentsAllowed

bool argumentsAllowed( )
Returns if arguments are allowed with the current option submition.

createOptionSynopsis

string createOptionSynopsis( ezcConsoleOption $option, &$usedOptions, [int $depth = 0], array(int=>string) $usedOptions )
Returns the synopsis string for a single option and its dependencies.
This method returns a part of the program synopsis, specifically for a certain parameter. The method recursively adds depending parameters up to the 2nd depth level to the synopsis. The second parameter is used to store the short names of all options that have already been used in the synopsis (to avoid adding an option twice). The 3rd parameter determines the actual deps in the option dependency recursion to terminate that after 2 recursions.

Parameters

Name Type Description
$option ezcConsoleOption The option to include.
$usedOptions array(int=>string) Array of used option short names.
$depth int Current recursion depth.
&$usedOptions  

getArguments

array(int=>string) getArguments( )
Returns arguments provided to the program.
This method returns all arguments provided to a program in an int indexed array. Arguments are sorted in the way they are submitted to the program. You can disable arguments through the 'arguments' flag of a parameter, if you want to disallow arguments.
Arguments are either the last part of the program call (if the last parameter is not a 'multiple' one) or divided via the '--' method which is commonly used on Unix (if the last parameter accepts multiple values this is required).

getHelp

array(int=>array(int=>string)) getHelp( [bool $long = false], [ $params = array()] )
Get help information for your options.
This method returns an array of help information for your options, indexed by int. Each help info has 2 fields:
  1. => The options names ("<short> / <long>")
  2. => The help text (depending on the $long parameter)
The $long options determines if you want to get the short- or longhelp texts. The array returned can be used by ezcConsoleTable.
If using the second options, you can filter the options shown in the help output (e.g. to show short help for related options). Provide as simple number indexed array of short and/or long values to set a filter.

Parameters

Name Type Description
$long bool Set this to true for getting the long help version.
$params array(int=>string) Set of option names to generate help for, default is all.

getHelpTable

ezcConsoleTable getHelpTable( ezcConsoleTable $table, [bool $long = false], [ $params = array()] )
Get help information for your options as a table.
This method provides the information returned by ezcConsoleInput::getHelp() in a table.

Parameters

Name Type Description
$table ezcConsoleTable The table object to fill.
$long bool Set this to true for getting the long help version.
$params array(int=>string) Set of option names to generate help for, default is all.

getHelpText

string getHelpText( string $programDesc, [int $width = 80], [bool $long = false], [ $params = null] )
Returns a standard help output for your program.
This method generates a help text as it's commonly known from Unix command line programs. The output will contain the synopsis, your provided program description and the selected parameter help as also provided by ezcConsoleInput::getHelp(). The returned string can directly be printed to the console.

Parameters

Name Type Description
$programDesc string The description of your program.
$width int The width to adjust the output text to.
$long bool Set this to true for getting the long help version.
$params array(int=>string) Set of option names to generate help for, default is all.

getOption

ezcConsoleOption getOption( string $name )
Returns the definition object for the option with the name $name.
This method receives the long or short name of an option and returns the ezcConsoleOption object.

Parameters

Name Type Description
$name string Short or long name of the option (without - or --).

Throws

ClassDescription
ezcConsoleOptionNotExistsException If requesting a not registered parameter.

getOptions

array(string=>ezcConsoleOption) getOptions( )
Returns an array of all registered options.
Returns an array of all registered options in the following format: 
1.  array(
2.       0 => ezcConsoleOption,
3.       1 => ezcConsoleOption,
4.       2 => ezcConsoleOption,
5.       ...
6.  );

getOptionValues

array(string=>mixed) getOptionValues( [bool $longnames = false] )
Returns the values of all submitted options.
Returns an array of all values submitted to the options. The array is indexed by the parameters short name (excluding the '-' prefix). The array does not contain any parameter, which value is 'false' (meaning: the parameter was not submitted).

Parameters

Name Type Description
$longnames bool Wheather to use longnames for indexing.

getSynopsis

string getSynopsis( [ $optionNames = null] )
Returns the synopsis string for the program.
This gives you a synopsis definition for the options and arguments defined with this instance of ezcConsoleInput. You can filter the options named in the synopsis by submitting their short names in an array as the parameter of this method. If the parameter $optionNames is set, only those options are listed in the synopsis.

Parameters

Name Type Description
$optionNames array(int=>string)  

hasOption

bool hasOption( string $name )
Returns true if an option with the given name exists, otherwise false.
Checks if an option with the given name is registered.

Parameters

Name Type Description
$name string Short or long name of the option.

helpOptionSet

bool helpOptionSet( )
Returns if a help option was set.
This method returns if an option was submitted, which was defined to be a help option, using the isHelpOption flag.

process

void process( [ $args = null] )
Process the input parameters.
Actually process the input options and arguments according to the actual settings.
Per default this method uses $argc and $argv for processing. You can override this setting with your own input, if necessary, using the parameters of this method. (Attention, first argument is always the pro gram name itself!)
All exceptions thrown by this method contain an additional attribute "option" which specifies the parameter on which the error occurred.

Parameters

Name Type Description
$args array(int=>string) The arguments

Throws

ClassDescription
ezcConsoleOptionNotExistsException If an option that was submitted does not exist.
ezcConsoleOptionDependencyViolationException If a dependency rule was violated.
ezcConsoleOptionTypeViolationException If the type of a submitted value violates the options type rule.
ezcConsoleOptionExclusionViolationException If an exclusion rule was violated.
ezcConsoleOptionArgumentsViolationException If arguments are passed although a parameter disallowed them.

See also:

ezcConsoleOptionException.


registerAlias

void registerAlias( string $short, string $long, ezcConsoleOption $option, ezcConsoleOption $option )
Registers an alias for an option.
Registers a new alias for an existing option. Aliases can be used as if they were a normal option.
The alias is registered with the short option name $short and the long option name $long. The alias references to the existing option $option.

Parameters

Name Type Description
$short string  
$long string  
$option ezcConsoleOption  
$option ezcConsoleOption  

Throws

ClassDescription
ezcConsoleOptionNotExistsException If the referenced option is not registered.
ezcConsoleOptionAlreadyRegisteredException If another option/alias has taken the provided short or long name.

See also:

ezcConsoleInput::unregisterAlias().


registerOption

ezcConsoleOption registerOption( ezcConsoleOption $option, ezcConsoleOption $option )
Registers the new option $option.
This method adds the new option $option to your option collection. If already an option with the assigned short or long value exists, an exception will be thrown.

Parameters

Name Type Description
$option ezcConsoleOption  
$option ezcConsoleOption  

See also:

ezcConsoleInput::unregisterOption().


registerOptionString

void registerOptionString( string $optionDef )
Registers options according to a string specification.
Accepts a string to define parameters and registers all parameters as options accordingly. String definition, specified in $optionDef, looks like this:
1.  [s:|size:][u:|user:][a:|all:]
This string registers 3 parameters: -s / --size -u / --user -a / --all

Parameters

Name Type Description
$optionDef string  

Throws

ClassDescription
ezcConsoleOptionStringNotWellformedException If provided string does not have the correct format.

reset

void reset( )
Resets all option and argument values.
This method is called automatically by process(), if this method is called twice or more, and may also be used to manually reset the values of all registered {@ezcConsoleOption} and ezcConsoleArgument objects.

unregisterAlias

void unregisterAlias( string $short, string $long )
Removes an alias to an option.
This function removes an alias with the short name $short and long name $long.

Parameters

Name Type Description
$short string  
$long string  

Throws

ClassDescription
ezcConsoleOptionNoAliasException If the requested short/long name belongs to a real parameter instead.

See also:

ezcConsoleInput::registerAlias().


unregisterOption

void unregisterOption( ezcConsoleOption $option )
Removes an option.
This function removes an option. All dependencies to that specific option are removed completely from every other registered option.

Parameters

Name Type Description
$option ezcConsoleOption The option object to unregister.

Throws

ClassDescription
ezcConsoleOptionNotExistsException If requesting a not registered option.

See also:

ezcConsoleInput::registerOption().


Last updated: Thu, 31 Jan 2008