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

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

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

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]

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.

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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);

stir::KeyParser::add_key

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

Definition KeyParser.cxx:343

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.

References parse(), and post_processing().

Referenced by stir::CListModeDataPENN::CListModeDataPENN(), stir::PoissonLLReconstructionTests< TargetT >::construct_projector_pair(), parse(), parse(), parse(), stir::ScatterEstimation::post_processing(), stir::MultiDynamicDiscretisedDensityInputFileFormat::read_from_file(), stir::MultiParametricDiscretisedDensityInputFileFormat::read_from_file(), 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 parse(), and 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.

References parse().

◆ 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.

References add_key().

◆ add_key() [2/7]

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

The 'value' can contain spaces.

References add_key().

◆ 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.

References add_key(), and add_vectorised_key().

◆ 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.

References add_key().

◆ 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 add_key(), add_start_key(), and start_parsing().

Referenced by add_start_key(), stir::CListModeDataPENN::CListModeDataPENN(), stir::PoissonLLReconstructionTests< TargetT >::construct_projector_pair(), stir::RigidObject3DMotionFromPolaris::post_processing(), stir::ScatterEstimation::post_processing(), and stir::RigidObject3DMotionFromPolaris::synchronise().

◆ 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:= ;

References set_parsing_object().

Referenced by stir::CListModeDataPENN::CListModeDataPENN(), stir::PoissonLLReconstructionTests< TargetT >::construct_projector_pair(), 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

References set_shared_parsing_object().

◆ 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 remove_key().

Referenced by remove_key(), and stir::InterfileHeader::set_version_specific_keys().

◆ 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.

References add_alias_key(), and standardise_keyword().

Referenced by add_alias_key().

◆ 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 parameter_info(), start_parsing(), and stop_parsing().

Referenced by parameter_info().

◆ 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 ask_parameters(), do_nothing(), post_processing(), start_parsing(), stop_parsing(), and stir::warning().

Referenced by ask_parameters().

◆ 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

References find_in_ASCIIlist(), and standardise_keyword().

Referenced by find_in_ASCIIlist(), and set_variable().

◆ 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::InterfileHeader, stir::InterfileHeaderSiemens, stir::InterfileImageHeader, stir::InterfileListmodeHeaderSiemens, stir::InterfileNormHeaderSiemens, stir::InterfilePDFSHeader, stir::InterfilePDFSHeaderSiemens, stir::InterfilePDFSHeaderSPECT, and stir::InterfileRawDataHeaderSiemens.

Referenced by ask_parameters(), and parse().

◆ 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(), and standardise_keyword().

Referenced by add_alias_key(), find_in_ASCIIlist(), stir::InterfilePDFSHeader::post_processing(), stir::InterfilePDFSHeaderSiemens::post_processing(), stir::InterfilePDFSHeaderSPECT::post_processing(), and standardise_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.

References get_keyword().

Referenced by get_keyword().

◆ 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

References add_key().

◆ 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

References add_key().

◆ 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

References add_key(), and set_variable().

◆ 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

References add_key(), and set_variable().

◆ 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(), find_in_ASCIIlist(), set_variable(), and stir::warning().

Referenced by add_key(), add_key(), stir::InterfileImageHeader::read_image_data_types(), set_variable(), and stir::MinimalInterfileHeader::set_version_specific_keys().

◆ 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(), and set_parsing_object().

Referenced by add_parsing_key(), and set_parsing_object().

◆ 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(), and set_shared_parsing_object().

Referenced by add_parsing_key(), and set_shared_parsing_object().

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

/home/kris/devel/STIRdistrib/STIR/src/include/stir/KeyParser.h
/home/kris/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()