Command Line Argument Parsing¶

The command line argument package simplifies a number of aspects of defining and also parsing command line arguments for MACSio’s main code or any of its plugins. The package supports command line arguments and their options with the followin features…

boolean arguments (the argument’s presence or absence maps to 0 or 1)
integer, double and string valued arguments
multiple arguments for a given command-line option
default values for arguments
option groupings
help strings and printing of usage with --help option
pretty (somewhat) formatting of long help strings to terminal width
separating arguments into sub-command groups.
routing the parsed results to caller supplied local variables or constructing a returned JSON object.
error detection and logging
collective execution in parallel * argc, argv inputs ensured consistent across all tasks * results collectively unified across all tasks in parallel

The package is designed to do parsing of simple command-line arguments and assign values associated with them either to caller-supplied scalar variables or to populate a json_object. The work-horse function, MACSIO_CLARGS_ProcessCmdline(), is used in the following manner…

After the argi, argc, argv trio of arguments, the remaining arguments come in groups of either 3 (when mapping to a json_object) or 4 (when mapping to scalar program variables).

The first of these is an argument format specifier much like a printf statement. It indicates the type of each parameter to the argument as well as the number of parameters. Presently, it understands only %d, %f and %s types.

The second is a string argument indicating the default value, as a string.

The third is a help string for the argument. Note, you can make this string as long as the C-compiler will permit. You should not embed any newline characters as the routine to print the help string will do that for you. However, you may embed newline characters if you wish to control specific line breaking when output.

The fourth argument is present only when mapping to scalar program variables and is a pointer to the variable location(s) where values will be stored.

Command line arguments for which only existence on the command-line is tested assume a caller-supplied return value of int and will be assigned 1 if the argument exists on the command line and 0 otherwise.

Do not name any argument with a substring help as that is reserved for obtaining help. Also, do not name any argument with the string end_of_args as that is used to indicate the end of the list of arguments passed to the function.

If any argument on the command line has the substring help, help will be printed by task 0 and then this function calls MPI_Finalize() (in parallel) and exit(1).

This function must be called collectively in MPI_COMM_WORLD. All tasks are guaranteed to complete with identical results.

CLARGS API¶

group MACSIO_CLARGS

Command-line argument parsing utilities.

Defines

MACSIO_CLARGS_WARN¶

MACSIO_CLARGS_ERROR¶

MACSIO_CLARGS_TOMEM¶

MACSIO_CLARGS_TOJSON¶

MACSIO_CLARGS_ASSIGN_OFF¶

MACSIO_CLARGS_ASSIGN_ON¶

MACSIO_CLARGS_HELP¶

MACSIO_CLARGS_OK¶

MACSIO_CLARGS_GRP_SEP_STR¶

MACSIO_CLARGS_GRP_BEG¶

MACSIO_CLARGS_GRP_END¶

MACSIO_CLARGS_ARG_GROUP_BEG(GRPNAME, GRPHELP)¶: Begin option group (for TOJSON routing invokation)

MACSIO_CLARGS_ARG_GROUP_END(GRPNAME)¶: End option group (for TOJSON routing invokation)

MACSIO_CLARGS_ARG_GROUP_BEG2(GRPNAME, GRPHELP)¶: Begin option group (for TOMEM routing invokation)

MACSIO_CLARGS_ARG_GROUP_END2(GRPNAME)¶: End option group (for TOMEM routing invokation)

MACSIO_CLARGS_END_OF_ARGS¶: Moniker to terminate argument list.

MACSIO_CLARGS_NODEFAULT¶: Value to indicate no default specified.

Typedefs

typedef struct _MACSIO_CLARGS_ArgvFlags_t MACSIO_CLARGS_ArgvFlags_t¶

Functions

int MACSIO_CLARGS_ProcessCmdline(void **retobj, MACSIO_CLARGS_ArgvFlags_t flags, int argi, int argc, char **argv, ...)¶

Command-line argument parsing, default values and help output.

Parameters

retobj: Optional void pointer to a returned object encoding the command line options. Currently only JSON_C object is supported. Must specify TOJSON routing.
argi: First arg index at which to to start processing argv
argc: argc from main
argv: argv from main

Avoid definining any argument with the substring --help or --no-strict. These are command-line option keywords reserved by MACSio. --help is a request to print usage and exit. no-strict disables strict command-line option error response which ordinarily causes an abort and instead issues warnings.

In parallel, this function must be called collectively by all ranks in MPI_COMM_WORLD. argc and argv on task rank 0 are broadcast to all tasks. If request for help (e.g. --help is in argv) or error(s) are encountered, all tasks are broadcast this outcome. Only task rank 0 will print usage or error messages.

Return: An integer value of either MACSIO_CLARGS_OK, MACSIO_CLARGS_HELP or MACSIO_CLARGS_ERROR.

struct _MACSIO_CLARGS_ArgvFlags_t¶

#include <macsio_clargs.h>

Public Members

unsigned int error_mode¶: 0=warn, 1=abort

unsigned int route_mode¶: 0=(TOMEM) scalar variables, 1=(TOJSON) json_object, 2,3 unused

unsigned int defaults_mode¶: 0=assign defaults, 1=do not assign defaults

Example¶

int doMultifile, numCycles, Ni, Nj;
double Xi, Xj;
MACSIO_CLARGS_ArgvFlags_t flags;
json_object *obj = 0;
int argi = 1; /* start at argv[1] not argv[0] */

flags.error_mode = MACSIO_CLARGS_ERROR;
flags.route_mode = MACSIO_CLARGS_TOMEM;

MACSIO_CLARGS_ProccessCmdline(obj, flags, argi, argc, argv,
    "--multifile", "", /* example boolean with no default */
        "if specified, use a file-per-timestep",
        &doMultifile,
    "--numCycles %d", "10", /* example integer with default of 10 */
        "specify the number of cycles to run",
        &numCycles,
    "--dims %d %f %d %f", "25 5 35 7", /* example multiple values */
        "specify size (logical and geometric) of mesh",
        &Ni, &Xi, &Nj, &Xj,
MACSIO_CLARGS_END_OF_ARGS);

./macsio --help
Usage and Help for "./macsio" Defaults, if any, in square brackets after argument definition
  --multifile [] if specified, use a file-per-timestep
  --numCycles %d [10] specify the number of cycles to run
  --dims %d %f %d %f [25 5 35 7] specify size (logical and geometric) of mesh