gifsicle  1.92
About: Gifsicle is a UNIX command-line tool for creating, editing, and getting information about GIF images and animations.
  Fossies Dox: gifsicle-1.92.tar.gz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

clp.h File Reference

Functions for parsing command line options. More...

#include <stdio.h>
#include <stdarg.h>
Include dependency graph for clp.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

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. More...
 
#define Clp_Done   -1
 Clp_Next value: there are no more arguments. More...
 
#define Clp_BadOption   -2
 Clp_Next value: argument was an erroneous option. More...
 
#define Clp_Error   -3
 Clp_Next value: internal CLP error. More...
 
#define Clp_ValSize   40
 Minimum size of the Clp_Parser val.cs field. More...
 
#define Clp_ValIntSize   10
 Minimum size of the Clp_Parser val.is field. More...
 
#define Clp_DisallowOptions   (1<<0)
 Value type flag: value can't be an option string. More...
 
#define Clp_AllowNumbers   (1<<0)
 String list flag: allow explicit numbers. More...
 
#define Clp_StringListLong   (1<<1)
 String list flag: values have long type. More...
 
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. More...
 
#define Clp_ValString   1
 Option value is an arbitrary string. More...
 
#define Clp_ValStringNotOption   2
 Option value is a non-option string. More...
 
#define Clp_ValBool   3
 Option value is a boolean. More...
 
#define Clp_ValInt   4
 Option value is a signed int. More...
 
#define Clp_ValUnsigned   5
 Option value is an unsigned int. More...
 
#define Clp_ValLong   6
 Option value is a signed long. More...
 
#define Clp_ValUnsignedLong   7
 Option value is an unsigned long. More...
 
#define Clp_ValDouble   8
 Option value is a double. Accepts a real number as defined by strtod(). More...
 
#define Clp_ValFirstUser   10
 Value types >= Clp_ValFirstUser are available for user types. More...
 
Option flags

These flags are used in the Clp_Option flags field.

#define Clp_Mandatory   (1<<0)
 Option flag: value is mandatory. More...
 
#define Clp_Optional   (1<<1)
 Option flag: value is optional. More...
 
#define Clp_Negate   (1<<2)
 Option flag: option may be negated. More...
 
#define Clp_OnlyNegated   (1<<3)
 Option flag: option must be negated. More...
 
#define Clp_PreferredMatch   (1<<4)
 Option flag: prefer this option when matching. More...
 
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. More...
 
#define Clp_Long   (1<<1)
 Option character begins a long option. More...
 
#define Clp_ShortNegated   (1<<2)
 Option character begins a set of negated short options. More...
 
#define Clp_LongNegated   (1<<3)
 Option character begins a negated long option. More...
 
#define Clp_LongImplicit   (1<<4)
 Option character can begin a long option, and is part of that long option. More...
 

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

Functions

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

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;
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.

Macro Definition Documentation

◆ Clp_AllowNumbers

#define Clp_AllowNumbers   (1<<0)

String list flag: allow explicit numbers.

See Clp_AddStringListType() and Clp_AddStringListTypeVec().

Definition at line 327 of file clp.h.

◆ Clp_BadOption

#define Clp_BadOption   -2

Clp_Next value: argument was an erroneous option.

Definition at line 197 of file clp.h.

◆ Clp_DisallowOptions

#define Clp_DisallowOptions   (1<<0)

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

See Clp_AddType().

Definition at line 314 of file clp.h.

◆ Clp_Done

#define Clp_Done   -1

Clp_Next value: there are no more arguments.

Definition at line 194 of file clp.h.

◆ Clp_Error

#define Clp_Error   -3

Clp_Next value: internal CLP error.

Definition at line 200 of file clp.h.

◆ Clp_Long

#define Clp_Long   (1<<1)

Option character begins a long option.

Definition at line 175 of file clp.h.

◆ Clp_LongImplicit

#define Clp_LongImplicit   (1<<4)

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

Definition at line 184 of file clp.h.

◆ Clp_LongNegated

#define Clp_LongNegated   (1<<3)

Option character begins a negated long option.

Definition at line 181 of file clp.h.

◆ 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.

Definition at line 125 of file clp.h.

◆ Clp_Negate

#define Clp_Negate   (1<<2)

Option flag: option may be negated.

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

Definition at line 139 of file clp.h.

◆ Clp_NotOption

#define Clp_NotOption   0

Clp_Next value: argument was not an option.

Definition at line 191 of file clp.h.

◆ Clp_NoVal

#define Clp_NoVal   0

Option takes no value.

Definition at line 58 of file clp.h.

◆ 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-".

Definition at line 146 of file clp.h.

◆ Clp_Optional

#define Clp_Optional   (1<<1)

Option flag: value is optional.

Definition at line 136 of file clp.h.

◆ 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].

Definition at line 157 of file clp.h.

◆ Clp_Short

#define Clp_Short   (1<<0)

Option character begins a set of short options.

Definition at line 172 of file clp.h.

◆ Clp_ShortNegated

#define Clp_ShortNegated   (1<<2)

Option character begins a set of negated short options.

Definition at line 178 of file clp.h.

◆ Clp_StringListLong

#define Clp_StringListLong   (1<<1)

String list flag: values have long type.

Definition at line 334 of file clp.h.

◆ 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.

Definition at line 69 of file clp.h.

◆ Clp_ValDouble

#define Clp_ValDouble   8

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

Definition at line 110 of file clp.h.

◆ Clp_ValFirstUser

#define Clp_ValFirstUser   10

Value types >= Clp_ValFirstUser are available for user types.

Definition at line 115 of file clp.h.

◆ 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.

Definition at line 78 of file clp.h.

◆ Clp_ValIntSize

#define Clp_ValIntSize   10

Minimum size of the Clp_Parser val.is field.

Definition at line 207 of file clp.h.

◆ Clp_ValLong

#define Clp_ValLong   6

Option value is a signed long.

Definition at line 104 of file clp.h.

◆ Clp_ValSize

#define Clp_ValSize   40

Minimum size of the Clp_Parser val.cs field.

Definition at line 204 of file clp.h.

◆ Clp_ValString

#define Clp_ValString   1

Option value is an arbitrary string.

Definition at line 59 of file clp.h.

◆ Clp_ValStringNotOption

#define Clp_ValStringNotOption   2

Option value is a non-option string.

See Clp_DisallowOptions.

Definition at line 62 of file clp.h.

◆ 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.

Definition at line 91 of file clp.h.

◆ Clp_ValUnsignedLong

#define Clp_ValUnsignedLong   7

Option value is an unsigned long.

Definition at line 107 of file clp.h.

Typedef Documentation

◆ Clp_ErrorHandler

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

A function for reporting option errors.

Parameters
clpthe parser
messageerror message

Definition at line 226 of file clp.h.

◆ Clp_Option

typedef struct Clp_Option Clp_Option

Definition at line 31 of file clp.h.

◆ Clp_Parser

typedef struct Clp_Parser Clp_Parser

Definition at line 32 of file clp.h.

◆ Clp_ParserState

Definition at line 33 of file clp.h.

◆ Clp_ValParseFunc

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

A value parsing function.

Parameters
clpthe parser
vstrthe value to be parsed
complainif nonzero, report error messages via Clp_OptionError
user_datauser data passed to Clp_AddType()
Returns
1 if parsing succeeded, 0 otherwise

Definition at line 219 of file clp.h.

Function Documentation

◆ Clp_AddStringListType()

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

Define a new string list value type for clp.

Parameters
clpthe parser
val_typevalue type ID
flagsstring 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:

"cattle", 2, "dog", 3, (const char *) NULL);
const char * const strs[] = { "cat", "cattle", "dog" };
const int vals[] = { 1, 2, 3 };
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.

Definition at line 1285 of file clp.c.

Referenced by main().

◆ 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
clpthe parser
val_typevalue type ID
flagsstring list flags
nstrsnumber of strings in list
strsarray of strings
valsarray 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 };

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.

Definition at line 1374 of file clp.c.

◆ 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
clpthe parser
val_typevalue type ID
flagsvalue type flags
parserparser function
user_datauser 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.

Definition at line 1041 of file clp.c.

Referenced by main().

◆ Clp_CurOptionName()

const char* Clp_CurOptionName ( Clp_Parser clp)

Extract the current option as a string.

Parameters
clpthe 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

Definition at line 2460 of file clp.c.

Referenced by main().

◆ Clp_CurOptionNameBuf()

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

Extract the current option as a string.

Parameters
clpthe parser
bufoutput buffer
lenlength 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

Definition at line 2422 of file clp.c.

◆ Clp_DeleteParser()

void Clp_DeleteParser ( Clp_Parser clp)

Destroy a Clp_Parser object.

Parameters
clpthe parser

All memory associated with clp is freed.

Definition at line 579 of file clp.c.

Referenced by main().

◆ Clp_DeleteParserState()

void Clp_DeleteParserState ( Clp_ParserState state)

Destroy a Clp_ParserState object.

Parameters
stateparser state

The memory associated with state is freed.

Definition at line 1470 of file clp.c.

◆ Clp_fprintf()

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

Print a message.

Parameters
clpthe parser
foutput file
formaterror 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

Definition at line 2285 of file clp.c.

Referenced by short_usage(), and usage().

◆ Clp_IsLong()

int Clp_IsLong ( Clp_Parser clp,
const char *  long_name 
)

Test if the current option had long name name.

Definition at line 2468 of file clp.c.

◆ Clp_IsShort()

int Clp_IsShort ( Clp_Parser clp,
int  short_name 
)

Test if the current option had short name name.

Definition at line 2476 of file clp.c.

References clp, Clp_Internal::current_option, Clp_Parser::internal, Clp_Option::long_name, and Clp_Internal::opt.

◆ 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
argcnumber of arguments
argvargument array
noptnumber of option definitions
optoption 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.

Definition at line 503 of file clp.c.

Referenced by main().

◆ 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

Definition at line 1446 of file clp.c.

◆ Clp_Next()

int Clp_Next ( Clp_Parser clp)

Parse and return the next argument from clp.

Parameters
clpthe 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 arugment list.

Definition at line 1835 of file clp.c.

Referenced by main().

◆ Clp_OptionChar()

int Clp_OptionChar ( Clp_Parser clp,
int  c 
)

Return clp's treatment of character c.

Parameters
clpthe parser
ccharacter
Returns
option character treatment

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

Definition at line 652 of file clp.c.

◆ Clp_OptionError()

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

Report a parser error.

Parameters
clpthe parser
formaterror 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

Definition at line 2261 of file clp.c.

Referenced by compare_options(), main(), parse_color(), parse_dimensions(), parse_frame_spec(), parse_position(), parse_rectangle(), parse_scale_factor(), and parse_two_colors().

◆ Clp_ProgramName()

const char* Clp_ProgramName ( Clp_Parser clp)

Return clp's program name.

Definition at line 1407 of file clp.c.

References clp, Clp_Parser::internal, and Clp_Internal::program_name.

Referenced by main().

◆ Clp_RestoreParser()

void Clp_RestoreParser ( Clp_Parser clp,
const Clp_ParserState state 
)

Restore parser state from state into clp.

Parameters
clpthe parser
stateparser 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

Definition at line 1513 of file clp.c.

◆ Clp_SaveParser()

void Clp_SaveParser ( const Clp_Parser clp,
Clp_ParserState state 
)

Save clp's current state in state.

Parameters
clpthe parser
stateparser state
See also
Clp_NewParserState, Clp_RestoreParser

Definition at line 1480 of file clp.c.

Referenced by Clp_Shift().

◆ Clp_SetArguments()

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

Set clp's arguments.

Parameters
clpthe parser
argcnumber of arguments
argvargument 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.

Definition at line 871 of file clp.c.

◆ Clp_SetErrorHandler()

Clp_ErrorHandler Clp_SetErrorHandler ( Clp_Parser clp,
Clp_ErrorHandler  errh 
)

Set clp's error handler function.

Referenced by main().

◆ Clp_SetOptionChar()

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

Set clp's treatment of character c.

Parameters
clpthe parser
ccharacter
typeoption 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().

Definition at line 710 of file clp.c.

Referenced by main().

◆ Clp_SetOptionProcessing()

int Clp_SetOptionProcessing ( Clp_Parser clp,
int  on 
)

Set whether clp is searching for options.

Parameters
clpthe parser
onwhether 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.

Definition at line 894 of file clp.c.

◆ Clp_SetOptions()

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

Set clp's option definitions.

Parameters
clpthe parser
noptnumber of option definitions
optoption 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.

Definition at line 785 of file clp.c.

◆ Clp_SetProgramName()

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

Set clp's program name.

Parameters
clpthe parser
namenew program name
Returns
previous program name

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

Definition at line 1419 of file clp.c.

◆ Clp_SetUTF8()

int Clp_SetUTF8 ( Clp_Parser clp,
int  utf8 
)

Set clp's UTF-8 mode.

Parameters
clpthe parser
utf8does 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.

Definition at line 635 of file clp.c.

◆ Clp_Shift()

const char* Clp_Shift ( Clp_Parser clp,
int  allow_options 
)

Return the next argument from clp without option parsing.

Parameters
clpthe parser
allow_optionswhether 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.

Definition at line 1983 of file clp.c.

References clp, Clp_SaveParser(), and next_argument().

Referenced by parse_two_colors().

◆ Clp_vfprintf()

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

Print a message.

Parameters
clpthe parser
foutput file
formaterror format
valarguments

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

Definition at line 2310 of file clp.c.

◆ Clp_vsnprintf()

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

Format a message.

Parameters
clpthe parser
stroutput string
sizesize of output string
formaterror 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

Definition at line 2336 of file clp.c.

Referenced by error(), fatal_error(), and verror().

Clp_Negate
#define Clp_Negate
Option flag: option may be negated.
Definition: clp.h:139
options
const Clp_Option options[]
Definition: gifdiff.c:29
Clp_NewParser
Clp_Parser * Clp_NewParser(int argc, const char *const *argv, int nopt, const Clp_Option *opt)
Create a new Clp_Parser.
Definition: clp.c:503
Clp_AddStringListType
int Clp_AddStringListType(Clp_Parser *clp, int val_type, int flags,...) CLP_SENTINEL
Define a new string list value type for clp.
Definition: clp.c:1285
Clp_Done
#define Clp_Done
Clp_Next value: there are no more arguments.
Definition: clp.h:194
Clp_ValInt
#define Clp_ValInt
Option value is a signed int.
Definition: clp.h:78
Clp_NotOption
#define Clp_NotOption
Clp_Next value: argument was not an option.
Definition: clp.h:191
Clp_Parser
Command line parser.
Definition: clp.h:234
Clp_Optional
#define Clp_Optional
Option flag: value is optional.
Definition: clp.h:136
Clp_Parser::s
const char * s
Definition: clp.h:249
clp
static Clp_Parser * clp
Definition: gifdiff.c:58
Clp_Parser::negated
int negated
Definition: clp.h:237
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.
Definition: clp.c:1374
Clp_Next
int Clp_Next(Clp_Parser *clp)
Parse and return the next argument from clp.
Definition: clp.c:1835
Clp_Option
Option description.
Definition: clp.h:41
main
int main(int argc, char *argv[])
Definition: gifdiff.c:539
Clp_Parser::have_val
int have_val
Definition: clp.h:239
Clp_Parser::vstr
const char * vstr
Definition: clp.h:240
Clp_Parser::val
union Clp_Parser::@0 val
Clp_ValString
#define Clp_ValString
Option value is an arbitrary string.
Definition: clp.h:59
Clp_AllowNumbers
#define Clp_AllowNumbers
String list flag: allow explicit numbers.
Definition: clp.h:327
Clp_Parser::i
int i
Definition: clp.h:244