Detailed Description

Module for simple unified handling of user-input from config-file and/or command-line.

Author: Reinhard Prix

Description

This module provides functions and macros to 'register' a set off C-variables as 'User Variables', which can then be read in from the commandline and/or an input config file, as parsed by Header ConfigFile.h.

The module also handles generating and outputting a help-string on the available input options when requested, and can deal with enforcing input of required options and using default values.

Usage

The general approach consists of the following steps:

set default-values for optional user-variables as appropriate
register all user-variables using calls to XLALRegisterUvarMember(), which assumes a pointer named 'uvar' to a struct containing all user-variables in the form 'uvar->UserVariable'.
parse user-input using XLALUserVarReadAllInput()

One can use XLALUserVarWasSet() to determine whether a given user-input option has been set by the user.

The function XLALUserVarGetLog() can be used to obtain a log-string containing the full user-input, either in commandline- or ConfigFile format.

Here is a worked simple example of its recommended use:

#include <stdio.h>
#include <lal/XLALError.h>
#include <lal/LALDatatypes.h>
 
#include <lal/UserInput.h>
 
// these are the C-variables we want to read in from user-input
typedef struct {
  BOOLEAN help;                // did user request help-output?
  INT4 anInteger;
  REAL8 aDoubleVar;
  CHAR *andAString;
  REAL8 specialGeekSwitch;
  LIGOTimeGPS someEpoch;
  REAL8 RA;
  REAL8 DEC;
} UserInput_t;
 
 
int main(int argc,char *argv[])
{
  UserInput_t XLAL_INIT_DECL(UserVariables); // initializes this struct to {0}
  UserInput_t *uvar = &UserVariables;          // struct-pointer allows us to use the XLALreg<TYPE>UserStruct() macros...
 
  // 1. step: set default-values for optional user-input variables
  uvar->anInteger = 0;
  uvar->andAString = NULL;     // Note: need to assign allocated strings here as default!!
 
  // 2. step: Register all user-variables using the shortcut macros:
  XLALRegisterUvarMember( help,               BOOLEAN, 'h',  HELP,      "Output this help-message");
  XLALRegisterUvarMember( anInteger,          INT4,    'i',  OPTIONAL,  "An example user-variable of an optional integer");
  XLALRegisterUvarMember( aDoubleVar,         REAL8,   'r',  REQUIRED,  "This REAL8 user-variable is required");
  XLALRegisterUvarMember( andAString,         STRING,   0,   OPTIONAL,  "Optional string-input, has no short-option");
  XLALRegisterUvarMember( someEpoch,          EPOCH,    0,   OPTIONAL,  "Reference epoch (format 'xx.yy[GPS|MJD]')");
  XLALRegisterUvarMember( RAJ,                RAJ,      0,   OPTIONAL,  "Sky location: equatorial right ascension in [0,2pi] (in radians or hours:minutes:seconds)");
  XLALRegisterUvarMember( DEC,                DECJ,     0,   OPTIONAL,  "Sky location: equatorial declination [-pi/2,pi/2] (in radians or degrees:minutes:seconds)");
  XLALRegisterUvarMember( specialGeekSwitch,  REAL8,    'g', DEVELOPER, "This REAL8 user-variable may not be relevant for standard usage");
 
  // 3. step: parse all user-input, from either config-file if given, or commandline (overloads config-file values)
  XLAL_CHECK ( XLALUserVarReadAllInput ( argc, argv, lalAppsVCSInfoList ) == XLAL_SUCCESS, XLAL_EFUNC);
 
  if (uvar->help){      // if user had requested help, then we're already done here
    return 0;
  }
 
  printf ("User-input was: anInteger = %d, aDoubleVar = %f, andAString = %s\n", uvar->anInteger, uvar->aDoubleVar, uvar->andAString );
  printf ("someEpoch = {%d s, %d ns}, RA = %f rad, DEC = %f rad\n", uvar->someEpoch.gpsSeconds, uvar->someEpoch.gpsNanoSeconds, uvar->RA, uvar->DEC );
 
  // 4. step: free user-input module memory
  XLALDestroyUserVars();
 
  LALCheckMemoryLeaks();
  return 0;
} // main()

Note: This code can be compiled as is within lalapps, and yields

$ LAL_DEBUG_LEVEL=1 ./tmp --help

Usage: ./tmp [@ConfigFile] [options], where options are:

-h, --help                BOOLEAN    Output this help-message []
-i, --anInteger           INT4       An example user-variable of an optional integer [0]
-r, --aDoubleVar          REAL8      This REAL8 user-variable is required [REQUIRED]
    --andAString          STRING     Optional string-input, has no short-option [NULL]
    --someEpoch           EPOCH      Reference epoch (format 'xx.yy[GPS|MJD]') [0.000000000GPS]
    --RA                  RAJ        Sky location: right ascension in [0,2pi] (in radians or hours:minutes:seconds) [0.0]
    --DEC                 DECJ       Sky location: declination [-pi/2,pi/2] (in radians or degrees:minutes:seconds) [0.0]

---------- The following are 'Developer'-options not useful for most users:----------

-g, --specialGeekSwitch   REAL8      This REAL8 user-variable may not be relevant for standard usage [0.0]

And if called

$ ./tmp -r 3.1415 --andAString="stupid example" --someEpoch=5555MJD --RA=10:25:10.123 --DEC=-30:0:0
User-input was: anInteger = 0, aDoubleVar = 3.141500, andAString = stupid example
someEpoch = {2147483596 s, 816000000 ns}, RA = 2.727813 rad, DEC = -0.523599 rad

Note: For a real-world example of usage, see various codes under lalapps/src/pulsar/{Injections,Fstatistic}

Modules
	Header UserInputParse.h
	Sub-module for parsing of input 'string values' as various 'types' (as defined in Header UserInput.h).

	Header UserInputPrint.h
	Sub-module for general printing of various input 'types' (as defined in Header UserInput.h) as 'string values', These can be thought of as the 'inverse functions' to Header UserInputParse.h.

Prototypes
int	XLALRegisterUserVar (void cvar, const void cdata, const CHAR name, UserVarType type, CHAR optchar, UserVarCategory category, const CHAR help)
	Internal function: Register a user-variable with the module. More...

void	XLALDestroyUserVars (void)
	Free all memory associated with user-variable linked list. More...

int	XLALUserVarReadCmdline (BOOLEAN should_exit, int argc, char argv[], const LALVCSInfoList vcs_list)
	Parse command-line into UserVariable array. More...

int	XLALUserVarReadCfgfile (BOOLEAN should_exit, const CHAR cfgfile)
	Read config-variables from cfgfile and parse into input-structure. More...

int	XLALUserVarReadAllInput (BOOLEAN should_exit, int argc, char argv[], const LALVCSInfoList vcs_list)
	Put all the pieces together, and basically does everything: print help (if requested), get config-filename from cmd-line (if found), then interpret config-file and then the command-line. More...

int	XLALUserVarWasSet (const void *cvar)
	Has this user-variable been set by the user? returns 1 (=TRUE) or 0 (=FALSE) on success, error-code otherwise. More...

void	XLALUserVarCheck (BOOLEAN should_exit, const int assertion, const CHAR fmt,...) _LAL_GCC_PRINTF_FORMAT_(3

void CHAR *	XLALUserVarGetLog (UserVarLogFormat format)
	Return a log-string representing the complete user-input. More...

CHAR *	XLALUserVarGetLogEx (UserVarLogFormat format, const BOOLEAN skip_unset)
	Return a log-string representing the complete user-input. More...

	DECL_REGISTER_UVAR (BOOLEAN, BOOLEAN)

	DECL_REGISTER_UVAR (INT4, INT4)

	DECL_REGISTER_UVAR (INT8, INT8)

	DECL_REGISTER_UVAR (UINT4, UINT4)

	DECL_REGISTER_UVAR (UINT8, UINT8)

	DECL_REGISTER_UVAR (REAL8, REAL8)

	DECL_REGISTER_UVAR (EPOCH, LIGOTimeGPS)

	DECL_REGISTER_UVAR (RAJ, REAL8)

	DECL_REGISTER_UVAR (DECJ, REAL8)

	DECL_REGISTER_UVAR (STRING, CHAR *)

	DECL_REGISTER_UVAR (INT4Range, INT4Range)

	DECL_REGISTER_UVAR (REAL8Range, REAL8Range)

	DECL_REGISTER_UVAR (EPOCHRange, LIGOTimeGPSRange)

	DECL_REGISTER_UVAR (RAJRange, REAL8Range)

	DECL_REGISTER_UVAR (DECJRange, REAL8Range)

	DECL_REGISTER_UVAR_AUX_DATA (UserEnum, int, UserChoices)

	DECL_REGISTER_UVAR_AUX_DATA (UserFlag, int, UserChoices)

	DECL_REGISTER_UVAR (INT4Vector, INT4Vector *)

	DECL_REGISTER_UVAR (UINT4Vector, UINT4Vector *)

	DECL_REGISTER_UVAR (REAL8Vector, REAL8Vector *)

	DECL_REGISTER_UVAR (STRINGVector, LALStringVector *)

Enumerations
enum	UserVarCategory { UVAR_CATEGORY_START = 0 , UVAR_CATEGORY_OPTIONAL , UVAR_CATEGORY_REQUIRED , UVAR_CATEGORY_DEVELOPER , UVAR_CATEGORY_DEPRECATED , UVAR_CATEGORY_DEFUNCT , UVAR_CATEGORY_NODEFAULT , UVAR_CATEGORY_END }
	Mutually-exclusive user variable categories: optional, required, help, developer, ... More...

enum	UserVarLogFormat { UVAR_LOGFMT_RAWFORM , UVAR_LOGFMT_CFGFILE , UVAR_LOGFMT_CMDLINE , UVAR_LOGFMT_PROCPARAMS , UVAR_LOGFMT_LAST }
	Format for logging User-input: configFile- or cmdLine-style. More...

Macros
#define	XLALRegisterUvarMember(name, type, option, category, ...) XLALRegister ##type## UserVar( &(uvar-> name), NULL, #name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)
	Shortcut macro for registering new user variables, which are accessed via the struct-pointer '*uvar'. More...

#define	XLALRegisterUvarAuxDataMember(name, type, cdata, option, category, ...) XLALRegister ##type## UserVar( &(uvar-> name), cdata, #name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)
	Shortcut macro for registering new user variables, which are accessed via the struct-pointer '*uvar', and which acquire some auxilliary data in order to be parsed. More...

#define	XLALRegisterNamedUvar(cvar, name, type, option, category, ...) XLALRegister ##type## UserVar( cvar, NULL, name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)
	Shortcut macro for registering new user variables, named 'name' and accessed via the variable-pointer '*cvar'. More...

#define	XLALRegisterNamedUvarAuxData(cvar, name, type, cdata, option, category, ...) XLALRegister ##type## UserVar( cvar, cdata, name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)
	Shortcut macro for registering new user variables, named 'name' and accessed via the variable-pointer '*cvar', and which acquire some auxilliary data in order to be parsed. More...

#define	DECL_REGISTER_UVAR(UTYPE, CTYPE) DECL_REGISTER_UVAR_AUX_DATA(UTYPE,CTYPE,void)

#define	DECL_REGISTER_UVAR_AUX_DATA(UTYPE, CTYPE, DTYPE) int XLALRegister ##UTYPE## UserVar ( CTYPE cvar, const DTYPE cdata, const CHAR name, CHAR optchar, UserVarCategory category, const CHAR fmt, ... ) _LAL_GCC_PRINTF_FORMAT_(6,7)

Variables
const char *	lalUserVarHelpBrief
	An optional brief description of the program, printed after its name as part of the help page. More...

const char *	lalUserVarHelpDescription
	An optional longer description of the program, printed in its own section as part of the help page. More...

const char *	lalUserVarHelpOptionSubsection
	An optional subsection heading under OPTIONS, under which all subsequently-defined user variables are printed as part of the help page. More...

Convenience macros for checking how many of a set of user input variables were set
#define	UVAR_SET(n) (XLALUserVarWasSet(&(uvar-> n)) ? 1 : 0)

#define	UVAR_SET2(n1, n2) (UVAR_SET(n1) + UVAR_SET(n2))

#define	UVAR_SET3(n1, n2, n3) (UVAR_SET2(n1,n2) + UVAR_SET(n3))

#define	UVAR_SET4(n1, n2, n3, n4) (UVAR_SET3(n1,n2,n3) + UVAR_SET(n4))

#define	UVAR_SET5(n1, n2, n3, n4, n5) (UVAR_SET4(n1,n2,n3,n4) + UVAR_SET(n5))

#define	UVAR_SET6(n1, n2, n3, n4, n5, n6) (UVAR_SET5(n1,n2,n3,n4,n5) + UVAR_SET(n6))

Convenience macros for checking whether all of a set of user input variables were set
#define	UVAR_ALLSET2(n1, n2) (UVAR_SET2(n1,n2) == 2)

#define	UVAR_ALLSET3(n1, n2, n3) (UVAR_SET3(n1,n2,n3) == 3)

#define	UVAR_ALLSET4(n1, n2, n3, n4) (UVAR_SET4(n1,n2,n3,n4) == 4)

#define	UVAR_ALLSET5(n1, n2, n3, n4, n5) (UVAR_SET5(n1,n2,n3,n4,n5) == 5)

#define	UVAR_ALLSET6(n1, n2, n3, n4, n5, n6) (UVAR_SET6(n1,n2,n3,n4,n5,n6) == 6)

Convenience macros for checking whether any of a set of user input variables were set
#define	UVAR_ANYSET2(n1, n2) (UVAR_SET2(n1,n2) > 0)

#define	UVAR_ANYSET3(n1, n2, n3) (UVAR_SET3(n1,n2,n3) > 0)

#define	UVAR_ANYSET4(n1, n2, n3, n4) (UVAR_SET4(n1,n2,n3,n4) > 0)

#define	UVAR_ANYSET5(n1, n2, n3, n4, n5) (UVAR_SET5(n1,n2,n3,n4,n5) > 0)

#define	UVAR_ANYSET6(n1, n2, n3, n4, n5, n6) (UVAR_SET6(n1,n2,n3,n4,n5,n6) > 0)

Convenience macros for printing user input variables in error messages
#define	UVAR_FMT "`--%s'"

#define	UVAR_STR(n) "`--"#n"'"

#define	UVAR_STR2AND(n1, n2) "`--"#n1"' and `--"#n2"'"

#define	UVAR_STR2OR(n1, n2) "`--"#n1"' or `--"#n2"'"

#define	UVAR_STR3AND(n1, n2, n3) "`--"#n1"', `--"#n2"', and `--"#n3"'"

#define	UVAR_STR3OR(n1, n2, n3) "`--"#n1"', `--"#n2"', or `--"#n3"'"

#define	UVAR_STR4AND(n1, n2, n3, n4) "`--"#n1"', `--"#n2"', `--"#n3"', and `--"#n4"'"

#define	UVAR_STR4OR(n1, n2, n3, n4) "`--"#n1"', `--"#n2"', `--"#n3"', or `--"#n4"'"

#define	UVAR_STR5AND(n1, n2, n3, n4, n5) "`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', and `--"#n5"'"

#define	UVAR_STR5OR(n1, n2, n3, n4, n5) "`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', or `--"#n5"'"

#define	UVAR_STR6AND(n1, n2, n3, n4, n5, n6) "`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', `--"#n5"', and `--"#n6"'"

#define	UVAR_STR6OR(n1, n2, n3, n4, n5, n6) "`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', `--"#n5"', or `--"#n6"'"

Function Documentation

◆ XLALRegisterUserVar()

int XLALRegisterUserVar	(	void *	cvar,
		const void *	cdata,
		const CHAR *	name,
		UserVarType	type,
		CHAR	optchar,
		UserVarCategory	category,
		const CHAR *	help
	)

Internal function: Register a user-variable with the module.

Effectively put an appropriate entry into UVAR_vars

Checks that long- and short-options are unique, an error is returned if a previous option name collides.

Note: don't use this function directly, as it is not type-safe!! ==> use the type-safe macro XLALRegisterUvarMember(name,type,option,category,help) instead!

Parameters

cvar	pointer to the actual C-variable to link to this user-variable
cdata	pointer to auxilliary data needed to parse the C-variable
name	name of user-variable to register
type	variable type (int,bool,string,real)
optchar	optional short-option character
category	sets category to this
help	help-string explaining this input-variable

Definition at line 275 of file UserInput.c.

◆ XLALDestroyUserVars()

void XLALDestroyUserVars ( void )

Free all memory associated with user-variable linked list.

Definition at line 349 of file UserInput.c.

◆ XLALUserVarReadCmdline()

int XLALUserVarReadCmdline	(	BOOLEAN *	should_exit,
		int	argc,
		char *	argv[],
		const LALVCSInfoList	vcs_list
	)

Parse command-line into UserVariable array.

If *should_exit is TRUE when this function returns, the caller should exit immediately.

Definition at line 394 of file UserInput.c.

◆ XLALUserVarReadCfgfile()

int XLALUserVarReadCfgfile	(	BOOLEAN *	should_exit,
		const CHAR *	cfgfile
	)

Read config-variables from cfgfile and parse into input-structure.

An error is reported if the config-file reading fails, but the individual variable-reads are treated as optional

If *should_exit is TRUE when this function returns, the caller should exit immediately.

Definition at line 647 of file UserInput.c.

◆ XLALUserVarReadAllInput()

int XLALUserVarReadAllInput	(	BOOLEAN *	should_exit,
		int	argc,
		char *	argv[],
		const LALVCSInfoList	vcs_list
	)

Put all the pieces together, and basically does everything: print help (if requested), get config-filename from cmd-line (if found), then interpret config-file and then the command-line.

If *should_exit is TRUE when this function returns, the program should exit immediately with a non-zero status.

Definition at line 1064 of file UserInput.c.

◆ XLALUserVarWasSet()

int XLALUserVarWasSet ( const void * cvar )

Has this user-variable been set by the user? returns 1 (=TRUE) or 0 (=FALSE) on success, error-code otherwise.

Definition at line 1175 of file UserInput.c.

◆ XLALUserVarCheck()

void XLALUserVarCheck	(	BOOLEAN *	should_exit,
		const int	assertion,
		const CHAR *	fmt,
			...
	)

◆ XLALUserVarGetLog()

void CHAR* XLALUserVarGetLog ( UserVarLogFormat format )

Return a log-string representing the complete user-input.

NOTE: we only record user-variables that have been set by the user.

Parameters

format output format: return as config-file or command-line

Definition at line 1228 of file UserInput.c.

◆ XLALUserVarGetLogEx()

CHAR* XLALUserVarGetLogEx	(	UserVarLogFormat	format,
		const BOOLEAN	skip_unset
	)

Return a log-string representing the complete user-input.

Parameters

format	output format: return as config-file or command-line
skip_unset	if true, do not include unset variables in output

Definition at line 1238 of file UserInput.c.

◆ DECL_REGISTER_UVAR() [1/19]

DECL_REGISTER_UVAR	(	BOOLEAN	,
		BOOLEAN
	)

◆ DECL_REGISTER_UVAR() [2/19]

DECL_REGISTER_UVAR	(	INT4	,
		INT4
	)

◆ DECL_REGISTER_UVAR() [3/19]

DECL_REGISTER_UVAR	(	INT8	,
		INT8
	)

◆ DECL_REGISTER_UVAR() [4/19]

DECL_REGISTER_UVAR	(	UINT4	,
		UINT4
	)

◆ DECL_REGISTER_UVAR() [5/19]

DECL_REGISTER_UVAR	(	UINT8	,
		UINT8
	)

◆ DECL_REGISTER_UVAR() [6/19]

DECL_REGISTER_UVAR	(	REAL8	,
		REAL8
	)

◆ DECL_REGISTER_UVAR() [7/19]

DECL_REGISTER_UVAR	(	EPOCH	,
		LIGOTimeGPS
	)

◆ DECL_REGISTER_UVAR() [8/19]

DECL_REGISTER_UVAR	(	RAJ	,
		REAL8
	)

◆ DECL_REGISTER_UVAR() [9/19]

DECL_REGISTER_UVAR	(	DECJ	,
		REAL8
	)

◆ DECL_REGISTER_UVAR() [10/19]

DECL_REGISTER_UVAR	(	STRING	,
		CHAR *
	)

◆ DECL_REGISTER_UVAR() [11/19]

DECL_REGISTER_UVAR	(	INT4Range	,
		INT4Range
	)

◆ DECL_REGISTER_UVAR() [12/19]

DECL_REGISTER_UVAR	(	REAL8Range	,
		REAL8Range
	)

◆ DECL_REGISTER_UVAR() [13/19]

DECL_REGISTER_UVAR	(	EPOCHRange	,
		LIGOTimeGPSRange
	)

◆ DECL_REGISTER_UVAR() [14/19]

DECL_REGISTER_UVAR	(	RAJRange	,
		REAL8Range
	)

◆ DECL_REGISTER_UVAR() [15/19]

DECL_REGISTER_UVAR	(	DECJRange	,
		REAL8Range
	)

◆ DECL_REGISTER_UVAR_AUX_DATA() [1/2]

DECL_REGISTER_UVAR_AUX_DATA	(	UserEnum	,
		int	,
		UserChoices
	)

◆ DECL_REGISTER_UVAR_AUX_DATA() [2/2]

DECL_REGISTER_UVAR_AUX_DATA	(	UserFlag	,
		int	,
		UserChoices
	)

◆ DECL_REGISTER_UVAR() [16/19]

DECL_REGISTER_UVAR	(	INT4Vector	,
		INT4Vector *
	)

◆ DECL_REGISTER_UVAR() [17/19]

DECL_REGISTER_UVAR	(	UINT4Vector	,
		UINT4Vector *
	)

◆ DECL_REGISTER_UVAR() [18/19]

DECL_REGISTER_UVAR	(	REAL8Vector	,
		REAL8Vector *
	)

◆ DECL_REGISTER_UVAR() [19/19]

DECL_REGISTER_UVAR	(	STRINGVector	,
		LALStringVector *
	)

Enumeration Type Documentation

◆ UserVarCategory

enum UserVarCategory

Mutually-exclusive user variable categories: optional, required, help, developer, ...

Enumerator
UVAR_CATEGORY_START	internal start marker for range checking
UVAR_CATEGORY_OPTIONAL	optional
UVAR_CATEGORY_REQUIRED	required
UVAR_CATEGORY_DEVELOPER	optional and hidden in help-output until lalDebugLevel>=warning
UVAR_CATEGORY_DEPRECATED	optional and hidden until lalDebugLevel>=info; still supported but output warning if used
UVAR_CATEGORY_DEFUNCT	hidden completely from help output; not supported, will output error + help-string if used
UVAR_CATEGORY_NODEFAULT	optional and supresses printing the default value in the help, where it doesn't make sense
UVAR_CATEGORY_END	internal end marker for range checking

Definition at line 185 of file UserInput.h.

◆ UserVarLogFormat

enum UserVarLogFormat

Format for logging User-input: configFile- or cmdLine-style.

This determines the format of the string returned from XLALUserVarGetLog().

Enumerator
UVAR_LOGFMT_RAWFORM	return UserVars in a raw format suitable for further parsing
UVAR_LOGFMT_CFGFILE	return UserVars as a config-file
UVAR_LOGFMT_CMDLINE	return UserVars as a command-line
UVAR_LOGFMT_PROCPARAMS	return UserVars suitable for filling in process-params struct
UVAR_LOGFMT_LAST

Definition at line 201 of file UserInput.h.

Macro Definition Documentation

◆ XLALRegisterUvarMember

#define XLALRegisterUvarMember	(	name,
		type,
		option,
		category,
		...
	)	XLALRegister ##type## UserVar( &(uvar-> name), NULL, #name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)

Shortcut macro for registering new user variables, which are accessed via the struct-pointer '*uvar'.

Definition at line 157 of file UserInput.h.

◆ XLALRegisterUvarAuxDataMember

#define XLALRegisterUvarAuxDataMember	(	name,
		type,
		cdata,
		option,
		category,
		...
	)	XLALRegister ##type## UserVar( &(uvar-> name), cdata, #name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)

Shortcut macro for registering new user variables, which are accessed via the struct-pointer '*uvar', and which acquire some auxilliary data in order to be parsed.

Definition at line 164 of file UserInput.h.

◆ XLALRegisterNamedUvar

#define XLALRegisterNamedUvar	(	cvar,
		name,
		type,
		option,
		category,
		...
	)	XLALRegister ##type## UserVar( cvar, NULL, name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)

Shortcut macro for registering new user variables, named 'name' and accessed via the variable-pointer '*cvar'.

Note: This style of user variable is deprecated; XLALRegisterUvarMember() is preferred

Definition at line 171 of file UserInput.h.

◆ XLALRegisterNamedUvarAuxData

#define XLALRegisterNamedUvarAuxData	(	cvar,
		name,
		type,
		cdata,
		option,
		category,
		...
	)	XLALRegister ##type## UserVar( cvar, cdata, name, option, UVAR_CATEGORY_ ## category, __VA_ARGS__)

Shortcut macro for registering new user variables, named 'name' and accessed via the variable-pointer '*cvar', and which acquire some auxilliary data in order to be parsed.

Note: This style of user variable is deprecated; XLALRegisterUvarAuxDataMember() is preferred

Definition at line 179 of file UserInput.h.

◆ UVAR_SET

#define UVAR_SET ( n ) (XLALUserVarWasSet(&(uvar-> n)) ? 1 : 0)

Definition at line 230 of file UserInput.h.

◆ UVAR_SET2

#define UVAR_SET2	(	n1,
		n2
	)	(UVAR_SET(n1) + UVAR_SET(n2))

Definition at line 231 of file UserInput.h.

◆ UVAR_SET3

#define UVAR_SET3	(	n1,
		n2,
		n3
	)	(UVAR_SET2(n1,n2) + UVAR_SET(n3))

Definition at line 232 of file UserInput.h.

◆ UVAR_SET4

#define UVAR_SET4	(	n1,
		n2,
		n3,
		n4
	)	(UVAR_SET3(n1,n2,n3) + UVAR_SET(n4))

Definition at line 233 of file UserInput.h.

◆ UVAR_SET5

#define UVAR_SET5	(	n1,
		n2,
		n3,
		n4,
		n5
	)	(UVAR_SET4(n1,n2,n3,n4) + UVAR_SET(n5))

Definition at line 234 of file UserInput.h.

◆ UVAR_SET6

#define UVAR_SET6	(	n1,
		n2,
		n3,
		n4,
		n5,
		n6
	)	(UVAR_SET5(n1,n2,n3,n4,n5) + UVAR_SET(n6))

Definition at line 235 of file UserInput.h.

◆ UVAR_ALLSET2

#define UVAR_ALLSET2	(	n1,
		n2
	)	(UVAR_SET2(n1,n2) == 2)

Definition at line 242 of file UserInput.h.

◆ UVAR_ALLSET3

#define UVAR_ALLSET3	(	n1,
		n2,
		n3
	)	(UVAR_SET3(n1,n2,n3) == 3)

Definition at line 243 of file UserInput.h.

◆ UVAR_ALLSET4

#define UVAR_ALLSET4	(	n1,
		n2,
		n3,
		n4
	)	(UVAR_SET4(n1,n2,n3,n4) == 4)

Definition at line 244 of file UserInput.h.

◆ UVAR_ALLSET5

#define UVAR_ALLSET5	(	n1,
		n2,
		n3,
		n4,
		n5
	)	(UVAR_SET5(n1,n2,n3,n4,n5) == 5)

Definition at line 245 of file UserInput.h.

◆ UVAR_ALLSET6

#define UVAR_ALLSET6	(	n1,
		n2,
		n3,
		n4,
		n5,
		n6
	)	(UVAR_SET6(n1,n2,n3,n4,n5,n6) == 6)

Definition at line 246 of file UserInput.h.

◆ UVAR_ANYSET2

#define UVAR_ANYSET2	(	n1,
		n2
	)	(UVAR_SET2(n1,n2) > 0)

Definition at line 253 of file UserInput.h.

◆ UVAR_ANYSET3

#define UVAR_ANYSET3	(	n1,
		n2,
		n3
	)	(UVAR_SET3(n1,n2,n3) > 0)

Definition at line 254 of file UserInput.h.

◆ UVAR_ANYSET4

#define UVAR_ANYSET4	(	n1,
		n2,
		n3,
		n4
	)	(UVAR_SET4(n1,n2,n3,n4) > 0)

Definition at line 255 of file UserInput.h.

◆ UVAR_ANYSET5

#define UVAR_ANYSET5	(	n1,
		n2,
		n3,
		n4,
		n5
	)	(UVAR_SET5(n1,n2,n3,n4,n5) > 0)

Definition at line 256 of file UserInput.h.

◆ UVAR_ANYSET6

#define UVAR_ANYSET6	(	n1,
		n2,
		n3,
		n4,
		n5,
		n6
	)	(UVAR_SET6(n1,n2,n3,n4,n5,n6) > 0)

Definition at line 257 of file UserInput.h.

◆ UVAR_FMT

#define UVAR_FMT "`--%s'"

Definition at line 264 of file UserInput.h.

◆ UVAR_STR

#define UVAR_STR ( n ) "`--"#n"'"

Definition at line 265 of file UserInput.h.

◆ UVAR_STR2AND

#define UVAR_STR2AND	(	n1,
		n2
	)	"`--"#n1"' and `--"#n2"'"

Definition at line 266 of file UserInput.h.

◆ UVAR_STR2OR

#define UVAR_STR2OR	(	n1,
		n2
	)	"`--"#n1"' or `--"#n2"'"

Definition at line 267 of file UserInput.h.

◆ UVAR_STR3AND

#define UVAR_STR3AND	(	n1,
		n2,
		n3
	)	"`--"#n1"', `--"#n2"', and `--"#n3"'"

Definition at line 268 of file UserInput.h.

◆ UVAR_STR3OR

#define UVAR_STR3OR	(	n1,
		n2,
		n3
	)	"`--"#n1"', `--"#n2"', or `--"#n3"'"

Definition at line 269 of file UserInput.h.

◆ UVAR_STR4AND

#define UVAR_STR4AND	(	n1,
		n2,
		n3,
		n4
	)	"`--"#n1"', `--"#n2"', `--"#n3"', and `--"#n4"'"

Definition at line 270 of file UserInput.h.

◆ UVAR_STR4OR

#define UVAR_STR4OR	(	n1,
		n2,
		n3,
		n4
	)	"`--"#n1"', `--"#n2"', `--"#n3"', or `--"#n4"'"

Definition at line 271 of file UserInput.h.

◆ UVAR_STR5AND

#define UVAR_STR5AND	(	n1,
		n2,
		n3,
		n4,
		n5
	)	"`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', and `--"#n5"'"

Definition at line 272 of file UserInput.h.

◆ UVAR_STR5OR

#define UVAR_STR5OR	(	n1,
		n2,
		n3,
		n4,
		n5
	)	"`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', or `--"#n5"'"

Definition at line 273 of file UserInput.h.

◆ UVAR_STR6AND

#define UVAR_STR6AND	(	n1,
		n2,
		n3,
		n4,
		n5,
		n6
	)	"`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', `--"#n5"', and `--"#n6"'"

Definition at line 274 of file UserInput.h.

◆ UVAR_STR6OR

#define UVAR_STR6OR	(	n1,
		n2,
		n3,
		n4,
		n5,
		n6
	)	"`--"#n1"', `--"#n2"', `--"#n3"', `--"#n4"', `--"#n5"', or `--"#n6"'"

Definition at line 275 of file UserInput.h.

◆ DECL_REGISTER_UVAR

#define DECL_REGISTER_UVAR	(	UTYPE,
		CTYPE
	)	DECL_REGISTER_UVAR_AUX_DATA(UTYPE,CTYPE,void)

Definition at line 279 of file UserInput.h.

◆ DECL_REGISTER_UVAR_AUX_DATA

#define DECL_REGISTER_UVAR_AUX_DATA	(	UTYPE,
		CTYPE,
		DTYPE
	)	int XLALRegister ##UTYPE## UserVar ( CTYPE cvar, const DTYPE cdata, const CHAR name, CHAR optchar, UserVarCategory category, const CHAR fmt, ... ) _LAL_GCC_PRINTF_FORMAT_(6,7)

Definition at line 281 of file UserInput.h.

Variable Documentation

◆ lalUserVarHelpBrief

const char* lalUserVarHelpBrief

extern

An optional brief description of the program, printed after its name as part of the help page.

Definition at line 248 of file UserInput.c.

◆ lalUserVarHelpDescription

const char* lalUserVarHelpDescription

extern

An optional longer description of the program, printed in its own section as part of the help page.

Definition at line 253 of file UserInput.c.

◆ lalUserVarHelpOptionSubsection

const char* lalUserVarHelpOptionSubsection

extern

An optional subsection heading under OPTIONS, under which all subsequently-defined user variables are printed as part of the help page.

Definition at line 258 of file UserInput.c.

Detailed Description

Description

Usage

Modules

Prototypes

Enumerations

Macros

Variables

Convenience macros for checking how many of a set of user input variables were set

Convenience macros for checking whether all of a set of user input variables were set

Convenience macros for checking whether any of a set of user input variables were set

Convenience macros for printing user input variables in error messages

Function Documentation

◆ XLALRegisterUserVar()

◆ XLALDestroyUserVars()

◆ XLALUserVarReadCmdline()

◆ XLALUserVarReadCfgfile()

◆ XLALUserVarReadAllInput()

◆ XLALUserVarWasSet()

◆ XLALUserVarCheck()

◆ XLALUserVarGetLog()

◆ XLALUserVarGetLogEx()

◆ DECL_REGISTER_UVAR() [1/19]

◆ DECL_REGISTER_UVAR() [2/19]

◆ DECL_REGISTER_UVAR() [3/19]

◆ DECL_REGISTER_UVAR() [4/19]

◆ DECL_REGISTER_UVAR() [5/19]

◆ DECL_REGISTER_UVAR() [6/19]

◆ DECL_REGISTER_UVAR() [7/19]

◆ DECL_REGISTER_UVAR() [8/19]

◆ DECL_REGISTER_UVAR() [9/19]

◆ DECL_REGISTER_UVAR() [10/19]

◆ DECL_REGISTER_UVAR() [11/19]

◆ DECL_REGISTER_UVAR() [12/19]

◆ DECL_REGISTER_UVAR() [13/19]

◆ DECL_REGISTER_UVAR() [14/19]

◆ DECL_REGISTER_UVAR() [15/19]

◆ DECL_REGISTER_UVAR_AUX_DATA() [1/2]

◆ DECL_REGISTER_UVAR_AUX_DATA() [2/2]

◆ DECL_REGISTER_UVAR() [16/19]

◆ DECL_REGISTER_UVAR() [17/19]

◆ DECL_REGISTER_UVAR() [18/19]

◆ DECL_REGISTER_UVAR() [19/19]

Enumeration Type Documentation

◆ UserVarCategory

◆ UserVarLogFormat

Macro Definition Documentation

◆ XLALRegisterUvarMember

◆ XLALRegisterUvarAuxDataMember

◆ XLALRegisterNamedUvar

◆ XLALRegisterNamedUvarAuxData

◆ UVAR_SET

◆ UVAR_SET2

◆ UVAR_SET3

◆ UVAR_SET4

◆ UVAR_SET5

◆ UVAR_SET6

◆ UVAR_ALLSET2

◆ UVAR_ALLSET3

◆ UVAR_ALLSET4

◆ UVAR_ALLSET5

◆ UVAR_ALLSET6

◆ UVAR_ANYSET2

◆ UVAR_ANYSET3

◆ UVAR_ANYSET4

◆ UVAR_ANYSET5

◆ UVAR_ANYSET6

◆ UVAR_FMT

◆ UVAR_STR

◆ UVAR_STR2AND

◆ UVAR_STR2OR

◆ UVAR_STR3AND

◆ UVAR_STR3OR

◆ UVAR_STR4AND

◆ UVAR_STR4OR

◆ UVAR_STR5AND

◆ UVAR_STR5OR

◆ UVAR_STR6AND

◆ UVAR_STR6OR

◆ DECL_REGISTER_UVAR