Main Page | Modules | Data Structures | File List | Data Fields | Globals

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 option.
00142  */
00143 void
00144 svn_opt_format_option (const char **string,
00145                        const apr_getopt_option_t *opt,
00146                        svn_boolean_t doc,
00147                        apr_pool_t *pool);
00148 
00149 
00150 
00151 /**
00152  * Get @a subcommand's usage from @a table, and print it to @c stdout.  
00153  * Obtain option usage from @a options_table.  Use @a pool for temporary
00154  * allocation.  @a subcommand may be a canonical command name or an
00155  * alias.  (### todo: why does this only print to @c stdout, whereas
00156  * @c svn_opt_print_generic_help gives us a choice?)
00157  */
00158 void
00159 svn_opt_subcommand_help (const char *subcommand, 
00160                          const svn_opt_subcommand_desc_t *table,
00161                          const apr_getopt_option_t *options_table,
00162                          apr_pool_t *pool);
00163 
00164 
00165 
00166 /* Parsing revision and date options. */
00167 
00168 /**
00169  * Various ways of specifying revisions. 
00170  *
00171  * Note:
00172  * In contexts where local mods are relevant, the `working' kind
00173  * refers to the uncommitted "working" revision, which may be modified
00174  * with respect to its base revision.  In other contexts, `working'
00175  * should behave the same as `committed' or `current'.
00176  */
00177 enum svn_opt_revision_kind {
00178   /** No revision information given. */
00179   svn_opt_revision_unspecified,
00180 
00181   /** revision given as number */
00182   svn_opt_revision_number,
00183 
00184   /** revision given as date */
00185   svn_opt_revision_date,
00186 
00187   /** rev of most recent change */
00188   svn_opt_revision_committed,
00189 
00190   /** (rev of most recent change) - 1 */
00191   svn_opt_revision_previous,
00192 
00193   /** .svn/entries current revision */
00194   svn_opt_revision_base,
00195 
00196   /** current, plus local mods */
00197   svn_opt_revision_working,
00198 
00199   /** repository youngest */
00200   svn_opt_revision_head
00201 };
00202 
00203 
00204 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
00205 typedef struct svn_opt_revision_t
00206 {
00207   enum svn_opt_revision_kind kind;
00208   union {
00209     svn_revnum_t number;
00210     apr_time_t date;
00211   } value;
00212 } svn_opt_revision_t;
00213 
00214 
00215 /**
00216  * Set @a *start_revision and/or @a *end_revision according to @a arg, 
00217  * where @a arg is "N" or "N:M", like so:
00218  * 
00219  *    - If @a arg is "N", set @a *start_revision's kind to
00220  *      @c svn_opt_revision_number and its value to the number N; and
00221  *      leave @a *end_revision untouched.
00222  *
00223  *    - If @a arg is "N:M", set @a *start_revision's and @a *end_revision's
00224  *      kinds to @c svn_opt_revision_number and values to N and M
00225  *      respectively. 
00226  * 
00227  * N and/or M may be one of the special revision descriptors
00228  * recognized by @c revision_from_word().
00229  *
00230  * If @a arg is invalid, return -1; else return 0.
00231  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
00232  *
00233  * Note:
00234  *
00235  * It is typical, though not required, for @a *start_revision and
00236  * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
00237  */
00238 int svn_opt_parse_revision (svn_opt_revision_t *start_revision,
00239                             svn_opt_revision_t *end_revision,
00240                             const char *arg,
00241                             apr_pool_t *pool);
00242 
00243 
00244 
00245 /* Parsing arguments. */
00246 
00247 /**
00248  * Pull remaining target arguments from @a os into @a *targets_p, including
00249  * targets stored in @a known_targets (which might come from, for
00250  * example, the "--targets" command line option), converting them to
00251  * UTF-8.  Allocate @a *targets_p and its elements in @a pool.
00252  *
00253  * If @a extract_revisions is set, then this function will attempt to
00254  * look for trailing "@rev" syntax on the paths.  If an @rev is found
00255  * for the first target in *TARGETS_P, it will overwrite the value of
00256  * @a *start_revision.  If an @rev is found for the second target in
00257  * *TARGETS_P,  it will overwrite @a *end_revision.  (Extra revisions 
00258  * beyond that are ignored.) 
00259  */
00260 svn_error_t *
00261 svn_opt_args_to_target_array (apr_array_header_t **targets_p,
00262                               apr_getopt_t *os,
00263                               apr_array_header_t *known_targets,
00264                               svn_opt_revision_t *start_revision,
00265                               svn_opt_revision_t *end_revision,
00266                               svn_boolean_t extract_revisions,
00267                               apr_pool_t *pool);
00268 
00269 
00270 /**
00271  * If no targets exist in @a *targets, add `.' as the lone target.
00272  *
00273  * (Some commands take an implicit "." string argument when invoked
00274  * with no arguments. Those commands make use of this function to
00275  * add "." to the target array if the user passes no args.)
00276  */
00277 void svn_opt_push_implicit_dot_target (apr_array_header_t *targets,
00278                                        apr_pool_t *pool);
00279 
00280 
00281 /**
00282  * Parse @a num_args non-target arguments from the list of arguments in
00283  * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without 
00284  * doing any UTF-8 conversion.  Allocate @a *args_p and its values in @a pool.
00285  */
00286 svn_error_t *
00287 svn_opt_parse_num_args (apr_array_header_t **args_p,
00288                         apr_getopt_t *os,
00289                         int num_args,
00290                         apr_pool_t *pool);
00291 
00292 
00293 /**
00294  * Parse all remaining arguments from @a os->argv, return them as
00295  * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
00296  * Allocate @a *args_p and its values in @a pool.
00297  */
00298 svn_error_t *
00299 svn_opt_parse_all_args (apr_array_header_t **args_p,
00300                         apr_getopt_t *os,
00301                         apr_pool_t *pool);
00302 
00303 
00304 /**
00305  * Print either generic help, or command-specific help for @a pgm_name.
00306  * If there are arguments in @a os, then try printing help for them as
00307  * though they are subcommands, using  @a cmd_table and @a option_table 
00308  * for option information.
00309  *
00310  * If @a os is @c NULL, or there are no targets in @a os, then:
00311  *
00312  *    - If @a print_version is true, then print version info, in brief
00313  *      form if @a quiet is also true; if @a quiet is false, then if
00314  *      @a version_footer is non-null, print it following the version
00315  *      information.
00316  *
00317  *    - Else if @a print_version is not true, then print generic help,
00318  *      via @c svn_opt_print_generic_help with the @a header, @a cmd_table,
00319  *      @a option_table, and @a footer arguments.
00320  *
00321  * Use @a pool for temporary allocations.
00322  *
00323  * Notes: The reason this function handles both version printing and
00324  * general usage help is that a confused user might put both the
00325  * --version flag *and* subcommand arguments on a help command line.
00326  * The logic for handling such a situation should be in one place.
00327  */
00328 svn_error_t *
00329 svn_opt_print_help (apr_getopt_t *os,
00330                     const char *pgm_name,
00331                     svn_boolean_t print_version,
00332                     svn_boolean_t quiet,
00333                     const char *version_footer,
00334                     const char *header,
00335                     const svn_opt_subcommand_desc_t *cmd_table,
00336                     const apr_getopt_option_t *option_table,
00337                     const char *footer,
00338                     apr_pool_t *pool);
00339 
00340 #ifdef __cplusplus
00341 }
00342 #endif /* __cplusplus */
00343 
00344 #endif /* SVN_OPTS_H */

Generated on Mon Oct 18 17:33:13 2004 for Subversion by doxygen 1.3.5