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;

    virtual std::string description () 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;

    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;

    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;

    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;

    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;

    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;

    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;

    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;

    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;

    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;

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

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

  virtual bool read_input_from_string (const char *s);

  virtual bool read_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 << ">");
  DeclException0 (ExcAlreadyAtTopLevel);
  DeclException1 (ExcEntryUndeclared,
                  std::string,
                  << "You can't ask for entry <" << arg1 << "> you have not yet declared");
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;

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

  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