IpRegOptions.hpp

Go to the documentation of this file.

// Copyright (C) 2004, 2007 International Business Machines and others.
// All Rights Reserved.
// This code is published under the Eclipse Public License.
//
// Authors:  Carl Laird, Andreas Waechter     IBM    2005-06-18
 
#ifndef __IPREGOPTIONS_HPP__
#define __IPREGOPTIONS_HPP__
 
#include "IpUtils.hpp"
#include "IpReferenced.hpp"
#include "IpException.hpp"
#include "IpSmartPtr.hpp"
 
#include <map>
#include <set>
#include <list>
 
namespace Ipopt
{
 
enum RegisteredOptionType
{
   OT_Number,
   OT_Integer,
   OT_String,
   OT_Unknown
};
 
class OptionsList;
class RegisteredOption;
 
class IPOPTLIB_EXPORT RegisteredCategory: public ReferencedObject
{
   friend class RegisteredOptions;
public:
   RegisteredCategory(
      const std::string& name,
      int                priority
   )
      : name_(name),
        priority_(priority)
   { }
 
   const std::string& Name() const
   {
      return name_;
   }
 
   IPOPT_DEPRECATED
   operator const std::string& () const
   {
      return name_;
   }
 
   IPOPT_DEPRECATED
   bool operator!=(
      const std::string& other
   ) const
   {
      return name_ != other;
   }
 
   IPOPT_DEPRECATED
   bool operator==(
      const std::string& other
   ) const
   {
      return name_ == other;
   }
 
   IPOPT_DEPRECATED
   bool operator<(
      const RegisteredCategory& other
   ) const
   {
      return name_ < other.name_;
   }
 
   int Priority() const
   {
      return priority_;
   }
 
   const std::list<SmartPtr<RegisteredOption> >& RegisteredOptions() const
   {
      return regoptions_;
   }
 
   // class comparing two categories by priority
   class ComparePriority
   {
   public:
      bool operator()(
         const SmartPtr<RegisteredCategory>& lhs,
         const SmartPtr<RegisteredCategory>& rhs
      ) const
      {
         DBG_ASSERT(IsValid(lhs));
         DBG_ASSERT(IsValid(rhs));
         return lhs->priority_ > rhs->priority_;
      }
   };
 
private:
   RegisteredCategory();
   RegisteredCategory(const RegisteredCategory&);
   RegisteredCategory& operator=(const RegisteredCategory&);
 
   std::string name_;
 
   int priority_;
 
   std::list<SmartPtr<RegisteredOption> > regoptions_;
};
 
class IPOPTLIB_EXPORT RegisteredOption: public ReferencedObject
{
   friend class RegisteredOptions;
public:
   class string_entry
   {
   public:
      string_entry(
         const std::string& value,
         const std::string& description
      )
         : value_(value),
           description_(description)
      { }
 
      std::string value_;
      std::string description_;
   };
 
   RegisteredOption(
      Index counter
   )
      : type_(OT_Unknown),
        advanced_(false),
        has_lower_(false),
        has_upper_(false),
        counter_(counter)
   { }
 
   RegisteredOption(
      const std::string& name,                                   
      const std::string& short_description,                      
      const std::string& long_description,                       
      const SmartPtr<RegisteredCategory>& registering_category,  
      Index counter,                                             
      bool advanced = false                                      
   )
      : name_(name),
        short_description_(short_description),
        long_description_(long_description),
        registering_category_(registering_category),
        type_(OT_Unknown),
        advanced_(advanced),
        has_lower_(false),
        has_upper_(false),
        counter_(counter)
   { }
 
   RegisteredOption(
      const RegisteredOption& copy
   )
      : name_(copy.name_),
        short_description_(copy.short_description_),
        long_description_(copy.long_description_),
        registering_category_(copy.registering_category_),
        type_(copy.type_),
        advanced_(copy.advanced_),
        has_lower_(copy.has_lower_),
        lower_(copy.lower_),
        has_upper_(copy.has_upper_),
        upper_(copy.upper_),
        valid_strings_(copy.valid_strings_),
        counter_(copy.counter_)
   { }
 
   virtual ~RegisteredOption()
   { }
 
   DECLARE_STD_EXCEPTION(ERROR_CONVERTING_STRING_TO_ENUM);
 
 
   virtual const std::string& Name() const
   {
      return name_;
   }
   virtual void SetName(
      const std::string& name
   )
   {
      name_ = name;
   }
   virtual const std::string& ShortDescription() const
   {
      return short_description_;
   }
 
   virtual const std::string& LongDescription() const
   {
      return long_description_;
   }
 
   virtual void SetShortDescription(
      const std::string& short_description
   )
   {
      short_description_ = short_description;
   }
 
   virtual void SetLongDescription(
      const std::string& long_description
   )
   {
      long_description_ = long_description;
   }
 
   virtual const RegisteredCategory& RegisteringCategory() const
   {
      return *registering_category_;
   }
 
   virtual const RegisteredOptionType& Type() const
   {
      return type_;
 
   }
   virtual void SetType(
      const RegisteredOptionType& type
   )
   {
      type_ = type;
   }
 
   virtual bool Advanced() const
   {
      return advanced_;
   }
   virtual void SetAdvanced(
      bool advanced = true
   )
   {
      advanced_ = advanced;
   }
 
   virtual Index Counter() const
   {
      return counter_;
   }
 
 
   virtual const bool& HasLower() const
   {
      DBG_ASSERT(type_ == OT_Number || type_ == OT_Integer);
      return has_lower_;
   }
 
   virtual const bool& LowerStrict() const
   {
      DBG_ASSERT(type_ == OT_Number && has_lower_ == true);
      return lower_strict_;
   }
 
   virtual Number LowerNumber() const
   {
      DBG_ASSERT(has_lower_ == true && type_ == OT_Number);
      return lower_;
   }
 
   virtual void SetLowerNumber(
      const Number& lower,
      const bool&   strict
   )
   {
      DBG_ASSERT(type_ == OT_Number);
      lower_ = lower;
      lower_strict_ = strict, has_lower_ = true;
   }
 
   virtual Index LowerInteger() const
   {
      DBG_ASSERT(has_lower_ == true && type_ == OT_Integer);
      return (Index) lower_;
   }
 
   virtual void SetLowerInteger(
      const Index& lower
   )
   {
      DBG_ASSERT(type_ == OT_Integer);
      lower_ = (Number) lower;
      has_lower_ = true;
   }
 
   virtual const bool& HasUpper() const
   {
      DBG_ASSERT(type_ == OT_Number || type_ == OT_Integer);
      return has_upper_;
   }
 
   virtual const bool& UpperStrict() const
   {
      DBG_ASSERT(type_ == OT_Number && has_upper_ == true);
      return upper_strict_;
   }
 
   virtual Number UpperNumber() const
   {
      DBG_ASSERT(has_upper_ == true && type_ == OT_Number);
      return upper_;
   }
 
   virtual void SetUpperNumber(
      const Number& upper,
      const bool&   strict
   )
   {
      DBG_ASSERT(type_ == OT_Number);
      upper_ = upper;
      upper_strict_ = strict;
      has_upper_ = true;
   }
 
   virtual Index UpperInteger() const
   {
      DBG_ASSERT(has_upper_ == true && type_ == OT_Integer);
      return (Index) upper_;
   }
 
   virtual void SetUpperInteger(
      const Index& upper
   )
   {
      DBG_ASSERT(type_ == OT_Integer);
      upper_ = (Number) upper;
      has_upper_ = true;
   }
 
   virtual void AddValidStringSetting(
      const std::string& value,
      const std::string& description)
   {
      DBG_ASSERT(type_ == OT_String);
      valid_strings_.push_back(string_entry(value, description));
   }
 
   virtual Number DefaultNumber() const
   {
      DBG_ASSERT(type_ == OT_Number);
      return default_number_;
   }
 
   virtual void SetDefaultNumber(
      const Number& default_value
   )
   {
      DBG_ASSERT(type_ == OT_Number);
      default_number_ = default_value;
   }
 
   virtual Index DefaultInteger() const
   {
      DBG_ASSERT(type_ == OT_Integer);
      return (Index) default_number_;
   }
 
   virtual void SetDefaultInteger(
      const Index& default_value
   )
   {
      DBG_ASSERT(type_ == OT_Integer);
      default_number_ = (Number) default_value;
   }
 
   virtual std::string DefaultString() const
   {
      DBG_ASSERT(type_ == OT_String);
      return default_string_;
   }
 
   virtual Index DefaultStringAsEnum() const
   {
      DBG_ASSERT(type_ == OT_String);
      return MapStringSettingToEnum(default_string_);
   }
 
   virtual void SetDefaultString(
      const std::string& default_value
   )
   {
      DBG_ASSERT(type_ == OT_String);
      default_string_ = default_value;
   }
 
   virtual std::vector<string_entry> GetValidStrings() const
   {
      DBG_ASSERT(type_ == OT_String);
      return valid_strings_;
   }
 
   virtual bool IsValidNumberSetting(
      const Number& value
   ) const
   {
      DBG_ASSERT(type_ == OT_Number);
      if( has_lower_ && ((lower_strict_ == true && value <= lower_) || (lower_strict_ == false && value < lower_)) )
      {
         return false;
      }
      if( has_upper_ && ((upper_strict_ == true && value >= upper_) || (upper_strict_ == false && value > upper_)) )
      {
         return false;
      }
      return true;
   }
 
   virtual bool IsValidIntegerSetting(
      const Index& value
   ) const
   {
      DBG_ASSERT(type_ == OT_Integer);
      if( has_lower_ && value < lower_ )
      {
         return false;
      }
      if( has_upper_ && value > upper_ )
      {
         return false;
      }
      return true;
   }
 
   virtual bool IsValidStringSetting(
      const std::string& value
   ) const;
 
   virtual std::string MapStringSetting(
      const std::string& value
   ) const;
 
   virtual Index MapStringSettingToEnum(
      const std::string& value
   ) const;
 
   virtual void OutputDescription(
      const Journalist& jnlst
   ) const;
 
   virtual void OutputShortDescription(
      const Journalist& jnlst
   ) const;
 
   virtual void OutputLatexDescription(
      const Journalist& jnlst
   ) const;
 
   virtual void OutputDoxygenDescription(
      const Journalist& jnlst
   ) const;
 
private:
   std::string name_;
   std::string short_description_;
   std::string long_description_;
   SmartPtr<RegisteredCategory> registering_category_;
   RegisteredOptionType type_;
   bool advanced_;
 
   bool has_lower_;
   bool lower_strict_;
   Number lower_;
   bool has_upper_;
   bool upper_strict_;
   Number upper_;
   Number default_number_;
 
   std::vector<string_entry> valid_strings_;
   std::string default_string_;
 
   const Index counter_;
 
   void MakeValidLatexString(
      const std::string& source,
      std::string&       dest
   ) const;
 
   std::string MakeValidLatexNumber(
      Number value
   ) const;
 
   std::string MakeValidHTMLNumber(
      Number value
   ) const;
 
   bool string_equal_insensitive(
      const std::string& s1,
      const std::string& s2
   ) const;
};
 
class IPOPTLIB_EXPORT RegisteredOptions: public ReferencedObject
{
public:
   typedef std::map<std::string, SmartPtr<RegisteredOption> > RegOptionsList;
   typedef std::map<std::string, SmartPtr<RegisteredCategory> > RegCategoriesList;
   typedef std::set<SmartPtr<RegisteredCategory>, RegisteredCategory::ComparePriority> RegCategoriesByPriority;
 
   enum OutputMode
   {
      OUTPUTTEXT = 0,
      OUTPUTLATEX,
      OUTPUTDOXYGEN
   };
 
 
   RegisteredOptions()
      : next_counter_(0)
   { }
 
   virtual ~RegisteredOptions()
   {
      // break circular reference between registered options and registered categories
      for( RegCategoriesList::iterator it(registered_categories_.begin()); it != registered_categories_.end(); ++it )
      {
         it->second->regoptions_.clear();
      }
   }
 
   DECLARE_STD_EXCEPTION(OPTION_ALREADY_REGISTERED);
 
   virtual void SetRegisteringCategory(
      const std::string& registering_category, 
      int                priority = 0          
   );
 
   virtual void SetRegisteringCategory(
      SmartPtr<RegisteredCategory> registering_category
   );
 
   virtual SmartPtr<RegisteredCategory> RegisteringCategory()
   {
      return current_registering_category_;
   }
 
   virtual void AddNumberOption(
      const std::string& name,                  
      const std::string& short_description,     
      Number             default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddLowerBoundedNumberOption(
      const std::string& name,                  
      const std::string& short_description,     
      Number             lower,                 
      bool               strict,                
      Number             default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddUpperBoundedNumberOption(
      const std::string& name,                  
      const std::string& short_description,     
      Number             upper,                 
      bool               strict,                
      Number             default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddBoundedNumberOption(
      const std::string& name,                  
      const std::string& short_description,     
      Number             lower,                 
      bool               lower_strict,          
      Number             upper,                 
      bool               upper_strict,          
      Number             default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddIntegerOption(
      const std::string& name,                  
      const std::string& short_description,     
      Index              default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddLowerBoundedIntegerOption(
      const std::string& name,                  
      const std::string& short_description,     
      Index              lower,                 
      Index              default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddUpperBoundedIntegerOption(
      const std::string& name,                  
      const std::string& short_description,     
      Index              upper,                 
      Index              default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddBoundedIntegerOption(
      const std::string& name,                  
      const std::string& short_description,     
      Index              lower,                 
      Index              upper,                 
      Index              default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::vector<std::string>& settings, 
      const std::vector<std::string>& descriptions, 
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption1(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption2(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption3(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption4(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& setting4,              
      const std::string& description4,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption5(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& setting4,              
      const std::string& description4,          
      const std::string& setting5,              
      const std::string& description5,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption6(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& setting4,              
      const std::string& description4,          
      const std::string& setting5,              
      const std::string& description5,          
      const std::string& setting6,              
      const std::string& description6,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption7(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& setting4,              
      const std::string& description4,          
      const std::string& setting5,              
      const std::string& description5,          
      const std::string& setting6,              
      const std::string& description6,          
      const std::string& setting7,              
      const std::string& description7,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption8(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& setting4,              
      const std::string& description4,          
      const std::string& setting5,              
      const std::string& description5,          
      const std::string& setting6,              
      const std::string& description6,          
      const std::string& setting7,              
      const std::string& description7,          
      const std::string& setting8,              
      const std::string& description8,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption9(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& setting4,              
      const std::string& description4,          
      const std::string& setting5,              
      const std::string& description5,          
      const std::string& setting6,              
      const std::string& description6,          
      const std::string& setting7,              
      const std::string& description7,          
      const std::string& setting8,              
      const std::string& description8,          
      const std::string& setting9,              
      const std::string& description9,          
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddStringOption10(
      const std::string& name,                  
      const std::string& short_description,     
      const std::string& default_value,         
      const std::string& setting1,              
      const std::string& description1,          
      const std::string& setting2,              
      const std::string& description2,          
      const std::string& setting3,              
      const std::string& description3,          
      const std::string& setting4,              
      const std::string& description4,          
      const std::string& setting5,              
      const std::string& description5,          
      const std::string& setting6,              
      const std::string& description6,          
      const std::string& setting7,              
      const std::string& description7,          
      const std::string& setting8,              
      const std::string& description8,          
      const std::string& setting9,              
      const std::string& description9,          
      const std::string& setting10,             
      const std::string& description10,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual void AddBoolOption(
      const std::string& name,                  
      const std::string& short_description,     
      bool               default_value,         
      const std::string& long_description = "", 
      bool               advanced = false       
   );
 
   virtual SmartPtr<const RegisteredOption> GetOption(
      const std::string& name
   );
 
   const RegOptionsList& RegisteredOptionsList() const
   {
      return registered_options_;
   }
 
   const RegCategoriesList& RegisteredCategories() const
   {
      return registered_categories_;
   }
 
   void RegisteredCategoriesByPriority(
      RegCategoriesByPriority& categories
   ) const;
 
   virtual void OutputOptionDocumentation(
      const Journalist&             jnlst,
      SmartPtr<OptionsList>         options,
      int                           minpriority = 0
   ) const;
 
   IPOPT_DEPRECATED
   virtual void OutputOptionDocumentation(
      const Journalist&             jnlst,
      const std::list<std::string>& categories = std::list<std::string>()
   ) const;
 
   IPOPT_DEPRECATED
   virtual void OutputLatexOptionDocumentation(
      const Journalist&             jnlst,
      const std::list<std::string>& options_to_print = std::list<std::string>()
   ) const;
 
   IPOPT_DEPRECATED
   virtual void OutputDoxygenOptionDocumentation(
      const Journalist&             jnlst,
      const std::list<std::string>& options_to_print = std::list<std::string>()
   ) const;
 
   static void RegisterOptions(
      SmartPtr<RegisteredOptions> roptions
   );
 
private:
   void AddOption(
      const SmartPtr<RegisteredOption>& option
   );
 
   RegOptionsList registered_options_;
   RegCategoriesList registered_categories_;
 
   Index next_counter_;
   SmartPtr<RegisteredCategory> current_registering_category_;
};
 
} // namespace Ipopt
 
#endif