Main Page   Modules   Data Structures   File List   Data Fields  

svn_opt.h

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  * @c 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, specified in one of @c svn_opt_revision_kind ways. */
00206 typedef struct svn_opt_revision_t
00207 {
00208   enum svn_opt_revision_kind kind;  /**< See svn_opt_revision_kind */
00209   union {
00210     svn_revnum_t number;
00211     apr_time_t date;
00212   } value;                          /**< Extra data qualifying the @c kind */
00213 } svn_opt_revision_t;
00214 
00215 
00216 /**
00217  * Set @a *start_revision and/or @a *end_revision according to @a arg, 
00218  * where @a arg is "N" or "N:M", like so:
00219  * 
00220  *    - If @a arg is "N", set @a *start_revision to represent N, and
00221  *      leave @a *end_revision untouched.
00222  *
00223  *    - If @a arg is "N:M", set @a *start_revision and @a *end_revision
00224  *      to represent N and M respectively. 
00225  * 
00226  * N and/or M may be one of the special revision descriptors
00227  * recognized by @c revision_from_word(), or a date in curly braces.
00228  *
00229  * If @a arg is invalid, return -1; else return 0.
00230  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
00231  *
00232  * Note:
00233  *
00234  * It is typical, though not required, for @a *start_revision and
00235  * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
00236  *
00237  * Use @a pool for temporary allocations.
00238  */
00239 int svn_opt_parse_revision (svn_opt_revision_t *start_revision,
00240                             svn_opt_revision_t *end_revision,
00241                             const char *arg,
00242                             apr_pool_t *pool);
00243 
00244 
00245 
00246 /* Parsing arguments. */
00247 
00248 /**
00249  * @since New in 1.2.
00250  *
00251  * Pull remaining target arguments from @a os into @a *targets_p,
00252  * converting them to UTF-8, followed by targets from @a known_targets
00253  * (which might come from, for example, the "--targets" command line
00254  * option), which are already in UTF-8.
00255  *
00256  * On each URL target, do some IRI-to-URI encoding and some
00257  * auto-escaping.  On each local path, canonicalize case and path
00258  * separators, and silently skip it if it is a Subversion administrative
00259  * directory.
00260  *
00261  * Allocate @a *targets_p and its elements in @a pool.
00262  */
00263 svn_error_t *
00264 svn_opt_args_to_target_array2 (apr_array_header_t **targets_p,
00265                                apr_getopt_t *os,
00266                                apr_array_header_t *known_targets,
00267                                apr_pool_t *pool);
00268 
00269 
00270 /**
00271  * @deprecated Provided for backward compatibility with the 1.1 API.
00272  *
00273  * The same as @c svn_opt_args_to_target_array2 except that, in
00274  * addition, if @a extract_revisions is set, then look for trailing
00275  * "@rev" syntax on the first two paths.  If the first target in @a
00276  * *targets_p ends in "@rev", replace it with a canonicalized version of
00277  * the part before "@rev" and replace @a *start_revision with the value
00278  * of "rev".  If the second target in @a *targets_p ends in "@rev",
00279  * replace it with a canonicalized version of the part before "@rev"
00280  * and replace @a *end_revision with the value of "rev".  Ignore
00281  * revision specifiers on any further paths.  "rev" can be any form of
00282  * single revision specifier, as accepted by @c svn_opt_parse_revision.
00283  */
00284 svn_error_t *
00285 svn_opt_args_to_target_array (apr_array_header_t **targets_p,
00286                               apr_getopt_t *os,
00287                               apr_array_header_t *known_targets,
00288                               svn_opt_revision_t *start_revision,
00289                               svn_opt_revision_t *end_revision,
00290                               svn_boolean_t extract_revisions,
00291                               apr_pool_t *pool);
00292 
00293 
00294 /**
00295  * If no targets exist in @a *targets, add `.' as the lone target.
00296  *
00297  * (Some commands take an implicit "." string argument when invoked
00298  * with no arguments. Those commands make use of this function to
00299  * add "." to the target array if the user passes no args.)
00300  */
00301 void svn_opt_push_implicit_dot_target (apr_array_header_t *targets,
00302                                        apr_pool_t *pool);
00303 
00304 
00305 /**
00306  * Parse @a num_args non-target arguments from the list of arguments in
00307  * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without 
00308  * doing any UTF-8 conversion.  Allocate @a *args_p and its values in @a pool.
00309  */
00310 svn_error_t *
00311 svn_opt_parse_num_args (apr_array_header_t **args_p,
00312                         apr_getopt_t *os,
00313                         int num_args,
00314                         apr_pool_t *pool);
00315 
00316 
00317 /**
00318  * Parse all remaining arguments from @a os->argv, return them as
00319  * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
00320  * Allocate @a *args_p and its values in @a pool.
00321  */
00322 svn_error_t *
00323 svn_opt_parse_all_args (apr_array_header_t **args_p,
00324                         apr_getopt_t *os,
00325                         apr_pool_t *pool);
00326 
00327 /**
00328  * @since New in 1.1.
00329  *
00330  * Parse a working-copy or URL in @a path, extracting any trailing
00331  * revision specifier of the form "@rev" from the last component of
00332  * the path.
00333  *
00334  * Some examples would be:
00335  *
00336  *   - foo/bar               -> "foo/bar",       (unspecified)
00337  *   - foo/bar@@13           -> "foo/bar",       (number, 13)
00338  *   - foo/bar@@HEAD         -> "foo/bar",       (head)
00339  *   - foo/bar@@{1999-12-31} -> "foo/bar",       (date, 1999-12-31)
00340  *   - http://a/b@27         -> "http://a/b",    (number, 27) 
00341  *   - http://a/b@COMMITTED  -> "http://a/b",    (committed) [*]
00342  *   - foo/bar@@1:2          -> error
00343  *   - foo/bar@@baz          -> error
00344  *   - foo/bar@              -> error
00345  *   - foo/bar/@@13          -> "foo/bar",       (number, 13)
00346  *   - foo/bar@@13           -> "foo/bar@",     (number, 13)
00347  *   - foo/@@bar@@HEAD       -> "foo/@bar",     (head)
00348  *   - foo@/bar              -> "foo@/bar",     (unspecified)
00349  *   - foo@@HEAD/bar         -> "foo@HEAD/bar", (unspecified)
00350  *
00351  *   [*] Syntactically valid but probably not semantically useful.
00352  *
00353  * If a trailing revision specifier is found, parse it into @a *rev and
00354  * put the rest of the path into @a *truepath, allocating from @a pool;
00355  * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR if the revision
00356  * specifier is invalid.  If no trailing revision specifier is found,
00357  * set @a *truepath to @a path and @a rev->kind to @c
00358  * svn_opt_revision_unspecified.
00359  */
00360 svn_error_t *
00361 svn_opt_parse_path (svn_opt_revision_t *rev,
00362                     const char **truepath,
00363                     const char *path,
00364                     apr_pool_t *pool);
00365 
00366 /**
00367  * Print either generic help, or command-specific help for @a pgm_name.
00368  * If there are arguments in @a os, then try printing help for them as
00369  * though they are subcommands, using  @a cmd_table and @a option_table 
00370  * for option information.
00371  *
00372  * If @a os is @c NULL, or there are no targets in @a os, then:
00373  *
00374  *    - If @a print_version is true, then print version info, in brief
00375  *      form if @a quiet is also true; if @a quiet is false, then if
00376  *      @a version_footer is non-null, print it following the version
00377  *      information.
00378  *
00379  *    - Else if @a print_version is not true, then print generic help,
00380  *      via @c svn_opt_print_generic_help with the @a header, @a cmd_table,
00381  *      @a option_table, and @a footer arguments.
00382  *
00383  * Use @a pool for temporary allocations.
00384  *
00385  * Notes: The reason this function handles both version printing and
00386  * general usage help is that a confused user might put both the
00387  * --version flag *and* subcommand arguments on a help command line.
00388  * The logic for handling such a situation should be in one place.
00389  */
00390 svn_error_t *
00391 svn_opt_print_help (apr_getopt_t *os,
00392                     const char *pgm_name,
00393                     svn_boolean_t print_version,
00394                     svn_boolean_t quiet,
00395                     const char *version_footer,
00396                     const char *header,
00397                     const svn_opt_subcommand_desc_t *cmd_table,
00398                     const apr_getopt_option_t *option_table,
00399                     const char *footer,
00400                     apr_pool_t *pool);
00401 
00402 #ifdef __cplusplus
00403 }
00404 #endif /* __cplusplus */
00405 
00406 #endif /* SVN_OPTS_H */

Generated on Wed Aug 31 01:47:56 2005 for Subversion by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002