boost/program_options/options_description.hpp

0001 // Copyright Vladimir Prus 2002-2004.
0002 // Copyright Bertolt Mildner 2004.
0003 // Distributed under the Boost Software License, Version 1.0.
0004 // (See accompanying file LICENSE_1_0.txt
0005 // or copy at http://www.boost.org/LICENSE_1_0.txt)
0006
0007
0008 #ifndef BOOST_OPTION_DESCRIPTION_VP_2003_05_19
0009 #define BOOST_OPTION_DESCRIPTION_VP_2003_05_19
0010
0011 #include <boost/program_options/config.hpp>
0012 #include <boost/program_options/errors.hpp>
0013 #include <boost/program_options/value_semantic.hpp>
0014
0015 #include <boost/function.hpp>
0016 #include <boost/shared_ptr.hpp>
0017 #include <boost/detail/workaround.hpp>
0018 #include <boost/any.hpp>
0019
0020 #include <string>
0021 #include <vector>
0022 #include <set>
0023 #include <map>
0024 #include <stdexcept>
0025 #include <utility>
0026
0027 #include <iosfwd>
0028
0029 #if defined(BOOST_MSVC)
0030 #   pragma warning (push)
0031 #   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'
0032 #endif
0033
0034
0035 /** Boost namespace */
0036 namespace boost {
0037 /** Namespace for the library. */
0038 namespace program_options {
0039
0040     /** Describes one possible command line/config file option. There are two
0041         kinds of properties of an option. First describe it syntactically and
0042         are used only to validate input. Second affect interpretation of the
0043         option, for example default value for it or function that should be
0044         called  when the value is finally known. Routines which perform parsing
0045         never use second kind of properties \-- they are side effect free.
0046         @sa options_description
0047     */
0048     class BOOST_PROGRAM_OPTIONS_DECL option_description {
0049     public:
0050
0051         option_description();
0052
0053         /** Initializes the object with the passed data.
0054
0055             Note: it would be nice to make the second parameter auto_ptr,
0056             to explicitly pass ownership. Unfortunately, it's often needed to
0057             create objects of types derived from 'value_semantic':
0058                options_description d;
0059                d.add_options()("a", parameter<int>("n")->default_value(1));
0060             Here, the static type returned by 'parameter' should be derived
0061             from value_semantic.
0062
0063             Alas, derived->base conversion for auto_ptr does not really work,
0064             see
0065             http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf
0066             http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#84
0067
0068             So, we have to use plain old pointers. Besides, users are not
0069             expected to use the constructor directly.
0070
0071
0072             The 'name' parameter is interpreted by the following rules:
0073             - if there's no "," character in 'name', it specifies long name
0074             - otherwise, the part before "," specifies long name and the part
0075             after \-- short name.
0076         */
0077         option_description(const char* name,
0078                            const value_semantic* s);
0079
0080         /** Initializes the class with the passed data.
0081          */
0082         option_description(const char* name,
0083                            const value_semantic* s,
0084                            const char* description);
0085
0086         virtual ~option_description();
0087
0088         enum match_result { no_match, full_match, approximate_match };
0089
0090         /** Given 'option', specified in the input source,
0091             returns 'true' if 'option' specifies *this.
0092         */
0093         match_result match(const std::string& option, bool approx,
0094                            bool long_ignore_case, bool short_ignore_case) const;
0095
0096         /** Returns the key that should identify the option, in
0097             particular in the variables_map class.
0098             The 'option' parameter is the option spelling from the
0099             input source.
0100             If option name contains '*', returns 'option'.
0101             If long name was specified, it's the long name, otherwise
0102             it's a short name with prepended '-'.
0103         */
0104         const std::string& key(const std::string& option) const;
0105
0106
0107         /** Returns the canonical name for the option description to enable the user to
0108             recognised a matching option.
0109             1) For short options ('-', '/'), returns the short name prefixed.
0110             2) For long options ('--' / '-') returns the first long name prefixed
0111             3) All other cases, returns the first long name (if present) or the short
0112                name, unprefixed.
0113         */
0114         std::string canonical_display_name(int canonical_option_style = 0) const;
0115
0116         const std::string& long_name() const;
0117
0118         const std::pair<const std::string*, std::size_t> long_names() const;
0119
0120         /// Explanation of this option
0121         const std::string& description() const;
0122
0123         /// Semantic of option's value
0124         shared_ptr<const value_semantic> semantic() const;
0125
0126         /// Returns the option name, formatted suitably for usage message.
0127         std::string format_name() const;
0128
0129         /** Returns the parameter name and properties, formatted suitably for
0130             usage message. */
0131         std::string format_parameter() const;
0132
0133     private:
0134
0135         option_description& set_names(const char* name);
0136
0137         /**
0138          * a one-character "switch" name - with its prefix,
0139          * so that this is either empty or has length 2 (e.g. "-c"
0140          */
0141         std::string m_short_name;
0142
0143         /**
0144          *  one or more names by which this option may be specified
0145          *  on a command-line or in a config file, which are not
0146          *  a single-letter switch. The names here are _without_
0147          * any prefix.
0148          */
0149         std::vector<std::string> m_long_names;
0150
0151         std::string m_description;
0152
0153         // shared_ptr is needed to simplify memory management in
0154         // copy ctor and destructor.
0155         shared_ptr<const value_semantic> m_value_semantic;
0156     };
0157
0158     class options_description;
0159
0160     /** Class which provides convenient creation syntax to option_description.
0161      */
0162     class BOOST_PROGRAM_OPTIONS_DECL options_description_easy_init {
0163     public:
0164         options_description_easy_init(options_description* owner);
0165
0166         options_description_easy_init&
0167         operator()(const char* name,
0168                    const char* description);
0169
0170         options_description_easy_init&
0171         operator()(const char* name,
0172                    const value_semantic* s);
0173
0174         options_description_easy_init&
0175         operator()(const char* name,
0176                    const value_semantic* s,
0177                    const char* description);
0178
0179     private:
0180         options_description* owner;
0181     };
0182
0183
0184     /** A set of option descriptions. This provides convenient interface for
0185         adding new option (the add_options) method, and facilities to search
0186         for options by name.
0187
0188         See @ref a_adding_options "here" for option adding interface discussion.
0189         @sa option_description
0190     */
0191     class BOOST_PROGRAM_OPTIONS_DECL options_description {
0192     public:
0193         static const unsigned m_default_line_length;
0194
0195         /** Creates the instance. */
0196         options_description(unsigned line_length = m_default_line_length,
0197                             unsigned min_description_length = m_default_line_length / 2);
0198         /** Creates the instance. The 'caption' parameter gives the name of
0199             this 'options_description' instance. Primarily useful for output.
0200             The 'description_length' specifies the number of columns that
0201             should be reserved for the description text; if the option text
0202             encroaches into this, then the description will start on the next
0203             line.
0204         */
0205         options_description(const std::string& caption,
0206                             unsigned line_length = m_default_line_length,
0207                             unsigned min_description_length = m_default_line_length / 2);
0208         /** Adds new variable description. Throws duplicate_variable_error if
0209             either short or long name matches that of already present one.
0210         */
0211         void add(shared_ptr<option_description> desc);
0212         /** Adds a group of option description. This has the same
0213             effect as adding all option_descriptions in 'desc'
0214             individually, except that output operator will show
0215             a separate group.
0216             Returns *this.
0217         */
0218         options_description& add(const options_description& desc);
0219
0220         /** Find the maximum width of the option column, including options
0221             in groups. */
0222         unsigned get_option_column_width() const;
0223
0224     public:
0225         /** Returns an object of implementation-defined type suitable for adding
0226             options to options_description. The returned object will
0227             have overloaded operator() with parameter type matching
0228             'option_description' constructors. Calling the operator will create
0229             new option_description instance and add it.
0230         */
0231         options_description_easy_init add_options();
0232
0233         const option_description& find(const std::string& name,
0234                                        bool approx,
0235                                        bool long_ignore_case = false,
0236                                        bool short_ignore_case = false) const;
0237
0238         const option_description* find_nothrow(const std::string& name,
0239                                                bool approx,
0240                                                bool long_ignore_case = false,
0241                                                bool short_ignore_case = false) const;
0242
0243
0244         const std::vector< shared_ptr<option_description> >& options() const;
0245
0246         /** Produces a human readable output of 'desc', listing options,
0247             their descriptions and allowed parameters. Other options_description
0248             instances previously passed to add will be output separately. */
0249         friend BOOST_PROGRAM_OPTIONS_DECL std::ostream& operator<<(std::ostream& os,
0250                                              const options_description& desc);
0251
0252         /** Outputs 'desc' to the specified stream, calling 'f' to output each
0253             option_description element. */
0254         void print(std::ostream& os, unsigned width = 0) const;
0255
0256     private:
0257 #if BOOST_WORKAROUND(BOOST_MSVC, BOOST_TESTED_AT(1800))
0258         // prevent warning C4512: assignment operator could not be generated
0259         options_description& operator=(const options_description&);
0260 #endif
0261
0262         typedef std::map<std::string, int>::const_iterator name2index_iterator;
0263         typedef std::pair<name2index_iterator, name2index_iterator>
0264             approximation_range;
0265
0266         //approximation_range find_approximation(const std::string& prefix) const;
0267
0268         std::string m_caption;
0269         const unsigned m_line_length;
0270         const unsigned m_min_description_length;
0271
0272         // Data organization is chosen because:
0273         // - there could be two names for one option
0274         // - option_add_proxy needs to know the last added option
0275         std::vector< shared_ptr<option_description> > m_options;
0276
0277         // Whether the option comes from one of declared groups.
0278 #if BOOST_WORKAROUND(BOOST_DINKUMWARE_STDLIB, BOOST_TESTED_AT(313))
0279         // vector<bool> is buggy there, see
0280         // http://support.microsoft.com/default.aspx?scid=kb;en-us;837698
0281         std::vector<char> belong_to_group;
0282 #else
0283         std::vector<bool> belong_to_group;
0284 #endif
0285
0286         std::vector< shared_ptr<options_description> > groups;
0287
0288     };
0289
0290     /** Class thrown when duplicate option description is found. */
0291     class BOOST_PROGRAM_OPTIONS_DECL duplicate_option_error : public error {
0292     public:
0293         duplicate_option_error(const std::string& xwhat) : error(xwhat) {}
0294     };
0295 }}
0296
0297 #if defined(BOOST_MSVC)
0298 #   pragma warning (pop)
0299 #endif
0300
0301 #endif