Parse sectioned INI file or HDF5 or command line, provide the results as dictionary. More...

#include <params.hpp>

Inheritance diagram for alps::params_ns::params:

Collaboration diagram for alps::params_ns::params:

Classes
class	archive_conflict
	Exception type: attempt to restore from 2 archives. More...

struct	not_restored
	Exception type: the object was not restored from archive. More...

Public Member Functions
	params ()
	Default ctor: creates an empty parameters object. More...

	params (const std::string &inifile)
	Constructor from INI file. More...

	params (int argc, const char const argv, const char *hdf5_path="/parameters")
	Constructor from command line and parameter files. More...

std::string	get_argv0 () const
	Access to argv[0] (returns empty string if unknown) More...

std::string	get_ini_name (int n) const
	Access to ini file names (if any); returns empty string if out of range. More...

int	get_ini_name_count () const
	Returns the number of ini file names. More...

std::string	get_origin_name () const ALPS_DEPRECATED
	Convenience method: returns the "origin name". More...

bool	is_restored () const
	Conveninece method: true if the object was restored from an archive. More...

std::string	get_archive_name () const
	Convenience method: returns the archive name the object has been restored from, or throws. More...

bool	ok () const
	No-errors status. More...

bool	has_missing () const
	True if there are missing or wrong-type parameters. More...

bool	defaulted (const std::string &name) const
	True if the parameter acquired its value by default. More...

bool	supplied (const std::string &name) const
	True if the parameter is supplied via file or cmdline. More...

bool	has_unused (std::ostream &out) const
	True if there are parameters supplied but not defined; prints them out. More...

bool	has_unused (std::ostream &out, const std::string &subsection) const
	True if there are parameters supplied but not defined in a subsection; prints them out. More...

bool	has_missing (std::ostream &out) const
	True if there are missing or wrong-type parameters; prints the message to that effect. More...

bool	help_requested () const
	True if user requested help. More...

bool	help_requested (std::ostream &) const
	True if user requested help; print it to the supplied stream. More...

std::ostream &	print_help (std::ostream &) const
	Print help to the given stream. More...

bool	operator== (const params &rhs) const
	Returns true if the objects are identical. More...

bool	defined (const std::string &name) const
	Check whether a parameter was ever defined. More...

template<typename T >
params &	define (const std::string &name, const std::string &descr)
	Defines a parameter; returns false on error, and records the error in the object. More...

template<typename T >
params &	define (const std::string &name, const T &defval, const std::string &descr)
	Defines a parameter with a default; returns false on error, and records the error in the object. More...

params &	define (const std::string &name, const std::string &descr)
	Defines a flag (boolean option with default of `false`) More...

params &	description (const std::string &message)
	Sets a description for the help message and introduces "--help" flag (if not already defined) More...

const std::string	get_descr (const std::string &name) const
	Returns a string describing the parameter (or an empty string) More...

void	save (alps::hdf5::archive &) const
	Saves parameter object to an archive. More...

void	load (alps::hdf5::archive &)
	Loads parameter object form an archive. More...

Public Member Functions inherited from alps::params_ns::dictionary
const_iterator	begin () const
	Const-iterator to the beginning of the contained map. More...

const_iterator	end () const
	Const-iterator to the end of the contained map. More...

virtual	~dictionary ()
	Virtual destructor to make dictionary inheritable. More...

bool	empty () const
	True if the cdictionary does not contain elements (even empty ones) More...

std::size_t	size () const
	Size of the dictionary (including empty elements) More...

void	erase (const std::string &key)
	Erase an element if it exists. More...

value_type &	operator[] (const std::string &key)
	Access with intent to assign. More...

const value_type &	operator[] (const std::string &key) const
	Read-only access. More...

const_iterator	find (const std::string &key) const
	Obtain read-only iterator to a name. More...

bool	exists (const std::string &key) const
	Check if a key exists and has a value (without creating the key) More...

template<typename T >
bool	exists (const std::string &key) const
	Check if a key exists and has a value of a particular type (without creating the key) More...

bool	equals (const dictionary &rhs) const
	Compare two dictionaries (true if all entries are of the same type and value) More...

void	save (alps::hdf5::archive &ar) const
	Save the dictionary to an archive. More...

void	load (alps::hdf5::archive &ar)
	Load the dictionary from an archive. More...

Friends
void	swap (params &p1, params &p2)

std::ostream &	operator<< (std::ostream &, const params &)
	Prints parameters to a stream in an unspecified format. More...

Additional Inherited Members
Public Types inherited from alps::params_ns::dictionary
typedef dict_value	value_type

typedef map_type::const_iterator	const_iterator

Detailed Description

Parse sectioned INI file or HDF5 or command line, provide the results as dictionary.

Default-constructed params object cannot be re-associated with a file; therefore, is 100% equivalent to dictionary ("is-a" dictionary).
Lexing of the file and of the command line occurs at construction. Command line overrides the file. INI file name is taken from the command line.
Parsing of a specific parameter occurs at the time of its type definition. There is no way for parameters to appear after the file and cmdline are read.

Definition at line 84 of file params.hpp.

Constructor & Destructor Documentation

alps::params_ns::params::params ( )

inline

Default ctor: creates an empty parameters object.

Definition at line 129 of file params.hpp.

alps::params_ns::params::params ( const std::string & inifile )

Constructor from INI file.

Reads the provided file (in INI format). Automatically defines --help flag.

Parameters

inifile Path to the INI file

Definition at line 105 of file params.cpp.

alps::params_ns::params::params	(	int	argc,
		const char const	argv,
		const char *	hdf5_path = `"/parameters"`
	)

Constructor from command line and parameter files.

Tries to see if the file is an HDF5, in which case restores the object from the HDF5 file, ignoring the command line. Automatically defines --help flag.

Parameters

argc	Number of command line arguments (as in `main(int argc, char** argv)`)
argv	Array of pointers to command line arguments (as in `main(int argc, char** argv)`)
hdf5_path	path to HDF5 dataset containing the saved parameter object (NULL if this functionality is not needed)

The parameters are supplied in the --key=value format; the double dash (--) can be shortened to a single dash (-) or omitted. The =value part may be omitted, in which case it is interpreted as =false, and the key must be preceded by at least one dash (-).

If an argument is not recognized as a key-value pair (that is, it does not contain the = character and does not start with -) it is interpreted as a file name.

If a double-dash argument (--) is encountered, it is skipped, and all arguments following it are interpreted as file names.

The files are either HDF5-formatted archives or INI-formatted files. INI file can be sectoned by [section] headers: the key some_key in section [some_section] is interpreted as a key some_section.some_key.

The command line is parsed in the following way:

The whole command line is scanned.
If an (HDF5) archive file name is present, the parameters object is loaded from the archive.
If there is another archive file name, an exception of type alps::params::archive_conflict is thrown.
All INI files are read in the order given.
The command line arguments are read.
1. If a key is encountered more than once, the latter occurence silently overrides the former. Thus, the values supplied in the command line override values from INI files and archives.
2. If a key was present and define<T>()d in the archive, the new value must be parsable as type T; otherwise an exception of type alps::params_ns::dictionary::value_mismatch is thrown.

Definition at line 114 of file params.cpp.

Member Function Documentation

bool alps::params_ns::params::defaulted ( const std::string & name ) const

inline

True if the parameter acquired its value by default.

Definition at line 142 of file params_impl.hpp.

template<typename T >

params & alps::params_ns::params::define	(	const std::string &	name,
		const std::string &	descr
	)

Defines a parameter; returns false on error, and records the error in the object.

Definition at line 120 of file params_impl.hpp.

template<typename T >

params & alps::params_ns::params::define	(	const std::string &	name,
		const T &	defval,
		const std::string &	descr
	)

Defines a parameter with a default; returns false on error, and records the error in the object.

Definition at line 129 of file params_impl.hpp.

params& alps::params_ns::params::define	(	const std::string &	name,
		const std::string &	descr
	)

inline

Defines a flag (boolean option with default of false)

Definition at line 290 of file params.hpp.

bool alps::params_ns::params::defined ( const std::string & name ) const

inline

Check whether a parameter was ever defined.

That is, calling define() is unnecessary and will throw if type does not match.

Definition at line 147 of file params_impl.hpp.

params & alps::params_ns::params::description ( const std::string & message )

Sets a description for the help message and introduces "--help" flag (if not already defined)

Definition at line 149 of file params.cpp.

std::string alps::params_ns::params::get_archive_name ( ) const

Convenience method: returns the archive name the object has been restored from, or throws.

Definition at line 143 of file params.cpp.

std::string alps::params_ns::params::get_argv0 ( ) const

Access to argv[0] (returns empty string if unknown)

Definition at line 138 of file params.cpp.

const std::string alps::params_ns::params::get_descr ( const std::string & name ) const

Returns a string describing the parameter (or an empty string)

Definition at line 349 of file params.cpp.

std::string alps::params_ns::params::get_ini_name ( int n ) const

Access to ini file names (if any); returns empty string if out of range.

Definition at line 132 of file params.cpp.

int alps::params_ns::params::get_ini_name_count ( ) const

Returns the number of ini file names.

Definition at line 127 of file params.cpp.

std::string alps::params_ns::params::get_origin_name ( ) const

inline

Convenience method: returns the "origin name".

Returns: (parameter_file_name || restart_file name || program_name || "")

Deprecated:: Use alps::params_ns::origin_name(const params&) instead, also available as alps::origin_name(const params&).

Definition at line 162 of file params_impl.hpp.

bool alps::params_ns::params::has_missing ( ) const

inline

True if there are missing or wrong-type parameters.

Definition at line 243 of file params.hpp.

bool alps::params_ns::params::has_missing ( std::ostream & out ) const

True if there are missing or wrong-type parameters; prints the message to that effect.

Definition at line 242 of file params.cpp.

bool alps::params_ns::params::has_unused ( std::ostream & out ) const

True if there are parameters supplied but not defined; prints them out.

Definition at line 179 of file params.cpp.

bool alps::params_ns::params::has_unused	(	std::ostream &	out,
		const std::string &	subsection
	)		const

True if there are parameters supplied but not defined in a subsection; prints them out.

Parameters

out	Stream to print the list of supplied, but unused parameters
subsection	The subsection to look into; empty string means "top level" (or "anonymous") subsection.

Definition at line 174 of file params.cpp.

bool alps::params_ns::params::help_requested ( ) const

True if user requested help.

Definition at line 230 of file params.cpp.

bool alps::params_ns::params::help_requested ( std::ostream & out ) const

True if user requested help; print it to the supplied stream.

Definition at line 235 of file params.cpp.

bool alps::params_ns::params::is_restored ( ) const

inline

Conveninece method: true if the object was restored from an archive.

Definition at line 234 of file params.hpp.

void alps::params_ns::params::load ( alps::hdf5::archive & ar )

Loads parameter object form an archive.

Definition at line 398 of file params.cpp.

bool alps::params_ns::params::ok ( ) const

inline

No-errors status.

Definition at line 240 of file params.hpp.

bool alps::params_ns::params::operator== ( const params & rhs ) const

Returns true if the objects are identical.

Definition at line 355 of file params.cpp.

std::ostream & alps::params_ns::params::print_help ( std::ostream & out ) const

Print help to the given stream.

Returns: the stream

Definition at line 184 of file params.cpp.

void alps::params_ns::params::save ( alps::hdf5::archive & ar ) const

Saves parameter object to an archive.

Definition at line 370 of file params.cpp.

bool alps::params_ns::params::supplied ( const std::string & name ) const

inline

True if the parameter is supplied via file or cmdline.

Definition at line 137 of file params_impl.hpp.

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	s,
		const params &	p
	)

friend

Prints parameters to a stream in an unspecified format.

Definition at line 482 of file params.cpp.

void swap	(	params &	p1,
		params &	p2
	)

friend

Definition at line 152 of file params_impl.hpp.

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

Classes

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation