[ceph.git] / ceph / src / boost / boost / program_options / options_description.hpp

// Copyright Vladimir Prus 2002-2004.
// Copyright Bertolt Mildner 2004.
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE_1_0.txt
// or copy at http://www.boost.org/LICENSE_1_0.txt)


#ifndef BOOST_OPTION_DESCRIPTION_VP_2003_05_19
#define BOOST_OPTION_DESCRIPTION_VP_2003_05_19

#include <boost/program_options/config.hpp>
#include <boost/program_options/errors.hpp>
#include <boost/program_options/value_semantic.hpp>

#include <boost/function.hpp>
#include <boost/shared_ptr.hpp>
#include <boost/detail/workaround.hpp>
#include <boost/any.hpp>

#include <string>
#include <vector>
#include <set>
#include <map>
#include <stdexcept>
#include <utility>

#include <iosfwd>

#if defined(BOOST_MSVC)
#   pragma warning (push)
#   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'
#endif


/** Boost namespace */
namespace boost { 
/** Namespace for the library. */
namespace program_options {

    /** Describes one possible command line/config file option. There are two
        kinds of properties of an option. First describe it syntactically and
        are used only to validate input. Second affect interpretation of the
        option, for example default value for it or function that should be
        called  when the value is finally known. Routines which perform parsing
        never use second kind of properties \-- they are side effect free.
        @sa options_description
    */
    class BOOST_PROGRAM_OPTIONS_DECL option_description {
    public:

        option_description();

        /** Initializes the object with the passed data.

            Note: it would be nice to make the second parameter auto_ptr,
            to explicitly pass ownership. Unfortunately, it's often needed to
            create objects of types derived from 'value_semantic':
               options_description d;
               d.add_options()("a", parameter<int>("n")->default_value(1));
            Here, the static type returned by 'parameter' should be derived
            from value_semantic.

            Alas, derived->base conversion for auto_ptr does not really work,
            see
            http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf
            http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#84

            So, we have to use plain old pointers. Besides, users are not
            expected to use the constructor directly.

            
            The 'name' parameter is interpreted by the following rules:
            - if there's no "," character in 'name', it specifies long name
            - otherwise, the part before "," specifies long name and the part
            after \-- short name.
        */
        option_description(const char* name,
                           const value_semantic* s);

        /** Initializes the class with the passed data. 
         */
        option_description(const char* name,
                           const value_semantic* s,
                           const char* description);

        virtual ~option_description();

        enum match_result { no_match, full_match, approximate_match };

        /** Given 'option', specified in the input source,
            returns 'true' if 'option' specifies *this.
        */
        match_result match(const std::string& option, bool approx,
                           bool long_ignore_case, bool short_ignore_case) const;

        /** Returns the key that should identify the option, in
            particular in the variables_map class.
            The 'option' parameter is the option spelling from the
            input source.
            If option name contains '*', returns 'option'.
            If long name was specified, it's the long name, otherwise
            it's a short name with prepended '-'.
        */
        const std::string& key(const std::string& option) const;


        /** Returns the canonical name for the option description to enable the user to
            recognised a matching option.
            1) For short options ('-', '/'), returns the short name prefixed.
            2) For long options ('--' / '-') returns the first long name prefixed
            3) All other cases, returns the first long name (if present) or the short
               name, unprefixed.
        */
        std::string canonical_display_name(int canonical_option_style = 0) const;

        const std::string& long_name() const;

        const std::pair<const std::string*, std::size_t> long_names() const;

        /// Explanation of this option
        const std::string& description() const;

        /// Semantic of option's value
        shared_ptr<const value_semantic> semantic() const;
        
        /// Returns the option name, formatted suitably for usage message. 
        std::string format_name() const;

        /** Returns the parameter name and properties, formatted suitably for
            usage message. */
        std::string format_parameter() const;

    private:
    
        option_description& set_names(const char* name);

        /**
         * a one-character "switch" name - with its prefix,
         * so that this is either empty or has length 2 (e.g. "-c"
         */
        std::string m_short_name;

        /**
         *  one or more names by which this option may be specified
         *  on a command-line or in a config file, which are not
         *  a single-letter switch. The names here are _without_
         * any prefix.
         */
        std::vector<std::string> m_long_names;

        std::string m_description;

        // shared_ptr is needed to simplify memory management in
        // copy ctor and destructor.
        shared_ptr<const value_semantic> m_value_semantic;
    };

    class options_description;

    /** Class which provides convenient creation syntax to option_description. 
     */        
    class BOOST_PROGRAM_OPTIONS_DECL options_description_easy_init {
    public:
        options_description_easy_init(options_description* owner);

        options_description_easy_init&
        operator()(const char* name,
                   const char* description);

        options_description_easy_init&
        operator()(const char* name,
                   const value_semantic* s);
        
        options_description_easy_init&
        operator()(const char* name,
                   const value_semantic* s,
                   const char* description);
       
    private:
        options_description* owner;
    };


    /** A set of option descriptions. This provides convenient interface for
        adding new option (the add_options) method, and facilities to search
        for options by name.
        
        See @ref a_adding_options "here" for option adding interface discussion.
        @sa option_description
    */
    class BOOST_PROGRAM_OPTIONS_DECL options_description {
    public:
        static const unsigned m_default_line_length;
        
        /** Creates the instance. */
        options_description(unsigned line_length = m_default_line_length,
                            unsigned min_description_length = m_default_line_length / 2);
        /** Creates the instance. The 'caption' parameter gives the name of
            this 'options_description' instance. Primarily useful for output.
            The 'description_length' specifies the number of columns that
            should be reserved for the description text; if the option text
            encroaches into this, then the description will start on the next
            line.
        */
        options_description(const std::string& caption,
                            unsigned line_length = m_default_line_length,
                            unsigned min_description_length = m_default_line_length / 2);
        /** Adds new variable description. Throws duplicate_variable_error if
            either short or long name matches that of already present one. 
        */
        void add(shared_ptr<option_description> desc);
        /** Adds a group of option description. This has the same
            effect as adding all option_descriptions in 'desc' 
            individually, except that output operator will show
            a separate group.
            Returns *this.
        */
        options_description& add(const options_description& desc);

        /** Find the maximum width of the option column, including options 
            in groups. */
        unsigned get_option_column_width() const;

    public:
        /** Returns an object of implementation-defined type suitable for adding
            options to options_description. The returned object will
            have overloaded operator() with parameter type matching 
            'option_description' constructors. Calling the operator will create
            new option_description instance and add it.
        */
        options_description_easy_init add_options();

        const option_description& find(const std::string& name, 
                                       bool approx, 
                                       bool long_ignore_case = false,
                                       bool short_ignore_case = false) const;

        const option_description* find_nothrow(const std::string& name, 
                                               bool approx,
                                               bool long_ignore_case = false,
                                               bool short_ignore_case = false) const;


        const std::vector< shared_ptr<option_description> >& options() const;

        /** Produces a human readable output of 'desc', listing options,
            their descriptions and allowed parameters. Other options_description
            instances previously passed to add will be output separately. */
        friend BOOST_PROGRAM_OPTIONS_DECL std::ostream& operator<<(std::ostream& os, 
                                             const options_description& desc);

        /** Outputs 'desc' to the specified stream, calling 'f' to output each
            option_description element. */
        void print(std::ostream& os, unsigned width = 0) const;

    private:
#if BOOST_WORKAROUND(BOOST_MSVC, BOOST_TESTED_AT(1800))
        // prevent warning C4512: assignment operator could not be generated
        options_description& operator=(const options_description&);
#endif

        typedef std::map<std::string, int>::const_iterator name2index_iterator;
        typedef std::pair<name2index_iterator, name2index_iterator> 
            approximation_range;

        //approximation_range find_approximation(const std::string& prefix) const;

        std::string m_caption;
        const unsigned m_line_length;
        const unsigned m_min_description_length;
        
        // Data organization is chosen because:
        // - there could be two names for one option
        // - option_add_proxy needs to know the last added option
        std::vector< shared_ptr<option_description> > m_options;

        // Whether the option comes from one of declared groups.
#if BOOST_WORKAROUND(BOOST_DINKUMWARE_STDLIB, BOOST_TESTED_AT(313))
        // vector<bool> is buggy there, see
        // http://support.microsoft.com/default.aspx?scid=kb;en-us;837698
        std::vector<char> belong_to_group;
#else
        std::vector<bool> belong_to_group;
#endif

        std::vector< shared_ptr<options_description> > groups;

    };

    /** Class thrown when duplicate option description is found. */
    class BOOST_PROGRAM_OPTIONS_DECL duplicate_option_error : public error {
    public:
        duplicate_option_error(const std::string& xwhat) : error(xwhat) {}
    };
}}

#if defined(BOOST_MSVC)
#   pragma warning (pop)
#endif

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