contrib/subversion/subversion/include/svn_opt.h

   1 /**
   2  * @copyright
   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
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  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
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_opt.h
  24  * @brief Option and argument parsing for Subversion command lines
  25  */
  26
  27 #ifndef SVN_OPTS_H
  28 #define SVN_OPTS_H
  29
  30 #include <apr.h>
  31 #include <apr_pools.h>
  32 #include <apr_getopt.h>
  33 #include <apr_tables.h>
  34 #include <apr_hash.h>
  35
  36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  37 #define APR_WANT_STDIO
  38 #endif
  39 #include <apr_want.h>   /* for FILE* */
  40
  41 #include "svn_types.h"
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif /* __cplusplus */
  46
  47
  48 \f
  49 /**
  50  * All subcommand procedures in Subversion conform to this prototype.
  51  *
  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.
  55  *
  56  * @a baton is anything you need it to be.
  57  *
  58  * @a pool is used for allocating errors, and for any other allocation
  59  * unless the instance is explicitly documented to allocate from a
  60  * pool in @a baton.
  61  */
  62 typedef svn_error_t *(svn_opt_subcommand_t)(
  63   apr_getopt_t *os, void *baton, apr_pool_t *pool);
  64
  65
  66 /** The maximum number of aliases a subcommand can have. */
  67 #define SVN_OPT_MAX_ALIASES 3
  68
  69 /** The maximum number of options that can be accepted by a subcommand. */
  70 #define SVN_OPT_MAX_OPTIONS 50
  71
  72 /** Options that have no short option char should use an identifying
  73  * integer equal to or greater than this.
  74  */
  75 #define SVN_OPT_FIRST_LONGOPT_ID 256
  76
  77
  78 /** One element of a subcommand dispatch table.
  79  *
  80  * @since New in 1.4.
  81  */
  82 typedef struct svn_opt_subcommand_desc2_t
  83 {
  84   /** The full name of this command. */
  85   const char *name;
  86
  87   /** The function this command invokes. */
  88   svn_opt_subcommand_t *cmd_func;
  89
  90   /** A list of alias names for this command (e.g., 'up' for 'update'). */
  91   const char *aliases[SVN_OPT_MAX_ALIASES];
  92
  93   /** A brief string describing this command, for usage messages. */
  94   const char *help;
  95
  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)
  98    */
  99   int valid_options[SVN_OPT_MAX_OPTIONS];
 100
 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.
 104    */
 105   struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS];
 106 } svn_opt_subcommand_desc2_t;
 107
 108
 109 /** One element of a subcommand dispatch table.
 110  *
 111  * @deprecated Provided for backward compatibility with the 1.3 API.
 112  *
 113  * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides
 114  * member.
 115  */
 116 typedef struct svn_opt_subcommand_desc_t
 117 {
 118   /** The full name of this command. */
 119   const char *name;
 120
 121   /** The function this command invokes. */
 122   svn_opt_subcommand_t *cmd_func;
 123
 124   /** A list of alias names for this command (e.g., 'up' for 'update'). */
 125   const char *aliases[SVN_OPT_MAX_ALIASES];
 126
 127   /** A brief string describing this command, for usage messages. */
 128   const char *help;
 129
 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)
 132    */
 133   int valid_options[SVN_OPT_MAX_OPTIONS];
 134
 135 } svn_opt_subcommand_desc_t;
 136
 137
 138 /**
 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.
 141  *
 142  * @since New in 1.4.
 143  */
 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);
 147
 148
 149 /**
 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.
 152  *
 153  * Same as svn_opt_get_canonical_subcommand2(), but acts on
 154  * #svn_opt_subcommand_desc_t.
 155  *
 156  * @deprecated Provided for backward compatibility with the 1.3 API.
 157  */
 158 SVN_DEPRECATED
 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);
 162
 163
 164 /**
 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.
 170  *
 171  * The returned value may be statically allocated, or allocated in @a pool.
 172  *
 173  * @since New in 1.4.
 174  */
 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,
 179                               apr_pool_t *pool);
 180
 181
 182 /**
 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.
 186  *
 187  * @deprecated Provided for backward compatibility with the 1.3 API.
 188  */
 189 SVN_DEPRECATED
 190 const apr_getopt_option_t *
 191 svn_opt_get_option_from_code(int code,
 192                              const apr_getopt_option_t *option_table);
 193
 194
 195 /**
 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.
 200  *
 201  * @since New in 1.5.
 202  */
 203 svn_boolean_t
 204 svn_opt_subcommand_takes_option3(const svn_opt_subcommand_desc2_t *command,
 205                                  int option_code,
 206                                  const int *global_options);
 207
 208 /**
 209  * Same as svn_opt_subcommand_takes_option3(), but with @c NULL for @a
 210  * global_options.
 211  *
 212  * @deprecated Provided for backward compatibility with the 1.4 API.
 213  */
 214 SVN_DEPRECATED
 215 svn_boolean_t
 216 svn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t *command,
 217                                  int option_code);
 218
 219
 220 /**
 221  * Return @c TRUE iff subcommand @a command supports option @a option_code,
 222  * else return @c FALSE.
 223  *
 224  * Same as svn_opt_subcommand_takes_option2(), but acts on
 225  * #svn_opt_subcommand_desc_t.
 226  *
 227  * @deprecated Provided for backward compatibility with the 1.3 API.
 228  */
 229 SVN_DEPRECATED
 230 svn_boolean_t
 231 svn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t *command,
 232                                 int option_code);
 233
 234
 235 /**
 236  * Print a generic (not command-specific) usage message to @a stream.
 237  *
 238  * ### @todo Why is @a stream a stdio file instead of an svn stream?
 239  *
 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.
 244  *
 245  * Use @a pool for temporary allocation.
 246  *
 247  * @since New in 1.4.
 248  */
 249 void
 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,
 253                             const char *footer,
 254                             apr_pool_t *pool,
 255                             FILE *stream);
 256
 257
 258 /**
 259  * Same as svn_opt_print_generic_help2(), but acts on
 260  * #svn_opt_subcommand_desc_t.
 261  *
 262  * @deprecated Provided for backward compatibility with the 1.3 API.
 263  */
 264 SVN_DEPRECATED
 265 void
 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,
 269                            const char *footer,
 270                            apr_pool_t *pool,
 271                            FILE *stream);
 272
 273
 274 /**
 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.
 278  */
 279 void
 280 svn_opt_format_option(const char **string,
 281                       const apr_getopt_option_t *opt,
 282                       svn_boolean_t doc,
 283                       apr_pool_t *pool);
 284
 285
 286
 287 /**
 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?
 294  *
 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.
 299  *
 300  * @since New in 1.5.
 301  */
 302 void
 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,
 307                          apr_pool_t *pool);
 308
 309 /**
 310  * Same as svn_opt_subcommand_help3(), but with @a global_options
 311  * always NULL.
 312  *
 313  * @deprecated Provided for backward compatibility with the 1.4 API.
 314  */
 315 SVN_DEPRECATED
 316 void
 317 svn_opt_subcommand_help2(const char *subcommand,
 318                          const svn_opt_subcommand_desc2_t *table,
 319                          const apr_getopt_option_t *options_table,
 320                          apr_pool_t *pool);
 321
 322
 323 /**
 324  * Same as svn_opt_subcommand_help2(), but acts on
 325  * #svn_opt_subcommand_desc_t.
 326  *
 327  * @deprecated Provided for backward compatibility with the 1.3 API.
 328  */
 329 SVN_DEPRECATED
 330 void
 331 svn_opt_subcommand_help(const char *subcommand,
 332                         const svn_opt_subcommand_desc_t *table,
 333                         const apr_getopt_option_t *options_table,
 334                         apr_pool_t *pool);
 335
 336
 337 \f
 338 /* Parsing revision and date options. */
 339
 340 /**
 341  * Various ways of specifying revisions.
 342  *
 343  * @note
 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'.
 348  */
 349 enum svn_opt_revision_kind {
 350   /** No revision information given. */
 351   svn_opt_revision_unspecified,
 352
 353   /** revision given as number */
 354   svn_opt_revision_number,
 355
 356   /** revision given as date */
 357   svn_opt_revision_date,
 358
 359   /** rev of most recent change */
 360   svn_opt_revision_committed,
 361
 362   /** (rev of most recent change) - 1 */
 363   svn_opt_revision_previous,
 364
 365   /** .svn/entries current revision */
 366   svn_opt_revision_base,
 367
 368   /** current, plus local mods */
 369   svn_opt_revision_working,
 370
 371   /** repository youngest */
 372   svn_opt_revision_head
 373
 374   /* please update svn_opt__revision_to_string() when extending this enum */
 375 };
 376
 377 /**
 378  * A revision value, which can be specified as a number or a date.
 379  *
 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.
 383  *
 384  * @since New in 1.3.
 385  */
 386 typedef union svn_opt_revision_value_t
 387 {
 388   /** The revision number */
 389   svn_revnum_t number;
 390
 391   /** the date of the revision */
 392   apr_time_t date;
 393 } svn_opt_revision_value_t;
 394
 395 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
 396 typedef struct svn_opt_revision_t
 397 {
 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;
 401
 402 /** A revision range, specified in one of @c svn_opt_revision_kind ways. */
 403 typedef struct svn_opt_revision_range_t
 404 {
 405   /** The first revision in the range */
 406   svn_opt_revision_t start;
 407
 408   /** The last revision in the range */
 409   svn_opt_revision_t end;
 410 } svn_opt_revision_range_t;
 411
 412 /**
 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:
 415  *
 416  *    - If @a arg is "N", set @a *start_revision to represent N, and
 417  *      leave @a *end_revision untouched.
 418  *
 419  *    - If @a arg is "N:M", set @a *start_revision and @a *end_revision
 420  *      to represent N and M respectively.
 421  *
 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.
 424  *
 425  * If @a arg is invalid, return -1; else return 0.
 426  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
 427  *
 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.
 430  *
 431  * Use @a pool for temporary allocations.
 432  */
 433 int
 434 svn_opt_parse_revision(svn_opt_revision_t *start_revision,
 435                        svn_opt_revision_t *end_revision,
 436                        const char *arg,
 437                        apr_pool_t *pool);
 438
 439 /**
 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.
 442  *
 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.
 446  *
 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
 449  *      to represent M.
 450  *
 451  * If @a arg is invalid, return -1; else return 0.  It is invalid to omit
 452  * a revision (as in, ":", "N:" or ":M").
 453  *
 454  * Use @a pool to allocate @c svn_opt_revision_range_t pushed to the array.
 455  *
 456  * @since New in 1.5.
 457  */
 458 int
 459 svn_opt_parse_revision_to_range(apr_array_header_t *opt_ranges,
 460                                 const char *arg,
 461                                 apr_pool_t *pool);
 462
 463 /**
 464  * Resolve peg revisions and operational revisions in the following way:
 465  *
 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.
 469  *
 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.
 473  *
 474  *    - If @a op_rev->kind is @c svn_opt_revision_unspecified, @a op_rev
 475  *      defaults to @a peg_rev.
 476  *
 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.
 480  *
 481  * If @a notice_local_mods is set, @c svn_opt_revision_working is used,
 482  * instead of @c svn_opt_revision_base.
 483  *
 484  * Use @a pool for allocations.
 485  *
 486  * @since New in 1.5.
 487  */
 488 svn_error_t *
 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,
 493                           apr_pool_t *pool);
 494
 495 \f
 496 /* Parsing arguments. */
 497
 498 /**
 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.
 503  *
 504  * On each URL target, do some IRI-to-URI encoding and some
 505  * auto-escaping.  On each local path, canonicalize case and path
 506  * separators.
 507  *
 508  * Allocate @a *targets_p and its elements in @a pool.
 509  *
 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).
 517  *
 518  * @deprecated Provided for backward compatibility with the 1.5 API.
 519  * @see svn_client_args_to_target_array()
 520  */
 521 SVN_DEPRECATED
 522 svn_error_t *
 523 svn_opt_args_to_target_array3(apr_array_header_t **targets_p,
 524                               apr_getopt_t *os,
 525                               const apr_array_header_t *known_targets,
 526                               apr_pool_t *pool);
 527
 528 /**
 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.
 532  *
 533  * @since New in 1.2.
 534  *
 535  * @deprecated Provided for backward compatibility with the 1.4 API.
 536  */
 537 SVN_DEPRECATED
 538 svn_error_t *
 539 svn_opt_args_to_target_array2(apr_array_header_t **targets_p,
 540                               apr_getopt_t *os,
 541                               const apr_array_header_t *known_targets,
 542                               apr_pool_t *pool);
 543
 544
 545 /**
 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().
 556  *
 557  * @deprecated Provided for backward compatibility with the 1.1 API.
 558  */
 559 SVN_DEPRECATED
 560 svn_error_t *
 561 svn_opt_args_to_target_array(apr_array_header_t **targets_p,
 562                              apr_getopt_t *os,
 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,
 567                              apr_pool_t *pool);
 568
 569
 570 /**
 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.
 576  *
 577  * @since New in 1.6.
 578  */
 579 svn_error_t *
 580 svn_opt_parse_revprop(apr_hash_t **revprops, const char *revprop_spec,
 581                       apr_pool_t *pool);
 582
 583
 584 /**
 585  * If no targets exist in @a *targets, add `.' as the lone target.
 586  *
 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.)
 590  */
 591 void
 592 svn_opt_push_implicit_dot_target(apr_array_header_t *targets,
 593                                  apr_pool_t *pool);
 594
 595
 596 /**
 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.
 600  */
 601 svn_error_t *
 602 svn_opt_parse_num_args(apr_array_header_t **args_p,
 603                        apr_getopt_t *os,
 604                        int num_args,
 605                        apr_pool_t *pool);
 606
 607
 608 /**
 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.
 612  */
 613 svn_error_t *
 614 svn_opt_parse_all_args(apr_array_header_t **args_p,
 615                        apr_getopt_t *os,
 616                        apr_pool_t *pool);
 617
 618 /**
 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
 621  * the path.
 622  *
 623  * Some examples would be:
 624  *
 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)
 644  *
 645  *   [*] Syntactically valid but probably not semantically useful.
 646  *
 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.
 653  *
 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.
 657  *
 658  * @since New in 1.1.
 659  */
 660 svn_error_t *
 661 svn_opt_parse_path(svn_opt_revision_t *rev,
 662                    const char **truepath,
 663                    const char *path,
 664                    apr_pool_t *pool);
 665
 666 /**
 667  * Central dispatcher function for various kinds of help message.
 668  * Prints one of:
 669  *   * subcommand-specific help (svn_opt_subcommand_help)
 670  *   * generic help (svn_opt_print_generic_help)
 671  *   * version info
 672  *   * simple usage complaint: "Type '@a pgm_name help' for usage."
 673  *
 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.
 679  *
 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.
 685  *
 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.
 689  *
 690  * Else, when @a os is @c NULL, print the simple usage complaint.
 691  *
 692  * Use @a pool for temporary allocations.
 693  *
 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.
 698  *
 699  * @since New in 1.8.
 700  */
 701
 702 svn_error_t *
 703 svn_opt_print_help4(apr_getopt_t *os,
 704                     const char *pgm_name,
 705                     svn_boolean_t print_version,
 706                     svn_boolean_t quiet,
 707                     svn_boolean_t verbose,
 708                     const char *version_footer,
 709                     const char *header,
 710                     const svn_opt_subcommand_desc2_t *cmd_table,
 711                     const apr_getopt_option_t *option_table,
 712                     const int *global_options,
 713                     const char *footer,
 714                     apr_pool_t *pool);
 715
 716 /**
 717  * Same as svn_opt_print_help4(), but with @a verbose always @c FALSE.
 718  *
 719  * @deprecated Provided for backward compatibility with the 1.7 API.
 720  */
 721
 722 SVN_DEPRECATED
 723 svn_error_t *
 724 svn_opt_print_help3(apr_getopt_t *os,
 725                     const char *pgm_name,
 726                     svn_boolean_t print_version,
 727                     svn_boolean_t quiet,
 728                     const char *version_footer,
 729                     const char *header,
 730                     const svn_opt_subcommand_desc2_t *cmd_table,
 731                     const apr_getopt_option_t *option_table,
 732                     const int *global_options,
 733                     const char *footer,
 734                     apr_pool_t *pool);
 735
 736 /**
 737  * Same as svn_opt_print_help3(), but with @a global_options always @c
 738  * NULL.
 739  *
 740  * @deprecated Provided for backward compatibility with the 1.4 API.
 741  */
 742
 743 SVN_DEPRECATED
 744 svn_error_t *
 745 svn_opt_print_help2(apr_getopt_t *os,
 746                     const char *pgm_name,
 747                     svn_boolean_t print_version,
 748                     svn_boolean_t quiet,
 749                     const char *version_footer,
 750                     const char *header,
 751                     const svn_opt_subcommand_desc2_t *cmd_table,
 752                     const apr_getopt_option_t *option_table,
 753                     const char *footer,
 754                     apr_pool_t *pool);
 755
 756
 757 /**
 758  * Same as svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t.
 759  *
 760  * @deprecated Provided for backward compatibility with the 1.3 API.
 761  */
 762 SVN_DEPRECATED
 763 svn_error_t *
 764 svn_opt_print_help(apr_getopt_t *os,
 765                    const char *pgm_name,
 766                    svn_boolean_t print_version,
 767                    svn_boolean_t quiet,
 768                    const char *version_footer,
 769                    const char *header,
 770                    const svn_opt_subcommand_desc_t *cmd_table,
 771                    const apr_getopt_option_t *option_table,
 772                    const char *footer,
 773                    apr_pool_t *pool);
 774
 775 #ifdef __cplusplus
 776 }
 777 #endif /* __cplusplus */
 778
 779 #endif /* SVN_OPTS_H */