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 */ 35 namespace boost { 36 /** Namespace for the library. */ 37 namespace 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://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf 65 http://www.open-std.org/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 106 /** Returns the canonical name for the option description to enable the user to 107 recognised a matching option. 108 1) For short options ('-', '/'), returns the short name prefixed. 109 2) For long options ('--' / '-') returns the long name prefixed 110 3) All other cases, returns the long name (if present) or the short name, 111 unprefixed. 112 */ 113 std::string canonical_display_name(int canonical_option_style = 0) const; 114 115 const std::string& long_name() const; 116 117 /// Explanation of this option 118 const std::string& description() const; 119 120 /// Semantic of option's value 121 shared_ptr<const value_semantic> semantic() const; 122 123 /// Returns the option name, formatted suitably for usage message. 124 std::string format_name() const; 125 126 /** Returns the parameter name and properties, formatted suitably for 127 usage message. */ 128 std::string format_parameter() const; 129 130 private: 131 132 option_description& set_name(const char* name); 133 134 std::string m_short_name, m_long_name, m_description; 135 // shared_ptr is needed to simplify memory management in 136 // copy ctor and destructor. 137 shared_ptr<const value_semantic> m_value_semantic; 138 }; 139 140 class options_description; 141 142 /** Class which provides convenient creation syntax to option_description. 143 */ 144 class BOOST_PROGRAM_OPTIONS_DECL options_description_easy_init { 145 public: 146 options_description_easy_init(options_description* owner); 147 148 options_description_easy_init& 149 operator()(const char* name, 150 const char* description); 151 152 options_description_easy_init& 153 operator()(const char* name, 154 const value_semantic* s); 155 156 options_description_easy_init& 157 operator()(const char* name, 158 const value_semantic* s, 159 const char* description); 160 161 private: 162 options_description* owner; 163 }; 164 165 166 /** A set of option descriptions. This provides convenient interface for 167 adding new option (the add_options) method, and facilities to search 168 for options by name. 169 170 See @ref a_adding_options "here" for option adding interface discussion. 171 @sa option_description 172 */ 173 class BOOST_PROGRAM_OPTIONS_DECL options_description { 174 public: 175 static const unsigned m_default_line_length; 176 177 /** Creates the instance. */ 178 options_description(unsigned line_length = m_default_line_length, 179 unsigned min_description_length = m_default_line_length / 2); 180 /** Creates the instance. The 'caption' parameter gives the name of 181 this 'options_description' instance. Primarily useful for output. 182 The 'description_length' specifies the number of columns that 183 should be reserved for the description text; if the option text 184 encroaches into this, then the description will start on the next 185 line. 186 */ 187 options_description(const std::string& caption, 188 unsigned line_length = m_default_line_length, 189 unsigned min_description_length = m_default_line_length / 2); 190 /** Adds new variable description. Throws duplicate_variable_error if 191 either short or long name matches that of already present one. 192 */ 193 void add(shared_ptr<option_description> desc); 194 /** Adds a group of option description. This has the same 195 effect as adding all option_descriptions in 'desc' 196 individually, except that output operator will show 197 a separate group. 198 Returns *this. 199 */ 200 options_description& add(const options_description& desc); 201 202 /** Find the maximum width of the option column, including options 203 in groups. */ 204 unsigned get_option_column_width() const; 205 206 public: 207 /** Returns an object of implementation-defined type suitable for adding 208 options to options_description. The returned object will 209 have overloaded operator() with parameter type matching 210 'option_description' constructors. Calling the operator will create 211 new option_description instance and add it. 212 */ 213 options_description_easy_init add_options(); 214 215 const option_description& find(const std::string& name, 216 bool approx, 217 bool long_ignore_case = false, 218 bool short_ignore_case = false) const; 219 220 const option_description* find_nothrow(const std::string& name, 221 bool approx, 222 bool long_ignore_case = false, 223 bool short_ignore_case = false) const; 224 225 226 const std::vector< shared_ptr<option_description> >& options() const; 227 228 /** Produces a human readable output of 'desc', listing options, 229 their descriptions and allowed parameters. Other options_description 230 instances previously passed to add will be output separately. */ 231 friend BOOST_PROGRAM_OPTIONS_DECL std::ostream& operator<<(std::ostream& os, 232 const options_description& desc); 233 234 /** Outputs 'desc' to the specified stream, calling 'f' to output each 235 option_description element. */ 236 void print(std::ostream& os, unsigned width = 0) const; 237 238 private: 239 #if BOOST_WORKAROUND(BOOST_MSVC, BOOST_TESTED_AT(1800)) 240 // prevent warning C4512: assignment operator could not be generated 241 options_description& operator=(const options_description&); 242 #endif 243 244 typedef std::map<std::string, int>::const_iterator name2index_iterator; 245 typedef std::pair<name2index_iterator, name2index_iterator> 246 approximation_range; 247 248 //approximation_range find_approximation(const std::string& prefix) const; 249 250 std::string m_caption; 251 const unsigned m_line_length; 252 const unsigned m_min_description_length; 253 254 // Data organization is chosen because: 255 // - there could be two names for one option 256 // - option_add_proxy needs to know the last added option 257 std::vector< shared_ptr<option_description> > m_options; 258 259 // Whether the option comes from one of declared groups. 260 #if BOOST_WORKAROUND(BOOST_DINKUMWARE_STDLIB, BOOST_TESTED_AT(313)) 261 // vector<bool> is buggy there, see 262 // http://support.microsoft.com/default.aspx?scid=kb;en-us;837698 263 std::vector<char> belong_to_group; 264 #else 265 std::vector<bool> belong_to_group; 266 #endif 267 268 std::vector< shared_ptr<options_description> > groups; 269 270 }; 271 272 /** Class thrown when duplicate option description is found. */ 273 class BOOST_PROGRAM_OPTIONS_DECL duplicate_option_error : public error { 274 public: 275 duplicate_option_error(const std::string& xwhat) : error(xwhat) {} 276 }; 277 }} 278 279 #if defined(BOOST_MSVC) 280 # pragma warning (pop) 281 #endif 282 283 #endif 284