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

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.

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) :


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 :


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 :


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


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 :


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


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 :

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


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.
  

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 :

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

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.

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

default attribute

help-group attribute

help-text attribute

hidden attribute

max-arguments attribute

min-arguments attribute

multiple attribute

name attribute

required attribute

usage attribute

value-text attribute

validation-regex attribute

Under construction

Under construction

Under construction