Factory / SmartPointee::Subcontractor_t interface. More...

#include <GyotoFactoryMessenger.h>

Public Member Functions
	FactoryMessenger (Gyoto::Factory , xercesc::DOMElement )
	Constructor called before subcontracting.

	FactoryMessenger (const FactoryMessenger &parent, std::string)
	Constructor called before fillElement.

void	reset ()
	Get back to first parameter.

SmartPointer< Metric::Generic >	metric ()
	Build and get the Metric described in this XML file. More...

SmartPointer< Screen >	screen ()
	Build and get the Screen described in this XML file. More...

SmartPointer< Photon >	photon ()
	Build and get the Photon described in this XML file. More...

SmartPointer< Astrobj::Generic >	astrobj ()
	Build and get the Astrobj described in this XML file. More...

int	getNextParameter (std::string name, std::string content, std::string *unit=NULL)
	Get name and value of next parameter. More...

std::string	getSelfAttribute (std::string attrname) const
	Get attribute of FactoryMessenger::element_. More...

std::string	getAttribute (std::string attrname) const
	Get attribute of a last retrieved parameter. More...

std::string	getFullContent () const
	Get full content of element_. More...

FactoryMessenger *	getChild () const
	Get another FactoryMessenger instance initialized to current child. More...

std::string	fullPath (std::string relpath)
	Transform path into full path specification. More...

void	metric (SmartPointer< Metric::Generic >)
	Set the Metric. More...

void	astrobj (SmartPointer< Astrobj::Generic >)
	Set the Astrobj. More...

void	screen (SmartPointer< Screen >)
	Set the Screen. More...

void	setParameter (std::string name)
	Output parameter. More...

void	setParameter (std::string name, double value)
	Output parameter. More...

void	setParameter (std::string name, long int value)
	Output parameter. More...

void	setParameter (std::string name, unsigned int value)
	Output parameter. More...

void	setParameter (std::string name, unsigned long value)
	Output parameter. More...

void	setParameter (std::string name, int value)
	Output parameter. More...

void	setParameter (std::string name, std::string value)
	Output parameter. More...

void	setParameter (std::string name, double val[], size_t n, FactoryMessenger **child=NULL)
	Output an array of parameters. More...

void	setParameter (std::string name, std::vector< double > const &val, FactoryMessenger **child=NULL)

void	setParameter (std::string name, std::vector< unsigned long > const &val, FactoryMessenger **child=NULL)
	Output a vector of parameters.

void	setSelfAttribute (std::string attrname, std::string value)
	Set attribute in FactoryMessenger::element_. More...

void	setSelfAttribute (std::string attrname, unsigned long value)
	Set attribute in FactoryMessenger::element_. More...

void	setSelfAttribute (std::string attrname, unsigned int value)
	Set attribute in FactoryMessenger::element_. More...

void	setSelfAttribute (std::string attrname, double value)
	Set attribute in FactoryMessenger::element_. More...

void	setFullContent (std::string value)
	Low level, prefer setParameter() More...

FactoryMessenger *	makeChild (std::string name)
	Create child FactoryMessenger. More...

Static Public Member Functions
static size_t	parseArray (std::string src, double dst[], size_t max_tokens)
	Parse string into array. More...

static std::vector< double >	parseArray (std::string src)
	Parse string into array. More...

static std::vector< unsigned long >	parseArrayULong (std::string src)
	Parse string into array. More...

Private Attributes
Gyoto::Factory *	employer_
	The Factory that sent this messenger.

xercesc::DOMElement *	element_
	The XML element concerned by this transaction.

xercesc::DOMNodeList *	children_
	The children of the XML element concerned by this transaction.

XMLSize_t	nodeCount_
	The number of children of the XML element concerned by this transaction.

XMLSize_t	curNodeIndex_
	Current child.

Detailed Description

Factory / SmartPointee::Subcontractor_t interface.

A FactoryMessenger instance is like an employee passing messages between its employer (the Factory) and a subcontractor (a function of the SmartPointee::Subcontractor_t type).

The FactoryMessenger also communicate with the fillElement method of some classes (Astrobj::Generic::fillElement(), Metric::Generic::fillElement(), Spectrum::Generic::fillElement()).

A subcontractor function typically loops calling getNextParameter() to read all the parameters provided for it in an XML file. If BASE is one of Astrobj, Metric or Spectrum, and MyClass is an implementation of BASE::Generic, the subcontractor static member function often looks like this:

 SmartPointer<Gyoto::BASE::Generic> MyClass::Subcontractor(Gyoto::FactoryMessenger *messenger) {
 SmartPointer<Gyoto::BASE::MyClass> deliverable = new MyClass();
 while (messenger->getNextParameter(name, content) {
  if (name=="SomeProperty") deliverable -> setSomeProperty(content);
  else if (name=="AnotherProperty") deliverable -> setAnotherProperty(content);
 }
 return deliverable;
}

Other get* methods are provided to cope with more complex syntax (e.g. when XML attributes are used, as in <ParameterName attribute="attrvalue">ParameterValue</ParameterName>

Conversely, the Factory asks certain Gyoto classes through their fillElement() method how they should be printed or saved to an XML file. Those fillElement() methods use the FactoryMessenger::set*() methods (in particular setParameter()) as well as, occasionally, makeChild() to describe themselves to the Factory.

Member Function Documentation

◆ astrobj() [1/2]

SmartPointer<Astrobj::Generic> Gyoto::FactoryMessenger::astrobj ( )

Build and get the Astrobj described in this XML file.

An Gyoto XML file may contain at most a single Astrobj section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call astrobj() to find and interpret the Astrobj section.

◆ astrobj() [2/2]

void Gyoto::FactoryMessenger::astrobj ( SmartPointer< Astrobj::Generic > )

Set the Astrobj.

Same as metric(), but for the Astrobj.

◆ fullPath()

std::string Gyoto::FactoryMessenger::fullPath ( std::string relpath )

Transform path into full path specification.

This function takes a relative path (e.g. ../foo/bar.data) and transforms it into a full path (starting with "/"). It is not guaranteed to be portable (we assume that the path separator is "/" and that absolute paths start with "/").

Parameters

relpath path relative to the directory where the XML file on which the Factory works is located.

Returns: fullpath at full path specification to the same point pon the file-system.

◆ getAttribute()

std::string Gyoto::FactoryMessenger::getAttribute ( std::string attrname ) const

Get attribute of a last retrieved parameter.

For instance

<ParameterName attrname="attrvalue">ParameterContent</ParameterName>

Parameters

attrname name of the attribute

Returns: attrvalue

◆ getChild()

FactoryMessenger* Gyoto::FactoryMessenger::getChild ( ) const

Get another FactoryMessenger instance initialized to current child.

If one of the FactoryMessenger::children_ is complex (for instance the complete description of a Gyoto::Spectrum), it is possible to initialize a new FactoryMessenger and call the correct subcontractor:

SmartPointer<Spectrum::Generic> spectrum = NULL;
while (messenger->getNextParameter(name, content) {
 if (name=="Spectrum") {
  content = messenger->getAttribute("kind");
  FactoryMessenger* child = messenger->getChild();
  deliverable->spectrum( (*Spectrum::getSubcontractor(content))(child) );
  delete child;
 }
}

The child is allocated with new and must be deleted after use.

◆ getFullContent()

std::string Gyoto::FactoryMessenger::getFullContent ( ) const

Get full content of element_.

In exceptional circumstances, it may be necessary to get the entire text content of the topmost element FactoryMessenger::element_ instead or getting only the individual FactoryMessenger::children_ .

For instance a Spectrometer description looks like this:

and the Spectrometer builder uses getFullContent() to retrieve the spectral boundaries (2.0e-6 and 2.4e-6 here).

◆ getNextParameter()

int Gyoto::FactoryMessenger::getNextParameter	(	std::string *	name,
		std::string *	content,
		std::string *	unit = `NULL`
	)

Get name and value of next parameter.

On each call, return a pair name-content of one of the children_. Usually, "name" is the name of a parameter and "content" is the string representation of the corresponding value. For instance:

<Name>Content</Name>

Parameters

name	upon output, name of the child
content	of the child
unit=	propertty of the child

Returns: 1 if there remains parameters to retrieve, 0 otherwise.

◆ getSelfAttribute()

std::string Gyoto::FactoryMessenger::getSelfAttribute ( std::string attrname ) const

Get attribute of FactoryMessenger::element_.

For instance a Spectrometer description looks like this

and the Spectrometer builder uses getSelfAttribute() to retrieve the attributes "kind" and "nsamples".

Parameters

attrname name of the attribute

Returns: attrvalue

◆ makeChild()

FactoryMessenger* Gyoto::FactoryMessenger::makeChild ( std::string name )

Create child FactoryMessenger.

To be used from fillElement() methods. For instance, the Star::fillElement() method calls makeChild() to save the Star's Spectrum and Opacity members somewhat like this:

FactoryMessenger * child;
child = messenger-> makeChild("Spectrum");
spectrum_ -> fillElement(child);
delete child;
child = messenger-> makeChild("Opacity");
opacity_ -> fillElement(child);
delete child;
child=NULL;

The child messenger is allocated with new, you need to delete it after use.

◆ metric() [1/2]

SmartPointer<Metric::Generic> Gyoto::FactoryMessenger::metric ( )

Build and get the Metric described in this XML file.

An Gyoto XML file may contain at most a single Metric section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call metric() to find and interpret the Metric section.

◆ metric() [2/2]

void Gyoto::FactoryMessenger::metric ( SmartPointer< Metric::Generic > )

Set the Metric.

At most one Metric section may be present in a give Gyoto XML file.

When an object's fillElement() method is called, if this object is connected to a Metric, it should call metric() with this Metric. Very often, the Metric will already have been set previously. The Factory will check that all the objects in the hierarchy are attached to the same Metric instance, and save this instance only once. Trying to set the Metric to something else than the already set Metric instance is an error condition.

To make things clearer: Assume "scenery" is a fully filled Scenery. scenery->fillElement(messenger) will call:

messenger->metric(Scenery::gg_)
messenger->screen(Scenery::screen_)
messenger->astrobj(Scenery::obj_);

The Factory will then call screen_->fillElement(child_messenger) and obj_->fillElement(child_messenger), each of which will also call metric(). If the same Metric is connected to the Astrobj, to the Screen and to the Scenery, all is well. Else, you have a bug to fix.

◆ parseArray() [1/2]

static size_t Gyoto::FactoryMessenger::parseArray	(	std::string	src,
		double	dst[],
		size_t	max_tokens
	)

static

Parse string into array.

Parse at most max_tokens tokens from string src into pre-allocated array dst. Returns the number of tokens actually found (interpreted using atof). dst must be at least of size max_tokens.

◆ parseArray() [2/2]

static std::vector<double> Gyoto::FactoryMessenger::parseArray ( std::string src )

static

Parse string into array.

Parse tokens from string src, returns them into a std::vector<double>.

◆ parseArrayULong()

static std::vector<unsigned long> Gyoto::FactoryMessenger::parseArrayULong ( std::string src )

static

Parse string into array.

Parse tokens from string src, returns them into a std::vector<unsigned long>.

◆ photon()

SmartPointer<Photon> Gyoto::FactoryMessenger::photon ( )

Build and get the Photon described in this XML file.

An Gyoto XML file may contain at most a single Photon section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call photon() to find and interpret the Photon section.

◆ screen() [1/2]

SmartPointer<Screen> Gyoto::FactoryMessenger::screen ( )

Build and get the Screen described in this XML file.

An Gyoto XML file may contain at most a single Screen section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call screen() to find and interpret the Screen section.

◆ screen() [2/2]

void Gyoto::FactoryMessenger::screen ( SmartPointer< Screen > )

Set the Screen.

Same as metric(), but for the Screen.

◆ setFullContent()

void Gyoto::FactoryMessenger::setFullContent ( std::string value )

Low level, prefer setParameter()

Exceptionnaly, a class instance may be best described by setting the entire content of the corresponding element than by setting a bunch of "parameters". This is the case of the spectrometer, which sets a couple of attributes and reserves the full content for the spectral boundaries (see Spectrometer::fillElement()).

◆ setParameter() [1/8]

void Gyoto::FactoryMessenger::setParameter ( std::string name )

Output parameter.

Create child XML element of the form

<name/>

for instance when "name" is boolean (present or absent), or only takes attributes (see FactoryMessenger::setAttribute()). As an example, Astrobj::Generic::fillElement() uses setParameter() to set either Opticallythin or OpticallyThick.

◆ setParameter() [2/8]

void Gyoto::FactoryMessenger::setParameter	(	std::string	name,
		double	value
	)

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

◆ setParameter() [3/8]

void Gyoto::FactoryMessenger::setParameter	(	std::string	name,
		long int	value
	)

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

◆ setParameter() [4/8]

void Gyoto::FactoryMessenger::setParameter	(	std::string	name,
		unsigned int	value
	)

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

◆ setParameter() [5/8]

void Gyoto::FactoryMessenger::setParameter	(	std::string	name,
		unsigned long	value
	)

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

◆ setParameter() [6/8]

void Gyoto::FactoryMessenger::setParameter	(	std::string	name,
		int	value
	)

Output parameter.

Convert value to string "svalue" and create an XML child element of the form

<name>svalue</name>

◆ setParameter() [7/8]

void Gyoto::FactoryMessenger::setParameter	(	std::string	name,
		std::string	value
	)

Output parameter.

Create an XML child element of the form

<name>value</name>

◆ setParameter() [8/8]

void Gyoto::FactoryMessenger::setParameter	(	std::string	name,
		double	val[],
		size_t	n,
		FactoryMessenger **	child = `NULL`
	)

Output an array of parameters.

For instance:

double val[4] = {1., 2., 3., 4.};

messenger->setParameter("MyArray", val, 4);

will result in something like this:

The exact format is unspecified, determined at compile time, and by default, unlike in the example above, outputs a large number of digits for each double (about 20).

Parameters

name	the name of the parameter
val[]	an array of doubles
n	number of cells in val[]
child	(optional) if not NULL, a new FactoryMessenger is created to access the new parameter element e.g. to set attributes in it (using setSelfAttribute()). You then need to delete the child.