Chris@16: // Copyright Vladimir Prus 2002-2004.
Chris@16: // Copyright Bertolt Mildner 2004.
Chris@16: // Distributed under the Boost Software License, Version 1.0.
Chris@16: // (See accompanying file LICENSE_1_0.txt
Chris@16: // or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16: 
Chris@16: 
Chris@16: #ifndef BOOST_OPTION_DESCRIPTION_VP_2003_05_19
Chris@16: #define BOOST_OPTION_DESCRIPTION_VP_2003_05_19
Chris@16: 
Chris@16: #include <boost/program_options/config.hpp>
Chris@16: #include <boost/program_options/errors.hpp>
Chris@16: #include <boost/program_options/value_semantic.hpp>
Chris@16: 
Chris@16: #include <boost/function.hpp>
Chris@16: #include <boost/shared_ptr.hpp>
Chris@16: #include <boost/detail/workaround.hpp>
Chris@16: #include <boost/any.hpp>
Chris@16: 
Chris@16: #include <string>
Chris@16: #include <vector>
Chris@16: #include <set>
Chris@16: #include <map>
Chris@16: #include <stdexcept>
Chris@16: 
Chris@16: #include <iosfwd>
Chris@16: 
Chris@16: #if defined(BOOST_MSVC)
Chris@16: #   pragma warning (push)
Chris@16: #   pragma warning (disable:4251) // class 'boost::shared_ptr<T>' needs to have dll-interface to be used by clients of class 'boost::program_options::option_description'
Chris@16: #endif
Chris@16: 
Chris@16: 
Chris@16: /** Boost namespace */
Chris@16: namespace boost { 
Chris@16: /** Namespace for the library. */
Chris@16: namespace program_options {
Chris@16: 
Chris@16:     /** Describes one possible command line/config file option. There are two
Chris@16:         kinds of properties of an option. First describe it syntactically and
Chris@16:         are used only to validate input. Second affect interpretation of the
Chris@16:         option, for example default value for it or function that should be
Chris@16:         called  when the value is finally known. Routines which perform parsing
Chris@16:         never use second kind of properties -- they are side effect free.
Chris@16:         @sa options_description
Chris@16:     */
Chris@16:     class BOOST_PROGRAM_OPTIONS_DECL option_description {
Chris@16:     public:
Chris@16: 
Chris@16:         option_description();
Chris@16: 
Chris@16:         /** Initializes the object with the passed data.
Chris@16: 
Chris@16:             Note: it would be nice to make the second parameter auto_ptr,
Chris@16:             to explicitly pass ownership. Unfortunately, it's often needed to
Chris@16:             create objects of types derived from 'value_semantic':
Chris@16:                options_description d;
Chris@16:                d.add_options()("a", parameter<int>("n")->default_value(1));
Chris@16:             Here, the static type returned by 'parameter' should be derived
Chris@16:             from value_semantic.
Chris@16: 
Chris@16:             Alas, derived->base conversion for auto_ptr does not really work,
Chris@16:             see
Chris@101:             http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf
Chris@101:             http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#84
Chris@16: 
Chris@16:             So, we have to use plain old pointers. Besides, users are not
Chris@16:             expected to use the constructor directly.
Chris@16: 
Chris@16:             
Chris@16:             The 'name' parameter is interpreted by the following rules:
Chris@16:             - if there's no "," character in 'name', it specifies long name
Chris@16:             - otherwise, the part before "," specifies long name and the part
Chris@16:             after -- short name.
Chris@16:         */
Chris@16:         option_description(const char* name,
Chris@16:                            const value_semantic* s);
Chris@16: 
Chris@16:         /** Initializes the class with the passed data. 
Chris@16:          */
Chris@16:         option_description(const char* name,
Chris@16:                            const value_semantic* s,
Chris@16:                            const char* description);
Chris@16: 
Chris@16:         virtual ~option_description();
Chris@16: 
Chris@16:         enum match_result { no_match, full_match, approximate_match };
Chris@16: 
Chris@16:         /** Given 'option', specified in the input source,
Chris@16:             returns 'true' if 'option' specifies *this.
Chris@16:         */
Chris@16:         match_result match(const std::string& option, bool approx,
Chris@16:                            bool long_ignore_case, bool short_ignore_case) const;
Chris@16: 
Chris@16:         /** Returns the key that should identify the option, in
Chris@16:             particular in the variables_map class.
Chris@16:             The 'option' parameter is the option spelling from the
Chris@16:             input source.
Chris@16:             If option name contains '*', returns 'option'.
Chris@16:             If long name was specified, it's the long name, otherwise
Chris@16:             it's a short name with prepended '-'.
Chris@16:         */
Chris@16:         const std::string& key(const std::string& option) const;
Chris@16: 
Chris@16: 
Chris@16:         /** Returns the canonical name for the option description to enable the user to
Chris@16:             recognised a matching option.
Chris@16:             1) For short options ('-', '/'), returns the short name prefixed.
Chris@16:             2) For long options ('--' / '-') returns the long name prefixed
Chris@16:             3) All other cases, returns the long name (if present) or the short name,
Chris@16:                 unprefixed.
Chris@16:         */
Chris@16:         std::string canonical_display_name(int canonical_option_style = 0) const;
Chris@16: 
Chris@16:         const std::string& long_name() const;
Chris@16: 
Chris@16:         /// Explanation of this option
Chris@16:         const std::string& description() const;
Chris@16: 
Chris@16:         /// Semantic of option's value
Chris@16:         shared_ptr<const value_semantic> semantic() const;
Chris@16:         
Chris@16:         /// Returns the option name, formatted suitably for usage message. 
Chris@16:         std::string format_name() const;
Chris@16: 
Chris@16:         /** Returns the parameter name and properties, formatted suitably for
Chris@16:             usage message. */
Chris@16:         std::string format_parameter() const;
Chris@16: 
Chris@16:     private:
Chris@16:     
Chris@16:         option_description& set_name(const char* name);
Chris@16: 
Chris@16:         std::string m_short_name, m_long_name, m_description;
Chris@16:         // shared_ptr is needed to simplify memory management in
Chris@16:         // copy ctor and destructor.
Chris@16:         shared_ptr<const value_semantic> m_value_semantic;
Chris@16:     };
Chris@16: 
Chris@16:     class options_description;
Chris@16: 
Chris@16:     /** Class which provides convenient creation syntax to option_description. 
Chris@16:      */        
Chris@16:     class BOOST_PROGRAM_OPTIONS_DECL options_description_easy_init {
Chris@16:     public:
Chris@16:         options_description_easy_init(options_description* owner);
Chris@16: 
Chris@16:         options_description_easy_init&
Chris@16:         operator()(const char* name,
Chris@16:                    const char* description);
Chris@16: 
Chris@16:         options_description_easy_init&
Chris@16:         operator()(const char* name,
Chris@16:                    const value_semantic* s);
Chris@16:         
Chris@16:         options_description_easy_init&
Chris@16:         operator()(const char* name,
Chris@16:                    const value_semantic* s,
Chris@16:                    const char* description);
Chris@16:        
Chris@16:     private:
Chris@16:         options_description* owner;
Chris@16:     };
Chris@16: 
Chris@16: 
Chris@16:     /** A set of option descriptions. This provides convenient interface for
Chris@16:         adding new option (the add_options) method, and facilities to search
Chris@16:         for options by name.
Chris@16:         
Chris@16:         See @ref a_adding_options "here" for option adding interface discussion.
Chris@16:         @sa option_description
Chris@16:     */
Chris@16:     class BOOST_PROGRAM_OPTIONS_DECL options_description {
Chris@16:     public:
Chris@16:         static const unsigned m_default_line_length;
Chris@16:         
Chris@16:         /** Creates the instance. */
Chris@16:         options_description(unsigned line_length = m_default_line_length,
Chris@16:                             unsigned min_description_length = m_default_line_length / 2);
Chris@16:         /** Creates the instance. The 'caption' parameter gives the name of
Chris@16:             this 'options_description' instance. Primarily useful for output.
Chris@16:             The 'description_length' specifies the number of columns that
Chris@16:             should be reserved for the description text; if the option text
Chris@16:             encroaches into this, then the description will start on the next
Chris@16:             line.
Chris@16:         */
Chris@16:         options_description(const std::string& caption,
Chris@16:                             unsigned line_length = m_default_line_length,
Chris@16:                             unsigned min_description_length = m_default_line_length / 2);
Chris@16:         /** Adds new variable description. Throws duplicate_variable_error if
Chris@16:             either short or long name matches that of already present one. 
Chris@16:         */
Chris@16:         void add(shared_ptr<option_description> desc);
Chris@16:         /** Adds a group of option description. This has the same
Chris@16:             effect as adding all option_descriptions in 'desc' 
Chris@16:             individually, except that output operator will show
Chris@16:             a separate group.
Chris@16:             Returns *this.
Chris@16:         */
Chris@16:         options_description& add(const options_description& desc);
Chris@16: 
Chris@101:         /** Find the maximum width of the option column, including options 
Chris@101:             in groups. */
Chris@101:         unsigned get_option_column_width() const;
Chris@101: 
Chris@16:     public:
Chris@16:         /** Returns an object of implementation-defined type suitable for adding
Chris@16:             options to options_description. The returned object will
Chris@16:             have overloaded operator() with parameter type matching 
Chris@16:             'option_description' constructors. Calling the operator will create
Chris@16:             new option_description instance and add it.
Chris@16:         */
Chris@16:         options_description_easy_init add_options();
Chris@16: 
Chris@16:         const option_description& find(const std::string& name, 
Chris@16:                                        bool approx, 
Chris@16:                                        bool long_ignore_case = false,
Chris@16:                                        bool short_ignore_case = false) const;
Chris@16: 
Chris@16:         const option_description* find_nothrow(const std::string& name, 
Chris@16:                                                bool approx,
Chris@16:                                                bool long_ignore_case = false,
Chris@16:                                                bool short_ignore_case = false) const;
Chris@16: 
Chris@16: 
Chris@16:         const std::vector< shared_ptr<option_description> >& options() const;
Chris@16: 
Chris@16:         /** Produces a human readable output of 'desc', listing options,
Chris@16:             their descriptions and allowed parameters. Other options_description
Chris@16:             instances previously passed to add will be output separately. */
Chris@16:         friend BOOST_PROGRAM_OPTIONS_DECL std::ostream& operator<<(std::ostream& os, 
Chris@16:                                              const options_description& desc);
Chris@16: 
Chris@16:         /** Outputs 'desc' to the specified stream, calling 'f' to output each
Chris@16:             option_description element. */
Chris@101:         void print(std::ostream& os, unsigned width = 0) const;
Chris@16: 
Chris@16:     private:
Chris@16:         typedef std::map<std::string, int>::const_iterator name2index_iterator;
Chris@16:         typedef std::pair<name2index_iterator, name2index_iterator> 
Chris@16:             approximation_range;
Chris@16: 
Chris@16:         //approximation_range find_approximation(const std::string& prefix) const;
Chris@16: 
Chris@16:         std::string m_caption;
Chris@16:         const unsigned m_line_length;
Chris@16:         const unsigned m_min_description_length;
Chris@16:         
Chris@16:         // Data organization is chosen because:
Chris@16:         // - there could be two names for one option
Chris@16:         // - option_add_proxy needs to know the last added option
Chris@16:         std::vector< shared_ptr<option_description> > m_options;
Chris@16: 
Chris@16:         // Whether the option comes from one of declared groups.
Chris@16: #if BOOST_WORKAROUND(BOOST_DINKUMWARE_STDLIB, BOOST_TESTED_AT(313))
Chris@16:         // vector<bool> is buggy there, see
Chris@16:         // http://support.microsoft.com/default.aspx?scid=kb;en-us;837698
Chris@16:         std::vector<char> belong_to_group;
Chris@16: #else
Chris@16:         std::vector<bool> belong_to_group;
Chris@16: #endif
Chris@16: 
Chris@16:         std::vector< shared_ptr<options_description> > groups;
Chris@16: 
Chris@16:     };
Chris@16: 
Chris@16:     /** Class thrown when duplicate option description is found. */
Chris@16:     class BOOST_PROGRAM_OPTIONS_DECL duplicate_option_error : public error {
Chris@16:     public:
Chris@16:         duplicate_option_error(const std::string& xwhat) : error(xwhat) {}
Chris@16:     };
Chris@16: }}
Chris@16: 
Chris@16: #if defined(BOOST_MSVC)
Chris@16: #   pragma warning (pop)
Chris@16: #endif
Chris@16: 
Chris@16: #endif