---

parametermap.h

Go to the documentation of this file.

#ifndef ___PARAMETERMAP_H___
#define ___PARAMETERMAP_H___

#include <math.h>
#include <map>
#include <algorithm>
#include <vector>

#include "parameter.h"
#include "stringutils.h"
#include "stringparser.h"
#include "pathspecification.h"
#include "pointerlookup.h"
#include "parammap.h"
#include "msg.h"
#include "generic_stdlib.h"
#include "mathconstants.h"



template<class ParamT=ParameterDefinition<> > 
class ParameterMap : public ParamMap {
public:
  typedef ParamT               ParamType;
  typedef ParameterMap<ParamT> self;
  typedef ParamType            value_type;

  virtual ~ParameterMap() {
    /* Before dying, sever all links to us */
    if (parent) parent->children.erase(name()); /* Make our parent forget us */
    for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
      (*c).second->parent=0; /* Make our children consider themselves parentless */
    Generic::delete_contents(allocated);
  }

  
  ParameterMap(self* parent_i=0, const string name_="")
    : parent(parent_i), name_str(name_)
    {  if (parent) parent->children[name()]=this;  }

  virtual self* new_child(const string name_="", const bool owned=false) {
    self* p=new self(this,name_);
    if (owned) allocated.push_back(p);
    return p;
  }

  void    init_hook(void);
  int     define_param(const ParamType& param);
  void    add_constants();
  void    update_all_default_values(const StringParser& sp);

  virtual const ParamType& lookup(const string& name, bool warn=true) const;
  virtual       ParamType& lookup(const string& name, bool warn=true);
  virtual       ParamType& local_copy(ParamType& param, bool notify=true, bool copysetfn=true);


  /* Macro: silently ensure that the given parameters exists in the
     local map and set it to the given value. */
  template <class T>
  self& set_local(const string& name, const T& value)
    {  local_copy(lookup(name),false).datavalue().set(Polymorph<T>(value));  return *this;  }

  virtual ParamMap& get_child(const string& name_="")
    {  return lookup_map(name_);  }

  virtual const ParamMap& get_child(const string& name_="") const
    {  return const_cast<self*>(this)->lookup_map(name_);  }

  const self& root() const 
    {  return (parent? parent->root() : *this);  }
  self& root() {  return (parent? parent->root() : *this);  }
    
  
  self& lookup_map(const string& mapname, bool warn=true) {
    const PathSpecification path(mapname);
    return lookup_map(path.all(),warn,path.isrooted());
  }

  self& lookup_map(const PathSpecification::NameList& names, bool warn, bool isrooted) {
    self& startmap=(isrooted? root() : *this);
    if (names.empty()) return startmap;
    PathSpecification::NameList::const_iterator rest=names.begin();
    self& child=startmap.lookup_child(*rest++, warn);
    PathSpecification::NameList remainder(rest,names.end());
    return child.lookup_map(remainder,warn,false);
  }
  const self& lookup_map(const PathSpecification::NameList& names, bool warn, bool isrooted) const {
    const self& startmap=(isrooted? root() : *this);
    if (names.empty()) return startmap;
    PathSpecification::NameList::const_iterator rest=names.begin();
    const self& child=startmap.lookup_child(*rest++, warn);
    PathSpecification::NameList remainder(rest,names.end());
    return child.lookup_map(remainder,warn,false);
  }
  
  /* Macro: set parameter to the given valuestr (creating a copy of
     the param locally if necessary) in all matching paths (accepting
     * to represent all children at a given level).  Returns the
     number of parameters actually set. */
  int set_matching(const StringParser& sp, const string& pathspec, const string& valuestr,
                   const bool mark=true, const bool verbose=true,
                   const bool local_only=false, const bool copysetfn=true ) {
    PathSpecification path(pathspec);
    PathSpecification::NameList namelist=path.allbutlast();
    return (path.isrooted()? root() : *this).
      set_matching(sp,namelist.begin(),namelist.end(),path.last(),valuestr,mark,verbose,local_only, copysetfn);
  }
  

  inline ParamType& lookup_with_path(const string& pathspec, bool warn=true) {
    PathSpecification path(pathspec);
    return lookup_map(path.allbutlast(),true,path.isrooted()).lookup(path.last(),warn);
  }
  inline const ParamType& lookup_with_path(const string& pathspec, bool warn=true) const {
    PathSpecification path(pathspec);    
    return lookup_map(path.allbutlast(),true,path.isrooted()).lookup(path.last(),warn);
  }

  Typeless* getptr(const key_type& k) {
    ParamType& existing = lookup_with_path(k,true);
    return (existing.is_valid() ? &(existing.datavalue()) : 0);
  }

  const Typeless* getptr(const key_type& k) const {
    const ParamType& existing = lookup_with_path(k,true);
    return (existing.is_valid() ? &(existing.datavalue()) : 0);
  }

  
  int     check_all( void ) const;

  void    print_all(            FILE *fp, const string& prefix="") const;
  void    print_constants(      FILE *fp, const string& prefix="") const;
  void    print_constants_doc(  FILE *fp, const string& prefix="") const;
  void    print_children(       FILE *fp, const string& prefix="") const;
  void    print_parameters(     FILE *fp, const string& prefix="") const;
  void    print_parameters_doc( FILE *fp, const string& prefix="") const;
  void    save_parameters(      FILE *fp, const string& prefix="") const;
  
  char*   completion_generator (char *text, int state) const;
  
  static const char* const help_separator;

  void message(Msg::MessageLevel m, const string& s) const {  ParamType::message(m,s);  }

  const string& name()       const {  return name_str;  }

  const string  path_name()  const {
    return (parent && (parent->path_name()!="") ?
            (parent->path_name()+"::")+name() :
            name());
  }
  
  const string  path_prefix()  const {
    const string path = path_name();
    return path + (path == "" ? "" : "::");
  }

  /* Merges the local values from another parameter set into this one */
  void merge(const self& b, const bool overwrite=true) {
    for (typename DataType::const_iterator i=b.data.begin(); i!=b.data.end(); i++) {
      if (overwrite || !local_lookup(i->name(),false).is_valid())
        local_copy(lookup(i->name()),false).datavalue().set(i->datavalue());
    }
  }

  /* Returns true if a parameter by the given name is defined in this map */
  bool defined_locally(const string& name) const 
    {  return local_lookup(name,false).is_valid();  }
  
  
private:
  self& lookup_child(const string& childname, bool warn=true) {
    typename ChildListType::iterator location = children.find(childname);
    if (location==children.end()) {
      if (warn)
        message(Msg::Error,"Could not locate parameter set '"+childname+"'; using default set");
      return *this;
    }
    return *((*location).second);
  }
  const self& lookup_child(const string& childname, bool warn=true) const {
    typename ChildListType::const_iterator location = children.find(childname);
    if (location==children.end()) {
      if (warn)
        message(Msg::Error,"Could not locate parameter set '"+childname+"'; using default set");
      return *this;
    }
    return *((*location).second);
  }

  
  /* Recursive implementation of public set_matching routine. */
  int set_matching(const StringParser& sp,
                   const PathSpecification::NameList::const_iterator& pathbegin,
                   const PathSpecification::NameList::const_iterator& pathend,
                   const string& paramname,
                   const string& valuestr,
                   const bool mark, const bool verbose,
                   const bool local_only, const bool copysetfn) {
    /* If no path and the parameter definition exists, set in this blackboard */
    if (pathbegin==pathend) {
      ParamType& param = lookup(paramname);
      if (param.is_valid()) {
        ParamType& existinglocal = local_lookup(paramname,false);
        if (!local_only || existinglocal.is_valid())
          return local_copy(param,verbose,copysetfn).set(sp,valuestr,mark,verbose,path_prefix());
      }
      return 0;
    }

    PathSpecification::NameList::const_iterator rest=pathbegin;
    const string mapname=*rest++;

    /* Set in all matching children. */
    int numset=0;
    int nummaps=0;
    for (typename ChildListType::iterator c=children.begin(); c!=children.end(); c++) {
      const string childname=(*c).first;
      /* Supporting real globbing or a regex here might be nice */
      if (String::glob_match(mapname,childname)) {
        nummaps++;
        numset+= ((*c).second)->set_matching(sp,rest,pathend,paramname,valuestr,
                                             mark,verbose,local_only,copysetfn);
      }
    }
    if (!nummaps) message(Msg::Error,"No parameter set matches `" + path_prefix() + mapname + "'");
    return numset;
  }
  

        ParamType& local_lookup(const string& name, bool warn);
  const ParamType& local_lookup(const string& name, bool warn) const;
  
  typedef std::vector<ParamType>       DataType;
  typedef std::map<const string,self*> ChildListType;

  DataType data;
  ChildListType children;
  
  std::vector<ParamMap*> allocated;
  
  self* parent;
  const string name_str;
};

template<class ParamT>
const char* const ParameterMap<ParamT>::help_separator=
"_______________________________________________________________________________\n";




#define DEFCONST(type,name,location,doc) ParamType \
param_ ## name = ParamType(make_Polymorph(&location),#name,true);\
param_ ## name.add_doc(doc); \
define_param(param_ ## name)

template<class ParamT>
void ParameterMap<ParamT>::add_constants()
{
  static double   mpi = (Math::pi);
  static Tristate tru = True;
  static Tristate fal = False;
  static Tristate uni = Uninitialized;
  static int      mxi = INT_MAX-1;
  static int      mni = INT_MIN+1;
  
  DEFCONST(DOUBLE,PI,            mpi,"Symbol representing PI.");
  DEFCONST(3BOOL, true,          tru,"Symbol representing Boolean `True'.");
  DEFCONST(3BOOL, false,         fal,"Symbol representing Boolean `False'.");
  DEFCONST(3BOOL, True,          tru,"Symbol representing Boolean `True'.");
  DEFCONST(3BOOL, False,         fal,"Symbol representing Boolean `False'.");
  DEFCONST(3BOOL, Yes,           tru,"Symbol representing Boolean `True'.");
  DEFCONST(3BOOL, No,            fal,"Symbol representing Boolean `False'.");
  DEFCONST(3BOOL, Uninitialized, uni,"Symbol representing an uninitialized or default value.");
  DEFCONST(INT,   MaxInt,        mxi,"Symbol representing the maximum integer value.");
  DEFCONST(INT,   MinInt,        mni,"Symbol representing the minimum integer value.");
}
#undef DEFCONST



template<class ParamT>
void ParameterMap<ParamT>::init_hook( void )
{
  /* Sort for pretty and to make user-defined ones separate. */
  std::sort(data.begin(),data.end());
}



template<class ParamT>
const typename ParameterMap<ParamT>::ParamType&
ParameterMap<ParamT>::local_lookup(const string& name, bool warn) const
{
  /* Counts backward, which is very quick if this parameter was just added */
  for (int idx=data.size()-1; idx>=0; idx--)
    if (name == data[idx].name())
      return data[idx];
  if (warn) message(Msg::Error,"No parameter (or constant) `" + name + "' is defined");
  static ParamType dummy;
  assert (!dummy.is_valid());
  return dummy;
}



template<class ParamT>
typename ParameterMap<ParamT>::ParamType&
ParameterMap<ParamT>::local_lookup(const string& name, bool warn)
{
  /* Counts backward, which is very quick if this parameter was just added */
  for (int idx=data.size()-1; idx>=0; idx--)
    if (name == data[idx].name())
      return data[idx];
  if (warn) message(Msg::Error,"No parameter (or constant) `" + name + "' is defined");
  static ParamType dummy;
  return dummy;
}



template<class ParamT>
typename ParameterMap<ParamT>::ParamType&
ParameterMap<ParamT>::lookup(const string& name, bool warn)
{
  ParamType& result = local_lookup(name,(warn && !parent));
  if (!result.is_valid() && parent) return parent->lookup(name,warn);
  return result;
}



/* Const version of lookup */
template<class ParamT>
const typename ParameterMap<ParamT>::ParamType&
ParameterMap<ParamT>::lookup(const string& name, bool warn) const
{
  const ParamType& result = local_lookup(name,(warn && !parent));
  if (!result.is_valid() && parent) return parent->lookup(name,warn);
  return result;
}



/*
  Copies the result from a non-const lookup() into the local map.
  This is generally done in preparation for a set() operation that is
  intended to affect the local map rather than the global one.
  Ignores invalid parameters and parameters already in the local map.
*/
template<class ParamT>
typename ParameterMap<ParamT>::ParamType&
ParameterMap<ParamT>::local_copy(ParamType& param, bool notify, bool copysetfn)
{
  if (param.is_valid()) {
    ParamType& result = local_lookup(param.name(),false);
    if (result.is_valid())
      return result;
    else {
      if (notify) message(Msg::Notify,"Adding " + param.name() + " to parameter set " + path_name());
      ParamType* copy = param.duplicate();
      if (!copysetfn) copy->add_setfn(0);
      data.push_back(*copy);
      delete copy;
      return data.back();
    }
  }

  return param;
}



template<class ParamT>
int ParameterMap<ParamT>::check_all( void ) const
{
  int numerrors=0;

  /* Check our data */
  for (typename DataType::const_iterator i=data.begin(); i!=data.end(); i++) {
    //message(Msg::Notify,"Checking " + (*i).name());    
    numerrors += (*i).check2();
  }

  /* Check children's data */
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
    numerrors += (*c).second->check_all();

  return numerrors;
}



template<class ParamT>
void ParameterMap<ParamT>::print_all(FILE *fp, const string& prefix) const
{
  /* Print our data */
  for (typename DataType::const_iterator i=data.begin(); i!=data.end(); i++)
    fprintf(fp,"%s\n",(*i).usage_string(prefix).c_str());

  /* Print children's data */
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
    (*c).second->print_all(fp,prefix+(*c).first+"::");
}



template<class ParamT>
void ParameterMap<ParamT>::print_children(FILE *fp, const string& prefix) const
{
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++) {
    const string new_prefix = prefix + (*c).first.c_str();
    fprintf(fp,"%s\n",new_prefix.c_str());
    (*c).second->print_children(fp,new_prefix + "::");
  }
}



template<class ParamT>
void ParameterMap<ParamT>::print_parameters(FILE *fp, const string& prefix) const
{
  /* Print our data */
  for (typename DataType::const_iterator i=data.begin(); i!=data.end(); i++)
    if (!(*i).is_constant())
      fprintf(fp,"%s\n",(*i).usage_string(prefix).c_str());

  /* Print children's data */
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
    (*c).second->print_parameters(fp,prefix+(*c).first+"::");
}



template<class ParamT>
void ParameterMap<ParamT>::save_parameters(FILE *fp, const string& prefix) const
{
  /* Print our data */
  for (typename DataType::const_iterator i=data.begin(); i!=data.end(); i++)
    if (!(*i).is_constant())
      fprintf(fp,"%s\n",(*i).print_to_str("::"+prefix).c_str());

  /* Print children's data */
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
    (*c).second->save_parameters(fp,prefix+(*c).first+"::");
}


template<class ParamT>
void ParameterMap<ParamT>::print_constants(FILE *fp, const string& prefix) const
{
  /* Print our data */
  for (typename DataType::const_iterator i=data.begin(); i!=data.end(); i++)
    if ((*i).is_constant())
      fprintf(fp,"%s\n",(*i).usage_string(prefix).c_str());

  /* Print children's data */
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
    (*c).second->print_constants(fp,prefix+(*c).first+"::");
}



template<class ParamT>
int ParameterMap<ParamT>::define_param(const ParamType& param)
{
  if (param.name().length() != String::C_identifier_length(param.name()))
    message(Msg::Warning,"Invalid characters in parameter name `" + param.name() + "'; can't define it");
  else {
    const ParamType& existing = lookup(param.name(),false);
    
    if (existing.is_valid()) {
      if (param.definition_matches(existing)) {
        //message(Msg::Notify,"Parameter " + param.name() + " already exists; not redefining it");
        return 2;
      }
      else message(Msg::Error,"Different parameter `" + param.name() + "' already exists; can't redefine it");
    }
    else if (!param.is_valid()) message(Msg::Error,"Could not construct parameter");
    else {
      data.push_back(param);
      return 1;
    }
  }

  return 0;
}



template<class ParamT>
void ParameterMap<ParamT>::update_all_default_values(const StringParser& sp)
{
  /* Update own values */
  for (typename DataType::iterator i=data.begin(); i!=data.end(); i++)
    (*i).update_default_value(sp);

  /* Update children */
  for (typename ChildListType::iterator c=children.begin(); c!=children.end(); c++)
    (*c).second->update_all_default_values(sp);
}



template<class ParamT>
void ParameterMap<ParamT>::print_constants_doc(FILE *fp, const string& prefix) const
{
  /* Only print separator at top level */
  if (prefix=="")
    fprintf(fp,"%s\n",help_separator);
  
  for (typename DataType::const_iterator i=data.begin(); i!=data.end(); i++)
    if ((*i).is_constant())
      fprintf(fp,"%s%s\n",(*i).doc_string(prefix).c_str(),help_separator);


  /* Print children's data */
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
    (*c).second->print_constants_doc(fp,prefix+(*c).first+"::");
}



template<class ParamT>
void ParameterMap<ParamT>::print_parameters_doc(FILE *fp, const string& prefix) const
{
  /* Only print separator at top level */
  if (prefix=="")
    fprintf(fp,"%s\n",help_separator);
  
  /* Print our data */
  for (typename DataType::const_iterator i=data.begin(); i!=data.end(); i++)
    if (!(*i).is_constant())
      fprintf(fp,"%s%s\n",(*i).doc_string(prefix).c_str(),help_separator);

  /* Print children's data */
  for (typename ChildListType::const_iterator c=children.begin(); c!=children.end(); c++)
    (*c).second->print_parameters_doc(fp,prefix+(*c).first+"::");
}



template<class ParamT>
char* ParameterMap<ParamT>::completion_generator (char *text, int state) const
{
  static int idx, len;

  /*
    If this is a new word to complete, initialize the index counters
    to the beginning and save the length of text for efficiency
  */
  if (!state) {
    idx = 0;
    len = strlen(text);
  }
  
  /* Return the next parameter which partially matches, if any. */
  while (idx < int(data.size())) {
    const char *name = data[idx++].name().c_str();
    if (strncmp (name, text, len) == 0) {
      /* Duplicate the name string, as required by readline */
      char *newstr = (char *)malloc(strlen(name)+1); assert (newstr);
      strcpy (newstr, name);
      return (newstr);
    }
  }
  
  return ((char *)0); /* No more matches */
}



#endif /* ___PARAMETERMAP_H___ */

---