Path

ez components / documentation / api reference / 1.0.1 / consoletools

eZ Components 1.0.1

ConsoleTools: ezcConsoleInput

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

Class: ezcConsoleInput

Class for handling input submitted to console based programs (meaning options and arguments) . [source]
This class allows the complete handling of options and arguments submitted to a console based application.
 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 ( ezcConsoleInputException $e )
44.  {
45.       if ( $e->getCode() === ezcConsoleInputException::PARAMETER_DEPENDENCY_RULE_NOT_MET )
46.       {
47.           $consoleOut->outputText(
48.               'Parameter ' . isset( $e->param ) ? $e->param->name : 'unknown' . " may not occur here.\n", 'error'
49.           );
50.       }
51.       exit( 1 );
52.  }
53.  
54.  // Process a single parameter
55.   $file = $optionHandler->getOption( 'f' );
56.  if ( $file->value === false )
57.  {
58.       echo "Parameter -{$file->short}/--{$file->long} was not submitted.\n";
59.  }
60.  elseif ( $file->value === true )
61.  {
62.       echo "Parameter -{$file->short}/--{$file->long} was submitted without value.\n";
63.  }
64.  else
65.  {
66.       echo "Parameter -{$file->short}/--{$file->long} was submitted with value <".var_export($file->value, true).">.\n";
67.  }
68.  
69.  // Process all parameters at once:
70.   foreach ( $optionHandler->getOptionValues() as $paramShort => $val )
71.  {
72.       switch ( true )
73.       {
74.           case $val === false:
75.               echo "Parameter $paramShort was not submitted.\n";
76.               break;
77.           case $val === true:
78.               echo "Parameter $paramShort was submitted without a value.\n";
79.               break;
80.           case is_array( $val ):
81.               echo "Parameter $paramShort was submitted multiple times with value: <".implode(', ', $val).">.\n";
82.               break;
83.           default:
84.               echo "Parameter $paramShort was submitted with value: <$val>.\n";
85.               break;
86.       }
87.  }

Constants

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

Method Summary

public ezcConsoleInput __construct( )
Create input handler
protected string createOptionSynopsis( $option, &$usedOptions, [$depth = 0], $usedOptions )
Returns the synopsis string for a single option and it's 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 ezcConsoleOption getOption( $name )
Returns the definition object for a specific option.
public array(string=>ezcConsoleOption) getOptions( )
Returns an array of all registered options.
public array(string=>mixed) getOptionValues( )
Returns the values of all submitted options.
public string getSynopsis( [$optionNames = null] )
Returns a synopsis string for the program.
public bool hasOption( $name )
Returns if an option with the given name exists.
public void process( [$args = null] )
Process the input parameters.
public void registerAlias( $short, $long, $option )
Register an alias to a option.
public ezcConsoleOption registerOption( $option )
Register a new option.
public void registerOptionString( $optionDef )
Registeres options according to a string specification.
public void unregisterAlias( $short, $long )
Remove a alias to be no more supported.
public void unregisterOption( $option )
Remove a option to be no more supported.

Methods

__construct

ezcConsoleInput __construct( )
Create input handler

createOptionSynopsis

string createOptionSynopsis( ezcConsoleOption $option, &$usedOptions, [int $depth = 0], array(int=>string) $usedOptions )
Returns the synopsis string for a single option and it's 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 helo 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.

getOption

ezcConsoleOption getOption( string $name )
Returns the definition object for a specific option.
This method receives the long or short name of a 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( )
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, whiches value is 'false' (meaning: the parameter was not submitted).

getSynopsis

string getSynopsis( [ $optionNames = null] )
Returns a 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 $options is set, only the option names listed in this array are listed in the synopsis.

Parameters

Name Type Description
$optionNames array(int=>string) Names of options to include.

hasOption

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

Parameters

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

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 occured.

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 dissallowed them.

See also:

ezcConsoleOptionException.


registerAlias

void registerAlias( string $short, string $long, ezcConsoleOption $option )
Register an alias to a option.
Registers a new alias for an existing option. Aliases may then be used as if they were real option.

Parameters

Name Type Description
$short string Shortcut of the alias
$long string Long version of the alias
$option ezcConsoleOption Reference to an existing option

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 )
Register a new option.
This method adds a new option to your option collection. If allready a option with the assigned short or long value exists, an exception will be thrown.

Parameters

Name Type Description
$option ezcConsoleOption The option to register.

See also:

ezcConsoleInput::unregisterOption().


registerOptionString

void registerOptionString( string $optionDef )
Registeres options according to a string specification.
Accepts a string like used in eZ publis 3.x to define parameters and registeres all parameters as options accordingly. String definitions look like this:
1.  [s:|size:][u:|user:][a:|all:]
This string will result in 3 parameters: -s / --size -u / --user -a / --all

Parameters

Name Type Description
$optionDef string Option definition string.

Throws

ClassDescription
ezcConsoleOptionStringNotWellformedException If string provided is not wellformed.

unregisterAlias

void unregisterAlias( string $short, string $long )
Remove a alias to be no more supported.
Using this function you will remove an alias.

Parameters

Name Type Description
$short string Short name of the alias
$long string Long name of the alias.

Throws

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

See also:

ezcConsoleInput::registerAlias().


unregisterOption

void unregisterOption( ezcConsoleOption $option )
Remove a option to be no more supported.
Using this function you will remove a option. All dependencies to that specific option are removed completly 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: Fri, 02 Nov 2007