ParameterSetDescription.h

Go to the documentation of this file.

#ifndef FWCore_ParameterSet_ParameterSetDescription_h
#define FWCore_ParameterSet_ParameterSetDescription_h
// -*- C++ -*-
//
// Package:     ParameterSet
// Class  :     ParameterSetDescription
// 
//
// Original Author:  Chris Jones
//         Created:  Tue Jul 31 15:18:40 EDT 2007
//

#include "FWCore/Utilities/interface/value_ptr.h"
#include "FWCore/ParameterSet/interface/ParameterDescriptionNode.h"

#include <vector>
#include <set>
#include <string>
#include <memory>
#include <iosfwd>

namespace edm {

  class ParameterSet;
  class ParameterDescriptionBase;
  class ParameterWildcardBase;
  class ParameterDescriptionNode;
  template <typename T> class ParameterDescription;
  template <typename T> class ParameterDescriptionCases;
  class DocFormatHelper;

  class ParameterSetDescription {
  public:
    class SetDescriptionEntry {
    public:
      bool optional() const { return optional_; }
      bool writeToCfi() const { return writeToCfi_; }
      edm::value_ptr<ParameterDescriptionNode> const& node() const { return node_; }
      void setOptional(bool value) { optional_ = value; }
      void setWriteToCfi(bool value) { writeToCfi_ = value; }
      ParameterDescriptionNode* setNode(std::auto_ptr<ParameterDescriptionNode> node) { node_ = node; return node_.operator->(); }
    private:
      bool optional_;
      bool writeToCfi_;
      edm::value_ptr<ParameterDescriptionNode> node_;
    };

    typedef std::vector<SetDescriptionEntry> SetDescriptionEntries;
    typedef SetDescriptionEntries::const_iterator const_iterator;

    ParameterSetDescription();
    virtual ~ParameterSetDescription();

    std::string const& comment() const { return comment_; }
    void setComment(std::string const & value);
    void setComment(char const* value);

    void setAllowAnything();
      
    // This is set only for parameterizables which have not set their descriptions.
    // This should only be called to allow backwards compatibility.
    void setUnknown();

    // ***** In these next 8 functions named "add", T is the parameter type ******
    // Exceptions: For parameters of type ParameterSet, T should be a
    // ParameterSetDescription instead of a ParameterSet.  And do not
    // use these next 8 functions for parameters of type vector<ParameterSet>

    template<typename T, typename U>
    ParameterDescriptionBase * add(U const& iLabel, T const& value) {
      return add<T, U>(iLabel, value, true, false, true);
    }

    template<typename T, typename U>
    ParameterDescriptionBase * addUntracked(U const& iLabel, T const& value) {
      return add<T, U>(iLabel, value, false, false, true);
    }

    template<typename T, typename U>
    ParameterDescriptionBase * addOptional(U const& iLabel, T const& value) {
      return add<T, U>(iLabel, value, true, true, true);
    }

    template<typename T, typename U>
    ParameterDescriptionBase * addOptionalUntracked(U const& iLabel, T const& value) {
      return add<T, U>(iLabel, value, false, true, true);
    }

    // For the next 4 functions, there is no default so they will not get injected
    // during validation if missing and they will not get written into cfi files.

    template<typename T, typename U>
    ParameterDescriptionBase * add(U const& iLabel) {
      return add<T, U>(iLabel, true, false, false);
    }

    template<typename T, typename U>
    ParameterDescriptionBase * addUntracked(U const& iLabel) {
      return add<T, U>(iLabel, false, false, false);
    }

    template<typename T, typename U>
    ParameterDescriptionBase * addOptional(U const& iLabel) {
      return add<T, U>(iLabel, true, true, false);
    }

    template<typename T, typename U>
    ParameterDescriptionBase * addOptionalUntracked(U const& iLabel) {
      return add<T, U>(iLabel, false, true, false);
    }

    // ***** Use these 8 functions for parameters of type vector<ParameterSet> *****
    // When a vector<ParameterSet> appears in a configuration, all of its
    // elements will be validated using the description in the argument named
    // "validator" below.  The argument named "defaults" is used when the
    // a vector<ParameterSet> is required to be in the configuration and
    // is absent.  Note that these default ParameterSet's will be validated
    // as if they had appeared in the configuration so they must be consistent
    // with the description and missing parameters that have defaults in
    // in the description will be inserted during validation.  These defaults
    // are also used when writing cfi files.

    template<typename U>
    ParameterDescriptionBase * addVPSet(U const& iLabel,
                                        ParameterSetDescription const& validator,
                                        std::vector<ParameterSet> const& defaults) {
      return addVPSet<U>(iLabel, validator, defaults, true, false, true);
    }

    template<typename U>
    ParameterDescriptionBase * addVPSetUntracked(U const& iLabel,
                                        ParameterSetDescription const& validator,
                                        std::vector<ParameterSet> const& defaults) {
      return addVPSet<U>(iLabel, validator, defaults, false, false, true);
    }

    template<typename U>
    ParameterDescriptionBase * addVPSetOptional(U const& iLabel,
                                        ParameterSetDescription const& validator,
                                        std::vector<ParameterSet> const& defaults) {
      return addVPSet<U>(iLabel, validator, defaults, true, true, true);
    }

    template<typename U>
    ParameterDescriptionBase * addVPSetOptionalUntracked(U const& iLabel,
                                        ParameterSetDescription const& validator,
                                        std::vector<ParameterSet> const& defaults) {
      return addVPSet<U>(iLabel, validator, defaults, false, true, true);
    }

    template<typename U>
    ParameterDescriptionBase * addVPSet(U const& iLabel,
                                        ParameterSetDescription const& validator) {
      return addVPSet<U>(iLabel, validator, true, false, false);
    }

    template<typename U>
    ParameterDescriptionBase * addVPSetUntracked(U const& iLabel,
                                        ParameterSetDescription const& validator) {
      return addVPSet<U>(iLabel, validator, false, false, false);
    }

    template<typename U>
    ParameterDescriptionBase * addVPSetOptional(U const& iLabel,
                                        ParameterSetDescription const& validator) {
      return addVPSet<U>(iLabel, validator, true, true, false);
    }

    template<typename U>
    ParameterDescriptionBase * addVPSetOptionalUntracked(U const& iLabel,
                                        ParameterSetDescription const& validator) {
      return addVPSet<U>(iLabel, validator, false, true, false);
    }

    // ********* Wildcards *********

    template<typename T, typename U>
    ParameterWildcardBase * addWildcard(U const& pattern) {
      return addWildcard<T, U>(pattern, true);
    }

    template<typename T, typename U>
    ParameterWildcardBase * addWildcardUntracked(U const& pattern) {
      return addWildcard<T, U>(pattern, false);
    }

    // ********* Used to insert generic nodes of any type ************

    ParameterDescriptionNode* addNode(ParameterDescriptionNode const& node);
    ParameterDescriptionNode* addNode(std::auto_ptr<ParameterDescriptionNode> node);
    ParameterDescriptionNode* addOptionalNode(ParameterDescriptionNode const& node, bool writeToCfi);
    ParameterDescriptionNode* addOptionalNode(std::auto_ptr<ParameterDescriptionNode> node, bool writeToCfi);

    // ********* Switches ************
    // ifValue will only work with type T as a bool, int, or string.
    // T holds the value of the switch variable.
    // If you try using any other type, then it will not compile.
    template <typename T>
    ParameterDescriptionNode*
    ifValue(ParameterDescription<T> const& switchParameter,
            std::auto_ptr<ParameterDescriptionCases<T> > cases) {
      return ifValue<T>(switchParameter, cases, false, true);
    }

    template <typename T>
    ParameterDescriptionNode*
    ifValueOptional(ParameterDescription<T> const& switchParameter,
                    std::auto_ptr<ParameterDescriptionCases<T> > cases,
                    bool writeToCfi) {
      return ifValue<T>(switchParameter, cases, true, writeToCfi);
    }

    // ********* if exists ************
    ParameterDescriptionNode*
    ifExists(ParameterDescriptionNode const& node1,
         ParameterDescriptionNode const& node2) {
      return ifExists(node1, node2, false, true);
    }

    ParameterDescriptionNode*
    ifExistsOptional(ParameterDescriptionNode const& node1,
                  ParameterDescriptionNode const& node2,
                          bool writeToCfi) {
      return ifExists(node1, node2, true, writeToCfi);
    }

    // ********* for parameters that are a list of allowed labels *********
    template<typename T, typename U>
    ParameterDescriptionNode*
    labelsFrom(U const& iLabel) {
      return labelsFrom<T,U>(iLabel, true, false, true);
    }

    template<typename T, typename U>
    ParameterDescriptionNode*
    labelsFromUntracked(U const& iLabel) {
      return labelsFrom<T,U>(iLabel, false, false, true);
    }

    template<typename T, typename U>
    ParameterDescriptionNode*
    labelsFromOptional(U const& iLabel, bool writeToCfi) {
      return labelsFrom<T,U>(iLabel, true, true, writeToCfi);
    }

    template<typename T, typename U>
    ParameterDescriptionNode*
    labelsFromOptionalUntracked(U const& iLabel, bool writeToCfi) {
      return labelsFrom<T,U>(iLabel, false, true, writeToCfi);
    }

    // These next four functions only work when the template
    // parameters are:
    // T = ParameterSetDescription and V = ParameterSetDescription
    // or
    // T = vector<ParameterSet> and V = ParameterSetDescription
    // In either case U can be either a string or char*
    // Note the U and V can be determined from the arguments, but
    // T must be explicitly specified by the calling function.
    template<typename T, typename U, typename V>
    ParameterDescriptionNode*
    labelsFrom(U const& iLabel, V const& desc) {
      return labelsFrom<T,U,V>(iLabel, true, false, true, desc);
    }

    template<typename T, typename U, typename V>
    ParameterDescriptionNode*
    labelsFromUntracked(U const& iLabel, V const& desc) {
      return labelsFrom<T,U,V>(iLabel, false, false, true, desc);
    }

    template<typename T, typename U, typename V>
    ParameterDescriptionNode*
    labelsFromOptional(U const& iLabel, bool writeToCfi, V const& desc) {
      return labelsFrom<T,U,V>(iLabel, true, true, writeToCfi, desc);
    }

    template<typename T, typename U, typename V>
    ParameterDescriptionNode*
    labelsFromOptionalUntracked(U const& iLabel, bool writeToCfi, V const& desc) {
      return labelsFrom<T,U,V>(iLabel, false, true, writeToCfi, desc);
    }

    bool anythingAllowed() const { return anythingAllowed_; }
    bool isUnknown() const { return unknown_; }

    const_iterator begin() const {
      return entries_.begin();
    }

    const_iterator end() const {
      return entries_.end();
    }

    // Better performance if space is reserved for the number of
    // top level parameters before any are added.
    void reserve(SetDescriptionEntries::size_type n) {
      entries_.reserve(n);
    }

    void validate(ParameterSet & pset) const;

    void writeCfi(std::ostream & os, bool startWithComma, int indentation) const; 

    void print(std::ostream & os, DocFormatHelper & dfh) const; 

    bool isLabelUnused(std::string const& label) const;

  private:

    template<typename T, typename U>
    ParameterDescriptionBase * add(U const& iLabel, T const& value,
                                   bool isTracked, bool isOptional, bool writeToCfi);

    template<typename T, typename U>
    ParameterDescriptionBase * add(U const& iLabel,
                                   bool isTracked, bool isOptional, bool writeToCfi);

    template<typename U>
    ParameterDescriptionBase * addVPSet(U const& iLabel,
                    ParameterSetDescription const& validator,
                                        std::vector<ParameterSet> const& defaults,
                                        bool isTracked, bool isOptional, bool writeToCfi);

    template<typename U>
    ParameterDescriptionBase * addVPSet(U const& iLabel,
                    ParameterSetDescription const& validator,
                                        bool isTracked, bool isOptional, bool writeToCfi);

    template<typename T, typename U>
    ParameterWildcardBase * addWildcard(U const& pattern, bool isTracked);

    ParameterDescriptionNode* addNode(std::auto_ptr<ParameterDescriptionNode> node, bool optional, bool writeToCfi);

    template <typename T>
    ParameterDescriptionNode*
    ifValue(ParameterDescription<T> const& switchParameter,
            std::auto_ptr<ParameterDescriptionCases<T> > cases,
            bool optional, bool writeToCfi);

    ParameterDescriptionNode*
    ifExists(ParameterDescriptionNode const& node1,
             ParameterDescriptionNode const& node2,
             bool optional, bool writeToCfi);

    template<typename T, typename U>
    ParameterDescriptionNode*
    labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi);

    template<typename T, typename U, typename V>
    ParameterDescriptionNode*
    labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi, V const& desc);

    static
    void
    validateNode(SetDescriptionEntry const& entry,
                 ParameterSet & pset,
                 std::set<std::string> & validatedNames);

    static void 
    throwIllegalParameters(std::vector<std::string> const& parameterNames,
                           std::set<std::string> const& validatedNames);

    static void
    writeNode(SetDescriptionEntry const& entry,
              std::ostream & os,
              bool & startWithComma,
              int indentation,
              bool & wroteSomething);

    static void
    printNode(SetDescriptionEntry const& entry,
              std::ostream & os,
              DocFormatHelper & dfh);

    void throwIfLabelsAlreadyUsed(std::set<std::string> const& nodeLabels);
    void throwIfWildcardCollision(std::set<ParameterTypes> const& nodeParameterTypes,
                                  std::set<ParameterTypes> const& nodeWildcardTypes);

    bool anythingAllowed_;
    bool unknown_;
    SetDescriptionEntries entries_;

    std::set<std::string> usedLabels_;
    std::set<ParameterTypes> typesUsedForParameters_;
    std::set<ParameterTypes> typesUsedForWildcards_;    

    std::string comment_;
  };
}

#include "FWCore/ParameterSet/interface/ParameterWildcard.h"
#include "FWCore/ParameterSet/interface/ParameterSwitch.h"
#include "FWCore/ParameterSet/interface/AllowedLabelsDescription.h"

namespace edm {

  template<typename T, typename U>
  ParameterDescriptionBase*
  ParameterSetDescription::add(U const& iLabel, T const& value, bool isTracked, bool isOptional, bool writeToCfi) {

    std::auto_ptr<ParameterDescriptionNode> node(new ParameterDescription<T>(iLabel, value, isTracked));
    ParameterDescriptionNode* pnode = addNode(node, isOptional, writeToCfi);
    return static_cast<ParameterDescriptionBase*>(pnode);
  }

  template<typename T, typename U>
  ParameterDescriptionBase*
  ParameterSetDescription::add(U const& iLabel, bool isTracked, bool isOptional, bool writeToCfi) {

    std::auto_ptr<ParameterDescriptionNode> node(new ParameterDescription<T>(iLabel, isTracked));
    ParameterDescriptionNode* pnode = addNode(node, isOptional, writeToCfi);
    return static_cast<ParameterDescriptionBase*>(pnode);
  }

  template<typename U>
  ParameterDescriptionBase *
  ParameterSetDescription::addVPSet(U const& iLabel,
                                    ParameterSetDescription const& validator,
                                    std::vector<ParameterSet> const& defaults,
                                    bool isTracked, bool isOptional, bool writeToCfi) {
    std::auto_ptr<ParameterDescriptionNode> node(
        new ParameterDescription<std::vector<ParameterSet> >(iLabel, validator, isTracked, defaults));
    ParameterDescriptionNode* pnode = addNode(node, isOptional, writeToCfi);
    return static_cast<ParameterDescriptionBase*>(pnode);
  }

  template<typename U>
  ParameterDescriptionBase *
  ParameterSetDescription::addVPSet(U const& iLabel,
                                    ParameterSetDescription const& validator,
                                    bool isTracked, bool isOptional, bool writeToCfi) {
    std::auto_ptr<ParameterDescriptionNode> node(
        new ParameterDescription<std::vector<ParameterSet> >(iLabel, validator, isTracked));
    ParameterDescriptionNode* pnode = addNode(node, isOptional, writeToCfi);
    return static_cast<ParameterDescriptionBase*>(pnode);
  }

  template<typename T, typename U>
  ParameterWildcardBase*
  ParameterSetDescription::addWildcard(U const& pattern, bool isTracked) {
    
    std::auto_ptr<ParameterDescriptionNode> node(new ParameterWildcard<T>(pattern, RequireZeroOrMore, isTracked));
    ParameterDescriptionNode* pnode = addNode(node, true, false);
    return static_cast<ParameterWildcardBase*>(pnode);
  }

  template <typename T>
  ParameterDescriptionNode*
  ParameterSetDescription::ifValue(ParameterDescription<T> const& switchParameter,
          std::auto_ptr<ParameterDescriptionCases<T> > cases,
          bool optional, bool writeToCfi) {
    std::auto_ptr<ParameterDescriptionNode> pdswitch(new ParameterSwitch<T>(switchParameter, cases));
    return addNode(pdswitch, optional, writeToCfi);
  }

  template<typename T, typename U>
  ParameterDescriptionNode*
  ParameterSetDescription::labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi) {
    std::auto_ptr<ParameterDescriptionNode> pd(new AllowedLabelsDescription<T>(iLabel, isTracked));
    return addNode(pd, optional, writeToCfi);
  }

  template<typename T, typename U, typename V>
  ParameterDescriptionNode*
  ParameterSetDescription::labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi, V const& desc) {
    std::auto_ptr<ParameterDescriptionNode> pd(new AllowedLabelsDescription<T>(iLabel, desc, isTracked));
    return addNode(pd, optional, writeToCfi);
  }
}

#endif