decodeargs.c File Reference

Interpretation of program arguments. More...

Data Structures
struct	SprOptDesc

Macros
#define	spr_od_end
	Indicate the end of an argument description list. More...
#define	spr_od_info(title, info)
#define	spr_od_include(other_opt_spec, offs)
#define	spr_od_alias(alias, original)
#define	spr_od_funcarg0(name, flags, brief, detailed, func)
#define	spr_od_funcarg1(name, flags, brief, detailed, func, def_val)
#define	spr_od_posarg(flags, brief, detailed, type, offs, def_val)

Enumerations
enum	SprOptFlags { SPR_OD_REQUIRED, SPR_OD_OPTIONAL, SPR_OD_ALLOW_REDEF, SPR_OD_ABS_DST }

Functions
int	spraak_ini_prog (void *restrict dst, const SprOptDesc *restrict od, const char *const *argv, SprMsgId *restrict prog)
void	spraak_fini_prog (void *restrict dst, const SprOptDesc *restrict od, SprMsgId *restrict prog)

Variables
const SprOptDesc	spr_od_common []

Detailed Description

Interpretation of program arguments.

The functions in this module handle –using an SprOptDesc list– the program arguments. In order to assure (1) inter program consistency, (2) correct automatic extraction of documentation and (2) correct access to the SPRAAK specific debugging and on-line help capabilities, all programs in SPRAAK must decode their arguments using this functionality.

The advantages of using the facilities provided by 'decodeargs.c' are:

• The arguments have to be described only once: both the actual argument decoding and the corresponding documentation (off- and on-line) use the same SprOptDesc description list.
• The system eliminates the need of custom code in each program to handle argument decoding.
• The system provides a common interface to all programs. This included a standardized way of specifying arguments types, default values, and documentation. Also it provides a list of common options to all programs (e.g. –help, –debug).

The system is designed primarily to decode options specified by name, i.e. "-option_name value" constructs. Positional arguments are supported as well, but are discommended since they typically offer less flexibility and are more error prone (any misspelled named argument will be assumed to be the first positional argument instead of triggering a warning).

The main structure used to the describe the program arguments is the SprOptDesc description array (list). The normal (non special) SprOptDesc elements (structures) consist of the following fields:

The option name:

the character string that must be used when selecting this option, without the preceeding dash ('-').

Flags:

one or more flags. In most cases the flag field will be set to SPR_OD_OPTIONAL or SPR_OD_REQUIRED, meaning that this argument is either optional (with a possible default value) or required (the program won't run when this argument is not specified). See SprOptFlags for more details concerning the different flags and their meaning.

Brief argument explanation:

a character string containing a short explanation of the argument.

Detailed argument explanation:

a character string containing the detailed (complete) explanation of the argument.

Argument type:

the arguments data type. This can be any datatype in existence in the SPRAAK environment, but in practice, it is best to limit oneself to the basic types defined in datatype.c.

Offset of the argument variable:

by default, the decoded arguments will be stored in a structure. The 'offset' links the option with a certain field in the structure. Obviously the type of the structure element the offset refers to should match the specified 'Argument type'. In special cases (indicated with additional flags in the 'flags' field), an absolute address or a function address needs to be specified instead.

Default value:

a character string containing the default value of the variable. A NULL can be specified if a default value is not in order. The default value string should be of the correct type, i.e. it must be possible to convert it to someting of the type 'Argument type' using the SprDt::str_cvt() method. To initialize dynamic (i.e. allocated) strings to NULL, the special value SPR_OD_NULL must be used. Elements of the type spr_dt_bool are always initialized. A NULL default value will be converted in a 'false'.

The last elements in the SprOptDesc array must always be a spr_opt_spec_end element. Other special elements are:

spr_od_info(title,info):

specify some (global) comment instead of an argument. The 'title' and 'info' arguments are strings containing the paragraph title (optional) and the actual information.

spr_od_include(other_opt_spec,offs):

include some other option description list.

spr_od_funcarg0(name,flags,brief,detailed,func):

define an option that will trigger a call to the function (*func)(SprMsgId *prog,const SprOptDesc*od_match,const SprOptDesc*od_list) when specified (the normal result of specifying an option is decoding the argument and storing its values).

spr_od_funcarg1(name,flags,brief,detailed,func,def_val):

define an option that will trigger a call to the function (*func)(SprMsgId *prog,const SprOptDesc*od_match,const char *arg_val) when specified (the normal result of specifying an option is decoding the argument and storing its values).

spr_od_posarg(flags,brief,detailed,type,offs,def_val):

define an positional (ordinal) argument, i.e. an argument with no option name. Ordinal arguments are filled in on a first come first served base. From the moment the first positional argument is encountered, all remaining arguments are assumed to be positional arguments! Use a collector data type if you want to collect all remaining arguments.

spr_od_alias(alias,original):

define an alias for some original argument, i.e. have two options refer to the same thing. Typically used to provide backward compatibility.

Example code:

typedef struct
 {int       arg_int;
  int       arg_flag;
  float     arg_f32;
  double    arg_f64;
  SprDynStr arg_str;
 } ArgOpt;

spr_sdoc spr_private_var
const SprOptDesc od[] =
 {{"nc",   SPR_OD_REQUIRED, "#coeff.",   "The number of filter coefficients for the ...", spr_dt_int,   offsetof(ArgOpt,arg_int),  "13"},
  {"F",    SPR_OD_OPTIONAL, "FIR flag",  "Use an FIR instead of an IIR (default) filter.",spr_dt_bool,  offsetof(ArgOpt,arg_flag), NULL},
  {"iv",   SPR_OD_OPTIONAL, "init. val.","Value used to initialize the filters.",         spr_dt_f32,   offsetof(ArgOpt,arg_f32), "0.0"},
  {"pi",   SPR_OD_OPTIONAL, "PI",        "Some magical constant.",                        spr_dt_f64,   offsetof(ArgOpt,arg_f64),"3.14"},
  {"name", SPR_OD_OPTIONAL, "name",      "Name to use when refering to ...",              spr_dt_dynstr,offsetof(ArgOpt,arg_str),"[unnamed]"},
  spr_od_end
 };

static ArgOpt arg;

main(int argc,const char *argv[])
{SPR_MSG_ID(routine,"my_program");
 if(spraak_ini_prog(&arg,od,routine,argv) == -1)
   goto LBL_ERROR;
 ...
 spraak_fini();
 return(0);
LBL_ERROR:
 spraak_fini();
 return(1);
}

Author

Kris Demuynck

Version

390 – 2017-08-29 19:00:00 UTC

Date

30/07/1993 - FS

First version.

13/08/2001 - KD

Complete rewrite based on the previous version written by Frank Schoeters.

Environment variables:

SPR_DEBUG_FPE
When this environment variable is set, the floating point processor on i86-linux platforms will trigger on all 'malign' exceptions (invalid operation, zero-divide and overflow). This feature is added to faciliate debugging.