1 | /** |
---|
2 | * @copyright |
---|
3 | * ==================================================================== |
---|
4 | * Copyright (c) 2000-2008 CollabNet. All rights reserved. |
---|
5 | * |
---|
6 | * This software is licensed as described in the file COPYING, which |
---|
7 | * you should have received as part of this distribution. The terms |
---|
8 | * are also available at http://subversion.tigris.org/license-1.html. |
---|
9 | * If newer versions of this license are posted there, you may use a |
---|
10 | * newer version instead, at your option. |
---|
11 | * |
---|
12 | * This software consists of voluntary contributions made by many |
---|
13 | * individuals. For exact contribution history, see the revision |
---|
14 | * history and logs, available at http://subversion.tigris.org/. |
---|
15 | * ==================================================================== |
---|
16 | * @endcopyright |
---|
17 | * |
---|
18 | * @file svn_opt.h |
---|
19 | * @brief Option and argument parsing for Subversion command lines |
---|
20 | */ |
---|
21 | |
---|
22 | #ifndef SVN_OPTS_H |
---|
23 | #define SVN_OPTS_H |
---|
24 | |
---|
25 | #include <apr.h> |
---|
26 | #include <apr_pools.h> |
---|
27 | #include <apr_getopt.h> |
---|
28 | #include <apr_tables.h> |
---|
29 | #include <apr_hash.h> |
---|
30 | |
---|
31 | #ifndef DOXYGEN_SHOULD_SKIP_THIS |
---|
32 | #define APR_WANT_STDIO |
---|
33 | #endif |
---|
34 | #include <apr_want.h> /* for FILE* */ |
---|
35 | |
---|
36 | #include "svn_types.h" |
---|
37 | |
---|
38 | #ifdef __cplusplus |
---|
39 | extern "C" { |
---|
40 | #endif /* __cplusplus */ |
---|
41 | |
---|
42 | |
---|
43 | |
---|
44 | /** |
---|
45 | * All subcommand procedures in Subversion conform to this prototype. |
---|
46 | * |
---|
47 | * @a os is the apr option state after getopt processing has been run; in |
---|
48 | * other words, it still contains the non-option arguments following |
---|
49 | * the subcommand. See @a os->argv and @a os->ind. |
---|
50 | * |
---|
51 | * @a baton is anything you need it to be. |
---|
52 | * |
---|
53 | * @a pool is used for allocating errors, and for any other allocation |
---|
54 | * unless the instance is explicitly documented to allocate from a |
---|
55 | * pool in @a baton. |
---|
56 | */ |
---|
57 | typedef svn_error_t *(svn_opt_subcommand_t) |
---|
58 | (apr_getopt_t *os, void *baton, apr_pool_t *pool); |
---|
59 | |
---|
60 | |
---|
61 | /** The maximum number of aliases a subcommand can have. */ |
---|
62 | #define SVN_OPT_MAX_ALIASES 3 |
---|
63 | |
---|
64 | /** The maximum number of options that can be accepted by a subcommand. */ |
---|
65 | #define SVN_OPT_MAX_OPTIONS 50 |
---|
66 | |
---|
67 | /** Options that have no short option char should use an identifying |
---|
68 | * integer equal to or greater than this. |
---|
69 | */ |
---|
70 | #define SVN_OPT_FIRST_LONGOPT_ID 256 |
---|
71 | |
---|
72 | |
---|
73 | /** One element of a subcommand dispatch table. |
---|
74 | * |
---|
75 | * @since New in 1.4. |
---|
76 | */ |
---|
77 | typedef struct svn_opt_subcommand_desc2_t |
---|
78 | { |
---|
79 | /** The full name of this command. */ |
---|
80 | const char *name; |
---|
81 | |
---|
82 | /** The function this command invokes. */ |
---|
83 | svn_opt_subcommand_t *cmd_func; |
---|
84 | |
---|
85 | /** A list of alias names for this command (e.g., 'up' for 'update'). */ |
---|
86 | const char *aliases[SVN_OPT_MAX_ALIASES]; |
---|
87 | |
---|
88 | /** A brief string describing this command, for usage messages. */ |
---|
89 | const char *help; |
---|
90 | |
---|
91 | /** A list of options accepted by this command. Each value in the |
---|
92 | * array is a unique enum (the 2nd field in apr_getopt_option_t) |
---|
93 | */ |
---|
94 | int valid_options[SVN_OPT_MAX_OPTIONS]; |
---|
95 | |
---|
96 | /** A list of option help descriptions, keyed by the option unique enum |
---|
97 | * (the 2nd field in apr_getopt_option_t), which override the generic |
---|
98 | * descriptions given in an apr_getopt_option_t on a per-subcommand basis. |
---|
99 | */ |
---|
100 | struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS]; |
---|
101 | } svn_opt_subcommand_desc2_t; |
---|
102 | |
---|
103 | |
---|
104 | /** One element of a subcommand dispatch table. |
---|
105 | * |
---|
106 | * @deprecated Provided for backward compatibility with the 1.3 API. |
---|
107 | * |
---|
108 | * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides |
---|
109 | * member. |
---|
110 | */ |
---|
111 | typedef struct svn_opt_subcommand_desc_t |
---|
112 | { |
---|
113 | /** The full name of this command. */ |
---|
114 | const char *name; |
---|
115 | |
---|
116 | /** The function this command invokes. */ |
---|
117 | svn_opt_subcommand_t *cmd_func; |
---|
118 | |
---|
119 | /** A list of alias names for this command (e.g., 'up' for 'update'). */ |
---|
120 | const char *aliases[SVN_OPT_MAX_ALIASES]; |
---|
121 | |
---|
122 | /** A brief string describing this command, for usage messages. */ |
---|
123 | const char *help; |
---|
124 | |
---|
125 | /** A list of options accepted by this command. Each value in the |
---|
126 | * array is a unique enum (the 2nd field in apr_getopt_option_t) |
---|
127 | */ |
---|
128 | int valid_options[SVN_OPT_MAX_OPTIONS]; |
---|
129 | |
---|
130 | } svn_opt_subcommand_desc_t; |
---|
131 | |
---|
132 | |
---|
133 | /** |
---|
134 | * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if |
---|
135 | * none. @a cmd_name may be an alias. |
---|
136 | * |
---|
137 | * @since New in 1.4. |
---|
138 | */ |
---|
139 | const svn_opt_subcommand_desc2_t * |
---|
140 | svn_opt_get_canonical_subcommand2(const svn_opt_subcommand_desc2_t *table, |
---|
141 | const char *cmd_name); |
---|
142 | |
---|
143 | |
---|
144 | /** |
---|
145 | * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if |
---|
146 | * none. @a cmd_name may be an alias. |
---|
147 | * |
---|
148 | * Same as svn_opt_get_canonical_subcommand2(), but acts on |
---|
149 | * #svn_opt_subcommand_desc_t. |
---|
150 | * |
---|
151 | * @deprecated Provided for backward compatibility with the 1.3 API. |
---|
152 | */ |
---|
153 | SVN_DEPRECATED |
---|
154 | const svn_opt_subcommand_desc_t * |
---|
155 | svn_opt_get_canonical_subcommand(const svn_opt_subcommand_desc_t *table, |
---|
156 | const char *cmd_name); |
---|
157 | |
---|
158 | |
---|
159 | /** |
---|
160 | * Return pointer to an @c apr_getopt_option_t for the option whose |
---|
161 | * option code is @a code, or @c NULL if no match. @a option_table must end |
---|
162 | * with an element whose every field is zero. If @c command is non-NULL, |
---|
163 | * then return the subcommand-specific option description instead of the |
---|
164 | * generic one, if a specific description is defined. |
---|
165 | * |
---|
166 | * The returned value may be statically allocated, or allocated in @a pool. |
---|
167 | * |
---|
168 | * @since New in 1.4. |
---|
169 | */ |
---|
170 | const apr_getopt_option_t * |
---|
171 | svn_opt_get_option_from_code2(int code, |
---|
172 | const apr_getopt_option_t *option_table, |
---|
173 | const svn_opt_subcommand_desc2_t *command, |
---|
174 | apr_pool_t *pool); |
---|
175 | |
---|
176 | |
---|
177 | /** |
---|
178 | * Return the first entry from @a option_table whose option code is @a code, |
---|
179 | * or @c NULL if no match. @a option_table must end with an element whose |
---|
180 | * every field is zero. |
---|
181 | * |
---|
182 | * @deprecated Provided for backward compatibility with the 1.3 API. |
---|
183 | */ |
---|
184 | SVN_DEPRECATED |
---|
185 | const apr_getopt_option_t * |
---|
186 | svn_opt_get_option_from_code(int code, |
---|
187 | const apr_getopt_option_t *option_table); |
---|
188 | |
---|
189 | |
---|
190 | /** |
---|
191 | * Return @c TRUE iff subcommand @a command supports option @a |
---|
192 | * option_code, else return @c FALSE. If @a global_options is |
---|
193 | * non-NULL, it is a zero-terminated array, and all subcommands take |
---|
194 | * the options listed in it. |
---|
195 | * |
---|
196 | * @since New in 1.5. |
---|
197 | */ |
---|
198 | svn_boolean_t |
---|
199 | svn_opt_subcommand_takes_option3(const svn_opt_subcommand_desc2_t *command, |
---|
200 | int option_code, |
---|
201 | const int *global_options); |
---|
202 | |
---|
203 | /** |
---|
204 | * Same as svn_opt_subcommand_takes_option3(), but with @c NULL for @a |
---|
205 | * global_options. |
---|
206 | * |
---|
207 | * @deprecated Provided for backward compatibility with the 1.4 API. |
---|
208 | */ |
---|
209 | SVN_DEPRECATED |
---|
210 | svn_boolean_t |
---|
211 | svn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t *command, |
---|
212 | int option_code); |
---|
213 | |
---|
214 | |
---|
215 | /** |
---|
216 | * Return @c TRUE iff subcommand @a command supports option @a option_code, |
---|
217 | * else return @c FALSE. |
---|
218 | * |
---|
219 | * Same as svn_opt_subcommand_takes_option2(), but acts on |
---|
220 | * #svn_opt_subcommand_desc_t. |
---|
221 | * |
---|
222 | * @deprecated Provided for backward compatibility with the 1.3 API. |
---|
223 | */ |
---|
224 | SVN_DEPRECATED |
---|
225 | svn_boolean_t |
---|
226 | svn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t *command, |
---|
227 | int option_code); |
---|
228 | |
---|
229 | |
---|
230 | /** |
---|
231 | * Print a generic (not command-specific) usage message to @a stream. |
---|
232 | * |
---|
233 | * ### @todo Why is @a stream a stdio file instead of an svn stream? |
---|
234 | * |
---|
235 | * If @a header is non-NULL, print @a header followed by a newline. Then |
---|
236 | * loop over @a cmd_table printing the usage for each command (getting |
---|
237 | * option usages from @a opt_table). Then if @a footer is non-NULL, print |
---|
238 | * @a footer followed by a newline. |
---|
239 | * |
---|
240 | * Use @a pool for temporary allocation. |
---|
241 | * |
---|
242 | * @since New in 1.4. |
---|
243 | */ |
---|
244 | void |
---|
245 | svn_opt_print_generic_help2(const char *header, |
---|
246 | const svn_opt_subcommand_desc2_t *cmd_table, |
---|
247 | const apr_getopt_option_t *opt_table, |
---|
248 | const char *footer, |
---|
249 | apr_pool_t *pool, |
---|
250 | FILE *stream); |
---|
251 | |
---|
252 | |
---|
253 | /** |
---|
254 | * Same as svn_opt_print_generic_help2(), but acts on |
---|
255 | * #svn_opt_subcommand_desc_t. |
---|
256 | * |
---|
257 | * @deprecated Provided for backward compatibility with the 1.3 API. |
---|
258 | */ |
---|
259 | SVN_DEPRECATED |
---|
260 | void |
---|
261 | svn_opt_print_generic_help(const char *header, |
---|
262 | const svn_opt_subcommand_desc_t *cmd_table, |
---|
263 | const apr_getopt_option_t *opt_table, |
---|
264 | const char *footer, |
---|
265 | apr_pool_t *pool, |
---|
266 | FILE *stream); |
---|
267 | |
---|
268 | |
---|
269 | /** |
---|
270 | * Print an option @a opt nicely into a @a string allocated in @a pool. |
---|
271 | * If @a doc is set, include the generic documentation string of @a opt, |
---|
272 | * localized to the current locale if a translation is available. |
---|
273 | */ |
---|
274 | void |
---|
275 | svn_opt_format_option(const char **string, |
---|
276 | const apr_getopt_option_t *opt, |
---|
277 | svn_boolean_t doc, |
---|
278 | apr_pool_t *pool); |
---|
279 | |
---|
280 | |
---|
281 | |
---|
282 | /** |
---|
283 | * Get @a subcommand's usage from @a table, and print it to @c stdout. |
---|
284 | * Obtain option usage from @a options_table. If not @c NULL, @a |
---|
285 | * global_options is a zero-terminated list of global options. Use @a |
---|
286 | * pool for temporary allocation. @a subcommand may be a canonical |
---|
287 | * command name or an alias. ### @todo Why does this only print to |
---|
288 | * @c stdout, whereas svn_opt_print_generic_help() gives us a choice? |
---|
289 | * |
---|
290 | * @since New in 1.5. |
---|
291 | */ |
---|
292 | void |
---|
293 | svn_opt_subcommand_help3(const char *subcommand, |
---|
294 | const svn_opt_subcommand_desc2_t *table, |
---|
295 | const apr_getopt_option_t *options_table, |
---|
296 | const int *global_options, |
---|
297 | apr_pool_t *pool); |
---|
298 | |
---|
299 | /** |
---|
300 | * Same as svn_opt_subcommand_help3(), but with @a global_options |
---|
301 | * always NULL. |
---|
302 | * |
---|
303 | * @deprecated Provided for backward compatibility with the 1.4 API. |
---|
304 | */ |
---|
305 | SVN_DEPRECATED |
---|
306 | void |
---|
307 | svn_opt_subcommand_help2(const char *subcommand, |
---|
308 | const svn_opt_subcommand_desc2_t *table, |
---|
309 | const apr_getopt_option_t *options_table, |
---|
310 | apr_pool_t *pool); |
---|
311 | |
---|
312 | |
---|
313 | /** |
---|
314 | * Same as svn_opt_subcommand_help2(), but acts on |
---|
315 | * #svn_opt_subcommand_desc_t. |
---|
316 | * |
---|
317 | * @deprecated Provided for backward compatibility with the 1.3 API. |
---|
318 | */ |
---|
319 | SVN_DEPRECATED |
---|
320 | void |
---|
321 | svn_opt_subcommand_help(const char *subcommand, |
---|
322 | const svn_opt_subcommand_desc_t *table, |
---|
323 | const apr_getopt_option_t *options_table, |
---|
324 | apr_pool_t *pool); |
---|
325 | |
---|
326 | |
---|
327 | |
---|
328 | /* Parsing revision and date options. */ |
---|
329 | |
---|
330 | /** |
---|
331 | * Various ways of specifying revisions. |
---|
332 | * |
---|
333 | * @note |
---|
334 | * In contexts where local mods are relevant, the `working' kind |
---|
335 | * refers to the uncommitted "working" revision, which may be modified |
---|
336 | * with respect to its base revision. In other contexts, `working' |
---|
337 | * should behave the same as `committed' or `current'. |
---|
338 | */ |
---|
339 | enum svn_opt_revision_kind { |
---|
340 | /** No revision information given. */ |
---|
341 | svn_opt_revision_unspecified, |
---|
342 | |
---|
343 | /** revision given as number */ |
---|
344 | svn_opt_revision_number, |
---|
345 | |
---|
346 | /** revision given as date */ |
---|
347 | svn_opt_revision_date, |
---|
348 | |
---|
349 | /** rev of most recent change */ |
---|
350 | svn_opt_revision_committed, |
---|
351 | |
---|
352 | /** (rev of most recent change) - 1 */ |
---|
353 | svn_opt_revision_previous, |
---|
354 | |
---|
355 | /** .svn/entries current revision */ |
---|
356 | svn_opt_revision_base, |
---|
357 | |
---|
358 | /** current, plus local mods */ |
---|
359 | svn_opt_revision_working, |
---|
360 | |
---|
361 | /** repository youngest */ |
---|
362 | svn_opt_revision_head |
---|
363 | }; |
---|
364 | |
---|
365 | /** |
---|
366 | * A revision value, which can be specified as a number or a date. |
---|
367 | * |
---|
368 | * @note This union was formerly an anonymous inline type in |
---|
369 | * @c svn_opt_revision_t, and was converted to a named type just to |
---|
370 | * make things easier for SWIG. |
---|
371 | * |
---|
372 | * @since New in 1.3. |
---|
373 | */ |
---|
374 | typedef union svn_opt_revision_value_t |
---|
375 | { |
---|
376 | /** The revision number */ |
---|
377 | svn_revnum_t number; |
---|
378 | |
---|
379 | /** the date of the revision */ |
---|
380 | apr_time_t date; |
---|
381 | } svn_opt_revision_value_t; |
---|
382 | |
---|
383 | /** A revision, specified in one of @c svn_opt_revision_kind ways. */ |
---|
384 | typedef struct svn_opt_revision_t |
---|
385 | { |
---|
386 | enum svn_opt_revision_kind kind; /**< See svn_opt_revision_kind */ |
---|
387 | svn_opt_revision_value_t value; /**< Extra data qualifying the @c kind */ |
---|
388 | } svn_opt_revision_t; |
---|
389 | |
---|
390 | /** A revision range, specified in one of @c svn_opt_revision_kind ways. */ |
---|
391 | typedef struct svn_opt_revision_range_t |
---|
392 | { |
---|
393 | /** The first revision in the range */ |
---|
394 | svn_opt_revision_t start; |
---|
395 | |
---|
396 | /** The last revision in the range */ |
---|
397 | svn_opt_revision_t end; |
---|
398 | } svn_opt_revision_range_t; |
---|
399 | |
---|
400 | /** |
---|
401 | * Set @a *start_revision and/or @a *end_revision according to @a arg, |
---|
402 | * where @a arg is "N" or "N:M", like so: |
---|
403 | * |
---|
404 | * - If @a arg is "N", set @a *start_revision to represent N, and |
---|
405 | * leave @a *end_revision untouched. |
---|
406 | * |
---|
407 | * - If @a arg is "N:M", set @a *start_revision and @a *end_revision |
---|
408 | * to represent N and M respectively. |
---|
409 | * |
---|
410 | * N and/or M may be one of the special revision descriptors |
---|
411 | * recognized by revision_from_word(), or a date in curly braces. |
---|
412 | * |
---|
413 | * If @a arg is invalid, return -1; else return 0. |
---|
414 | * It is invalid to omit a revision (as in, ":", "N:" or ":M"). |
---|
415 | * |
---|
416 | * @note It is typical, though not required, for @a *start_revision and |
---|
417 | * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry. |
---|
418 | * |
---|
419 | * Use @a pool for temporary allocations. |
---|
420 | */ |
---|
421 | int |
---|
422 | svn_opt_parse_revision(svn_opt_revision_t *start_revision, |
---|
423 | svn_opt_revision_t *end_revision, |
---|
424 | const char *arg, |
---|
425 | apr_pool_t *pool); |
---|
426 | |
---|
427 | /** |
---|
428 | * Parse @a arg, where @a arg is "N" or "N:M", into a |
---|
429 | * @c svn_opt_revision_range_t and push that onto @a opt_ranges. |
---|
430 | * |
---|
431 | * - If @a arg is "N", set the @c start field of the |
---|
432 | * @c svn_opt_revision_range_t to represent N and the @c end field |
---|
433 | * to @c svn_opt_revision_unspecified. |
---|
434 | * |
---|
435 | * - If @a arg is "N:M", set the @c start field of the |
---|
436 | * @c svn_opt_revision_range_t to represent N and the @c end field |
---|
437 | * to represent M. |
---|
438 | * |
---|
439 | * If @a arg is invalid, return -1; else return 0. It is invalid to omit |
---|
440 | * a revision (as in, ":", "N:" or ":M"). |
---|
441 | * |
---|
442 | * Use @a pool to allocate @c svn_opt_revision_range_t pushed to the array. |
---|
443 | * |
---|
444 | * @since New in 1.5. |
---|
445 | */ |
---|
446 | int |
---|
447 | svn_opt_parse_revision_to_range(apr_array_header_t *opt_ranges, |
---|
448 | const char *arg, |
---|
449 | apr_pool_t *pool); |
---|
450 | |
---|
451 | /** |
---|
452 | * Resolve peg revisions and operational revisions in the following way: |
---|
453 | * |
---|
454 | * - If @a is_url is set and @a peg_rev->kind is |
---|
455 | * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to |
---|
456 | * @c svn_opt_revision_head. |
---|
457 | * |
---|
458 | * - If @a is_url is not set, and @a peg_rev->kind is |
---|
459 | * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to |
---|
460 | * @c svn_opt_revision_base. |
---|
461 | * |
---|
462 | * - If @a op_rev->kind is @c svn_opt_revision_unspecified, @a op_rev |
---|
463 | * defaults to @a peg_rev. |
---|
464 | * |
---|
465 | * Both @a peg_rev and @a op_rev may be modified as a result of this |
---|
466 | * function. @a is_url should be set if the path the revisions refer to is |
---|
467 | * a url, and unset otherwise. |
---|
468 | * |
---|
469 | * If @a notice_local_mods is set, @c svn_opt_revision_working is used, |
---|
470 | * instead of @c svn_opt_revision_base. |
---|
471 | * |
---|
472 | * Use @a pool for allocations. |
---|
473 | * |
---|
474 | * @since New in 1.5. |
---|
475 | */ |
---|
476 | svn_error_t * |
---|
477 | svn_opt_resolve_revisions(svn_opt_revision_t *peg_rev, |
---|
478 | svn_opt_revision_t *op_rev, |
---|
479 | svn_boolean_t is_url, |
---|
480 | svn_boolean_t notice_local_mods, |
---|
481 | apr_pool_t *pool); |
---|
482 | |
---|
483 | |
---|
484 | /* Parsing arguments. */ |
---|
485 | |
---|
486 | /** |
---|
487 | * Pull remaining target arguments from @a os into @a *targets_p, |
---|
488 | * converting them to UTF-8, followed by targets from @a known_targets |
---|
489 | * (which might come from, for example, the "--targets" command line |
---|
490 | * option), which are already in UTF-8. |
---|
491 | * |
---|
492 | * On each URL target, do some IRI-to-URI encoding and some |
---|
493 | * auto-escaping. On each local path, canonicalize case and path |
---|
494 | * separators. |
---|
495 | * |
---|
496 | * Allocate @a *targets_p and its elements in @a pool. |
---|
497 | * |
---|
498 | * If a path has the same name as a Subversion working copy |
---|
499 | * administrative directory, return SVN_ERR_RESERVED_FILENAME_SPECIFIED; |
---|
500 | * if multiple reserved paths are encountered, return a chain of |
---|
501 | * errors, all of which are SVN_ERR_RESERVED_FILENAME_SPECIFIED. Do |
---|
502 | * not return this type of error in a chain with any other type of |
---|
503 | * error, and if this is the only type of error encountered, complete |
---|
504 | * the operation before returning the error(s). |
---|
505 | * |
---|
506 | * @deprecated Provided for backward compatibility with the 1.5 API. |
---|
507 | * @see svn_client_args_to_target_array() |
---|
508 | */ |
---|
509 | SVN_DEPRECATED |
---|
510 | svn_error_t * |
---|
511 | svn_opt_args_to_target_array3(apr_array_header_t **targets_p, |
---|
512 | apr_getopt_t *os, |
---|
513 | apr_array_header_t *known_targets, |
---|
514 | apr_pool_t *pool); |
---|
515 | |
---|
516 | /** |
---|
517 | * This is the same as svn_opt_args_to_target_array3() except that it |
---|
518 | * silently ignores paths that have the same name as a working copy |
---|
519 | * administrative directory. |
---|
520 | * |
---|
521 | * @since New in 1.2. |
---|
522 | * |
---|
523 | * @deprecated Provided for backward compatibility with the 1.4 API. |
---|
524 | */ |
---|
525 | SVN_DEPRECATED |
---|
526 | svn_error_t * |
---|
527 | svn_opt_args_to_target_array2(apr_array_header_t **targets_p, |
---|
528 | apr_getopt_t *os, |
---|
529 | apr_array_header_t *known_targets, |
---|
530 | apr_pool_t *pool); |
---|
531 | |
---|
532 | |
---|
533 | /** |
---|
534 | * The same as svn_opt_args_to_target_array2() except that, in |
---|
535 | * addition, if @a extract_revisions is set, then look for trailing |
---|
536 | * "@rev" syntax on the first two paths. If the first target in @a |
---|
537 | * *targets_p ends in "@rev", replace it with a canonicalized version of |
---|
538 | * the part before "@rev" and replace @a *start_revision with the value |
---|
539 | * of "rev". If the second target in @a *targets_p ends in "@rev", |
---|
540 | * replace it with a canonicalized version of the part before "@rev" |
---|
541 | * and replace @a *end_revision with the value of "rev". Ignore |
---|
542 | * revision specifiers on any further paths. "rev" can be any form of |
---|
543 | * single revision specifier, as accepted by svn_opt_parse_revision(). |
---|
544 | * |
---|
545 | * @deprecated Provided for backward compatibility with the 1.1 API. |
---|
546 | */ |
---|
547 | SVN_DEPRECATED |
---|
548 | svn_error_t * |
---|
549 | svn_opt_args_to_target_array(apr_array_header_t **targets_p, |
---|
550 | apr_getopt_t *os, |
---|
551 | apr_array_header_t *known_targets, |
---|
552 | svn_opt_revision_t *start_revision, |
---|
553 | svn_opt_revision_t *end_revision, |
---|
554 | svn_boolean_t extract_revisions, |
---|
555 | apr_pool_t *pool); |
---|
556 | |
---|
557 | |
---|
558 | /** |
---|
559 | * Parse revprop key/value pair from @a revprop_spec (name[=value]) into |
---|
560 | * @a revprops, making copies of both with @a pool. If @a revprops is |
---|
561 | * @c NULL, allocate a new apr_hash_t in it. @a revprops maps |
---|
562 | * const char * revprop names to svn_string_t * revprop values for use |
---|
563 | * with svn_repos_get_commit_editor5 and other get_commit_editor APIs. |
---|
564 | * |
---|
565 | * @since New in 1.6. |
---|
566 | */ |
---|
567 | svn_error_t * |
---|
568 | svn_opt_parse_revprop(apr_hash_t **revprops, const char *revprop_spec, |
---|
569 | apr_pool_t *pool); |
---|
570 | |
---|
571 | |
---|
572 | /** |
---|
573 | * If no targets exist in @a *targets, add `.' as the lone target. |
---|
574 | * |
---|
575 | * (Some commands take an implicit "." string argument when invoked |
---|
576 | * with no arguments. Those commands make use of this function to |
---|
577 | * add "." to the target array if the user passes no args.) |
---|
578 | */ |
---|
579 | void |
---|
580 | svn_opt_push_implicit_dot_target(apr_array_header_t *targets, |
---|
581 | apr_pool_t *pool); |
---|
582 | |
---|
583 | |
---|
584 | /** |
---|
585 | * Parse @a num_args non-target arguments from the list of arguments in |
---|
586 | * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without |
---|
587 | * doing any UTF-8 conversion. Allocate @a *args_p and its values in @a pool. |
---|
588 | */ |
---|
589 | svn_error_t * |
---|
590 | svn_opt_parse_num_args(apr_array_header_t **args_p, |
---|
591 | apr_getopt_t *os, |
---|
592 | int num_args, |
---|
593 | apr_pool_t *pool); |
---|
594 | |
---|
595 | |
---|
596 | /** |
---|
597 | * Parse all remaining arguments from @a os->argv, return them as |
---|
598 | * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion. |
---|
599 | * Allocate @a *args_p and its values in @a pool. |
---|
600 | */ |
---|
601 | svn_error_t * |
---|
602 | svn_opt_parse_all_args(apr_array_header_t **args_p, |
---|
603 | apr_getopt_t *os, |
---|
604 | apr_pool_t *pool); |
---|
605 | |
---|
606 | /** |
---|
607 | * Parse a working-copy or URL in @a path, extracting any trailing |
---|
608 | * revision specifier of the form "@rev" from the last component of |
---|
609 | * the path. |
---|
610 | * |
---|
611 | * Some examples would be: |
---|
612 | * |
---|
613 | * "foo/bar" -> "foo/bar", (unspecified) |
---|
614 | * "foo/bar@13" -> "foo/bar", (number, 13) |
---|
615 | * "foo/bar@HEAD" -> "foo/bar", (head) |
---|
616 | * "foo/bar@{1999-12-31}" -> "foo/bar", (date, 1999-12-31) |
---|
617 | * "http://a/b@27" -> "http://a/b", (number, 27) |
---|
618 | * "http://a/b@COMMITTED" -> "http://a/b", (committed) [*] |
---|
619 | * "http://a/b@{1999-12-31} -> "http://a/b", (date, 1999-12-31) |
---|
620 | * "http://a/b@%7B1999-12-31%7D -> "http://a/b", (date, 1999-12-31) |
---|
621 | * "foo/bar@1:2" -> error |
---|
622 | * "foo/bar@baz" -> error |
---|
623 | * "foo/bar@" -> "foo/bar", (base) |
---|
624 | * "foo/bar/@13" -> "foo/bar/", (number, 13) |
---|
625 | * "foo/bar@@13" -> "foo/bar@", (number, 13) |
---|
626 | * "foo/@bar@HEAD" -> "foo/@bar", (head) |
---|
627 | * "foo@/bar" -> "foo@/bar", (unspecified) |
---|
628 | * "foo@HEAD/bar" -> "foo@HEAD/bar", (unspecified) |
---|
629 | * |
---|
630 | * [*] Syntactically valid but probably not semantically useful. |
---|
631 | * |
---|
632 | * If a trailing revision specifier is found, parse it into @a *rev and |
---|
633 | * put the rest of the path into @a *truepath, allocating from @a pool; |
---|
634 | * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR (with the effect on |
---|
635 | * @a *truepath undefined) if the revision specifier is invalid. |
---|
636 | * If no trailing revision specifier is found, set @a *truepath to |
---|
637 | * @a path and @a rev->kind to @c svn_opt_revision_unspecified. |
---|
638 | * |
---|
639 | * This function does not require that @a path be in canonical form. |
---|
640 | * No canonicalization is done and @a *truepath will only be in |
---|
641 | * canonical form if @a path is in canonical form. |
---|
642 | * |
---|
643 | * @since New in 1.1. |
---|
644 | */ |
---|
645 | svn_error_t * |
---|
646 | svn_opt_parse_path(svn_opt_revision_t *rev, |
---|
647 | const char **truepath, |
---|
648 | const char *path, |
---|
649 | apr_pool_t *pool); |
---|
650 | |
---|
651 | /** |
---|
652 | * Central dispatcher function for various kinds of help message. |
---|
653 | * Prints one of: |
---|
654 | * * subcommand-specific help (svn_opt_subcommand_help) |
---|
655 | * * generic help (svn_opt_print_generic_help) |
---|
656 | * * version info |
---|
657 | * * simple usage complaint: "Type '@a pgm_name help' for usage." |
---|
658 | * |
---|
659 | * If @a os is not @c NULL and it contains arguments, then try |
---|
660 | * printing help for them as though they are subcommands, using @a |
---|
661 | * cmd_table and @a option_table for option information. If not @c |
---|
662 | * NULL, @a global_options is a zero-terminated array of options taken |
---|
663 | * by all subcommands. |
---|
664 | * |
---|
665 | * Else, if @a print_version is TRUE, then print version info, in |
---|
666 | * brief form if @a quiet is also TRUE; if @a quiet is FALSE, then if |
---|
667 | * @a version_footer is non-NULL, print it following the version |
---|
668 | * information. |
---|
669 | * |
---|
670 | * Else, if @a os is not @c NULL and does not contain arguments, print |
---|
671 | * generic help, via svn_opt_print_generic_help2() with the @a header, |
---|
672 | * @a cmd_table, @a option_table, and @a footer arguments. |
---|
673 | * |
---|
674 | * Else, when @a os is @c NULL, print the simple usage complaint. |
---|
675 | * |
---|
676 | * Use @a pool for temporary allocations. |
---|
677 | * |
---|
678 | * Notes: The reason this function handles both version printing and |
---|
679 | * general usage help is that a confused user might put both the |
---|
680 | * --version flag *and* subcommand arguments on a help command line. |
---|
681 | * The logic for handling such a situation should be in one place. |
---|
682 | * |
---|
683 | * @since New in 1.5. |
---|
684 | */ |
---|
685 | svn_error_t * |
---|
686 | svn_opt_print_help3(apr_getopt_t *os, |
---|
687 | const char *pgm_name, |
---|
688 | svn_boolean_t print_version, |
---|
689 | svn_boolean_t quiet, |
---|
690 | const char *version_footer, |
---|
691 | const char *header, |
---|
692 | const svn_opt_subcommand_desc2_t *cmd_table, |
---|
693 | const apr_getopt_option_t *option_table, |
---|
694 | const int *global_options, |
---|
695 | const char *footer, |
---|
696 | apr_pool_t *pool); |
---|
697 | |
---|
698 | /** |
---|
699 | * Same as svn_opt_print_help3(), but with @a global_options always @c |
---|
700 | * NULL. |
---|
701 | * |
---|
702 | * @deprecated Provided for backward compatibility with the 1.4 API. |
---|
703 | */ |
---|
704 | |
---|
705 | SVN_DEPRECATED |
---|
706 | svn_error_t * |
---|
707 | svn_opt_print_help2(apr_getopt_t *os, |
---|
708 | const char *pgm_name, |
---|
709 | svn_boolean_t print_version, |
---|
710 | svn_boolean_t quiet, |
---|
711 | const char *version_footer, |
---|
712 | const char *header, |
---|
713 | const svn_opt_subcommand_desc2_t *cmd_table, |
---|
714 | const apr_getopt_option_t *option_table, |
---|
715 | const char *footer, |
---|
716 | apr_pool_t *pool); |
---|
717 | |
---|
718 | |
---|
719 | /** |
---|
720 | * Same as svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t. |
---|
721 | * |
---|
722 | * @deprecated Provided for backward compatibility with the 1.3 API. |
---|
723 | */ |
---|
724 | SVN_DEPRECATED |
---|
725 | svn_error_t * |
---|
726 | svn_opt_print_help(apr_getopt_t *os, |
---|
727 | const char *pgm_name, |
---|
728 | svn_boolean_t print_version, |
---|
729 | svn_boolean_t quiet, |
---|
730 | const char *version_footer, |
---|
731 | const char *header, |
---|
732 | const svn_opt_subcommand_desc_t *cmd_table, |
---|
733 | const apr_getopt_option_t *option_table, |
---|
734 | const char *footer, |
---|
735 | apr_pool_t *pool); |
---|
736 | |
---|
737 | #ifdef __cplusplus |
---|
738 | } |
---|
739 | #endif /* __cplusplus */ |
---|
740 | |
---|
741 | #endif /* SVN_OPTS_H */ |
---|