Reference Manual

Go to the documentation of this file.
00001 #ifndef FWCore_ParameterSet_ParameterSetDescription_h
00002 #define FWCore_ParameterSet_ParameterSetDescription_h
00003 // -*- C++ -*-
00004 //
00005 // Package:     ParameterSet
00006 // Class  :     ParameterSetDescription
00007 // 
00026 //
00027 // Original Author:  Chris Jones
00028 //         Created:  Tue Jul 31 15:18:40 EDT 2007
00029 //
00030 
00031 #include "FWCore/Utilities/interface/value_ptr.h"
00032 #include "FWCore/ParameterSet/interface/ParameterDescriptionNode.h"
00033 
00034 #include <vector>
00035 #include <set>
00036 #include <string>
00037 #include <memory>
00038 #include <iosfwd>
00039 
00040 namespace edm {
00041 
00042   class ParameterSet;
00043   class ParameterDescriptionBase;
00044   class ParameterWildcardBase;
00045   class ParameterDescriptionNode;
00046   template <typename T> class ParameterDescription;
00047   template <typename T> class ParameterDescriptionCases;
00048   class DocFormatHelper;
00049 
00050   class ParameterSetDescription {
00051   public:
00052     class SetDescriptionEntry {
00053     public:
00054       bool optional() const { return optional_; }
00055       bool writeToCfi() const { return writeToCfi_; }
00056       edm::value_ptr<ParameterDescriptionNode> const& node() const { return node_; }
00057       void setOptional(bool value) { optional_ = value; }
00058       void setWriteToCfi(bool value) { writeToCfi_ = value; }
00059       void setNode(std::auto_ptr<ParameterDescriptionNode> node) { node_ = node; }
00060     private:
00061       bool optional_;
00062       bool writeToCfi_;
00063       edm::value_ptr<ParameterDescriptionNode> node_;
00064     };
00065 
00066     typedef std::vector<SetDescriptionEntry> SetDescriptionEntries;
00067     typedef SetDescriptionEntries::const_iterator const_iterator;
00068 
00069     ParameterSetDescription();
00070     virtual ~ParameterSetDescription();
00071 
00072     std::string const& comment() const { return comment_; }
00073     void setComment(std::string const & value);
00074     void setComment(char const* value);
00075 
00077     void setAllowAnything();
00078       
00079     // This is set only for parameterizables which have not set their descriptions.
00080     // This should only be called to allow backwards compatibility.
00081     void setUnknown();
00082 
00083     // ***** In these next 8 functions named "add", T is the parameter type ******
00084     // Exceptions: For parameters of type ParameterSet, T should be a
00085     // ParameterSetDescription instead of a ParameterSet.  And do not
00086     // use these next 8 functions for parameters of type vector<ParameterSet>
00087 
00088     template<typename T, typename U>
00089     ParameterDescriptionBase * add(U const& iLabel, T const& value) {
00090       return add<T, U>(iLabel, value, true, false, true);
00091     }
00092 
00093     template<typename T, typename U>
00094     ParameterDescriptionBase * addUntracked(U const& iLabel, T const& value) {
00095       return add<T, U>(iLabel, value, false, false, true);
00096     }
00097 
00098     template<typename T, typename U>
00099     ParameterDescriptionBase * addOptional(U const& iLabel, T const& value) {
00100       return add<T, U>(iLabel, value, true, true, true);
00101     }
00102 
00103     template<typename T, typename U>
00104     ParameterDescriptionBase * addOptionalUntracked(U const& iLabel, T const& value) {
00105       return add<T, U>(iLabel, value, false, true, true);
00106     }
00107 
00108     // For the next 4 functions, there is no default so they will not get injected
00109     // during validation if missing and they will not get written into cfi files.
00110 
00111     template<typename T, typename U>
00112     ParameterDescriptionBase * add(U const& iLabel) {
00113       return add<T, U>(iLabel, true, false, false);
00114     }
00115 
00116     template<typename T, typename U>
00117     ParameterDescriptionBase * addUntracked(U const& iLabel) {
00118       return add<T, U>(iLabel, false, false, false);
00119     }
00120 
00121     template<typename T, typename U>
00122     ParameterDescriptionBase * addOptional(U const& iLabel) {
00123       return add<T, U>(iLabel, true, true, false);
00124     }
00125 
00126     template<typename T, typename U>
00127     ParameterDescriptionBase * addOptionalUntracked(U const& iLabel) {
00128       return add<T, U>(iLabel, false, true, false);
00129     }
00130 
00131     // ***** Use these 8 functions for parameters of type vector<ParameterSet> *****
00132     // When a vector<ParameterSet> appears in a configuration, all of its
00133     // elements will be validated using the description in the argument named
00134     // "validator" below.  The argument named "defaults" is used when the
00135     // a vector<ParameterSet> is required to be in the configuration and
00136     // is absent.  Note that these default ParameterSet's will be validated
00137     // as if they had appeared in the configuration so they must be consistent
00138     // with the description and missing parameters that have defaults in
00139     // in the description will be inserted during validation.  These defaults
00140     // are also used when writing cfi files.
00141 
00142     template<typename U>
00143     ParameterDescriptionBase * addVPSet(U const& iLabel,
00144                                         ParameterSetDescription const& validator,
00145                                         std::vector<ParameterSet> const& defaults) {
00146       return addVPSet<U>(iLabel, validator, defaults, true, false, true);
00147     }
00148 
00149     template<typename U>
00150     ParameterDescriptionBase * addVPSetUntracked(U const& iLabel,
00151                                         ParameterSetDescription const& validator,
00152                                         std::vector<ParameterSet> const& defaults) {
00153       return addVPSet<U>(iLabel, validator, defaults, false, false, true);
00154     }
00155 
00156     template<typename U>
00157     ParameterDescriptionBase * addVPSetOptional(U const& iLabel,
00158                                         ParameterSetDescription const& validator,
00159                                         std::vector<ParameterSet> const& defaults) {
00160       return addVPSet<U>(iLabel, validator, defaults, true, true, true);
00161     }
00162 
00163     template<typename U>
00164     ParameterDescriptionBase * addVPSetOptionalUntracked(U const& iLabel,
00165                                         ParameterSetDescription const& validator,
00166                                         std::vector<ParameterSet> const& defaults) {
00167       return addVPSet<U>(iLabel, validator, defaults, false, true, true);
00168     }
00169 
00170     template<typename U>
00171     ParameterDescriptionBase * addVPSet(U const& iLabel,
00172                                         ParameterSetDescription const& validator) {
00173       return addVPSet<U>(iLabel, validator, true, false, false);
00174     }
00175 
00176     template<typename U>
00177     ParameterDescriptionBase * addVPSetUntracked(U const& iLabel,
00178                                         ParameterSetDescription const& validator) {
00179       return addVPSet<U>(iLabel, validator, false, false, false);
00180     }
00181 
00182     template<typename U>
00183     ParameterDescriptionBase * addVPSetOptional(U const& iLabel,
00184                                         ParameterSetDescription const& validator) {
00185       return addVPSet<U>(iLabel, validator, true, true, false);
00186     }
00187 
00188     template<typename U>
00189     ParameterDescriptionBase * addVPSetOptionalUntracked(U const& iLabel,
00190                                         ParameterSetDescription const& validator) {
00191       return addVPSet<U>(iLabel, validator, false, true, false);
00192     }
00193 
00194     // ********* Wildcards *********
00195 
00196     template<typename T, typename U>
00197     ParameterWildcardBase * addWildcard(U const& pattern) {
00198       return addWildcard<T, U>(pattern, true);
00199     }
00200 
00201     template<typename T, typename U>
00202     ParameterWildcardBase * addWildcardUntracked(U const& pattern) {
00203       return addWildcard<T, U>(pattern, false);
00204     }
00205 
00206     // ********* Used to insert generic nodes of any type ************
00207 
00208     ParameterDescriptionNode* addNode(ParameterDescriptionNode const& node);
00209     ParameterDescriptionNode* addNode(std::auto_ptr<ParameterDescriptionNode> node);
00210     ParameterDescriptionNode* addOptionalNode(ParameterDescriptionNode const& node, bool writeToCfi);
00211     ParameterDescriptionNode* addOptionalNode(std::auto_ptr<ParameterDescriptionNode> node, bool writeToCfi);
00212 
00213     // ********* Switches ************
00214     // ifValue will only work with type T as a bool, int, or string.
00215     // T holds the value of the switch variable.
00216     // If you try using any other type, then it will not compile.
00217     template <typename T>
00218     ParameterDescriptionNode*
00219     ifValue(ParameterDescription<T> const& switchParameter,
00220             std::auto_ptr<ParameterDescriptionCases<T> > cases) {
00221       return ifValue<T>(switchParameter, cases, false, true);
00222     }
00223 
00224     template <typename T>
00225     ParameterDescriptionNode*
00226     ifValueOptional(ParameterDescription<T> const& switchParameter,
00227                     std::auto_ptr<ParameterDescriptionCases<T> > cases,
00228                     bool writeToCfi) {
00229       return ifValue<T>(switchParameter, cases, true, writeToCfi);
00230     }
00231 
00232     // ********* if exists ************
00233     ParameterDescriptionNode*
00234     ifExists(ParameterDescriptionNode const& node1,
00235              ParameterDescriptionNode const& node2) {
00236       return ifExists(node1, node2, false, true);
00237     }
00238 
00239     ParameterDescriptionNode*
00240     ifExistsOptional(ParameterDescriptionNode const& node1,
00241                           ParameterDescriptionNode const& node2,
00242                           bool writeToCfi) {
00243       return ifExists(node1, node2, true, writeToCfi);
00244     }
00245 
00246     // ********* for parameters that are a list of allowed labels *********
00247     template<typename T, typename U>
00248     ParameterDescriptionNode*
00249     labelsFrom(U const& iLabel) {
00250       return labelsFrom<T,U>(iLabel, true, false, true);
00251     }
00252 
00253     template<typename T, typename U>
00254     ParameterDescriptionNode*
00255     labelsFromUntracked(U const& iLabel) {
00256       return labelsFrom<T,U>(iLabel, false, false, true);
00257     }
00258 
00259     template<typename T, typename U>
00260     ParameterDescriptionNode*
00261     labelsFromOptional(U const& iLabel, bool writeToCfi) {
00262       return labelsFrom<T,U>(iLabel, true, true, writeToCfi);
00263     }
00264 
00265     template<typename T, typename U>
00266     ParameterDescriptionNode*
00267     labelsFromOptionalUntracked(U const& iLabel, bool writeToCfi) {
00268       return labelsFrom<T,U>(iLabel, false, true, writeToCfi);
00269     }
00270 
00271     // These next four functions only work when the template
00272     // parameters are:
00273     // T = ParameterSetDescription and V = ParameterSetDescription
00274     // or
00275     // T = vector<ParameterSet> and V = ParameterSetDescription
00276     // In either case U can be either a string or char*
00277     // Note the U and V can be determined from the arguments, but
00278     // T must be explicitly specified by the calling function.
00279     template<typename T, typename U, typename V>
00280     ParameterDescriptionNode*
00281     labelsFrom(U const& iLabel, V const& desc) {
00282       return labelsFrom<T,U,V>(iLabel, true, false, true, desc);
00283     }
00284 
00285     template<typename T, typename U, typename V>
00286     ParameterDescriptionNode*
00287     labelsFromUntracked(U const& iLabel, V const& desc) {
00288       return labelsFrom<T,U,V>(iLabel, false, false, true, desc);
00289     }
00290 
00291     template<typename T, typename U, typename V>
00292     ParameterDescriptionNode*
00293     labelsFromOptional(U const& iLabel, bool writeToCfi, V const& desc) {
00294       return labelsFrom<T,U,V>(iLabel, true, true, writeToCfi, desc);
00295     }
00296 
00297     template<typename T, typename U, typename V>
00298     ParameterDescriptionNode*
00299     labelsFromOptionalUntracked(U const& iLabel, bool writeToCfi, V const& desc) {
00300       return labelsFrom<T,U,V>(iLabel, false, true, writeToCfi, desc);
00301     }
00302 
00303     bool anythingAllowed() const { return anythingAllowed_; }
00304     bool isUnknown() const { return unknown_; }
00305 
00306     const_iterator begin() const {
00307       return entries_.begin();
00308     }
00309 
00310     const_iterator end() const {
00311       return entries_.end();
00312     }
00313 
00314     // Better performance if space is reserved for the number of
00315     // top level parameters before any are added.
00316     void reserve(SetDescriptionEntries::size_type n) {
00317       entries_.reserve(n);
00318     }
00319 
00320     void validate(ParameterSet & pset) const;
00321 
00322     void writeCfi(std::ostream & os, bool startWithComma, int indentation) const; 
00323 
00324     void print(std::ostream & os, DocFormatHelper & dfh) const; 
00325 
00326   private:
00327 
00328     template<typename T, typename U>
00329     ParameterDescriptionBase * add(U const& iLabel, T const& value,
00330                                    bool isTracked, bool isOptional, bool writeToCfi);
00331 
00332     template<typename T, typename U>
00333     ParameterDescriptionBase * add(U const& iLabel,
00334                                    bool isTracked, bool isOptional, bool writeToCfi);
00335 
00336     template<typename U>
00337     ParameterDescriptionBase * addVPSet(U const& iLabel,
00338                                         ParameterSetDescription const& validator,
00339                                         std::vector<ParameterSet> const& defaults,
00340                                         bool isTracked, bool isOptional, bool writeToCfi);
00341 
00342     template<typename U>
00343     ParameterDescriptionBase * addVPSet(U const& iLabel,
00344                                         ParameterSetDescription const& validator,
00345                                         bool isTracked, bool isOptional, bool writeToCfi);
00346 
00347     template<typename T, typename U>
00348     ParameterWildcardBase * addWildcard(U const& pattern, bool isTracked);
00349 
00350     ParameterDescriptionNode* addNode(std::auto_ptr<ParameterDescriptionNode> node, bool optional, bool writeToCfi);
00351 
00352     template <typename T>
00353     ParameterDescriptionNode*
00354     ifValue(ParameterDescription<T> const& switchParameter,
00355             std::auto_ptr<ParameterDescriptionCases<T> > cases,
00356             bool optional, bool writeToCfi);
00357 
00358     ParameterDescriptionNode*
00359     ifExists(ParameterDescriptionNode const& node1,
00360              ParameterDescriptionNode const& node2,
00361              bool optional, bool writeToCfi);
00362 
00363     template<typename T, typename U>
00364     ParameterDescriptionNode*
00365     labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi);
00366 
00367     template<typename T, typename U, typename V>
00368     ParameterDescriptionNode*
00369     labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi, V const& desc);
00370 
00371     static
00372     void
00373     validateNode(SetDescriptionEntry const& entry,
00374                  ParameterSet & pset,
00375                  std::set<std::string> & validatedNames);
00376 
00377     static void 
00378     throwIllegalParameters(std::vector<std::string> const& parameterNames,
00379                            std::set<std::string> const& validatedNames);
00380 
00381     static void
00382     writeNode(SetDescriptionEntry const& entry,
00383               std::ostream & os,
00384               bool & startWithComma,
00385               int indentation,
00386               bool & wroteSomething);
00387 
00388     static void
00389     printNode(SetDescriptionEntry const& entry,
00390               std::ostream & os,
00391               DocFormatHelper & dfh);
00392 
00393     void throwIfLabelsAlreadyUsed(std::set<std::string> const& nodeLabels);
00394     void throwIfWildcardCollision(std::set<ParameterTypes> const& nodeParameterTypes,
00395                                   std::set<ParameterTypes> const& nodeWildcardTypes);
00396 
00397     bool anythingAllowed_;
00398     bool unknown_;
00399     SetDescriptionEntries entries_;
00400 
00401     std::set<std::string> usedLabels_;
00402     std::set<ParameterTypes> typesUsedForParameters_;
00403     std::set<ParameterTypes> typesUsedForWildcards_;    
00404 
00405     std::string comment_;
00406   };
00407 }
00408 
00409 #include "FWCore/ParameterSet/interface/ParameterWildcard.h"
00410 #include "FWCore/ParameterSet/interface/ParameterSwitch.h"
00411 #include "FWCore/ParameterSet/interface/AllowedLabelsDescription.h"
00412 
00413 namespace edm {
00414 
00415   template<typename T, typename U>
00416   ParameterDescriptionBase*
00417   ParameterSetDescription::add(U const& iLabel, T const& value, bool isTracked, bool isOptional, bool writeToCfi) {
00418 
00419     std::auto_ptr<ParameterDescriptionBase> pdbase(new ParameterDescription<T>(iLabel, value, isTracked));
00420     ParameterDescriptionBase* pdReturn = pdbase.get();
00421     std::auto_ptr<ParameterDescriptionNode> node(pdbase);
00422     addNode(node, isOptional, writeToCfi);
00423 
00424     return pdReturn;
00425   }
00426 
00427   template<typename T, typename U>
00428   ParameterDescriptionBase*
00429   ParameterSetDescription::add(U const& iLabel, bool isTracked, bool isOptional, bool writeToCfi) {
00430 
00431     std::auto_ptr<ParameterDescriptionBase> pdbase(new ParameterDescription<T>(iLabel, isTracked));
00432     ParameterDescriptionBase* pdReturn = pdbase.get();
00433     std::auto_ptr<ParameterDescriptionNode> node(pdbase);
00434     addNode(node, isOptional, writeToCfi);
00435 
00436     return pdReturn;
00437   }
00438 
00439   template<typename U>
00440   ParameterDescriptionBase *
00441   ParameterSetDescription::addVPSet(U const& iLabel,
00442                                     ParameterSetDescription const& validator,
00443                                     std::vector<ParameterSet> const& defaults,
00444                                     bool isTracked, bool isOptional, bool writeToCfi) {
00445     std::auto_ptr<ParameterDescriptionBase> pdbase(
00446         new ParameterDescription<std::vector<ParameterSet> >(iLabel, validator, isTracked, defaults));
00447 
00448     ParameterDescriptionBase* pdReturn = pdbase.get();
00449     std::auto_ptr<ParameterDescriptionNode> node(pdbase);
00450     addNode(node, isOptional, writeToCfi);
00451 
00452     return pdReturn;
00453   }
00454 
00455   template<typename U>
00456   ParameterDescriptionBase *
00457   ParameterSetDescription::addVPSet(U const& iLabel,
00458                                     ParameterSetDescription const& validator,
00459                                     bool isTracked, bool isOptional, bool writeToCfi) {
00460     std::auto_ptr<ParameterDescriptionBase> pdbase(
00461         new ParameterDescription<std::vector<ParameterSet> >(iLabel, validator, isTracked));
00462 
00463     ParameterDescriptionBase* pdReturn = pdbase.get();
00464     std::auto_ptr<ParameterDescriptionNode> node(pdbase);
00465     addNode(node, isOptional, writeToCfi);
00466 
00467     return pdReturn;
00468   }
00469 
00470   template<typename T, typename U>
00471   ParameterWildcardBase*
00472   ParameterSetDescription::addWildcard(U const& pattern, bool isTracked) {
00473     
00474     std::auto_ptr<ParameterWildcardBase> pdbase(new ParameterWildcard<T>(pattern, RequireZeroOrMore, isTracked));
00475     ParameterWildcardBase * pdReturn = pdbase.get();
00476     std::auto_ptr<ParameterDescriptionNode> node(pdbase);
00477     addNode(node, true, false);
00478 
00479     return pdReturn;
00480   }
00481 
00482   template <typename T>
00483   ParameterDescriptionNode*
00484   ParameterSetDescription::ifValue(ParameterDescription<T> const& switchParameter,
00485           std::auto_ptr<ParameterDescriptionCases<T> > cases,
00486           bool optional, bool writeToCfi) {
00487     std::auto_ptr<ParameterDescriptionNode> pdswitch(new ParameterSwitch<T>(switchParameter, cases));
00488     return addNode(pdswitch, optional, writeToCfi);
00489   }
00490 
00491   template<typename T, typename U>
00492   ParameterDescriptionNode*
00493   ParameterSetDescription::labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi) {
00494     std::auto_ptr<ParameterDescriptionNode> pd(new AllowedLabelsDescription<T>(iLabel, isTracked));
00495     return addNode(pd, optional, writeToCfi);
00496   }
00497 
00498   template<typename T, typename U, typename V>
00499   ParameterDescriptionNode*
00500   ParameterSetDescription::labelsFrom(U const& iLabel, bool isTracked, bool optional, bool writeToCfi, V const& desc) {
00501     std::auto_ptr<ParameterDescriptionNode> pd(new AllowedLabelsDescription<T>(iLabel, desc, isTracked));
00502     return addNode(pd, optional, writeToCfi);
00503   }
00504 }
00505 
00506 #endif
/data/refman/pasoursint/CMSSW_4_1_8_patch13/src/FWCore/ParameterSet/interface/ParameterSetDescription.h
