KeyParser.h

Go to the documentation of this file.

/*
    Copyright (C) 2000 PARAPET partners
    Copyright (C) 2000 - 2007-10-08, Hammersmith Imanet Ltd
    Copyright (C) 2013, 2020, 2021, 2023, 2024 University College London
    This file is part of STIR.

    SPDX-License-Identifier: Apache-2.0 AND License-ref-PARAPET-license

    See STIR/LICENSE.txt for details
*/
#ifndef __stir_KEYPARSER_H__
#define __stir_KEYPARSER_H__

#include "stir/shared_ptr.h"
#include "stir/Array.h"
#include "stir/warning.h"
#include "boost/any.hpp"

#include <map>
#include <list>
#include <utility>
#include <string>
#include <iostream>
#include <vector>

START_NAMESPACE_STIR

typedef std::vector<std::string> ASCIIlist_type;

class RegisteredObjectBase;
class Succeeded;

class KeyParser;

class KeyArgument
{
public:
  enum type
  {
    NONE,
    ASCII,
    LIST_OF_ASCII,
    ASCIIlist,
    UINT,
    ULONG,
    LONG,
    INT,
    LIST_OF_INTS,
    DOUBLE,
    LIST_OF_DOUBLES,
    listASCIIlist,
    ARRAY2D_OF_FLOATS,
    ARRAY3D_OF_FLOATS,
    BASICCOORDINATE3D_OF_FLOATS,
    BASICCOORDINATE3D_OF_ARRAY3D_OF_FLOATS,
    PARSINGOBJECT,
    SHARED_PARSINGOBJECT,
    FLOAT,
    BOOL
  };
};

class map_element
{
public:
  KeyArgument::type type;
  void (KeyParser::*p_object_member)(); // pointer to a member function
  // TODO void (*p_object_member)();
  void* p_object_variable; // pointer to a variable
  int vectorised_key_level;
  const ASCIIlist_type* p_object_list_of_values; // only used by ASCIIlist
  // TODO should really not be here, but it works for now
  typedef RegisteredObjectBase*(Parser)(std::istream*, const std::string&);
  Parser* parser;

  map_element();

  // map_element(KeyArgument::type t, void (KeyParser::*object_member_ptr)());

  map_element(KeyArgument::type t,
              void (KeyParser::*object_member_ptr)(),
              void* variable_ptr,
              const int vectorised_key_level,
              const ASCIIlist_type* list_of_valid_keywords = 0);
  map_element(void (KeyParser::*pom)(), RegisteredObjectBase** pov, Parser*);
  map_element(void (KeyParser::*pom)(), shared_ptr<RegisteredObjectBase>* pov, Parser*);
  ~map_element();

  map_element& operator=(const map_element& me);
};

// note: next text contains double \\ for correct parsing by doxygen
// you should read them as a single  backslash
class KeyParser
{
  // historical typedefs
  typedef std::vector<int> IntVect;
  typedef std::vector<double> DoubleVect;

public:
  KeyParser();
  virtual ~KeyParser();


  bool parse(std::istream& f, const bool write_warnings = true);

  bool parse(const char* const filename, const bool write_warnings = true);
  bool parse(const std::string&, const bool write_warnings = true);


  // KT 07/02/2001 all these are new (up to add_parsing_key)

  void add_key(const std::string& keyword, float* variable_ptr);
  void add_vectorised_key(const std::string& keyword, std::vector<float>* variable_ptr);
  void add_key(const std::string& keyword, double* variable_ptr);
  void add_vectorised_key(const std::string& keyword, std::vector<double>* variable_ptr);
  void add_vectorised_key(const std::string& keyword, std::vector<std::vector<double>>* variable_ptr);

  void add_key(const std::string& keyword, int* variable_ptr);
  void add_key(const std::string& keyword, std::vector<int>* variable_ptr);
  void add_vectorised_key(const std::string& keyword, std::vector<int>* variable_ptr);
  void add_vectorised_key(const std::string& keyword, std::vector<std::vector<int>>* variable_ptr);

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

  void add_key(const std::string& keyword, unsigned int* variable_ptr);
  void add_vectorised_key(const std::string& keyword, std::vector<unsigned int>* variable);
  void add_key(const std::string& keyword, unsigned long* variable_ptr);
  void add_vectorised_key(const std::string& keyword, std::vector<unsigned long>* variable_ptr);


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

  void add_key(const std::string& keyword, std::vector<double>* variable_ptr);

  void add_key(const std::string& keyword, std::vector<std::string>* variable_ptr);

  void add_key(const std::string& keyword, Array<2, float>* variable_ptr);

  void add_key(const std::string& keyword, Array<3, float>* variable_ptr);

  void add_key(const std::string& keyword, BasicCoordinate<3, float>* variable_ptr);

  void add_key(const std::string& keyword, BasicCoordinate<3, Array<3, float>>* 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);
  void add_key(const std::string& keyword, int* variable_ptr, const ASCIIlist_type* const list_of_values);

  void ignore_key(const std::string& keyword);

  void add_start_key(const std::string& keyword);
  void add_stop_key(const std::string& keyword);


  // definition of next function has to be here to get it to compile with VC (it uses member templates)
  template <typename ParsingClass>
  void add_parsing_key(const std::string& keyword, ParsingClass** parsed_object_ptr_ptr)
  {
    add_in_keymap(keyword,
                  map_element(&KeyParser::set_parsing_object,
                              reinterpret_cast<RegisteredObjectBase**>(parsed_object_ptr_ptr),
                              (map_element::Parser*)(&ParsingClass::read_registered_object)));
  }


  template <typename ParsingClass>
  void add_parsing_key(const std::string& keyword, shared_ptr<ParsingClass>* parsed_object_ptr_ptr)
  {
    add_in_keymap(keyword,
                  map_element(&KeyParser::set_shared_parsing_object,
                              reinterpret_cast<shared_ptr<RegisteredObjectBase>*>(parsed_object_ptr_ptr),
                              (map_element::Parser*)(&ParsingClass::read_registered_object)));
  }


  bool remove_key(const std::string& keyword);


  void add_alias_key(const std::string& keyword, const std::string& alias, bool deprecated_key = true);
  void print_keywords_to_stream(std::ostream&) const;

  // KT 07/02/2001 new

  virtual std::string parameter_info() const;

  // KT 07/02/2001 new

  virtual void ask_parameters();


  int find_in_ASCIIlist(const std::string&, const ASCIIlist_type& list_of_values);

protected:


  virtual bool post_processing() { return false; }


  virtual std::string standardise_keyword(const std::string& keyword) const;


  virtual std::string get_keyword(const std::string&) const;

  typedef void (KeyParser::*KeywordProcessor)();
  // TODO typedef void (*KeywordProcessor)();


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

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


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

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

public:
  void start_parsing();
  void stop_parsing();
  void do_nothing(){};

  void set_variable();


  void set_parsing_object();

  void set_shared_parsing_object();

private:
  friend class map_element;

  enum parse_status
  {
    end_parsing,
    parsing
  };
  parse_status status;

  // KT 01/05/2001 changed to a list, to preserve order of keywords
  // typedef std::map<std::string,map_element> Keymap;
  typedef std::list<std::pair<std::string, map_element>> Keymap;

  Keymap kmap;

  typedef std::map<std::string, std::string> AliasMap;

  AliasMap alias_map;
  AliasMap deprecated_alias_map;

  // KT 01/05/2001 new functions to allow a list type
  map_element* find_in_keymap(const std::string& keyword);
  void add_in_keymap(const std::string& keyword, const map_element& new_element);

  std::string resolve_alias(const std::string& keyword) const;

  std::istream* input;
  map_element* current;
  int current_index;
  std::string keyword;

  // next will be false when there's only a keyword on the line
  // maybe should be protected (or even public?). At the moment, this is only used by set_variable().
  // That should cover most cases.
  bool keyword_has_a_value;
  boost::any parameter;


  static void value_to_stream(std::ostream& s, const map_element&);
  static void vectorised_value_to_stream(std::ostream& s, const std::string& keyword, const map_element& element);

  Succeeded parse_header(const bool write_warnings);

  Succeeded read_and_parse_line(const bool write_warning);

  // see if current keyword is in the keymap using map_keyword
  // if so, call its call_back function and return Succeeded::yes, else
  // conditionally write a warning and return Succeeded::no
  Succeeded parse_value_in_line(const std::string& line, const bool write_warning);

  // return Succeeded::yes if valid keyword, Succeeded::no otherwise
  Succeeded map_keyword(const std::string& keyword);

  void process_key();
};

END_NAMESPACE_STIR

#endif