stc/exp/ml_stc_linux_make_v1.0/include/boost/program_options/options_description.hpp

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