Logo Search packages:      
Sourcecode: t1utils version File versions  Download package

clp.h File Reference


Detailed Description

Functions for parsing command line options.

The CLP functions are used to parse command line arugments into options. It automatically handles value parsing, error messages, long options with minimum prefix matching, short options, and negated options.

The CLP model works like this.

  1. The user declares an array of Clp_Option structures that define the options their program accepts.
  2. The user creates a Clp_Parser object using Clp_NewParser(), passing in the command line arguments to parse and the Clp_Option structures.
  3. A loop repeatedly calls Clp_Next() to parse the arguments.

Unlike many command line parsing libraries, CLP steps through all arguments one at a time, rather than slurping up all options at once. This makes it meaningful to give an option more than once.

Here's an example.

 #define ANIMAL_OPT 1
 #define VEGETABLE_OPT 2
 #define MINERALS_OPT 3
 #define USAGE_OPT 4

 static const Clp_Option options[] = {
     { "animal", 'a', ANIMAL_OPT, Clp_ValString, 0 },
     { "vegetable", 'v', VEGETABLE_OPT, Clp_ValString, Clp_Negate | Clp_Optional },
     { "minerals", 'm', MINERALS_OPT, Clp_ValInt, 0 },
     { "usage", 0, USAGE_OPT, 0, 0 }
 };

 int main(int argc, char *argv[]) {
     Clp_Parser *clp = Clp_NewParser(argc, argv,
               sizeof(options) / sizeof(options[0]), options);
     int opt;
     while ((opt = Clp_Next(clp)) != Clp_Done)
         switch (opt) {
         case ANIMAL_OPT:
             fprintf(stderr, "animal is %s\n", clp->val.s);
             break;
         case VEGETABLE_OPT:
             if (clp->negated)
                 fprintf(stderr, "no vegetables!\n");
             else if (clp->have_val)
                 fprintf(stderr, "vegetable is %s\n", clp->val.s);
             else
                 fprintf(stderr, "vegetables OK\n");
             break;
         case MINERALS_OPT:
             fprintf(stderr, "%d minerals\n", clp->val.i);
             break;
         case USAGE_OPT:
             fprintf(stderr, "Usage: 20q [--animal=ANIMAL] [--vegetable[=VEGETABLE]] [--minerals=N]\n");
             break;
         case Clp_NotOption:
             fprintf(stderr, "non-option %s\n", clp->vstr);
             break;
         }
     }
 }

Here are a couple of executions.

 % ./20q --animal=cat
 animal is cat
 % ./20q --animal=cat -a dog -afish --animal bird --an=snake
 animal is cat
 animal is dog
 animal is fish
 animal is bird
 animal is snake
 % ./20q --no-vegetables
 no vegetables!
 % ./20q -v
 vegetables OK
 % ./20q -vkale
 vegetable is kale
 % ./20q -m10
 10 minerals
 % ./20q -m foo
 '-m' expects an integer, not 'foo'
 

Definition in file clp.h.

Go to the source code of this file.

Classes

struct  Clp_Option
 Option description. More...
struct  Clp_Parser
 Command line parser. More...

Defines

#define Clp_AllowNumbers   (1<<0)
 String list flag: allow explicit numbers.
#define Clp_BadOption   -2
 Clp_Next value: argument was an erroneous option.
#define Clp_DisallowOptions   (1<<0)
 Value type flag: value can't be an option string.
#define Clp_Done   -1
 Clp_Next value: there are no more arguments.
#define Clp_Error   -3
 Clp_Next value: internal CLP error.
#define Clp_NotOption   0
 Clp_Next value: argument was not an option.
#define Clp_ValIntSize   10
 Minimum size of the Clp_Parser val.is field.
#define Clp_ValSize   40
 Minimum size of the Clp_Parser val.cs field.
Option character types
These flags are used in to define character types in Clp_SetOptionChar().

#define Clp_Long   (1<<1)
 Option character begins a long option.
#define Clp_LongImplicit   (1<<4)
 Option character can begin a long option, and is part of that long option.
#define Clp_LongNegated   (1<<3)
 Option character begins a negated long option.
#define Clp_Short   (1<<0)
 Option character begins a set of short options.
#define Clp_ShortNegated   (1<<2)
 Option character begins a set of negated short options.
Option flags
These flags are used in the Clp_Option flags field.

#define Clp_Mandatory   (1<<0)
 Option flag: value is mandatory.
#define Clp_Negate   (1<<2)
 Option flag: option may be negated.
#define Clp_OnlyNegated   (1<<3)
 Option flag: option must be negated.
#define Clp_Optional   (1<<1)
 Option flag: value is optional.
#define Clp_PreferredMatch   (1<<4)
 Option flag: prefer this option when matching.
Value types
These values describe the type of an option's argument and are used in the Clp_Option val_type field. For example, if an option took integers, its Clp_Option structure would have val_type set to Clp_ValInt.

#define Clp_NoVal   0
 Option takes no value.
#define Clp_ValBool   3
 Option value is a boolean.
#define Clp_ValDouble   6
 Option value is a double. Accepts a real number as defined by strtod().
#define Clp_ValFirstUser   10
 Value types >= Clp_ValFirstUser are available for user types.
#define Clp_ValInt   4
 Option value is a signed int.
#define Clp_ValString   1
 Option value is an arbitrary string.
#define Clp_ValStringNotOption   2
 Option value is a non-option string.
#define Clp_ValUnsigned   5
 Option value is an unsigned int.

Typedefs

typedef void(* Clp_ErrorHandler )(Clp_Parser *clp, const char *message)
 A function for reporting option errors.
typedef struct Clp_Option Clp_Option
typedef struct Clp_Parser Clp_Parser
typedef struct Clp_ParserState Clp_ParserState
typedef int(* Clp_ValParseFunc )(Clp_Parser *clp, const char *vstr, int complain, void *user_data)
 A value parsing function.

Functions

int Clp_AddStringListType (Clp_Parser *clp, int val_type, int flags,...) CLP_SENTINEL
 Define a new string list value type for clp.
int Clp_AddStringListTypeVec (Clp_Parser *clp, int val_type, int flags, int nstrs, const char *const *strs, const int *vals)
 Define a new string list value type for clp.
int Clp_AddType (Clp_Parser *clp, int val_type, int flags, Clp_ValParseFunc parser, void *user_data)
 Define a new value type for clp.
const char * Clp_CurOptionName (Clp_Parser *clp)
 Extract the current option as a string.
int Clp_CurOptionNameBuf (Clp_Parser *clp, char *buf, int len)
 Extract the current option as a string.
void Clp_DeleteParser (Clp_Parser *clp)
 Destroy a Clp_Parser object.
void Clp_DeleteParserState (Clp_ParserState *state)
 Destroy a Clp_ParserState object.
Clp_ParserClp_NewParser (int argc, const char *const *argv, int nopt, const Clp_Option *opt)
 Create a new Clp_Parser.
Clp_ParserState * Clp_NewParserState (void)
 Create a new Clp_ParserState.
int Clp_Next (Clp_Parser *clp)
 Parse and return the next argument from clp.
int Clp_OptionChar (Clp_Parser *clp, int c)
 Return clp's treatment of character c.
int Clp_OptionError (Clp_Parser *clp, const char *format,...)
 Report a parser error.
const char * Clp_ProgramName (Clp_Parser *clp)
 Return clp's program name.
void Clp_RestoreParser (Clp_Parser *clp, const Clp_ParserState *state)
 Restore parser state from state into clp.
void Clp_SaveParser (const Clp_Parser *clp, Clp_ParserState *state)
 Save clp's current state in state.
void Clp_SetArguments (Clp_Parser *clp, int argc, const char *const *argv)
 Set clp's arguments.
Clp_ErrorHandler Clp_SetErrorHandler (Clp_Parser *clp, Clp_ErrorHandler errh)
 Set clp's error handler function.
int Clp_SetOptionChar (Clp_Parser *clp, int c, int type)
 Set clp's treatment of character c.
int Clp_SetOptionProcessing (Clp_Parser *clp, int on)
 Set whether clp is searching for options.
int Clp_SetOptions (Clp_Parser *clp, int nopt, const Clp_Option *opt)
 Set clp's option definitions.
const char * Clp_SetProgramName (Clp_Parser *clp, const char *name)
 Set clp's program name.
int Clp_SetUTF8 (Clp_Parser *clp, int utf8)
 Set clp's UTF-8 mode.
const char * Clp_Shift (Clp_Parser *clp, int allow_options)
 Return the next argument from clp without option parsing.


Generated by  Doxygen 1.6.0   Back to index