[ class tree: Console_CommandLine ] [ index: Console_CommandLine ] [ all elements ]

Packages:
Console_CommandLine

Classes:

Files:

Action.php
Argument.php
Callback.php
Command.php
CommandLine.php
Counter.php
CustomMessageProvider.php
Default.php
Default.php
Default.php
Element.php
ex1.php
ex2.php
ex3.php
ex4.php
Exception.php
Help.php
List.php
MessageProvider.php
Option.php
Outputter.php
Password.php
Renderer.php
Result.php
StoreArray.php
StoreFalse.php
StoreFloat.php
StoreInt.php
StoreString.php
StoreTrue.php
Version.php
XmlParser.php

Class: Console_CommandLine

Source Location: /Console_CommandLine-1.1.3/Console/CommandLine.php

Class Overview

Main class for parsing command line options and arguments.

Author(s):

David JEAN LOUIS <izimobil at gmail.com>

Version:

Release: 1.1.3

Copyright:

2007 David JEAN LOUIS

Child classes:

Console_CommandLine_Command: Class that represent a command with option and arguments.

Inherited Variables

Inherited Methods

Class Details

[line 64]
Main class for parsing command line options and arguments.

There are three ways to create parsers with this class:

 // direct usage

 $parser = new Console_CommandLine ();

 // with an xml definition file
 $parser = Console_CommandLine ::fromXmlFile ('path/to/file.xml');

 // with an xml definition string
 $validXmlString = '..your xml string...';
 $parser = Console_CommandLine ::fromXmlString ($validXmlString);

Author: David JEAN LOUIS <izimobil@gmail.com>
Version: Release: 1.1.3
Copyright: 2007 David JEAN LOUIS
Link: http://pear.php.net/package/Console_CommandLine
Since: File available since release 0.1.0
Example: example not found
Example: example not found
License: MIT License

[ Top ]

Class Variables

$actions = array(
'StoreTrue' => array('Console_CommandLine_Action_StoreTrue', true),'StoreFalse'=>array('Console_CommandLine_Action_StoreFalse',true),'StoreString'=>array('Console_CommandLine_Action_StoreString',true),'StoreInt'=>array('Console_CommandLine_Action_StoreInt',true),'StoreFloat'=>array('Console_CommandLine_Action_StoreFloat',true),'StoreArray'=>array('Console_CommandLine_Action_StoreArray',true),'Callback'=>array('Console_CommandLine_Action_Callback',true),'Counter'=>array('Console_CommandLine_Action_Counter',true),'Help'=>array('Console_CommandLine_Action_Help',true),'Version'=>array('Console_CommandLine_Action_Version',true),'Password'=>array('Console_CommandLine_Action_Password',true),'List'=>array('Console_CommandLine_Action_List',true),)

[line 214]

Array of valid actions for an option, this array will also store user registered actions.

The array format is:

 array(
  => array(, )
 )

Var: List of valid actions
Access: public

Type: array

[ Top ]

$add_help_option = true

[line 119]

Boolean that determine if the command line parser should add the help (-h, --help) option automatically.

Var: Whether to add a help option or not
Access: public

Type: bool

[ Top ]

$add_version_option = true

[line 130]

Boolean that determine if the command line parser should add the version (-v, --version) option automatically.

Note that the version option is also generated only if the version property is not empty, it's up to you to provide a version string of course.

Var: Whether to add a version option or not
Access: public

Type: bool

[ Top ]

$args = array()

[line 183]

An array of Console_CommandLine_Argument objects.

Var: The arguments array
Access: public

Type: array

[ Top ]

$commands = array()

[line 190]

An array of Console_CommandLine_Command objects (sub commands).

Var: The commands array
Access: public

Type: array

[ Top ]

$description = ''

[line 100]

A description text that will be displayed in the help message.

Var: Description of your program
Access: public

Type: string

[ Top ]

$errors = array(
'option_bad_name' => 'option name must be a valid php variable name (got: {$name})',
'argument_bad_name' => 'argument name must be a valid php variable name (got: {$name})',
'option_long_and_short_name_missing' => 'you must provide at least an option short name or long name for option "{$name}"',
'option_bad_short_name' => 'option "{$name}" short name must be a dash followed by a letter (got: "{$short_name}")',
'option_bad_long_name' => 'option "{$name}" long name must be 2 dashes followed by a word (got: "{$long_name}")',
'option_unregistered_action' => 'unregistered action "{$action}" for option "{$name}".',
'option_bad_action' => 'invalid action for option "{$name}".',
'option_invalid_callback' => 'you must provide a valid callback for option "{$name}"',
'action_class_does_not_exists' => 'action "{$name}" class "{$class}" not found, make sure that your class is available before calling Console_CommandLine::registerAction()',
'invalid_xml_file' => 'XML definition file "{$file}" does not exists or is not readable',
'invalid_rng_file' => 'RNG file "{$file}" does not exists or is not readable'
)

[line 74]

Error messages.

Var: Error messages
Todo: move this to Console_CommandLine_MessageProvider
Access: public

Type: array

[ Top ]

$force_options_defaults = false

[line 169]

Boolean that tells the parser to set relevant options default values, according to the option action.

Var: Whether to force option default values
See: Console_CommandLine_Option::setDefaults()
Access: public

Type: bool

[ Top ]

$force_posix = false

[line 160]

Boolean that tells the parser to be POSIX compliant, POSIX demands the following behavior: the first non-option stops option processing.

Var: Whether to force posix compliance or not
Access: public

Type: bool

[ Top ]

$messages = array()

[line 256]

Custom errors messages for this command

This array is of the form:

 <?php

 array(
   $messageName => $messageText,
   $messageName => $messageText,
   ...
 );
 ?>

If specified, these messages override the messages provided by the default message provider. For example:

 <?php

 $messages = array(
   'ARGUMENT_REQUIRED' => 'The argument foo is required.',
 );
 ?>

See: Console_CommandLine_MessageProvider_Default
Access: public

Type: array

[ Top ]

$message_provider = false

[line 152]

The command line message provider instance.

Var: A message provider instance
Access: public

Type: Console_CommandLine_MessageProvider

[ Top ]

$name =

[line 93]

The name of the program, if not given it defaults to argv[0].

Var: Name of your program
Access: public

Type: string

[ Top ]

$options = array()

[line 176]

An array of Console_CommandLine_Option objects.

Var: The options array
Access: public

Type: array

[ Top ]

$outputter = false

[line 145]

The command line parser outputter instance.

Var: An outputter
Access: public

Type: Console_CommandLine_Outputter

[ Top ]

$parent = false

[line 199]

Parent, only relevant in Command objects but left here for interface convenience.

Var: The parent instance
Todo: move Console_CommandLine::parent to Console_CommandLine_Command
Access: public

Type: Console_CommandLine

[ Top ]

$renderer = false

[line 138]

The command line parser renderer instance.

Var: implements Console_CommandLine_Renderer interface
Access: public

Type: object that

[ Top ]

$version = ''

[line 111]

A string that represents the version of the program, if this property is not empty and property add_version_option is not set to false, the command line parser will add a --version option, that will display the property content.

Access: public

Type: string

[ Top ]

Method Detail

__construct (Constructor) [line 290]

void __construct(
[array
$params = array()])

Constructor.

Example:

 $parser = new Console_CommandLine (array(

   'name'        => 'yourprogram', // defaults to argv[0]
   'description'    => 'Description of your program',
   'version'      => '0.0.1', // your program version
   'add_help_option'  => true, // or false to disable --help option
   'add_version_option' => true, // or false to disable --version option
   'force_posix'    => false // or true to force posix compliance
 ));

Access: public

Overridden in child classes as:

Console_CommandLine_Command::__construct(): Constructor.

Parameters:

array $params — An optional array of parameters

[ Top ]

accept [line 341]

void accept(
mixed
$instance)

Method to allow Console_CommandLine to accept either:

a custom renderer,
a custom outputter,
or a custom message provider

Throws: Console_CommandLine_Exception if wrong argument passed
Access: public

Parameters:

mixed $instance — The custom instance

[ Top ]

addArgument [line 466]

Console_CommandLine_Argument addArgument(
mixed
$name, [array
$params = array()])

Adds an argument to the command line parser and returns it.

Adds an argument with the name $name and set its attributes with the array $params, then return the Console_CommandLine_Argument instance created. The method accepts another form: you can directly pass a Console_CommandLine_Argument object as the sole argument, this allows you to contruct the argument separately, in order to reuse it in different command line parsers or commands for example.

Example:

 $parser = new Console_CommandLine ();

 // add an array argument
 $parser->addArgument ('input_files', array('multiple'=>true));
 // add a simple argument
 $parser->addArgument ('output_file');
 $result = $parser->parse ();
 print_r ($result->args ['input_files']);
 print_r ($result->args ['output_file']);
 // will print:
 // array('file1', 'file2')
 // 'file3'
 // if the command line was:
 // myscript.php file1 file2 file3

In a terminal, the help will be displayed like this:

 $ myscript.php install -h

 Usage: myscript.php <input_files...> <output_file>

Return: the added argument
See: Console_CommandLine_Argument
Access: public

Parameters:

mixed $name — A string containing the argument name or an instance of Console_CommandLine_Argument

array $params — An array containing the argument attributes

[ Top ]

addBuiltinOptions [line 1122]

void addBuiltinOptions(
)

Adds the builtin "Help" and "Version" options if needed.

Access: public

[ Top ]

addCommand [line 527]

Console_CommandLine_Command addCommand(
mixed
$name, [array
$params = array()])

Adds a sub-command to the command line parser.

Adds a command with the given $name to the parser and returns the Console_CommandLine_Command instance, you can then populate the command with options, configure it, etc... like you would do for the main parser because the class Console_CommandLine_Command inherits from Console_CommandLine.

An example:

 $parser = new Console_CommandLine ();

 $install_cmd = $parser->addCommand ('install');
 $install_cmd->addOption (
   'verbose',
   array(
     'short_name' => '-v',
     'long_name'  => '--verbose',
     'description' => 'be noisy when installing stuff',
     'action'   => 'StoreTrue'
   )
 );
 $parser->parse ();

Then in a terminal:

 $ myscript.php install -h
 Usage: myscript.php install [options ]

 Options:
  -h, --help   display this help message and exit
  -v, --verbose be noisy when installing stuff

 $ myscript.php install --verbose
 Installing whatever...
 $

Return: the added subcommand
See: Console_CommandLine_Command
Access: public

Parameters:

mixed $name — A string containing the command name or an instance of Console_CommandLine_Command

array $params — An array containing the command attributes

[ Top ]

addOption [line 615]

Console_CommandLine_Option addOption(
mixed
$name, [array
$params = array()])

Adds an option to the command line parser and returns it.

Adds an option with the name $name and set its attributes with the array $params, then return the Console_CommandLine_Option instance created. The method accepts another form: you can directly pass a Console_CommandLine_Option object as the sole argument, this allows you to contruct the option separately, in order to reuse it in different command line parsers or commands for example.

Example:

 $parser = new Console_CommandLine ();

 $parser->addOption ('path', array(
   'short_name' => '-p', // a short name
   'long_name'  => '--path', // a long name
   'description' => 'path to the dir', // a description msg
   'action'   => 'StoreString',
   'default'   => '/tmp' // a default value
 ));
 $parser->parse ();

In a terminal, the help will be displayed like this:

 $ myscript.php --help

 Usage: myscript.php [options ]

 Options:
  -h, --help display this help message and exit
  -p, --path path to the dir

Various methods to specify an option, these 3 commands are equivalent:

 $ myscript.php --path=some/path

 $ myscript.php -p some/path
 $ myscript.php -psome/path

Return: The added option
See: Console_CommandLine_Option
Access: public

Parameters:

mixed $name — A string containing the option name or an instance of Console_CommandLine_Option

array $params — An array containing the option attributes

[ Top ]

displayError [line 655]

void displayError(
string
$error, [int
$exitCode = 1])

Displays an error to the user via stderr and exit with $exitCode if its value is not equals to false.

Access: public

Parameters:

string $error — The error message

int $exitCode — The exit code number (default: 1). If set to false, the exit() function will not be called

[ Top ]

displayUsage [line 675]

void displayUsage(
[int
$exitCode = 0])

Displays the usage help message to the user via stdout and exit with $exitCode if its value is not equals to false.

Access: public

Parameters:

int $exitCode — The exit code number (default: 0). If set to false, the exit() function will not be called

[ Top ]

displayVersion [line 696]

void displayVersion(
[int
$exitCode = 0])

Displays the program version to the user via stdout and exit with $exitCode if its value is not equals to false.

Access: public

Parameters:

int $exitCode — The exit code number (default: 0). If set to false, the exit() function will not be called

[ Top ]

findOption [line 715]

mixed findOption(
string
$str)

Finds the option that matches the given short_name (ex: -v), long_name (ex: --verbose) or name (ex: verbose).

Return: A Console_CommandLine_Option instance or false
Access: public

Parameters:

string $str — The option identifier

[ Top ]

fromXmlFile [line 379]

Console_CommandLine fromXmlFile(
string
$file)

Returns a command line parser instance built from an xml file.

Example:

 require_once 'Console/CommandLine.php';

 $parser = Console_CommandLine ::fromXmlFile ('path/to/file.xml');
 $result = $parser->parse ();

Return: The parser instance
Access: public

Parameters:

string $file — Path to the xml file

[ Top ]

fromXmlString [line 416]

Console_CommandLine fromXmlString(
string
$string)

Returns a command line parser instance built from an xml string.

Example:

 require_once 'Console/CommandLine.php';

 $xmldata = '<?xml version="1.0" encoding="utf-8" standalone="yes"?>
 <command>
  <description>Compress files</description>
  <option name="quiet">
   <short_name>-q</short_name>
   <long_name>--quiet</long_name>
   <description>be quiet when run</description>
   <action>StoreTrue/action>
  </option>
  <argument name="files">
   <description>a list of files</description>
   <multiple>true</multiple>
  </argument>
 </command>';
 $parser = Console_CommandLine ::fromXmlString ($xmldata);
 $result = $parser->parse ();

Return: The parser instance
Access: public

Parameters:

string $string — The xml data

[ Top ]

getArgcArgv [line 1160]

array getArgcArgv(
)

Tries to return an array containing argc and argv, or trigger an error if it fails to get them.

Return: The argc/argv array
Throws: Console_CommandLine_Exception
Access: protected

[ Top ]

parse [line 851]

Console_CommandLine_Result parse(
[integer
$userArgc = null], [array
$userArgv = null])

Parses the command line arguments and returns a Console_CommandLine_Result instance.

Return: The result instance
Throws: Exception on user errors
Access: public

Parameters:

integer $userArgc — Number of arguments (optional)

array $userArgv — Array containing arguments (optional)

[ Top ]

parseToken [line 952]

void parseToken(
string
$token, object
$result, array
&$args, int
$argc)

Parses the command line token and modifies *by reference* the $options and $args arrays.

Throws: Exception on user errors
Access: protected

Parameters:

string $token — The command line token to parse

object $result — The Console_CommandLine_Result instance

array &$args — The argv array

int $argc — Number of lasting args

[ Top ]

registerAction [line 802]

void registerAction(
string
$name, string
$class)

Registers a custom action for the parser, an example:

 // in this example we create a "range" action:

 // the user will be able to enter something like:
 // $ <program> -r 1,5
 // and in the result we will have:
 // $result->options['range']: array(1, 5)

 require_once 'Console/CommandLine.php';
 require_once 'Console/CommandLine/Action.php';

 class ActionRange extends Console_CommandLine_Action 
 {
   public function execute($value=false, $params=array())
   {
     $range = explode (',', str_replace (' ', '', $value));
     if (count ($range) != 2) {
       throw new Exception(sprintf (
         'Option "%s" must be 2 integers separated by a comma',
         $this->option->name
       ));
     }
     $this->setResult($range);
   }
 }
 // then we can register our action
 Console_CommandLine ::registerAction ('Range', 'ActionRange');
 // and now our action is available !
 $parser = new Console_CommandLine ();
 $parser->addOption('range', array(
   'short_name' => '-r',
   'long_name'  => '--range',
   'action'   => 'Range', // note our custom action
   'description' => 'A range of two integers separated by a comma'
 ));
 // etc...

Access: public

Parameters:

string $name — The name of the custom action

string $class — The class name of the custom action

[ Top ]

triggerError [line 827]

void triggerError(
string
$msgId, int
$level, [array
$params = array()])

A wrapper for programming errors triggering.

Todo: remove Console::triggerError() and use exceptions only
Access: public

Parameters:

string $msgId — Identifier of the message

int $level — The php error level

array $params — An array of search=>replaces entries

[ Top ]