Header ConfigFile.h

Detailed Description

Module for general parsing of simple ASCII-based config-files.

Author

Reinhard Prix

Description

This module provides routines for reading formatted config-files containing definitions of the form variable = value. The general syntax is somewhat similar to the one provided by the perl-module ConfigParser (cf. http://www.python.org/doc/current/lib/module-ConfigParser.html)

Comments are allowed using either '#' or %. You can also use line-continuation using a '\' at the end of the line. Also note that comment-signs '#%' within double-quotes "..." are not treated as comment-characters. Semi-colons ; are ignored, but can be used to separate several assignments on the same line. The general syntax is best illustrated using a simple example:

# comment line
var1 = 1.0; var2 = 3.1;   ## several assignments on a line, separated by ';'
somevar = some text.\
You can also use\
line-continuation
var3 = 4      # whatever that means
note = "this is also possible, and # here does nothing"
a_switch = true  #possible values: 0,1,true,false,yes,no, case insensitive
...

Note that TABS generally get replaced by a single space, which can be useful in the case of line-continuation (see example). All leading and trailing spaces in are ignore (except within double-quotes).

The general approach of reading from such a config-file, is to first call XLALParseDataFile() which loads and pre-parses the contents of the config-file into the structure LALParsedDataFile. Then one can read in config-variables either using one of the type-strict custom-wrappers XLALReadConfig<TYPE>Variable() or the general-purpose reading function XLALReadConfigVariable().

A boolean variable read by XLALReadConfigBOOLEANVariable() can have any of the values {1, 0, yes, no, true, false}, where the comparison is done case-insensitively, i.e. you can also use 'True' or 'FALSE'....

If one wishes a tight sytnax for the config-file, one can check that there are no illegal entries in the config-file. This is done by checking at the end that all config-file entries have been successfully parsed, using: XLALConfigFileGetUnreadEntries()

The configfile-data should be freed at the end using XLALDestroyParsedDataFile().

Notes

XLALReadConfigSTRINGVariable() read the rest of the logical line (excluding comments) as a string, and removes any surrounding quotes \' or ".

Note

instead of using these functions directly, it might be more convenient to use the Header UserInput.h.

Prototypes
int	XLALParseDataFile (LALParsedDataFile **cfgdata, const CHAR *fname)
	Parse an ASCII data-file into a pre-cleaned array of lines. More...
int	XLALParseDataFileContent (LALParsedDataFile **cfgdata, const CHAR *string)
void	XLALDestroyParsedDataFile (LALParsedDataFile *cfgdata)
	Free memory associated with a LALParsedDataFile structure. More...
int	XLALConfigSectionExists (const LALParsedDataFile *, const CHAR *)
	Function to determine whether a given section secName exists in the parsed config-file contents cfgdata. More...
LALStringVector *	XLALListConfigFileSections (const LALParsedDataFile *cfgdata)
	Function to find all sections in given config-file contents cfgdata. More...
UINT4Vector *	XLALConfigFileGetUnreadEntries (const LALParsedDataFile *cfgdata)
	Return a list of unread config-file entries, NULL if none found (without error). More...
	DECLARE_XLALREADCONFIGVARIABLE (STRING, CHAR *)
	DECLARE_XLALREADCONFIGVARIABLE (BOOLEAN, BOOLEAN)
	DECLARE_XLALREADCONFIGVARIABLE (INT4, INT4)
	DECLARE_XLALREADCONFIGVARIABLE (INT8, INT8)
	DECLARE_XLALREADCONFIGVARIABLE (UINT4, UINT4)
	DECLARE_XLALREADCONFIGVARIABLE (UINT8, UINT8)
	DECLARE_XLALREADCONFIGVARIABLE (REAL8, REAL8)
	DECLARE_XLALREADCONFIGVARIABLE (STRINGVector, LALStringVector *)
	DECLARE_XLALREADCONFIGVARIABLE (EPOCH, LIGOTimeGPS)
	DECLARE_XLALREADCONFIGVARIABLE (RAJ, REAL8)
	DECLARE_XLALREADCONFIGVARIABLE (DECJ, REAL8)

Data Structures
struct	LALParsedDataFile
	This structure is returned by XLALParseDataFile() and holds the contents of an ASCII data-file in a pre-parsed form, namely stripped from all comments ('#', '%'), spurious whitespaces, and separated into lines (taking into account line-continuation by '\' at the end of lines). More...

Macros
#define	DECLARE_XLALREADCONFIGVARIABLE(TYPE, CTYPE)    int XLALReadConfig ##TYPE## Variable ( CTYPE *varp, LALParsedDataFile *cfgdata, const CHAR *secName, const CHAR *varName, BOOLEAN *wasRead )

Function Documentation

XLALParseDataFile()

int XLALParseDataFile	(	LALParsedDataFile **	cfgdata,
		const CHAR *	path
	)

Parse an ASCII data-file into a pre-cleaned array of lines.

The cleaning gets rid of comments ('#', '%'), empty lines, and performs line-continuation if '\' is found at EOL

NOTE: This function can transparently detect and read gzip-compressed data-files, independently of filename-extension

NOTE2: allows passing of file-contents directly instead of filename to read by passing a string like "{ file-contents }" instead of a file-path, ie if first character == '{' and last character == '}' This is useful to allow ascii-file user inputs to be transparently passed as filenames or direct contents

Parameters

[out]	cfgdata	pre-parsed data-file lines
[in]	path	file-path of config-file to be read

Definition at line 65 of file ConfigFile.c.

XLALParseDataFileContent()

int XLALParseDataFileContent	(	LALParsedDataFile **	cfgdata,
		const CHAR *	string
	)

Parameters

[out]	cfgdata	pre-parsed data-file lines
[in]	string	string-contents of config-file: can get modified!

Definition at line 95 of file ConfigFile.c.

XLALDestroyParsedDataFile()

void XLALDestroyParsedDataFile

(

LALParsedDataFile *

cfgdata

)

Free memory associated with a LALParsedDataFile structure.

Parameters

[in]

cfgdata

config-file data

Definition at line 147 of file ConfigFile.c.

XLALConfigSectionExists()

int XLALConfigSectionExists	(	const LALParsedDataFile *	cfgdata,
		const CHAR *	secName
	)

Function to determine whether a given section secName exists in the parsed config-file contents cfgdata.

Note

: this function tolerates NULL input as secName, cfgdata, or cfgdata->lines, in which case the answer is simply 'FALSE'.

NOTE2: quite inefficient implementation, re-creates table of content each time it's called however this function also doesn't seem to be used right now and should probably be removed?

Parameters

[in]	cfgdata	pre-parsed config-data
[in]	secName	section-name to read

Definition at line 172 of file ConfigFile.c.

XLALListConfigFileSections()

LALStringVector* XLALListConfigFileSections

(

const LALParsedDataFile *

cfgdata

)

Function to find all sections in given config-file contents cfgdata.

A section start is defined by a string "[ section-name ]" found at the beginning of a line The first non-section part of a config-file is referred to as the "default" section, which is included in the returned list of section-names provided it is not empty.

Parameters

[in]

cfgdata

pre-parsed config-data

Definition at line 214 of file ConfigFile.c.

XLALConfigFileGetUnreadEntries()

UINT4Vector* XLALConfigFileGetUnreadEntries

(

const LALParsedDataFile *

cfgdata

)

Return a list of unread config-file entries, NULL if none found (without error).

Parameters

[in]

cfgdata

config-file data

Definition at line 398 of file ConfigFile.c.

DECLARE_XLALREADCONFIGVARIABLE() [1/11]

DECLARE_XLALREADCONFIGVARIABLE	(	STRING	,
		CHAR *
	)

DECLARE_XLALREADCONFIGVARIABLE() [2/11]

DECLARE_XLALREADCONFIGVARIABLE	(	BOOLEAN	,
		BOOLEAN
	)

DECLARE_XLALREADCONFIGVARIABLE() [3/11]

DECLARE_XLALREADCONFIGVARIABLE	(	INT4	,
		INT4
	)

DECLARE_XLALREADCONFIGVARIABLE() [4/11]

DECLARE_XLALREADCONFIGVARIABLE	(	INT8	,
		INT8
	)

DECLARE_XLALREADCONFIGVARIABLE() [5/11]

DECLARE_XLALREADCONFIGVARIABLE	(	UINT4	,
		UINT4
	)

DECLARE_XLALREADCONFIGVARIABLE() [6/11]

DECLARE_XLALREADCONFIGVARIABLE	(	UINT8	,
		UINT8
	)

DECLARE_XLALREADCONFIGVARIABLE() [7/11]

DECLARE_XLALREADCONFIGVARIABLE	(	REAL8	,
		REAL8
	)

DECLARE_XLALREADCONFIGVARIABLE() [8/11]

DECLARE_XLALREADCONFIGVARIABLE	(	STRINGVector	,
		LALStringVector *
	)

DECLARE_XLALREADCONFIGVARIABLE() [9/11]

DECLARE_XLALREADCONFIGVARIABLE	(	EPOCH	,
		LIGOTimeGPS
	)

DECLARE_XLALREADCONFIGVARIABLE() [10/11]

DECLARE_XLALREADCONFIGVARIABLE	(	RAJ	,
		REAL8
	)

DECLARE_XLALREADCONFIGVARIABLE() [11/11]

DECLARE_XLALREADCONFIGVARIABLE	(	DECJ	,
		REAL8
	)

Macro Definition Documentation

DECLARE_XLALREADCONFIGVARIABLE

#define DECLARE_XLALREADCONFIGVARIABLE	(		TYPE,
			CTYPE
	)		int XLALReadConfig ##TYPE## Variable ( CTYPE *varp, LALParsedDataFile *cfgdata, const CHAR *secName, const CHAR *varName, BOOLEAN *wasRead )

Definition at line 124 of file ConfigFile.h.