svn_opt.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 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 
00029 #include "svn_types.h"
00030 #include "svn_error.h"
00031 
00032 #ifdef __cplusplus
00033 extern "C" {
00034 #endif /* __cplusplus */
00035 
00036 
00037 
00038 /**
00039  * All subcommand procedures in Subversion conform to this prototype.
00040  *
00041  * @a os is the apr option state after getopt processing has been run; in
00042  * other words, it still contains the non-option arguments following
00043  * the subcommand.  See @a os->argv and @a os->ind.
00044  *
00045  * @a baton is anything you need it to be.
00046  * 
00047  * @a pool is used for allocating errors, and for any other allocation
00048  * unless the instance is explicitly documented to allocate from a
00049  * pool in @a baton.
00050  */
00051 typedef svn_error_t *(svn_opt_subcommand_t)
00052        (apr_getopt_t *os, void *baton, apr_pool_t *pool);
00053 
00054 
00055 /** The maximum number of aliases a subcommand can have. */
00056 #define SVN_OPT_MAX_ALIASES 3
00057 
00058 /** The maximum number of options that can be accepted by a subcommand. */
00059 #define SVN_OPT_MAX_OPTIONS 50
00060 
00061 /** Options that have no short option char should use an identifying
00062  * integer equal to or greater than this.
00063  */
00064 #define SVN_OPT_FIRST_LONGOPT_ID 256
00065 
00066 
00067 /** One element of a subcommand dispatch table.
00068  *
00069  * @since New in 1.4.
00070  */
00071 typedef struct svn_opt_subcommand_desc2_t
00072 {
00073   /** The full name of this command. */
00074   const char *name;
00075 
00076   /** The function this command invokes. */
00077   svn_opt_subcommand_t *cmd_func;
00078 
00079   /** A list of alias names for this command (e.g., 'up' for 'update'). */
00080   const char *aliases[SVN_OPT_MAX_ALIASES];
00081 
00082   /** A brief string describing this command, for usage messages. */
00083   const char *help;
00084 
00085   /** A list of options accepted by this command.  Each value in the
00086    * array is a unique enum (the 2nd field in apr_getopt_option_t)
00087    */
00088   int valid_options[SVN_OPT_MAX_OPTIONS];
00089 
00090   /** A list of option help descriptions, keyed by the option unique enum
00091    * (the 2nd field in apr_getopt_option_t), which override the generic
00092    * descriptions given in an apr_getopt_option_t on a per-subcommand basis.
00093    */
00094   struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS];
00095 } svn_opt_subcommand_desc2_t;
00096 
00097 
00098 /** One element of a subcommand dispatch table.
00099  *
00100  * @deprecated Provided for backward compatibility with the 1.3 API.
00101  *
00102  * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides
00103  * member.
00104  */
00105 typedef struct svn_opt_subcommand_desc_t
00106 {
00107   /** The full name of this command. */
00108   const char *name;
00109 
00110   /** The function this command invokes. */
00111   svn_opt_subcommand_t *cmd_func;
00112 
00113   /** A list of alias names for this command (e.g., 'up' for 'update'). */
00114   const char *aliases[SVN_OPT_MAX_ALIASES];
00115 
00116   /** A brief string describing this command, for usage messages. */
00117   const char *help;
00118 
00119   /** A list of options accepted by this command.  Each value in the
00120    * array is a unique enum (the 2nd field in apr_getopt_option_t)
00121    */
00122   int valid_options[SVN_OPT_MAX_OPTIONS];
00123 
00124 } svn_opt_subcommand_desc_t;
00125 
00126 
00127 /**
00128  * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if 
00129  * none.  @a cmd_name may be an alias.
00130  *
00131  * @since New in 1.4.
00132  */  
00133 const svn_opt_subcommand_desc2_t *
00134 svn_opt_get_canonical_subcommand2(const svn_opt_subcommand_desc2_t *table,
00135                                   const char *cmd_name);
00136 
00137 
00138 /**
00139  * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if 
00140  * none.  @a cmd_name may be an alias.
00141  *
00142  * Same as svn_opt_get_canonical_subcommand2(), but acts on
00143  * #svn_opt_subcommand_desc_t.
00144  *
00145  * @deprecated Provided for backward compatibility with the 1.3 API.
00146  */  
00147 const svn_opt_subcommand_desc_t *
00148 svn_opt_get_canonical_subcommand(const svn_opt_subcommand_desc_t *table,
00149                                  const char *cmd_name);
00150 
00151 
00152 /**
00153  * Return pointer to an @c apr_getopt_option_t for the option whose 
00154  * option code is @a code, or @c NULL if no match.  @a option_table must end
00155  * with an element whose every field is zero.  If @c command is non-NULL,
00156  * then the subcommand-specific option description instead of the generic one,
00157  * if a specific description is defined.
00158  *
00159  * The returned value may be statically allocated, or allocated in @a pool.
00160  *
00161  * @since New in 1.4.
00162  */
00163 const apr_getopt_option_t *
00164 svn_opt_get_option_from_code2(int code,
00165                               const apr_getopt_option_t *option_table,
00166                               const svn_opt_subcommand_desc2_t *command,
00167                               apr_pool_t *pool);
00168 
00169 
00170 /**
00171  * Return the first entry from @a option_table whose option code is @a code,
00172  * or @c NULL if no match.  @a option_table must end with an element whose
00173  * every field is zero.
00174  *
00175  * @deprecated Provided for backward compatibility with the 1.3 API.
00176  */
00177 const apr_getopt_option_t *
00178 svn_opt_get_option_from_code(int code,
00179                              const apr_getopt_option_t *option_table);
00180 
00181 
00182 /**
00183  * Return @c TRUE iff subcommand @a command supports option @a option_code,
00184  * else return @c FALSE.
00185  *
00186  * @since New in 1.4.
00187  */
00188 svn_boolean_t
00189 svn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t *command,
00190                                  int option_code);
00191 
00192 
00193 /**
00194  * Return @c TRUE iff subcommand @a command supports option @a option_code,
00195  * else return @c FALSE.
00196  *
00197  * Same as svn_opt_subcommand_takes_option2(), but acts on
00198  * #svn_opt_subcommand_desc_t.
00199  *
00200  * @deprecated Provided for backward compatibility with the 1.3 API.
00201  */
00202 svn_boolean_t
00203 svn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t *command,
00204                                 int option_code);
00205 
00206 
00207 /**
00208  * Print a generic (not command-specific) usage message to @a stream.
00209  *
00210  * (### todo: why is @a stream a stdio file instead of an svn stream?)
00211  *
00212  * If @a header is non-null, print @a header followed by a newline.  Then
00213  * loop over @a cmd_table printing the usage for each command (getting
00214  * option usages from @a opt_table).  Then if @a footer is non-null, print
00215  * @a footer followed by a newline.
00216  *
00217  * Use @a pool for temporary allocation.
00218  *
00219  * @since New in 1.4.
00220  */
00221 void
00222 svn_opt_print_generic_help2(const char *header,
00223                             const svn_opt_subcommand_desc2_t *cmd_table,
00224                             const apr_getopt_option_t *opt_table,
00225                             const char *footer,
00226                             apr_pool_t *pool,
00227                             FILE *stream);
00228 
00229 
00230 /* Same as svn_opt_print_generic_help2(), but acts on
00231  * #svn_opt_subcommand_desc_t.
00232  *
00233  * @deprecated Provided for backward compatibility with the 1.3 API.
00234  */
00235 void
00236 svn_opt_print_generic_help(const char *header,
00237                            const svn_opt_subcommand_desc_t *cmd_table,
00238                            const apr_getopt_option_t *opt_table,
00239                            const char *footer,
00240                            apr_pool_t *pool,
00241                            FILE *stream);
00242 
00243 
00244 /**
00245  * Print an option @a opt nicely into a @a string allocated in @a pool.  
00246  * If @a doc is set, include the generic documentation string of @a opt,
00247  * localized to the current locale if a translation is available.
00248  */
00249 void
00250 svn_opt_format_option(const char **string,
00251                       const apr_getopt_option_t *opt,
00252                       svn_boolean_t doc,
00253                       apr_pool_t *pool);
00254 
00255 
00256 
00257 /**
00258  * Get @a subcommand's usage from @a table, and print it to @c stdout.  
00259  * Obtain option usage from @a options_table.  Use @a pool for temporary
00260  * allocation.  @a subcommand may be a canonical command name or an
00261  * alias.  (### todo: why does this only print to @c stdout, whereas
00262  * svn_opt_print_generic_help() gives us a choice?)
00263  *
00264  * @since New in 1.4.
00265  */
00266 void
00267 svn_opt_subcommand_help2(const char *subcommand, 
00268                          const svn_opt_subcommand_desc2_t *table,
00269                          const apr_getopt_option_t *options_table,
00270                          apr_pool_t *pool);
00271 
00272 
00273 /**
00274  * Same as svn_opt_subcommand_help2(), but acts on
00275  * #svn_opt_subcommand_desc_t.
00276  *
00277  * @deprecated Provided for backward compatibility with the 1.3 API.
00278  */
00279 void
00280 svn_opt_subcommand_help(const char *subcommand, 
00281                         const svn_opt_subcommand_desc_t *table,
00282                         const apr_getopt_option_t *options_table,
00283                         apr_pool_t *pool);
00284 
00285 
00286 
00287 /* Parsing revision and date options. */
00288 
00289 /**
00290  * Various ways of specifying revisions. 
00291  *
00292  * @note
00293  * In contexts where local mods are relevant, the `working' kind
00294  * refers to the uncommitted "working" revision, which may be modified
00295  * with respect to its base revision.  In other contexts, `working'
00296  * should behave the same as `committed' or `current'.
00297  */
00298 enum svn_opt_revision_kind {
00299   /** No revision information given. */
00300   svn_opt_revision_unspecified,
00301 
00302   /** revision given as number */
00303   svn_opt_revision_number,
00304 
00305   /** revision given as date */
00306   svn_opt_revision_date,
00307 
00308   /** rev of most recent change */
00309   svn_opt_revision_committed,
00310 
00311   /** (rev of most recent change) - 1 */
00312   svn_opt_revision_previous,
00313 
00314   /** .svn/entries current revision */
00315   svn_opt_revision_base,
00316 
00317   /** current, plus local mods */
00318   svn_opt_revision_working,
00319 
00320   /** repository youngest */
00321   svn_opt_revision_head
00322 };
00323 
00324 /**
00325  * A revision value, which can be specified as a number or a date.
00326  *
00327  * @note This union was formerly an anonymous inline type in
00328  * @c svn_opt_revision_t, and was converted to a named type just to
00329  * make things easier for SWIG.
00330  *
00331  * @since New in 1.3.
00332  */
00333 typedef union svn_opt_revision_value_t
00334 {
00335   svn_revnum_t number;
00336   apr_time_t date;
00337 } svn_opt_revision_value_t;
00338 
00339 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
00340 typedef struct svn_opt_revision_t
00341 {
00342   enum svn_opt_revision_kind kind;  /**< See svn_opt_revision_kind */
00343   svn_opt_revision_value_t value;   /**< Extra data qualifying the @c kind */
00344 } svn_opt_revision_t;
00345 
00346 
00347 /**
00348  * Set @a *start_revision and/or @a *end_revision according to @a arg, 
00349  * where @a arg is "N" or "N:M", like so:
00350  * 
00351  *    - If @a arg is "N", set @a *start_revision to represent N, and
00352  *      leave @a *end_revision untouched.
00353  *
00354  *    - If @a arg is "N:M", set @a *start_revision and @a *end_revision
00355  *      to represent N and M respectively. 
00356  * 
00357  * N and/or M may be one of the special revision descriptors
00358  * recognized by revision_from_word(), or a date in curly braces.
00359  *
00360  * If @a arg is invalid, return -1; else return 0.
00361  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
00362  *
00363  * @note It is typical, though not required, for @a *start_revision and
00364  * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
00365  *
00366  * Use @a pool for temporary allocations.
00367  */
00368 int svn_opt_parse_revision(svn_opt_revision_t *start_revision,
00369                            svn_opt_revision_t *end_revision,
00370                            const char *arg,
00371                            apr_pool_t *pool);
00372 
00373 
00374 
00375 /* Parsing arguments. */
00376 
00377 /**
00378  * Pull remaining target arguments from @a os into @a *targets_p,
00379  * converting them to UTF-8, followed by targets from @a known_targets
00380  * (which might come from, for example, the "--targets" command line
00381  * option), which are already in UTF-8.
00382  *
00383  * On each URL target, do some IRI-to-URI encoding and some
00384  * auto-escaping.  On each local path, canonicalize case and path
00385  * separators, and silently skip it if it has the same name as a
00386  * Subversion working copy administrative directory.
00387  *
00388  * Allocate @a *targets_p and its elements in @a pool.
00389  *
00390  * @since New in 1.2.
00391  */
00392 svn_error_t *
00393 svn_opt_args_to_target_array2(apr_array_header_t **targets_p,
00394                               apr_getopt_t *os,
00395                               apr_array_header_t *known_targets,
00396                               apr_pool_t *pool);
00397 
00398 
00399 /**
00400  * The same as svn_opt_args_to_target_array2() except that, in
00401  * addition, if @a extract_revisions is set, then look for trailing
00402  * "@rev" syntax on the first two paths.  If the first target in @a
00403  * *targets_p ends in "@rev", replace it with a canonicalized version of
00404  * the part before "@rev" and replace @a *start_revision with the value
00405  * of "rev".  If the second target in @a *targets_p ends in "@rev",
00406  * replace it with a canonicalized version of the part before "@rev"
00407  * and replace @a *end_revision with the value of "rev".  Ignore
00408  * revision specifiers on any further paths.  "rev" can be any form of
00409  * single revision specifier, as accepted by svn_opt_parse_revision().
00410  *
00411  * @deprecated Provided for backward compatibility with the 1.1 API.
00412  */
00413 svn_error_t *
00414 svn_opt_args_to_target_array(apr_array_header_t **targets_p,
00415                              apr_getopt_t *os,
00416                              apr_array_header_t *known_targets,
00417                              svn_opt_revision_t *start_revision,
00418                              svn_opt_revision_t *end_revision,
00419                              svn_boolean_t extract_revisions,
00420                              apr_pool_t *pool);
00421 
00422 
00423 /**
00424  * If no targets exist in @a *targets, add `.' as the lone target.
00425  *
00426  * (Some commands take an implicit "." string argument when invoked
00427  * with no arguments. Those commands make use of this function to
00428  * add "." to the target array if the user passes no args.)
00429  */
00430 void svn_opt_push_implicit_dot_target(apr_array_header_t *targets,
00431                                       apr_pool_t *pool);
00432 
00433 
00434 /**
00435  * Parse @a num_args non-target arguments from the list of arguments in
00436  * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without 
00437  * doing any UTF-8 conversion.  Allocate @a *args_p and its values in @a pool.
00438  */
00439 svn_error_t *
00440 svn_opt_parse_num_args(apr_array_header_t **args_p,
00441                        apr_getopt_t *os,
00442                        int num_args,
00443                        apr_pool_t *pool);
00444 
00445 
00446 /**
00447  * Parse all remaining arguments from @a os->argv, return them as
00448  * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
00449  * Allocate @a *args_p and its values in @a pool.
00450  */
00451 svn_error_t *
00452 svn_opt_parse_all_args(apr_array_header_t **args_p,
00453                        apr_getopt_t *os,
00454                        apr_pool_t *pool);
00455 
00456 /**
00457  * Parse a working-copy or URL in @a path, extracting any trailing
00458  * revision specifier of the form "@rev" from the last component of
00459  * the path.
00460  *
00461  * Some examples would be:
00462  *
00463  *    "foo/bar"                      -> "foo/bar",       (unspecified)
00464  *    "foo/bar@13"                   -> "foo/bar",       (number, 13)
00465  *    "foo/bar@HEAD"                 -> "foo/bar",       (head)
00466  *    "foo/bar@{1999-12-31}"         -> "foo/bar",       (date, 1999-12-31)
00467  *    "http://a/b@27"                -> "http://a/b",    (number, 27)
00468  *    "http://a/b@COMMITTED"         -> "http://a/b",    (committed) [*]
00469  *    "http://a/b@{1999-12-31}       -> "http://a/b",    (date, 1999-12-31)
00470  *    "http://a/b@%7B1999-12-31%7D   -> "http://a/b",    (date, 1999-12-31)
00471  *    "foo/bar@1:2"                  -> error
00472  *    "foo/bar@baz"                  -> error
00473  *    "foo/bar@"                     -> error
00474  *    "foo/bar/@13"                  -> "foo/bar",       (number, 13)
00475  *    "foo/bar@@13"                  -> "foo/bar@",      (number, 13)
00476  *    "foo/@bar@HEAD"                -> "foo/@bar",      (head)
00477  *    "foo@/bar"                     -> "foo@/bar",      (unspecified)
00478  *    "foo@HEAD/bar"                 -> "foo@HEAD/bar",  (unspecified)
00479  *
00480  *   [*] Syntactically valid but probably not semantically useful.
00481  *
00482  * If a trailing revision specifier is found, parse it into @a *rev and
00483  * put the rest of the path into @a *truepath, allocating from @a pool;
00484  * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR if the revision
00485  * specifier is invalid.  If no trailing revision specifier is found,
00486  * set @a *truepath to @a path and @a rev->kind to @c
00487  * svn_opt_revision_unspecified.
00488  *
00489  * @since New in 1.1.
00490  */
00491 svn_error_t *
00492 svn_opt_parse_path(svn_opt_revision_t *rev,
00493                    const char **truepath,
00494                    const char *path,
00495                    apr_pool_t *pool);
00496 
00497 /**
00498  * Print either generic help, or command-specific help for @a pgm_name.
00499  * If there are arguments in @a os, then try printing help for them as
00500  * though they are subcommands, using  @a cmd_table and @a option_table 
00501  * for option information.
00502  *
00503  * If @a os is @c NULL, or there are no targets in @a os, then:
00504  *
00505  *    - If @a print_version is true, then print version info, in brief
00506  *      form if @a quiet is also true; if @a quiet is false, then if
00507  *      @a version_footer is non-null, print it following the version
00508  *      information.
00509  *
00510  *    - Else if @a print_version is not true, then print generic help,
00511  *      via svn_opt_print_generic_help2() with the @a header, @a cmd_table,
00512  *      @a option_table, and @a footer arguments.
00513  *
00514  * Use @a pool for temporary allocations.
00515  *
00516  * Notes: The reason this function handles both version printing and
00517  * general usage help is that a confused user might put both the
00518  * --version flag *and* subcommand arguments on a help command line.
00519  * The logic for handling such a situation should be in one place.
00520  *
00521  * @since New in 1.4.
00522  */
00523 svn_error_t *
00524 svn_opt_print_help2(apr_getopt_t *os,
00525                     const char *pgm_name,
00526                     svn_boolean_t print_version,
00527                     svn_boolean_t quiet,
00528                     const char *version_footer,
00529                     const char *header,
00530                     const svn_opt_subcommand_desc2_t *cmd_table,
00531                     const apr_getopt_option_t *option_table,
00532                     const char *footer,
00533                     apr_pool_t *pool);
00534 
00535 
00536 /* Same as vn_opt_print_help2), but acts on #svn_opt_subcommand_desc_t.
00537  *
00538  * @deprecated Provided for backward compatibility with the 1.3 API.
00539  */
00540 svn_error_t *
00541 svn_opt_print_help(apr_getopt_t *os,
00542                    const char *pgm_name,
00543                    svn_boolean_t print_version,
00544                    svn_boolean_t quiet,
00545                    const char *version_footer,
00546                    const char *header,
00547                    const svn_opt_subcommand_desc_t *cmd_table,
00548                    const apr_getopt_option_t *option_table,
00549                    const char *footer,
00550                    apr_pool_t *pool);
00551 
00552 #ifdef __cplusplus
00553 }
00554 #endif /* __cplusplus */
00555 
00556 #endif /* SVN_OPTS_H */

Generated on Thu Aug 6 17:28:24 2009 for Subversion by  doxygen 1.5.1