src/TortoiseMerge/svninclude/svn_opt.h

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