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
Adding new command-line parameters to your script simply consists in adding Xml tags of the appropriate type to your definitions ; for example,
for filenames, and so on.
You will find here a complete reference about the parameter declarations that you can put in your
All the examples in this section assume that they are put in a script called
Moreover, it is assumed that a typical example script provides command-line parameter definitions in a variable named
By default, all command-line arguments must be prefixed by the "-" (minus or dash) character.
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 |
|
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" ;