3 * ====================================================================
4 * Copyright (c) 2000-2008 CollabNet. All rights reserved.
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.
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 * ====================================================================
19 * @brief Option and argument parsing for Subversion command lines
26 #include <apr_pools.h>
27 #include <apr_getopt.h>
28 #include <apr_tables.h>
31 #ifndef DOXYGEN_SHOULD_SKIP_THIS
32 #define APR_WANT_STDIO
34 #include <apr_want.h> /* for FILE* */
36 #include "svn_types.h"
40 #endif /* __cplusplus */
45 * All subcommand procedures in Subversion conform to this prototype.
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.
51 * @a baton is anything you need it to be.
53 * @a pool is used for allocating errors, and for any other allocation
54 * unless the instance is explicitly documented to allocate from a
57 typedef svn_error_t
*(svn_opt_subcommand_t
)
58 (apr_getopt_t
*os
, void *baton
, apr_pool_t
*pool
);
61 /** The maximum number of aliases a subcommand can have. */
62 #define SVN_OPT_MAX_ALIASES 3
64 /** The maximum number of options that can be accepted by a subcommand. */
65 #define SVN_OPT_MAX_OPTIONS 50
67 /** Options that have no short option char should use an identifying
68 * integer equal to or greater than this.
70 #define SVN_OPT_FIRST_LONGOPT_ID 256
73 /** One element of a subcommand dispatch table.
77 typedef struct svn_opt_subcommand_desc2_t
79 /** The full name of this command. */
82 /** The function this command invokes. */
83 svn_opt_subcommand_t
*cmd_func
;
85 /** A list of alias names for this command (e.g., 'up' for 'update'). */
86 const char *aliases
[SVN_OPT_MAX_ALIASES
];
88 /** A brief string describing this command, for usage messages. */
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)
94 int valid_options
[SVN_OPT_MAX_OPTIONS
];
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.
100 struct { int optch
; const char *desc
; } desc_overrides
[SVN_OPT_MAX_OPTIONS
];
101 } svn_opt_subcommand_desc2_t
;
104 /** One element of a subcommand dispatch table.
106 * @deprecated Provided for backward compatibility with the 1.3 API.
108 * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides
111 typedef struct svn_opt_subcommand_desc_t
113 /** The full name of this command. */
116 /** The function this command invokes. */
117 svn_opt_subcommand_t
*cmd_func
;
119 /** A list of alias names for this command (e.g., 'up' for 'update'). */
120 const char *aliases
[SVN_OPT_MAX_ALIASES
];
122 /** A brief string describing this command, for usage messages. */
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)
128 int valid_options
[SVN_OPT_MAX_OPTIONS
];
130 } svn_opt_subcommand_desc_t
;
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.
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
);
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.
148 * Same as svn_opt_get_canonical_subcommand2(), but acts on
149 * #svn_opt_subcommand_desc_t.
151 * @deprecated Provided for backward compatibility with the 1.3 API.
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
);
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.
166 * The returned value may be statically allocated, or allocated in @a pool.
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
,
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.
182 * @deprecated Provided for backward compatibility with the 1.3 API.
185 const apr_getopt_option_t
*
186 svn_opt_get_option_from_code(int code
,
187 const apr_getopt_option_t
*option_table
);
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.
199 svn_opt_subcommand_takes_option3(const svn_opt_subcommand_desc2_t
*command
,
201 const int *global_options
);
204 * Same as svn_opt_subcommand_takes_option3(), but with @c NULL for @a
207 * @deprecated Provided for backward compatibility with the 1.4 API.
211 svn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t
*command
,
216 * Return @c TRUE iff subcommand @a command supports option @a option_code,
217 * else return @c FALSE.
219 * Same as svn_opt_subcommand_takes_option2(), but acts on
220 * #svn_opt_subcommand_desc_t.
222 * @deprecated Provided for backward compatibility with the 1.3 API.
226 svn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t
*command
,
231 * Print a generic (not command-specific) usage message to @a stream.
233 * ### @todo Why is @a stream a stdio file instead of an svn stream?
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.
240 * Use @a pool for temporary allocation.
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
,
254 * Same as svn_opt_print_generic_help2(), but acts on
255 * #svn_opt_subcommand_desc_t.
257 * @deprecated Provided for backward compatibility with the 1.3 API.
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
,
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.
275 svn_opt_format_option(const char **string
,
276 const apr_getopt_option_t
*opt
,
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?
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
,
300 * Same as svn_opt_subcommand_help3(), but with @a global_options
303 * @deprecated Provided for backward compatibility with the 1.4 API.
307 svn_opt_subcommand_help2(const char *subcommand
,
308 const svn_opt_subcommand_desc2_t
*table
,
309 const apr_getopt_option_t
*options_table
,
314 * Same as svn_opt_subcommand_help2(), but acts on
315 * #svn_opt_subcommand_desc_t.
317 * @deprecated Provided for backward compatibility with the 1.3 API.
321 svn_opt_subcommand_help(const char *subcommand
,
322 const svn_opt_subcommand_desc_t
*table
,
323 const apr_getopt_option_t
*options_table
,
328 /* Parsing revision and date options. */
331 * Various ways of specifying revisions.
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'.
339 enum svn_opt_revision_kind
{
340 /** No revision information given. */
341 svn_opt_revision_unspecified
,
343 /** revision given as number */
344 svn_opt_revision_number
,
346 /** revision given as date */
347 svn_opt_revision_date
,
349 /** rev of most recent change */
350 svn_opt_revision_committed
,
352 /** (rev of most recent change) - 1 */
353 svn_opt_revision_previous
,
355 /** .svn/entries current revision */
356 svn_opt_revision_base
,
358 /** current, plus local mods */
359 svn_opt_revision_working
,
361 /** repository youngest */
362 svn_opt_revision_head
366 * A revision value, which can be specified as a number or a date.
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.
374 typedef union svn_opt_revision_value_t
376 /** The revision number */
379 /** the date of the revision */
381 } svn_opt_revision_value_t
;
383 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
384 typedef struct svn_opt_revision_t
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
;
390 /** A revision range, specified in one of @c svn_opt_revision_kind ways. */
391 typedef struct svn_opt_revision_range_t
393 /** The first revision in the range */
394 svn_opt_revision_t start
;
396 /** The last revision in the range */
397 svn_opt_revision_t end
;
398 } svn_opt_revision_range_t
;
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:
404 * - If @a arg is "N", set @a *start_revision to represent N, and
405 * leave @a *end_revision untouched.
407 * - If @a arg is "N:M", set @a *start_revision and @a *end_revision
408 * to represent N and M respectively.
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.
413 * If @a arg is invalid, return -1; else return 0.
414 * It is invalid to omit a revision (as in, ":", "N:" or ":M").
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.
419 * Use @a pool for temporary allocations.
422 svn_opt_parse_revision(svn_opt_revision_t
*start_revision
,
423 svn_opt_revision_t
*end_revision
,
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.
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.
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
439 * If @a arg is invalid, return -1; else return 0. It is invalid to omit
440 * a revision (as in, ":", "N:" or ":M").
442 * Use @a pool to allocate @c svn_opt_revision_range_t pushed to the array.
447 svn_opt_parse_revision_to_range(apr_array_header_t
*opt_ranges
,
452 * Resolve peg revisions and operational revisions in the following way:
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.
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.
462 * - If @a op_rev->kind is @c svn_opt_revision_unspecified, @a op_rev
463 * defaults to @a peg_rev.
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.
469 * If @a notice_local_mods is set, @c svn_opt_revision_working is used,
470 * instead of @c svn_opt_revision_base.
472 * Use @a pool for allocations.
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
,
484 /* Parsing arguments. */
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.
492 * On each URL target, do some IRI-to-URI encoding and some
493 * auto-escaping. On each local path, canonicalize case and path
496 * Allocate @a *targets_p and its elements in @a pool.
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).
506 * @deprecated Provided for backward compatibility with the 1.5 API.
507 * @see svn_client_args_to_target_array()
511 svn_opt_args_to_target_array3(apr_array_header_t
**targets_p
,
513 apr_array_header_t
*known_targets
,
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.
523 * @deprecated Provided for backward compatibility with the 1.4 API.
527 svn_opt_args_to_target_array2(apr_array_header_t
**targets_p
,
529 apr_array_header_t
*known_targets
,
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().
545 * @deprecated Provided for backward compatibility with the 1.1 API.
549 svn_opt_args_to_target_array(apr_array_header_t
**targets_p
,
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
,
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.
568 svn_opt_parse_revprop(apr_hash_t
**revprops
, const char *revprop_spec
,
573 * If no targets exist in @a *targets, add `.' as the lone target.
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.)
580 svn_opt_push_implicit_dot_target(apr_array_header_t
*targets
,
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.
590 svn_opt_parse_num_args(apr_array_header_t
**args_p
,
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.
602 svn_opt_parse_all_args(apr_array_header_t
**args_p
,
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
611 * Some examples would be:
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)
630 * [*] Syntactically valid but probably not semantically useful.
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.
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.
646 svn_opt_parse_path(svn_opt_revision_t
*rev
,
647 const char **truepath
,
652 * Central dispatcher function for various kinds of help message.
654 * * subcommand-specific help (svn_opt_subcommand_help)
655 * * generic help (svn_opt_print_generic_help)
657 * * simple usage complaint: "Type '@a pgm_name help' for usage."
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.
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
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.
674 * Else, when @a os is @c NULL, print the simple usage complaint.
676 * Use @a pool for temporary allocations.
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.
686 svn_opt_print_help3(apr_getopt_t
*os
,
687 const char *pgm_name
,
688 svn_boolean_t print_version
,
690 const char *version_footer
,
692 const svn_opt_subcommand_desc2_t
*cmd_table
,
693 const apr_getopt_option_t
*option_table
,
694 const int *global_options
,
699 * Same as svn_opt_print_help3(), but with @a global_options always @c
702 * @deprecated Provided for backward compatibility with the 1.4 API.
707 svn_opt_print_help2(apr_getopt_t
*os
,
708 const char *pgm_name
,
709 svn_boolean_t print_version
,
711 const char *version_footer
,
713 const svn_opt_subcommand_desc2_t
*cmd_table
,
714 const apr_getopt_option_t
*option_table
,
720 * Same as svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t.
722 * @deprecated Provided for backward compatibility with the 1.3 API.
726 svn_opt_print_help(apr_getopt_t
*os
,
727 const char *pgm_name
,
728 svn_boolean_t print_version
,
730 const char *version_footer
,
732 const svn_opt_subcommand_desc_t
*cmd_table
,
733 const apr_getopt_option_t
*option_table
,
739 #endif /* __cplusplus */
741 #endif /* SVN_OPTS_H */