diff --git a/lib/roken/getarg.3 b/lib/roken/getarg.3 new file mode 100644 index 000000000..53a69265d --- /dev/null +++ b/lib/roken/getarg.3 @@ -0,0 +1,246 @@ +.\" Copyright (c) 1999 Kungliga Tekniska Högskolan +.\" $Id$ +.Dd September 24, 1999 +.Dt GETARG 3 +.Os ROKEN +.Sh NAME +.Nm getarg , +.Nm arg_printusage +.Nd collect command line options +.Sh SYNOPSIS +.Fd #include + +.Ft int +.Fn getarg "struct getargs *args" "size_t num_args" "int argc" "char **argv" "int *optind" + +.Ft void +.Fn arg_printusage "struct getargs *args" "size_t num_args" "const char *progname" "const char *extra_string" + +.Sh DESCRIPTION +.Fn getarg +collects any command line options given to a program in an easily used way. +.Fn arg_printusage +pretty-prints the available options, with a short help text. +.Pp +.Fa args +is the option specification to use, and it's an array of +.Fa struct getargs +elements. +.Fa num_args +is the size of +.Fa args +(in elements). +.Fa argc +and +.Fa argv +are the argument count and argument vector to extract option from. +.Fa optind +is a pointer to an integer where the index to the last processed +argument is stored, it must be initialised to the first index (minus +one) to process (normally 0) before the first call. +.Pp +.Fa arg_printusage +take the same +.Fa args +and +.Fa num_args +as getarg; +.Fa progname is the name of the program (to be used in the help text), and +.Fa extra_string +is a string to print after the actual options to indicate more +arguments. The usefulness of this function is realised only be people +who has used programs that has help strings that doesn't match what +the code does. +.Pp +The +.Fa getargs +struct has the following elements. + +.Bd -literal +struct getargs{ + const char *long_name; + char short_name; + enum { arg_integer, + arg_string, + arg_flag, + arg_negative_flag, + arg_strings, + arg_double + } type; + void *value; + const char *help; + const char *arg_help; +}; +.Ed +.Pp +.Fa long_name +is the long name of the option, it can be +.Dv NULL , +if you don't want a long name. +.Fa short_name +is the characted to use as short option, it can be zero. If the option +has a value the +.Fa value +field gets filled in with that value interpreted as specified by the +.Fa type +field. +.Fa help +is a longer help string for the option as a whole, if it's +.Dv NULL +the help text for the option is omitted (but it's still displayed in +the synopsis). +.Fa arg_help +is a description of the argument, if +.Dv NULL +a default value will be used, depending on the type of the option: +.Pp +.Bl -hang -width arg_negative_flag +.It arg_integer +the argument is a signed integer, and +.Fa value +should point to an +.Fa int . +.It Fa arg_string +the argument is a string, and +.Fa value +should point to a +.Fa char* . +.It Fa arg_flag +the argument is a flag, and +.Fa value +should point to a +.Fa int . +It gets filled in with either zero or one, depending on how the option +is given, the normal case beeing one. Note that if the option isn't +given, the value isn't altered, so it should be initialised to some +useful default. +.It Fa arg_negative_flag +this is the same as +.Fa arg_flag +but it reverses the meaning of the flag (a given short option clears +the flag), and the synopsis of a long option is negated. +.It Fa arg_strings +the argument can be given multiple times, and the values are collected +in an array; +.Fa value +should be a pointer to a +.Fa struct getarg_strings +structure, which holds a length and a string pointer. +.It Fa arg_double +argument is a double precision floating point value, and +.Fa value +should point to a +.Fa double . +.El +.Pp +Option parsing is similar to what +.Xr getopt +uses. Short options without arguments can be compressed +.Pf ( Fl xyz +is the same as +.Fl x y z ) , +and short +options with arguments take these as either the rest of the +argv-string or as the next option +.Pf ( Fl o Ns Ar foo , +or +.Fl o Ar foo ) . +.Pp +Long option names are prefixed with -- (double dash), and the value +with a = (equal), +.Fl -foo= Ns Ar bar . +Long option flags can either be specified as they are +.Pf ( Fl -help ) , +or with an (boolean parsable) option +.Pf ( Fl -help= Ns Ar yes , +.Fl -help= Ns Ar true , +or similar), or they can also be negated +.Pf ( Fl -no-help +is the same as +.Fl -help= Ns no ) , +and if you're really confused you can do it multiple times +.Pf ( Fl -no-no-help= Ns Ar false , +or even +.Fl -no-no-help= Ns Ar maybe ) . + +.Pp +.Sh EXAMPLE +.Bd -literal +#include +#include +#include + +char *source = "Ouagadougou"; +char *destination; +int weight; +int include_catalog = 1; +int help_flag; + +struct getargs args[] = { + { "source", 's', arg_string, &source, + "source of shippment", "city" }, + { "destination", 'd', arg_string, &destination, + "destination of shippment", "city" }, + { "weight", 'w', arg_integer, &weight, + "weight of shippment", "tons" }, + { "catalog", 'c', arg_negative_flag, &include_catalog, + "include product catalog" }, + { "help", 'h', arg_flag, &help_flag } +}; + +int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */ + +const char *progname = "ship++"; + +int +main(int argc, char **argv) +{ + int optind = 0; + if (getarg(args, num_args, argc, argv, &optind)) { + arg_printusage(args, num_args, progname, "stuff..."); + exit (1); + } + if (help_flag) { + arg_printusage(args, num_args, progname, "stuff..."); + exit (0); + } + if (destination == NULL) { + fprintf(stderr, "%s: must specify destination\n", progname); + exit(1); + } + if (strcmp(source, destination) == 0) { + fprintf(stderr, "%s: destination must be different from source\n"); + exit(1); + } + /* include more stuff here ... */ + exit(2); +} +.Ed +.Pp +The output help output from this program looks like this: +.Bd -literal +$ ship++ --help +Usage: ship++ [--source=city] [-s city] [--destination=city] [-d city] + [--weight=tons] [-w tons] [--no-catalog] [-c] [--help] [-h] stuff... +-s city, --source=city source of shippment +-d city, --destination=city destination of shippment +-w tons, --weight=tons weight of shippment +-c, --no-catalog include product catalog +.Ed + +.Sh BUGS +It should be more flexible, so it would be possible to use other more +complicated option syntaxes, such as what +.Xr ps 1 , +and +.Xr tar 1 , +uses, or the AFS model where you can skip the flag names as long as +the options come in the correct order. +.Pp +Options with multiple arguments should be handled better. +.Pp +Should be integreated with SL. +.Pp +It's very confusing that the struct you pass in is called getargS. +.Sh SEE ALSO +.Xr getopt 3