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 namespace boost { namespace program_options {

    21 

    22     class options_description;

    23     class positional_options_description;

    24 

    25 

    26     /** Results of parsing an input source. 

    27         The primary use of this class is passing information from parsers 

    28         component to value storage component. This class does not makes

    29         much sense itself.        

    30     */

    31     template<class charT>

    32     class basic_parsed_options {

    33     public:

    34         explicit basic_parsed_options(const options_description* description) 

    35         : description(description) {}

    36         /** Options found in the source. */

    37         std::vector< basic_option<charT> > options;

    38         /** Options description that was used for parsing. 

    39             Parsers should return pointer to the instance of 

    40             option_description passed to them, and issues of lifetime are

    41             up to the caller. Can be NULL.

    42          */

    43         const options_description* description;

    44     };

    45 

    46     /** Specialization of basic_parsed_options which:

    47         - provides convenient conversion from basic_parsed_options<char>

    48         - stores the passed char-based options for later use.

    49     */

    50     template<>

    51     class BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<wchar_t> {

    52     public:

    53         /** Constructs wrapped options from options in UTF8 encoding. */

    54         explicit basic_parsed_options(const basic_parsed_options<char>& po);

    55 

    56         std::vector< basic_option<wchar_t> > options;

    57         const options_description* description;

    58 

    59         /** Stores UTF8 encoded options that were passed to constructor,

    60             to avoid reverse conversion in some cases. */

    61         basic_parsed_options<char> utf8_encoded_options;        

    62     };

    63 

    64     typedef basic_parsed_options<char> parsed_options;

    65     typedef basic_parsed_options<wchar_t> wparsed_options;

    66 

    67     /** Augments basic_parsed_options<wchar_t> with conversion from

    68         'parsed_options' */

    69 

    70 

    71     typedef function1<std::pair<std::string, std::string>, const std::string&> ext_parser;

    72 

    73     /** Command line parser.

    74 

    75         The class allows one to specify all the information needed for parsing

    76         and to parse the command line. It is primarily needed to

    77         emulate named function parameters -- a regular function with 5

    78         parameters will be hard to use and creating overloads with a smaller

    79         nuber of parameters will be confusing.

    80 

    81         For the most common case, the function parse_command_line is a better 

    82         alternative.        

    83 

    84         There are two typedefs -- command_line_parser and wcommand_line_parser,

    85         for charT == char and charT == wchar_t cases.

    86     */

    87     template<class charT>

    88     class basic_command_line_parser : private detail::cmdline {

    89     public:

    90         /** Creates a command line parser for the specified arguments

    91             list. The 'args' parameter should not include program name.

    92         */

    93         basic_command_line_parser(const std::vector<

    94                                   std::basic_string<charT> >& args);

    95         /** Creates a command line parser for the specified arguments

    96             list. The parameters should be the same as passed to 'main'.

    97         */

    98         basic_command_line_parser(int argc, charT* argv[]);

    99 

   100         /** Sets options descriptions to use. */

   101         basic_command_line_parser& options(const options_description& desc);

   102         /** Sets positional options description to use. */

   103         basic_command_line_parser& positional(

   104             const positional_options_description& desc);

   105 

   106         /** Sets the command line style. */

   107         basic_command_line_parser& style(int);

   108         /** Sets the extra parsers. */

   109         basic_command_line_parser& extra_parser(ext_parser);

   110 

   111         /** Parses the options and returns the result of parsing.

   112             Throws on error.

   113         */

   114         basic_parsed_options<charT> run();

   115 

   116         /** Specifies that unregistered options are allowed and should

   117             be passed though. For each command like token that looks

   118             like an option but does not contain a recognized name, an

   119             instance of basic_option<charT> will be added to result,

   120             with 'unrecognized' field set to 'true'. It's possible to

   121             collect all unrecognized options with the 'collect_unrecognized'

   122             funciton. 

   123         */

   124         basic_command_line_parser& allow_unregistered();

   125         

   126         using detail::cmdline::style_parser;

   127 

   128         basic_command_line_parser& extra_style_parser(style_parser s);

   129 

   130     private:

   131         const options_description* m_desc;

   132     };

   133 

   134     typedef basic_command_line_parser<char> command_line_parser;

   135     typedef basic_command_line_parser<wchar_t> wcommand_line_parser;

   136 

   137     /** Creates instance of 'command_line_parser', passes parameters to it,

   138         and returns the result of calling the 'run' method.        

   139      */

   140     template<class charT>

   141     basic_parsed_options<charT>

   142     parse_command_line(int argc, charT* argv[],

   143                        const options_description&,

   144                        int style = 0,

   145                        function1<std::pair<std::string, std::string>, 

   146                                  const std::string&> ext

   147                        = ext_parser());

   148 

   149     /** Parse a config file. 

   150     */

   151     template<class charT>

   152 #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))

   153     BOOST_PROGRAM_OPTIONS_DECL

   154 #endif

   155     basic_parsed_options<charT>

   156     parse_config_file(std::basic_istream<charT>&, const options_description&);

   157 

   158     /** Controls if the 'collect_unregistered' function should

   159         include positional options, or not. */

   160     enum collect_unrecognized_mode 

   161     { include_positional, exclude_positional };

   162 

   163     /** Collects the original tokens for all named options with

   164         'unregistered' flag set. If 'mode' is 'include_positional'

   165         also collects all positional options.

   166         Returns the vector of origianl tokens for all collected

   167         options.

   168     */

   169     template<class charT>

   170     std::vector< std::basic_string<charT> > 

   171     collect_unrecognized(const std::vector< basic_option<charT> >& options,

   172                          enum collect_unrecognized_mode mode);

   173 

   174     /** Parse environment. 

   175 

   176         For each environment variable, the 'name_mapper' function is called to

   177         obtain the option name. If it returns empty string, the variable is 

   178         ignored. 

   179 

   180         This is done since naming of environment variables is typically 

   181         different from the naming of command line options.        

   182     */

   183     BOOST_PROGRAM_OPTIONS_DECL parsed_options

   184     parse_environment(const options_description&, 

   185                       const function1<std::string, std::string>& name_mapper);

   186 

   187     /** Parse environment.

   188 

   189         Takes all environment variables which start with 'prefix'. The option

   190         name is obtained from variable name by removing the prefix and 

   191         converting the remaining string into lower case.

   192     */

   193     BOOST_PROGRAM_OPTIONS_DECL parsed_options

   194     parse_environment(const options_description&, const std::string& prefix);

   195 

   196     /** @overload

   197         This function exists to resolve ambiguity between the two above 

   198         functions when second argument is of 'char*' type. There's implicit

   199         conversion to both function1 and string.

   200     */

   201     BOOST_PROGRAM_OPTIONS_DECL parsed_options

   202     parse_environment(const options_description&, const char* prefix);

   203 

   204     #ifdef _WIN32

   205     /** Parses the char* string which is passed to WinMain function on

   206         windows. This function is provided for convenience, and because it's

   207         not clear how to portably access split command line string from

   208         runtime library and if it always exists.

   209         This function is available only on Windows.

   210     */

   211     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>

   212     split_winmain(const std::string& cmdline);

   213 

   214 #ifndef BOOST_NO_STD_WSTRING

   215     /** @overload */

   216     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>

   217     split_winmain(const std::wstring& cmdline);

   218     #endif

   219 #endif

   220     

   221 

   222 }}

   223 

   224 #undef DECL

   225 

   226 #include "boost/program_options/detail/parsers.hpp"

   227 

   228 #endif