libclp README
~~~~~~~~~~~~~
Version 0
$Revision: 1.3 $
$Date: 2002/08/20 04:40:39 $


libclp is a library intended to ease up parsing of complex command line
arguments or in rc files.


Index
~~~~~
I	Installation
II	Usage
    i	The ClpOpt type
    ii	The different types of options
    iii	The functions
III	Note on linking against libclp
IV	Contact


I Installation
~~~~~~~~~~~~~~

Simply use the classic ./configure && make && su -c "make install" trio to have
libclp installed to you /usr/local/lib and its headers to /usr/local/include.
The above process also compiles a test binary (from src/tst.c) but won't
install it.


II Usage
~~~~~~~~

To use libclp, you first have to determine what options your program command
line will accept, and how it will handle them (ie. will it just switch a
function on or gather an list of trailing floats ?).

i The ClpOpt type
~~~~~~~~~~~~~~~~~
Once your done with this part, you have to fill a global array of ClpOpt (which
is a structure) :

    struct _ClpOpt {
	    char sht_opt;
	    char *lng_opt;
    	    char *hlp_msg;
    	    int opt_type;
    	    void *var;
    	    int unique;
    };

    typedef struct _ClpOpt ClpOpt;

    * sht_opt is the short option (eg. 'h' to handle the -h option
    * lng_opt is the long option (eg. "help" to hanlde the --help option)
    * hlp_msg is the help message wich will be used while generating the help
    * opt_type is the type of the following var an can be one of the macros
described below
    * var is a pointer to the variable which will be filled with the result of
the parsing. Depending on the opt_type, var this variable can be of different
types according (see ii The different types of options).
    * unique must be a boolean value (ie TRUE or FALSE). If TRUE, the parser
won't parse after the given option, as this option should be used alone.

Then you have to define a global variable determining the size of the array.
Given opts1 is your ClpOpt array, int size1 = sizeof(opts1) / sizeof(ClpOpt);
will do.

ii The different types of options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ---------------------------------------------------------------------
    |	opt_type	|	*var	|	*var will contain	| 
    ---------------------------------------------------------------------
    |	OPT_SINGLE	|	int	| TRUE if the option is given	|
    |	OPT_CHAR	|	char	| the single character given	|
    |	OPT_CHAR_LIST	|	char*	| a null terminated string	|
    |	OPT_STRING	|	char*	| a null terminated string	|
    |	OPT_STRING_LIST	|	char**	| a null terminated char* list	|
    |	OPT_INT		|	int	| the atoi'd integer		|
    |	OPT_INT_LIST	|	int*	| a -1 terminated int list	|
    |	OPT_FLOAT	|	float	| the atof'd float		|
    |	OPT_FLOAT_LIST	|	float*	| a -1 terminated float list	|
    ---------------------------------------------------------------------

iii The functions
~~~~~~~~~~~~~~~~~
Finally, you have three functions available :
    * int clp_parse_opts (int argc, char **argv, ClpOpt * opts, int size);
	It is the main functions which will parse the argv, according to opts,
	    of size size.
	On success, it returns 0.
	If an option ont the command line is not recognized, it returns its
	    index (ie. you can read it with argv[index]).
	If an option needs more arguments, it returns its NEGATIVE index (ie.
	    you can read it with argv[-index]).
    * char *clp_gen_help PARAMS((ClpOpt *opts, int size, char *name));
	This functions will generate the help string corresponding to the opts
	    array and the name of the program (usually argv[0]).
    * void clp_free_help PARAMS((char *helpstring));
	clp_gen_help returns a malloc'd string, when you're finished with it,
	    you can cleanly free it with this function.
	    
If you want a live example of how to use this lib, refer to src/tst.c, which
will show all the supported types and usages.


III Note on linking against libclp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Current version of this library cannot be considered as stable. Moreover, its
interfaces are not yet clearly established and may drastically change. You must
be careful while writing program using this library as they may require a bit
more of maintenance until the first developpement phase of this library is
finished.


IV Contact
~~~~~~~~~~
If you have comments or request, you can contact me (shtrom@ssji.net).