## Apache Zeta Components Manual :: Docs For Class ezcConsoleInput

### ConsoleTools::ezcConsoleInput

### Class ezcConsoleInput

The ezcConsoleInput class handles the given options and arguments on the console.

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 ();
3. // Register simple parameter -h/--help
4. $optionHandler-> registerOption (new ezcConsoleOption ('h','help') );
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);
18. // Manipulate parameter -f/--file after registration
19. $file->multiple=true;
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);
35. // Register an alias for this parameter
36. $optionHandler-> registerAlias ('e','extended-dir',$dir);
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. }
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. }
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$paramShortwas not submitted.\n";
71. break;
72. case$val===true:
73. echo"Parameter$paramShortwas submitted without a value.\n";
74. break;
75. case is_array ($val):
76. echo"Parameter$paramShortwas submitted multiple times with value: '".implode (', ',$val)."'.\n";
77. break;
78. default:
79. echo"Parameter$paramShortwas submitted with value: '$val'.\n";
80. break;
81. }
82. }

Source for this file: /ConsoleTools/src/input.php

Version: | //autogen//

### 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 array(string=>mixed) | `$properties = array()` Collection of properties.

### 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(string) | `getArguments( )` Returns arguments provided to the program.
public array(array(string)) | `getHelp( [ $long = false] , [ $params = array()] , [ $paramGrouping = null] )` Get help information for your options.
public ezcConsoleTable | `getHelpTable( $table , [ $long = false] , [ $params = array()] , [ $paramGrouping = null] )` Get help information for your options as a table.
public string | `getHelpText( $programDesc , [ $width = 80] , [ $long = false] , [ $params = null] , [ $paramGrouping = 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 )` Registers an alias for an option.
public ezcConsoleOption | `registerOption( $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(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(string) | Array of used option short names.
`$depth` | int | Current recursion depth.
`&$usedOptions` |  |

#### getArguments

array(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(array(string)) getHelp( [bool $long = false] , [ $params = array()] , [ $paramGrouping = null] )

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 long help 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.

The $paramGrouping option can be used to group options in the help output. The structure of this array parameter is as follows:

1. array(
2. 'First section'=>array(
3. 'input',
4. 'output'
5. 'overwrite',
6. ),
7. 'Second section'=>array(
8. 'v',
9. 'h',
10. ),
11. )

As can be seen, short option names are possible as well as long ones. The key of the first array level is the name of the section, which is assigned to an array of options to group under this section. The $params parameter still influences if an option is displayed at all.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$long` | bool |
`$params` | array(string) |
`$paramGrouping` | array(string=>array(string)) |

#### getHelpTable

ezcConsoleTable getHelpTable( ezcConsoleTable $table , [bool $long = false] , [ $params = array()] , [array(string=>array(string)) $paramGrouping = null] )

Get help information for your options as a table.

This method provides the information returned by ezcConsoleInput::getHelp() in a table.

The $paramGrouping option can be used to group options in the help output. The structure of this array parameter is as follows:

1. array(
2. 'First section'=>array(
3. 'input',
4. 'output'
5. 'overwrite',
6. ),
7. 'Second section'=>array(
8. 'v',
9. 'h',
10. ),
11. )

As can be seen, short option names are possible as well as long ones. The key of the first array level is the name of the section, which is assigned to an array of options to group under this section. The $params parameter still influences if an option as displayed at all.

##### 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(string) | Set of option names to generate help for, default is all.
`$paramGrouping` | array(string=>array(string)) |

#### getHelpText

string getHelpText( string $programDesc , [int $width = 80] , [bool $long = false] , [ $params = null] , [array(string=>array(string)) $paramGrouping = 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.

The $paramGrouping option can be used to group options in the help output. The structure of this array parameter is as follows:

1. array(
2. 'First section'=>array(
3. 'input',
4. 'output'
5. 'overwrite',
6. ),
7. 'Second section'=>array(
8. 'v',
9. 'h',
10. ),
11. )

As can be seen, short option names are possible as well as long ones. The key of the first array level is the name of the section, which is assigned to an array of options to group under this section. The $params parameter still influences if an option as displayed at all.

##### 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(string) | Set of option names to generate help for, default is all.
`$paramGrouping` | array(string=>array(string)) |

#### 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 --).

##### Exceptions:

Type | Description
--- | ---
`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(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(string) | The arguments

##### Exceptions:

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

#### registerAlias

void registerAlias( string $short , string $long , 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 |

##### Exceptions:

Type | Description
--- | ---
`ezcConsoleOptionNotExistsException` | If the referenced option is not registered.
`ezcConsoleOptionAlreadyRegisteredException` | If another option/alias has taken the provided short or long name.

#### registerOption

ezcConsoleOption registerOption( 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 |

#### 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 |

##### Exceptions:

Type | Description
--- | ---
`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 |

##### Exceptions:

Type | Description
--- | ---
`ezcConsoleOptionNoAliasException` | If the requested short/long name belongs to a real parameter instead.

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

##### Exceptions:

Type | Description
--- | ---
`ezcConsoleOptionNotExistsException` | If requesting a not registered option.

Documentation generated by phpDocumentor 1.4.3