boost/program_options/variables_map.hpp

0001 // Copyright Vladimir Prus 2002-2004.
0002 // Distributed under the Boost Software License, Version 1.0.
0003 // (See accompanying file LICENSE_1_0.txt
0004 // or copy at http://www.boost.org/LICENSE_1_0.txt)
0005
0006
0007 #ifndef BOOST_VARIABLES_MAP_VP_2003_05_19
0008 #define BOOST_VARIABLES_MAP_VP_2003_05_19
0009
0010 #include <boost/program_options/config.hpp>
0011
0012 #include <boost/any.hpp>
0013 #include <boost/shared_ptr.hpp>
0014
0015 #include <string>
0016 #include <map>
0017 #include <set>
0018
0019 #if defined(BOOST_MSVC)
0020 #   pragma warning (push)
0021 #   pragma warning (disable:4251) // 'boost::program_options::variable_value::v' : class 'boost::any' needs to have dll-interface to be used by clients of class 'boost::program_options::variable_value
0022 #endif
0023
0024 namespace boost { namespace program_options {
0025
0026     template<class charT>
0027     class basic_parsed_options;
0028
0029     class value_semantic;
0030     class variables_map;
0031
0032     // forward declaration
0033
0034     /** Stores in 'm' all options that are defined in 'options'.
0035         If 'm' already has a non-defaulted value of an option, that value
0036         is not changed, even if 'options' specify some value.
0037     */
0038     BOOST_PROGRAM_OPTIONS_DECL
0039     void store(const basic_parsed_options<char>& options, variables_map& m,
0040                     bool utf8 = false);
0041
0042     /** Stores in 'm' all options that are defined in 'options'.
0043         If 'm' already has a non-defaulted value of an option, that value
0044         is not changed, even if 'options' specify some value.
0045         This is wide character variant.
0046     */
0047     BOOST_PROGRAM_OPTIONS_DECL
0048     void store(const basic_parsed_options<wchar_t>& options,
0049                     variables_map& m);
0050
0051
0052     /** Runs all 'notify' function for options in 'm'. */
0053     BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map& m);
0054
0055     /** Class holding value of option. Contains details about how the
0056         value is set and allows to conveniently obtain the value.
0057     */
0058     class BOOST_PROGRAM_OPTIONS_DECL variable_value {
0059     public:
0060         variable_value() : m_defaulted(false) {}
0061         variable_value(const boost::any& xv, bool xdefaulted)
0062         : v(xv), m_defaulted(xdefaulted)
0063         {}
0064
0065         /** If stored value if of type T, returns that value. Otherwise,
0066             throws boost::bad_any_cast exception. */
0067        template<class T>
0068        const T& as() const {
0069            return boost::any_cast<const T&>(v);
0070        }
0071        /** @overload */
0072        template<class T>
0073        T& as() {
0074            return boost::any_cast<T&>(v);
0075        }
0076
0077         /// Returns true if no value is stored.
0078         bool empty() const;
0079         /** Returns true if the value was not explicitly
0080             given, but has default value. */
0081         bool defaulted() const;
0082         /** Returns the contained value. */
0083         const boost::any& value() const;
0084
0085         /** Returns the contained value. */
0086         boost::any& value();
0087     private:
0088         boost::any v;
0089         bool m_defaulted;
0090         // Internal reference to value semantic. We need to run
0091         // notifications when *final* values of options are known, and
0092         // they are known only after all sources are stored. By that
0093         // time options_description for the first source might not
0094         // be easily accessible, so we need to store semantic here.
0095         shared_ptr<const value_semantic> m_value_semantic;
0096
0097         friend BOOST_PROGRAM_OPTIONS_DECL
0098         void store(const basic_parsed_options<char>& options,
0099               variables_map& m, bool);
0100
0101         friend class BOOST_PROGRAM_OPTIONS_DECL variables_map;
0102     };
0103
0104     /** Implements string->string mapping with convenient value casting
0105         facilities. */
0106     class BOOST_PROGRAM_OPTIONS_DECL abstract_variables_map {
0107     public:
0108         abstract_variables_map();
0109         abstract_variables_map(const abstract_variables_map* next);
0110
0111         virtual ~abstract_variables_map() {}
0112
0113         /** Obtains the value of variable 'name', from *this and
0114             possibly from the chain of variable maps.
0115
0116             - if there's no value in *this.
0117                 - if there's next variable map, returns value from it
0118                 - otherwise, returns empty value
0119
0120             - if there's defaulted value
0121                 - if there's next variable map, which has a non-defaulted
0122                   value, return that
0123                 - otherwise, return value from *this
0124
0125             - if there's a non-defaulted value, returns it.
0126         */
0127         const variable_value& operator[](const std::string& name) const;
0128
0129         /** Sets next variable map, which will be used to find
0130            variables not found in *this. */
0131         void next(abstract_variables_map* next);
0132
0133     private:
0134         /** Returns value of variable 'name' stored in *this, or
0135             empty value otherwise. */
0136         virtual const variable_value& get(const std::string& name) const = 0;
0137
0138         const abstract_variables_map* m_next;
0139     };
0140
0141     /** Concrete variables map which store variables in real map.
0142
0143         This class is derived from std::map<std::string, variable_value>,
0144         so you can use all map operators to examine its content.
0145     */
0146     class BOOST_PROGRAM_OPTIONS_DECL variables_map : public abstract_variables_map,
0147                                public std::map<std::string, variable_value>
0148     {
0149     public:
0150         variables_map();
0151         variables_map(const abstract_variables_map* next);
0152
0153         // Resolve conflict between inherited operators.
0154         const variable_value& operator[](const std::string& name) const
0155         { return abstract_variables_map::operator[](name); }
0156
0157         // Override to clear some extra fields.
0158         void clear();
0159
0160         void notify();
0161
0162     private:
0163         /** Implementation of abstract_variables_map::get
0164             which does 'find' in *this. */
0165         const variable_value& get(const std::string& name) const;
0166
0167         /** Names of option with 'final' values \-- which should not
0168             be changed by subsequence assignments. */
0169         std::set<std::string> m_final;
0170
0171         friend BOOST_PROGRAM_OPTIONS_DECL
0172         void store(const basic_parsed_options<char>& options,
0173                           variables_map& xm,
0174                           bool utf8);
0175
0176         /** Names of required options, filled by parser which has
0177             access to options_description.
0178             The map values are the "canonical" names for each corresponding option.
0179             This is useful in creating diagnostic messages when the option is absent. */
0180         std::map<std::string, std::string> m_required;
0181     };
0182
0183
0184     /*
0185      * Templates/inlines
0186      */
0187
0188     inline bool
0189     variable_value::empty() const
0190     {
0191         return v.empty();
0192     }
0193
0194     inline bool
0195     variable_value::defaulted() const
0196     {
0197         return m_defaulted;
0198     }
0199
0200     inline
0201     const boost::any&
0202     variable_value::value() const
0203     {
0204         return v;
0205     }
0206
0207     inline
0208     boost::any&
0209     variable_value::value()
0210     {
0211         return v;
0212     }
0213
0214 }}
0215
0216 #if defined(BOOST_MSVC)
0217 #   pragma warning (pop)
0218 #endif
0219
0220 #endif