svn_opt.h revision 299742
1204635Sgnn/** 2204635Sgnn * @copyright 3204635Sgnn * ==================================================================== 4204635Sgnn * Licensed to the Apache Software Foundation (ASF) under one 5204635Sgnn * or more contributor license agreements. See the NOTICE file 6204635Sgnn * distributed with this work for additional information 7204635Sgnn * regarding copyright ownership. The ASF licenses this file 8204635Sgnn * to you under the Apache License, Version 2.0 (the 9204635Sgnn * "License"); you may not use this file except in compliance 10204635Sgnn * with the License. You may obtain a copy of the License at 11204635Sgnn * 12231871Sbrueffer * http://www.apache.org/licenses/LICENSE-2.0 13231871Sbrueffer * 14231871Sbrueffer * Unless required by applicable law or agreed to in writing, 15231871Sbrueffer * software distributed under the License is distributed on an 16231871Sbrueffer * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17231871Sbrueffer * KIND, either express or implied. See the License for the 18231871Sbrueffer * specific language governing permissions and limitations 19231871Sbrueffer * under the License. 20231871Sbrueffer * ==================================================================== 21231871Sbrueffer * @endcopyright 22231871Sbrueffer * 23204635Sgnn * @file svn_opt.h 24204635Sgnn * @brief Option and argument parsing for Subversion command lines 25204635Sgnn */ 26233451Sgonzo 27233451Sgonzo#ifndef SVN_OPT_H 28204635Sgnn#define SVN_OPT_H 29204635Sgnn 30233451Sgonzo#include <apr.h> 31204635Sgnn#include <apr_pools.h> 32233451Sgonzo#include <apr_getopt.h> 33204635Sgnn#include <apr_tables.h> 34204635Sgnn#include <apr_hash.h> 35204635Sgnn 36204635Sgnn#ifndef DOXYGEN_SHOULD_SKIP_THIS 37204635Sgnn#define APR_WANT_STDIO 38204635Sgnn#endif 39204635Sgnn#include <apr_want.h> /* for FILE* */ 40204635Sgnn 41204635Sgnn#include "svn_types.h" 42204635Sgnn 43204635Sgnn#ifdef __cplusplus 44204635Sgnnextern "C" { 45204635Sgnn#endif /* __cplusplus */ 46204635Sgnn 47204635Sgnn 48204635Sgnn 49204635Sgnn/** 50204635Sgnn * All subcommand procedures in Subversion conform to this prototype. 51204635Sgnn * 52204635Sgnn * @a os is the apr option state after getopt processing has been run; in 53204635Sgnn * other words, it still contains the non-option arguments following 54204635Sgnn * the subcommand. See @a os->argv and @a os->ind. 55204635Sgnn * 56204635Sgnn * @a baton is anything you need it to be. 57232158Sgjb * 58204635Sgnn * @a pool is used for allocating errors, and for any other allocation 59232158Sgjb * unless the instance is explicitly documented to allocate from a 60204635Sgnn * pool in @a baton. 61204635Sgnn */ 62204635Sgnntypedef svn_error_t *(svn_opt_subcommand_t)( 63204635Sgnn apr_getopt_t *os, void *baton, apr_pool_t *pool); 64204635Sgnn 65204635Sgnn 66232158Sgjb/** The maximum number of aliases a subcommand can have. */ 67204635Sgnn#define SVN_OPT_MAX_ALIASES 3 68204635Sgnn 69204635Sgnn/** The maximum number of options that can be accepted by a subcommand. */ 70204635Sgnn#define SVN_OPT_MAX_OPTIONS 50 71204635Sgnn 72204635Sgnn/** Options that have no short option char should use an identifying 73204635Sgnn * integer equal to or greater than this. 74204635Sgnn */ 75204635Sgnn#define SVN_OPT_FIRST_LONGOPT_ID 256 76204635Sgnn 77204635Sgnn 78204635Sgnn/** One element of a subcommand dispatch table. 79204635Sgnn * 80204635Sgnn * @since New in 1.4. 81204635Sgnn */ 82204635Sgnntypedef struct svn_opt_subcommand_desc2_t 83204635Sgnn{ 84204635Sgnn /** The full name of this command. */ 85204635Sgnn const char *name; 86204635Sgnn 87204635Sgnn /** The function this command invokes. */ 88232158Sgjb svn_opt_subcommand_t *cmd_func; 89204635Sgnn 90232158Sgjb /** A list of alias names for this command (e.g., 'up' for 'update'). */ 91204635Sgnn const char *aliases[SVN_OPT_MAX_ALIASES]; 92204635Sgnn 93204635Sgnn /** A brief string describing this command, for usage messages. */ 94204635Sgnn const char *help; 95204635Sgnn 96204635Sgnn /** A list of options accepted by this command. Each value in the 97204635Sgnn * array is a unique enum (the 2nd field in apr_getopt_option_t) 98204635Sgnn */ 99204635Sgnn int valid_options[SVN_OPT_MAX_OPTIONS]; 100204635Sgnn 101204635Sgnn /** A list of option help descriptions, keyed by the option unique enum 102204635Sgnn * (the 2nd field in apr_getopt_option_t), which override the generic 103204635Sgnn * descriptions given in an apr_getopt_option_t on a per-subcommand basis. 104204635Sgnn */ 105232158Sgjb struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS]; 106232158Sgjb} svn_opt_subcommand_desc2_t; 107204635Sgnn 108204635Sgnn 109204635Sgnn/** One element of a subcommand dispatch table. 110204635Sgnn * 111204635Sgnn * @deprecated Provided for backward compatibility with the 1.3 API. 112204635Sgnn * 113204635Sgnn * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides 114204635Sgnn * member. 115204635Sgnn */ 116204635Sgnntypedef struct svn_opt_subcommand_desc_t 117204635Sgnn{ 118204635Sgnn /** The full name of this command. */ 119204635Sgnn const char *name; 120204635Sgnn 121204635Sgnn /** The function this command invokes. */ 122204635Sgnn svn_opt_subcommand_t *cmd_func; 123232158Sgjb 124232158Sgjb /** A list of alias names for this command (e.g., 'up' for 'update'). */ 125204635Sgnn const char *aliases[SVN_OPT_MAX_ALIASES]; 126204635Sgnn 127204635Sgnn /** A brief string describing this command, for usage messages. */ 128204635Sgnn const char *help; 129204635Sgnn 130204635Sgnn /** A list of options accepted by this command. Each value in the 131204635Sgnn * array is a unique enum (the 2nd field in apr_getopt_option_t) 132204635Sgnn */ 133204635Sgnn int valid_options[SVN_OPT_MAX_OPTIONS]; 134204635Sgnn 135204635Sgnn} svn_opt_subcommand_desc_t; 136204635Sgnn 137204635Sgnn 138204635Sgnn/** 139204635Sgnn * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if 140204635Sgnn * none. @a cmd_name may be an alias. 141204635Sgnn * 142204635Sgnn * @since New in 1.4. 143204635Sgnn */ 144204635Sgnnconst svn_opt_subcommand_desc2_t * 145204635Sgnnsvn_opt_get_canonical_subcommand2(const svn_opt_subcommand_desc2_t *table, 146204635Sgnn const char *cmd_name); 147204635Sgnn 148204635Sgnn 149204635Sgnn/** 150204635Sgnn * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if 151204635Sgnn * none. @a cmd_name may be an alias. 152204635Sgnn * 153204635Sgnn * Same as svn_opt_get_canonical_subcommand2(), but acts on 154204635Sgnn * #svn_opt_subcommand_desc_t. 155204635Sgnn * 156204635Sgnn * @deprecated Provided for backward compatibility with the 1.3 API. 157210933Sjoel */ 158204635SgnnSVN_DEPRECATED 159204635Sgnnconst svn_opt_subcommand_desc_t * 160204635Sgnnsvn_opt_get_canonical_subcommand(const svn_opt_subcommand_desc_t *table, 161204635Sgnn const char *cmd_name); 162204635Sgnn 163204635Sgnn 164204635Sgnn/** 165204635Sgnn * Return pointer to an @c apr_getopt_option_t for the option whose 166204635Sgnn * option code is @a code, or @c NULL if no match. @a option_table must end 167204635Sgnn * with an element whose every field is zero. If @a command is non-NULL, 168204635Sgnn * then return the subcommand-specific option description instead of the 169204635Sgnn * generic one, if a specific description is defined. 170204635Sgnn * 171232157Sgjb * The returned value may be statically allocated, or allocated in @a pool. 172204635Sgnn * 173204635Sgnn * @since New in 1.4. 174204635Sgnn */ 175204635Sgnnconst apr_getopt_option_t * 176204635Sgnnsvn_opt_get_option_from_code2(int code, 177204635Sgnn const apr_getopt_option_t *option_table, 178204635Sgnn const svn_opt_subcommand_desc2_t *command, 179204635Sgnn apr_pool_t *pool); 180204635Sgnn 181204635Sgnn 182204635Sgnn/** 183204635Sgnn * Return the first entry from @a option_table whose option code is @a code, 184232158Sgjb * or @c NULL if no match. @a option_table must end with an element whose 185232158Sgjb * every field is zero. 186204635Sgnn * 187204635Sgnn * @deprecated Provided for backward compatibility with the 1.3 API. 188204635Sgnn */ 189204635SgnnSVN_DEPRECATED 190204635Sgnnconst apr_getopt_option_t * 191204635Sgnnsvn_opt_get_option_from_code(int code, 192204635Sgnn const apr_getopt_option_t *option_table); 193204635Sgnn 194204635Sgnn 195232158Sgjb/** 196204635Sgnn * Return @c TRUE iff subcommand @a command supports option @a 197204635Sgnn * option_code, else return @c FALSE. If @a global_options is 198204635Sgnn * non-NULL, it is a zero-terminated array, and all subcommands take 199204635Sgnn * the options listed in it. 200204635Sgnn * 201204635Sgnn * @since New in 1.5. 202204635Sgnn */ 203204635Sgnnsvn_boolean_t 204204635Sgnnsvn_opt_subcommand_takes_option3(const svn_opt_subcommand_desc2_t *command, 205204635Sgnn int option_code, 206204635Sgnn const int *global_options); 207204635Sgnn 208204635Sgnn/** 209204635Sgnn * Same as svn_opt_subcommand_takes_option3(), but with @c NULL for @a 210204635Sgnn * global_options. 211204635Sgnn * 212204635Sgnn * @deprecated Provided for backward compatibility with the 1.4 API. 213204635Sgnn */ 214204635SgnnSVN_DEPRECATED 215204635Sgnnsvn_boolean_t 216204635Sgnnsvn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t *command, 217204635Sgnn int option_code); 218204635Sgnn 219204635Sgnn 220232158Sgjb/** 221204635Sgnn * Return @c TRUE iff subcommand @a command supports option @a option_code, 222204635Sgnn * else return @c FALSE. 223204635Sgnn * 224204635Sgnn * Same as svn_opt_subcommand_takes_option2(), but acts on 225204635Sgnn * #svn_opt_subcommand_desc_t. 226204635Sgnn * 227204635Sgnn * @deprecated Provided for backward compatibility with the 1.3 API. 228204635Sgnn */ 229204635SgnnSVN_DEPRECATED 230210933Sjoelsvn_boolean_t 231204635Sgnnsvn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t *command, 232204635Sgnn int option_code); 233210933Sjoel 234204635Sgnn 235204635Sgnn/** 236204635Sgnn * Print a generic (not command-specific) usage message to @a stream. 237204635Sgnn * 238204635Sgnn * ### @todo Why is @a stream a stdio file instead of an svn stream? 239204635Sgnn * 240204635Sgnn * If @a header is non-NULL, print @a header followed by a newline. Then 241204635Sgnn * loop over @a cmd_table printing the usage for each command (getting 242204635Sgnn * option usages from @a opt_table). Then if @a footer is non-NULL, print 243204635Sgnn * @a footer followed by a newline. 244204635Sgnn * 245204635Sgnn * Use @a pool for temporary allocation. 246204635Sgnn * 247204635Sgnn * @since New in 1.4. 248204635Sgnn */ 249204635Sgnnvoid 250204635Sgnnsvn_opt_print_generic_help2(const char *header, 251204635Sgnn const svn_opt_subcommand_desc2_t *cmd_table, 252204635Sgnn const apr_getopt_option_t *opt_table, 253204635Sgnn const char *footer, 254204635Sgnn apr_pool_t *pool, 255204635Sgnn FILE *stream); 256204635Sgnn 257204635Sgnn 258204635Sgnn/** 259204635Sgnn * Same as svn_opt_print_generic_help2(), but acts on 260204635Sgnn * #svn_opt_subcommand_desc_t. 261204635Sgnn * 262232158Sgjb * @deprecated Provided for backward compatibility with the 1.3 API. 263204635Sgnn */ 264204635SgnnSVN_DEPRECATED 265204635Sgnnvoid 266204635Sgnnsvn_opt_print_generic_help(const char *header, 267204635Sgnn const svn_opt_subcommand_desc_t *cmd_table, 268204635Sgnn const apr_getopt_option_t *opt_table, 269204635Sgnn const char *footer, 270204635Sgnn apr_pool_t *pool, 271204635Sgnn FILE *stream); 272204635Sgnn 273204635Sgnn 274204635Sgnn/** 275204635Sgnn * Print an option @a opt nicely into a @a string allocated in @a pool. 276204635Sgnn * If @a doc is set, include the generic documentation string of @a opt, 277204635Sgnn * localized to the current locale if a translation is available. 278204635Sgnn */ 279204635Sgnnvoid 280204635Sgnnsvn_opt_format_option(const char **string, 281204635Sgnn const apr_getopt_option_t *opt, 282204635Sgnn svn_boolean_t doc, 283204635Sgnn apr_pool_t *pool); 284204635Sgnn 285204635Sgnn 286204635Sgnn 287204635Sgnn/** 288232158Sgjb * Get @a subcommand's usage from @a table, and print it to @c stdout. 289232158Sgjb * Obtain option usage from @a options_table. If not @c NULL, @a 290204635Sgnn * global_options is a zero-terminated list of global options. Use @a 291204635Sgnn * pool for temporary allocation. @a subcommand may be a canonical 292204635Sgnn * command name or an alias. ### @todo Why does this only print to 293204635Sgnn * @c stdout, whereas svn_opt_print_generic_help() gives us a choice? 294204635Sgnn * 295204635Sgnn * When printing the description of an option, if the same option code 296204635Sgnn * appears a second time in @a options_table with a different name, then 297204635Sgnn * use that second name as an alias for the first name. This additional 298204635Sgnn * behaviour is new in 1.7. 299204635Sgnn * 300204635Sgnn * @since New in 1.5. 301204635Sgnn */ 302204635Sgnnvoid 303204635Sgnnsvn_opt_subcommand_help3(const char *subcommand, 304204635Sgnn const svn_opt_subcommand_desc2_t *table, 305204635Sgnn const apr_getopt_option_t *options_table, 306204635Sgnn const int *global_options, 307204635Sgnn apr_pool_t *pool); 308204635Sgnn 309204635Sgnn/** 310204635Sgnn * Same as svn_opt_subcommand_help3(), but with @a global_options 311204635Sgnn * always NULL. 312204635Sgnn * 313204635Sgnn * @deprecated Provided for backward compatibility with the 1.4 API. 314204635Sgnn */ 315204635SgnnSVN_DEPRECATED 316204635Sgnnvoid 317204635Sgnnsvn_opt_subcommand_help2(const char *subcommand, 318204635Sgnn const svn_opt_subcommand_desc2_t *table, 319204635Sgnn const apr_getopt_option_t *options_table, 320204635Sgnn apr_pool_t *pool); 321204635Sgnn 322204635Sgnn 323204635Sgnn/** 324204635Sgnn * Same as svn_opt_subcommand_help2(), but acts on 325204635Sgnn * #svn_opt_subcommand_desc_t. 326204635Sgnn * 327204635Sgnn * @deprecated Provided for backward compatibility with the 1.3 API. 328204635Sgnn */ 329204635SgnnSVN_DEPRECATED 330204635Sgnnvoid 331204635Sgnnsvn_opt_subcommand_help(const char *subcommand, 332204635Sgnn const svn_opt_subcommand_desc_t *table, 333204635Sgnn const apr_getopt_option_t *options_table, 334204635Sgnn apr_pool_t *pool); 335204635Sgnn 336204635Sgnn 337204635Sgnn 338204635Sgnn/* Parsing revision and date options. */ 339204635Sgnn 340204635Sgnn/** 341204635Sgnn * Various ways of specifying revisions. 342204635Sgnn * 343204635Sgnn * @note 344204635Sgnn * In contexts where local mods are relevant, the `working' kind 345204635Sgnn * refers to the uncommitted "working" revision, which may be modified 346204635Sgnn * with respect to its base revision. In other contexts, `working' 347204635Sgnn * should behave the same as `committed' or `current'. 348204635Sgnn */ 349204635Sgnnenum svn_opt_revision_kind { 350204635Sgnn /** No revision information given. */ 351204635Sgnn svn_opt_revision_unspecified, 352204635Sgnn 353204635Sgnn /** revision given as number */ 354204635Sgnn svn_opt_revision_number, 355204635Sgnn 356204635Sgnn /** revision given as date */ 357204635Sgnn svn_opt_revision_date, 358204635Sgnn 359204635Sgnn /** rev of most recent change */ 360204635Sgnn svn_opt_revision_committed, 361204635Sgnn 362204635Sgnn /** (rev of most recent change) - 1 */ 363204635Sgnn svn_opt_revision_previous, 364204635Sgnn 365204635Sgnn /** .svn/entries current revision */ 366204635Sgnn svn_opt_revision_base, 367204635Sgnn 368204635Sgnn /** current, plus local mods */ 369204635Sgnn svn_opt_revision_working, 370204635Sgnn 371204635Sgnn /** repository youngest */ 372204635Sgnn svn_opt_revision_head 373204635Sgnn 374204635Sgnn /* please update svn_opt__revision_to_string() when extending this enum */ 375204635Sgnn}; 376204635Sgnn 377204635Sgnn/** 378204635Sgnn * A revision value, which can be specified as a number or a date. 379233565Sjoel * 380233565Sjoel * @note This union was formerly an anonymous inline type in 381233565Sjoel * @c svn_opt_revision_t, and was converted to a named type just to 382233565Sjoel * make things easier for SWIG. 383204635Sgnn * 384204635Sgnn * @since New in 1.3. 385204635Sgnn */ 386204635Sgnntypedef union svn_opt_revision_value_t 387204635Sgnn{ 388204635Sgnn /** The revision number */ 389204635Sgnn svn_revnum_t number; 390204635Sgnn 391233451Sgonzo /** the date of the revision */ 392204635Sgnn apr_time_t date; 393204635Sgnn} svn_opt_revision_value_t; 394204635Sgnn 395233628Sfabient/** A revision, specified in one of @c svn_opt_revision_kind ways. */ 396204635Sgnntypedef struct svn_opt_revision_t 397204635Sgnn{ 398204635Sgnn enum svn_opt_revision_kind kind; /**< See svn_opt_revision_kind */ 399204635Sgnn svn_opt_revision_value_t value; /**< Extra data qualifying the @c kind */ 400204635Sgnn} svn_opt_revision_t; 401204635Sgnn 402204635Sgnn/** A revision range, specified in one of @c svn_opt_revision_kind ways. */ 403204635Sgnntypedef struct svn_opt_revision_range_t 404204635Sgnn{ 405204635Sgnn /** The first revision in the range */ 406204635Sgnn svn_opt_revision_t start; 407204635Sgnn 408204635Sgnn /** The last revision in the range */ 409204635Sgnn svn_opt_revision_t end; 410204635Sgnn} svn_opt_revision_range_t; 411204635Sgnn 412204635Sgnn/** 413204635Sgnn * Set @a *start_revision and/or @a *end_revision according to @a arg, 414 * where @a arg is "N" or "N:M", like so: 415 * 416 * - If @a arg is "N", set @a *start_revision to represent N, and 417 * leave @a *end_revision untouched. 418 * 419 * - If @a arg is "N:M", set @a *start_revision and @a *end_revision 420 * to represent N and M respectively. 421 * 422 * N and/or M may be one of the special revision descriptors 423 * recognized by revision_from_word(), or a date in curly braces. 424 * 425 * If @a arg is invalid, return -1; else return 0. 426 * It is invalid to omit a revision (as in, ":", "N:" or ":M"). 427 * 428 * @note It is typical, though not required, for @a *start_revision and 429 * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry. 430 * 431 * Use @a pool for temporary allocations. 432 */ 433int 434svn_opt_parse_revision(svn_opt_revision_t *start_revision, 435 svn_opt_revision_t *end_revision, 436 const char *arg, 437 apr_pool_t *pool); 438 439/** 440 * Parse @a arg, where @a arg is "N" or "N:M", into a 441 * @c svn_opt_revision_range_t and push that onto @a opt_ranges. 442 * 443 * - If @a arg is "N", set the @c start field of the 444 * @c svn_opt_revision_range_t to represent N and the @c end field 445 * to @c svn_opt_revision_unspecified. 446 * 447 * - If @a arg is "N:M", set the @c start field of the 448 * @c svn_opt_revision_range_t to represent N and the @c end field 449 * to represent M. 450 * 451 * If @a arg is invalid, return -1; else return 0. It is invalid to omit 452 * a revision (as in, ":", "N:" or ":M"). 453 * 454 * Use @a pool to allocate @c svn_opt_revision_range_t pushed to the array. 455 * 456 * @since New in 1.5. 457 */ 458int 459svn_opt_parse_revision_to_range(apr_array_header_t *opt_ranges, 460 const char *arg, 461 apr_pool_t *pool); 462 463/** 464 * Resolve peg revisions and operational revisions in the following way: 465 * 466 * - If @a is_url is set and @a peg_rev->kind is 467 * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to 468 * @c svn_opt_revision_head. 469 * 470 * - If @a is_url is not set, and @a peg_rev->kind is 471 * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to 472 * @c svn_opt_revision_base. 473 * 474 * - If @a op_rev->kind is @c svn_opt_revision_unspecified, @a op_rev 475 * defaults to @a peg_rev. 476 * 477 * Both @a peg_rev and @a op_rev may be modified as a result of this 478 * function. @a is_url should be set if the path the revisions refer to is 479 * a url, and unset otherwise. 480 * 481 * If @a notice_local_mods is set, @c svn_opt_revision_working is used, 482 * instead of @c svn_opt_revision_base. 483 * 484 * Use @a pool for allocations. 485 * 486 * @since New in 1.5. 487 */ 488svn_error_t * 489svn_opt_resolve_revisions(svn_opt_revision_t *peg_rev, 490 svn_opt_revision_t *op_rev, 491 svn_boolean_t is_url, 492 svn_boolean_t notice_local_mods, 493 apr_pool_t *pool); 494 495 496/* Parsing arguments. */ 497 498/** 499 * Pull remaining target arguments from @a os into @a *targets_p, 500 * converting them to UTF-8, followed by targets from @a known_targets 501 * (which might come from, for example, the "--targets" command line 502 * option), which are already in UTF-8. 503 * 504 * On each URL target, do some IRI-to-URI encoding and some 505 * auto-escaping. On each local path, canonicalize case and path 506 * separators. 507 * 508 * Allocate @a *targets_p and its elements in @a pool. 509 * 510 * If a path has the same name as a Subversion working copy 511 * administrative directory, return SVN_ERR_RESERVED_FILENAME_SPECIFIED; 512 * if multiple reserved paths are encountered, return a chain of 513 * errors, all of which are SVN_ERR_RESERVED_FILENAME_SPECIFIED. Do 514 * not return this type of error in a chain with any other type of 515 * error, and if this is the only type of error encountered, complete 516 * the operation before returning the error(s). 517 * 518 * @deprecated Provided for backward compatibility with the 1.5 API. 519 * @see svn_client_args_to_target_array() 520 */ 521SVN_DEPRECATED 522svn_error_t * 523svn_opt_args_to_target_array3(apr_array_header_t **targets_p, 524 apr_getopt_t *os, 525 const apr_array_header_t *known_targets, 526 apr_pool_t *pool); 527 528/** 529 * This is the same as svn_opt_args_to_target_array3() except that it 530 * silently ignores paths that have the same name as a working copy 531 * administrative directory. 532 * 533 * @since New in 1.2. 534 * 535 * @deprecated Provided for backward compatibility with the 1.4 API. 536 */ 537SVN_DEPRECATED 538svn_error_t * 539svn_opt_args_to_target_array2(apr_array_header_t **targets_p, 540 apr_getopt_t *os, 541 const apr_array_header_t *known_targets, 542 apr_pool_t *pool); 543 544 545/** 546 * The same as svn_opt_args_to_target_array2() except that, in 547 * addition, if @a extract_revisions is set, then look for trailing 548 * "@rev" syntax on the first two paths. If the first target in @a 549 * *targets_p ends in "@rev", replace it with a canonicalized version of 550 * the part before "@rev" and replace @a *start_revision with the value 551 * of "rev". If the second target in @a *targets_p ends in "@rev", 552 * replace it with a canonicalized version of the part before "@rev" 553 * and replace @a *end_revision with the value of "rev". Ignore 554 * revision specifiers on any further paths. "rev" can be any form of 555 * single revision specifier, as accepted by svn_opt_parse_revision(). 556 * 557 * @deprecated Provided for backward compatibility with the 1.1 API. 558 */ 559SVN_DEPRECATED 560svn_error_t * 561svn_opt_args_to_target_array(apr_array_header_t **targets_p, 562 apr_getopt_t *os, 563 const apr_array_header_t *known_targets, 564 svn_opt_revision_t *start_revision, 565 svn_opt_revision_t *end_revision, 566 svn_boolean_t extract_revisions, 567 apr_pool_t *pool); 568 569 570/** 571 * Parse revprop key/value pair from @a revprop_spec (name[=value]) into 572 * @a revprops, making copies of both with @a pool. If @a revprops is 573 * @c NULL, allocate a new apr_hash_t in it. @a revprops maps 574 * const char * revprop names to svn_string_t * revprop values for use 575 * with svn_repos_get_commit_editor5 and other get_commit_editor APIs. 576 * 577 * @since New in 1.6. 578 */ 579svn_error_t * 580svn_opt_parse_revprop(apr_hash_t **revprops, const char *revprop_spec, 581 apr_pool_t *pool); 582 583 584/** 585 * If no targets exist in @a *targets, add `.' as the lone target. 586 * 587 * (Some commands take an implicit "." string argument when invoked 588 * with no arguments. Those commands make use of this function to 589 * add "." to the target array if the user passes no args.) 590 */ 591void 592svn_opt_push_implicit_dot_target(apr_array_header_t *targets, 593 apr_pool_t *pool); 594 595 596/** 597 * Parse @a num_args non-target arguments from the list of arguments in 598 * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without 599 * doing any UTF-8 conversion. Allocate @a *args_p and its values in @a pool. 600 */ 601svn_error_t * 602svn_opt_parse_num_args(apr_array_header_t **args_p, 603 apr_getopt_t *os, 604 int num_args, 605 apr_pool_t *pool); 606 607 608/** 609 * Parse all remaining arguments from @a os->argv, return them as 610 * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion. 611 * Allocate @a *args_p and its values in @a pool. 612 */ 613svn_error_t * 614svn_opt_parse_all_args(apr_array_header_t **args_p, 615 apr_getopt_t *os, 616 apr_pool_t *pool); 617 618/** 619 * Parse a working-copy path or URL in @a path, extracting any trailing 620 * revision specifier of the form "@rev" from the last component of 621 * the path. 622 * 623 * Some examples would be: 624 * 625 * - "foo/bar" -> "foo/bar", (unspecified) 626 * - "foo/bar@13" -> "foo/bar", (number, 13) 627 * - "foo/bar@HEAD" -> "foo/bar", (head) 628 * - "foo/bar@{1999-12-31}" -> "foo/bar", (date, 1999-12-31) 629 * - "http://a/b@27" -> "http://a/b", (number, 27) 630 * - "http://a/b@COMMITTED" -> "http://a/b", (committed) [*] 631 * - "http://a/b@{1999-12-31}" -> "http://a/b", (date, 1999-12-31) 632 * - "http://a/b@%7B1999-12-31%7D" -> "http://a/b", (date, 1999-12-31) 633 * - "foo/bar@1:2" -> error 634 * - "foo/bar@baz" -> error 635 * - "foo/bar@" -> "foo/bar", (unspecified) 636 * - "foo/@bar@" -> "foo/@bar", (unspecified) 637 * - "foo/bar/@13" -> "foo/bar/", (number, 13) 638 * - "foo/bar@@13" -> "foo/bar@", (number, 13) 639 * - "foo/@bar@HEAD" -> "foo/@bar", (head) 640 * - "foo@/bar" -> "foo@/bar", (unspecified) 641 * - "foo@HEAD/bar" -> "foo@HEAD/bar", (unspecified) 642 * - "@foo/bar" -> "@foo/bar", (unspecified) 643 * - "@foo/bar@" -> "@foo/bar", (unspecified) 644 * 645 * [*] Syntactically valid but probably not semantically useful. 646 * 647 * If a trailing revision specifier is found, parse it into @a *rev and 648 * put the rest of the path into @a *truepath, allocating from @a pool; 649 * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR (with the effect on 650 * @a *truepath undefined) if the revision specifier is invalid. 651 * If no trailing revision specifier is found, set @a *truepath to 652 * @a path and @a rev->kind to @c svn_opt_revision_unspecified. 653 * 654 * This function does not require that @a path be in canonical form. 655 * No canonicalization is done and @a *truepath will only be in 656 * canonical form if @a path is in canonical form. 657 * 658 * @since New in 1.1. 659 * @since Since 1.6.5, this returns an error if @a path contains a peg 660 * specifier with no path before it, such as "@abc". 661 * @since Since 1.9.0, this no longer returns an error if @a path contains a peg 662 * specifier with no path before it, such as "@abc". 663 */ 664svn_error_t * 665svn_opt_parse_path(svn_opt_revision_t *rev, 666 const char **truepath, 667 const char *path, 668 apr_pool_t *pool); 669 670/** 671 * Central dispatcher function for various kinds of help message. 672 * Prints one of: 673 * * subcommand-specific help (svn_opt_subcommand_help) 674 * * generic help (svn_opt_print_generic_help) 675 * * version info 676 * * simple usage complaint: "Type '@a pgm_name help' for usage." 677 * 678 * If @a os is not @c NULL and it contains arguments, then try 679 * printing help for them as though they are subcommands, using @a 680 * cmd_table and @a option_table for option information. If not @c 681 * NULL, @a global_options is a zero-terminated array of options taken 682 * by all subcommands. 683 * 684 * Else, if @a print_version is TRUE, then print version info, in 685 * brief form if @a quiet is also TRUE; if @a quiet is FALSE, then if 686 * @a version_footer is non-NULL, print it following the version 687 * information. If @a verbose is TRUE, also print information about 688 * the running system and loaded shared libraries, where available. 689 * 690 * Else, if @a os is not @c NULL and does not contain arguments, print 691 * generic help, via svn_opt_print_generic_help2() with the @a header, 692 * @a cmd_table, @a option_table, and @a footer arguments. 693 * 694 * Else, when @a os is @c NULL, print the simple usage complaint. 695 * 696 * Use @a pool for temporary allocations. 697 * 698 * Notes: The reason this function handles both version printing and 699 * general usage help is that a confused user might put both the 700 * --version flag *and* subcommand arguments on a help command line. 701 * The logic for handling such a situation should be in one place. 702 * 703 * @since New in 1.8. 704 */ 705 706svn_error_t * 707svn_opt_print_help4(apr_getopt_t *os, 708 const char *pgm_name, 709 svn_boolean_t print_version, 710 svn_boolean_t quiet, 711 svn_boolean_t verbose, 712 const char *version_footer, 713 const char *header, 714 const svn_opt_subcommand_desc2_t *cmd_table, 715 const apr_getopt_option_t *option_table, 716 const int *global_options, 717 const char *footer, 718 apr_pool_t *pool); 719 720/** 721 * Same as svn_opt_print_help4(), but with @a verbose always @c FALSE. 722 * 723 * @deprecated Provided for backward compatibility with the 1.7 API. 724 */ 725 726SVN_DEPRECATED 727svn_error_t * 728svn_opt_print_help3(apr_getopt_t *os, 729 const char *pgm_name, 730 svn_boolean_t print_version, 731 svn_boolean_t quiet, 732 const char *version_footer, 733 const char *header, 734 const svn_opt_subcommand_desc2_t *cmd_table, 735 const apr_getopt_option_t *option_table, 736 const int *global_options, 737 const char *footer, 738 apr_pool_t *pool); 739 740/** 741 * Same as svn_opt_print_help3(), but with @a global_options always @c 742 * NULL. 743 * 744 * @deprecated Provided for backward compatibility with the 1.4 API. 745 */ 746 747SVN_DEPRECATED 748svn_error_t * 749svn_opt_print_help2(apr_getopt_t *os, 750 const char *pgm_name, 751 svn_boolean_t print_version, 752 svn_boolean_t quiet, 753 const char *version_footer, 754 const char *header, 755 const svn_opt_subcommand_desc2_t *cmd_table, 756 const apr_getopt_option_t *option_table, 757 const char *footer, 758 apr_pool_t *pool); 759 760 761/** 762 * Same as svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t. 763 * 764 * @deprecated Provided for backward compatibility with the 1.3 API. 765 */ 766SVN_DEPRECATED 767svn_error_t * 768svn_opt_print_help(apr_getopt_t *os, 769 const char *pgm_name, 770 svn_boolean_t print_version, 771 svn_boolean_t quiet, 772 const char *version_footer, 773 const char *header, 774 const svn_opt_subcommand_desc_t *cmd_table, 775 const apr_getopt_option_t *option_table, 776 const char *footer, 777 apr_pool_t *pool); 778 779#ifdef __cplusplus 780} 781#endif /* __cplusplus */ 782 783#endif /* SVN_OPT_H */ 784