3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief Option and argument parsing for Subversion command lines
31 #include <apr_pools.h>
32 #include <apr_getopt.h>
33 #include <apr_tables.h>
36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
37 #define APR_WANT_STDIO
39 #include <apr_want.h> /* for FILE* */
41 #include "svn_types.h"
45 #endif /* __cplusplus */
50 * All subcommand procedures in Subversion conform to this prototype.
52 * @a os is the apr option state after getopt processing has been run; in
53 * other words, it still contains the non-option arguments following
54 * the subcommand. See @a os->argv and @a os->ind.
56 * @a baton is anything you need it to be.
58 * @a pool is used for allocating errors, and for any other allocation
59 * unless the instance is explicitly documented to allocate from a
62 typedef svn_error_t *(svn_opt_subcommand_t)(
63 apr_getopt_t *os, void *baton, apr_pool_t *pool);
66 /** The maximum number of aliases a subcommand can have. */
67 #define SVN_OPT_MAX_ALIASES 3
69 /** The maximum number of options that can be accepted by a subcommand. */
70 #define SVN_OPT_MAX_OPTIONS 50
72 /** Options that have no short option char should use an identifying
73 * integer equal to or greater than this.
75 #define SVN_OPT_FIRST_LONGOPT_ID 256
78 /** One element of a subcommand dispatch table.
82 typedef struct svn_opt_subcommand_desc2_t
84 /** The full name of this command. */
87 /** The function this command invokes. */
88 svn_opt_subcommand_t *cmd_func;
90 /** A list of alias names for this command (e.g., 'up' for 'update'). */
91 const char *aliases[SVN_OPT_MAX_ALIASES];
93 /** A brief string describing this command, for usage messages. */
96 /** A list of options accepted by this command. Each value in the
97 * array is a unique enum (the 2nd field in apr_getopt_option_t)
99 int valid_options[SVN_OPT_MAX_OPTIONS];
101 /** A list of option help descriptions, keyed by the option unique enum
102 * (the 2nd field in apr_getopt_option_t), which override the generic
103 * descriptions given in an apr_getopt_option_t on a per-subcommand basis.
105 struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS];
106 } svn_opt_subcommand_desc2_t;
109 /** One element of a subcommand dispatch table.
111 * @deprecated Provided for backward compatibility with the 1.3 API.
113 * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides
116 typedef struct svn_opt_subcommand_desc_t
118 /** The full name of this command. */
121 /** The function this command invokes. */
122 svn_opt_subcommand_t *cmd_func;
124 /** A list of alias names for this command (e.g., 'up' for 'update'). */
125 const char *aliases[SVN_OPT_MAX_ALIASES];
127 /** A brief string describing this command, for usage messages. */
130 /** A list of options accepted by this command. Each value in the
131 * array is a unique enum (the 2nd field in apr_getopt_option_t)
133 int valid_options[SVN_OPT_MAX_OPTIONS];
135 } svn_opt_subcommand_desc_t;
139 * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
140 * none. @a cmd_name may be an alias.
144 const svn_opt_subcommand_desc2_t *
145 svn_opt_get_canonical_subcommand2(const svn_opt_subcommand_desc2_t *table,
146 const char *cmd_name);
150 * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
151 * none. @a cmd_name may be an alias.
153 * Same as svn_opt_get_canonical_subcommand2(), but acts on
154 * #svn_opt_subcommand_desc_t.
156 * @deprecated Provided for backward compatibility with the 1.3 API.
159 const svn_opt_subcommand_desc_t *
160 svn_opt_get_canonical_subcommand(const svn_opt_subcommand_desc_t *table,
161 const char *cmd_name);
165 * Return pointer to an @c apr_getopt_option_t for the option whose
166 * option code is @a code, or @c NULL if no match. @a option_table must end
167 * with an element whose every field is zero. If @a command is non-NULL,
168 * then return the subcommand-specific option description instead of the
169 * generic one, if a specific description is defined.
171 * The returned value may be statically allocated, or allocated in @a pool.
175 const apr_getopt_option_t *
176 svn_opt_get_option_from_code2(int code,
177 const apr_getopt_option_t *option_table,
178 const svn_opt_subcommand_desc2_t *command,
183 * Return the first entry from @a option_table whose option code is @a code,
184 * or @c NULL if no match. @a option_table must end with an element whose
185 * every field is zero.
187 * @deprecated Provided for backward compatibility with the 1.3 API.
190 const apr_getopt_option_t *
191 svn_opt_get_option_from_code(int code,
192 const apr_getopt_option_t *option_table);
196 * Return @c TRUE iff subcommand @a command supports option @a
197 * option_code, else return @c FALSE. If @a global_options is
198 * non-NULL, it is a zero-terminated array, and all subcommands take
199 * the options listed in it.
204 svn_opt_subcommand_takes_option3(const svn_opt_subcommand_desc2_t *command,
206 const int *global_options);
209 * Same as svn_opt_subcommand_takes_option3(), but with @c NULL for @a
212 * @deprecated Provided for backward compatibility with the 1.4 API.
216 svn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t *command,
221 * Return @c TRUE iff subcommand @a command supports option @a option_code,
222 * else return @c FALSE.
224 * Same as svn_opt_subcommand_takes_option2(), but acts on
225 * #svn_opt_subcommand_desc_t.
227 * @deprecated Provided for backward compatibility with the 1.3 API.
231 svn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t *command,
236 * Print a generic (not command-specific) usage message to @a stream.
238 * ### @todo Why is @a stream a stdio file instead of an svn stream?
240 * If @a header is non-NULL, print @a header followed by a newline. Then
241 * loop over @a cmd_table printing the usage for each command (getting
242 * option usages from @a opt_table). Then if @a footer is non-NULL, print
243 * @a footer followed by a newline.
245 * Use @a pool for temporary allocation.
250 svn_opt_print_generic_help2(const char *header,
251 const svn_opt_subcommand_desc2_t *cmd_table,
252 const apr_getopt_option_t *opt_table,
259 * Same as svn_opt_print_generic_help2(), but acts on
260 * #svn_opt_subcommand_desc_t.
262 * @deprecated Provided for backward compatibility with the 1.3 API.
266 svn_opt_print_generic_help(const char *header,
267 const svn_opt_subcommand_desc_t *cmd_table,
268 const apr_getopt_option_t *opt_table,
275 * Print an option @a opt nicely into a @a string allocated in @a pool.
276 * If @a doc is set, include the generic documentation string of @a opt,
277 * localized to the current locale if a translation is available.
280 svn_opt_format_option(const char **string,
281 const apr_getopt_option_t *opt,
288 * Get @a subcommand's usage from @a table, and print it to @c stdout.
289 * Obtain option usage from @a options_table. If not @c NULL, @a
290 * global_options is a zero-terminated list of global options. Use @a
291 * pool for temporary allocation. @a subcommand may be a canonical
292 * command name or an alias. ### @todo Why does this only print to
293 * @c stdout, whereas svn_opt_print_generic_help() gives us a choice?
295 * When printing the description of an option, if the same option code
296 * appears a second time in @a options_table with a different name, then
297 * use that second name as an alias for the first name. This additional
298 * behaviour is new in 1.7.
303 svn_opt_subcommand_help3(const char *subcommand,
304 const svn_opt_subcommand_desc2_t *table,
305 const apr_getopt_option_t *options_table,
306 const int *global_options,
310 * Same as svn_opt_subcommand_help3(), but with @a global_options
313 * @deprecated Provided for backward compatibility with the 1.4 API.
317 svn_opt_subcommand_help2(const char *subcommand,
318 const svn_opt_subcommand_desc2_t *table,
319 const apr_getopt_option_t *options_table,
324 * Same as svn_opt_subcommand_help2(), but acts on
325 * #svn_opt_subcommand_desc_t.
327 * @deprecated Provided for backward compatibility with the 1.3 API.
331 svn_opt_subcommand_help(const char *subcommand,
332 const svn_opt_subcommand_desc_t *table,
333 const apr_getopt_option_t *options_table,
338 /* Parsing revision and date options. */
341 * Various ways of specifying revisions.
344 * In contexts where local mods are relevant, the `working' kind
345 * refers to the uncommitted "working" revision, which may be modified
346 * with respect to its base revision. In other contexts, `working'
347 * should behave the same as `committed' or `current'.
349 enum svn_opt_revision_kind {
350 /** No revision information given. */
351 svn_opt_revision_unspecified,
353 /** revision given as number */
354 svn_opt_revision_number,
356 /** revision given as date */
357 svn_opt_revision_date,
359 /** rev of most recent change */
360 svn_opt_revision_committed,
362 /** (rev of most recent change) - 1 */
363 svn_opt_revision_previous,
365 /** .svn/entries current revision */
366 svn_opt_revision_base,
368 /** current, plus local mods */
369 svn_opt_revision_working,
371 /** repository youngest */
372 svn_opt_revision_head
374 /* please update svn_opt__revision_to_string() when extending this enum */
378 * A revision value, which can be specified as a number or a date.
380 * @note This union was formerly an anonymous inline type in
381 * @c svn_opt_revision_t, and was converted to a named type just to
382 * make things easier for SWIG.
386 typedef union svn_opt_revision_value_t
388 /** The revision number */
391 /** the date of the revision */
393 } svn_opt_revision_value_t;
395 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
396 typedef struct svn_opt_revision_t
398 enum svn_opt_revision_kind kind; /**< See svn_opt_revision_kind */
399 svn_opt_revision_value_t value; /**< Extra data qualifying the @c kind */
400 } svn_opt_revision_t;
402 /** A revision range, specified in one of @c svn_opt_revision_kind ways. */
403 typedef struct svn_opt_revision_range_t
405 /** The first revision in the range */
406 svn_opt_revision_t start;
408 /** The last revision in the range */
409 svn_opt_revision_t end;
410 } svn_opt_revision_range_t;
413 * Set @a *start_revision and/or @a *end_revision according to @a arg,
414 * where @a arg is "N" or "N:M", like so:
416 * - If @a arg is "N", set @a *start_revision to represent N, and
417 * leave @a *end_revision untouched.
419 * - If @a arg is "N:M", set @a *start_revision and @a *end_revision
420 * to represent N and M respectively.
422 * N and/or M may be one of the special revision descriptors
423 * recognized by revision_from_word(), or a date in curly braces.
425 * If @a arg is invalid, return -1; else return 0.
426 * It is invalid to omit a revision (as in, ":", "N:" or ":M").
428 * @note It is typical, though not required, for @a *start_revision and
429 * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
431 * Use @a pool for temporary allocations.
434 svn_opt_parse_revision(svn_opt_revision_t *start_revision,
435 svn_opt_revision_t *end_revision,
440 * Parse @a arg, where @a arg is "N" or "N:M", into a
441 * @c svn_opt_revision_range_t and push that onto @a opt_ranges.
443 * - If @a arg is "N", set the @c start field of the
444 * @c svn_opt_revision_range_t to represent N and the @c end field
445 * to @c svn_opt_revision_unspecified.
447 * - If @a arg is "N:M", set the @c start field of the
448 * @c svn_opt_revision_range_t to represent N and the @c end field
451 * If @a arg is invalid, return -1; else return 0. It is invalid to omit
452 * a revision (as in, ":", "N:" or ":M").
454 * Use @a pool to allocate @c svn_opt_revision_range_t pushed to the array.
459 svn_opt_parse_revision_to_range(apr_array_header_t *opt_ranges,
464 * Resolve peg revisions and operational revisions in the following way:
466 * - If @a is_url is set and @a peg_rev->kind is
467 * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to
468 * @c svn_opt_revision_head.
470 * - If @a is_url is not set, and @a peg_rev->kind is
471 * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to
472 * @c svn_opt_revision_base.
474 * - If @a op_rev->kind is @c svn_opt_revision_unspecified, @a op_rev
475 * defaults to @a peg_rev.
477 * Both @a peg_rev and @a op_rev may be modified as a result of this
478 * function. @a is_url should be set if the path the revisions refer to is
479 * a url, and unset otherwise.
481 * If @a notice_local_mods is set, @c svn_opt_revision_working is used,
482 * instead of @c svn_opt_revision_base.
484 * Use @a pool for allocations.
489 svn_opt_resolve_revisions(svn_opt_revision_t *peg_rev,
490 svn_opt_revision_t *op_rev,
491 svn_boolean_t is_url,
492 svn_boolean_t notice_local_mods,
496 /* Parsing arguments. */
499 * Pull remaining target arguments from @a os into @a *targets_p,
500 * converting them to UTF-8, followed by targets from @a known_targets
501 * (which might come from, for example, the "--targets" command line
502 * option), which are already in UTF-8.
504 * On each URL target, do some IRI-to-URI encoding and some
505 * auto-escaping. On each local path, canonicalize case and path
508 * Allocate @a *targets_p and its elements in @a pool.
510 * If a path has the same name as a Subversion working copy
511 * administrative directory, return SVN_ERR_RESERVED_FILENAME_SPECIFIED;
512 * if multiple reserved paths are encountered, return a chain of
513 * errors, all of which are SVN_ERR_RESERVED_FILENAME_SPECIFIED. Do
514 * not return this type of error in a chain with any other type of
515 * error, and if this is the only type of error encountered, complete
516 * the operation before returning the error(s).
518 * @deprecated Provided for backward compatibility with the 1.5 API.
519 * @see svn_client_args_to_target_array()
523 svn_opt_args_to_target_array3(apr_array_header_t **targets_p,
525 const apr_array_header_t *known_targets,
529 * This is the same as svn_opt_args_to_target_array3() except that it
530 * silently ignores paths that have the same name as a working copy
531 * administrative directory.
535 * @deprecated Provided for backward compatibility with the 1.4 API.
539 svn_opt_args_to_target_array2(apr_array_header_t **targets_p,
541 const apr_array_header_t *known_targets,
546 * The same as svn_opt_args_to_target_array2() except that, in
547 * addition, if @a extract_revisions is set, then look for trailing
548 * "@rev" syntax on the first two paths. If the first target in @a
549 * *targets_p ends in "@rev", replace it with a canonicalized version of
550 * the part before "@rev" and replace @a *start_revision with the value
551 * of "rev". If the second target in @a *targets_p ends in "@rev",
552 * replace it with a canonicalized version of the part before "@rev"
553 * and replace @a *end_revision with the value of "rev". Ignore
554 * revision specifiers on any further paths. "rev" can be any form of
555 * single revision specifier, as accepted by svn_opt_parse_revision().
557 * @deprecated Provided for backward compatibility with the 1.1 API.
561 svn_opt_args_to_target_array(apr_array_header_t **targets_p,
563 const apr_array_header_t *known_targets,
564 svn_opt_revision_t *start_revision,
565 svn_opt_revision_t *end_revision,
566 svn_boolean_t extract_revisions,
571 * Parse revprop key/value pair from @a revprop_spec (name[=value]) into
572 * @a revprops, making copies of both with @a pool. If @a revprops is
573 * @c NULL, allocate a new apr_hash_t in it. @a revprops maps
574 * const char * revprop names to svn_string_t * revprop values for use
575 * with svn_repos_get_commit_editor5 and other get_commit_editor APIs.
580 svn_opt_parse_revprop(apr_hash_t **revprops, const char *revprop_spec,
585 * If no targets exist in @a *targets, add `.' as the lone target.
587 * (Some commands take an implicit "." string argument when invoked
588 * with no arguments. Those commands make use of this function to
589 * add "." to the target array if the user passes no args.)
592 svn_opt_push_implicit_dot_target(apr_array_header_t *targets,
597 * Parse @a num_args non-target arguments from the list of arguments in
598 * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without
599 * doing any UTF-8 conversion. Allocate @a *args_p and its values in @a pool.
602 svn_opt_parse_num_args(apr_array_header_t **args_p,
609 * Parse all remaining arguments from @a os->argv, return them as
610 * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
611 * Allocate @a *args_p and its values in @a pool.
614 svn_opt_parse_all_args(apr_array_header_t **args_p,
619 * Parse a working-copy path or URL in @a path, extracting any trailing
620 * revision specifier of the form "@rev" from the last component of
623 * Some examples would be:
625 * - "foo/bar" -> "foo/bar", (unspecified)
626 * - "foo/bar@13" -> "foo/bar", (number, 13)
627 * - "foo/bar@HEAD" -> "foo/bar", (head)
628 * - "foo/bar@{1999-12-31}" -> "foo/bar", (date, 1999-12-31)
629 * - "http://a/b@27" -> "http://a/b", (number, 27)
630 * - "http://a/b@COMMITTED" -> "http://a/b", (committed) [*]
631 * - "http://a/b@{1999-12-31}" -> "http://a/b", (date, 1999-12-31)
632 * - "http://a/b@%7B1999-12-31%7D" -> "http://a/b", (date, 1999-12-31)
633 * - "foo/bar@1:2" -> error
634 * - "foo/bar@baz" -> error
635 * - "foo/bar@" -> "foo/bar", (unspecified)
636 * - "foo/@bar@" -> "foo/@bar", (unspecified)
637 * - "foo/bar/@13" -> "foo/bar/", (number, 13)
638 * - "foo/bar@@13" -> "foo/bar@", (number, 13)
639 * - "foo/@bar@HEAD" -> "foo/@bar", (head)
640 * - "foo@/bar" -> "foo@/bar", (unspecified)
641 * - "foo@HEAD/bar" -> "foo@HEAD/bar", (unspecified)
642 * - "@foo/bar" -> "@foo/bar", (unspecified)
643 * - "@foo/bar@" -> "@foo/bar", (unspecified)
645 * [*] Syntactically valid but probably not semantically useful.
647 * If a trailing revision specifier is found, parse it into @a *rev and
648 * put the rest of the path into @a *truepath, allocating from @a pool;
649 * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR (with the effect on
650 * @a *truepath undefined) if the revision specifier is invalid.
651 * If no trailing revision specifier is found, set @a *truepath to
652 * @a path and @a rev->kind to @c svn_opt_revision_unspecified.
654 * This function does not require that @a path be in canonical form.
655 * No canonicalization is done and @a *truepath will only be in
656 * canonical form if @a path is in canonical form.
661 svn_opt_parse_path(svn_opt_revision_t *rev,
662 const char **truepath,
667 * Central dispatcher function for various kinds of help message.
669 * * subcommand-specific help (svn_opt_subcommand_help)
670 * * generic help (svn_opt_print_generic_help)
672 * * simple usage complaint: "Type '@a pgm_name help' for usage."
674 * If @a os is not @c NULL and it contains arguments, then try
675 * printing help for them as though they are subcommands, using @a
676 * cmd_table and @a option_table for option information. If not @c
677 * NULL, @a global_options is a zero-terminated array of options taken
678 * by all subcommands.
680 * Else, if @a print_version is TRUE, then print version info, in
681 * brief form if @a quiet is also TRUE; if @a quiet is FALSE, then if
682 * @a version_footer is non-NULL, print it following the version
683 * information. If @a verbose is TRUE, also print information about
684 * the running system and loaded shared libraries, where available.
686 * Else, if @a os is not @c NULL and does not contain arguments, print
687 * generic help, via svn_opt_print_generic_help2() with the @a header,
688 * @a cmd_table, @a option_table, and @a footer arguments.
690 * Else, when @a os is @c NULL, print the simple usage complaint.
692 * Use @a pool for temporary allocations.
694 * Notes: The reason this function handles both version printing and
695 * general usage help is that a confused user might put both the
696 * --version flag *and* subcommand arguments on a help command line.
697 * The logic for handling such a situation should be in one place.
703 svn_opt_print_help4(apr_getopt_t *os,
704 const char *pgm_name,
705 svn_boolean_t print_version,
707 svn_boolean_t verbose,
708 const char *version_footer,
710 const svn_opt_subcommand_desc2_t *cmd_table,
711 const apr_getopt_option_t *option_table,
712 const int *global_options,
717 * Same as svn_opt_print_help4(), but with @a verbose always @c FALSE.
719 * @deprecated Provided for backward compatibility with the 1.7 API.
724 svn_opt_print_help3(apr_getopt_t *os,
725 const char *pgm_name,
726 svn_boolean_t print_version,
728 const char *version_footer,
730 const svn_opt_subcommand_desc2_t *cmd_table,
731 const apr_getopt_option_t *option_table,
732 const int *global_options,
737 * Same as svn_opt_print_help3(), but with @a global_options always @c
740 * @deprecated Provided for backward compatibility with the 1.4 API.
745 svn_opt_print_help2(apr_getopt_t *os,
746 const char *pgm_name,
747 svn_boolean_t print_version,
749 const char *version_footer,
751 const svn_opt_subcommand_desc2_t *cmd_table,
752 const apr_getopt_option_t *option_table,
758 * Same as svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t.
760 * @deprecated Provided for backward compatibility with the 1.3 API.
764 svn_opt_print_help(apr_getopt_t *os,
765 const char *pgm_name,
766 svn_boolean_t print_version,
768 const char *version_footer,
770 const svn_opt_subcommand_desc_t *cmd_table,
771 const apr_getopt_option_t *option_table,
777 #endif /* __cplusplus */
779 #endif /* SVN_OPTS_H */