parameter_handler.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2018 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii_parameter_handler_h
#define dealii_parameter_handler_h


#include <deal.II/base/config.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/subscriptor.h>
#include <deal.II/base/patterns.h>

#include <boost/property_tree/ptree_fwd.hpp>
#include <boost/serialization/split_member.hpp>
#include <boost/archive/basic_archive.hpp>
#include <boost/property_tree/ptree_serialization.hpp>

#include <map>
#include <vector>
#include <string>
#include <memory>

DEAL_II_NAMESPACE_OPEN

// forward declarations for interfaces and friendship
class LogStream;
class MultipleParameterLoop;

class ParameterHandler : public Subscriptor
{
private:
  ParameterHandler (const ParameterHandler &) = delete;

  ParameterHandler &operator= (const ParameterHandler &) = delete;

public:
  enum OutputStyle
  {
    Text = 1,

    LaTeX = 2,
    Description = 3,

    XML = 4,

    JSON = 5,

    ShortText = 193
  };



  ParameterHandler ();

  virtual ~ParameterHandler () = default;

  virtual void parse_input (std::istream &input,
                            const std::string &filename = "input file",
                            const std::string &last_line = "");

  virtual void parse_input (const std::string &filename,
                            const std::string &last_line = "");

  virtual void parse_input_from_string (const char *s,
                                        const std::string &last_line = "");

  virtual void parse_input_from_xml (std::istream &input);

  virtual void parse_input_from_json (std::istream &input);

  void clear ();


  void declare_entry (const std::string           &entry,
                      const std::string           &default_value,
                      const Patterns::PatternBase &pattern = Patterns::Anything(),
                      const std::string           &documentation = std::string());

  void add_action (const std::string &entry,
                   const std::function<void (const std::string &value)> &action);

  template <class ParameterType>
  void add_parameter(const std::string &entry,
                     ParameterType &parameter,
                     const std::string &documentation = std::string(),
                     const Patterns::PatternBase &pattern =
                       *Patterns::Tools::Convert<ParameterType>::to_pattern());

  void declare_alias (const std::string &existing_entry_name,
                      const std::string &alias_name,
                      const bool         alias_is_deprecated = false);

  void enter_subsection (const std::string &subsection);

  void leave_subsection ();

  std::string get (const std::string &entry_string) const;

  long int       get_integer (const std::string &entry_string) const;

  double         get_double (const std::string &entry_name) const;

  bool           get_bool (const std::string &entry_name) const;

  void           set (const std::string &entry_name,
                      const std::string &new_value);

  void           set (const std::string &entry_name,
                      const char        *new_value);

  void           set (const std::string &entry_name,
                      const long int    &new_value);

  void           set (const std::string &entry_name,
                      const double      &new_value);

  void           set (const std::string &entry_name,
                      const bool        &new_value);


  std::ostream &
  print_parameters (std::ostream      &out,
                    const OutputStyle  style) const;

  DEAL_II_DEPRECATED
  void print_parameters_section (std::ostream       &out,
                                 const OutputStyle   style,
                                 const unsigned int  indent_level,
                                 const bool          include_top_level_elements = false);

  void log_parameters (LogStream &out);

  void log_parameters_section (LogStream &out);

  std::size_t memory_consumption () const;

  template <class Archive>
  void save (Archive &ar, const unsigned int version) const;

  template <class Archive>
  void load (Archive &ar, const unsigned int version);

  BOOST_SERIALIZATION_SPLIT_MEMBER()

  
  bool operator == (const ParameterHandler &prm2)  const;

  DeclException1 (ExcEntryAlreadyExists,
                  std::string,
                  << "The following entry already exists: " << arg1 << ".");
  DeclException2 (ExcValueDoesNotMatchPattern,
                  std::string, std::string,
                  << "The string <" << arg1
                  << "> does not match the given pattern <" << arg2 << ">.");
  DeclExceptionMsg (ExcAlreadyAtTopLevel,
                    "You can't leave a subsection if you are already at the top level "
                    "of the subsection hierarchy.");
  DeclException1 (ExcEntryUndeclared,
                  std::string,
                  << "You can't ask for entry <" << arg1 << "> you have not yet declared.");

  DeclException2 (ExcUnbalancedSubsections,
                  std::string, std::string,
                  << "There are unequal numbers of 'subsection' and 'end' "
                  "statements in the parameter file <" << arg1 << ">."
                  << (arg2.size() > 0 ? "\n" + arg2 : ""));

  DeclException3 (ExcNoSubsection,
                  int, std::string, std::string,
                  << "Line <" << arg1 << "> of file <" << arg2 << ": There is "
                  "no such subsection to be entered: " << arg3);

  DeclException3 (ExcCannotParseLine,
                  int, std::string, std::string, << "Line <" << arg1 <<
                  "> of file <" << arg2 << ">: " << arg3);

  DeclException5 (ExcInvalidEntryForPattern,
                  int, std::string, std::string, std::string, std::string,
                  << "Line <" << arg1 << "> of file <" << arg2 << ">:\n"
                  "    The entry value \n" << "        " << arg3 << '\n' <<
                  "    for the entry named\n" << "        " << arg4 << '\n' <<
                  "    does not match the given pattern:\n" << "        " <<
                  arg5);

  DeclExceptionMsg (ExcInvalidXMLParameterFile,
                    "The provided file could not be parsed as a "
                    "ParameterHandler description.");

  DeclException3 (ExcInvalidEntryForPatternXML,
                  std::string, std::string, std::string,
                  << "    The entry value \n" << "        " << arg1 << '\n' <<
                  "    for the entry named\n" << "        " << arg2 << '\n' <<
                  "    does not match the given pattern:\n" << "        " <<
                  arg3);

  DeclException3 (ExcCannotOpenIncludeStatementFile,
                  int, std::string, std::string,
                  << "Line <" << arg1 << "> of file <" << arg2 << ">: This line "
                  "contains an 'include' or 'INCLUDE' statement, but the given "
                  "file to include <" << arg3 << "> cannot be opened.");

private:
  static const char path_separator = '.';

  std::vector<std::string> subsection_path;

  std::unique_ptr<boost::property_tree::ptree> entries;

  std::vector<std::unique_ptr<const Patterns::PatternBase> > patterns;

  std::vector<std::function<void (const std::string &)> > actions;

  static
  std::string
  collate_path_string (const std::vector<std::string> &subsection_path);

  std::string get_current_path () const;

  std::string get_current_full_path (const std::string &name) const;

  void scan_line (std::string         line,
                  const std::string  &input_filename,
                  const unsigned int  current_line_n);

  void recursively_print_parameters (const std::vector<std::string> &target_subsection_path,
                                     const OutputStyle               style,
                                     const unsigned int              indent_level,
                                     std::ostream                   &out) const;

  friend class MultipleParameterLoop;
};



class MultipleParameterLoop : public ParameterHandler
{
public:
  class UserClass
  {
  public:
    virtual ~UserClass () = default;

    virtual void create_new (const unsigned int run_no) = 0;

    virtual void run (ParameterHandler &prm) = 0;
  };

  MultipleParameterLoop ();

  virtual ~MultipleParameterLoop () override = default;

  virtual void parse_input (std::istream &input,
                            const std::string &filename = "input file",
                            const std::string &last_line = "") override;

  using ParameterHandler::parse_input;

  void loop (UserClass &uc);

  std::size_t memory_consumption () const;

private:

  class Entry
  {
  public:
    enum MultipleEntryType
    {
      variant,
      array
    };

    Entry () : type (array) {}

    Entry (const std::vector<std::string> &Path,
           const std::string              &Name,
           const std::string              &Value);

    void split_different_values ();

    std::vector<std::string> subsection_path;

    std::string         entry_name;

    std::string         entry_value;

    std::vector<std::string> different_values;

    MultipleEntryType      type;

    std::size_t memory_consumption () const;
  };

  std::vector<Entry> multiple_choices;

  unsigned int n_branches;

  void init_branches ();

  void init_branches_current_section ();

  void fill_entry_values (const unsigned int run_no);
};


// ---------------------- inline and template functions --------------------
template <class Archive>
inline
void
ParameterHandler::save (Archive &ar, const unsigned int) const
{
  // Forward to serialization
  // function in the base class.
  ar   &static_cast<const Subscriptor &>(*this);

  ar & *entries.get();

  std::vector<std::string> descriptions;

  for (unsigned int j=0; j<patterns.size(); ++j)
    descriptions.push_back (patterns[j]->description());

  ar &descriptions;
}


template <class Archive>
inline
void
ParameterHandler::load (Archive &ar, const unsigned int)
{
  // Forward to serialization
  // function in the base class.
  ar   &static_cast<Subscriptor &>(*this);

  ar & *entries.get();

  std::vector<std::string> descriptions;
  ar &descriptions;

  patterns.clear ();
  for (unsigned int j=0; j<descriptions.size(); ++j)
    patterns.push_back (Patterns::pattern_factory(descriptions[j]));
}


template <class ParameterType>
void ParameterHandler::add_parameter(const std::string &entry,
                                     ParameterType &parameter,
                                     const std::string &documentation,
                                     const Patterns::PatternBase &pattern)
{

  static_assert(std::is_const<ParameterType>::value == false,
                "You tried to add a parameter using a type "
                "that is const. Use a non-const type.");

  declare_entry(entry,
                Patterns::Tools::Convert<ParameterType>::to_string(
                  parameter, pattern.clone()),
                pattern,
                documentation);

  std::string path = get_current_full_path(entry);
  const unsigned int pattern_index
    = entries->get<unsigned int> (path + path_separator + "pattern");

  auto action = [ &, pattern_index](const std::string &val)
  {
    parameter =
      Patterns::Tools::Convert<ParameterType>::to_value(val, patterns[pattern_index]->clone());
  };
  add_action(entry, action);
}

DEAL_II_NAMESPACE_CLOSE

#endif