A class for storing information in a tree-like structure of key-value pairs. This class is used throughout the egspp class library for passing information to the various objects. More...

#include <egs_input.h>

Public Member Functions
	EGS_Input ()
	Create an empty property (no key and no value).

	EGS_Input (const EGS_Input &o)
	Copy constructor. More...

	EGS_Input (const string &name, const string &value="")
	Create an elementary property named name having a value value.

	~EGS_Input ()
	Destructor.

const char *	name () const
	Get the name of this property.

int	setContentFromFile (const char *fname)
	Set the property from the input file fname (which is considered to be an absolute file name) More...

int	setContentFromString (string &input)

int	addContentFromFile (const char *fname)
	Add the content of the file fname to this EGS_Input object. More...

int	addContentFromString (string &input)

EGS_Input *	takeInputItem (const string &key, bool self=true)
	Get the property named key. More...

EGS_Input *	getInputItem (const string &key) const
	Same as the previous function but now ownership remains with the EGS_Input object.

void	addInputItem (const EGS_Input &i)
	Add the input i to this property.

int	getInput (const string &key, vector< string > &values) const
	Assign values to an array of strings from an input identified by key. More...

int	getInput (const string &key, vector< EGS_Float > &values) const
	Assign values to an array of floats from an input identified by key. More...

int	getInput (const string &key, vector< int > &values) const
	Assign values to an array of integers from an input identified by key. More...

int	getInput (const string &key, string &value) const
	Assign values to a single string from an input identified by key. More...

int	getInput (const string &key, float &value) const
	Assign values to a float from an input identified by key. More...

int	getInput (const string &key, double &value) const
	Assign values to an integer from an input identified by key. More...

int	getInput (const string &key, int &value) const
	Assign values to a double from an input identified by key. More...

int	getInput (const string &key, EGS_I64 &value) const
	Assign values to a 64 bit integer from an input identified by key. More...

int	getInput (const string &key, const vector< string > &allowed, int def=0, bool *found=0) const
	Get input from a range of allowed values. More...

bool	isA (const string &key) const

void	print (int nind, ostream &)
	Used for debugging purposes.

Static Public Member Functions
static bool	compare (const string &s1, const string &s2)

Detailed Description

A class for storing information in a tree-like structure of key-value pairs. This class is used throughout the egspp class library for passing information to the various objects.

An EGS_Input object contains a tree-like structure of elementary or composite properties, which are instances of EGS_Input. In the simplest possible scenario an EGS_Input object is simply the combination of a key and a corresponding value, i.e

key = value

This is referred to as an elementary property. A composite property (or EGS_Input object) has several elementary or composite properties, i.e.

 key
     key1 = value1
     key2 = value2
     key3
         key3a = value3a
         key3b = value3b
     key4 = value4
     ...

The name of an EGS_Input object can be obtained using the name() function. A sub-property with name Name can be obtained using getInputItem() or takeInputItem(). Given an elementary property, one can use the various getInput() functions to parse the value as a single integer, floating point number or string or as an array of integers, floating point numbers or strings. The content of an EGS_Input object can be set from a file using setContentFromFile() or addContentFromFile() or from a string using setContentFromString() or addContentFromString(). These 4 methods use the following syntax rules to put the content of the file or string into the tree-like key-value structure described above:

Input following a # character is ignored until the end of a line
The new line character delimits between subsequent key-value pairs
If a value is to be continued on the next line, a line continuation with a trailing comma is required
Elementary properties are of the form
key = value
Composite properties are defined using
```
 :start some_key:
     subkey1 = value1
     subkey2 = value2
     ...
 :stop some_key:
```
where some_key vecomes the name (or key) of the composite property

Composite properties can be nested, e.g.

 :start key1:
     :start key2:
         subkey2 = value
         subkey3 = value
     :stop key2:
     key 3 = value
 :stop key1:

Note: the indentation is not required, it is only used for better visibility

Since the 2008 version of the C++ class library it is possible to include the content of some other file into the input file using

include file = some_file

In this way one can define e.g. the geometry in a separate file and then include it into the input file for different runs. Note that the file is searched for in the current working directory, so for batch execution one has to add the absolute path to the file name.

Also since the 2008 version of the C++ class library one has the ability to use so called input loops. Input loops are useful for saving typing for repetitive input where only relatively little changes. To do so, one encloses the to be repeated input between :start input loop: and :stop input loop: delimeters as follows:

:start input loop:
    loop count = N
    loop variable = 0 var1 v1min v1delta
    loop variable = 1 var2 v3min v3delta
    loop variable = 2 var3 list_of_N_string_values
    some other input
:stop input loop:

Then, everything in the input loop block except for the definition of loop count and loop variables will be repeated N times, replacing all occurences of $(var1) with v1min+v1delta*i, of $(var2) with v2min+v2delta*i, and of $(var3) with the i'th string provided in the list of strings. The first integer in the definition of a loop variable specifies its type (0 = integer, 1 = float, 2 = list of strings). Note that input loops can also be nested. To give a concrete example, consider

:start input loop:
    loop count = 3
    loop variable = 0 var1 1 1
    loop varaible = 2 var2 Blake Ernesto Iwan
    :start input loop:
        loop count = 2
        loop variable = 0 var3 10 5
        $(var2) = $(var1) $(var3)
    :stop input loop:
 :stop input loop:

will get expanded to

Blake = 1 10
Blake = 1 15
Ernesto = 2 10
Ernesto = 2 15
Iwan = 3 10
Iwan = 3 15

Todo:: Add the possibility to replace values with previously defined values using e.g. make syntax: media = $(air_medium) $(water_medium) should initiate a search for a previous definition of air_medium and water_medium and should replace them, if such definitions exist. This would be useful for e.g. easier change of the media in a geometry definition if one wanted to use different PEGS data sets.

Todo:: Extend the class to allow the definition of a required input by defining which keys are required or optional. This would need the possibility of grouping keys when alternative definitions are possible.

Examples:: geometry/egs_box/egs_box.cpp, sources/egs_point_source/egs_point_source.cpp, and tutor7pp.cpp.

Definition at line 182 of file egs_input.h.

Constructor & Destructor Documentation

EGS_Input::EGS_Input ( const EGS_Input & o )

Copy constructor.

Note: this uses a shallow copy so that changes made to o also affect the new object and vice versa.

Definition at line 182 of file egs_input.cpp.

Member Function Documentation

int EGS_Input::setContentFromFile ( const char * fname )

Set the property from the input file fname (which is considered to be an absolute file name)

Any previous content is discarded and then the input file is read and parsed according to the rules described above.

See Also: setContentFromString(), addContentFromFile(), addContentFromString()

Definition at line 200 of file egs_input.cpp.

Referenced by EGS_Application::EGS_Application(), and EGS_SimpleApplication::EGS_SimpleApplication().

int EGS_Input::setContentFromString ( string & input )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 206 of file egs_input.cpp.

Referenced by EGS_BaseGeometry::setName().

int EGS_Input::addContentFromFile ( const char * fname )

Add the content of the file fname to this EGS_Input object.

See Also: setContentFromFile(), setContentFromString(), addContentFromString()

Definition at line 212 of file egs_input.cpp.

int EGS_Input::addContentFromString ( string & input )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 219 of file egs_input.cpp.

EGS_Input * EGS_Input::takeInputItem	(	const string &	key,
		bool	self = `true`
	)

Get the property named key.

The item is removed from the object and ownership is transfered to the caller, who is responsible for deleting the item. If self is true, it is first checked if the object itself is named key and if yes, the object itself is returned and the current object becomes an empty property. If self is false or if the object name is not key, this function checks if the object contains a child property named key and if yes, returns it. Otherwise null is returned.

Examples:: tutor7pp.cpp.

Definition at line 226 of file egs_input.cpp.

References takeInputItem().

Referenced by createGeometry(), EGS_BaseGeometry::createGeometry(), EGS_ObjectFactory::createObjects(), EGS_RandomGenerator::createRNG(), EGS_BaseSpectrum::createSpectrum(), EGS_AEnvelope::createTransforms(), EGS_CollimatedSource::EGS_CollimatedSource(), EGS_DynamicSource::EGS_DynamicSource(), EGS_FanoSource::EGS_FanoSource(), EGS_IsotropicSource::EGS_IsotropicSource(), EGS_ParallelBeam::EGS_ParallelBeam(), EGS_RunControl::EGS_RunControl(), EGS_SimpleApplication::EGS_SimpleApplication(), EGS_SourceCollection::EGS_SourceCollection(), EGS_TransformedSource::EGS_TransformedSource(), EGS_GeometryTester::getGeometryTester(), EGS_AffineTransform::getTransformation(), volcor::VCOptions::setBoundsShape(), EGS_BaseGeometry::setBScaling(), EGS_BaseGeometry::setLabels(), EGS_BaseGeometry::setMedia(), EGS_NDGeometry::setMedia(), EGS_BaseGeometry::setName(), EGS_BaseGeometry::setRelativeRho(), and takeInputItem().

int EGS_Input::getInput	(	const string &	key,
		vector< string > &	values
	)		const

Assign values to an array of strings from an input identified by key.

Returns 0 on success or an error code on failure. The function fails if the object is not named key and does not have a child property named key (return value is -1), or if a property named key exists but an error occured while reading the value as an array of strings (returns 1 or 2).

Examples:: geometry/egs_box/egs_box.cpp, sources/egs_point_source/egs_point_source.cpp, and tutor7pp.cpp.

Definition at line 338 of file egs_input.cpp.

Referenced by EGS_BaseGeometry::createGeometry(), EGS_PointShape::createObject(), EGS_BoxShape::createObject(), EGS_SphereShape::createObject(), EGS_CylinderShape::createObject(), EGS_ObjectFactory::createObjects(), EGS_RandomGenerator::createRNG(), EGS_ObjectFactory::createSingleObject(), EGS_BaseSpectrum::createSpectrum(), EGS_BaseSimpleSource::EGS_BaseSimpleSource(), EGS_BeamSource::EGS_BeamSource(), EGS_CollimatedSource::EGS_CollimatedSource(), EGS_DynamicSource::EGS_DynamicSource(), EGS_FanoSource::EGS_FanoSource(), EGS_IsotropicSource::EGS_IsotropicSource(), EGS_ParallelBeam::EGS_ParallelBeam(), EGS_PhspSource::EGS_PhspSource(), EGS_PointSource::EGS_PointSource(), EGS_RadionuclideSource::EGS_RadionuclideSource(), EGS_RunControl::EGS_RunControl(), EGS_SourceCollection::EGS_SourceCollection(), EGS_TransformedSource::EGS_TransformedSource(), EGS_GeometryTester::getGeometryTester(), volcor::getShapeVolume(), EGS_AffineTransform::getTransformation(), IAEA_PhspSource::IAEA_PhspSource(), EGS_BaseGeometry::setBoundaryTolerance(), EGS_BaseGeometry::setBScaling(), volcor::VCOptions::setDensity(), EGS_BaseGeometry::setLabels(), EGS_BaseGeometry::setMedia(), EGS_NDGeometry::setMedia(), volcor::VCOptions::setMode(), EGS_Object::setName(), EGS_BaseGeometry::setName(), EGS_BaseGeometry::setRelativeRho(), volcor::VCOptions::setRNG(), and volcor::VCOptions::setVCFile().

int EGS_Input::getInput	(	const string &	key,
		vector< EGS_Float > &	values
	)		const

Assign values to an array of floats from an input identified by key.

See Also: getInput(const string &,vector<string> &)

Definition at line 342 of file egs_input.cpp.

int EGS_Input::getInput	(	const string &	key,
		vector< int > &	values
	)		const

Assign values to an array of integers from an input identified by key.

See Also: getInput(const string &,vector<string> &)

Definition at line 346 of file egs_input.cpp.

int EGS_Input::getInput	(	const string &	key,
		string &	value
	)		const

Assign values to a single string from an input identified by key.

Returns 0 on success or an error code on failure. The function fails if the object is not named key and does not have a child property named key (return value is -1), or if a property named key exists but an error occured while reading the value as a string (returns 1 or 2).

Definition at line 384 of file egs_input.cpp.

int EGS_Input::getInput	(	const string &	key,
		float &	value
	)		const

Assign values to a float from an input identified by key.

See Also: getInput(const string &,string &)

Definition at line 403 of file egs_input.cpp.

int EGS_Input::getInput	(	const string &	key,
		double &	value
	)		const

Assign values to an integer from an input identified by key.

See Also: getInput(const string &,string &)

Definition at line 407 of file egs_input.cpp.

int EGS_Input::getInput	(	const string &	key,
		int &	value
	)		const

Assign values to a double from an input identified by key.

See Also: getInput(const string &,string &)

Definition at line 411 of file egs_input.cpp.

int EGS_Input::getInput	(	const string &	key,
		EGS_I64 &	value
	)		const

Assign values to a 64 bit integer from an input identified by key.

See Also: getInput(const string &,string &)

Definition at line 419 of file egs_input.cpp.

int EGS_Input::getInput	(	const string &	key,
		const vector< string > &	allowed,
		int	def = `0`,
		bool *	found = `0`
	)		const

Get input from a range of allowed values.

If the input was not found or some other error occured, this function returns the integer specified by def, otherwise it returns the index of the input in the array of allowed values allowed. If found is not null, it is set to true if everything worked ok and to false, if some error occured.

Definition at line 465 of file egs_input.cpp.

bool EGS_Input::isA ( const string & key ) const

Is this a property named key?

Definition at line 278 of file egs_input.cpp.

Referenced by EGS_BaseGeometry::createGeometry(), EGS_ObjectFactory::createObjects(), EGS_RandomGenerator::createRNG(), EGS_BaseSpectrum::createSpectrum(), EGS_GeometryTester::getGeometryTester(), EGS_AffineTransform::getTransformation(), and EGS_BaseGeometry::setMedia().

bool EGS_Input::compare	(	const string &	s1,
		const string &	s2
	)

static

Compare the strings s1 and s2.

Comparison is case insensitive and also all white space is removed from s1 and s2 before performing the comparison.

Definition at line 1170 of file egs_input.cpp.

Referenced by EGS_RandomGenerator::createRNG(), EGS_ObjectFactory::createSingleObject(), EGS_BaseSpectrum::createSpectrum(), EGS_GeometryTester::getGeometryTester(), and volcor::VCOptions::setRNG().

The documentation for this class was generated from the following files:

/home/rwtownson/EGSnrc/HEN_HOUSE/egs++/egs_input.h
/home/rwtownson/EGSnrc/HEN_HOUSE/egs++/egs_input.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation