/Src/Dependencies/Boost/boost/program_options/options_description.hpp

  1// Copyright Vladimir Prus 2002-2004.
  2// Copyright Bertolt Mildner 2004.
  3// Distributed under the Boost Software License, Version 1.0.
  4// (See accompanying file LICENSE_1_0.txt
  5// or copy at http://www.boost.org/LICENSE_1_0.txt)
  6
  7
  8#ifndef BOOST_OPTION_DESCRIPTION_VP_2003_05_19
  9#define BOOST_OPTION_DESCRIPTION_VP_2003_05_19
 10
 11#include <boost/program_options/config.hpp>
 12#include <boost/program_options/errors.hpp>
 13#include <boost/program_options/value_semantic.hpp>
 14
 15#include <boost/function.hpp>
 16#include <boost/shared_ptr.hpp>
 17#include <boost/detail/workaround.hpp>
 18#include <boost/any.hpp>
 19
 20#include <string>
 21#include <vector>
 22#include <set>
 23#include <map>
 24#include <stdexcept>
 25
 26#include <iosfwd>
 27
 28#if defined(BOOST_MSVC)
 29#   pragma warning (push)
 30#   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'
 31#endif
 32
 33
 34/** Boost namespace */
 35namespace boost { 
 36/** Namespace for the library. */
 37namespace program_options {
 38
 39    /** Describes one possible command line/config file option. There are two
 40        kinds of properties of an option. First describe it syntactically and
 41        are used only to validate input. Second affect interpretation of the
 42        option, for example default value for it or function that should be
 43        called  when the value is finally known. Routines which perform parsing
 44        never use second kind of properties -- they are side effect free.
 45        @sa options_description
 46    */
 47    class BOOST_PROGRAM_OPTIONS_DECL option_description {
 48    public:
 49
 50        option_description();
 51
 52        /** Initializes the object with the passed data.
 53
 54            Note: it would be nice to make the second parameter auto_ptr,
 55            to explicitly pass ownership. Unfortunately, it's often needed to
 56            create objects of types derived from 'value_semantic':
 57               options_description d;
 58               d.add_options()("a", parameter<int>("n")->default_value(1));
 59            Here, the static type returned by 'parameter' should be derived
 60            from value_semantic.
 61
 62            Alas, derived->base conversion for auto_ptr does not really work,
 63            see
 64            http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf
 65            http://std.dkuug.dk/jtc1/sc22/wg21/docs/cwg_defects.html#84
 66
 67            So, we have to use plain old pointers. Besides, users are not
 68            expected to use the constructor directly.
 69
 70            
 71            The 'name' parameter is interpreted by the following rules:
 72            - if there's no "," character in 'name', it specifies long name
 73            - otherwise, the part before "," specifies long name and the part
 74            after -- short name.
 75        */
 76        option_description(const char* name,
 77                           const value_semantic* s);
 78
 79        /** Initializes the class with the passed data. 
 80         */
 81        option_description(const char* name,
 82                           const value_semantic* s,
 83                           const char* description);
 84
 85        virtual ~option_description();
 86
 87        enum match_result { no_match, full_match, approximate_match };
 88
 89        /** Given 'option', specified in the input source,
 90            returns 'true' if 'option' specifies *this.
 91        */
 92        match_result match(const std::string& option, bool approx,
 93                           bool long_ignore_case, bool short_ignore_case) const;
 94
 95        /** Returns the key that should identify the option, in
 96            particular in the variables_map class.
 97            The 'option' parameter is the option spelling from the
 98            input source.
 99            If option name contains '*', returns 'option'.
100            If long name was specified, it's the long name, otherwise
101            it's a short name with prepended '-'.
102        */
103        const std::string& key(const std::string& option) const;
104
105        const std::string& long_name() const;
106
107        /// Explanation of this option
108        const std::string& description() const;
109
110        /// Semantic of option's value
111        shared_ptr<const value_semantic> semantic() const;
112        
113        /// Returns the option name, formatted suitably for usage message. 
114        std::string format_name() const;
115
116        /** Returns the parameter name and properties, formatted suitably for
117            usage message. */
118        std::string format_parameter() const;
119
120    private:
121    
122        option_description& set_name(const char* name);
123
124        std::string m_short_name, m_long_name, m_description;
125        // shared_ptr is needed to simplify memory management in
126        // copy ctor and destructor.
127        shared_ptr<const value_semantic> m_value_semantic;
128    };
129
130    class options_description;
131
132    /** Class which provides convenient creation syntax to option_description. 
133     */        
134    class BOOST_PROGRAM_OPTIONS_DECL options_description_easy_init {
135    public:
136        options_description_easy_init(options_description* owner);
137
138        options_description_easy_init&
139        operator()(const char* name,
140                   const char* description);
141
142        options_description_easy_init&
143        operator()(const char* name,
144                   const value_semantic* s);
145        
146        options_description_easy_init&
147        operator()(const char* name,
148                   const value_semantic* s,
149                   const char* description);
150       
151    private:
152        options_description* owner;
153    };
154
155
156    /** A set of option descriptions. This provides convenient interface for
157        adding new option (the add_options) method, and facilities to search
158        for options by name.
159        
160        See @ref a_adding_options "here" for option adding interface discussion.
161        @sa option_description
162    */
163    class BOOST_PROGRAM_OPTIONS_DECL options_description {
164    public:
165        static const unsigned m_default_line_length;
166        
167        /** Creates the instance. */
168        options_description(unsigned line_length = m_default_line_length,
169                            unsigned min_description_length = m_default_line_length / 2);
170        /** Creates the instance. The 'caption' parameter gives the name of
171            this 'options_description' instance. Primarily useful for output.
172            The 'description_length' specifies the number of columns that
173            should be reserved for the description text; if the option text
174            encroaches into this, then the description will start on the next
175            line.
176        */
177        options_description(const std::string& caption,
178                            unsigned line_length = m_default_line_length,
179                            unsigned min_description_length = m_default_line_length / 2);
180        /** Adds new variable description. Throws duplicate_variable_error if
181            either short or long name matches that of already present one. 
182        */
183        void add(shared_ptr<option_description> desc);
184        /** Adds a group of option description. This has the same
185            effect as adding all option_descriptions in 'desc' 
186            individually, except that output operator will show
187            a separate group.
188            Returns *this.
189        */
190        options_description& add(const options_description& desc);
191
192    public:
193        /** Returns an object of implementation-defined type suitable for adding
194            options to options_description. The returned object will
195            have overloaded operator() with parameter type matching 
196            'option_description' constructors. Calling the operator will create
197            new option_description instance and add it.
198        */
199        options_description_easy_init add_options();
200
201        const option_description& find(const std::string& name, 
202                                       bool approx, 
203                                       bool long_ignore_case = false,
204                                       bool short_ignore_case = false) const;
205
206        const option_description* find_nothrow(const std::string& name, 
207                                               bool approx,
208                                               bool long_ignore_case = false,
209                                               bool short_ignore_case = false) const;
210
211
212        const std::vector< shared_ptr<option_description> >& options() const;
213
214        /** Produces a human readable output of 'desc', listing options,
215            their descriptions and allowed parameters. Other options_description
216            instances previously passed to add will be output separately. */
217        friend BOOST_PROGRAM_OPTIONS_DECL std::ostream& operator<<(std::ostream& os, 
218                                             const options_description& desc);
219
220        /** Outputs 'desc' to the specified stream, calling 'f' to output each
221            option_description element. */
222        void print(std::ostream& os) const;
223
224    private:
225        typedef std::map<std::string, int>::const_iterator name2index_iterator;
226        typedef std::pair<name2index_iterator, name2index_iterator> 
227            approximation_range;
228
229        //approximation_range find_approximation(const std::string& prefix) const;
230
231        std::string m_caption;
232        const unsigned m_line_length;
233        const unsigned m_min_description_length;
234        
235        // Data organization is chosen because:
236        // - there could be two names for one option
237        // - option_add_proxy needs to know the last added option
238        std::vector< shared_ptr<option_description> > m_options;
239
240        // Whether the option comes from one of declared groups.
241#if BOOST_WORKAROUND(BOOST_DINKUMWARE_STDLIB, BOOST_TESTED_AT(313))
242        // vector<bool> is buggy there, see
243        // http://support.microsoft.com/default.aspx?scid=kb;en-us;837698
244        std::vector<char> belong_to_group;
245#else
246        std::vector<bool> belong_to_group;
247#endif
248
249        std::vector< shared_ptr<options_description> > groups;
250
251    };
252
253    /** Class thrown when duplicate option description is found. */
254    class BOOST_PROGRAM_OPTIONS_DECL duplicate_option_error : public error {
255    public:
256        duplicate_option_error(const std::string& xwhat) : error(xwhat) {}
257    };
258}}
259
260#if defined(BOOST_MSVC)
261#   pragma warning (pop)
262#endif
263
264#endif