Subversion 1.6.16

svn_opt.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2008 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_opt.h
00019  * @brief Option and argument parsing for Subversion command lines
00020  */
00021 
00022 #ifndef SVN_OPTS_H
00023 #define SVN_OPTS_H
00024 
00025 #include <apr.h>
00026 #include <apr_pools.h>
00027 #include <apr_getopt.h>
00028 #include <apr_tables.h>
00029 #include <apr_hash.h>
00030 
00031 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00032 #define APR_WANT_STDIO
00033 #endif
00034 #include <apr_want.h>   /* for FILE* */
00035 
00036 #include "svn_types.h"
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif /* __cplusplus */
00041 
00042 
00043 
00044 /**
00045  * All subcommand procedures in Subversion conform to this prototype.
00046  *
00047  * @a os is the apr option state after getopt processing has been run; in
00048  * other words, it still contains the non-option arguments following
00049  * the subcommand.  See @a os->argv and @a os->ind.
00050  *
00051  * @a baton is anything you need it to be.
00052  *
00053  * @a pool is used for allocating errors, and for any other allocation
00054  * unless the instance is explicitly documented to allocate from a
00055  * pool in @a baton.
00056  */
00057 typedef svn_error_t *(svn_opt_subcommand_t)
00058        (apr_getopt_t *os, void *baton, apr_pool_t *pool);
00059 
00060 
00061 /** The maximum number of aliases a subcommand can have. */
00062 #define SVN_OPT_MAX_ALIASES 3
00063 
00064 /** The maximum number of options that can be accepted by a subcommand. */
00065 #define SVN_OPT_MAX_OPTIONS 50
00066 
00067 /** Options that have no short option char should use an identifying
00068  * integer equal to or greater than this.
00069  */
00070 #define SVN_OPT_FIRST_LONGOPT_ID 256
00071 
00072 
00073 /** One element of a subcommand dispatch table.
00074  *
00075  * @since New in 1.4.
00076  */
00077 typedef struct svn_opt_subcommand_desc2_t
00078 {
00079   /** The full name of this command. */
00080   const char *name;
00081 
00082   /** The function this command invokes. */
00083   svn_opt_subcommand_t *cmd_func;
00084 
00085   /** A list of alias names for this command (e.g., 'up' for 'update'). */
00086   const char *aliases[SVN_OPT_MAX_ALIASES];
00087 
00088   /** A brief string describing this command, for usage messages. */
00089   const char *help;
00090 
00091   /** A list of options accepted by this command.  Each value in the
00092    * array is a unique enum (the 2nd field in apr_getopt_option_t)
00093    */
00094   int valid_options[SVN_OPT_MAX_OPTIONS];
00095 
00096   /** A list of option help descriptions, keyed by the option unique enum
00097    * (the 2nd field in apr_getopt_option_t), which override the generic
00098    * descriptions given in an apr_getopt_option_t on a per-subcommand basis.
00099    */
00100   struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS];
00101 } svn_opt_subcommand_desc2_t;
00102 
00103 
00104 /** One element of a subcommand dispatch table.
00105  *
00106  * @deprecated Provided for backward compatibility with the 1.3 API.
00107  *
00108  * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides
00109  * member.
00110  */
00111 typedef struct svn_opt_subcommand_desc_t
00112 {
00113   /** The full name of this command. */
00114   const char *name;
00115 
00116   /** The function this command invokes. */
00117   svn_opt_subcommand_t *cmd_func;
00118 
00119   /** A list of alias names for this command (e.g., 'up' for 'update'). */
00120   const char *aliases[SVN_OPT_MAX_ALIASES];
00121 
00122   /** A brief string describing this command, for usage messages. */
00123   const char *help;
00124 
00125   /** A list of options accepted by this command.  Each value in the
00126    * array is a unique enum (the 2nd field in apr_getopt_option_t)
00127    */
00128   int valid_options[SVN_OPT_MAX_OPTIONS];
00129 
00130 } svn_opt_subcommand_desc_t;
00131 
00132 
00133 /**
00134  * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
00135  * none.  @a cmd_name may be an alias.
00136  *
00137  * @since New in 1.4.
00138  */
00139 const svn_opt_subcommand_desc2_t *
00140 svn_opt_get_canonical_subcommand2(const svn_opt_subcommand_desc2_t *table,
00141                                   const char *cmd_name);
00142 
00143 
00144 /**
00145  * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
00146  * none.  @a cmd_name may be an alias.
00147  *
00148  * Same as svn_opt_get_canonical_subcommand2(), but acts on
00149  * #svn_opt_subcommand_desc_t.
00150  *
00151  * @deprecated Provided for backward compatibility with the 1.3 API.
00152  */
00153 SVN_DEPRECATED
00154 const svn_opt_subcommand_desc_t *
00155 svn_opt_get_canonical_subcommand(const svn_opt_subcommand_desc_t *table,
00156                                  const char *cmd_name);
00157 
00158 
00159 /**
00160  * Return pointer to an @c apr_getopt_option_t for the option whose
00161  * option code is @a code, or @c NULL if no match.  @a option_table must end
00162  * with an element whose every field is zero.  If @c command is non-NULL,
00163  * then return the subcommand-specific option description instead of the
00164  * generic one, if a specific description is defined.
00165  *
00166  * The returned value may be statically allocated, or allocated in @a pool.
00167  *
00168  * @since New in 1.4.
00169  */
00170 const apr_getopt_option_t *
00171 svn_opt_get_option_from_code2(int code,
00172                               const apr_getopt_option_t *option_table,
00173                               const svn_opt_subcommand_desc2_t *command,
00174                               apr_pool_t *pool);
00175 
00176 
00177 /**
00178  * Return the first entry from @a option_table whose option code is @a code,
00179  * or @c NULL if no match.  @a option_table must end with an element whose
00180  * every field is zero.
00181  *
00182  * @deprecated Provided for backward compatibility with the 1.3 API.
00183  */
00184 SVN_DEPRECATED
00185 const apr_getopt_option_t *
00186 svn_opt_get_option_from_code(int code,
00187                              const apr_getopt_option_t *option_table);
00188 
00189 
00190 /**
00191  * Return @c TRUE iff subcommand @a command supports option @a
00192  * option_code, else return @c FALSE.  If @a global_options is
00193  * non-NULL, it is a zero-terminated array, and all subcommands take
00194  * the options listed in it.
00195  *
00196  * @since New in 1.5.
00197  */
00198 svn_boolean_t
00199 svn_opt_subcommand_takes_option3(const svn_opt_subcommand_desc2_t *command,
00200                                  int option_code,
00201                                  const int *global_options);
00202 
00203 /**
00204  * Same as svn_opt_subcommand_takes_option3(), but with @c NULL for @a
00205  * global_options.
00206  *
00207  * @deprecated Provided for backward compatibility with the 1.4 API.
00208  */
00209 SVN_DEPRECATED
00210 svn_boolean_t
00211 svn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t *command,
00212                                  int option_code);
00213 
00214 
00215 /**
00216  * Return @c TRUE iff subcommand @a command supports option @a option_code,
00217  * else return @c FALSE.
00218  *
00219  * Same as svn_opt_subcommand_takes_option2(), but acts on
00220  * #svn_opt_subcommand_desc_t.
00221  *
00222  * @deprecated Provided for backward compatibility with the 1.3 API.
00223  */
00224 SVN_DEPRECATED
00225 svn_boolean_t
00226 svn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t *command,
00227                                 int option_code);
00228 
00229 
00230 /**
00231  * Print a generic (not command-specific) usage message to @a stream.
00232  *
00233  * ### @todo Why is @a stream a stdio file instead of an svn stream?
00234  *
00235  * If @a header is non-NULL, print @a header followed by a newline.  Then
00236  * loop over @a cmd_table printing the usage for each command (getting
00237  * option usages from @a opt_table).  Then if @a footer is non-NULL, print
00238  * @a footer followed by a newline.
00239  *
00240  * Use @a pool for temporary allocation.
00241  *
00242  * @since New in 1.4.
00243  */
00244 void
00245 svn_opt_print_generic_help2(const char *header,
00246                             const svn_opt_subcommand_desc2_t *cmd_table,
00247                             const apr_getopt_option_t *opt_table,
00248                             const char *footer,
00249                             apr_pool_t *pool,
00250                             FILE *stream);
00251 
00252 
00253 /**
00254  * Same as svn_opt_print_generic_help2(), but acts on
00255  * #svn_opt_subcommand_desc_t.
00256  *
00257  * @deprecated Provided for backward compatibility with the 1.3 API.
00258  */
00259 SVN_DEPRECATED
00260 void
00261 svn_opt_print_generic_help(const char *header,
00262                            const svn_opt_subcommand_desc_t *cmd_table,
00263                            const apr_getopt_option_t *opt_table,
00264                            const char *footer,
00265                            apr_pool_t *pool,
00266                            FILE *stream);
00267 
00268 
00269 /**
00270  * Print an option @a opt nicely into a @a string allocated in @a pool.
00271  * If @a doc is set, include the generic documentation string of @a opt,
00272  * localized to the current locale if a translation is available.
00273  */
00274 void
00275 svn_opt_format_option(const char **string,
00276                       const apr_getopt_option_t *opt,
00277                       svn_boolean_t doc,
00278                       apr_pool_t *pool);
00279 
00280 
00281 
00282 /**
00283  * Get @a subcommand's usage from @a table, and print it to @c stdout.
00284  * Obtain option usage from @a options_table.  If not @c NULL, @a
00285  * global_options is a zero-terminated list of global options.  Use @a
00286  * pool for temporary allocation.  @a subcommand may be a canonical
00287  * command name or an alias.  ### @todo Why does this only print to
00288  * @c stdout, whereas svn_opt_print_generic_help() gives us a choice?
00289  *
00290  * @since New in 1.5.
00291  */
00292 void
00293 svn_opt_subcommand_help3(const char *subcommand,
00294                          const svn_opt_subcommand_desc2_t *table,
00295                          const apr_getopt_option_t *options_table,
00296                          const int *global_options,
00297                          apr_pool_t *pool);
00298 
00299 /**
00300  * Same as svn_opt_subcommand_help3(), but with @a global_options
00301  * always NULL.
00302  *
00303  * @deprecated Provided for backward compatibility with the 1.4 API.
00304  */
00305 SVN_DEPRECATED
00306 void
00307 svn_opt_subcommand_help2(const char *subcommand,
00308                          const svn_opt_subcommand_desc2_t *table,
00309                          const apr_getopt_option_t *options_table,
00310                          apr_pool_t *pool);
00311 
00312 
00313 /**
00314  * Same as svn_opt_subcommand_help2(), but acts on
00315  * #svn_opt_subcommand_desc_t.
00316  *
00317  * @deprecated Provided for backward compatibility with the 1.3 API.
00318  */
00319 SVN_DEPRECATED
00320 void
00321 svn_opt_subcommand_help(const char *subcommand,
00322                         const svn_opt_subcommand_desc_t *table,
00323                         const apr_getopt_option_t *options_table,
00324                         apr_pool_t *pool);
00325 
00326 
00327 
00328 /* Parsing revision and date options. */
00329 
00330 /**
00331  * Various ways of specifying revisions.
00332  *
00333  * @note
00334  * In contexts where local mods are relevant, the `working' kind
00335  * refers to the uncommitted "working" revision, which may be modified
00336  * with respect to its base revision.  In other contexts, `working'
00337  * should behave the same as `committed' or `current'.
00338  */
00339 enum svn_opt_revision_kind {
00340   /** No revision information given. */
00341   svn_opt_revision_unspecified,
00342 
00343   /** revision given as number */
00344   svn_opt_revision_number,
00345 
00346   /** revision given as date */
00347   svn_opt_revision_date,
00348 
00349   /** rev of most recent change */
00350   svn_opt_revision_committed,
00351 
00352   /** (rev of most recent change) - 1 */
00353   svn_opt_revision_previous,
00354 
00355   /** .svn/entries current revision */
00356   svn_opt_revision_base,
00357 
00358   /** current, plus local mods */
00359   svn_opt_revision_working,
00360 
00361   /** repository youngest */
00362   svn_opt_revision_head
00363 };
00364 
00365 /**
00366  * A revision value, which can be specified as a number or a date.
00367  *
00368  * @note This union was formerly an anonymous inline type in
00369  * @c svn_opt_revision_t, and was converted to a named type just to
00370  * make things easier for SWIG.
00371  *
00372  * @since New in 1.3.
00373  */
00374 typedef union svn_opt_revision_value_t
00375 {
00376   /** The revision number */
00377   svn_revnum_t number;
00378 
00379   /** the date of the revision */
00380   apr_time_t date;
00381 } svn_opt_revision_value_t;
00382 
00383 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
00384 typedef struct svn_opt_revision_t
00385 {
00386   enum svn_opt_revision_kind kind;  /**< See svn_opt_revision_kind */
00387   svn_opt_revision_value_t value;   /**< Extra data qualifying the @c kind */
00388 } svn_opt_revision_t;
00389 
00390 /** A revision range, specified in one of @c svn_opt_revision_kind ways. */
00391 typedef struct svn_opt_revision_range_t
00392 {
00393   /** The first revision in the range */
00394   svn_opt_revision_t start;
00395 
00396   /** The last revision in the range */
00397   svn_opt_revision_t end;
00398 } svn_opt_revision_range_t;
00399 
00400 /**
00401  * Set @a *start_revision and/or @a *end_revision according to @a arg,
00402  * where @a arg is "N" or "N:M", like so:
00403  *
00404  *    - If @a arg is "N", set @a *start_revision to represent N, and
00405  *      leave @a *end_revision untouched.
00406  *
00407  *    - If @a arg is "N:M", set @a *start_revision and @a *end_revision
00408  *      to represent N and M respectively.
00409  *
00410  * N and/or M may be one of the special revision descriptors
00411  * recognized by revision_from_word(), or a date in curly braces.
00412  *
00413  * If @a arg is invalid, return -1; else return 0.
00414  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
00415  *
00416  * @note It is typical, though not required, for @a *start_revision and
00417  * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
00418  *
00419  * Use @a pool for temporary allocations.
00420  */
00421 int
00422 svn_opt_parse_revision(svn_opt_revision_t *start_revision,
00423                        svn_opt_revision_t *end_revision,
00424                        const char *arg,
00425                        apr_pool_t *pool);
00426 
00427 /**
00428  * Parse @a arg, where @a arg is "N" or "N:M", into a
00429  * @c svn_opt_revision_range_t and push that onto @a opt_ranges.
00430  *
00431  *    - If @a arg is "N", set the @c start field of the
00432  *      @c svn_opt_revision_range_t to represent N and the @c end field
00433  *      to @c svn_opt_revision_unspecified.
00434  *
00435  *    - If @a arg is "N:M", set the @c start field of the
00436  *      @c svn_opt_revision_range_t to represent N and the @c end field
00437  *      to represent M.
00438  *
00439  * If @a arg is invalid, return -1; else return 0.  It is invalid to omit
00440  * a revision (as in, ":", "N:" or ":M").
00441  *
00442  * Use @a pool to allocate @c svn_opt_revision_range_t pushed to the array.
00443  *
00444  * @since New in 1.5.
00445  */
00446 int
00447 svn_opt_parse_revision_to_range(apr_array_header_t *opt_ranges,
00448                                 const char *arg,
00449                                 apr_pool_t *pool);
00450 
00451 /**
00452  * Resolve peg revisions and operational revisions in the following way:
00453  *
00454  *    - If @a is_url is set and @a peg_rev->kind is
00455  *      @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to
00456  *      @c svn_opt_revision_head.
00457  *
00458  *    - If @a is_url is not set, and @a peg_rev->kind is
00459  *      @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to
00460  *      @c svn_opt_revision_base.
00461  *
00462  *    - If @a op_rev->kind is @c svn_opt_revision_unspecified, @a op_rev
00463  *      defaults to @a peg_rev.
00464  *
00465  * Both @a peg_rev and @a op_rev may be modified as a result of this
00466  * function.  @a is_url should be set if the path the revisions refer to is
00467  * a url, and unset otherwise.
00468  *
00469  * If @a notice_local_mods is set, @c svn_opt_revision_working is used,
00470  * instead of @c svn_opt_revision_base.
00471  *
00472  * Use @a pool for allocations.
00473  *
00474  * @since New in 1.5.
00475  */
00476 svn_error_t *
00477 svn_opt_resolve_revisions(svn_opt_revision_t *peg_rev,
00478                           svn_opt_revision_t *op_rev,
00479                           svn_boolean_t is_url,
00480                           svn_boolean_t notice_local_mods,
00481                           apr_pool_t *pool);
00482 
00483 
00484 /* Parsing arguments. */
00485 
00486 /**
00487  * Pull remaining target arguments from @a os into @a *targets_p,
00488  * converting them to UTF-8, followed by targets from @a known_targets
00489  * (which might come from, for example, the "--targets" command line
00490  * option), which are already in UTF-8.
00491  *
00492  * On each URL target, do some IRI-to-URI encoding and some
00493  * auto-escaping.  On each local path, canonicalize case and path
00494  * separators.
00495  *
00496  * Allocate @a *targets_p and its elements in @a pool.
00497  *
00498  * If a path has the same name as a Subversion working copy
00499  * administrative directory, return SVN_ERR_RESERVED_FILENAME_SPECIFIED;
00500  * if multiple reserved paths are encountered, return a chain of
00501  * errors, all of which are SVN_ERR_RESERVED_FILENAME_SPECIFIED.  Do
00502  * not return this type of error in a chain with any other type of
00503  * error, and if this is the only type of error encountered, complete
00504  * the operation before returning the error(s).
00505  *
00506  * @deprecated Provided for backward compatibility with the 1.5 API.
00507  * @see svn_client_args_to_target_array()
00508  */
00509 SVN_DEPRECATED
00510 svn_error_t *
00511 svn_opt_args_to_target_array3(apr_array_header_t **targets_p,
00512                               apr_getopt_t *os,
00513                               apr_array_header_t *known_targets,
00514                               apr_pool_t *pool);
00515 
00516 /**
00517  * This is the same as svn_opt_args_to_target_array3() except that it
00518  * silently ignores paths that have the same name as a working copy
00519  * administrative directory.
00520  *
00521  * @since New in 1.2.
00522  *
00523  * @deprecated Provided for backward compatibility with the 1.4 API.
00524  */
00525 SVN_DEPRECATED
00526 svn_error_t *
00527 svn_opt_args_to_target_array2(apr_array_header_t **targets_p,
00528                               apr_getopt_t *os,
00529                               apr_array_header_t *known_targets,
00530                               apr_pool_t *pool);
00531 
00532 
00533 /**
00534  * The same as svn_opt_args_to_target_array2() except that, in
00535  * addition, if @a extract_revisions is set, then look for trailing
00536  * "@rev" syntax on the first two paths.  If the first target in @a
00537  * *targets_p ends in "@rev", replace it with a canonicalized version of
00538  * the part before "@rev" and replace @a *start_revision with the value
00539  * of "rev".  If the second target in @a *targets_p ends in "@rev",
00540  * replace it with a canonicalized version of the part before "@rev"
00541  * and replace @a *end_revision with the value of "rev".  Ignore
00542  * revision specifiers on any further paths.  "rev" can be any form of
00543  * single revision specifier, as accepted by svn_opt_parse_revision().
00544  *
00545  * @deprecated Provided for backward compatibility with the 1.1 API.
00546  */
00547 SVN_DEPRECATED
00548 svn_error_t *
00549 svn_opt_args_to_target_array(apr_array_header_t **targets_p,
00550                              apr_getopt_t *os,
00551                              apr_array_header_t *known_targets,
00552                              svn_opt_revision_t *start_revision,
00553                              svn_opt_revision_t *end_revision,
00554                              svn_boolean_t extract_revisions,
00555                              apr_pool_t *pool);
00556 
00557 
00558 /**
00559  * Parse revprop key/value pair from @a revprop_spec (name[=value]) into
00560  * @a revprops, making copies of both with @a pool.  If @a revprops is
00561  * @c NULL, allocate a new apr_hash_t in it.  @a revprops maps
00562  * const char * revprop names to svn_string_t * revprop values for use
00563  * with svn_repos_get_commit_editor5 and other get_commit_editor APIs.
00564  *
00565  * @since New in 1.6.
00566  */
00567 svn_error_t *
00568 svn_opt_parse_revprop(apr_hash_t **revprops, const char *revprop_spec,
00569                       apr_pool_t *pool);
00570 
00571 
00572 /**
00573  * If no targets exist in @a *targets, add `.' as the lone target.
00574  *
00575  * (Some commands take an implicit "." string argument when invoked
00576  * with no arguments. Those commands make use of this function to
00577  * add "." to the target array if the user passes no args.)
00578  */
00579 void
00580 svn_opt_push_implicit_dot_target(apr_array_header_t *targets,
00581                                  apr_pool_t *pool);
00582 
00583 
00584 /**
00585  * Parse @a num_args non-target arguments from the list of arguments in
00586  * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without
00587  * doing any UTF-8 conversion.  Allocate @a *args_p and its values in @a pool.
00588  */
00589 svn_error_t *
00590 svn_opt_parse_num_args(apr_array_header_t **args_p,
00591                        apr_getopt_t *os,
00592                        int num_args,
00593                        apr_pool_t *pool);
00594 
00595 
00596 /**
00597  * Parse all remaining arguments from @a os->argv, return them as
00598  * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
00599  * Allocate @a *args_p and its values in @a pool.
00600  */
00601 svn_error_t *
00602 svn_opt_parse_all_args(apr_array_header_t **args_p,
00603                        apr_getopt_t *os,
00604                        apr_pool_t *pool);
00605 
00606 /**
00607  * Parse a working-copy or URL in @a path, extracting any trailing
00608  * revision specifier of the form "@rev" from the last component of
00609  * the path.
00610  *
00611  * Some examples would be:
00612  *
00613  *    "foo/bar"                      -> "foo/bar",       (unspecified)
00614  *    "foo/bar@13"                   -> "foo/bar",       (number, 13)
00615  *    "foo/bar@HEAD"                 -> "foo/bar",       (head)
00616  *    "foo/bar@{1999-12-31}"         -> "foo/bar",       (date, 1999-12-31)
00617  *    "http://a/b@27"                -> "http://a/b",    (number, 27)
00618  *    "http://a/b@COMMITTED"         -> "http://a/b",    (committed) [*]
00619  *    "http://a/b@{1999-12-31}       -> "http://a/b",    (date, 1999-12-31)
00620  *    "http://a/b@%7B1999-12-31%7D   -> "http://a/b",    (date, 1999-12-31)
00621  *    "foo/bar@1:2"                  -> error
00622  *    "foo/bar@baz"                  -> error
00623  *    "foo/bar@"                     -> "foo/bar",       (base)
00624  *    "foo/@bar@"                    -> "foo/@bar",      (base)
00625  *    "foo/bar/@13"                  -> "foo/bar/",      (number, 13)
00626  *    "foo/bar@@13"                  -> "foo/bar@",      (number, 13)
00627  *    "foo/@bar@HEAD"                -> "foo/@bar",      (head)
00628  *    "foo@/bar"                     -> "foo@/bar",      (unspecified)
00629  *    "foo@HEAD/bar"                 -> "foo@HEAD/bar",  (unspecified)
00630  *    "@foo/bar"                     -> error
00631  *    "@foo/bar@"                    -> "@foo/bar",      (unspecified)
00632  *
00633  *   [*] Syntactically valid but probably not semantically useful.
00634  *
00635  * If a trailing revision specifier is found, parse it into @a *rev and
00636  * put the rest of the path into @a *truepath, allocating from @a pool;
00637  * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR (with the effect on
00638  * @a *truepath undefined) if the revision specifier is invalid.
00639  * If no trailing revision specifier is found, set @a *truepath to
00640  * @a path and @a rev->kind to @c svn_opt_revision_unspecified.
00641  *
00642  * This function does not require that @a path be in canonical form.
00643  * No canonicalization is done and @a *truepath will only be in
00644  * canonical form if @a path is in canonical form.
00645  *
00646  * @since New in 1.1.
00647  */
00648 svn_error_t *
00649 svn_opt_parse_path(svn_opt_revision_t *rev,
00650                    const char **truepath,
00651                    const char *path,
00652                    apr_pool_t *pool);
00653 
00654 /**
00655  * Central dispatcher function for various kinds of help message.
00656  * Prints one of:
00657  *   * subcommand-specific help (svn_opt_subcommand_help)
00658  *   * generic help (svn_opt_print_generic_help)
00659  *   * version info
00660  *   * simple usage complaint: "Type '@a pgm_name help' for usage."
00661  *
00662  * If @a os is not @c NULL and it contains arguments, then try
00663  * printing help for them as though they are subcommands, using @a
00664  * cmd_table and @a option_table for option information.  If not @c
00665  * NULL, @a global_options is a zero-terminated array of options taken
00666  * by all subcommands.
00667  *
00668  * Else, if @a print_version is TRUE, then print version info, in
00669  * brief form if @a quiet is also TRUE; if @a quiet is FALSE, then if
00670  * @a version_footer is non-NULL, print it following the version
00671  * information.
00672  *
00673  * Else, if @a os is not @c NULL and does not contain arguments, print
00674  * generic help, via svn_opt_print_generic_help2() with the @a header,
00675  * @a cmd_table, @a option_table, and @a footer arguments.
00676  *
00677  * Else, when @a os is @c NULL, print the simple usage complaint.
00678  *
00679  * Use @a pool for temporary allocations.
00680  *
00681  * Notes: The reason this function handles both version printing and
00682  * general usage help is that a confused user might put both the
00683  * --version flag *and* subcommand arguments on a help command line.
00684  * The logic for handling such a situation should be in one place.
00685  *
00686  * @since New in 1.5.
00687  */
00688 svn_error_t *
00689 svn_opt_print_help3(apr_getopt_t *os,
00690                     const char *pgm_name,
00691                     svn_boolean_t print_version,
00692                     svn_boolean_t quiet,
00693                     const char *version_footer,
00694                     const char *header,
00695                     const svn_opt_subcommand_desc2_t *cmd_table,
00696                     const apr_getopt_option_t *option_table,
00697                     const int *global_options,
00698                     const char *footer,
00699                     apr_pool_t *pool);
00700 
00701 /**
00702  * Same as svn_opt_print_help3(), but with @a global_options always @c
00703  * NULL.
00704  *
00705  * @deprecated Provided for backward compatibility with the 1.4 API.
00706  */
00707 
00708 SVN_DEPRECATED
00709 svn_error_t *
00710 svn_opt_print_help2(apr_getopt_t *os,
00711                     const char *pgm_name,
00712                     svn_boolean_t print_version,
00713                     svn_boolean_t quiet,
00714                     const char *version_footer,
00715                     const char *header,
00716                     const svn_opt_subcommand_desc2_t *cmd_table,
00717                     const apr_getopt_option_t *option_table,
00718                     const char *footer,
00719                     apr_pool_t *pool);
00720 
00721 
00722 /**
00723  * Same as svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t.
00724  *
00725  * @deprecated Provided for backward compatibility with the 1.3 API.
00726  */
00727 SVN_DEPRECATED
00728 svn_error_t *
00729 svn_opt_print_help(apr_getopt_t *os,
00730                    const char *pgm_name,
00731                    svn_boolean_t print_version,
00732                    svn_boolean_t quiet,
00733                    const char *version_footer,
00734                    const char *header,
00735                    const svn_opt_subcommand_desc_t *cmd_table,
00736                    const apr_getopt_option_t *option_table,
00737                    const char *footer,
00738                    apr_pool_t *pool);
00739 
00740 #ifdef __cplusplus
00741 }
00742 #endif /* __cplusplus */
00743 
00744 #endif /* SVN_OPTS_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines