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
25namespace 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', meaning:
124 @param argc Must be non-negative i.e. >= 0
125 @param argv Argv[argc] must be 0 e.g. nullptr and
126 if argc is >0 argv[0] up to argv[argc-1] must point to
127 null terminated strings
128 */
129 basic_command_line_parser(int argc, const charT* const argv[]);
130
131 /** Sets options descriptions to use. */
132 basic_command_line_parser& options(const options_description& desc);
133 /** Sets positional options description to use. */
134 basic_command_line_parser& positional(
135 const positional_options_description& desc);
136
137 /** Sets the command line style. */
138 basic_command_line_parser& style(int);
139 /** Sets the extra parsers. */
140 basic_command_line_parser& extra_parser(ext_parser);
141
142 /** Parses the options and returns the result of parsing.
143 Throws on error.
144 */
145 basic_parsed_options<charT> run();
146
147 /** Specifies that unregistered options are allowed and should
148 be passed though. For each command like token that looks
149 like an option but does not contain a recognized name, an
150 instance of basic_option<charT> will be added to result,
151 with 'unrecognized' field set to 'true'. It's possible to
152 collect all unrecognized options with the 'collect_unrecognized'
153 funciton.
154 */
155 basic_command_line_parser& allow_unregistered();
156
157 using detail::cmdline::style_parser;
158
159 basic_command_line_parser& extra_style_parser(style_parser s);
160
161 private:
162 const options_description* m_desc;
163 };
164
165 typedef basic_command_line_parser<char> command_line_parser;
166 typedef basic_command_line_parser<wchar_t> wcommand_line_parser;
167
168 /** Creates instance of 'command_line_parser', passes parameters to it,
169 and returns the result of calling the 'run' method.
170 */
171 template<class charT>
172 basic_parsed_options<charT>
173 parse_command_line(int argc, const charT* const argv[],
174 const options_description&,
175 int style = 0,
176 function1<std::pair<std::string, std::string>,
177 const std::string&> ext
178 = ext_parser());
179
180 /** Parse a config file.
181
182 Read from given stream.
183 */
184 template<class charT>
185#if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
186 BOOST_PROGRAM_OPTIONS_DECL
187#endif
188 basic_parsed_options<charT>
189 parse_config_file(std::basic_istream<charT>&, const options_description&,
190 bool allow_unregistered = false);
191
192 /** Parse a config file.
193
194 Read from file with the given name. The character type is
195 passed to the file stream.
196 */
197#ifdef BOOST_NO_CXX11_FUNCTION_TEMPLATE_DEFAULT_ARGS
198 template<class charT>
199#else
200 template<class charT = char>
201#endif
202#if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
203 BOOST_PROGRAM_OPTIONS_DECL
204#endif
205 basic_parsed_options<charT>
206 parse_config_file(const char* filename, const options_description&,
207 bool allow_unregistered = false);
208
209 /** Controls if the 'collect_unregistered' function should
210 include positional options, or not. */
211 enum collect_unrecognized_mode
212 { include_positional, exclude_positional };
213
214 /** Collects the original tokens for all named options with
215 'unregistered' flag set. If 'mode' is 'include_positional'
216 also collects all positional options.
217 Returns the vector of origianl tokens for all collected
218 options.
219 */
220 template<class charT>
221 std::vector< std::basic_string<charT> >
222 collect_unrecognized(const std::vector< basic_option<charT> >& options,
223 enum collect_unrecognized_mode mode);
224
225 /** Parse environment.
226
227 For each environment variable, the 'name_mapper' function is called to
228 obtain the option name. If it returns empty string, the variable is
229 ignored.
230
231 This is done since naming of environment variables is typically
232 different from the naming of command line options.
233 */
234 BOOST_PROGRAM_OPTIONS_DECL parsed_options
235 parse_environment(const options_description&,
236 const function1<std::string, std::string>& name_mapper);
237
238 /** Parse environment.
239
240 Takes all environment variables which start with 'prefix'. The option
241 name is obtained from variable name by removing the prefix and
242 converting the remaining string into lower case.
243 */
244 BOOST_PROGRAM_OPTIONS_DECL parsed_options
245 parse_environment(const options_description&, const std::string& prefix);
246
247 /** @overload
248 This function exists to resolve ambiguity between the two above
249 functions when second argument is of 'char*' type. There's implicit
250 conversion to both function1 and string.
251 */
252 BOOST_PROGRAM_OPTIONS_DECL parsed_options
253 parse_environment(const options_description&, const char* prefix);
254
255 /** Splits a given string to a collection of single strings which
256 can be passed to command_line_parser. The second parameter is
257 used to specify a collection of possible seperator chars used
258 for splitting. The seperator is defaulted to space " ".
259 Splitting is done in a unix style way, with respect to quotes '"'
260 and escape characters '\'
261 */
262 BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
263 split_unix(const std::string& cmdline, const std::string& seperator = " \t",
264 const std::string& quote = "'\"", const std::string& escape = "\\");
265
266#ifndef BOOST_NO_STD_WSTRING
267 /** @overload */
268 BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
269 split_unix(const std::wstring& cmdline, const std::wstring& seperator = L" \t",
270 const std::wstring& quote = L"'\"", const std::wstring& escape = L"\\");
271#endif
272
273 #ifdef _WIN32
274 /** Parses the char* string which is passed to WinMain function on
275 windows. This function is provided for convenience, and because it's
276 not clear how to portably access split command line string from
277 runtime library and if it always exists.
278 This function is available only on Windows.
279 */
280 BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
281 split_winmain(const std::string& cmdline);
282
283#ifndef BOOST_NO_STD_WSTRING
284 /** @overload */
285 BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
286 split_winmain(const std::wstring& cmdline);
287 #endif
288#endif
289
290
291}}
292
293#if defined(BOOST_MSVC)
294# pragma warning (pop)
295#endif
296
297#undef DECL
298
299#include "boost/program_options/detail/parsers.hpp"
300
301#endif
302

source code of boost/libs/program_options/include/boost/program_options/parsers.hpp