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