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

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