UserInput.h File Reference

Author:: Reinhard Prix Header file defining the API for the UserInput modules.

#include <lal/ConfigFile.h>
#include <lal/SFTutils.h>
#include <lal/LIGOMetadataTables.h>

Include dependency graph for UserInput.h:

Go to the source code of this file.

Defines

#define LALregREALUserVar(status, name, option, flag, help)   TRY(LALRegisterREALUserVar((status)->statusPtr, #name, option, flag, help,&(uvar_ ## name)), status)

#define LALregINTUserVar(status, name, option, flag, help)   TRY(LALRegisterINTUserVar((status)->statusPtr, #name, option,flag, help,&(uvar_ ## name)), status)

#define LALregBOOLUserVar(status, name, option, flag, help)   TRY(LALRegisterBOOLUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)

#define LALregSTRINGUserVar(status, name, option, flag, help)   TRY(LALRegisterSTRINGUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)

#define LALregLISTUserVar(status, name, option, flag, help)   TRY(LALRegisterLISTUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)

#define LALregREALUserStruct(status, name, option, flag, help)   TRY(LALRegisterREALUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)), status)

#define LALregINTUserStruct(status, name, option, flag, help)   TRY(LALRegisterINTUserVar((status)->statusPtr, #name, option,flag, help, &(uvar-> name)), status)

#define LALregBOOLUserStruct(status, name, option, flag, help)   TRY(LALRegisterBOOLUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)

#define LALregSTRINGUserStruct(status, name, option, flag, help)   TRY(LALRegisterSTRINGUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)

#define LALregLISTUserStruct(status, name, option, flag, help)   TRY(LALRegisterLISTUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)

Error codes

#define USERINPUTH_ENULL   1

#define USERINPUTH_ENONULL   2

#define USERINPUTH_EMEM   3

#define USERINPUTH_EOPT   4

#define USERINPUTH_ENOUVARS   5

#define USERINPUTH_ECMDLARG   6

#define USERINPUTH_EUNKNOWN   7

#define USERINPUTH_ENOTSET   8

#define USERINPUTH_EDEBUG   9

#define USERINPUTH_EONECONFIG   10

#define USERINPUTH_ERECFORMAT   11

#define USERINPUTH_EXLAL   12

#define USERINPUTH_MSGENULL   "Arguments contained an unexpected null pointer."

#define USERINPUTH_MSGENONULL   "Output pointer is not NULL"

#define USERINPUTH_MSGEMEM   "Out of memory"

#define USERINPUTH_MSGEOPT   "Unknown command-line option encountered"

#define USERINPUTH_MSGENOUVARS   "No user-variables have been registered!"

#define USERINPUTH_MSGECMDLARG   "Illegal command-line argument"

#define USERINPUTH_MSGEUNKNOWN   "Unknown user-variable"

#define USERINPUTH_MSGENOTSET   "Required user-variable was not set"

#define USERINPUTH_MSGEDEBUG   "lalDebugLevel can only be read before ANY mallocs(), even hidden.."

#define USERINPUTH_MSGEONECONFIG   "Currently one ONE config-file can be specified using '@'"

#define USERINPUTH_MSGERECFORMAT   "Unknown format for recording user-input"

#define USERINPUTH_MSGEXLAL   "Failure in XLAL function"

Enumerations

enum UserVarState {
  UVAR_OPTIONAL = 0, UVAR_REQUIRED = 1<<0, UVAR_HELP = 1<<1, UVAR_DEVELOPER = 1<<2,
  UVAR_SPECIAL = 1<<3, UVAR_WAS_SET = 1<<7
}

State-flags: variable is optional, required, help, developer or was_set. More...

enum UserVarLogFormat { UVAR_LOGFMT_CFGFILE, UVAR_LOGFMT_CMDLINE, UVAR_LOGFMT_PROCPARAMS, UVAR_LOGFMT_LAST }

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

Functions

NRCSID (USERINPUTH,"$Id: UserInput.h,v 1.23 2008/09/14 12:26:44 reinhard Exp $")

void LALRegisterREALUserVar (LALStatus *, const CHAR *name, CHAR optchar, UserVarState flag, const CHAR *helpstr, REAL8 *cvar)

void LALRegisterINTUserVar (LALStatus *, const CHAR *name, CHAR optchar, UserVarState flag, const CHAR *helpstr, INT4 *cvar)

void LALRegisterBOOLUserVar (LALStatus *, const CHAR *name, CHAR optchar, UserVarState flag, const CHAR *helpstr, BOOLEAN *cvar)

void LALRegisterSTRINGUserVar (LALStatus *, const CHAR *name, CHAR optchar, UserVarState flag, const CHAR *helpstr, CHAR **cvar)

void LALRegisterLISTUserVar (LALStatus *, const CHAR *name, CHAR optchar, UserVarState flag, const CHAR *helpstr, LALStringVector **cvar)

void LALDestroyUserVars (LALStatus *)

Free all memory associated with user-variable linked list.

void LALUserVarReadAllInput (LALStatus *, int argc, char *argv[])

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

void LALUserVarReadCmdline (LALStatus *, int argc, char *argv[])

Parse command-line into UserVariable array.

void LALUserVarReadCfgfile (LALStatus *, const CHAR *cfgfile)

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

void LALUserVarHelpString (LALStatus *, CHAR **helpstring, const CHAR *progname)

Assemble all help-info from uvars into a help-string.

void LALUserVarCheckRequired (LALStatus *)

Check that all required user-variables have been set successfully.

INT4 LALUserVarWasSet (const void *cvar)

Has this user-variable been set by the user? return -1 on error, TRUE/FALSE otherwise.

void LALGetDebugLevel (LALStatus *, int argc, char *argv[], CHAR optchar)

Handle the delicate setting of lalDebuglevel.

void LALUserVarGetLog (LALStatus *, CHAR **logstr, UserVarLogFormat format)

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

void LALUserVarGetProcParamsTable (LALStatus *status, ProcessParamsTable **out, CHAR *progname)

Return user log as a process-params table.

Detailed Description

Author:: Reinhard Prix Header file defining the API for the UserInput modules.

Date:

Date: 2008/09/14 12:26:44

Definition in file UserInput.h.

Define Documentation

#define USERINPUTH_ENULL 1

Definition at line 51 of file UserInput.h.

#define USERINPUTH_ENONULL 2

Definition at line 52 of file UserInput.h.

#define USERINPUTH_EMEM 3

Definition at line 53 of file UserInput.h.

#define USERINPUTH_EOPT 4

Definition at line 54 of file UserInput.h.

#define USERINPUTH_ENOUVARS 5

Definition at line 55 of file UserInput.h.

#define USERINPUTH_ECMDLARG 6

Definition at line 56 of file UserInput.h.

#define USERINPUTH_EUNKNOWN 7

Definition at line 57 of file UserInput.h.

#define USERINPUTH_ENOTSET 8

Definition at line 58 of file UserInput.h.

#define USERINPUTH_EDEBUG 9

Definition at line 59 of file UserInput.h.

#define USERINPUTH_EONECONFIG 10

Definition at line 60 of file UserInput.h.

#define USERINPUTH_ERECFORMAT 11

Definition at line 61 of file UserInput.h.

#define USERINPUTH_EXLAL 12

Definition at line 62 of file UserInput.h.

#define USERINPUTH_MSGENULL "Arguments contained an unexpected null pointer."

Definition at line 65 of file UserInput.h.

#define USERINPUTH_MSGENONULL "Output pointer is not NULL"

Definition at line 66 of file UserInput.h.

#define USERINPUTH_MSGEMEM "Out of memory"

Definition at line 67 of file UserInput.h.

#define USERINPUTH_MSGEOPT "Unknown command-line option encountered"

Definition at line 68 of file UserInput.h.

#define USERINPUTH_MSGENOUVARS "No user-variables have been registered!"

Definition at line 69 of file UserInput.h.

#define USERINPUTH_MSGECMDLARG "Illegal command-line argument"

Definition at line 70 of file UserInput.h.

#define USERINPUTH_MSGEUNKNOWN "Unknown user-variable"

Definition at line 71 of file UserInput.h.

#define USERINPUTH_MSGENOTSET "Required user-variable was not set"

Definition at line 72 of file UserInput.h.

#define USERINPUTH_MSGEDEBUG "lalDebugLevel can only be read before ANY mallocs(), even hidden.."

Definition at line 73 of file UserInput.h.

#define USERINPUTH_MSGEONECONFIG "Currently one ONE config-file can be specified using '@'"

Definition at line 74 of file UserInput.h.

#define USERINPUTH_MSGERECFORMAT "Unknown format for recording user-input"

Definition at line 75 of file UserInput.h.

#define USERINPUTH_MSGEXLAL "Failure in XLAL function"

Definition at line 76 of file UserInput.h.

#define LALregREALUserVar	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterREALUserVar((status)->statusPtr, #name, option, flag, help,&(uvar_ ## name)), status)

Definition at line 82 of file UserInput.h.

#define LALregINTUserVar	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterINTUserVar((status)->statusPtr, #name, option,flag, help,&(uvar_ ## name)), status)

Definition at line 85 of file UserInput.h.

#define LALregBOOLUserVar	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterBOOLUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)

Definition at line 88 of file UserInput.h.

#define LALregSTRINGUserVar	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterSTRINGUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)

Definition at line 91 of file UserInput.h.

#define LALregLISTUserVar	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterLISTUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)

Definition at line 94 of file UserInput.h.

#define LALregREALUserStruct	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterREALUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)), status)

Definition at line 98 of file UserInput.h.

#define LALregINTUserStruct	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterINTUserVar((status)->statusPtr, #name, option,flag, help, &(uvar-> name)), status)

Definition at line 101 of file UserInput.h.

#define LALregBOOLUserStruct	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterBOOLUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)

Definition at line 104 of file UserInput.h.

#define LALregSTRINGUserStruct	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterSTRINGUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)

Definition at line 107 of file UserInput.h.

#define LALregLISTUserStruct	(	status,
		name,
		option,
		flag,
		help	)	TRY(LALRegisterLISTUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)

Definition at line 110 of file UserInput.h.

Enumeration Type Documentation

enum UserVarState

State-flags: variable is optional, required, help, developer or was_set.

Enumerator:

UVAR_OPTIONAL	not required, and hasn't been set
UVAR_REQUIRED	we require the user to set this variable
UVAR_HELP	special variable: trigger output of help-string
UVAR_DEVELOPER	OPTIONAL and hidden in help-output at lalDebugLevel==0.
UVAR_SPECIAL	OPTIONAL and turns off checking of required variables (LALUserVarCheckRequired).
UVAR_WAS_SET	flag that this user-var has been set by user

Definition at line 115 of file UserInput.h.

enum UserVarLogFormat

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

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

Enumerator:

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 127 of file UserInput.h.

Function Documentation

NRCSID	(	USERINPUTH	,
		"$Id: UserInput.	h,
		v 1.23 2008/09/14 12:26:44 reinhard Exp $"
	)

void LALRegisterREALUserVar	(	LALStatus *	,
		const CHAR *	name,
		CHAR	optchar,
		UserVarState	flag,
		const CHAR *	helpstr,
		REAL8 *	cvar
	)

Definition at line 88 of file UserInput.c.

void LALRegisterINTUserVar	(	LALStatus *	,
		const CHAR *	name,
		CHAR	optchar,
		UserVarState	flag,
		const CHAR *	helpstr,
		INT4 *	cvar
	)

Definition at line 99 of file UserInput.c.

void LALRegisterBOOLUserVar	(	LALStatus *	,
		const CHAR *	name,
		CHAR	optchar,
		UserVarState	flag,
		const CHAR *	helpstr,
		BOOLEAN *	cvar
	)

Definition at line 110 of file UserInput.c.

void LALRegisterSTRINGUserVar	(	LALStatus *	,
		const CHAR *	name,
		CHAR	optchar,
		UserVarState	flag,
		const CHAR *	helpstr,
		CHAR **	cvar
	)

Definition at line 121 of file UserInput.c.

void LALRegisterLISTUserVar	(	LALStatus *	,
		const CHAR *	name,
		CHAR	optchar,
		UserVarState	flag,
		const CHAR *	helpstr,
		LALStringVector **	cvar
	)

Definition at line 132 of file UserInput.c.

void LALDestroyUserVars ( LALStatus * )

Free all memory associated with user-variable linked list.

Definition at line 200 of file UserInput.c.

void LALUserVarReadAllInput	(	LALStatus *	,
		int	argc,
		char *	argv[]
	)

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

Definition at line 767 of file UserInput.c.

void LALUserVarReadCmdline	(	LALStatus *	,
		int	argc,
		char *	argv[]
	)

Parse command-line into UserVariable array.

Definition at line 248 of file UserInput.c.

void LALUserVarReadCfgfile	(	LALStatus *	status,
		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

Definition at line 473 of file UserInput.c.

void LALUserVarHelpString	(	LALStatus *	,
		CHAR **	helpstring,
		const CHAR *	progname
	)

Assemble all help-info from uvars into a help-string.

Definition at line 571 of file UserInput.c.

void LALUserVarCheckRequired ( LALStatus * status )

Check that all required user-variables have been set successfully.

Print error if not

Definition at line 886 of file UserInput.c.

INT4 LALUserVarWasSet ( const void * cvar )

Has this user-variable been set by the user? return -1 on error, TRUE/FALSE otherwise.

Definition at line 858 of file UserInput.c.

void LALGetDebugLevel	(	LALStatus *	status,
		int	argc,
		char *	argv[],
		CHAR	optchar
	)

Handle the delicate setting of lalDebuglevel.

Note:: *NEVER* call this function after any LALMalloc/LALCalloc/LALRealloc have been used. A change of lalDebugLevel can then lead to inconsistencies in the LAL memory-checker. You should therefore call this function very early on in main(), before any LALMallocs ...

Definition at line 914 of file UserInput.c.

void LALUserVarGetLog	(	LALStatus *	status,
		CHAR **	logstr,
		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:

`[out]`	**outstr	the string containing the user-input record.
`[in]`	format	return as config-file or command-line

Definition at line 970 of file UserInput.c.

void LALUserVarGetProcParamsTable	(	LALStatus *	status,
		ProcessParamsTable **	out,
		CHAR *	progname
	)

Return user log as a process-params table.

Parameters:

`[out]`	**procPar	the output ProcessParamsTable
`[in]`	*progname	name of calling code

Definition at line 1062 of file UserInput.c.

Generated on Mon Oct 6 02:33:16 2008 for LAL by

1.5.2


Defines
#define	LALregREALUserVar(status, name, option, flag, help) TRY(LALRegisterREALUserVar((status)->statusPtr, #name, option, flag, help,&(uvar_ ## name)), status)
#define	LALregINTUserVar(status, name, option, flag, help) TRY(LALRegisterINTUserVar((status)->statusPtr, #name, option,flag, help,&(uvar_ ## name)), status)
#define	LALregBOOLUserVar(status, name, option, flag, help) TRY(LALRegisterBOOLUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)
#define	LALregSTRINGUserVar(status, name, option, flag, help) TRY(LALRegisterSTRINGUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)
#define	LALregLISTUserVar(status, name, option, flag, help) TRY(LALRegisterLISTUserVar((status)->statusPtr, #name, option, flag, help, &(uvar_ ## name)),status)
#define	LALregREALUserStruct(status, name, option, flag, help) TRY(LALRegisterREALUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)), status)
#define	LALregINTUserStruct(status, name, option, flag, help) TRY(LALRegisterINTUserVar((status)->statusPtr, #name, option,flag, help, &(uvar-> name)), status)
#define	LALregBOOLUserStruct(status, name, option, flag, help) TRY(LALRegisterBOOLUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)
#define	LALregSTRINGUserStruct(status, name, option, flag, help) TRY(LALRegisterSTRINGUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)
#define	LALregLISTUserStruct(status, name, option, flag, help) TRY(LALRegisterLISTUserVar((status)->statusPtr, #name, option, flag, help, &(uvar-> name)),status)
Error codes
#define	USERINPUTH_ENULL 1
#define	USERINPUTH_ENONULL 2
#define	USERINPUTH_EMEM 3
#define	USERINPUTH_EOPT 4
#define	USERINPUTH_ENOUVARS 5
#define	USERINPUTH_ECMDLARG 6
#define	USERINPUTH_EUNKNOWN 7
#define	USERINPUTH_ENOTSET 8
#define	USERINPUTH_EDEBUG 9
#define	USERINPUTH_EONECONFIG 10
#define	USERINPUTH_ERECFORMAT 11
#define	USERINPUTH_EXLAL 12
#define	USERINPUTH_MSGENULL "Arguments contained an unexpected null pointer."
#define	USERINPUTH_MSGENONULL "Output pointer is not NULL"
#define	USERINPUTH_MSGEMEM "Out of memory"
#define	USERINPUTH_MSGEOPT "Unknown command-line option encountered"
#define	USERINPUTH_MSGENOUVARS "No user-variables have been registered!"
#define	USERINPUTH_MSGECMDLARG "Illegal command-line argument"
#define	USERINPUTH_MSGEUNKNOWN "Unknown user-variable"
#define	USERINPUTH_MSGENOTSET "Required user-variable was not set"
#define	USERINPUTH_MSGEDEBUG "lalDebugLevel can only be read before ANY mallocs(), even hidden.."
#define	USERINPUTH_MSGEONECONFIG "Currently one ONE config-file can be specified using '@'"
#define	USERINPUTH_MSGERECFORMAT "Unknown format for recording user-input"
#define	USERINPUTH_MSGEXLAL "Failure in XLAL function"
Enumerations
enum	UserVarState { UVAR_OPTIONAL = 0, UVAR_REQUIRED = 1<<0, UVAR_HELP = 1<<1, UVAR_DEVELOPER = 1<<2, UVAR_SPECIAL = 1<<3, UVAR_WAS_SET = 1<<7 }
	State-flags: variable is optional, required, help, developer or was_set. More...
enum	UserVarLogFormat { UVAR_LOGFMT_CFGFILE, UVAR_LOGFMT_CMDLINE, UVAR_LOGFMT_PROCPARAMS, UVAR_LOGFMT_LAST }
	Format for logging User-input: configFile- or cmdLine-style. More...
Functions
	NRCSID (USERINPUTH,"$Id: UserInput.h,v 1.23 2008/09/14 12:26:44 reinhard Exp $")
void	LALRegisterREALUserVar (LALStatus , const CHAR name, CHAR optchar, UserVarState flag, const CHAR helpstr, REAL8 cvar)
void	LALRegisterINTUserVar (LALStatus , const CHAR name, CHAR optchar, UserVarState flag, const CHAR helpstr, INT4 cvar)
void	LALRegisterBOOLUserVar (LALStatus , const CHAR name, CHAR optchar, UserVarState flag, const CHAR helpstr, BOOLEAN cvar)
void	LALRegisterSTRINGUserVar (LALStatus , const CHAR name, CHAR optchar, UserVarState flag, const CHAR helpstr, CHAR *cvar)
void	LALRegisterLISTUserVar (LALStatus , const CHAR name, CHAR optchar, UserVarState flag, const CHAR helpstr, LALStringVector *cvar)
void	LALDestroyUserVars (LALStatus *)
	Free all memory associated with user-variable linked list.
void	LALUserVarReadAllInput (LALStatus , int argc, char argv[])
	Put all the pieces together, and basically does everything: get config-filename from cmd-line (if found), then interpret config-file and then the command-line.
void	LALUserVarReadCmdline (LALStatus , int argc, char argv[])
	Parse command-line into UserVariable array.
void	LALUserVarReadCfgfile (LALStatus , const CHAR cfgfile)
	Read config-variables from cfgfile and parse into input-structure.
void	LALUserVarHelpString (LALStatus , CHAR helpstring, const CHAR progname)
	Assemble all help-info from uvars into a help-string.
void	LALUserVarCheckRequired (LALStatus *)
	Check that all required user-variables have been set successfully.
INT4	LALUserVarWasSet (const void *cvar)
	Has this user-variable been set by the user? return -1 on error, TRUE/FALSE otherwise.
void	LALGetDebugLevel (LALStatus , int argc, char argv[], CHAR optchar)
	Handle the delicate setting of lalDebuglevel.
void	LALUserVarGetLog (LALStatus , CHAR *logstr, UserVarLogFormat format)
	Return a log-string representing the complete user-input.
void	LALUserVarGetProcParamsTable (LALStatus status, ProcessParamsTable out, CHAR progname)
	Return user log as a process-params table.