CLI: CLI is shell argument parsing and handling class

CLI? What is it?
-------------------------------------

This is small PHP class that simplify creation of command line
PHP applications. It takes care of shell argument parsing

Requirements
-------------------------------------

Obligatory:

 - PHP interpreter <http://php.net>. This script is developed
   with PHP 4.2.x but any 4.x would do (it will fail on 3.x
   as it uses PHP 4.x specific functions here and there).
   Core installation will do. No extra modules is required.


Developer materials
-------------------------------------

 Args array
 ---------------------

 To make class work you need to define what argumens
 and option your application expects, which of them
 are required, which are optional etc. This is done
 by specifing $args table with structure as follow:

 $args = array( "option1" => array( ...params...,
                                    ...params...
                                  ),
                "option2" => array( ...params...,
                                    ..,params...
                                  )
                ...
              );

 "option" is your unique identifier you will later
 be refering to this given argument by.

 Params can be one of the following:

 "short"    - short (I suggest 1 letter here) switch
              for an option (i.e. "v")
 "long"     - long switch for an option (i.e. "version")
 "info"     - short description of an option. This text
              is used to build help page when ShowHelpPage()
              is called. Can be ommited but default is
              "--- No description. Complain! ---" message
 "required" - BOOL specifies if this option is required
              (default is FALSE). Class automatically
              checks for presence of required options
              and give you back an error if any is
              missing
 "switch"   - BOOL. If set to TRUE, option does not
              need any argument (i.e. -version). Default
              value is FALSE (so we'll need argument per
              option),
 "param"    - specifies option argument. If option is found
              it's argument value is placed here. You can
              use this field to specify default values for
              options that are not 'required'i.
 "multi"    - specifies if given option can be used more
              than once (i.e. to let use to give more than
              source dirs for your backup tool etc). Multi
              mutually excludes 'switch', but that obvious

 NOTE: you can give both short and long parameters
       per option, or ommit one of them. But at least
       one need to be specified.


 Class functions
 ---------------------

 constructor( $args );
 ---------------------------

    $cli = new CLI();

 or, with use of constructor arg:

    $cli = new CLI( $args );



 Parse( $argc, $argv [, $args]);
 ------------------------------------

 Parses user input. 3rd argument ($args array)
 can be ommited if you gave it to constructor.
 Otherwise you need to pass it here. Returns
 BOOL. When FALSE, an error occuredm and you 
 shall abort your application and display
 error message as stored in 'error_message'
 variable (see demo)


 IsOptionSet( $option );
 ------------------------------------

 Return TRUE if $option had been given by user.
 FALSE otherwise. You don't need to check against
 required options, as their presence is checked
 by Parse()


 GetOptionArg( $option );
 ------------------------------------

 Returns option argument. If option is argumentless
 it will return "".


 GetOptionArgCount( $option );
 -----------------------------------

 Returns number of values $option holds. Would return
 0 for switches, 1 for standard options or X for
 multi argument with X values. Returns FALSE if no
 $option exists


 ShowErrors();
 -----------------------------------
 
 Prints out all cumulated errors Parse() had collected.
 

 ShowHelpPage();
 -----------------------------------

 Outputs help page. Page contains usage information as
 well as list and description of each option. See demo.


Example
-------------------------------------

See self explanatory cli_demo.php for information about 
how to use the class.


Bugs? Suggestions?
-------------------------------------

Let me know of any found!


Author
-------------------------------------

 Written by Marcin Orlowski <carlos@wfmh.org.pl>
 http://www.phpclasses.org/browse.html/package/954.html


--
$Id: README,v 1.5 2003/05/24 09:13:02 carl-os Exp $