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 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 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 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 */ 878