Chris@16: // Copyright Vladimir Prus 2002-2004. Chris@16: // Distributed under the Boost Software License, Version 1.0. Chris@16: // (See accompanying file LICENSE_1_0.txt Chris@16: // or copy at http://www.boost.org/LICENSE_1_0.txt) Chris@16: Chris@16: Chris@16: #ifndef BOOST_PARSERS_VP_2003_05_19 Chris@16: #define BOOST_PARSERS_VP_2003_05_19 Chris@16: Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: Chris@16: #include Chris@16: Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: Chris@16: #if defined(BOOST_MSVC) Chris@16: # pragma warning (push) Chris@16: # 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' Chris@16: #endif Chris@16: Chris@16: namespace boost { namespace program_options { Chris@16: Chris@16: class options_description; Chris@16: class positional_options_description; Chris@16: Chris@16: Chris@16: /** Results of parsing an input source. Chris@16: The primary use of this class is passing information from parsers Chris@16: component to value storage component. This class does not makes Chris@16: much sense itself. Chris@16: */ Chris@16: template Chris@16: class basic_parsed_options { Chris@16: public: Chris@16: explicit basic_parsed_options(const options_description* xdescription, int options_prefix = 0) Chris@16: : description(xdescription), m_options_prefix(options_prefix) {} Chris@16: /** Options found in the source. */ Chris@16: std::vector< basic_option > options; Chris@16: /** Options description that was used for parsing. Chris@16: Parsers should return pointer to the instance of Chris@16: option_description passed to them, and issues of lifetime are Chris@16: up to the caller. Can be NULL. Chris@16: */ Chris@16: const options_description* description; Chris@16: Chris@16: /** Mainly used for the diagnostic messages in exceptions. Chris@16: * The canonical option prefix for the parser which generated these results, Chris@16: * depending on the settings for basic_command_line_parser::style() or Chris@16: * cmdline::style(). In order of precedence of command_line_style enums: Chris@16: * allow_long Chris@16: * allow_long_disguise Chris@16: * allow_dash_for_short Chris@16: * allow_slash_for_short Chris@16: */ Chris@16: int m_options_prefix; Chris@16: }; Chris@16: Chris@16: /** Specialization of basic_parsed_options which: Chris@16: - provides convenient conversion from basic_parsed_options Chris@16: - stores the passed char-based options for later use. Chris@16: */ Chris@16: template<> Chris@16: class BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options { Chris@16: public: Chris@16: /** Constructs wrapped options from options in UTF8 encoding. */ Chris@16: explicit basic_parsed_options(const basic_parsed_options& po); Chris@16: Chris@16: std::vector< basic_option > options; Chris@16: const options_description* description; Chris@16: Chris@16: /** Stores UTF8 encoded options that were passed to constructor, Chris@16: to avoid reverse conversion in some cases. */ Chris@16: basic_parsed_options utf8_encoded_options; Chris@16: Chris@16: /** Mainly used for the diagnostic messages in exceptions. Chris@16: * The canonical option prefix for the parser which generated these results, Chris@16: * depending on the settings for basic_command_line_parser::style() or Chris@16: * cmdline::style(). In order of precedence of command_line_style enums: Chris@16: * allow_long Chris@16: * allow_long_disguise Chris@16: * allow_dash_for_short Chris@16: * allow_slash_for_short Chris@16: */ Chris@16: int m_options_prefix; Chris@16: }; Chris@16: Chris@16: typedef basic_parsed_options parsed_options; Chris@16: typedef basic_parsed_options wparsed_options; Chris@16: Chris@16: /** Augments basic_parsed_options with conversion from Chris@16: 'parsed_options' */ Chris@16: Chris@16: Chris@16: typedef function1, const std::string&> ext_parser; Chris@16: Chris@16: /** Command line parser. Chris@16: Chris@16: The class allows one to specify all the information needed for parsing Chris@16: and to parse the command line. It is primarily needed to Chris@16: emulate named function parameters -- a regular function with 5 Chris@16: parameters will be hard to use and creating overloads with a smaller Chris@16: nuber of parameters will be confusing. Chris@16: Chris@16: For the most common case, the function parse_command_line is a better Chris@16: alternative. Chris@16: Chris@16: There are two typedefs -- command_line_parser and wcommand_line_parser, Chris@16: for charT == char and charT == wchar_t cases. Chris@16: */ Chris@16: template Chris@16: class basic_command_line_parser : private detail::cmdline { Chris@16: public: Chris@16: /** Creates a command line parser for the specified arguments Chris@16: list. The 'args' parameter should not include program name. Chris@16: */ Chris@16: basic_command_line_parser(const std::vector< Chris@16: std::basic_string >& args); Chris@16: /** Creates a command line parser for the specified arguments Chris@16: list. The parameters should be the same as passed to 'main'. Chris@16: */ Chris@16: basic_command_line_parser(int argc, const charT* const argv[]); Chris@16: Chris@16: /** Sets options descriptions to use. */ Chris@16: basic_command_line_parser& options(const options_description& desc); Chris@16: /** Sets positional options description to use. */ Chris@16: basic_command_line_parser& positional( Chris@16: const positional_options_description& desc); Chris@16: Chris@16: /** Sets the command line style. */ Chris@16: basic_command_line_parser& style(int); Chris@16: /** Sets the extra parsers. */ Chris@16: basic_command_line_parser& extra_parser(ext_parser); Chris@16: Chris@16: /** Parses the options and returns the result of parsing. Chris@16: Throws on error. Chris@16: */ Chris@16: basic_parsed_options run(); Chris@16: Chris@16: /** Specifies that unregistered options are allowed and should Chris@16: be passed though. For each command like token that looks Chris@16: like an option but does not contain a recognized name, an Chris@16: instance of basic_option will be added to result, Chris@16: with 'unrecognized' field set to 'true'. It's possible to Chris@16: collect all unrecognized options with the 'collect_unrecognized' Chris@16: funciton. Chris@16: */ Chris@16: basic_command_line_parser& allow_unregistered(); Chris@16: Chris@16: using detail::cmdline::style_parser; Chris@16: Chris@16: basic_command_line_parser& extra_style_parser(style_parser s); Chris@16: Chris@16: private: Chris@16: const options_description* m_desc; Chris@16: }; Chris@16: Chris@16: typedef basic_command_line_parser command_line_parser; Chris@16: typedef basic_command_line_parser wcommand_line_parser; Chris@16: Chris@16: /** Creates instance of 'command_line_parser', passes parameters to it, Chris@16: and returns the result of calling the 'run' method. Chris@16: */ Chris@16: template Chris@16: basic_parsed_options Chris@16: parse_command_line(int argc, const charT* const argv[], Chris@16: const options_description&, Chris@16: int style = 0, Chris@16: function1, Chris@16: const std::string&> ext Chris@16: = ext_parser()); Chris@16: Chris@16: /** Parse a config file. Chris@16: Chris@16: Read from given stream. Chris@16: */ Chris@16: template Chris@16: #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700)) Chris@16: BOOST_PROGRAM_OPTIONS_DECL Chris@16: #endif Chris@16: basic_parsed_options Chris@16: parse_config_file(std::basic_istream&, const options_description&, Chris@16: bool allow_unregistered = false); Chris@16: Chris@16: /** Parse a config file. Chris@16: Chris@16: Read from file with the given name. The character type is Chris@16: passed to the file stream. Chris@16: */ Chris@16: template Chris@16: #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700)) Chris@16: BOOST_PROGRAM_OPTIONS_DECL Chris@16: #endif Chris@16: basic_parsed_options Chris@16: parse_config_file(const char* filename, const options_description&, Chris@16: bool allow_unregistered = false); Chris@16: Chris@16: /** Controls if the 'collect_unregistered' function should Chris@16: include positional options, or not. */ Chris@16: enum collect_unrecognized_mode Chris@16: { include_positional, exclude_positional }; Chris@16: Chris@16: /** Collects the original tokens for all named options with Chris@16: 'unregistered' flag set. If 'mode' is 'include_positional' Chris@16: also collects all positional options. Chris@16: Returns the vector of origianl tokens for all collected Chris@16: options. Chris@16: */ Chris@16: template Chris@16: std::vector< std::basic_string > Chris@16: collect_unrecognized(const std::vector< basic_option >& options, Chris@16: enum collect_unrecognized_mode mode); Chris@16: Chris@16: /** Parse environment. Chris@16: Chris@16: For each environment variable, the 'name_mapper' function is called to Chris@16: obtain the option name. If it returns empty string, the variable is Chris@16: ignored. Chris@16: Chris@16: This is done since naming of environment variables is typically Chris@16: different from the naming of command line options. Chris@16: */ Chris@16: BOOST_PROGRAM_OPTIONS_DECL parsed_options Chris@16: parse_environment(const options_description&, Chris@16: const function1& name_mapper); Chris@16: Chris@16: /** Parse environment. Chris@16: Chris@16: Takes all environment variables which start with 'prefix'. The option Chris@16: name is obtained from variable name by removing the prefix and Chris@16: converting the remaining string into lower case. Chris@16: */ Chris@16: BOOST_PROGRAM_OPTIONS_DECL parsed_options Chris@16: parse_environment(const options_description&, const std::string& prefix); Chris@16: Chris@16: /** @overload Chris@16: This function exists to resolve ambiguity between the two above Chris@16: functions when second argument is of 'char*' type. There's implicit Chris@16: conversion to both function1 and string. Chris@16: */ Chris@16: BOOST_PROGRAM_OPTIONS_DECL parsed_options Chris@16: parse_environment(const options_description&, const char* prefix); Chris@16: Chris@16: /** Splits a given string to a collection of single strings which Chris@16: can be passed to command_line_parser. The second parameter is Chris@16: used to specify a collection of possible seperator chars used Chris@16: for splitting. The seperator is defaulted to space " ". Chris@16: Splitting is done in a unix style way, with respect to quotes '"' Chris@16: and escape characters '\' Chris@16: */ Chris@16: BOOST_PROGRAM_OPTIONS_DECL std::vector Chris@16: split_unix(const std::string& cmdline, const std::string& seperator = " \t", Chris@16: const std::string& quote = "'\"", const std::string& escape = "\\"); Chris@16: Chris@16: #ifndef BOOST_NO_STD_WSTRING Chris@16: /** @overload */ Chris@16: BOOST_PROGRAM_OPTIONS_DECL std::vector Chris@16: split_unix(const std::wstring& cmdline, const std::wstring& seperator = L" \t", Chris@16: const std::wstring& quote = L"'\"", const std::wstring& escape = L"\\"); Chris@16: #endif Chris@16: Chris@16: #ifdef _WIN32 Chris@16: /** Parses the char* string which is passed to WinMain function on Chris@16: windows. This function is provided for convenience, and because it's Chris@16: not clear how to portably access split command line string from Chris@16: runtime library and if it always exists. Chris@16: This function is available only on Windows. Chris@16: */ Chris@16: BOOST_PROGRAM_OPTIONS_DECL std::vector Chris@16: split_winmain(const std::string& cmdline); Chris@16: Chris@16: #ifndef BOOST_NO_STD_WSTRING Chris@16: /** @overload */ Chris@16: BOOST_PROGRAM_OPTIONS_DECL std::vector Chris@16: split_winmain(const std::wstring& cmdline); Chris@16: #endif Chris@16: #endif Chris@16: Chris@16: Chris@16: }} Chris@16: Chris@16: #if defined(BOOST_MSVC) Chris@16: # pragma warning (pop) Chris@16: #endif Chris@16: Chris@16: #undef DECL Chris@16: Chris@16: #include "boost/program_options/detail/parsers.hpp" Chris@16: Chris@16: #endif