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