boost/program_options/parsers.hpp

0001 // Copyright Vladimir Prus 2002-2004.
0002 // Distributed under the Boost Software License, Version 1.0.
0003 // (See accompanying file LICENSE_1_0.txt
0004 // or copy at http://www.boost.org/LICENSE_1_0.txt)
0005
0006
0007 #ifndef BOOST_PARSERS_VP_2003_05_19
0008 #define BOOST_PARSERS_VP_2003_05_19
0009
0010 #include <boost/program_options/config.hpp>
0011 #include <boost/program_options/option.hpp>
0012 #include <boost/program_options/detail/cmdline.hpp>
0013
0014 #include <boost/function/function1.hpp>
0015
0016 #include <iosfwd>
0017 #include <vector>
0018 #include <utility>
0019
0020 #if defined(BOOST_MSVC)
0021 #   pragma warning (push)
0022 #   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>'
0023 #endif
0024
0025 namespace boost { namespace program_options {
0026
0027     class options_description;
0028     class positional_options_description;
0029
0030
0031     /** Results of parsing an input source.
0032         The primary use of this class is passing information from parsers
0033         component to value storage component. This class does not makes
0034         much sense itself.
0035     */
0036     template<class charT>
0037     class basic_parsed_options {
0038     public:
0039         explicit basic_parsed_options(const options_description* xdescription, int options_prefix = 0)
0040         : description(xdescription), m_options_prefix(options_prefix) {}
0041         /** Options found in the source. */
0042         std::vector< basic_option<charT> > options;
0043         /** Options description that was used for parsing.
0044             Parsers should return pointer to the instance of
0045             option_description passed to them, and issues of lifetime are
0046             up to the caller. Can be NULL.
0047          */
0048         const options_description* description;
0049
0050         /** Mainly used for the diagnostic messages in exceptions.
0051          *  The canonical option prefix  for the parser which generated these results,
0052          *  depending on the settings for basic_command_line_parser::style() or
0053          *  cmdline::style(). In order of precedence of command_line_style enums:
0054          *      allow_long
0055          *      allow_long_disguise
0056          *      allow_dash_for_short
0057          *      allow_slash_for_short
0058         */
0059         int m_options_prefix;
0060     };
0061
0062     /** Specialization of basic_parsed_options which:
0063         - provides convenient conversion from basic_parsed_options<char>
0064         - stores the passed char-based options for later use.
0065     */
0066     template<>
0067     class BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<wchar_t> {
0068     public:
0069         /** Constructs wrapped options from options in UTF8 encoding. */
0070         explicit basic_parsed_options(const basic_parsed_options<char>& po);
0071
0072         std::vector< basic_option<wchar_t> > options;
0073         const options_description* description;
0074
0075         /** Stores UTF8 encoded options that were passed to constructor,
0076             to avoid reverse conversion in some cases. */
0077         basic_parsed_options<char> utf8_encoded_options;
0078
0079         /** Mainly used for the diagnostic messages in exceptions.
0080          *  The canonical option prefix  for the parser which generated these results,
0081          *  depending on the settings for basic_command_line_parser::style() or
0082          *  cmdline::style(). In order of precedence of command_line_style enums:
0083          *      allow_long
0084          *      allow_long_disguise
0085          *      allow_dash_for_short
0086          *      allow_slash_for_short
0087         */
0088         int m_options_prefix;
0089     };
0090
0091     typedef basic_parsed_options<char> parsed_options;
0092     typedef basic_parsed_options<wchar_t> wparsed_options;
0093
0094     /** Augments basic_parsed_options<wchar_t> with conversion from
0095         'parsed_options' */
0096
0097
0098     typedef function1<std::pair<std::string, std::string>, const std::string&> ext_parser;
0099
0100     /** Command line parser.
0101
0102         The class allows one to specify all the information needed for parsing
0103         and to parse the command line. It is primarily needed to
0104         emulate named function parameters \-- a regular function with 5
0105         parameters will be hard to use and creating overloads with a smaller
0106         number of parameters will be confusing.
0107
0108         For the most common case, the function parse_command_line is a better
0109         alternative.
0110
0111         There are two typedefs \-- command_line_parser and wcommand_line_parser,
0112         for charT == char and charT == wchar_t cases.
0113     */
0114     template<class charT>
0115     class basic_command_line_parser : private detail::cmdline {
0116     public:
0117         /** Creates a command line parser for the specified arguments
0118             list. The 'args' parameter should not include program name.
0119         */
0120         basic_command_line_parser(const std::vector<
0121                                   std::basic_string<charT> >& args);
0122         /** Creates a command line parser for the specified arguments
0123             list. The parameters should be the same as passed to 'main'.
0124         */
0125         basic_command_line_parser(int argc, const charT* const argv[]);
0126
0127         /** Sets options descriptions to use. */
0128         basic_command_line_parser& options(const options_description& desc);
0129         /** Sets positional options description to use. */
0130         basic_command_line_parser& positional(
0131             const positional_options_description& desc);
0132
0133         /** Sets the command line style. */
0134         basic_command_line_parser& style(int);
0135         /** Sets the extra parsers. */
0136         basic_command_line_parser& extra_parser(ext_parser);
0137
0138         /** Parses the options and returns the result of parsing.
0139             Throws on error.
0140         */
0141         basic_parsed_options<charT> run();
0142
0143         /** Specifies that unregistered options are allowed and should
0144             be passed though. For each command like token that looks
0145             like an option but does not contain a recognized name, an
0146             instance of basic_option<charT> will be added to result,
0147             with 'unrecognized' field set to 'true'. It's possible to
0148             collect all unrecognized options with the 'collect_unrecognized'
0149             funciton.
0150         */
0151         basic_command_line_parser& allow_unregistered();
0152
0153         using detail::cmdline::style_parser;
0154
0155         basic_command_line_parser& extra_style_parser(style_parser s);
0156
0157     private:
0158         const options_description* m_desc;
0159     };
0160
0161     typedef basic_command_line_parser<char> command_line_parser;
0162     typedef basic_command_line_parser<wchar_t> wcommand_line_parser;
0163
0164     /** Creates instance of 'command_line_parser', passes parameters to it,
0165         and returns the result of calling the 'run' method.
0166      */
0167     template<class charT>
0168     basic_parsed_options<charT>
0169     parse_command_line(int argc, const charT* const argv[],
0170                        const options_description&,
0171                        int style = 0,
0172                        function1<std::pair<std::string, std::string>,
0173                                  const std::string&> ext
0174                        = ext_parser());
0175
0176     /** Parse a config file.
0177
0178         Read from given stream.
0179     */
0180     template<class charT>
0181 #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
0182     BOOST_PROGRAM_OPTIONS_DECL
0183 #endif
0184     basic_parsed_options<charT>
0185     parse_config_file(std::basic_istream<charT>&, const options_description&,
0186                       bool allow_unregistered = false);
0187
0188     /** Parse a config file.
0189
0190         Read from file with the given name. The character type is
0191         passed to the file stream.
0192     */
0193 #ifdef BOOST_NO_CXX11_FUNCTION_TEMPLATE_DEFAULT_ARGS
0194     template<class charT>
0195 #else
0196     template<class charT = char>
0197 #endif
0198 #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
0199     BOOST_PROGRAM_OPTIONS_DECL
0200 #endif
0201     basic_parsed_options<charT>
0202     parse_config_file(const char* filename, const options_description&,
0203                       bool allow_unregistered = false);
0204
0205     /** Controls if the 'collect_unregistered' function should
0206         include positional options, or not. */
0207     enum collect_unrecognized_mode
0208     { include_positional, exclude_positional };
0209
0210     /** Collects the original tokens for all named options with
0211         'unregistered' flag set. If 'mode' is 'include_positional'
0212         also collects all positional options.
0213         Returns the vector of origianl tokens for all collected
0214         options.
0215     */
0216     template<class charT>
0217     std::vector< std::basic_string<charT> >
0218     collect_unrecognized(const std::vector< basic_option<charT> >& options,
0219                          enum collect_unrecognized_mode mode);
0220
0221     /** Parse environment.
0222
0223         For each environment variable, the 'name_mapper' function is called to
0224         obtain the option name. If it returns empty string, the variable is
0225         ignored.
0226
0227         This is done since naming of environment variables is typically
0228         different from the naming of command line options.
0229     */
0230     BOOST_PROGRAM_OPTIONS_DECL parsed_options
0231     parse_environment(const options_description&,
0232                       const function1<std::string, std::string>& name_mapper);
0233
0234     /** Parse environment.
0235
0236         Takes all environment variables which start with 'prefix'. The option
0237         name is obtained from variable name by removing the prefix and
0238         converting the remaining string into lower case.
0239     */
0240     BOOST_PROGRAM_OPTIONS_DECL parsed_options
0241     parse_environment(const options_description&, const std::string& prefix);
0242
0243     /** @overload
0244         This function exists to resolve ambiguity between the two above
0245         functions when second argument is of 'char*' type. There's implicit
0246         conversion to both function1 and string.
0247     */
0248     BOOST_PROGRAM_OPTIONS_DECL parsed_options
0249     parse_environment(const options_description&, const char* prefix);
0250
0251     /** Splits a given string to a collection of single strings which
0252         can be passed to command_line_parser. The second parameter is
0253         used to specify a collection of possible seperator chars used
0254         for splitting. The seperator is defaulted to space " ".
0255         Splitting is done in a unix style way, with respect to quotes '"'
0256         and escape characters '\'
0257     */
0258     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
0259     split_unix(const std::string& cmdline, const std::string& seperator = " \t",
0260          const std::string& quote = "'\"", const std::string& escape = "\\");
0261
0262 #ifndef BOOST_NO_STD_WSTRING
0263     /** @overload */
0264     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
0265     split_unix(const std::wstring& cmdline, const std::wstring& seperator = L" \t",
0266          const std::wstring& quote = L"'\"", const std::wstring& escape = L"\\");
0267 #endif
0268
0269     #ifdef _WIN32
0270     /** Parses the char* string which is passed to WinMain function on
0271         windows. This function is provided for convenience, and because it's
0272         not clear how to portably access split command line string from
0273         runtime library and if it always exists.
0274         This function is available only on Windows.
0275     */
0276     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
0277     split_winmain(const std::string& cmdline);
0278
0279 #ifndef BOOST_NO_STD_WSTRING
0280     /** @overload */
0281     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
0282     split_winmain(const std::wstring& cmdline);
0283     #endif
0284 #endif
0285
0286
0287 }}
0288
0289 #if defined(BOOST_MSVC)
0290 #   pragma warning (pop)
0291 #endif
0292
0293 #undef DECL
0294
0295 #include "boost/program_options/detail/parsers.hpp"
0296
0297 #endif