llib

• Index

Contents

• Functions

Modules

• obj
• str
• scan
• template
• list
• map
• file
• value
• interface
• json
• xml
• farr
• array
• table
• config
• arg
• flot

Topics

• readme

Examples

• test-array.c
• test-config.c
• test-file.c
• test-interface.c
• test-json.c
• test-list.c
• test-map.c
• test-obj.c
• test-pool.c
• test-scan.c
• test-seq.c
• test-sqlite3-table.c
• test-str.c
• test-table.c
• test-template.c
• test-xml.c
• testa.c
• testing.c
• cmd.c
• testa.c
• config.c
• words.c

Module arg

Command-line Argument Parser.

This allows you to bind variables to command-line arguments. For this we write specifications (which are strings containing pseudo-C declarations followed by a comment, which may specify a shortcut),followed by the address of the variable that receives the value. The first line may be a comment documenting the program.

The argument parser follows GNU conventions; long flags with double-hyphen, which may have short single-letter forms with a single-hyphen. Short flags may be combined (“-abc”) and may be followed immediately by their value (“-n10”).

#include <stdio.h>
#include <llib/arg.h>

int lines;
FILE *file;
bool verbose, print_lines;

PValue args[] = {
    "// cmd: show n lines from top of a file",
    "int lines=10; // -n number of lines to print",&lines,
    "bool verbose=false; // -v controls verbosity",&verbose,
    "bool lineno; // -l output line numbers",&print_lines,
    "infile #1=stdin; // file to dump",&file,
    NULL
};

int main(int argc,  const char **argv)
{
    arg_command_line(args,argv);
    char buff[512];
    int i = 1;
    while (fgets(buff,sizeof(buff),file)) {
        if (print_lines)
            printf("%03d\t%s",i,buff);
        else
            printf("%s",buff);
        if (i++ == lines)
            break;
    }
    fclose(file);
    return 0;
}

If you now call arg_command_line(args,argv) these variables will be bound; note how both type and optional default value are specified. Names like ‘#1’ refer to the first non-flag argument and so forth. Both ‘—lines’ and ‘-n’ can be used to set the integer variable lines. If a flag has no default, then it is an error. Plain boolean flags have an implicit default of false.

The supported types are int, float, bool, string, infile and outfile. float binds a double value, and infile|outfile bind to FILE* directly. An array ‘type’ (like “string I[]…”) binds to an array of these values and defines a flag that may be specified more than once, for instance “-I/my/path -I/your/path”.

Help usage is automatically generated from these specifications.

$ cmd --help
cmd: show n lines from top of a file
Flags:
        --help,-h       help on commands and flags
        --lines,-n (10) number of lines to print
        --verbose,-v (false)    controls verbosity
        --lineno,-l (false)     output line numbers
        --#1 (stdin)    file to dump

If a conversion is not possible (not a integer, file cannot be opened, etc) then the program will exit, showing the help.

cmd.c is a basic example; testa.c shows how to define flags and commands as functions, as well as defining a simple REPL.

arg_bind_values may be used directly to process an array of name/value pairs, for instance in config.c

Functions

arg_get_values (vals, ...)	extract raw values from args array.
arg_parse_spec (flagspec)	parse flag specification array.
arg_bind_values (cmds, sm)	Bind a set of variables to their values, using a simple map of name/value pairs.
arg_reset_used (cmds)	reset used state of flags, needed to reparse commands.
arg_process (cmds, argv)	parse the given command-line args, given the processed state.
arg_quit (cmds, msg, show_help)	quit the application with a message, optionally showing help.
arg_command_line (argspec, argv)	parse command-line arguments, binding flags to their values.

Functions

arg_get_values (vals, ...)

extract raw values from args array. Convenient way to unpack the array of values passed to commands and function flags.

Parameters:

• vals PValue *
• ...

Usage:

PValue two(PValue *args) {  double x;  char *name;  arg_get_values(args,&x,&name); ...

arg_parse_spec (flagspec)

parse flag specification array.

Parameters:

• flagspec PValue *

Returns:

ArgState *

arg_bind_values (cmds, sm)

Bind a set of variables to their values, using a simple map of name/value pairs.

Parameters:

• cmds ArgState *
• sm SMap

Returns:

PValue

arg_reset_used (cmds)

reset used state of flags, needed to reparse commands.

Parameters:

• cmds ArgState *

arg_process (cmds, argv)

parse the given command-line args, given the processed state. Call arg_parse_spec first to call this directly.

Parameters:

• cmds ArgState *
• argv const char * *

Returns:

PValue

arg_quit (cmds, msg, show_help)

quit the application with a message, optionally showing help.

Parameters:

• cmds ArgState *
• msg str_t
• show_help bool

arg_command_line (argspec, argv)

parse command-line arguments, binding flags to their values. It assumes that argv terminates in NULL, which is according to the C specification. Any error will cause the application to quit, showing help.

Parameters:

• argspec void * *
• argv const char * *

Returns:

ArgState *