A class to parse Interfile headers. More...

#include "stir/KeyParser.h"

Inheritance diagram for stir::KeyParser:

[legend]

Public Member Functions
bool	parse (std::istream &f, const bool write_warnings=true)
	parse() returns false if there is some error, true otherwise More...

bool	parse (const char *const filename, const bool write_warnings=true)
	parse() returns false if there is some error, true otherwise More...

bool	parse (const std::string &, const bool write_warnings=true)

void	add_key (const std::string &keyword, float *variable_ptr)
	add a keyword. When parsing, parse its value as a float and put it in *variable_ptr

void	add_vectorised_key (const std::string &keyword, std::vector< float > *variable_ptr)
	add a vectorised keyword. When parsing, parse its value as a float and put it in (*variable_ptr)[current_index]

void	add_key (const std::string &keyword, double *variable_ptr)
	add a keyword. When parsing, parse its value as a double and put it in *variable_ptr

void	add_vectorised_key (const std::string &keyword, std::vector< double > *variable_ptr)
	add a vectorised keyword. When parsing, parse its value as a double and put it in (*variable_ptr)[current_index]

void	add_vectorised_key (const std::string &keyword, std::vector< std::vector< double >> *variable_ptr)
	add a vectorised keyword. When parsing, parse its value as a list of doubles and put it in (*variable_ptr)[current_index]

void	add_key (const std::string &keyword, int *variable_ptr)
	add a keyword. When parsing, parse its value as a int and put it in *variable_ptr

void	add_key (const std::string &keyword, std::vector< int > *variable_ptr)
	add a keyword. When parsing, parse its value as a int and put it in *variable_ptr

void	add_vectorised_key (const std::string &keyword, std::vector< int > *variable_ptr)
	add a vectorised keyword. When parsing, parse its value as a int and put it in (*variable_ptr)[current_index]

void	add_vectorised_key (const std::string &keyword, std::vector< std::vector< int >> *variable_ptr)
	add a vectorised keyword. When parsing, parse its value as a list of ints and put it in (*variable_ptr)[current_index]

void	add_key (const std::string &keyword, long int *variable_ptr)
	add a keyword. When parsing, parse its value as a int and put it in *variable_ptr

void	add_key (const std::string &keyword, unsigned int *variable_ptr)
	add a keyword. When parsing, parse its value as a int and put it in *variable_ptr

void	add_vectorised_key (const std::string &keyword, std::vector< unsigned int > *variable)
	add a vectorised keyword. When parsing, parse its value as an unsigned int and put it in (*variable_ptr)[current_index]

void	add_key (const std::string &keyword, unsigned long *variable_ptr)
	add a keyword. When parsing, parse its value as an unsigned long and put it in *variable_ptr

void	add_vectorised_key (const std::string &keyword, std::vector< unsigned long > *variable_ptr)
	add a vectorised keyword. When parsing, parse its value as an unsigned long and put it in (*variable_ptr)[current_index]

void	add_key (const std::string &keyword, bool *variable_ptr)
	add a keyword. When parsing, parse its value as a int and put the bool value in *variable_ptr More...

void	add_key (const std::string &keyword, std::vector< double > *variable_ptr)
	add a keyword. When parsing, parse its value as a list of doubles and put its value in *variable_ptr

void	add_key (const std::string &keyword, std::vector< std::string > *variable_ptr)
	add a keyword. When parsing, parse its value as a list of comma-separated strings and put its value in *variable_ptr

void	add_key (const std::string &keyword, Array< 2, float > *variable_ptr)
	add a keyword. When parsing, parse its value as a 2d array of floats and put its value in *variable_ptr

void	add_key (const std::string &keyword, Array< 3, float > *variable_ptr)
	add a keyword. When parsing, parse its value as a 3d array of floats and put its value in *variable_ptr

void	add_key (const std::string &keyword, BasicCoordinate< 3, float > *variable_ptr)
	add a keyword. When parsing, parse its value as a 3d BasicCoordinate of floats and put its value in *variable_ptr

void	add_key (const std::string &keyword, BasicCoordinate< 3, Array< 3, float >> *variable_ptr)
	add a keyword. When parsing, parse its value as a 3d BasicCoordinate of a 3d array of floats and put its value in *variable_ptr

void	add_key (const std::string &keyword, std::string *variable_ptr)

void	add_vectorised_key (const std::string &keyword, std::vector< std::string > *variable_ptr)
	add a vectorised keyword. When parsing, parse its value as a string and put it in (*variable_ptr)[current_index] More...

void	add_key (const std::string &keyword, int variable_ptr, const ASCIIlist_type const list_of_values)
	add a keyword. When parsing, its string value is checked against a list of strings. The corresponding index is stored in variable_ptr. More...

void	ignore_key (const std::string &keyword)
	Add keyword this is just ignored by the parser.

void	add_start_key (const std::string &keyword)
	add keyword that has to occur before all others More...

void	add_stop_key (const std::string &keyword)
	add a keyword that when encountered, will stop the parsing

template<typename ParsingClass >
void	add_parsing_key (const std::string &keyword, ParsingClass **parsed_object_ptr_ptr)
	add keyword corresponding to an object that will parse the next keys itself More...

template<typename ParsingClass >
void	add_parsing_key (const std::string &keyword, shared_ptr< ParsingClass > *parsed_object_ptr_ptr)
	add keyword corresponding to an object that will parse the next keys itself More...

bool	remove_key (const std::string &keyword)
	Removes a key from the kep map. More...

void	add_alias_key (const std::string &keyword, const std::string &alias, bool deprecated_key=true)
	Add an alias for keyword. More...

void	print_keywords_to_stream (std::ostream &) const
	Prints all keywords (in random order) to the stream.

virtual std::string	parameter_info () const
	Returns a string with keywords and their values. More...

virtual void	ask_parameters ()
	Ask interactively for values for all keywords. More...

int	find_in_ASCIIlist (const std::string &, const ASCIIlist_type &list_of_values)
	returns the index of a string in 'list_of_values', -1 if not found More...

void	start_parsing ()
	callback function to start parsing, has to be set by first keyword

void	stop_parsing ()
	to stop parsing

void	do_nothing ()
	callback function for keys which do not do anything

void	set_variable ()
	callback function that sets the variable to the value given as the value of the keyword More...

void	set_parsing_object ()
	callback function that sets the variable by calling the parser (as stored by add_parsing_key()), with argument the value of the keyword More...

void	set_shared_parsing_object ()
	callback function that sets the shared_ptr variable by calling the parser (as stored by add_parsing_key()), with argument the value of the keyword More...

Protected Types
typedef void(KeyParser::*	KeywordProcessor) ()

Protected Member Functions
virtual bool	post_processing ()
	This will be called at the end of the parsing. More...

virtual std::string	standardise_keyword (const std::string &keyword) const
	convert 'rough' keyword into a standardised form More...

virtual std::string	get_keyword (const std::string &) const
	gets a keyword from a string More...

void	add_key (const std::string &keyword, KeyArgument::type t, KeywordProcessor function, void variable=0, const ASCIIlist_type const list=0)
	add a keyword to the list, together with its call_back function More...

void	add_key (const std::string &keyword, KeyArgument::type t, KeywordProcessor function, void variable, const int vectorised_key_level, const ASCIIlist_type const list=0)
	add a keyword to the list, together with its call_back function More...

void	add_key (const std::string &keyword, KeyArgument::type t, void variable, const ASCIIlist_type const list=0)
	version that defaults 'function' to set_variable More...

void	add_key (const std::string &keyword, KeyArgument::type t, void variable, const int vectorised_key_level, const ASCIIlist_type const list=0)
	version that defaults 'function' to set_variable More...

Friends
class	map_element

Detailed Description

A class to parse Interfile headers.

Currently, Interfile 3.3 parsing rules are hard-coded, with some extensions. Note that some functions such as get_keyword() are virtual such that a derived class could use non-Interfile parsing (but this might need more work).

KeyParser reads input line by line and parses each line separately. It allows for '\r' at the end of the line (as in files originating in DOS/Windows). When the line ends with a backslash '\', the next line will just be appended to the current one. That is, '\' acts as continuation marker.

Lines can have arbitrary length.

A special facility is provided for using the value of environment variables: after reading the whole line, the text is checked for occurences of the form ${some_text}$ . These text strings are then replaced by the value of the corresponding environment variables (using the std::getenv function).

Warning: For end-of-line continuation, the backslash HAS to be the last character. Even spaces after it will stop the 'continuation'.; The use of the [*] index for vectorised keys is NOT supported.

Main problem: when non-trivial callback functions have to be used, you need to do it via a derived class (as KeyParser requires pointers to member functions.)

Warning: As KeyParser::add_key stores pointers to the variables where you want your results, it is somewhat dangerous to copy a KeyParser object. That is, its keymap will still point to the same variables.

Todo:: add checking functions in the map, as in

add_key("my key",&my_value, check_positive);

Todo:: add facilities for checking (while parsing) if a keyword was present before the current one

Member Function Documentation

◆ parse() [1/3]

bool stir::KeyParser::parse	(	std::istream &	f,
		const bool	write_warnings = `true`
	)

parse() returns false if there is some error, true otherwise

if write_warnings is false, warnings about undefined keywords will be supressed.

Referenced by stir::CListModeDataPENN::CListModeDataPENN(), stir::CListModeDataROOT::CListModeDataROOT(), stir::PoissonLLReconstructionTests< target_type >::construct_projector_pair(), stir::RigidObject3DMotionFromPolaris::post_processing(), stir::ScatterEstimation::post_processing(), distributed::receive_and_construct_exam_and_proj_data_info_ptr(), and stir::TimeFrameDefinitions::TimeFrameDefinitions().

◆ parse() [2/3]

bool stir::KeyParser::parse	(	const char *const	filename,
		const bool	write_warnings = `true`
	)

parse() returns false if there is some error, true otherwise

if write_warnings is false, warnings about undefined keywords will be supressed.

References stir::warning().

◆ parse() [3/3]

bool stir::KeyParser::parse	(	const std::string &	s,
		const bool	write_warnings = `true`
	)

if write_warnings is false, warnings about undefined keywords will be supressed.

◆ add_key() [1/7]

void stir::KeyParser::add_key	(	const std::string &	keyword,
		bool *	variable_ptr
	)

add a keyword. When parsing, parse its value as a int and put the bool value in *variable_ptr

The integer should be 0 or 1, corresponding to false and true resp.

◆ add_key() [2/7]

void stir::KeyParser::add_key	(	const std::string &	keyword,
		std::string *	variable_ptr
	)

The 'value' can contain spaces.

◆ add_vectorised_key()

void stir::KeyParser::add_vectorised_key	(	const std::string &	keyword,
		std::vector< std::string > *	variable_ptr
	)

add a vectorised keyword. When parsing, parse its value as a string and put it in (*variable_ptr)[current_index]

The 'value' can contain spaces.

◆ add_key() [3/7]

void stir::KeyParser::add_key	(	const std::string &	keyword,
		int *	variable_ptr,
		const ASCIIlist_type *const	list_of_values
	)

add a keyword. When parsing, its string value is checked against a list of strings. The corresponding index is stored in variable_ptr.

If no match is found, a warning message is issued and *variable_ptr is set to -1.

◆ add_start_key()

void stir::KeyParser::add_start_key ( const std::string & keyword )

add keyword that has to occur before all others

Example of such a key: INTERFILE

References start_parsing().

◆ add_parsing_key() [1/2]

template<typename ParsingClass >

void stir::KeyParser::add_parsing_key	(	const std::string &	keyword,
		ParsingClass **	parsed_object_ptr_ptr
	)

inline

add keyword corresponding to an object that will parse the next keys itself

When this keyword is encountered during parsing, the parser ParsingClass::read_registered_object(name) is called, with 'name' set to to the value of the keyword.

ParsingClass has to be derived from RegisteredObject (strictly speaking it only has to be derived from Object, and provide a static function void read_registered_object(string&)).

Example of usage:

struct SomeReconstruction
{
  SomeReconstruction();
  ImageProcessor<3,float>* filter_ptr;
  double beta;
  KeyParser parser;
};
SomeReconstruction::SomeReconstruction()
{
      beta = 1;
      filter_ptr = 0;
      parser.add_start_key("SomeReconstructionParameters");
      parser.add_key("beta ", &beta);
      parser.add_parsing_key("MAP a la MRP filter type", &filter_ptr);
      parser.add_stop_key("END SomeReconstruction Parameters");
}

The .par file then would look as follows

  SomeReconstructionParameters :=
    beta := 0.001
    MAP a la MRP filter type := Median
    ; keywords here appropriate to a Median ImageFilter
  End SomeReconstruction Parameters:= ;

Referenced by stir::BackProjectorByBinUsingSquareProjMatrixByBin::actual_back_project(), stir::ChainedDataProcessor< DataT >::ChainedDataProcessor(), stir::CListModeDataPENN::CListModeDataPENN(), stir::CListModeDataROOT::CListModeDataROOT(), stir::FilterRootPrior< DataT >::compute_gradient(), stir::PoissonLLReconstructionTests< target_type >::construct_projector_pair(), stir::ForwardProjectorByBin::initialise_keymap(), stir::BackProjectorByBin::initialise_keymap(), stir::ScatterEstimation::initialise_keymap(), and stir::ScatterEstimation::post_processing().

◆ add_parsing_key() [2/2]

template<typename ParsingClass >

void stir::KeyParser::add_parsing_key	(	const std::string &	keyword,
		shared_ptr< ParsingClass > *	parsed_object_ptr_ptr
	)

inline

add keyword corresponding to an object that will parse the next keys itself

As above, but with a shared_ptr

◆ remove_key()

bool stir::KeyParser::remove_key ( const std::string & keyword )

Removes a key from the kep map.

Returns: true if it was found, false otherwise

References stir::warning().

◆ add_alias_key()

void stir::KeyParser::add_alias_key	(	const std::string &	keyword,
		const std::string &	alias,
		bool	deprecated_key = `true`
	)

Add an alias for keyword.

If deprecated_key if true, a warning will be written when the alias is encountered.

parameter_info() will use the keyword, not the alias.

Referenced by stir::CListModeDataROOT::CListModeDataROOT().

◆ parameter_info()

string stir::KeyParser::parameter_info ( ) const

virtual

Returns a string with keywords and their values.

Keywords are listed in the order they are inserted in the keymap (except for start and stop keys which are listed first and last).

References start_parsing(), and stop_parsing().

◆ ask_parameters()

void stir::KeyParser::ask_parameters ( )

virtual

Ask interactively for values for all keywords.

Keywords are asked in the order they are inserted in the keymap.

Todo:: any consistency checks are currently done by post_processing() at the end of the parsing. It should be possible to have checks after every question such that it can be repeated.

Bug:: breaks with for 'vectorised' keys.

References do_nothing(), start_parsing(), stop_parsing(), and stir::warning().

◆ find_in_ASCIIlist()

int stir::KeyParser::find_in_ASCIIlist	(	const std::string &	par_ascii,
		const ASCIIlist_type &	list_of_values
	)

returns the index of a string in 'list_of_values', -1 if not found

Implementation note: this function is non-static because it uses standardise_keyword

◆ post_processing()

virtual bool stir::KeyParser::post_processing ( )

inlineprotectedvirtual

This will be called at the end of the parsing.

Returns: false if everything OK, true if not

Todo:

return Succeeded instead.

rename to post_parsing()

Reimplemented in stir::InterfilePDFSHeader, stir::InterfileImageHeader, stir::InterfileHeader, and stir::InterfilePDFSHeaderSPECT.

◆ standardise_keyword()

string stir::KeyParser::standardise_keyword ( const std::string & keyword ) const

protectedvirtual

convert 'rough' keyword into a standardised form

Calls standardise_interfile_keyword(). This follows Interfile 3.3 conventions:

The characters space, tab, underscore, ! are all treated as white space and ignored.
Case is ignored.

Note: in this implementation 'ignoring' white space means 'trimming' at the start and end of the keyword, and replacing repeated white space with a single space.

References stir::standardise_interfile_keyword().

◆ get_keyword()

string stir::KeyParser::get_keyword ( const std::string & line ) const

protectedvirtual

gets a keyword from a string

Find := or [. Note that the returned keyword is not standardised yet.

◆ add_key() [4/7]

void stir::KeyParser::add_key	(	const std::string &	keyword,
		KeyArgument::type	t,
		KeywordProcessor	function,
		void *	variable = `0`,
		const ASCIIlist_type *const	list = `0`
	)

protected

add a keyword to the list, together with its call_back function

This provides a more flexible way to add keys with specific call_backs. Can currently only be used by derived classes, as KeywordProcessor has to be a pointer to member function.

Warning: this interface to KeyParser will change in a future release

◆ add_key() [5/7]

void stir::KeyParser::add_key	(	const std::string &	keyword,
		KeyArgument::type	t,
		KeywordProcessor	function,
		void *	variable,
		const int	vectorised_key_level,
		const ASCIIlist_type *const	list = `0`
	)

protected

add a keyword to the list, together with its call_back function

This provides a more flexible way to add keys with specific call_backs. Can currently only be used by derived classes, as KeywordProcessor has to be a pointer to member function.

Warning: this interface to KeyParser will change in a future release

◆ add_key() [6/7]

void stir::KeyParser::add_key	(	const std::string &	keyword,
		KeyArgument::type	t,
		void *	variable,
		const ASCIIlist_type *const	list = `0`
	)

protected

version that defaults 'function' to set_variable

Warning: this interface to KeyParser will change in a future release

◆ add_key() [7/7]

void stir::KeyParser::add_key	(	const std::string &	keyword,
		KeyArgument::type	t,
		void *	variable,
		const int	vectorised_key_level,
		const ASCIIlist_type *const	list = `0`
	)

protected

version that defaults 'function' to set_variable

Warning: this interface to KeyParser will change in a future release

◆ set_variable()

void stir::KeyParser::set_variable ( )

callback function that sets the variable to the value given as the value of the keyword

if the keyword had no value, set_variable will do nothing

References stir::error(), and stir::warning().

◆ set_parsing_object()

void stir::KeyParser::set_parsing_object ( )

callback function that sets the variable by calling the parser (as stored by add_parsing_key()), with argument the value of the keyword

if the keyword had no value, set_variable will do nothing

References stir::error().

◆ set_shared_parsing_object()

void stir::KeyParser::set_shared_parsing_object ( )

callback function that sets the shared_ptr variable by calling the parser (as stored by add_parsing_key()), with argument the value of the keyword

if the keyword had no value, set_variable will do nothing

References stir::error().

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

/home/sirfuser/devel/STIRdistrib/STIR/src/include/stir/KeyParser.h
/home/sirfuser/devel/STIRdistrib/STIR/src/buildblock/KeyParser.cxx

Public Member Functions

Protected Types

Protected Member Functions

Friends

Detailed Description

Member Function Documentation

◆ parse() [1/3]

◆ parse() [2/3]

◆ parse() [3/3]

◆ add_key() [1/7]

◆ add_key() [2/7]

◆ add_vectorised_key()

◆ add_key() [3/7]

◆ add_start_key()

◆ add_parsing_key() [1/2]

◆ add_parsing_key() [2/2]

◆ remove_key()

◆ add_alias_key()

◆ parameter_info()

◆ ask_parameters()

◆ find_in_ASCIIlist()

◆ post_processing()

◆ standardise_keyword()

◆ get_keyword()

◆ add_key() [4/7]

◆ add_key() [5/7]

◆ add_key() [6/7]

◆ add_key() [7/7]

◆ set_variable()

◆ set_parsing_object()

◆ set_shared_parsing_object()