ceph/src/boost/boost/program_options/parsers.hpp

   1 // Copyright Vladimir Prus 2002-2004.
   2 // Distributed under the Boost Software License, Version 1.0.
   3 // (See accompanying file LICENSE_1_0.txt
   4 // or copy at http://www.boost.org/LICENSE_1_0.txt)
   5
   6
   7 #ifndef BOOST_PARSERS_VP_2003_05_19
   8 #define BOOST_PARSERS_VP_2003_05_19
   9
  10 #include <boost/program_options/config.hpp>
  11 #include <boost/program_options/option.hpp>
  12 #include <boost/program_options/detail/cmdline.hpp>
  13
  14 #include <boost/function/function1.hpp>
  15
  16 #include <iosfwd>
  17 #include <vector>
  18 #include <utility>
  19
  20 #if defined(BOOST_MSVC)
  21 #   pragma warning (push)
  22 #   pragma warning (disable:4251) // class 'std::vector<_Ty>' needs to have dll-interface to be used by clients of class 'boost::program_options::basic_parsed_options<wchar_t>'
  23 #endif
  24
  25 namespace boost { namespace program_options {
  26
  27     class options_description;
  28     class positional_options_description;
  29
  30
  31     /** Results of parsing an input source.
  32         The primary use of this class is passing information from parsers
  33         component to value storage component. This class does not makes
  34         much sense itself.
  35     */
  36     template<class charT>
  37     class basic_parsed_options {
  38     public:
  39         explicit basic_parsed_options(const options_description* xdescription, int options_prefix = 0)
  40         : description(xdescription), m_options_prefix(options_prefix) {}
  41         /** Options found in the source. */
  42         std::vector< basic_option<charT> > options;
  43         /** Options description that was used for parsing.
  44             Parsers should return pointer to the instance of
  45             option_description passed to them, and issues of lifetime are
  46             up to the caller. Can be NULL.
  47          */
  48         const options_description* description;
  49
  50         /** Mainly used for the diagnostic messages in exceptions.
  51          *  The canonical option prefix  for the parser which generated these results,
  52          *  depending on the settings for basic_command_line_parser::style() or
  53          *  cmdline::style(). In order of precedence of command_line_style enums:
  54          *      allow_long
  55          *      allow_long_disguise
  56          *      allow_dash_for_short
  57          *      allow_slash_for_short
  58         */
  59         int m_options_prefix;
  60     };
  61
  62     /** Specialization of basic_parsed_options which:
  63         - provides convenient conversion from basic_parsed_options<char>
  64         - stores the passed char-based options for later use.
  65     */
  66     template<>
  67     class BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<wchar_t> {
  68     public:
  69         /** Constructs wrapped options from options in UTF8 encoding. */
  70         explicit basic_parsed_options(const basic_parsed_options<char>& po);
  71
  72         std::vector< basic_option<wchar_t> > options;
  73         const options_description* description;
  74
  75         /** Stores UTF8 encoded options that were passed to constructor,
  76             to avoid reverse conversion in some cases. */
  77         basic_parsed_options<char> utf8_encoded_options;
  78
  79         /** Mainly used for the diagnostic messages in exceptions.
  80          *  The canonical option prefix  for the parser which generated these results,
  81          *  depending on the settings for basic_command_line_parser::style() or
  82          *  cmdline::style(). In order of precedence of command_line_style enums:
  83          *      allow_long
  84          *      allow_long_disguise
  85          *      allow_dash_for_short
  86          *      allow_slash_for_short
  87         */
  88         int m_options_prefix;
  89     };
  90
  91     typedef basic_parsed_options<char> parsed_options;
  92     typedef basic_parsed_options<wchar_t> wparsed_options;
  93
  94     /** Augments basic_parsed_options<wchar_t> with conversion from
  95         'parsed_options' */
  96
  97
  98     typedef function1<std::pair<std::string, std::string>, const std::string&> ext_parser;
  99
 100     /** Command line parser.
 101
 102         The class allows one to specify all the information needed for parsing
 103         and to parse the command line. It is primarily needed to
 104         emulate named function parameters \-- a regular function with 5
 105         parameters will be hard to use and creating overloads with a smaller
 106         number of parameters will be confusing.
 107
 108         For the most common case, the function parse_command_line is a better
 109         alternative.
 110
 111         There are two typedefs \-- command_line_parser and wcommand_line_parser,
 112         for charT == char and charT == wchar_t cases.
 113     */
 114     template<class charT>
 115     class basic_command_line_parser : private detail::cmdline {
 116     public:
 117         /** Creates a command line parser for the specified arguments
 118             list. The 'args' parameter should not include program name.
 119         */
 120         basic_command_line_parser(const std::vector<
 121                                   std::basic_string<charT> >& args);
 122         /** Creates a command line parser for the specified arguments
 123             list. The parameters should be the same as passed to 'main'.
 124         */
 125         basic_command_line_parser(int argc, const charT* const argv[]);
 126
 127         /** Sets options descriptions to use. */
 128         basic_command_line_parser& options(const options_description& desc);
 129         /** Sets positional options description to use. */
 130         basic_command_line_parser& positional(
 131             const positional_options_description& desc);
 132
 133         /** Sets the command line style. */
 134         basic_command_line_parser& style(int);
 135         /** Sets the extra parsers. */
 136         basic_command_line_parser& extra_parser(ext_parser);
 137
 138         /** Parses the options and returns the result of parsing.
 139             Throws on error.
 140         */
 141         basic_parsed_options<charT> run();
 142
 143         /** Specifies that unregistered options are allowed and should
 144             be passed though. For each command like token that looks
 145             like an option but does not contain a recognized name, an
 146             instance of basic_option<charT> will be added to result,
 147             with 'unrecognized' field set to 'true'. It's possible to
 148             collect all unrecognized options with the 'collect_unrecognized'
 149             funciton.
 150         */
 151         basic_command_line_parser& allow_unregistered();
 152
 153         using detail::cmdline::style_parser;
 154
 155         basic_command_line_parser& extra_style_parser(style_parser s);
 156
 157     private:
 158         const options_description* m_desc;
 159     };
 160
 161     typedef basic_command_line_parser<char> command_line_parser;
 162     typedef basic_command_line_parser<wchar_t> wcommand_line_parser;
 163
 164     /** Creates instance of 'command_line_parser', passes parameters to it,
 165         and returns the result of calling the 'run' method.
 166      */
 167     template<class charT>
 168     basic_parsed_options<charT>
 169     parse_command_line(int argc, const charT* const argv[],
 170                        const options_description&,
 171                        int style = 0,
 172                        function1<std::pair<std::string, std::string>,
 173                                  const std::string&> ext
 174                        = ext_parser());
 175
 176     /** Parse a config file.
 177
 178         Read from given stream.
 179     */
 180     template<class charT>
 181 #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
 182     BOOST_PROGRAM_OPTIONS_DECL
 183 #endif
 184     basic_parsed_options<charT>
 185     parse_config_file(std::basic_istream<charT>&, const options_description&,
 186                       bool allow_unregistered = false);
 187
 188     /** Parse a config file.
 189
 190         Read from file with the given name. The character type is
 191         passed to the file stream.
 192     */
 193 #ifdef BOOST_NO_CXX11_FUNCTION_TEMPLATE_DEFAULT_ARGS
 194     template<class charT>
 195 #else
 196     template<class charT = char>
 197 #endif
 198 #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
 199     BOOST_PROGRAM_OPTIONS_DECL
 200 #endif
 201     basic_parsed_options<charT>
 202     parse_config_file(const char* filename, const options_description&,
 203                       bool allow_unregistered = false);
 204
 205     /** Controls if the 'collect_unregistered' function should
 206         include positional options, or not. */
 207     enum collect_unrecognized_mode
 208     { include_positional, exclude_positional };
 209
 210     /** Collects the original tokens for all named options with
 211         'unregistered' flag set. If 'mode' is 'include_positional'
 212         also collects all positional options.
 213         Returns the vector of origianl tokens for all collected
 214         options.
 215     */
 216     template<class charT>
 217     std::vector< std::basic_string<charT> >
 218     collect_unrecognized(const std::vector< basic_option<charT> >& options,
 219                          enum collect_unrecognized_mode mode);
 220
 221     /** Parse environment.
 222
 223         For each environment variable, the 'name_mapper' function is called to
 224         obtain the option name. If it returns empty string, the variable is
 225         ignored.
 226
 227         This is done since naming of environment variables is typically
 228         different from the naming of command line options.
 229     */
 230     BOOST_PROGRAM_OPTIONS_DECL parsed_options
 231     parse_environment(const options_description&,
 232                       const function1<std::string, std::string>& name_mapper);
 233
 234     /** Parse environment.
 235
 236         Takes all environment variables which start with 'prefix'. The option
 237         name is obtained from variable name by removing the prefix and
 238         converting the remaining string into lower case.
 239     */
 240     BOOST_PROGRAM_OPTIONS_DECL parsed_options
 241     parse_environment(const options_description&, const std::string& prefix);
 242
 243     /** @overload
 244         This function exists to resolve ambiguity between the two above
 245         functions when second argument is of 'char*' type. There's implicit
 246         conversion to both function1 and string.
 247     */
 248     BOOST_PROGRAM_OPTIONS_DECL parsed_options
 249     parse_environment(const options_description&, const char* prefix);
 250
 251     /** Splits a given string to a collection of single strings which
 252         can be passed to command_line_parser. The second parameter is
 253         used to specify a collection of possible seperator chars used
 254         for splitting. The seperator is defaulted to space " ".
 255         Splitting is done in a unix style way, with respect to quotes '"'
 256         and escape characters '\'
 257     */
 258     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
 259     split_unix(const std::string& cmdline, const std::string& seperator = " \t",
 260          const std::string& quote = "'\"", const std::string& escape = "\\");
 261
 262 #ifndef BOOST_NO_STD_WSTRING
 263     /** @overload */
 264     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
 265     split_unix(const std::wstring& cmdline, const std::wstring& seperator = L" \t",
 266          const std::wstring& quote = L"'\"", const std::wstring& escape = L"\\");
 267 #endif
 268
 269     #ifdef _WIN32
 270     /** Parses the char* string which is passed to WinMain function on
 271         windows. This function is provided for convenience, and because it's
 272         not clear how to portably access split command line string from
 273         runtime library and if it always exists.
 274         This function is available only on Windows.
 275     */
 276     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
 277     split_winmain(const std::string& cmdline);
 278
 279 #ifndef BOOST_NO_STD_WSTRING
 280     /** @overload */
 281     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
 282     split_winmain(const std::wstring& cmdline);
 283     #endif
 284 #endif
 285
 286
 287 }}
 288
 289 #if defined(BOOST_MSVC)
 290 #   pragma warning (pop)
 291 #endif
 292
 293 #undef DECL
 294
 295 #include "boost/program_options/detail/parsers.hpp"
 296
 297 #endif