OptionsCont Class Reference

#include <OptionsCont.h>

Detailed Description

A storage for options typed value containers).

This container stores options (typed value containers) by their names. In the case of command line tools, this container is the main interface between a user's definitions about what to do (command line options, configuration files) and the application.

At the begin, the application should initialise the container. Because the OptionsCont is also responsible for printing the help screen, one should name and describe the application, first. This means that the first usage of this container should look similar to this:

 OptionsCont &oc = OptionsCont::getOptions();
 // give some application descriptions
 oc.setApplicationDescription(<ONE_LINE_DESCRIPTION>);
 oc.setApplicationName(<APPLICATION_NAME>, "SUMO <APPLICATION_NAME> Version " + (string)VERSION_STRING);

See also:: setApplicationDescription
setApplicationName

Then, you may also add some example calls using addCallExample.

See also:: addCallExample

In the next step, option subtopics are registered. This is needed for the help screen and for writing the templates/saving configurations. A subtopic is added using addOptionSubTopic(<SUBTOPIC_NAME>).

See also:: addOptionSubTopic

After this, you may add options to the container. This is done using doRegister. This method requires a long name for the option and the value container. The value container must be an instance of one of the classes derived from "Option". Do not use Option itself! This is a base class which is meant to supply a default behaviour, but this default behaviour throws exceptions only!

See also:

Option

doRegister

addSynonyme

Once stored inside this container, options will not be visible to the world and are deleted by the container. Only values and stati of the options may be returned. While accessing the options, the programmer must assure that he asks for the right value (only Option_Bool is able to return a boolean value, other option types will throw exceptions). Further, options added to the container must not be deleted outside this container (the container becomes the owner).

For being printed in the help screen, a description together with the subtopic the option belongs to must be given to OptionsCont. This is done using addDescription(<OPTION_NAME>, <SUBTOPIC>, <DESCRIPTION>).

See also:: addDescription
http://sumo.sourceforge.net/wiki/index.php/OptionsSubSystem

Definition at line 104 of file OptionsCont.h.


Public Member Functions
void	clear () throw ()
	Removes all information from the container.
	OptionsCont () throw ()
	Constructor.
bool	processMetaOptions (bool missingOptions) throw (ProcessError)
	Checks for help and configuration output, returns whether we should exit.
void	resetWritable () throw ()
	Resets all options to be writeable.
	~OptionsCont () throw ()
	Destructor.
Methods setting and getting information about the appplication and currently set options
void	addCallExample (const std::string &example) throw ()
	Add a call example.
void	addOptionSubTopic (const std::string &topic) throw ()
	Adds an option subtopic.
void	printHelp (std::ostream &os) throw ()
	Prints the help.
void	setAdditionalHelpMessage (const std::string &add) throw ()
	Sets an additional message to be printed at the begin of the help screen.
void	setApplicationDescription (const std::string &appDesc) throw ()
	Sets the application description.
void	setApplicationName (const std::string &appName, const std::string &fullName) throw ()
	Sets the application name.
void	writeConfiguration (std::ostream &os, bool filled, bool complete, bool addComments) throw ()
	Writes the configuration.
void	writeXMLHeader (std::ostream &os, const bool writeConfig=true) throw ()
	Writes a standard XML header, optionally including the configuration.
Methods for registering options
void	addDescription (const std::string &name, const std::string &subtopic, const std::string &description) throw (InvalidArgument)
	Adds a description for an option.
void	addSynonyme (const std::string &name1, const std::string &name2) throw (InvalidArgument)
	Adds a synonyme for an options name (any order).
void	doRegister (const std::string &name, char abbr, Option *v) throw (InvalidArgument)
	Adds an option under the given name and the given abbreviation.
void	doRegister (const std::string &name, Option *v) throw (InvalidArgument)
	Adds an option under the given name.
Methods for retrieving information about options
bool	checkDependingSuboptions (const std::string &name, const std::string &prefix) const throw (InvalidArgument)
	Checks whether an option is set, which has options with a prefix depending on it.
bool	exists (const std::string &name) const throw ()
	Returns the information whether the named option is known.
std::vector< std::string >	getSynonymes (const std::string &name) const throw (InvalidArgument)
	Returns the synonymes of an option name.
bool	isBool (const std::string &name) const throw (InvalidArgument)
	Returns the information whether the option is a boolean option.
bool	isDefault (const std::string &name) const throw (InvalidArgument)
	Returns the information whether the named option has still the default value.
bool	isSet (const std::string &name) const throw (InvalidArgument)
	Returns the information whether the named option is set.
bool	isUsableFileList (const std::string &name) const throw (InvalidArgument)
	Checks whether the named option is usable as a file list (with at least a single file).
bool	isWriteable (const std::string &name) throw (InvalidArgument)
	Returns the information whether the named option may be set.
void	relocateFiles (const std::string &configuration) const throw ()
	Modifies file name options according to the configuration path.
Methods for retrieving values from options
bool	getBool (const std::string &name) const throw (InvalidArgument)
	Returns the boolean-value of the named option (only for Option_Bool).
SUMOReal	getFloat (const std::string &name) const throw (InvalidArgument)
	Returns the SUMOReal-value of the named option (only for Option_Float).
int	getInt (const std::string &name) const throw (InvalidArgument)
	Returns the int-value of the named option (only for Option_Integer).
const IntVector &	getIntVector (const std::string &name) const throw (InvalidArgument)
	Returns the list of integer-value of the named option (only for Option_IntVector).
std::string	getString (const std::string &name) const throw (InvalidArgument)
	Returns the string-value of the named option (only for Option_String).
std::vector< std::string >	getStringVector (const std::string &name) const throw (InvalidArgument)
	Returns the list of string-vector-value of the named option (only for Option_String).
bool	isInStringVector (const std::string &optionName, const std::string &itemName) throw (InvalidArgument)
	Returns the named option is a list of string values containing the specified item.
Methods for setting values into options
bool	set (const std::string &name, bool value) throw (InvalidArgument)
	Sets the given boolean value for the named option (Option_Bool only).
bool	set (const std::string &name, const std::string &value) throw (InvalidArgument)
	Sets the given value for the named option.
Static Public Member Functions
static OptionsCont &	getOptions () throw ()
	Retrieves the options.
Private Types
typedef std::vector< Option * >	ItemAddressContType
typedef std::map< std::string, Option * >	KnownContType
Private Member Functions
std::string	convertChar (char abbr) const throw ()
	Converts an abbreviation into a name.
Option *	getSecure (const std::string &name) const throw (InvalidArgument)
	Returns the named option.
OptionsCont &	operator= (const OptionsCont &s)
	OptionsCont (const OptionsCont &s)
void	reportDoubleSetting (const std::string &arg) const throw ()
	Reports an error that the option has already been set.
void	splitLines (std::ostream &os, std::string what, size_t offset, size_t nextOffset) throw ()
	Writes the given string 'formatted'.
Private Attributes
std::string	myAdditionalMessage
ItemAddressContType	myAddresses
std::string	myAppDescription
std::string	myAppName
	some information on the application
std::vector< std::string >	myCallExamples
	lists of call examples and option subtopics
std::string	myFullName
bool	myHaveInformedAboutDeprecatedDivider
	Information whether a warning a deprecated divider.
std::map< std::string, std::vector< std::string > >	mySubTopicEntries
	A map from subtopic to option.
std::vector< std::string >	mySubTopics
KnownContType	myValues
Static Private Attributes
static OptionsCont	myOptions
	The static options container used.
Friends
std::ostream &	operator<< (std::ostream &os, const OptionsCont &oc)
	Output operator.
Data Structures
class	abbreviation_finder
	A class to find abbreviated option names (length=1). More...

Member Typedef Documentation

typedef std::vector<Option*> OptionsCont::ItemAddressContType [private]

definition of the type that stores the addresses of used options

Definition at line 635 of file OptionsCont.h.

typedef std::map<std::string, Option*> OptionsCont::KnownContType [private]

definition of the type that realises the access to options

Definition at line 638 of file OptionsCont.h.

Constructor & Destructor Documentation

OptionsCont::OptionsCont ( ) throw ()

Constructor.

Definition at line 66 of file OptionsCont.cpp.

00067         : myAddresses(), myValues(), myHaveInformedAboutDeprecatedDivider(false) {}

OptionsCont::~OptionsCont ( ) throw ()

Destructor.

Definition at line 70 of file OptionsCont.cpp.

References clear().

00070                                   {
00071     clear();
00072 }

OptionsCont::OptionsCont ( const OptionsCont & s ) [private]

invalid copy constructor

Member Function Documentation

void OptionsCont::addCallExample ( const std::string & example ) throw ()

Add a call example.

Parameters:

[in] example A call example (without the app name)

Definition at line 435 of file OptionsCont.cpp.

References myCallExamples.

Referenced by ROJTRFrame::fillOptions(), RODUAFrame::fillOptions(), RODFFrame::fillOptions(), NIOptionsIO::fillOptions(), MSFrame::fillOptions(), and fillOptions().

00435                                                             {
00436     myCallExamples.push_back(example);
00437 }

void OptionsCont::addDescription	(	const std::string &	name,
		const std::string &	subtopic,
		const std::string &	description
	)			throw (InvalidArgument)

Adds a description for an option.

Tries to retrieve the named option and to set the given description. Adds the name to the list of option names to be located in the named subtopic.

Throws an InvalidArgument if the option is not known or already has a description set.

Parameters:

`[in]`	name	The option's name
`[in]`	subtopic	The subtopic to locate the description within
`[in]`	description	The description

Exceptions:

InvalidArgument

If none of the synonymes or both synonymes with different options were registered before

Definition at line 408 of file OptionsCont.cpp.

References getSecure(), Option::myDescription, mySubTopicEntries, and mySubTopics.

Referenced by SystemFrame::addConfigurationOptions(), RODUAFrame::addDUAOptions(), RODUAFrame::addImportOptions(), ROJTRFrame::addJTROptions(), GeoConvHelper::addProjectionOptions(), SystemFrame::addReportOptions(), ROFrame::fillOptions(), RODFFrame::fillOptions(), NIOptionsIO::fillOptions(), MSFrame::fillOptions(), fillOptions(), NBNetBuilder::insertNetBuildOptions(), MSDevice_Routing::insertOptions(), MSDevice_HBEFA::insertOptions(), and RandHelper::insertRandOptions().

00410                                                                                  {
00411     Option *o = getSecure(name);
00412     assert(o!=0);
00413     assert(o->myDescription=="");
00414     assert(find(mySubTopics.begin(), mySubTopics.end(), subtopic)!=mySubTopics.end());
00415     o->myDescription = description;
00416     mySubTopicEntries[subtopic].push_back(name);
00417 }

void OptionsCont::addOptionSubTopic ( const std::string & topic ) throw ()

Adds an option subtopic.

Sub-topics are used to join several options into one thematic field. They are used on writing the help screen and the configuration. They have no further meaning besides making the outputs better readable.

Parameters:

[in] topic The options sub topic

Definition at line 447 of file OptionsCont.cpp.

References mySubTopicEntries, and mySubTopics.

Referenced by SystemFrame::addConfigurationOptions(), GeoConvHelper::addProjectionOptions(), SystemFrame::addReportOptions(), ROJTRFrame::fillOptions(), RODUAFrame::fillOptions(), RODFFrame::fillOptions(), NIOptionsIO::fillOptions(), MSFrame::fillOptions(), fillOptions(), MSDevice_Routing::insertOptions(), MSDevice_HBEFA::insertOptions(), and RandHelper::insertRandOptions().

00447                                                              {
00448     mySubTopics.push_back(topic);
00449     mySubTopicEntries[topic] = std::vector<std::string>();
00450 }

void OptionsCont::addSynonyme	(	const std::string &	name1,
		const std::string &	name2
	)			throw (InvalidArgument)

Adds a synonyme for an options name (any order).

Tries to find one of the synonymes. If both are known and the option differs for both, an InvalidArgument exception is thrown. If none is known, also.

If one of the synonymes is known and the other not, the option from the known one is made accessable by the other.

In the case both synonymes are known and have the same option assigned, nothing is done.

Parameters:

`[in]`	name1	The first synonyme
`[in]`	name2	The second synonyme

Exceptions:

InvalidArgument

If none of the synonymes or both synonymes with different options were registered before

Definition at line 97 of file OptionsCont.cpp.

References doRegister(), and myValues.

Referenced by SystemFrame::addConfigurationOptions(), RODUAFrame::addImportOptions(), ROJTRFrame::addJTROptions(), ROFrame::fillOptions(), RODFFrame::fillOptions(), NIOptionsIO::fillOptions(), MSFrame::fillOptions(), fillOptions(), and NBNetBuilder::insertNetBuildOptions().

00097                                                                                               {
00098     KnownContType::iterator i1 = myValues.find(name1);
00099     KnownContType::iterator i2 = myValues.find(name2);
00100     if (i1==myValues.end()&&i2==myValues.end()) {
00101         throw InvalidArgument("Neither the option '" + name1 + "' nor the option '" + name2 + "' is known yet");
00102     }
00103     if (i1!=myValues.end()&&i2!=myValues.end()) {
00104         if ((*i1).second==(*i2).second) {
00105             return;
00106         }
00107         throw InvalidArgument("Both options '" + name1 + "' and '" + name2 + "' do exist and differ.");
00108     }
00109     if (i1==myValues.end()&&i2!=myValues.end()) {
00110         doRegister(name1, (*i2).second);
00111     }
00112     if (i1!=myValues.end()&&i2==myValues.end()) {
00113         doRegister(name2, (*i1).second);
00114     }
00115 }

bool OptionsCont::checkDependingSuboptions	(	const std::string &	name,
		const std::string &	prefix
	)			const throw (InvalidArgument)

Checks whether an option is set, which has options with a prefix depending on it.

The method returns true, if the named option is set or no option dependoing on it is set. Throws an InvalidArgument exception if the option is not known.

Parameters:

`[in]`	name	The name of the option to check
`[in]`	prefix	The prefix of depending options

Returns:: Whether the dependencies are fulfilled

Exceptions:

InvalidArgument

If the option does not exist

Definition at line 330 of file OptionsCont.cpp.

References MsgHandler::getErrorInstance(), getSecure(), MsgHandler::inform(), Option::isSet(), and myValues.

Referenced by NIOptionsIO::checkOptions().

00330                                                                                                                  {
00331     Option *o = getSecure(name);
00332     if (o->isSet()) {
00333         return true;
00334     }
00335     bool ok = true;
00336     for (KnownContType::const_iterator i=myValues.begin(); i!=myValues.end(); i++) {
00337         if ((*i).second->isSet() && !(*i).second->isDefault() && (*i).first.find(prefix) == 0) {
00338             MsgHandler::getErrorInstance()->inform("Option '" + (*i).first + "' needs option '" + name + "'.");
00339             ok = false;
00340         }
00341     }
00342     return ok;
00343 }

void OptionsCont::clear ( ) throw ()

Removes all information from the container.

Definition at line 395 of file OptionsCont.cpp.

References myAddresses, mySubTopicEntries, mySubTopics, and myValues.

Referenced by SystemFrame::close(), GUILoadThread::initOptions(), GUILoadThread::run(), and ~OptionsCont().

00395                            {
00396     ItemAddressContType::iterator i;
00397     for (i=myAddresses.begin(); i!=myAddresses.end(); i++) {
00398         delete(*i);
00399     }
00400     myAddresses.clear();
00401     myValues.clear();
00402     mySubTopics.clear();
00403     mySubTopicEntries.clear();
00404 }

std::string OptionsCont::convertChar ( char abbr ) const throw () [private]

Converts an abbreviation into a name.

Build and returns the string which consists of the given character only.

Parameters:

[in] abbr The abbreviation to convert into a string

Returns:: The abbreviation converted into a string

Definition at line 363 of file OptionsCont.cpp.

Referenced by doRegister().

00363                                                 {
00364     char buf[2];
00365     buf[0] = abbr;
00366     buf[1] = 0;
00367     std::string s(buf);
00368     return s;
00369 }

void OptionsCont::doRegister	(	const std::string &	name,
		char	abbr,
		Option *	v
	)			throw (InvalidArgument)

Adds an option under the given name and the given abbreviation.

Adds the option under both names using void doRegister(const std::string &name, Option *v);

Parameters:

`[in]`	name	The (long) name of the option
`[in]`	abbr	The (short) name of the option
`[in]`	v	The option (typed value storage)

Exceptions:

InvalidArgument

If one of the names is already used

Definition at line 90 of file OptionsCont.cpp.

References convertChar(), and doRegister().

00090                                                                                            {
00091     doRegister(name1, v);
00092     doRegister(convertChar(abbr), v);
00093 }

void OptionsCont::doRegister	(	const std::string &	name,
		Option *	v
	)			throw (InvalidArgument)

Adds an option under the given name.

Parameters:

`[in]`	name	The (long) name of the option
`[in]`	v	The option (typed value storage)

Exceptions:

InvalidArgument

If the name is already used

Definition at line 76 of file OptionsCont.cpp.

References myAddresses, and myValues.

Referenced by SystemFrame::addConfigurationOptions(), RODUAFrame::addDUAOptions(), RODUAFrame::addImportOptions(), ROJTRFrame::addJTROptions(), GeoConvHelper::addProjectionOptions(), SystemFrame::addReportOptions(), addSynonyme(), doRegister(), ROFrame::fillOptions(), RODFFrame::fillOptions(), NIOptionsIO::fillOptions(), MSFrame::fillOptions(), fillOptions(), NBNetBuilder::insertNetBuildOptions(), MSDevice_Routing::insertOptions(), MSDevice_HBEFA::insertOptions(), and RandHelper::insertRandOptions().

00076                                                                                {
00077     assert(v!=0);
00078     ItemAddressContType::iterator i = find(myAddresses.begin(), myAddresses.end(), v);
00079     if (i==myAddresses.end()) {
00080         myAddresses.push_back(v);
00081     }
00082     if (myValues.find(name)!=myValues.end()) {
00083         throw InvalidArgument(name + " is an already used option name.");
00084     }
00085     myValues[name] = v;
00086 }

bool OptionsCont::exists ( const std::string & name ) const throw ()

Returns the information whether the named option is known.

Returns:: true if an option has been added before under the given name, false otherwise

Definition at line 119 of file OptionsCont.cpp.

References myValues.

Referenced by MsgHandler::addRetriever(), GeoConvHelper::init(), OptionsIO::loadConfiguration(), ROLoader::openTypedRoutes(), MsgHandler::removeRetriever(), MsgHandler::report2cerr(), MsgHandler::report2cout(), and OptionsLoader::startElement().

00119                                                        {
00120     KnownContType::const_iterator i = myValues.find(name);
00121     return i!=myValues.end();
00122 }

bool OptionsCont::getBool ( const std::string & name ) const throw (InvalidArgument)

Returns the boolean-value of the named option (only for Option_Bool).

This method returns the boolean-value of an existing boolean-option. If the named option does not exist or is not a boolean-option, an InvalidArgument is thrown.

Parameters:

[in] name The name of the option to return the boolean-value of

Returns:: The boolean-value of the named, existing boolean-option

Exceptions:

InvalidArgument

If the option does not exist or is not a boolean-option

Definition at line 177 of file OptionsCont.cpp.

References Option::getBool(), and getSecure().

Referenced by MsgHandler::addRetriever(), NBEdgeCont::applyOptions(), RORouteDef_Complete::buildCurrentRoute(), ROLoader::buildNamedHandler(), buildNetwork(), MSDevice_Routing::buildVehicleDevices(), MSDevice_HBEFA::buildVehicleDevices(), NIOptionsIO::checkOptions(), checkOptions(), MSFrame::checkOptions(), NBNode::computeLogic(), RONet::computeRoute(), computeRoutes(), NBNodeCont::guessRamps(), NBNodeCont::guessTLs(), GeoConvHelper::init(), initNet(), MsgHandler::initOutputOptions(), RandHelper::initRandGlobal(), NIImporter_ArcView::load(), loadJTRDefinitions(), NIImporter_VISUM::loadNetwork(), NIImporter_ArcView::loadNetwork(), main(), MSNet::MSNet(), NIXMLNodesHandler::myStartElement(), NIXMLEdgesHandler::myStartElement(), ROLoader::openRoutes(), NIImporter_Vissim::postLoadBuild(), processMetaOptions(), ROLoader::processRoutesStepWise(), readDetectors(), MsgHandler::removeRetriever(), MsgHandler::report2cerr(), MsgHandler::report2cout(), RODFNet::RODFNet(), ROJTRRouter::ROJTRRouter(), RONet::saveAndRemoveRoutesUntil(), MSFrame::setMSGlobals(), startComputation(), ODMatrix::write(), NBRequest::writeLaneResponse(), ROLoader::writeStats(), and NBNode::writeXML().

00177                                                                        {
00178     Option *o = getSecure(name);
00179     return o->getBool();
00180 }

SUMOReal OptionsCont::getFloat ( const std::string & name ) const throw (InvalidArgument)

Returns the SUMOReal-value of the named option (only for Option_Float).

This method returns the SUMOReal-value of an existing SUMOReal-option. If the named option does not exist or is not a SUMOReal-option, an InvalidArgument is thrown.

Parameters:

[in] name The name of the option to return the SUMOReal-value of

Returns:: The SUMOReal-value of the named, existing SUMOReal-option

Exceptions:

InvalidArgument

If the option does not exist or is not a SUMOReal-option

Definition at line 163 of file OptionsCont.cpp.

References Option::getFloat(), and getSecure().

Referenced by NBEdgeCont::applyOptions(), ROLoader::buildNamedHandler(), NIVissimEdge::buildNBEdge(), buildNetwork(), NBNodeCont::buildOffRamp(), NBNodeCont::buildOnRamp(), MSDevice_Routing::buildVehicleDevices(), MSDevice_HBEFA::buildVehicleDevices(), RODFNet::computeRoutesFor(), NIVissimDistrictConnection::getRealSpeed(), NBNodeCont::guessRamps(), GeoConvHelper::init(), NIImporter_Vissim::load(), loadMatrix(), NIImporter_VISUM::loadNetwork(), NBNodeCont::mayNeedOffRamp(), NBNodeCont::mayNeedOnRamp(), ROJTRRouter::ROJTRRouter(), startComputation(), NGNet::toNB(), and traci::TraCIServer::TraCIServer().

00163                                                                         {
00164     Option *o = getSecure(name);
00165     return o->getFloat();
00166 }

int OptionsCont::getInt ( const std::string & name ) const throw (InvalidArgument)

Returns the int-value of the named option (only for Option_Integer).

This method returns the int-value of an existing int-option. If the named option does not exist or is not a int-option, an InvalidArgument is thrown.

Parameters:

[in] name The name of the option to return the int-value of

Returns:: The int-value of the named, existing int-option

Exceptions:

InvalidArgument

If the option does not exist or is not a int-option

Definition at line 170 of file OptionsCont.cpp.

References Option::getInt(), and getSecure().

Referenced by NLBuilder::build(), ROLoader::buildNamedHandler(), buildNetwork(), ROFrame::checkOptions(), MSFrame::checkOptions(), GeoConvHelper::init(), RandHelper::initRandGlobal(), PCLoaderArcView::load(), MSNet::MSNet(), MSRouteHandler::MSRouteHandler(), NBOwnTLDef::myCompute(), PCTypeDefHandler::myStartElement(), PCLoaderXML::myStartElement(), RONet::saveAndRemoveRoutesUntil(), MSNet::simulationState(), startComputation(), and traci::TraCIServer::TraCIServer().

00170                                                                       {
00171     Option *o = getSecure(name);
00172     return o->getInt();
00173 }

const IntVector & OptionsCont::getIntVector ( const std::string & name ) const throw (InvalidArgument)

Returns the list of integer-value of the named option (only for Option_IntVector).

This method returns the int-vector-value of an existing int-vector-option. If the named option does not exist or is not a int-vector-option, an InvalidArgument is thrown.

Parameters:

[in] name The name of the option to return the int-vector-value of

Returns:: The int-vector-value of the named, existing int-vector-option

Exceptions:

InvalidArgument

If the option does not exist or is not a int-vector-option

Definition at line 184 of file OptionsCont.cpp.

References Option::getIntVector(), and getSecure().

Referenced by NLBuilder::buildNet().

00184                                                                             {
00185     Option *o = getSecure(name);
00186     return o->getIntVector();
00187 }

OptionsCont & OptionsCont::getOptions ( ) throw () [static]

Retrieves the options.

Definition at line 61 of file OptionsCont.cpp.

References myOptions.

Referenced by MSDetectorControl::addDetectorAndInterval(), RODUAFrame::addDUAOptions(), NLHandler::addEdgeLaneMeanData(), RODUAFrame::addImportOptions(), ROJTRFrame::addJTROptions(), MsgHandler::addRetriever(), NBEdgeCont::applyOptions(), NLEdgeControlBuilder::build(), RORouteDef_Complete::buildCurrentRoute(), NBNetBuilder::buildLoaded(), NIVissimEdge::buildNBEdge(), NGNode::buildNBNode(), buildNetwork(), NLTriggerBuilder::buildVaporizer(), MSDevice_Routing::buildVehicleDevices(), MSDevice_HBEFA::buildVehicleDevices(), OptionsParser::check(), ROJTRFrame::checkOptions(), RODUAFrame::checkOptions(), NIOptionsIO::checkOptions(), checkOptions(), MSFrame::checkOptions(), SystemFrame::close(), MSNet::closeBuilding(), MSRouteHandler::closeFlow(), MSRouteHandler::closeVehicle(), traci::TraCIServer::commandChangeRoute(), NBNodeShapeComputer::compute(), NBNode::computeLogic(), NBNodeShapeComputer::computeNodeShapeByCrosses(), RODFNet::computeRoutesFor(), OutputDevice::createDeviceByOption(), ROJTRFrame::fillOptions(), RODUAFrame::fillOptions(), RODFFrame::fillOptions(), NIOptionsIO::fillOptions(), MSFrame::fillOptions(), fillOptions(), FXIMPLEMENT(), OutputDevice::getDeviceByOption(), OptionsIO::getOptions(), GUINet::getParameterWindow(), NIVissimDistrictConnection::getRealSpeed(), GUILoadThread::initOptions(), MsgHandler::initOutputOptions(), RandHelper::initRandGlobal(), NBEdgeCont::insert(), MSDevice_Routing::insertOptions(), MSDevice_HBEFA::insertOptions(), RandHelper::insertRandOptions(), NLBuilder::load(), OptionsIO::loadConfiguration(), PCLoaderOSM::loadIfSet(), PCLoaderDlrNavteq::loadPOIFile(), main(), GUIRunThread::makeStep(), MSNet::MSNet(), MSPhaseDefinition::MSPhaseDefinition(), MSRouteHandler::MSRouteHandler(), NBOwnTLDef::myCompute(), NBLoadedTLDef::myCompute(), PCLoaderXML::myStartElement(), NIXMLEdgesHandler::myStartElement(), traci::TraCIHandler::openVehicleTag(), NIImporter_VISUM::parse_Connectors(), NIImporter_VISUM::parse_EdgePolys(), NIImporter_VISUM::parse_Edges(), NIImporter_VISUM::parse_Turns(), SUMOVehicleParserHelper::parseFlowAttributes(), NIImporter_Vissim::postLoadBuild(), traci::TraCIServer::processCommandsUntilSimStep(), processMetaOptions(), NBNodeCont::removeIsolatedRoads(), MsgHandler::removeRetriever(), NBEdgeCont::removeUnwishedEdges(), MsgHandler::report2cerr(), MsgHandler::report2cout(), RODFNet::RODFNet(), ROJTRRouter::ROJTRRouter(), GUILoadThread::run(), ROVehicle::saveAllAsXML(), MSNet::simulate(), MSNet::simulationState(), NBNode::sortNodesEdges(), GUILoadThread::submitEndAndCleanup(), NGNet::toNB(), traci::TraCIServer::TraCIServer(), traci::TraCIServer::vehicleStateChanged(), ODMatrix::write(), NBRequest::writeLaneResponse(), MSNet::writeOutput(), NBNode::writeXML(), and OutputDevice::writeXMLHeader().

00061                                 {
00062     return myOptions;
00063 }

Option * OptionsCont::getSecure ( const std::string & name ) const throw (InvalidArgument) [private]

Returns the named option.

If the named option does not exist, an InvalidArgument is thrown.

Parameters:

[in] name The name of the option to return

Returns:: The named option

Definition at line 146 of file OptionsCont.cpp.

References myValues.

Referenced by addDescription(), checkDependingSuboptions(), getBool(), getFloat(), getInt(), getIntVector(), getString(), getStringVector(), getSynonymes(), isBool(), isUsableFileList(), isWriteable(), printHelp(), set(), and writeConfiguration().

00146                                                                          {
00147     KnownContType::const_iterator i = myValues.find(name);
00148     if (i==myValues.end()) {
00149         throw InvalidArgument("No option with the name '" + name + "' exists.");
00150     }
00151     return (*i).second;
00152 }

std::string OptionsCont::getString ( const std::string & name ) const throw (InvalidArgument)

Returns the string-value of the named option (only for Option_String).

This method returns the string-value of an existing string-option. If the named option does not exist or is not a string-option, an InvalidArgument is thrown.

Parameters:

[in] name The name of the option to return the string-value of

Returns:: The string-value of the named, existing string-option

Exceptions:

InvalidArgument

If the option does not exist or is not a string-option

Definition at line 156 of file OptionsCont.cpp.

References getSecure(), and Option::getString().

Referenced by NLBuilder::build(), NBNetBuilder::buildLoaded(), ROLoader::buildNamedHandler(), NGNode::buildNBNode(), NLBuilder::buildNet(), MSDevice_Routing::buildVehicleDevices(), ROJTRFrame::checkOptions(), RODUAFrame::checkOptions(), NIOptionsIO::checkOptions(), checkOptions(), computeRoutes(), OutputDevice::getDeviceByOption(), GeoConvHelper::init(), initNet(), MsgHandler::initOutputOptions(), PCLoaderArcView::load(), NIImporter_Vissim::load(), NIImporter_ArcView::load(), OptionsIO::loadConfiguration(), loadDistricts(), loadJTRDefinitions(), loadMatrix(), ROLoader::loadNet(), NIImporter_VISUM::loadNetwork(), NIImporter_Vissim::loadNetwork(), NIImporter_DlrNavteq::loadNetwork(), NIImporter_ArcView::loadNetwork(), main(), MSNet::MSNet(), PCTypeDefHandler::myStartElement(), PCLoaderXML::myStartElement(), ROLoader::openRoutes(), traci::TraCIHandler::openVehicleTag(), processMetaOptions(), readDetectorFlows(), GUILoadThread::run(), MSFrame::setMSGlobals(), startComputation(), traci::TraCIServer::TraCIServer(), and ODMatrix::write().

00156                                                                          {
00157     Option *o = getSecure(name);
00158     return o->getString();
00159 }

std::vector< std::string > OptionsCont::getStringVector ( const std::string & name ) const throw (InvalidArgument)

Returns the list of string-vector-value of the named option (only for Option_String).

This method returns the string-vector-value of an existing string-option. If the named option does not exist or is not a string-option, an InvalidArgument is thrown.

The string-value is determined, first. If the legacy-divider ';' is found within the string, a warning is generated. The retrieved string is splitted at ',' and ';'.

Parameters:

[in] name The name of the option to return the string-vector-value of

Returns:: The string-vector-value of the named, existing string-option

Exceptions:

InvalidArgument

If the option does not exist or is not a string-option

Todo:: Is it possible to retrieve a const-reference of the string?

See also:: getString()

Definition at line 701 of file OptionsCont.cpp.

References getSecure(), Option::getString(), StringTokenizer::getVector(), MsgHandler::getWarningInstance(), MsgHandler::inform(), myHaveInformedAboutDeprecatedDivider, and StringUtils::prune().

Referenced by NBEdgeCont::applyOptions(), NLBuilder::build(), getTurningDefaults(), NBNodeCont::guessRamps(), NBNodeCont::guessTLs(), isInStringVector(), isUsableFileList(), NLBuilder::load(), NILoader::load(), loadJTRDefinitions(), loadMatrix(), NIImporter_SUMO::loadNetwork(), NIImporter_RobocupRescue::loadNetwork(), NIImporter_OpenStreetMap::loadNetwork(), NIImporter_OpenDrive::loadNetwork(), ROLoader::loadWeights(), NILoader::loadXML(), main(), ROLoader::openTypedRoutes(), readDetectorFlows(), readDetectors(), RODFNet::RODFNet(), and traci::TraCIServer::TraCIServer().

00701                                                                                {
00702     Option *o = getSecure(name);
00703     std::string def = o->getString();
00704     if (def.find(';')!=std::string::npos&&!myHaveInformedAboutDeprecatedDivider) {
00705         MsgHandler::getWarningInstance()->inform("Please note that using ';' as list separator is deprecated.\n From 1.0 onwards, only ',' will be accepted.");
00706         myHaveInformedAboutDeprecatedDivider = true;
00707     }
00708     StringTokenizer st(def, ";,", true);
00709     std::vector<std::string> ret = st.getVector();
00710     for (std::vector<std::string>::iterator i=ret.begin(); i!=ret.end(); ++i) {
00711         (*i) = StringUtils::prune(*i);
00712     }
00713     return ret;
00714 }

std::vector< std::string > OptionsCont::getSynonymes ( const std::string & name ) const throw (InvalidArgument)

Returns the synonymes of an option name.

The named option is extracted, first. An InvalidArgument is thrown if it does not exist. Otherwise, other names for the named option are searched and returned (the original name is not in the list).

Parameters:

[in] name The name of the option to return synonymes of

Returns:: List of existing synonymes

Exceptions:

InvalidArgument

If the named option does not exist

Definition at line 232 of file OptionsCont.cpp.

References getSecure(), and myValues.

Referenced by operator<<(), printHelp(), and reportDoubleSetting().

00232                                                                             {
00233     Option *o = getSecure(name);
00234     std::vector<std::string> v(0);
00235     for (KnownContType::const_iterator i=myValues.begin(); i!=myValues.end(); i++) {
00236         if ((*i).second==o&&name!=(*i).first) {
00237             v.push_back((*i).first);
00238         }
00239     }
00240     return v;
00241 }

bool OptionsCont::isBool ( const std::string & name ) const throw (InvalidArgument)

Returns the information whether the option is a boolean option.

The option is retrieved from the container, first, what may cause an InvalidArgument exception if it is not known. Otherwise, this option's isBool-method is called.

Parameters:

[in] name The name of the option to check

Returns:: Whether the existing named option is a bool option

Exceptions:

InvalidArgument

If the option does not exist

Definition at line 373 of file OptionsCont.cpp.

References getSecure(), and Option::isBool().

Referenced by OptionsParser::check(), and OptionsLoader::setValue().

00373                                                                       {
00374     Option *o = getSecure(name);
00375     return o->isBool();
00376 }

bool OptionsCont::isDefault ( const std::string & name ) const throw (InvalidArgument)

Returns the information whether the named option has still the default value.

The named option is tried to be retrieved from the container. If it does not exist, an InvalidArgument is thrown. If it could be retrieved, the information whether the option still has the default value is returned.

An option "is default" if no value has been set from the command line / the configuration file.

Returns:: true if the option still has the default value

Exceptions:

InvalidArgument

If the named option is not known

Definition at line 136 of file OptionsCont.cpp.

References myValues.

Referenced by NLBuilder::build(), NLBuilder::buildNet(), buildNetwork(), NIOptionsIO::checkOptions(), GeoConvHelper::init(), and main().

00136                                                                          {
00137     KnownContType::const_iterator i = myValues.find(name);
00138     if (i==myValues.end()) {
00139         return false;
00140     }
00141     return (*i).second->isDefault();
00142 }

bool OptionsCont::isInStringVector	(	const std::string &	optionName,
		const std::string &	itemName
	)			throw (InvalidArgument)

Returns the named option is a list of string values containing the specified item.

If the named option is not set, false is returned. Otherwise, the string-vector of this option is retrieved using getStringVector what may throw an InvalidArgument exception if the named option is not a string option or not existing at all.

The given itemName is searched in the obtained string-vector and the method returns whether it is stored in the list or not.

Parameters:

`[in]`	optionName	The name of the option to evaluate entries of
`[in]`	itemName	The item to be searched for in the entries of the named option

Returns:: Whether the named item is set in the named string-option

Exceptions:

InvalidArgument

If the option does not exist or is not a string-option

See also:: getStringVector()

Todo:: Try to optimize - at each call, the vector is rebuilt

Definition at line 718 of file OptionsCont.cpp.

References getStringVector(), and isSet().

Referenced by MSDevice_Routing::buildVehicleDevices(), MSDevice_HBEFA::buildVehicleDevices(), NBNode::computeLogic(), PCLoaderOSM::loadIfSet(), PCLoaderXML::myStartElement(), and NBEdgeCont::removeUnwishedEdges().

00719                                                                                 {
00720     if (isSet(optionName)) {
00721         std::vector<std::string> values = getStringVector(optionName);
00722         return find(values.begin(), values.end(), itemName)!=values.end();
00723     }
00724     return false;
00725 }

bool OptionsCont::isSet ( const std::string & name ) const throw (InvalidArgument)

Returns the information whether the named option is set.

The named option is tried to be retrieved from the container. If it does not exist, an InvalidArgument is thrown. If it could be retrieved, the information whether the option has a value stored is returned.

An option "is set" if a default value was supplied or a value has been set from the command line / the configuration file.

Returns:: true if the option has a valid value, false otherwise

Exceptions:

InvalidArgument

If the named option is not known

Definition at line 126 of file OptionsCont.cpp.

References myValues.

Referenced by NBEdgeCont::applyOptions(), NLBuilder::build(), NBNetBuilder::buildLoaded(), NGNode::buildNBNode(), MSDevice_Routing::buildVehicleDevices(), MSDevice_HBEFA::buildVehicleDevices(), ROJTRFrame::checkOptions(), ROFrame::checkOptions(), RODUAFrame::checkOptions(), NIOptionsIO::checkOptions(), checkOptions(), MSFrame::checkOptions(), NBNodeShapeComputer::computeNodeShapeByCrosses(), NBNodeCont::guessRamps(), NBNodeCont::guessTLs(), initNet(), MsgHandler::initOutputOptions(), isInStringVector(), PCLoaderArcView::load(), NIImporter_ArcView::load(), OptionsIO::loadConfiguration(), loadDistricts(), loadJTRDefinitions(), ROLoader::loadNet(), NIImporter_VISUM::loadNetwork(), NIImporter_Vissim::loadNetwork(), NIImporter_RobocupRescue::loadNetwork(), NIImporter_OpenStreetMap::loadNetwork(), NIImporter_DlrNavteq::loadNetwork(), NIImporter_ArcView::loadNetwork(), main(), ROLoader::openTypedRoutes(), NIImporter_VISUM::parse_Turns(), processMetaOptions(), readDetectorFlows(), readDetectors(), MSFrame::setMSGlobals(), startComputation(), traci::TraCIServer::TraCIServer(), and ODMatrix::write().

00126                                                                      {
00127     KnownContType::const_iterator i = myValues.find(name);
00128     if (i==myValues.end()) {
00129         return false;
00130     }
00131     return (*i).second->isSet();
00132 }

bool OptionsCont::isUsableFileList ( const std::string & name ) const throw (InvalidArgument)

Checks whether the named option is usable as a file list (with at least a single file).

The method returns true, if the named option is set with entries containing names of accessable files.

Throw an InvalidArgument exception if the option is not known. If the option is not set, false is returned. Also, if the list is empty (conatins delimiters only) or if one of the named files (obtained using getStringVector) does not exist, false is returned. Additionally, an error is sent to MsgHandler in both cases.

In the case two delimiters were placed in the option value directly after each other, a warning is generated.

Parameters:

[in] name The name of the option to check

Returns:: Whether the option contains names of files which can be accessed (for reading)

Exceptions:

InvalidArgument

If the option does not exist or is not a string-option

Definition at line 301 of file OptionsCont.cpp.

References FileHelpers::exists(), MsgHandler::getErrorInstance(), getSecure(), getStringVector(), MsgHandler::getWarningInstance(), MsgHandler::inform(), and Option::isSet().

Referenced by NLBuilder::build(), NIImporter_SUMO::loadNetwork(), NIImporter_OpenDrive::loadNetwork(), ROLoader::loadWeights(), ROLoader::openTypedRoutes(), and traci::TraCIServer::TraCIServer().

00301                                                                                 {
00302     Option *o = getSecure(name);
00303     // check whether the option is set
00304     //  return false i not
00305     if (!o->isSet()) {
00306         return false;
00307     }
00308     // check whether the list of files is valid
00309     bool ok = true;
00310     std::vector<std::string> files = getStringVector(name);
00311     if (files.size()==0) {
00312         MsgHandler::getErrorInstance()->inform("The file list for '" + name + "' is empty.");
00313         ok = false;
00314     }
00315     for (std::vector<std::string>::const_iterator fileIt=files.begin(); fileIt!=files.end(); ++fileIt) {
00316         if (!FileHelpers::exists(*fileIt)) {
00317             if (*fileIt!="") {
00318                 MsgHandler::getErrorInstance()->inform("File '" + *fileIt + "' does not exist.");
00319                 ok = false;
00320             } else {
00321                 MsgHandler::getWarningInstance()->inform("Empty file name given; ignoring.");
00322             }
00323         }
00324     }
00325     return ok;
00326 }

bool OptionsCont::isWriteable ( const std::string & name ) throw (InvalidArgument)

Returns the information whether the named option may be set.

An option is writable after initialisation, but as soon as it gets set, it is no longer writeable. This method returns whether the named option is writeable. If the named option is not known, an InvalidArgument is thrown.

Parameters:

[in] name The name of the option to check

Returns:: Whether the value can be set

Exceptions:

InvalidArgument

If the option does not exist

Definition at line 388 of file OptionsCont.cpp.

References getSecure(), and Option::isWriteable().

Referenced by OptionsLoader::setSecure().

00388                                                                      {
00389     Option *o = getSecure(name);
00390     return o->isWriteable();
00391 }

OptionsCont& OptionsCont::operator= ( const OptionsCont & s ) [private]

invalid assignment operator

void OptionsCont::printHelp ( std::ostream & os ) throw ()

Prints the help.

Parameters:

[in] os The stream to write the help into

Definition at line 537 of file OptionsCont.cpp.

References Option::getDescription(), getSecure(), getSynonymes(), Option::getTypeName(), Option::isBool(), myAdditionalMessage, myAppDescription, myAppName, myCallExamples, mySubTopicEntries, mySubTopics, and splitLines().

Referenced by processMetaOptions().

00537                                              {
00538     std::vector<std::string>::const_iterator i, j;
00539     // print application description
00540     os << ' ' << std::endl;
00541     splitLines(os, myAppDescription , 0, 0);
00542     os << std::endl;
00543     // print usage BNF
00544     os << "Usage: " << myAppName << " [OPTION]*" << std::endl;
00545     os << ' ' << std::endl;
00546     // print usage examples
00547     if (myCallExamples.size()>1) {
00548         os << " Examples:" << std::endl;
00549     } else if (myCallExamples.size()!=0) {
00550         os << " Example:" << std::endl;
00551     }
00552     if (myCallExamples.size()!=0) {
00553         for (i=myCallExamples.begin(); i!=myCallExamples.end(); ++i) {
00554             os << "  " << myAppName << ' ' << (*i) << std::endl;
00555         }
00556     }
00557     os << ' ' << std::endl;
00558     // print additional text if any
00559     if (myAdditionalMessage.length()>0) {
00560         os << myAdditionalMessage << std::endl << ' ' << std::endl;
00561     }
00562     // print the options
00563     // check their sizes first
00564     //  we want to know how large the largest not-too-large-entry will be
00565     size_t tooLarge = 40;
00566     size_t maxSize = 0;
00567     for (i=mySubTopics.begin(); i!=mySubTopics.end(); ++i) {
00568         const std::vector<std::string> &entries = mySubTopicEntries[*i];
00569         for (j=entries.begin(); j!=entries.end(); ++j) {
00570             Option *o = getSecure(*j);
00571             // name, two leading spaces and "--"
00572             size_t csize = (*j).length() + 2 + 4;
00573             // abbreviation length ("-X, "->4chars) if any
00574             std::vector<std::string> synonymes = getSynonymes(*j);
00575             if (find_if(synonymes.begin(), synonymes.end(), abbreviation_finder())!=synonymes.end()) {
00576                 csize += 4;
00577             }
00578             // the type name
00579             if (!o->isBool()) {
00580                 csize += 1 + o->getTypeName().length();
00581             }
00582             // divider
00583             csize += 2;
00584             if (csize<tooLarge&&maxSize<csize) {
00585                 maxSize = csize;
00586             }
00587         }
00588     }
00589 
00590     for (i=mySubTopics.begin(); i!=mySubTopics.end(); ++i) {
00591         os << ' ' << *i << " Options:" << std::endl;
00592         const std::vector<std::string> &entries = mySubTopicEntries[*i];
00593         for (j=entries.begin(); j!=entries.end(); ++j) {
00594             // start length computation
00595             size_t csize = (*j).length() + 2;
00596             Option *o = getSecure(*j);
00597             os << "  ";
00598             // write abbreviation if given
00599             std::vector<std::string> synonymes = getSynonymes(*j);
00600             std::vector<std::string>::iterator a = find_if(synonymes.begin(), synonymes.end(), abbreviation_finder());
00601             if (a!=synonymes.end()) {
00602                 os << '-' << (*a) << ", ";
00603                 csize += 4;
00604             }
00605             // write leading '-'/"--"
00606             os << "--";
00607             csize += 2;
00608             // write the name
00609             os << *j;
00610             // write the type if not a bool option
00611             if (!o->isBool()) {
00612                 os << ' ' << o->getTypeName();
00613                 csize += 1 + o->getTypeName().length();
00614             }
00615             csize += 2;
00616             // write the description formatting it
00617             os << "  ";
00618             size_t r;
00619             for (r=maxSize; r>csize; --r) {
00620                 os << ' ';
00621             }
00622             std::string desc = o->getDescription();
00623             size_t offset = csize > tooLarge ? csize : maxSize;
00624             splitLines(os, desc, offset, maxSize);
00625         }
00626         os << std::endl;
00627     }
00628 }

bool OptionsCont::processMetaOptions ( bool missingOptions ) throw (ProcessError)

Checks for help and configuration output, returns whether we should exit.

Returns false if no error was detected and the application may be executed (at least from this point of view). If missingOptions is true, the user is informed that they should be supplied (returns true). Otherwise it is checked whether help shall be printed what is done if so, returning true. Also, it is checked whether the set options shall be printed and the configuration template or the current configuration shall be written.

This method throws a ProcessError if the configuration should be saved, but the file is not accessable. An error message is supplied.

Parameters:

[in] missingOptions Whether no options have been given

Returns:: Whether the application shall stop

Exceptions:

ProcessError

If the configuration file could not be saved

Definition at line 485 of file OptionsCont.cpp.

References getBool(), MsgHandler::getMessageInstance(), getOptions(), getString(), MsgHandler::inform(), isSet(), myFullName, printHelp(), and writeConfiguration().

Referenced by main().

00485                                                                        {
00486     if (missingOptions) {
00487         // no options are given
00488         std::cout << myFullName << std::endl;
00489         std::cout << " (c) DLR 2001-2009; http://sumo.sourceforge.net" << std::endl;
00490         std::cout << " Use --help to get the list of options." << std::endl;
00491         return true;
00492     }
00493 
00494     OptionsCont &oc = OptionsCont::getOptions();
00495     // check whether the help shall be printed
00496     if (oc.getBool("help")) {
00497         std::cout << myFullName << std::endl;
00498         std::cout << " (c) DLR 2001-2009; http://sumo.sourceforge.net" << std::endl;
00499         oc.printHelp(std::cout);
00500         return true;
00501     }
00502     // check whether the settings shall be printed
00503     if (oc.getBool("print-options")) {
00504         std::cout << oc;
00505     }
00506     // check whether something has to be done with options
00507     // whether the current options shall be saved
00508     if (oc.isSet("save-configuration")) {
00509         std::ofstream out(oc.getString("save-configuration").c_str());
00510         if (!out.good()) {
00511             throw ProcessError("Could not save configuration to '" + oc.getString("save-configuration") + "'");
00512         } else {
00513             oc.writeConfiguration(out, true, false, false);
00514             if (oc.getBool("verbose")) {
00515                 MsgHandler::getMessageInstance()->inform("Written configuration to '" + oc.getString("save-configuration") + "'");
00516             }
00517             return true;
00518         }
00519     }
00520     // whether the template shall be saved
00521     if (oc.isSet("save-template")) {
00522         std::ofstream out(oc.getString("save-template").c_str());
00523         if (!out.good()) {
00524             throw ProcessError("Could not save template to '" + oc.getString("save-template") + "'");
00525         } else {
00526             oc.writeConfiguration(out, false, true, oc.getBool("save-template.commented"));
00527             if (oc.getBool("verbose")) {
00528                 MsgHandler::getMessageInstance()->inform("Written template to '" + oc.getString("save-template") + "'");
00529             }
00530             return true;
00531         }
00532     }
00533     return false;
00534 }

void OptionsCont::relocateFiles ( const std::string & configuration ) const throw ()

Modifies file name options according to the configuration path.

If the configuration path given is a relative one all filenames inside are adapted such that they refer to the correct location.

Parameters:

[in] configuration The path to the configuration file

Definition at line 279 of file OptionsCont.cpp.

References FileHelpers::getConfigurationRelative(), FileHelpers::isAbsolute(), and myAddresses.

Referenced by OptionsIO::loadConfiguration().

00279                                                                        {
00280     for (ItemAddressContType::const_iterator i=myAddresses.begin(); i!=myAddresses.end(); i++) {
00281         if ((*i)->isFileName() && (*i)->isSet()) {
00282             StringTokenizer st((*i)->getString(), ";, ", true);
00283             std::string conv;
00284             while (st.hasNext()) {
00285                 if (conv.length()!=0) {
00286                     conv += ',';
00287                 }
00288                 std::string tmp = st.next();
00289                 if (!FileHelpers::isAbsolute(tmp)) {
00290                     tmp = FileHelpers::getConfigurationRelative(configuration, tmp);
00291                 }
00292                 conv += tmp;
00293             }
00294             (*i)->set(conv);
00295         }
00296     }
00297 }

void OptionsCont::reportDoubleSetting ( const std::string & arg ) const throw () [private]

Reports an error that the option has already been set.

Using the given option name, an error string is generated and reported to MsgHandler-error instance.

Parameters:

[in] name The name of the option that was already set

Definition at line 347 of file OptionsCont.cpp.

References MsgHandler::getErrorInstance(), getSynonymes(), and MsgHandler::inform().

Referenced by set().

00347                                                                    {
00348     std::vector<std::string> synonymes = getSynonymes(arg);
00349     std::ostringstream s;
00350     s << "A value for the option '" + arg + "' was already set.\n Possible synonymes: ";
00351     for (std::vector<std::string>::iterator i=synonymes.begin(); i!=synonymes.end();) {
00352         s << (*i);
00353         i++;
00354         if (i!=synonymes.end()) {
00355             s << ", ";
00356         }
00357     }
00358     MsgHandler::getErrorInstance()->inform(s.str());
00359 }

void OptionsCont::resetWritable ( ) throw ()

Resets all options to be writeable.

An option is writable after initialisation, but as soon as it gets set, it is no longer writeable. This method resets the writable-flag of all known options.

Definition at line 380 of file OptionsCont.cpp.

References myAddresses.

Referenced by OptionsIO::getOptions(), and main().

00380                                    {
00381     for (ItemAddressContType::iterator i=myAddresses.begin(); i!=myAddresses.end(); i++) {
00382         (*i)->myAmWritable = true;
00383     }
00384 }

bool OptionsCont::set	(	const std::string &	name,
		bool	value
	)			throw (InvalidArgument)

Sets the given boolean value for the named option (Option_Bool only).

The option is retrieved from the container, first, what yields in an InvalidArgument exception for not known options.

If the option is not writable (was set before), an error is generated using reportDoubleSetting, and false is returned. Otherwise, the option is told to set the given value using Option::set(bool). Possible problems herein are caught and reported to the error-handler, yielding in returning false.

If the new value could be set, true is returned.

Parameters:

`[in]`	name	The name of the option to set
`[in]`	value	The value to set

Returns:: Whether the value could be set

Exceptions:

InvalidArgument

If the option does not exist

See also:: reportDoubleSetting
Option::set(const std::string &)

Definition at line 210 of file OptionsCont.cpp.

References MsgHandler::getErrorInstance(), getSecure(), MsgHandler::inform(), Option::isBool(), Option::isWriteable(), reportDoubleSetting(), and Option::set().

00210                                                                          {
00211     Option *o = getSecure(name);
00212     if (!o->isBool()) {
00213         throw InvalidArgument("The option '" + name + "' is not a boolean attribute and requires an argument.");
00214     }
00215     if (!o->isWriteable()) {
00216         reportDoubleSetting(name);
00217         return false;
00218     }
00219     try {
00220         if (!o->set(value)) {
00221             return false;
00222         }
00223     } catch (InvalidArgument &e) {
00224         MsgHandler::getErrorInstance()->inform("While processing option '" + name + "':\n " + e.what());
00225         return false;
00226     }
00227     return true;
00228 }

bool OptionsCont::set	(	const std::string &	name,
		const std::string &	value
	)			throw (InvalidArgument)

Sets the given value for the named option.

The option is retrieved from the container, first, what yields in a InvalidArgument exception for not known options.

If the option is not writable (was set before), an error is generated using reportDoubleSetting, and false is returned. Otherwise, the option is told to set the given value using Option::set. Possible problems herein are caught and reported to the error-handler, yielding in returning false.

If the new value could be set, true is returned.

Parameters:

`[in]`	name	The name of the option to set
`[in]`	value	The value to set

Returns:: Whether the value could be set

Exceptions:

InvalidArgument

If the option does not exist

See also:: reportDoubleSetting
Option::set(const std::string &)

Definition at line 191 of file OptionsCont.cpp.

References MsgHandler::getErrorInstance(), getSecure(), MsgHandler::inform(), Option::isWriteable(), reportDoubleSetting(), and Option::set().

Referenced by NLBuilder::build(), OptionsParser::check(), NIOptionsIO::checkOptions(), GUILoadThread::initOptions(), main(), and OptionsLoader::setSecure().

00191                                                                                      {
00192     Option *o = getSecure(name);
00193     if (!o->isWriteable()) {
00194         reportDoubleSetting(name);
00195         return false;
00196     }
00197     try {
00198         if (!o->set(value)) {
00199             return false;
00200         }
00201     } catch (InvalidArgument &e) {
00202         MsgHandler::getErrorInstance()->inform("While processing option '" + name + "':\n " + e.what());
00203         return false;
00204     }
00205     return true;
00206 }

void OptionsCont::setAdditionalHelpMessage ( const std::string & add ) throw ()

Sets an additional message to be printed at the begin of the help screen.

Parameters:

[in] example Some additional information about how to use the application

Definition at line 441 of file OptionsCont.cpp.

References myAdditionalMessage.

Referenced by fillOptions().

00441                                                                   {
00442     myAdditionalMessage = add;
00443 }

void OptionsCont::setApplicationDescription ( const std::string & appDesc ) throw ()

Sets the application description.

Parameters:

[in] appDesc A description of the application

Definition at line 429 of file OptionsCont.cpp.

References myAppDescription.

Referenced by main().

00429                                                                        {
00430     myAppDescription = appDesc;
00431 }

void OptionsCont::setApplicationName	(	const std::string &	appName,
		const std::string &	fullName
	)			throw ()

Sets the application name.

Parameters:

`[in]`	name	The name of the excutable
`[in]`	v	The name of the executable with version information

Definition at line 421 of file OptionsCont.cpp.

References myAppName, and myFullName.

Referenced by main().

00422                                                                    {
00423     myAppName = appName;
00424     myFullName = fullName;
00425 }

void OptionsCont::splitLines	(	std::ostream &	os,
		std::string	what,
		size_t	offset,
		size_t	nextOffset
	)			throw () `[private]`

Writes the given string 'formatted'.

The given string is split so that no word-wrapping occurs at line ends. The text is wrapped at ';' or ' '.

Parameters:

`[in]`	os	The stream to write the text into
`[in]`	what	The text to write
`[in]`	offset	?
`[in]`	nextOffset	?

Todo:: Describe parameter

Definition at line 454 of file OptionsCont.cpp.

Referenced by printHelp().

00455                                                                   {
00456     while (what.length()>0) {
00457         if (what.length()>79-offset) {
00458             size_t splitPos = what.rfind(';', 79-offset);
00459             if (splitPos==std::string::npos) {
00460                 splitPos = what.rfind(' ', 79-offset);
00461             } else {
00462                 splitPos++;
00463             }
00464             if (splitPos!=std::string::npos) {
00465                 os << what.substr(0, splitPos) << std::endl;
00466                 what = what.substr(splitPos);
00467                 for (size_t r=0; r<nextOffset+1; ++r) {
00468                     os << ' ';
00469                 }
00470             } else {
00471                 os << what;
00472                 what = "";
00473             }
00474             offset = nextOffset;
00475         } else {
00476             os << what;
00477             what = "";
00478         }
00479     }
00480     os << std::endl;
00481 }

void OptionsCont::writeConfiguration	(	std::ostream &	os,
		bool	filled,
		bool	complete,
		bool	addComments
	)			throw ()

Writes the configuration.

The configuration is written as XML into the given stream, allowing to reload it on a next run.

Parameters:

`[in]`	os	The stream to write the configuration into
`[in]`	filled	Whether only set (and not default) options shall be written
`[in]`	complete	Whether all options shall be written
`[in]`	addComments	Whether comments (option descriptions) shall be written

Definition at line 632 of file OptionsCont.cpp.

References Option::getDescription(), getSecure(), Option::getValueString(), Option::isDefault(), Option::isSet(), mySubTopicEntries, and mySubTopics.

Referenced by processMetaOptions(), and writeXMLHeader().

00633                                                                          {
00634     std::vector<std::string>::const_iterator i, j;
00635     os << "<configuration>" << std::endl << std::endl;
00636     for (i=mySubTopics.begin(); i!=mySubTopics.end(); ++i) {
00637         std::string subtopic = *i;
00638         if (subtopic=="Configuration") {
00639             continue;
00640         }
00641         for (size_t k=0; k<subtopic.length(); ++k) {
00642             if (subtopic[k]==' ') {
00643                 subtopic[k] = '_';
00644             }
00645             if (subtopic[k]>='A'&&subtopic[k]<='Z') {
00646                 subtopic[k] = subtopic[k] - 'A' + 'a';
00647             }
00648         }
00649         const std::vector<std::string> &entries = mySubTopicEntries[*i];
00650         bool hadOne = false;
00651         for (j=entries.begin(); j!=entries.end(); ++j) {
00652             Option *o = getSecure(*j);
00653             bool write = complete || (filled&&!o->isDefault());
00654             if (!write) {
00655                 continue;
00656             }
00657             if (!hadOne) {
00658                 os << "    <" << subtopic << ">" << std::endl;
00659             }
00660             // add the comment if wished
00661             if (addComments) {
00662                 os << "        <!-- " << o->getDescription() << " -->" << std::endl;
00663             }
00664             // write the option and the value (if given)
00665             os << "        <" << *j << " value=\"";
00666             if (o->isSet()) {
00667                 os << o->getValueString();
00668             }
00669             os << "\"/>" << std::endl;
00670             // append an endline if a comment was printed
00671             if (addComments) {
00672                 os << std::endl;
00673             }
00674             hadOne = true;
00675         }
00676         if (hadOne) {
00677             os << "    </" << subtopic << ">" << std::endl << std::endl;
00678         }
00679     }
00680     os << "</configuration>" << std::endl;
00681 }

void OptionsCont::writeXMLHeader	(	std::ostream &	os,
		const bool	writeConfig = `true`
	)			throw ()

Writes a standard XML header, optionally including the configuration.

The header consists of the xml-declaration, followed by a note which contains the current date and time and optionally the application configuration (set values).

Parameters:

`[in]`	os	The stream to write the header into
`[in]`	writeConfig	Whether the current configuration shall be written, too

Definition at line 685 of file OptionsCont.cpp.

References myFullName, and writeConfiguration().

Referenced by OutputDevice::writeXMLHeader().

00685                                                                           {
00686     time_t rawtime;
00687     char buffer [80];
00688 
00689     os << "<?xml version=\"1.0\"?>\n\n";
00690     time(&rawtime);
00691     strftime(buffer, 80, "<!-- generated on %c by ", localtime(&rawtime));
00692     os << buffer << myFullName << "\n";
00693     if (writeConfig) {
00694         writeConfiguration(os, true, false, false);
00695     }
00696     os << "-->\n\n";
00697 }

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	os,
		const OptionsCont &	oc
	)			`[friend]`

Output operator.

Generates the output used when current option values shall be printed.

Parameters:

`[in]`	os	The stream to write into
`[in]`	oc	The options to print

Returns:: The stream to write into

Definition at line 245 of file OptionsCont.cpp.

00245                                                   {
00246     std::vector<std::string> done;
00247     os << "Options set:" << std::endl;
00248     for (OptionsCont::KnownContType::const_iterator i=oc.myValues.begin();
00249             i!=oc.myValues.end(); i++) {
00250         std::vector<std::string>::iterator j = find(done.begin(), done.end(), (*i).first);
00251         if (j==done.end()) {
00252             std::vector<std::string> synonymes = oc.getSynonymes((*i).first);
00253             if (synonymes.size()!=0) {
00254                 os << (*i).first << " (";
00255                 for (j=synonymes.begin(); j!=synonymes.end(); j++) {
00256                     if (j!=synonymes.begin()) {
00257                         os << ", ";
00258                     }
00259                     os << (*j);
00260                 }
00261                 os << ")";
00262             } else {
00263                 os << (*i).first;
00264             }
00265             if ((*i).second->isSet()) {
00266                 os << ": " << (*i).second->getValueString() << std::endl;
00267             } else {
00268                 os << ": <INVALID>" << std::endl;
00269             }
00270             done.push_back((*i).first);
00271             copy(synonymes.begin(), synonymes.end(), back_inserter(done));
00272         }
00273     }
00274     return os;
00275 }