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 */