Argument parsing¶

union mm_arg_val¶

struct mm_arg_val¶: generic holder of argument value

Definition¶

union mm_arg_val {
    const char* str;
    int i;
    long long ll;
    unsigned int ui;
    unsigned long long ull;
}

Members¶

str: pointer to string value
i: signed integer value
ll: signed long long value
ui: unsigned integer value
ull: unsigned long long value

Description¶

union mm_arg_val is the data holder to pass the value of an argument when a argument callback function is called. The field to use to manipulate the value depends on the type indicated mm_arg_opt.flags of the option supplied in the callback. This type can be retrieved by the helper mm_arg_opt_get_type().

struct mm_arg_opt¶

struct mm_arg_opt¶: option parser configuration

Definition¶

struct mm_arg_opt {
    const char* name;
    int flags;
    const char* defval;
    union {
        const char** sptr;
        int* iptr;
        long long* llptr;
        unsigned int* uiptr;
        unsigned long long* ullptr;
    } val;
    const char* desc;
}

Members¶

name: option names, see description
flags: conversion type and requirement flags, see options flags
defval: default value is option is supplied without value
val: union for the various types
val.sptr: pointer to pointer to string, used if type is MM_OPT_STR
val.iptr: pointer to integer, used if type is MM_OPT_INT
val.llptr: pointer to long long, used if type is MM_OPT_LLONG
val.uiptr: pointer to unsigned integer, used if type is MM_OPT_UINT
val.ullptr: pointer to unsigned long long, used if type is MM_OPT_ULLONG
desc: description of the option printed when usage is displayed

Description¶

This structure defines what an option supports and how its value must be interpreted. name defines both the short option key and long name. The short key (“c”) must be a single character of lower or upper case letter in ascii character set. The long option name (“long-name”) must contains only ascii lower case letter, digit or hyphens. name must adhere to one the 3 following formats

“c|long-name”: option can be referred by “-c” or “–long-name”
“c”: option can be referred only by short option “-c”
“long-name”: option can be referred only by long option “–long-name”

The parameter flags determine whether a value for an option:

MM_OPT_NOVAL: value is forbidden
MM_OPT_OPTVAL: value is optional and defval will be used if not set.
MM_OPT_NEEDVAL: value is mandatory

it also determines what is the supported type of a value (if not forbidden):

MM_OPT_STR: value is string (then val.sptr used)
MM_OPT_INT: value is int (then val.iptr used)
MM_OPT_UINT: value is unsigned int (then val.uiptr used)
MM_OPT_LLONG: value is long long (then val.llptr used)
MM_OPT_ULLONG: value is unsigned long long (then val.ullptr used)

the ptr fields specified in parenthesis indicates that if the corresponding field is not NULL, it will receive the value specified

desc provides the documentation of the option. It will be displayed if usage is requested. Please note that if an option accepts a value (optional or mandatory), the value name displayed in option synopsis will be VALUE, unless, desc contains one of more occurrence of string following “@NAMEOFVALUE” pattern where NAMEOFVALUE is a string made of only upper case letter and hyphens or underscore and of length less than 16 characters. If such pattern can be found NAMEOFVALUE will be used for synopsis and all occurrence of “@NAMEOFVALUE” will be replaced by “NAMEOFVALUE” in description.

mm_arg_callback¶

#include <mmargparse.h>

int mm_arg_callback(const struct mm_arg_opt* opt, union mm_arg_val value, void* data, int state)¶

prototype of argument parser callback

Parameters:	opt (const struct mm_arg_opt) – pointer to matching option value* (union mm_arg_val) – value set for option. The field of the union to use is determined with mm_arg_opt_get_type(@opt). data (void) – user pointer provided for hold state while running parser state* (int) – flags indicating the state of option parsing.

Description¶

The flags in state indicates special calling context. It can be a combination of the following flags :

MM_ARG_OPT_COMPLETION: the option value is being completed. The value passed is then always a string, no matter is opt->value. Also its content may be incomplete. If the callback want to provide completion candidates, it has to write them on standard output, each candidate on its own line. If it returns MM_ARGPARSE_COMPLETE, no further completion proposal will be added. This flag cannot appear if the flag MM_ARG_PARSER_COMPLETION has not been set in argument parser.

Return¶

0 in case of success, MM_ARGPARSE_ERROR (-1) if an error has been detected, MM_ARGPARSE_STOP (-2) if early exit is requested like with help display or MM_ARGPARSE_COMPLETE (-3) if value has been completed.

mm_arg_complete_path_cb¶

#include <mmargparse.h>

int mm_arg_complete_path_cb(const char* name, const char* dir, int type, void* data)¶

prototype of path completion callback

Parameters:	name (const char) – basename of path candidate dir* (const char) – directory of path candidate. type* (int) – file type of path candidate (one of the MM_DT_* definition) data (void*) – user pointer provided when calling path completion

Return¶

1 if path candidate must be kept, 0 if it must be discarded.

struct mm_arg_parser¶

struct mm_arg_parser¶: argument parser configuration

Definition¶

struct mm_arg_parser {
    int flags;
    int num_opt;
    const struct mm_arg_opt* optv;
    const char* doc;
    const char* args_doc;
    const char* execname;
    void* cb_data;
    mm_arg_callback cb;
}

Members¶

flags: flags to change behavior of parsing (MM_ARG_PARSER_*)
num_opt: number of element in optv.
optv: array of option supported. Please note that optv does not need to provide an option “h|help” since argument parser add such option automatically which will trigger usage printing. You may however provide such option in optv array to override the behaviour when this option is encountered.
doc: document of the program. Can be NULL
args_doc: lines of synopsis of program usage (excluding program name). This can support multiple line (like for different case of invocation). Can be NULL.
execname: name of executable. You are invited to set it to argv[0]. If NULL, “PROGRAM” will be used instead for synopsis
cb_data: user provided data callback
cb: callback called whenever an option is recognised and parsed. This callback is optional and can be set to NULL if unneeded.

mm_arg_opt_get_key¶

#include <mmargparse.h>

int mm_arg_opt_get_key(const struct mm_arg_opt* opt)¶

get short key of an option

Parameters:	opt (const struct mm_arg_opt*) – option whose key must be returned

Return¶

short key code used to recognised opt if used, 0 if opt cannot be matched by short key.

mm_arg_opt_get_name¶

#include <mmargparse.h>

const char* mm_arg_opt_get_name(const struct mm_arg_opt* opt)¶

get long option name

Parameters:	opt (const struct mm_arg_opt*) – option whose long name must be returned

Return¶

the long name of opt if supported, NULL otherwise.

mm_arg_opt_get_type¶

#include <mmargparse.h>

int mm_arg_opt_get_type(const struct mm_arg_opt* opt)¶

get type of value supported by an option

Parameters:	opt (const struct mm_arg_opt*) – option whose value type must be returned

Return¶

MM_OPT_STR, MM_OPT_INT, MM_OPT_UINT, MM_OPT_LLONG or MM_OPT_ULLONG

mm_arg_parse¶

#include <mmargparse.h>

int mm_arg_parse(const struct mm_arg_parser* parser, int argc, char* argv)¶

parse command-line options

Parameters:	parser (const struct mm_arg_parser) – argument parser configuration argc* (int) – argument count as passed to `main()` argv (char*) – argument array as passed to `main()`

Description¶

This functions parses the arguments in argv, of length argc, as provided by the argument of main() using the configuration set in parser. The supported options are specified in the parser->optv array. Even if it is not set in parser->optv, a parser always supports the “-h” or “–help” option. If encountered, the program usage will be printed on standard output and the process will exit with EXIT_SUCCESS code (This behaviour can be overridden if “h|help” is explicitly defined as option in parser->optv). If the parsing operation fails (because of invalid option or value), the error diagnostic will be printed on standard error and the process will exit with EXIT_FAILURE code. In other case, the parsing will continued until “–” or a non optional argument is encountered.

The value of parser->flags is a OR-combination of any number of the following flags :

MM_ARG_PARSER_NOEXIT: the process will not exit in case of help printing nor in case of error but mm_arg_parse() will return respectively MM_ARGPARSE_STOP and MM_ARGPARSE_ERROR.
MM_ARG_PARSER_COMPLETION: the parser is invoked for being used in shell completion script. In case of unknown option, the completed candidate options are printed on standard output (in a format suitable for bash completion script).

There are 2 non-exclusive ways to get the values of the option supplied on command line

setting the struct mm_arg_opt->*ptr field to the data that must be set when an option is found and parsed.
using the callback function parser->cb and data parser->cb_data.

Return¶

a non negative value indicating the index of the first non-option argument when argument parsing has been successfully finished. Additionally if MM_ARG_PARSER_NOEXIT is set in parser->flags :

MM_ARGPARSE_ERROR (-1): an error of argument parsing or validation occurred
MM_ARGPARSE_STOP (-2): help display has been requested or early parsing stop has been requested by callback.
MM_ARGPARSE_COMPLETE (-3): parser was in completion mode and the last argument has been completed (completion candidates have been printed on output).

mm_arg_optv_parse¶

#include <mmargparse.h>

int mm_arg_optv_parse(int optn, const struct mm_arg_opt* optv, int argc, char* argv)¶

parse command-line options

Parameters:	optn (int) – number of mm_arg_opt elements in optv optv (const struct mm_arg_opt) – pointer to mm_arg_opt array argc* (int) – argument count as passed to `main()` argv (char*) – argument array as passed to `main()`

Description¶

This function wraps around mm_arg_parse and it takes care to create and initialize a minimal mm_arg_parser structure. It can be useful when no extended usage documentation is needed, as it just provides the standard help function.

Return¶

a non negative value indicating the index of the first non-option argument when argument parsing has been successfully finished.

mm_arg_parse_complete¶

#include <mmargparse.h>

int mm_arg_parse_complete(const struct mm_arg_parser* parser, const char* arg)¶

print list of opts of arg parser for completion

Parameters:	parser (const struct mm_arg_parser) – argument parser configuration arg* (const char*) – beginning of argument (can be NULL)

Description¶

This function print on standard output the list of option accepted by parser and whose beginning match arg (if supplied). This list is the same format as bash compgen command.

Return¶

0 in case of success, MM_ARGPARSE_ERROR otherwise (validation error occurred)

mm_arg_complete_path¶

#include <mmargparse.h>

int mm_arg_complete_path(const char* arg, int type_mask, mm_arg_complete_path_cb cb, void* cb_data)¶

complete argument as path

Parameters:	arg (const char) – beginning of argument (must not be NULL) type_mask* (int) – Combination of MM_DT_* flags indicating the desired file cb (mm_arg_complete_path_cb) – user supplied completion callback (can be NULL) cb_data (void*) – pointer passed to `cb` if it is not NULL

Description¶

This function print on standard output the list of path whose beginning match arg and whose type match the mask specified by type_mask. This list has the same format as bash compgen command.

More path candidates can be filtered out by supplying a callback through the cb argument. If not NULL, this function will be called for each completion candidate which will be discarded if the callback does not return 1.

Return¶

0 in case of success, -1 otherwise

mm_arg_is_completing¶

#include <mmargparse.h>

int mm_arg_is_completing(void)¶

indicates whether shell completion is running

Parameters:	void – no arguments

Description¶

The function indicates if command completion has been requested through MMLIB_CMD_COMPLETION environment variable: by convention command completion is requested if this variable is set (no matter the value).

Please note that you are not forced to use this environment variable to trigger command completion. You may use any environment variable or any other mechanism of your choosing. If mm_arg_parse() is used to parse options, completion will run only if the flag MM_ARG_PARSER_COMPLETION is set in the flags field of struct mm_arg_parser. However on the other hand, there is little reason not to use MMLIB_CMD_COMPLETION environment variable. Hence if a code is mm_arg_parse() and using command completion through its executable, it is invited to set MM_ARG_PARSER_COMPLETION if mm_arg_is_completing() returns 1.

Return¶

1 if completion is running, 0 otherwise.

Argument parsing¶

union mm_arg_val¶

Definition¶

Members¶

Description¶

struct mm_arg_opt¶

Definition¶

Members¶

Description¶

mm_arg_callback¶

Description¶

Return¶

mm_arg_complete_path_cb¶

Return¶

struct mm_arg_parser¶

Definition¶

Members¶

mm_arg_opt_get_key¶

Return¶

mm_arg_opt_get_name¶

Return¶

mm_arg_opt_get_type¶

Return¶

mm_arg_parse¶

Description¶

Return¶

See also¶

mm_arg_optv_parse¶

Description¶

Return¶

mm_arg_parse_complete¶

Description¶

Return¶

mm_arg_complete_path¶

Description¶

Return¶

mm_arg_is_completing¶

Description¶

Return¶

See also¶