parameter_handler.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2016 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/std_cxx11/shared_ptr.h>
#include <deal.II/base/std_cxx11/unique_ptr.h>

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

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

DEAL_II_NAMESPACE_OPEN

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


namespace Patterns
{

  class PatternBase
  {
  public:
    virtual ~PatternBase ();

    virtual bool match (const std::string &test_string) const = 0;

    enum OutputStyle
    {
      Machine,
      Text,
      LaTeX
    };

    virtual std::string description (const OutputStyle style=Machine) const = 0;

    virtual PatternBase *clone () const = 0;

    virtual std::size_t memory_consumption () const;
  };

  PatternBase *pattern_factory (const std::string &description);

  class Integer : public PatternBase
  {
  public:
    static const int min_int_value;

    static const int max_int_value;

    Integer (const int lower_bound = min_int_value,
             const int upper_bound = max_int_value);

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static Integer *create (const std::string &description);

  private:
    const int lower_bound;

    const int upper_bound;

    static const char *description_init;
  };

  class Double : public PatternBase
  {
  public:
    static const double min_double_value;

    static const double max_double_value;

    Double (const double lower_bound = min_double_value,
            const double upper_bound = max_double_value);

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static Double *create (const std::string &description);

  private:
    const double lower_bound;

    const double upper_bound;

    static const char *description_init;
  };

  class Selection : public PatternBase
  {
  public:
    Selection (const std::string &seq);

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    std::size_t memory_consumption () const;

    static Selection *create (const std::string &description);

  private:
    std::string sequence;

    static const char *description_init;
  };


  class List : public PatternBase
  {
  public:
    static const unsigned int max_int_value;

    List (const PatternBase  &base_pattern,
          const unsigned int  min_elements = 0,
          const unsigned int  max_elements = max_int_value,
          const std::string  &separator = ",");

    virtual ~List ();

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static List *create (const std::string &description);

    std::size_t memory_consumption () const;

    DeclException2 (ExcInvalidRange,
                    int, int,
                    << "The values " << arg1 << " and " << arg2
                    << " do not form a valid range.");
  private:
    PatternBase *pattern;

    const unsigned int min_elements;

    const unsigned int max_elements;

    const std::string separator;

    static const char *description_init;
  };


  class Map : public PatternBase
  {
  public:
    static const unsigned int max_int_value;

    Map (const PatternBase  &key_pattern,
         const PatternBase  &value_pattern,
         const unsigned int  min_elements = 0,
         const unsigned int  max_elements = max_int_value,
         const std::string  &separator = ",");

    virtual ~Map ();

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static Map *create (const std::string &description);

    std::size_t memory_consumption () const;

    DeclException2 (ExcInvalidRange,
                    int, int,
                    << "The values " << arg1 << " and " << arg2
                    << " do not form a valid range.");
  private:
    PatternBase *key_pattern;
    PatternBase *value_pattern;

    const unsigned int min_elements;

    const unsigned int max_elements;

    const std::string separator;

    static const char *description_init;
  };


  class MultipleSelection : public PatternBase
  {
  public:
    MultipleSelection (const std::string &seq);

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static MultipleSelection *create (const std::string &description);

    std::size_t memory_consumption () const;

    DeclException1 (ExcCommasNotAllowed,
                    int,
                    << "A comma was found at position " << arg1
                    << " of your input string, but commas are not allowed here.");
  private:
    std::string sequence;

    static const char *description_init;
  };

  class Bool : public Selection
  {
  public:
    Bool ();

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static Bool *create (const std::string &description);

  private:
    static const char *description_init;
  };

  class Anything : public PatternBase
  {
  public:
    Anything ();

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static Anything *create (const std::string &description);

  private:
    static const char *description_init;
  };


  class FileName : public PatternBase
  {
  public:
    enum FileType
    {
      input = 0,
      output = 1
    };

    FileName (const FileType type = input);

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    FileType  file_type;

    static FileName *create (const std::string &description);

  private:
    static const char *description_init;
  };


  class DirectoryName : public PatternBase
  {
  public:
    DirectoryName ();

    virtual bool match (const std::string &test_string) const;

    virtual std::string description (const OutputStyle style=Machine) const;

    virtual PatternBase *clone () const;

    static DirectoryName *create (const std::string &description);

  private:
    static const char *description_init;
  };
}


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

  ParameterHandler &operator= (const ParameterHandler &);

public:
  enum OutputStyle
  {
    Text = 1,
    LaTeX = 2,
    Description = 3,

    XML = 4,

    JSON = 5,

    ShortText = 193
  };



  ParameterHandler ();

  virtual ~ParameterHandler ();

  virtual bool read_input (std::istream &input,
                           const std::string &filename = "input file",
                           const std::string &last_line = "") DEAL_II_DEPRECATED;

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

  virtual bool read_input (const std::string &filename,
                           const bool optional = false,
                           const bool write_stripped_file = false,
                           const std::string &last_line = "") DEAL_II_DEPRECATED;

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

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

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

  virtual bool read_input_from_xml (std::istream &input) DEAL_II_DEPRECATED;

  virtual void parse_input_from_xml (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 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);

  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_cxx11::unique_ptr<boost::property_tree::ptree> entries;

  std::vector<std_cxx11::shared_ptr<const Patterns::PatternBase> > patterns;

  static std::string mangle (const std::string &s);

  static std::string demangle (const std::string &s);

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

  friend class MultipleParameterLoop;
};



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

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

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

  MultipleParameterLoop ();

  virtual ~MultipleParameterLoop ();

  virtual bool read_input (std::istream &input,
                           const std::string &filename = "input file",
                           const std::string &last_line = "") DEAL_II_DEPRECATED;

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

  using ParameterHandler::parse_input;

  using ParameterHandler::read_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);
};


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 (std_cxx11::shared_ptr<const Patterns::PatternBase>(Patterns::pattern_factory(descriptions[j])));
}


DEAL_II_NAMESPACE_CLOSE

#endif