Preamble

The following document provides a comprehensive reference of the CLParser class.

Summary


Introduction

The CLParser (Command-Line Parser) package is yet-another command-line arguments parser.

If you are involved into developing multiple PHP scripts that are to be run as batch commands, command-line arguments parsing may become a real issue when you want this repetitive task to be reliable and easy to implement.

This package has been designed so that it will relieve you from the burden of parsing and verifying the values of command-line arguments, by implementing a vast amount of argument types and restrictions to be applied to the user-supplied values.

Don't feel yourself confused by the number of class files that make up this package ; you should never have to understand the few thousands of lines of code that make it up to use it, since a real focus has been put on making its usage really simple.

Features

The CLParser package provides the following features :
  • An xml-based language for defining command-line parameters
  • The possibility to include help contents at the command and parameter levels
  • Dozens of parameter types that can be defined for your script's command line
  • Automatic parsing and validation of user-supplied command line parameters
  • Automatic support of predefined parameters
  • A simple API for retrieving parameter values

Installation

Installation is fairly simple :
  • Copy the file CL.php and the CL/ directory somewhere in your preferred include directory
  • Include file CL.php in your PHP scripts

Getting started

Developing a batch PHP script using the CLParser package for parsing its command-line arguments is fairly straightforward ; it requires only a few steps that will quickly become familiar to you as your script development tasks will grow in quantity :
  1. Include the file CL.php in your script ; it will in turn include everything needed to perform command-line parsing
  2. Define your command-line syntax through a string containing Xml tags. These definitions will provide information such as parameter names, types, potential restrictions on their values, whether they are required or not, and so on.
  3. Instantiate a CLParser object, providing the definitions coming from step 2.
  4. Use your instance to retrieve individual parameter values.
By using the CLParser class, you will have access to features that are handled internally by the package, such as displaying command-line help, having access to a bunch of standard parameters, and much more.

A short example

Consider the following example script (let's name it example.php), which has a single parameter named string_value (note that there is an alias to this parameter, called sv) :

#!/usr/bin/php // Step 1 : include the main file, CL.php require ( 'path/to/CL.php' ) ; // Step 2 : Define the specifications of your command line $definitions = <<<END <command> <usage> A script that displays the value of its -string_value argument. </usage> <string name="string_value, sv" default="default string value"> A string value. </string> </command> END; // Step 3 : Instantiate a CLParser object, providing the above definitions $cl = new CLParser ( $definitions ) ; // Step 4 : Retrieve and use the supplied parameter values the way you like echo "The value of the string_value parameter is : " . $cl -> string_value . "\n" ;

You may have noticed that there is a $definitions variable, containing XML data. The XML format used for this is pretty simple :
  • The root node is always <command>
  • This root node contains several child items ; the above example specifies the following :
    • <usage> node : specifies a more or less short text that gives a brief description of what your script is really doing
    • <string> node : defines a parameter of type string. Its name is string_value and it has an alias named sv. You can specify as many parameter names or aliases as you like within a single parameter definition, as long as they are unique within your Xml definitions. Note that a default value has been specified for this parameter ("default string value"). Since this parameter definition is not marked as required, not supplying a value for this parameter on the command line will automatically assign the default value to your parameter, as if it had actually been specified when invoking the script.
Many other parameter types are available : booleans, integers, floats, emails, keywords, bitsets, ip addresses, etc.

One of the first things you could try now is invoking the script without any parameter :

$ php example.php

Or, if you're running Unix, if file *example.php* has the execute permission and if the directory that contains it is in your PATH, simply type :

$ example.php

which will output the default value of the -string_value parameter :

The value of the string_value parameter is : default string value

Now, to run your script specifying your own value for the string_value parameter, specify it the way you would for most Unix commands, by prepending a minus sign to its name :

$ example.php -string_value "Hello world" The value of the string_value parameter is : Hello world

Of course, you can use any alias defined together with this parameter :

$ example.php -sv "Hello world, again" The value of the string_value parameter is : Hello world, again

A note for Windows users :
Unless you define a new executable file extension using the ASSOC and FTYPE commands, add it to your PATHEXT environment variable and rename the example scripts to use this extension, you won't be able to directly execute the example scripts. You will have to invoke each script through PHP.EXE, such as in the following example :

C:\> php example.php -sv "Hello world, again"


Defining additional parameters

Adding new parameters to your script is as simple as adding new tags to your CLParser command definitions. The following example adds 3 parameters to the command definitions found in the Getting started example (for simplicity reason, only the contents of the $definitions variable will be listed below).

<command> <usage> A script that displays the value of its -string_value argument. </usage> <string name="string_value, sv" default="default string value"> A string value. </string> <flag name="flag_value, fv"> A flag value. </string> <integer name="integer_value, iv" min-value="1" max-value="100" default="1"> An integer value between 1 and 100. </string> <ip-address name="ip_address, ia"> An Ip address. </string> </command>

The parameters that have been added are the following (assume that we are using our Getting started example script) :
  • flag_value (with an alias, fv). The value of this parameter can be retrieved using the following code :

    $flag_value = $cl -> flag_value ; // or you can also use its alias : $flag_value = $cl -> fv ;

    The $flag_value variable will be true if the user specified the -flag_value parameter on the command line, and false otherwise.

  • integer_value (with an alias, iv). The value of this parameter must be in the range [1..100] and will default to 1 if it has not been specified on the command line. It can be retrieved using the following code :

    $integer_value = $cl -> integer_value ;

    The $integer_value variable will be the one specified by the user on the command line, or 1 otherwise. Note that an exception (of class CLException) will be thrown if the user specified a value outside the range [1..100].
    Since it's a numeric value, you can specify a mathematical expression as the parameter value :

    $ example.php -integer_value 8*5

  • ip_address (with an alias, ia). The value of this parameter can be retrieved using the following code :

    $ip_address = $cl -> ip_address ;

    However, if you do a print_r ( $ip_address ), you will notice that the value that the CLParser object returned is not a scalar value, but an array :

    Array ( [ip-address] => 127.0.0.1 [ip-version] => 4 [ip-bytes] => Array ( [0] => 127 [1] => 0 [2] => 0 [3] => 1 ) [ip] => 2130706433 )

    The CLParser class avoided the script developer to parse the ip address by himself and returned an array containing several information such as the supplied ip address, the ip address version (4 or 6), the individual bytes found in the ip address and, for the case of IPV4 addresses, its integer representation.

    Although you will get a scalar value with most of parameter types, some of them will return an array with already parsed data.

    You can have a look at the Parameter types reference section for a complete description of the various parameter types the CLParser class can handle.

Parameter types reference

As you might have guessed from the above introduction, making your script ready for automatic command-line arguments parsing only requires you to instantiate an object of class CLParser and passing the Xml contents containing the <command> root node to the class constructor.

Adding new command-line parameters to your script simply consists in adding Xml tags of the appropriate type to your definitions ; for example, <string> for strings, <integer> for integer values, <file> for filenames, and so on.

You will find here a complete reference about the parameter declarations that you can put in your CLParser definitions, with the following information :
All the examples in this section assume that they are put in a script called example.php, which will be run using the following command :

php example.php [example script arguments]

Moreover, it is assumed that a typical example script provides command-line parameter definitions in a variable named $definitions, and that an instance of the CLParser class has been assigned to a variable named $cl, as in the following example :

<?php require ( 'CL.php' ) ; $definitions = <<<END <command> some definitions here... </command> END ; $cl = new CLParser ( $definitions ) ;

By default, all command-line arguments must be prefixed by the "-" (minus or dash) character.

Your script must also include the file CL.php, which is bundled with this package.

Parameter attribute types

When specifying parameter definitions, you will have to provide some Xml attributes as strings. The most evident Xml attribute that you will have to provide is the name of your parameter, specified as a comma-separated list of names and aliases.

Although every xml attribute value is specified as a string, its syntax between quotes must obey to what the CLParser package expects. For example, the value of the name= parameter must be a list of 1 to n parameter names, separated by a comma. Some attributes, such as min-value, must represent an integer or floating-point value.

Don't confuse parameter attribute types with command-line parameter types : the former are used in parameter definitions as xml attributes, while the latter are the parameter definitions themselves.

The following example will you understand the difference between the two notions :
<command> <string name="string_value, sv" defaut="hello world"> </command>

In the above example, <string> starts the definition of a parameter type. name is an attribute of the command-line parameter defined by the <string> tag, and it expects a list of comma-separated identifiers. default is another attribute of the command-line parameter defined by the <string> tag, which expects as value any string accepted by the parameter being defined.

The table below lists the possible xml attribute value types that you will find in the following sections, which provide documentation for each command-line parameter type.
Attribute type Description Example value
any Any kind of string value default="hello world"
boolean A boolean parameter. Boolean values can be specified in many different forms :
  • true : "true", "1", "yes", "on"
  • false : "false", "0", "no", "off"
required="true"
character A single character value  
float A float value  
keyword A keyword from a list of authorized keywords  
keyword list A list of comma-separated keywords, from a list of authorized keywords  
list A list of comma-separated identifiers name="string_value, sv"
integer An integer value  
range A range of values, specified as : low..high  
string Any kind of string value. Equivalent of the "any" attribute value type. default="hello world"
unsigned float A float value greater than or equal to 0  
unsigned integer An integer value greater than or equal to 0  

Parameter attributes synopsis

All the parameter attributes documentation provided in the following sections include a synopsis table, which gives the following information :
Name Attribute name and aliases
Type Attribute type. See the Parameter attribute types section for more information about the various value types that can be specified as attribute values.
Member Corresponding member name, in the CLAbstractParameter object returned by the following code :
$cl = new CLParser ( $definitions ) ; print_r ( $cl [ 'name of your parameter' ] ) ;
Required Specifies whether the attribute is required or not.

Common parameter attributes

The following section describes the Xml attributes that are common to all parameter types, except otherwise stated in the parameter type documentation.

Each parameter attribute can have several aliases, which will be listed in the documentation below.

arguments attribute

Synopsis
Attribute name arguments, args, arg
Type range
Member MinArguments, MaxArguments
Required no
The arguments parameter attribute specifies how many values can be supplied after the name of a command-line parameter. Normally, all parameters accept only one value but you can extend this limit ; the following example defines a -string_value parameter that can accept up to 5 values :

<?php require ( 'CL.php' ) ; $definitions = <<<END <command> <string name="string_value, sv" arguments="1..5"> Help for the string_value parameter. </string> </command> END; $cl = new CLParser ( $definitions ) ; echo "String values are : " ; print_r ( $cl -> string_value ) ;
Note that the $cl -> string_value property is now an array of values reflecting what the caller specified on the command line.

The special notation "*" means an unlimited number of values, as in the following example :

arguments="1..*"

This attribute is a shortcut for the min-arguments and max-arguments attributes.

If the multiple attribute has been set to true, the limits imposed by the arguments or min-arguments/max-arguments attributes apply.

If the number of values specified on the command line for a given parameter exceeds the maximum allowed, then the extra values will be considered either as a parameter name or as a positional parameter ; in this case, the exception that will be thrown will talk about either an incorrect parameter name or about the fact that unnamed parameters are not allowed on the command line.
However, if your command definitions are such that positional parameters are authorized, then your extra values will be recognized as positional parameters.

default attribute

Synopsis
Attribute name default, default-value
Type string
Member DefaultValue
Required no
The xml attribute named default is used to specify a default value for a given parameter, which will be available even if the user did not specify this parameter on the command line :

The following example will display the string "hello world" if the user did not specify a value for the -string_value parameter during script execution :

<?php require ( 'CL.php' ) ; $definitions = <<<END <command> <string name="string_value, sv" default="hello world"> Help for the string_value parameter. </string> </command> END; $cl = new CLParser ( $definitions ) ; echo "String value is : " . $cl -> string_value ;

help-group attribute

Synopsis
Attribute name help-group, help-groups, help-topic, help-topics, topic, topics
Type list
Member HelpTopics
Required no
Allows you to associate a parameter with a help topic. Help topics are a way to group parameter together when displaying help using the reserved -help option.

The topic(s) referenced by this attribute must have been defined at the <command> tag level, using the <help-group> tag or one of its aliases.

The following example shows a script defining two help groups (or topics) : the first one is called strings and includes only the -string_value parameter ; the second one is called integers and includes the -integer_value1 and integer_value2 parameters :

<?php require ( 'CL.php' ) ; $definitions = <<<END <command> <topic name="strings, string, str"> General help for parameters belonging to the "strings" topic. </topic> <topic name="integers, integer, int"> General help for parameters belonging to the "integers" topic. </topic> <string name="string_value, sv" topic="strings"> Help for the -string_value parameter. </string> <integer name="integer_value1, iv1" topic="integers"> Help for the -integer_value1 parameter. </integer> <integer name="integer_value2, iv2" topic="integers"> Help for the -integer_value2 parameter. </integer> </command> END; $cl = new CLParser ( $definitions ) ; echo "Value for the -string_value parameter : " ; print_r ( $cl -> string_value ) ;

Running this script with the -help parameter will display the following help text :

Usage : help-group [-string_value string] [-integer_value1 integer] [-integer_value2 integer] [-string_value string] (-sv) : Help for the -string_value parameter. [-integer_value1 integer] (-iv1) : Help for the -integer_value1 parameter. [-integer_value2 integer] (-iv2) : Help for the -integer_value2 parameter. Available help topics : integers, strings

Notice the extra line listing the available help topics. If you want further information about the availbale topics, then you can run the script with the -topics reserved parameter ; the output will be the following :

$ php example.php -topics Available help topics - integers, integer, int : General help for parameters belonging to the "integers" topic. strings, string, str : General help for parameters belonging to the "strings" topic.

Now you can display command line usage for a particular topic, by specifying the topic name or one of its aliases after the reserved -help parameter :

$ php example.php -help integers Usage : help-group [-string_value string] [-integer_value1 integer] [-integer_value2 integer] [-integer_value1 integer] (-iv1) : Help for the -integer_value1 parameter. [-integer_value2 integer] (-iv2) : Help for the -integer_value2 parameter.

help-text attribute

Synopsis
Attribute name help-text, help
Type string
Member HelpText
Required no
The help-text attribute is an alternative for specifying help contents for a parameter ; the examples below are strictly equivalent :

<string name="string_value, sv" help-text="Help text for the -string_value parameter" />

<string name="string_value, sv"> Help text for the -string_value parameter </string>

The help-text attribute has the precedence over the parameter node's contents.

hidden attribute

Synopsis
Attribute name hidden
Type boolean
Member Hidden
Required no
The hidden parameter attribute indicates whether the parameter help should be displayed for this parameter when running the script with the -help argument.

Parameter help is always displayed by default, unless you set the hidden attribute to false

The following example script defines two parameters ; one of them, integer_value is hidden :

<?php require ( 'CL.php' ) ; $definitions = <<<END <command> <string name="string_value, sv" > Help for the string_value parameter. </string> <integer name="integer_value, iv" hidden="true" default="1"> Help for the hidden integer_value parameter. </integer> </command> END; $cl = new CLParser ( $definitions ) ; echo "Value of the -string_value parameter : {$cl -> string_value}\n" ; echo "Value of the -integer_value parameter : {$cl -> integer_value}\n" ;

Running your script with the -help parameter will display the following :

$ php example.php -help Usage : example [-string_value string] [-string_value string] (-sv) : Help for the string_value parameter.

If you want to display help for hidden parameters, just run your script with the special extra parameter --hidden :

$ php example.php -help --hidden Usage : example [-string_value string] [-integer_value integer] [-string_value string] (-sv) : Help for the string_value parameter. [-integer_value integer] (-iv) : Help for the hidden integer_value parameter. Default value : "1".

max-arguments attribute

Synopsis
Attribute name max-arguments, max-args
Type unsigned integer
Member MaxArguments
Required no
Specifies the maximum number of arguments for a particular parameter. See the arguments attribute for a more detailed explanation.
If the multiple attribute has been set to true, the limits imposed by the arguments or min-arguments/max-arguments attributes apply.

The special value "*" indicates an unlimited number of arguments.

min-arguments attribute

Synopsis
Attribute name min-arguments, min-args
Type unsigned integer
Member MinArguments
Required no
Specifies the minimum number of arguments for a particular parameter. See the arguments attribute for a more detailed explanation.
If the multiple attribute has been set to true, the limits imposed by the arguments or min-arguments/max-arguments attributes apply.

multiple attribute

Synopsis
Attribute name multiple
Type boolean
Member MultipleAllowed
Required no
Normally, a parameter can only be specified once on the command line. Specifying it more than once will cause an exception to be thrown.

The multiple attribute allows you to specify the same parameter on the command line multiple times.

The following example shows a script having a -string_value parameter with its multiple attribute set to true (note that the $cl -> string_value member is now an array of values, not a scalar value) :

<?php require ( 'CL.php' ) ; $definitions = <<<END <command> <string name="string_value, sv" multiple="true"> Help for the string_value parameter. </string> </command> END; $cl = new CLParser ( $definitions ) ; echo "Value for the -string_value parameter : " ; print_r ( $cl -> string_value ) ;

The limits fixed by the arguments attribute (or min-arguments and max-arguments) apply when the multiple attribute is set to true.

name attribute

Synopsis
Attribute name name, names, alias or aliases
Type list
Member Name
Required yes
Each command-line parameter must have a name, followed by a comma-separated list of optional aliases. Don't put the switch character (which defaults to "-") before each parameter name or alias.

Each parameter name and alias must be unique within the whole command definition, otherwise a CLException exception will be thrown.

The following example defines a parameter named string_value, which has an alias named sv. Both of them can be specified on the command line using either the -string_value parameter or its -sv alias :

<command> <string name="string_value, sv"> A string value that must be supplied on the command line. </string> </command>

required attribute

Synopsis
Attribute name required
Type boolean
Member Required
Required no
The xml attribute named required is used to indicate that the related parameter definition is a required command-line parameter.

The following example will throw a CLParameter exception if the -string_value parameter has not been specified on the command line :

<?php require ( 'CL.php' ) ; $definitions = <<<END <command> <string name="string_value, sv" required="true"> Help for the string_value parameter. </string> </command> END; $cl = new CLParser ( $definitions ) ;

usage attribute

Synopsis
Attribute name usage, usage-string
Type string
Member UsageString
Required no
Normally, the usage string of a parameter is built dynamically, either for its short version (when displaying command-line usage) or for its long version (when displaying parameter help).

This attribute allows to override both versions and define a custom usage string. The short and long usage strings for a parameter are shown in the help output below, in bold blue and green respectively :

Usage : default [-string_value string] Example script. [-string_value string] (-sv) : Help for the string_value parameter.

value-text attribute

Synopsis
Attribute name value-text, text
Type string
Member ValueLabel
Required no
The kind of value displayed in usage text is based on the parameter type ; for example, the usage text displayed below shows that there is a parameter called -string_value, who expects a parameter of type string :

Usage : default [-string_value string] Example script.

However, you may want to provide your user with a more meaningful clue for the parameter type (say "english noun") ; in this case, you will define your command line like this :

lt;?php require ( 'CL.php' ) ; $definitions = <<<END <command> <string name="string_value, sv" value-text="english noun"> Help for the string_value parameter. </string> </command> END;

Then, when running your script by providing the reserved -usage parameter, you will see the following instead :

Usage : default [-string_value english noun] Example script.


validation-regex attribute

Synopsis
Attribute name validation-regex, validation-expression, validation-expr
Type string
Member ValidationRegex
Required no
The validation-regex attribute specifies a regular expression to check the command-line value specified by the user. Delimiters are optional ; if not specified, a slash (/) is assumed. Note also that in the absence of regular expression delimiters, you will not be able to provide regular expression options for pattern matching.

The following example defines two parameters :
  • -string_value1, which accepts a value containing only lowercase letters. Note that the specified regular expression does not specify delimiters.
  • -string_value2, which accepts a value starting with a letter, followed by any number of letters and digits
<?php require ( 'CL.php' ) ; $definitions = <<<END <command> <string name="string_value1, sv1" validation-regex="[a-z]+"> A parameter that accepts values containing lowercase letters only. </string> <string name="string_value2, sv2" validation-regex="/[a-z][a-z0-9]*/ix"> A parameter that accepts values containing letters and digits, and starting with a letter. </string> </command> END; $cl = new CLParser ( $definitions ) ; echo "Value of -string_value1 : {$cl -> string_value1}\n" ; echo "Value of -string_value2 : {$cl -> string_value2}\n" ;

Parameter types

Under construction

Xml command language definition reference

Under construction

Command-line usage reference

Reserved parameter names

Under construction

Special parameter names

Under construction