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 typedef struct svn_opt_subcommand_desc_t
00069 {
00070   /** The full name of this command. */
00071   const char *name;
00072 
00073   /** The function this command invokes. */
00074   svn_opt_subcommand_t *cmd_func;
00075 
00076   /** A list of alias names for this command (e.g., 'up' for 'update'). */
00077   const char *aliases[SVN_OPT_MAX_ALIASES];
00078 
00079   /** A brief string describing this command, for usage messages. */
00080   const char *help;
00081 
00082   /** A list of options accepted by this command.  Each value in the
00083    * array is a unique enum (the 2nd field in apr_getopt_option_t)
00084    */
00085   int valid_options[SVN_OPT_MAX_OPTIONS];
00086 
00087 } svn_opt_subcommand_desc_t;
00088 
00089 
00090 /**
00091  * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if 
00092  * none.  @a cmd_name may be an alias.
00093  */  
00094 const svn_opt_subcommand_desc_t *
00095 svn_opt_get_canonical_subcommand (const svn_opt_subcommand_desc_t *table,
00096                                   const char *cmd_name);
00097 
00098 
00099 /**
00100  * Return the first entry from @a option_table whose option code is @a code,
00101  * or @c NULL if no match.  @a option_table must end with an element whose
00102  * every field is zero.
00103  */
00104 const apr_getopt_option_t *
00105 svn_opt_get_option_from_code (int code,
00106                               const apr_getopt_option_t *option_table);
00107 
00108 
00109 /**
00110  * Return @c TRUE iff subcommand @a command supports option @a option_code,
00111  * else return @c FALSE.
00112  */
00113 svn_boolean_t
00114 svn_opt_subcommand_takes_option (const svn_opt_subcommand_desc_t *command,
00115                                  int option_code);
00116 
00117 
00118 /**
00119  * Print a generic (not command-specific) usage message to @a stream.
00120  *
00121  * (### todo: why is @a stream a stdio file instead of an svn stream?)
00122  *
00123  * If @a header is non-null, print @a header followed by a newline.  Then
00124  * loop over @a cmd_table printing the usage for each command (getting
00125  * option usages from @a opt_table).  Then if @a footer is non-null, print
00126  * @a footer followed by a newline.
00127  *
00128  * Use @a pool for temporary allocation.
00129  */
00130 void
00131 svn_opt_print_generic_help (const char *header,
00132                             const svn_opt_subcommand_desc_t *cmd_table,
00133                             const apr_getopt_option_t *opt_table,
00134                             const char *footer,
00135                             apr_pool_t *pool,
00136                             FILE *stream);
00137 
00138 
00139 /**
00140  * Print an option @a opt nicely into a @a string allocated in @a pool.  
00141  * If @a doc is set, include the generic documentation string of @a opt,
00142  * localized to the current locale if a translation is available.
00143  */
00144 void
00145 svn_opt_format_option (const char **string,
00146                        const apr_getopt_option_t *opt,
00147                        svn_boolean_t doc,
00148                        apr_pool_t *pool);
00149 
00150 
00151 
00152 /**
00153  * Get @a subcommand's usage from @a table, and print it to @c stdout.  
00154  * Obtain option usage from @a options_table.  Use @a pool for temporary
00155  * allocation.  @a subcommand may be a canonical command name or an
00156  * alias.  (### todo: why does this only print to @c stdout, whereas
00157  * svn_opt_print_generic_help() gives us a choice?)
00158  */
00159 void
00160 svn_opt_subcommand_help (const char *subcommand, 
00161                          const svn_opt_subcommand_desc_t *table,
00162                          const apr_getopt_option_t *options_table,
00163                          apr_pool_t *pool);
00164 
00165 
00166 
00167 /* Parsing revision and date options. */
00168 
00169 /**
00170  * Various ways of specifying revisions. 
00171  *
00172  * @note
00173  * In contexts where local mods are relevant, the `working' kind
00174  * refers to the uncommitted "working" revision, which may be modified
00175  * with respect to its base revision.  In other contexts, `working'
00176  * should behave the same as `committed' or `current'.
00177  */
00178 enum svn_opt_revision_kind {
00179   /** No revision information given. */
00180   svn_opt_revision_unspecified,
00181 
00182   /** revision given as number */
00183   svn_opt_revision_number,
00184 
00185   /** revision given as date */
00186   svn_opt_revision_date,
00187 
00188   /** rev of most recent change */
00189   svn_opt_revision_committed,
00190 
00191   /** (rev of most recent change) - 1 */
00192   svn_opt_revision_previous,
00193 
00194   /** .svn/entries current revision */
00195   svn_opt_revision_base,
00196 
00197   /** current, plus local mods */
00198   svn_opt_revision_working,
00199 
00200   /** repository youngest */
00201   svn_opt_revision_head
00202 };
00203 
00204 /**
00205  * A revision value, which can be specified as a number or a date.
00206  *
00207  * @note This union was formerly an anonymous inline type in
00208  * @c svn_opt_revision_t, and was converted to a named type just to
00209  * make things easier for SWIG.
00210  *
00211  * @since New in 1.3.
00212  */
00213 typedef union svn_opt_revision_value_t
00214 {
00215   svn_revnum_t number;
00216   apr_time_t date;
00217 } svn_opt_revision_value_t;
00218 
00219 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
00220 typedef struct svn_opt_revision_t
00221 {
00222   enum svn_opt_revision_kind kind;  /**< See svn_opt_revision_kind */
00223   svn_opt_revision_value_t value;   /**< Extra data qualifying the @c kind */
00224 } svn_opt_revision_t;
00225 
00226 
00227 /**
00228  * Set @a *start_revision and/or @a *end_revision according to @a arg, 
00229  * where @a arg is "N" or "N:M", like so:
00230  * 
00231  *    - If @a arg is "N", set @a *start_revision to represent N, and
00232  *      leave @a *end_revision untouched.
00233  *
00234  *    - If @a arg is "N:M", set @a *start_revision and @a *end_revision
00235  *      to represent N and M respectively. 
00236  * 
00237  * N and/or M may be one of the special revision descriptors
00238  * recognized by revision_from_word(), or a date in curly braces.
00239  *
00240  * If @a arg is invalid, return -1; else return 0.
00241  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
00242  *
00243  * @note It is typical, though not required, for @a *start_revision and
00244  * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
00245  *
00246  * Use @a pool for temporary allocations.
00247  */
00248 int svn_opt_parse_revision (svn_opt_revision_t *start_revision,
00249                             svn_opt_revision_t *end_revision,
00250                             const char *arg,
00251                             apr_pool_t *pool);
00252 
00253 
00254 
00255 /* Parsing arguments. */
00256 
00257 /**
00258  * Pull remaining target arguments from @a os into @a *targets_p,
00259  * converting them to UTF-8, followed by targets from @a known_targets
00260  * (which might come from, for example, the "--targets" command line
00261  * option), which are already in UTF-8.
00262  *
00263  * On each URL target, do some IRI-to-URI encoding and some
00264  * auto-escaping.  On each local path, canonicalize case and path
00265  * separators, and silently skip it if it has the same name as a
00266  * Subversion working copy administrative directory.
00267  *
00268  * Allocate @a *targets_p and its elements in @a pool.
00269  *
00270  * @since New in 1.2.
00271  */
00272 svn_error_t *
00273 svn_opt_args_to_target_array2 (apr_array_header_t **targets_p,
00274                                apr_getopt_t *os,
00275                                apr_array_header_t *known_targets,
00276                                apr_pool_t *pool);
00277 
00278 
00279 /**
00280  * The same as svn_opt_args_to_target_array2() except that, in
00281  * addition, if @a extract_revisions is set, then look for trailing
00282  * "@rev" syntax on the first two paths.  If the first target in @a
00283  * *targets_p ends in "@rev", replace it with a canonicalized version of
00284  * the part before "@rev" and replace @a *start_revision with the value
00285  * of "rev".  If the second target in @a *targets_p ends in "@rev",
00286  * replace it with a canonicalized version of the part before "@rev"
00287  * and replace @a *end_revision with the value of "rev".  Ignore
00288  * revision specifiers on any further paths.  "rev" can be any form of
00289  * single revision specifier, as accepted by svn_opt_parse_revision().
00290  *
00291  * @deprecated Provided for backward compatibility with the 1.1 API.
00292  */
00293 svn_error_t *
00294 svn_opt_args_to_target_array (apr_array_header_t **targets_p,
00295                               apr_getopt_t *os,
00296                               apr_array_header_t *known_targets,
00297                               svn_opt_revision_t *start_revision,
00298                               svn_opt_revision_t *end_revision,
00299                               svn_boolean_t extract_revisions,
00300                               apr_pool_t *pool);
00301 
00302 
00303 /**
00304  * If no targets exist in @a *targets, add `.' as the lone target.
00305  *
00306  * (Some commands take an implicit "." string argument when invoked
00307  * with no arguments. Those commands make use of this function to
00308  * add "." to the target array if the user passes no args.)
00309  */
00310 void svn_opt_push_implicit_dot_target (apr_array_header_t *targets,
00311                                        apr_pool_t *pool);
00312 
00313 
00314 /**
00315  * Parse @a num_args non-target arguments from the list of arguments in
00316  * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without 
00317  * doing any UTF-8 conversion.  Allocate @a *args_p and its values in @a pool.
00318  */
00319 svn_error_t *
00320 svn_opt_parse_num_args (apr_array_header_t **args_p,
00321                         apr_getopt_t *os,
00322                         int num_args,
00323                         apr_pool_t *pool);
00324 
00325 
00326 /**
00327  * Parse all remaining arguments from @a os->argv, return them as
00328  * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
00329  * Allocate @a *args_p and its values in @a pool.
00330  */
00331 svn_error_t *
00332 svn_opt_parse_all_args (apr_array_header_t **args_p,
00333                         apr_getopt_t *os,
00334                         apr_pool_t *pool);
00335 
00336 /**
00337  * Parse a working-copy or URL in @a path, extracting any trailing
00338  * revision specifier of the form "@rev" from the last component of
00339  * the path.
00340  *
00341  * Some examples would be:
00342  *
00343  *   - foo/bar               -> "foo/bar",       (unspecified)
00344  *   - foo/bar@@13           -> "foo/bar",       (number, 13)
00345  *   - foo/bar@@HEAD         -> "foo/bar",       (head)
00346  *   - foo/bar@@{1999-12-31} -> "foo/bar",       (date, 1999-12-31)
00347  *   - http://a/b@27         -> "http://a/b",    (number, 27) 
00348  *   - http://a/b@COMMITTED  -> "http://a/b",    (committed) [*]
00349  *   - foo/bar@@1:2          -> error
00350  *   - foo/bar@@baz          -> error
00351  *   - foo/bar@              -> error
00352  *   - foo/bar/@@13          -> "foo/bar",       (number, 13)
00353  *   - foo/bar@@13           -> "foo/bar@",     (number, 13)
00354  *   - foo/@@bar@@HEAD       -> "foo/@bar",     (head)
00355  *   - foo@/bar              -> "foo@/bar",     (unspecified)
00356  *   - foo@@HEAD/bar         -> "foo@HEAD/bar", (unspecified)
00357  *
00358  *   [*] Syntactically valid but probably not semantically useful.
00359  *
00360  * If a trailing revision specifier is found, parse it into @a *rev and
00361  * put the rest of the path into @a *truepath, allocating from @a pool;
00362  * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR if the revision
00363  * specifier is invalid.  If no trailing revision specifier is found,
00364  * set @a *truepath to @a path and @a rev->kind to @c
00365  * svn_opt_revision_unspecified.
00366  *
00367  * @since New in 1.1.
00368  */
00369 svn_error_t *
00370 svn_opt_parse_path (svn_opt_revision_t *rev,
00371                     const char **truepath,
00372                     const char *path,
00373                     apr_pool_t *pool);
00374 
00375 /**
00376  * Print either generic help, or command-specific help for @a pgm_name.
00377  * If there are arguments in @a os, then try printing help for them as
00378  * though they are subcommands, using  @a cmd_table and @a option_table 
00379  * for option information.
00380  *
00381  * If @a os is @c NULL, or there are no targets in @a os, then:
00382  *
00383  *    - If @a print_version is true, then print version info, in brief
00384  *      form if @a quiet is also true; if @a quiet is false, then if
00385  *      @a version_footer is non-null, print it following the version
00386  *      information.
00387  *
00388  *    - Else if @a print_version is not true, then print generic help,
00389  *      via svn_opt_print_generic_help() with the @a header, @a cmd_table,
00390  *      @a option_table, and @a footer arguments.
00391  *
00392  * Use @a pool for temporary allocations.
00393  *
00394  * Notes: The reason this function handles both version printing and
00395  * general usage help is that a confused user might put both the
00396  * --version flag *and* subcommand arguments on a help command line.
00397  * The logic for handling such a situation should be in one place.
00398  */
00399 svn_error_t *
00400 svn_opt_print_help (apr_getopt_t *os,
00401                     const char *pgm_name,
00402                     svn_boolean_t print_version,
00403                     svn_boolean_t quiet,
00404                     const char *version_footer,
00405                     const char *header,
00406                     const svn_opt_subcommand_desc_t *cmd_table,
00407                     const apr_getopt_option_t *option_table,
00408                     const char *footer,
00409                     apr_pool_t *pool);
00410 
00411 #ifdef __cplusplus
00412 }
00413 #endif /* __cplusplus */
00414 
00415 #endif /* SVN_OPTS_H */

Generated on Wed Mar 23 12:11:30 2011 for Subversion by  doxygen 1.4.6