OB.DAAC Logo
NASA Logo
Ocean Color Science Software

ocssw V2022
argpar.h File Reference
#include <limits.h>
#include <math.h>
#include <stdio.h>
Include dependency graph for argpar.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  argpar_option
 
struct  argpar_state
 
struct  argpar_child
 
struct  argpar
 

Macros

#define ARGPAR_API_VERSION   2001000
 
#define ARGPAR_API_VERSION_STR   "2.1.0"
 
#define MAX_PARFILES   64
 
#define PARFILE_STR   "parfile"
 
#define ARGPAR_CAST_ARGS   0x1
 
#define ARGPAR_SKIP_PARFILES   0x2
 
#define ARGPAR_NO_KEYARGS   0x4
 
#define ARGPAR_NO_HELP   0x8
 
#define ARGPAR_NO_EXIT   0x10
 
#define ARGPAR_ACCEPT_ANY   0x20
 
#define ARGPAR_STORE_PARAMS   0x40
 
#define OPTION_ARG_OPTIONAL   0x1
 
#define OPTION_HIDDEN   0x2
 
#define OPTION_DOC   0x4
 
#define OPTION_DBL   0x10
 
#define OPTION_INT   0x20
 
#define OPTION_PARENT   0x40
 
#define OPTION_CHILD   0x80
 
#define OPTION_DOC_NO_BREAK   0x100
 
#define OPTION_ALIAS   0x200
 
#define OPTION_ENUM   (OPTION_DOC | 0x400)
 
#define OPTION_ATTR   (OPTION_DOC | OPTION_HIDDEN | 0x800)
 
#define ARGPAR_KEY_ARG   0
 
#define ARGPAR_KEY_ARGS   -8
 
#define ARGPAR_KEY_END   -1
 
#define ARGPAR_KEY_INIT   -3
 
#define ARGPAR_KEY_FINI   -4
 
#define ARGPAR_KEY_SUCCESS   -5
 
#define ARGPAR_KEY_ERROR   -6
 
#define ARGPAR_KEY_NO_ARGS   -7
 
#define ARGPAR_KEY_UNKNOWN   -8
 
#define ARGPAR_KEY_HELP_ARGS_DOC   -1
 
#define ARGPAR_KEY_HELP_PRE_DOC   -2
 
#define ARGPAR_KEY_HELP_POST_DOC   -3
 
#define ARGPAR_KEY_HELP_HEADER   -4
 
#define ARGPAR_KEY_HELP_OPTION_DOC   -5
 
#define ARGPAR_KEY_HELP_EXTRA   -7 /* After all other documentation; text is NULL for this key. */
 
#define ARGPAR_ERR_ABORT   -1
 
#define ARGPAR_ERR_USAGE   -2
 
#define ARGPAR_ERR_UNKNOWN   -5
 
#define ARGPAR_ERR_PARFILE   -3
 
#define ARGPAR_LIMIT_REACHED   -4
 
#define NULL_INT   INT_MIN
 
#define EMPTY_INT   INT_MAX
 

Typedefs

typedef int(* argpar_parser) (int key, char *argv, argpar_state *state)
 
typedef char *(* help_filter) (int key, const char *text, void *input)
 

Functions

int argpar_clean (argpar *p)
 
int argpar_parse_file (argpar *p, const char *path, unsigned flags, void *input)
 
int argpar_parse_args (argpar *p, unsigned argc, char *argv[], unsigned flags, unsigned *end_index, void *input)
 
int argpar_usage (argpar_state *state)
 
int argpar_usage_default (argpar *argpar)
 
int argpar_help (argpar *argpar, FILE *stream, unsigned flags, char *name)
 
int argpar_usage_json (argpar_state *state)
 
int argpar_usage_default_json (argpar *argpar)
 
int argpar_help_json (argpar *argpar, FILE *stream, unsigned flags, char *name)
 
const char * argpar_version ()
 
char ** argpar_split_str (char *str, const char *delim)
 
char ** argpar_split_trim (char *str, const char *delim)
 
int * argpar_split_int (char *str, const char *delim)
 
double * argpar_split_dbl (char *str, const char *delim)
 

Variables

const char * argpar_program_name
 
FILE * argpar_ostream
 
const char * argpar_program_version
 
void(* argpar_program_version_hook )(FILE *stream, argpar_state *state)
 

Detailed Description

Library for reading command-line arguments in the form of key=value.

This library parses a pointer of null-terminated strings (usually argv) and may modify the array in the process. All pairs are stored for later access. Any argument that does not contain an equal sign is considered a "key argument" and is stored as-is in a non-associative array in the order in which they are found. An argument of "--" will cause argpar to treat all remaining arguments as key arguments.

Files containing newline separated key=value entries (called a par file) can also be parsed, triggered by a special key. Any argument matching parfile=file (configurable via the PARFILE_STR macro) will cause the parser to immediately open the file (relative to the current working directory) and parse through the entire file. Par files can also contain parfile=file entries, which will interrupt the current file parsing; these entries are relative to the current file being parsed instead of the current working directory, unless specified as absolute paths. All repeat keys will overwrite previous entries.

This library can also generate a usage statement based on the expected arguments.

This library should not be used in conjunction with argp as some macros may have been re-used in an attempt to make this as much like argp as possible.

argpar is not expected to free any strings passed in as arguments and they must remain in-memory and accessible until the argpar object is destroyed.

Definition in file argpar.h.

Macro Definition Documentation

◆ ARGPAR_ACCEPT_ANY

#define ARGPAR_ACCEPT_ANY   0x20

Passed to the argpar_parse_ functions, this tells argpar to call every parser with every option found. This disables the "Unknown option" detection.

Definition at line 136 of file argpar.h.

◆ ARGPAR_API_VERSION

#define ARGPAR_API_VERSION   2001000

Current API version. If already defined, use API defined first.

Definition at line 42 of file argpar.h.

◆ ARGPAR_API_VERSION_STR

#define ARGPAR_API_VERSION_STR   "2.1.0"

Current API version as a string. If already defined, use API defined first.

Definition at line 44 of file argpar.h.

◆ ARGPAR_CAST_ARGS

#define ARGPAR_CAST_ARGS   0x1

Passed to the argpar_parse_ functions, this tells the parser to cast all key arguments to long and double, as if OPTION_INT|OPTION_DBL were given to each.

Definition at line 116 of file argpar.h.

◆ ARGPAR_ERR_ABORT

#define ARGPAR_ERR_ABORT   -1

Returned from the parser callback to signal argpar to stop parsing and return to the caller.

Definition at line 334 of file argpar.h.

◆ ARGPAR_ERR_PARFILE

#define ARGPAR_ERR_PARFILE   -3

Returned from argpar_parse_args and argpar_parse_file when an error has occurred in reading a parfile.

Definition at line 345 of file argpar.h.

◆ ARGPAR_ERR_UNKNOWN

#define ARGPAR_ERR_UNKNOWN   -5

What to return for unrecognized keys within an argpar_parser function.

Definition at line 341 of file argpar.h.

◆ ARGPAR_ERR_USAGE

#define ARGPAR_ERR_USAGE   -2

Returned from the parser callback to signal argpar to stop parsing, print a usage summary, and return to the caller.

Definition at line 338 of file argpar.h.

◆ ARGPAR_KEY_ARG

#define ARGPAR_KEY_ARG   0

This is not an option at all, but rather a command line argument. If a parser receiving this key returns success, the fact is recorded, and the ARGP_KEY_NO_ARGS case won't be used. HOWEVER, if while processing the argument, a parser function decrements the NEXT field of the state it is passed, the option won't be considered processed; this is to allow you to actually modify the argument (perhaps into an option), and have it processed again.

Definition at line 271 of file argpar.h.

◆ ARGPAR_KEY_ARGS

#define ARGPAR_KEY_ARGS   -8

There are remaining arguments not parsed by any parser, which may be found starting at (STATE->argv + STATE->next). If success is returned, but STATE->next left untouched, it's assumed that all arguments were consume, otherwise, the parser should adjust STATE->next to reflect any arguments consumed.

Definition at line 278 of file argpar.h.

◆ ARGPAR_KEY_END

#define ARGPAR_KEY_END   -1

Passed as the key to the parser callback function when there are no more arguments left to parse.

Definition at line 282 of file argpar.h.

◆ ARGPAR_KEY_ERROR

#define ARGPAR_KEY_ERROR   -6

Passed as the key to each parser callback function when parsing has finished and an error was returned.

Definition at line 299 of file argpar.h.

◆ ARGPAR_KEY_FINI

#define ARGPAR_KEY_FINI   -4

Passed as the key to each parser callback function at the very end of the process. This is guaranteed to be called on every parser.

Definition at line 291 of file argpar.h.

◆ ARGPAR_KEY_HELP_ARGS_DOC

#define ARGPAR_KEY_HELP_ARGS_DOC   -1

Passed as the key to each help filter when printing the args_doc.

Definition at line 310 of file argpar.h.

◆ ARGPAR_KEY_HELP_EXTRA

#define ARGPAR_KEY_HELP_EXTRA   -7 /* After all other documentation; text is NULL for this key. */

Passed as the key to each help filter after all other documentation is printed, to return extra information not contained in the options list.

Definition at line 330 of file argpar.h.

◆ ARGPAR_KEY_HELP_HEADER

#define ARGPAR_KEY_HELP_HEADER   -4

Passed as the key to each help filter when printing a group header.

Definition at line 323 of file argpar.h.

◆ ARGPAR_KEY_HELP_OPTION_DOC

#define ARGPAR_KEY_HELP_OPTION_DOC   -5

Passed as the key to each help filter when printing a group's trailing documentation.

Definition at line 326 of file argpar.h.

◆ ARGPAR_KEY_HELP_POST_DOC

#define ARGPAR_KEY_HELP_POST_DOC   -3

Passed as the key to each help filter when printing the doc string after all options are listed, if a vertical tab ('\v') was found in doc. Only the text after the tab is given to the filter.

Definition at line 320 of file argpar.h.

◆ ARGPAR_KEY_HELP_PRE_DOC

#define ARGPAR_KEY_HELP_PRE_DOC   -2

Passed as the key to each help filter when printing the doc string before options are listed. The text given is the portion preceding any vertical tabs ('\v'), if any, or the entire string otherwise.

Definition at line 315 of file argpar.h.

◆ ARGPAR_KEY_INIT

#define ARGPAR_KEY_INIT   -3

Passed as the key to each parser callback function before any parsing occurs. For most cases, this is the proper time to initialize child parsers' input pointers. This is guaranteed to be called on every parser.

Definition at line 287 of file argpar.h.

◆ ARGPAR_KEY_NO_ARGS

#define ARGPAR_KEY_NO_ARGS   -7

Passed as the key to each parser callback function when parsing has finished and no key arguments were found.

Definition at line 303 of file argpar.h.

◆ ARGPAR_KEY_SUCCESS

#define ARGPAR_KEY_SUCCESS   -5

Passed as the key to each parser callback function when parsing has finished and no errors were returned.

Definition at line 295 of file argpar.h.

◆ ARGPAR_KEY_UNKNOWN

#define ARGPAR_KEY_UNKNOWN   -8

Passed as the key to each parser callback function when an unknown option has been found. This is only used if ARGPAR_ACCEPT_ANY is used.

Definition at line 307 of file argpar.h.

◆ ARGPAR_LIMIT_REACHED

#define ARGPAR_LIMIT_REACHED   -4

Returned from argpar_parse_args and argpar_parse_file when attempting to load more than the maximum amount of parfiles.

Definition at line 349 of file argpar.h.

◆ ARGPAR_NO_EXIT

#define ARGPAR_NO_EXIT   0x10

Passed to the argpar_parse_ functions, this tells argpar not to call exit after printing help/usage, version, or parameters.

Definition at line 132 of file argpar.h.

◆ ARGPAR_NO_HELP

#define ARGPAR_NO_HELP   0x8

Passed to the argpar_parse_ functions, this tells argpar not to add the help option.

Definition at line 128 of file argpar.h.

◆ ARGPAR_NO_KEYARGS

#define ARGPAR_NO_KEYARGS   0x4

Passed to the argpar_parse_ functions, this tells the parser to accept options without equal signs, defaulting them to "1". E.g., <program> HELP is equivalent to <program> HELP=1. N.B., this also applies to parfiles.

Definition at line 125 of file argpar.h.

◆ ARGPAR_SKIP_PARFILES

#define ARGPAR_SKIP_PARFILES   0x2

Passed to argpar_parse_args, this tells the parser to ignore parfile= arguments, useful for overwriting parfile options with command line ones (via a second call).

Definition at line 120 of file argpar.h.

◆ ARGPAR_STORE_PARAMS

#define ARGPAR_STORE_PARAMS   0x40

Passed to the argpar_parse_ functions, this tells argpar to create a special parser that stores all parameters as they come in, with the ability to print them at the end if given help=params.

Definition at line 141 of file argpar.h.

◆ EMPTY_INT

#define EMPTY_INT   INT_MAX

Definition at line 550 of file argpar.h.

◆ MAX_PARFILES

#define MAX_PARFILES   64

Maximum amount of parfiles to be able to load into one object.

Definition at line 49 of file argpar.h.

◆ NULL_INT

#define NULL_INT   INT_MIN

Definition at line 546 of file argpar.h.

◆ OPTION_ALIAS

#define OPTION_ALIAS   0x200

Do not add an extra newline after this documentation string. Useful for lists and manual formatting.

Definition at line 175 of file argpar.h.

◆ OPTION_ARG_OPTIONAL

#define OPTION_ARG_OPTIONAL   0x1

Don't throw an error if not given and don't display at the top of the usage summary in the command line example. (Error not currently implemented.)

Definition at line 146 of file argpar.h.

◆ OPTION_ATTR

#define OPTION_ATTR   (OPTION_DOC | OPTION_HIDDEN | 0x800)

This option serves to document additional attributes for an option. These are hidden from the normal usage text but returned when printing JSON documentation.

Definition at line 183 of file argpar.h.

◆ OPTION_CHILD

#define OPTION_CHILD   0x80

This option only applies if this parser is not the top-most parser.

Definition at line 167 of file argpar.h.

◆ OPTION_DBL

#define OPTION_DBL   0x10

Cast this option as a double. The value and any error will be reflected in the argpar_state struct during the parser callback.

Definition at line 156 of file argpar.h.

◆ OPTION_DOC

#define OPTION_DOC   0x4

This option isn't actually an option, merely text for the usage summary.

Definition at line 152 of file argpar.h.

◆ OPTION_DOC_NO_BREAK

#define OPTION_DOC_NO_BREAK   0x100

Do not add an extra newline after this documentation string. Useful for lists and manual formatting.

Definition at line 171 of file argpar.h.

◆ OPTION_ENUM

#define OPTION_ENUM   (OPTION_DOC | 0x400)

This option serves to document a valid value for an option. This is not enforced by argpar.

Definition at line 179 of file argpar.h.

◆ OPTION_HIDDEN

#define OPTION_HIDDEN   0x2

Do not display this option anywhere in the usage summary.

Definition at line 149 of file argpar.h.

◆ OPTION_INT

#define OPTION_INT   0x20

Cast this option as a long. The value and any error will be reflected in the argpar_state struct during the parser callback.

Definition at line 160 of file argpar.h.

◆ OPTION_PARENT

#define OPTION_PARENT   0x40

This option only applies if this parser is the top-most parser. Useful for return value documentation.

Definition at line 164 of file argpar.h.

◆ PARFILE_STR

#define PARFILE_STR   "parfile"

Used to override the par file trigger.

Definition at line 54 of file argpar.h.

Typedef Documentation

◆ argpar_parser

typedef int(* argpar_parser) (int key, char *argv, argpar_state *state)

Pointer to a callback function to call for each argument and option parsed.

Parameters
[in]keyargpar_option.key of recognized options or one of the ARGPAR_KEY_ macros.
[in]argvvalue part of key=value parameter, or the entire argument in case of a key argument.
[in]stateStructure containing all the information needed to process an argument.
Returns
0 to continue or any of the ARGPAR_ERR_ macros to fail.

Definition at line 360 of file argpar.h.

◆ help_filter

typedef char*(* help_filter) (int key, const char *text, void *input)

Pointer to a callback function to call for each argument parsed.

Parameters
[in]keyargpar_option.key of recognized options or one of the ARGPAR_KEY_HELP_ macros.
[in]textThe text about to be printed. May be NULL for some ARGPAR_KEY_HELP_ keys.
[in]inputCurrently unused, I think.
Returns
NULL to print nothing, the input text pointer to print it unchanged, or a malloc'd string to print which is free'd by the parser after use.

Definition at line 371 of file argpar.h.

Function Documentation

◆ argpar_clean()

int argpar_clean ( argpar p)

Free any space consumed by argpar for parfiles.

Parameters
[in]pargpar structure to clean up.
Returns
0 on success.

Definition at line 649 of file argpar.c.

◆ argpar_help()

int argpar_help ( argpar argpar,
FILE *  stream,
unsigned  flags,
char *  name 
)

Print the default usage summary with all available sections.

Parameters
[in]argparargpar object from which to generate the usage summary.
[in]streamStream to which the help gets printed.
[in]flagsFlags controlling which sections to print. Currently unused.
[in]nameProgram name to use.
Returns
0 on success, non-0 on error.

Definition at line 512 of file argpar-help.c.

◆ argpar_help_json()

int argpar_help_json ( argpar argpar,
FILE *  stream,
unsigned  flags,
char *  name 
)

Print the default usage summary with all available sections, in a format more suitable for automated parsing.

Parameters
[in]argparargpar object from which to generate the usage summary.
[in]streamStream to which the help gets printed.
[in]flagsFlags controlling which sections to print. Currently unused.
[in]nameProgram name to use.
Returns
0 on success, non-0 on error.

Definition at line 420 of file argpar-json.c.

◆ argpar_parse_args()

int argpar_parse_args ( argpar p,
unsigned  argc,
char *  argv[],
unsigned  flags,
unsigned *  end_index,
void *  input 
)

Parse an array of key=value pairs and/or key arguments.

Parameters
[in]pargpar object to use to parse file
[in]argcNumber of arguments to parse.
[in]argvArray of key=value pairs and/or key arguments, starting at index 1. The first element is assumed to be the calling program's name.
[in]flagsFlags to modify the behavior of the parser.
[out]end_indexSet to the last index parsed.
[in]inputPointer to pass to the configured parser callback.
Returns
0 when the parsing is completed or the return value of the callback function if it bailed out early.
See also
ARGPAR_CAST_ARGS

Definition at line 679 of file argpar.c.

◆ argpar_parse_file()

int argpar_parse_file ( argpar p,
const char *  path,
unsigned  flags,
void *  input 
)

Parse a key=value store file.

Parameters
[in]pargpar object to use to parse file
[in]pathPath of file, absolute or relative to the current directory.
[in]flagsFlags to modify the behavior of the parser.
[in]inputPointer to pass to the configured parser callback.
Returns
0 when the parsing is completed or the return value of the callback function if it bailed out early.
See also
ARGPAR_CAST_ARGS

Definition at line 730 of file argpar.c.

◆ argpar_split_dbl()

double* argpar_split_dbl ( char *  str,
const char *  delim 
)

Splits a string on a delimiter, returning a NAN-terminated list of doubles.

Parameters
[in]strString on which to split. This string is modified, replacing delimiters with '\0'. Return pointers are points to within this string.
[in]delimDelimiters on which to split (each character is a separate delimiter).
Returns
NULL on failure, malloc'd array of doubles ending in NULL on success. Compare to INFINITY for empty strings. Conversion errors result in total failure (returning NULL). (N.B., the proper way to perform these comparisons are the macros isinf and isnan.)

Definition at line 809 of file argpar.c.

◆ argpar_split_int()

int* argpar_split_int ( char *  str,
const char *  delim 
)

Splits a string on a delimiter, returning a NULL_INT-terminated list of ints.

Parameters
[in]strString on which to split. This string is modified, replacing delimiters with '\0'. Return pointers are points to within this string.
[in]delimDelimiters on which to split (each character is a separate delimiter).
Returns
NULL on failure, malloc'd array of ints ending in NULL_INT on success. Compare to EMPTY_INT for empty strings. Conversion errors result in total failure (returning NULL).

Definition at line 785 of file argpar.c.

◆ argpar_split_str()

char** argpar_split_str ( char *  str,
const char *  delim 
)

Splits a string on a delimiter, returning a NULL-terminated list of strings.

Parameters
[in]strString on which to split. This string is modified, replacing delimiters with '\0'. Return pointers are points to within this string.
[in]delimDelimiters on which to split (each character is a separate delimiter).
Returns
NULL on failure, malloc'd array of strings ending in NULL on success.

Definition at line 744 of file argpar.c.

◆ argpar_split_trim()

char** argpar_split_trim ( char *  str,
const char *  delim 
)

Splits a string on a delimiter, returning a NULL-terminated list of strings, trimming left and right whitespace from each string.

Parameters
[in]strString on which to split. This string is modified, replacing delimiters with '\0'. Return pointers are points to within this string.
[in]delimDelimiters on which to split (each character is a separate delimiter).
Returns
NULL on failure, malloc'd array of strings ending in NULL on success.

Definition at line 769 of file argpar.c.

◆ argpar_usage()

int argpar_usage ( argpar_state state)

Print usage summary, called within a argpar_parser.

Parameters
[in]stateargpar_state from which to generate usage summary.
Returns
0 on success, non-0 on error.

Definition at line 506 of file argpar-help.c.

◆ argpar_usage_default()

int argpar_usage_default ( argpar argpar)

Print the default usage summary with all available sections.

Parameters
[in]argparargpar object from which to generate the usage summary.
Returns
0 on success, non-0 on error.

Definition at line 509 of file argpar-help.c.

◆ argpar_usage_default_json()

int argpar_usage_default_json ( argpar argpar)

Print the default usage summary with all available sections, in a format more suitable for automated parsing.

Parameters
[in]argparargpar object from which to generate the usage summary.
Returns
0 on success, non-0 on error.

Definition at line 417 of file argpar-json.c.

◆ argpar_usage_json()

int argpar_usage_json ( argpar_state state)

Print usage summary, called within a argpar_parser, in a format more suitable for automated parsing.

Parameters
[in]stateargpar_state from which to generate usage summary.
Returns
0 on success, non-0 on error.

Definition at line 414 of file argpar-json.c.

◆ argpar_version()

const char* argpar_version ( )

Returns the source code version and the implemented API version.

No assumptions are made about the format of the return value.

Definition at line 740 of file argpar.c.

Variable Documentation

◆ argpar_ostream

FILE * argpar_ostream

Used as the stream for printing help and usage messages. Defaults to STDERR.

Where to print errors and usage summaries to, defaults to STDERR.

Definition at line 190 of file argpar.h.

◆ argpar_program_name

const char* argpar_program_name

Used as a default for the program's invocation name if one is not found.

How to display the program name. If not given, it will be derived during a call to argpar_parse_args.

Definition at line 187 of file argpar.h.

◆ argpar_program_version

const char* argpar_program_version

Used as the program version string. If set, a version=1 option is automatically added. argpar_program_version_hook takes precedence.

Definition at line 98 of file leveltwo2csv-main.c.

◆ argpar_program_version_hook

void(* argpar_program_version_hook) (FILE *stream, argpar_state *state)

Called to print the version string. If set, a version=1 option is automatically added.

Definition at line 20 of file argpar.c.