clp.h File Reference

Functions for parsing command line options. More...

#include <stdio.h>
#include <stdarg.h>

Go to the source code of this file.

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

Macros
#define	Clp_NotOption   0
	Clp_Next value: argument was not an option.
#define	Clp_Done   -1
	Clp_Next value: there are no more arguments.
#define	Clp_BadOption   -2
	Clp_Next value: argument was an erroneous option.
#define	Clp_Error   -3
	Clp_Next value: internal CLP error.
#define	Clp_ValSize   40
	Minimum size of the Clp_Parser val.cs field.
#define	Clp_ValIntSize   10
	Minimum size of the Clp_Parser val.is field.
#define	Clp_DisallowOptions   (1<<0)
	Value type flag: value can't be an option string.
#define	Clp_DashTerminated   (1<<1)
#define	Clp_AllowNumbers   (1<<0)
	String list flag: allow explicit numbers.
#define	Clp_StringListLong   (1<<1)
	String list flag: values have long type.
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_ValString   1
	Option value is an arbitrary string.
#define	Clp_ValStringNotOption   2
	Option value is a non-option string.
#define	Clp_ValBool   3
	Option value is a boolean.
#define	Clp_ValInt   4
	Option value is a signed int.
#define	Clp_ValUnsigned   5
	Option value is an unsigned int.
#define	Clp_ValLong   6
	Option value is a signed long.
#define	Clp_ValUnsignedLong   7
	Option value is an unsigned long.
#define	Clp_ValDouble   8
	Option value is a double. Accepts a real number as defined by strtod().
#define	Clp_ValStringDashTerimnated   9
	Option value is a string terminated by a double dash.
#define	Clp_ValFirstUser   10
	Value types >= Clp_ValFirstUser are available for user types.
Option flags
These flags are used in the Clp_Option flags field.
#define	Clp_Mandatory   (1<<0)
	Option flag: value is mandatory.
#define	Clp_Optional   (1<<1)
	Option flag: value is optional.
#define	Clp_Negate   (1<<2)
	Option flag: option may be negated.
#define	Clp_OnlyNegated   (1<<3)
	Option flag: option must be negated.
#define	Clp_PreferredMatch   (1<<4)
	Option flag: prefer this option when matching.
Option character types
These flags are used in to define character types in Clp_SetOptionChar().
#define	Clp_Short   (1<<0)
	Option character begins a set of short options.
#define	Clp_Long   (1<<1)
	Option character begins a long option.
#define	Clp_ShortNegated   (1<<2)
	Option character begins a set of negated short options.
#define	Clp_LongNegated   (1<<3)
	Option character begins a negated long option.
#define	Clp_LongImplicit   (1<<4)
	Option character can begin a long option, and is part of that long option.

Typedefs
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.
typedef void(*	Clp_ErrorHandler) (Clp_Parser *clp, const char *message)
	A function for reporting option errors.

Functions
Clp_Parser *	Clp_NewParser (int argc, const char *const *argv, int nopt, const Clp_Option *opt)
	Create a new Clp_Parser.
void	Clp_DeleteParser (Clp_Parser *clp)
	Destroy a Clp_Parser object.
const char *	Clp_ProgramName (Clp_Parser *clp)
	Return clp's program name.
const char *	Clp_SetProgramName (Clp_Parser *clp, const char *name)
	Set clp's program name.
Clp_ErrorHandler	Clp_SetErrorHandler (Clp_Parser *clp, Clp_ErrorHandler errh)
	Set clp's error handler function.
int	Clp_SetUTF8 (Clp_Parser *clp, int utf8)
	Set clp's UTF-8 mode.
int	Clp_OptionChar (Clp_Parser *clp, int c)
	Return clp's treatment of character c.
int	Clp_SetOptionChar (Clp_Parser *clp, int c, int type)
	Set clp's treatment of character c.
int	Clp_SetOptions (Clp_Parser *clp, int nopt, const Clp_Option *opt)
	Set clp's option definitions.
void	Clp_SetArguments (Clp_Parser *clp, int argc, const char *const *argv)
	Set clp's arguments.
int	Clp_SetOptionProcessing (Clp_Parser *clp, int on)
	Set whether clp is searching for options.
int	Clp_AddType (Clp_Parser *clp, int val_type, int flags, Clp_ValParseFunc parser, void *user_data)
	Define a new 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_AddStringListType (Clp_Parser *clp, int val_type, int flags,...) CLP_SENTINEL
	Define a new string list value type for clp.
int	Clp_Next (Clp_Parser *clp)
	Parse and return the next argument from clp.
const char *	Clp_Shift (Clp_Parser *clp, int allow_options)
	Return the next argument from clp without option parsing.
Clp_ParserState *	Clp_NewParserState (void)
	Create a new Clp_ParserState.
void	Clp_DeleteParserState (Clp_ParserState *state)
	Destroy a Clp_ParserState object.
void	Clp_SaveParser (const Clp_Parser *clp, Clp_ParserState *state)
	Save clp's current state in state.
void	Clp_RestoreParser (Clp_Parser *clp, const Clp_ParserState *state)
	Restore parser state from state into clp.
int	Clp_OptionError (Clp_Parser *clp, const char *format,...)
	Report a parser error.
int	Clp_vsnprintf (Clp_Parser *clp, char *str, size_t size, const char *format, va_list val)
	Format a message.
int	Clp_fprintf (Clp_Parser *clp, FILE *f, const char *format,...)
	Print a message.
int	Clp_vfprintf (Clp_Parser *clp, FILE *f, const char *format, va_list val)
	Print a message.
int	Clp_CurOptionNameBuf (Clp_Parser *clp, char *buf, int len)
	Extract the current option as a string.
const char *	Clp_CurOptionName (Clp_Parser *clp)
	Extract the current option as a string.
int	Clp_IsLong (Clp_Parser *clp, const char *long_name)
	Test if the current option had long name name.
int	Clp_IsShort (Clp_Parser *clp, int short_name)
	Test if the current option had short name name.

Detailed Description

Functions for parsing command line options.

The CLP functions are used to parse command line arguments 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'

Macro Definition Documentation

Clp_NoVal

#define Clp_NoVal   0

Option takes no value.

Clp_ValString

#define Clp_ValString   1

Option value is an arbitrary string.

Clp_ValStringNotOption

#define Clp_ValStringNotOption   2

Option value is a non-option string.

See Clp_DisallowOptions.

Clp_ValBool

#define Clp_ValBool   3

Option value is a boolean.

Accepts "true", "false", "yes", "no", "1", and "0", or any prefixes thereof. The match is case-insensitive.

Clp_ValInt

#define Clp_ValInt   4

Option value is a signed int.

Accepts an optional "+" or "-" sign, followed by one or more digits. The digits may be include a "0x" or "0X" prefix, for a hexadecimal number, or a "0" prefix, for an octal number; otherwise it is decimal.

Clp_ValUnsigned

#define Clp_ValUnsigned   5

Option value is an unsigned int.

Accepts an optional "+" sign, followed by one or more digits. The digits may be include a "0x" or "0X" prefix, for a hexadecimal number, or a "0" prefix, for an octal number; otherwise it is decimal.

Clp_ValLong

#define Clp_ValLong   6

Option value is a signed long.

Clp_ValUnsignedLong

#define Clp_ValUnsignedLong   7

Option value is an unsigned long.

Clp_ValDouble

#define Clp_ValDouble   8

Option value is a double. Accepts a real number as defined by strtod().

Clp_ValStringDashTerimnated

#define Clp_ValStringDashTerimnated   9

Option value is a string terminated by a double dash.

Clp_ValFirstUser

#define Clp_ValFirstUser   10

Value types >= Clp_ValFirstUser are available for user types.

Clp_Mandatory

#define Clp_Mandatory   (1<<0)

Option flag: value is mandatory.

It is an error if the option has no value. This is the default if an option has arg_type != 0 and the Clp_Optional flag is not provided.

Clp_Optional

#define Clp_Optional   (1<<1)

Option flag: value is optional.

Clp_Negate

#define Clp_Negate   (1<<2)

Option flag: option may be negated.

–no-[long_name] will be accepted in argument lists.

Clp_OnlyNegated

#define Clp_OnlyNegated   (1<<3)

Option flag: option must be negated.

–no-[long_name] will be accepted in argument lists, but –[long_name] will not. This is the default if long_name begins with "no-".

Clp_PreferredMatch

#define Clp_PreferredMatch   (1<<4)

Option flag: prefer this option when matching.

Prefixes of –[long_name] should map to this option, even if other options begin with –[long_name].

Clp_Short

#define Clp_Short   (1<<0)

Option character begins a set of short options.

Clp_Long

#define Clp_Long   (1<<1)

Option character begins a long option.

Clp_ShortNegated

#define Clp_ShortNegated   (1<<2)

Option character begins a set of negated short options.

Clp_LongNegated

#define Clp_LongNegated   (1<<3)

Option character begins a negated long option.

Clp_LongImplicit

#define Clp_LongImplicit   (1<<4)

Option character can begin a long option, and is part of that long option.

Clp_NotOption

#define Clp_NotOption   0

Clp_Next value: argument was not an option.

Clp_Done

#define Clp_Done   -1

Clp_Next value: there are no more arguments.

Clp_BadOption

#define Clp_BadOption   -2

Clp_Next value: argument was an erroneous option.

Clp_Error

#define Clp_Error   -3

Clp_Next value: internal CLP error.

Clp_ValSize

#define Clp_ValSize   40

Minimum size of the Clp_Parser val.cs field.

Clp_ValIntSize

#define Clp_ValIntSize   10

Minimum size of the Clp_Parser val.is field.

Clp_DisallowOptions

#define Clp_DisallowOptions   (1<<0)

Value type flag: value can't be an option string.

See Clp_AddType().

Clp_AllowNumbers

#define Clp_AllowNumbers   (1<<0)

String list flag: allow explicit numbers.

See Clp_AddStringListType() and Clp_AddStringListTypeVec().

Clp_StringListLong

#define Clp_StringListLong   (1<<1)

String list flag: values have long type.

Typedef Documentation

Clp_ValParseFunc

typedef int(* Clp_ValParseFunc) (Clp_Parser *clp, const char *vstr, int complain, void *user_data)

A value parsing function.

Parameters

clp	the parser
vstr	the value to be parsed
complain	if nonzero, report error messages via Clp_OptionError
user_data	user data passed to Clp_AddType()

Returns

1 if parsing succeeded, 0 otherwise

Clp_ErrorHandler

typedef void(* Clp_ErrorHandler) (Clp_Parser *clp, const char *message)

A function for reporting option errors.

Parameters

clp	the parser
message	error message

Function Documentation

Clp_NewParser()

Clp_Parser * Clp_NewParser	(	int	argc,
		const char *const *	argv,
		int	nopt,
		const Clp_Option *	opt
	)

Create a new Clp_Parser.

never

Parameters

argc	number of arguments
argv	argument array
nopt	number of option definitions
opt	option definition array

Returns

the parser

The new Clp_Parser that will parse the arguments in argv according to the option definitions in opt.

The Clp_Parser is created with the following characteristics:

• The "-" character introduces short options (Clp_SetOptionChar(clp, '-', Clp_Short)).
• Clp_ProgramName is set from the first argument in argv, if any. The first argument returned by Clp_Next() will be the second argument in argv. Note that this behavior differs from Clp_SetArguments.
• UTF-8 support is on iff the LANG environment variable contains one of the substrings "UTF-8", "UTF8", or "utf8". Override this with Clp_SetUTF8().
• The Clp_ValString, Clp_ValStringNotOption, Clp_ValInt, Clp_ValUnsigned, Clp_ValLong, Clp_ValUnsignedLong, Clp_ValBool, and Clp_ValDouble types are installed.
• Errors are reported to standard error.

You may also create a Clp_Parser with no arguments or options (Clp_NewParser(0, 0, 0, 0)) and set the arguments and options later.

Returns NULL if there isn't enough memory to construct the parser.

Note

The CLP library will not modify the contents of argv or opt. The calling program must not modify opt. It may modify argv in limited cases.

Clp_DeleteParser()

void Clp_DeleteParser

(

Clp_Parser *

clp

)

Destroy a Clp_Parser object.

Parameters

clp	the parser

All memory associated with clp is freed.

Clp_ProgramName()

const char * Clp_ProgramName

(

Clp_Parser *

clp

)

Return clp's program name.

Clp_SetProgramName()

const char * Clp_SetProgramName	(	Clp_Parser *	clp,
		const char *	name
	)

Set clp's program name.

Parameters

clp	the parser
name	new program name

Returns

previous program name

The calling program should not modify or free name until clp itself is destroyed.

Clp_SetErrorHandler()

Clp_ErrorHandler Clp_SetErrorHandler	(	Clp_Parser *	clp,
		Clp_ErrorHandler	errh
	)

Set clp's error handler function.

Clp_SetUTF8()

int Clp_SetUTF8	(	Clp_Parser *	clp,
		int	utf8
	)

Set clp's UTF-8 mode.

Parameters

clp	the parser
utf8	does the parser support UTF-8?

Returns

previous UTF-8 mode

In UTF-8 mode, all input strings (arguments and long names for options) are assumed to be encoded via UTF-8, and all character names (Clp_SetOptionChar() and short names for options) may cover the whole Unicode range. Out of UTF-8 mode, all input strings are treated as binary, and all character names must be unsigned char values.

Furthermore, error messages in UTF-8 mode may contain Unicode quote characters.

Clp_OptionChar()

int Clp_OptionChar	(	Clp_Parser *	clp,
		int	c
	)

Return clp's treatment of character c.

Parameters

clp	the parser
c	character

Returns

option character treatment

Returns an integer specifying how CLP treats arguments that begin with character c. See Clp_SetOptionChar for possibilities.

Clp_SetOptionChar()

int Clp_SetOptionChar	(	Clp_Parser *	clp,
		int	c,
		int	type
	)

Set clp's treatment of character c.

Parameters

clp	the parser
c	character
type	option character treatment

Returns

previous option character treatment, or -1 on error

type specifies how CLP treats arguments that begin with character c. Possibilities are:

Clp_NotOption (or 0)

The argument cannot be an option.

Clp_Long

The argument is a long option.

Clp_Short

The argument is a set of short options.

Clp_Short|Clp_Long

The argument is either a long option or, if no matching long option is found, a set of short options.

Clp_LongNegated

The argument is a negated long option. For example, after Clp_SetOptionChar(clp, '^', Clp_LongNegated), the argument "^foo" is equivalent to "--no-foo".

Clp_ShortNegated

The argument is a set of negated short options.

Clp_ShortNegated|Clp_LongNegated

The argument is either a negated long option or, if no matching long option is found, a set of negated short options.

Clp_LongImplicit

The argument may be a long option, where the character c is actually part of the long option name. For example, after Clp_SetOptionChar(clp, 'f', Clp_LongImplicit), the argument "foo" may be equivalent to "--foo".

In UTF-8 mode, c may be any Unicode character. Otherwise, c must be an unsigned char value. The special character 0 assigns type to every character.

It is an error if c is out of range, type is illegal, or there are too many character definitions stored in clp already. The function returns -1 on error.

A double hyphen "--" always introduces a long option. This behavior cannot currently be changed with Clp_SetOptionChar().

Clp_SetOptions()

int Clp_SetOptions	(	Clp_Parser *	clp,
		int	nopt,
		const Clp_Option *	opt
	)

Set clp's option definitions.

Parameters

clp	the parser
nopt	number of option definitions
opt	option definition array

Returns

0 on success, -1 on failure

Installs the option definitions in opt. Future option parsing will use opt to search for options.

Also checks opt's option definitions for validity. "CLP internal errors" are reported via Clp_OptionError() if:

• An option has a negative ID.
• Two different short options have the same name.
• Two different long options have the same name.
• A short and a long option are ambiguous, in that some option character might introduce either a short or a long option (e.g., Clp_SetOptionChar(clp, '-', Clp_Long|Clp_Short)), and a short name equals a long name.

If necessary memory cannot be allocated, this function returns -1 without modifying the parser.

Note

The CLP library will not modify the contents of argv or opt. The calling program must not modify opt either until another call to Clp_SetOptions() or the parser is destroyed.

Clp_SetArguments()

void Clp_SetArguments	(	Clp_Parser *	clp,
		int	argc,
		const char *const *	argv
	)

Set clp's arguments.

Parameters

clp	the parser
argc	number of arguments
argv	argument array

Installs the arguments in argv for parsing. Future option parsing will analyze argv.

Unlike Clp_NewParser(), this function does not treat argv[0] specially. The first subsequent call to Clp_Next() will analyze argv[0].

This function also sets option processing to on, as by Clp_SetOptionProcessing(clp, 1).

Note

The CLP library will not modify the contents of argv. The calling program should not generally modify the element of argv that CLP is currently analyzing.

Clp_SetOptionProcessing()

int Clp_SetOptionProcessing	(	Clp_Parser *	clp,
		int	on
	)

Set whether clp is searching for options.

Parameters

clp	the parser
on	whether to search for options

Returns

previous option processing setting

When option processing is off, every call to Clp_Next() returns Clp_NotOption. By default the option "--" turns off option processing and is otherwise ignored.

Clp_AddType()

int Clp_AddType	(	Clp_Parser *	clp,
		int	val_type,
		int	flags,
		Clp_ValParseFunc	parser,
		void *	user_data
	)

Define a new value type for clp.

Parameters

clp	the parser
val_type	value type ID
flags	value type flags
parser	parser function
user_data	user data for parser function

Returns

0 on success, -1 on failure

Defines argument type val_type in parser clp. The parsing function parser will be passed argument values for type val_type. It should parse the argument into values (usually in clp->val, but sometimes elsewhere), report errors if necessary, and return whether the parse was successful.

Any prior argument parser match val_type is removed. val_type must be greater than zero.

flags specifies additional parsing flags. At the moment the only relevant flag is Clp_DisallowOptions, which means that separated values must not look like options. For example, assume argument –a/-a has mandatory value type Clp_ValStringNotOption (which has Clp_DisallowOptions). Then:

• –a=–b will parse with value –b.
• -a–b will parse with value –b.
• –a –b will not parse, since the mandatory value looks like an option.
• -a –b will not parse, since the mandatory value looks like an option.

Clp_AddStringListTypeVec()

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.

Parameters

clp	the parser
val_type	value type ID
flags	string list flags
nstrs	number of strings in list
strs	array of strings
vals	array of values

Returns

0 on success, -1 on failure

Defines argument type val_type in parser clp. The parsing function sets clp->val.i to an integer. The value string is matched against the strs. If there's a unique match, the corresponding entry from vals is returned. Unique prefix matches also work. Finally, if flags contains the Clp_AllowNumbers flag, then integers are also accepted.

For example:

const char * const strs[] = { "cat", "cattle", "dog" };
const int vals[]          = { 1,     2,        3     };
Clp_AddStringListTypeVec(clp, 100, Clp_AllowNumbers, 3, strs, vals);

Say that option –animal takes value type 100. Then:

• –animal=cat will succeed and set clp->val.i = 1.
• –animal=cattle will succeed and set clp->val.i = 2.
• –animal=dog will succeed and set clp->val.i = 3.
• –animal=d will succeed and set clp->val.i = 3.
• –animal=c will fail, since c is ambiguous.
• –animal=4 will succeed and set clp->val.i = 4.

Note

The CLP library will not modify the contents of strs or vals. The calling program can modify the strs array, but the actual strings (for instance, strs[0] and strs[1]) must not be modified or freed until the parser is destroyed.

Clp_AddStringListType()

int Clp_AddStringListType	(	Clp_Parser *	clp,
		int	val_type,
		int	flags,
			...
	)

Define a new string list value type for clp.

Parameters

clp	the parser
val_type	value type ID
flags	string list flags

Returns

0 on success, -1 on failure

Defines argument type val_type in parser clp. The parsing function sets clp->val.i to an integer. The value string is matched against strings provided in the ellipsis arguments. For example, the Clp_AddStringListType() call below has the same effect as the Clp_AddStringListTypeVec() call:

For example:

Clp_AddStringListType(clp, 100, Clp_AllowNumbers, "cat", 1,
                      "cattle", 2, "dog", 3, (const char *) NULL);
 
const char * const strs[] = { "cat", "cattle", "dog" };
const int vals[]          = { 1,     2,        3     };
Clp_AddStringListTypeVec(clp, 100, Clp_AllowNumbers, 3, strs, vals);

Note

The CLP library will not modify any of the passed-in strings. The calling program must not modify or free them either until the parser is destroyed.

Clp_Next()

int Clp_Next

(

Clp_Parser *

clp

)

Parse and return the next argument from clp.

Parameters

clp	the parser

Returns

option ID of next option

Parse the next argument from the argument list, store information about that argument in the fields of clp, and return the option's ID.

If an argument was successfully parsed, that option's ID is returned. Other possible return values are:

Clp_Done

There are no more arguments.

Clp_NotOption

The next argument was not an option. The argument's text is clp->vstr (and clp->val.s).

Clp_BadOption

The next argument was a bad option: either an option that wasn't understood, or an option lacking a required value, or an option whose value couldn't be parsed. The option has been skipped.

Clp_Error

There was an internal error. This should never occur unless a user messes with, for example, a Clp_Option array.

The fields of clp are set as follows.

negated

1 if the option was negated, 0 if it wasn't.

have_val

1 if the option had a value, 0 if it didn't. Note that negated options are not allowed to have values.

vstr

The value string, if any. NULL if there was no value.

val

An option's value type will parse the value string into this union.

The parsed argument is shifted off the argument list, so that sequential calls to Clp_Next() step through the argument list.

Clp_Shift()

const char * Clp_Shift	(	Clp_Parser *	clp,
		int	allow_options
	)

Return the next argument from clp without option parsing.

Parameters

clp	the parser
allow_options	whether options will be allowed

Remove and return the next argument from clp's argument array. If there are no arguments left, or if the next argument is an option and allow_options != 0, then returns null.

Clp_NewParserState()

Clp_ParserState * Clp_NewParserState

(

void

)

Create a new Clp_ParserState.

Returns

the parser state

A Clp_ParserState object can store a parsing state of a Clp_Parser object. This state specifies exactly how far the Clp_Parser has gotten in parsing an argument list. The Clp_SaveParser() and Clp_RestoreParser() functions can be used to save this state and then restore it later, allowing a Clp_Parser to switch among argument lists.

The initial state is empty, in that after Clp_RestoreParser(clp, state), Clp_Next(clp) would return Clp_Done.

Parser states can be saved and restored among different parser objects.

See also

Clp_DeleteParserState, Clp_SaveParser, Clp_RestoreParser

Clp_DeleteParserState()

void Clp_DeleteParserState

(

Clp_ParserState *

state

)

Destroy a Clp_ParserState object.

Parameters

state

parser state

The memory associated with state is freed.

Clp_SaveParser()

void Clp_SaveParser	(	const Clp_Parser *	clp,
		Clp_ParserState *	state
	)

Save clp's current state in state.

Parameters

clp	the parser
state	parser state

See also

Clp_NewParserState, Clp_RestoreParser

Clp_RestoreParser()

void Clp_RestoreParser	(	Clp_Parser *	clp,
		const Clp_ParserState *	state
	)

Restore parser state from state into clp.

Parameters

clp	the parser
state	parser state

The parser state in state is restored into clp. The next call to Clp_Next() will return the same result as it would have at the time state was saved (probably by Clp_SaveParser(clp, state)).

A parser state contains information about arguments (argc and argv; see Clp_SetArguments()) and option processing (Clp_SetOptionProcessing()), but not about options (Clp_SetOptions()). Changes to options and value types are preserved across Clp_RestoreParser().

See also

Clp_NewParserState, Clp_SaveParser

Clp_OptionError()

int Clp_OptionError	(	Clp_Parser *	clp,
		const char *	format,
			...
	)

Report a parser error.

Parameters

clp	the parser
format	error format

Format an error message from format and any additional arguments in the ellipsis. The resulting error string is then printed to standard error (or passed to the error handler specified by Clp_SetErrorHandler). Returns the number of characters printed.

The following format characters are accepted:

%c

A character (type int). Control characters are printed in caret notation. If the parser is in UTF-8 mode, the character is formatted in UTF-8. Otherwise, special characters are printed with backslashes and octal notation.

%s

A string (type const char *).

%C

The argument is a string (type const char *). The first character in this string is printed. If the parser is in UTF-8 mode, this may involve multiple bytes.

%d

An integer (type int). Printed in decimal.

%O

The current option. No values are read from the argument list; the current option is defined in the Clp_Parser object itself.

%V

Like %O, but also includes the current value, if any.

%%

Prints a percent character.

%<

Prints an open quote string. In UTF-8 mode, prints a left single quote. Otherwise prints a single quote.

%>

Prints a closing quote string. In UTF-8 mode, prints a right single quote. Otherwise prints a single quote.

%,

Prints an apostrophe. In UTF-8 mode, prints a right single quote. Otherwise prints a single quote.

Note that no flag characters, precision, or field width characters are currently supported.

See also

Clp_SetErrorHandler

Clp_vsnprintf()

int Clp_vsnprintf	(	Clp_Parser *	clp,
		char *	str,
		size_t	size,
		const char *	format,
		va_list	val
	)

Format a message.

Parameters

clp	the parser
str	output string
size	size of output string
format	error format

Format an error message from format and any additional arguments in the ellipsis, according to the Clp_OptionError formatting conventions. The resulting string is written to str. At most size characters are written to str, including a terminating null byte. The return value is the number of characters that would have been written (excluding the terminating null byte) if size were large enough to contain the entire string.

See also

Clp_OptionError

Clp_fprintf()

int Clp_fprintf	(	Clp_Parser *	clp,
		FILE *	f,
		const char *	format,
			...
	)

Print a message.

Parameters

clp	the parser
f	output file
format	error format

Format an error message using format and additional arguments in the ellipsis, according to the Clp_OptionError formatting conventions. The resulting message is written to f.

See also

Clp_OptionError

Clp_vfprintf()

int Clp_vfprintf	(	Clp_Parser *	clp,
		FILE *	f,
		const char *	format,
		va_list	val
	)

Print a message.

Parameters

clp	the parser
f	output file
format	error format
val	arguments

Format an error message using format and val, according to the Clp_OptionError formatting conventions. The resulting message is written to f.

See also

Clp_OptionError

Clp_CurOptionNameBuf()

int Clp_CurOptionNameBuf	(	Clp_Parser *	clp,
		char *	buf,
		int	len
	)

Extract the current option as a string.

Parameters

clp	the parser
buf	output buffer
len	length of output buffer

Returns

number of characters written to the buffer, not including the terminating NUL

A string that looks like the last option parsed by clp is extracted into buf. The correct option characters are put into the string first, followed by the option text. The output buffer is null-terminated unless len == 0.

See also

Clp_CurOptionName

Clp_CurOptionName()

const char * Clp_CurOptionName

(

Clp_Parser *

clp

)

Extract the current option as a string.

Parameters

clp	the parser

Returns

string describing the current option

This function acts like Clp_CurOptionNameBuf(), but returns a pointer into a static buffer that will be rewritten on the next call to Clp_CurOptionName().

Note

This function is not thread safe.

See also

Clp_CurOptionName

Clp_IsLong()

int Clp_IsLong	(	Clp_Parser *	clp,
		const char *	long_name
	)

Test if the current option had long name name.

Clp_IsShort()

int Clp_IsShort	(	Clp_Parser *	clp,
		int	short_name
	)

Test if the current option had short name name.