Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_opt.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Copyright (c) 2000-2008 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_opt.h
19  * @brief Option and argument parsing for Subversion command lines
20  */
21 
22 #ifndef SVN_OPTS_H
23 #define SVN_OPTS_H
24 
25 #include <apr.h>
26 #include <apr_pools.h>
27 #include <apr_getopt.h>
28 #include <apr_tables.h>
29 #include <apr_hash.h>
30 
31 #ifndef DOXYGEN_SHOULD_SKIP_THIS
32 #define APR_WANT_STDIO
33 #endif
34 #include <apr_want.h> /* for FILE* */
35 
36 #include "svn_types.h"
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif /* __cplusplus */
41 
42 
43 
44 /**
45  * All subcommand procedures in Subversion conform to this prototype.
46  *
47  * @a os is the apr option state after getopt processing has been run; in
48  * other words, it still contains the non-option arguments following
49  * the subcommand. See @a os->argv and @a os->ind.
50  *
51  * @a baton is anything you need it to be.
52  *
53  * @a pool is used for allocating errors, and for any other allocation
54  * unless the instance is explicitly documented to allocate from a
55  * pool in @a baton.
56  */
58  (apr_getopt_t *os, void *baton, apr_pool_t *pool);
59 
60 
61 /** The maximum number of aliases a subcommand can have. */
62 #define SVN_OPT_MAX_ALIASES 3
63 
64 /** The maximum number of options that can be accepted by a subcommand. */
65 #define SVN_OPT_MAX_OPTIONS 50
66 
67 /** Options that have no short option char should use an identifying
68  * integer equal to or greater than this.
69  */
70 #define SVN_OPT_FIRST_LONGOPT_ID 256
71 
72 
73 /** One element of a subcommand dispatch table.
74  *
75  * @since New in 1.4.
76  */
78 {
79  /** The full name of this command. */
80  const char *name;
81 
82  /** The function this command invokes. */
84 
85  /** A list of alias names for this command (e.g., 'up' for 'update'). */
87 
88  /** A brief string describing this command, for usage messages. */
89  const char *help;
90 
91  /** A list of options accepted by this command. Each value in the
92  * array is a unique enum (the 2nd field in apr_getopt_option_t)
93  */
95 
96  /** A list of option help descriptions, keyed by the option unique enum
97  * (the 2nd field in apr_getopt_option_t), which override the generic
98  * descriptions given in an apr_getopt_option_t on a per-subcommand basis.
99  */
100  struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS];
102 
103 
104 /** One element of a subcommand dispatch table.
105  *
106  * @deprecated Provided for backward compatibility with the 1.3 API.
107  *
108  * Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides
109  * member.
110  */
112 {
113  /** The full name of this command. */
114  const char *name;
115 
116  /** The function this command invokes. */
118 
119  /** A list of alias names for this command (e.g., 'up' for 'update'). */
121 
122  /** A brief string describing this command, for usage messages. */
123  const char *help;
124 
125  /** A list of options accepted by this command. Each value in the
126  * array is a unique enum (the 2nd field in apr_getopt_option_t)
127  */
129 
131 
132 
133 /**
134  * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
135  * none. @a cmd_name may be an alias.
136  *
137  * @since New in 1.4.
138  */
141  const char *cmd_name);
142 
143 
144 /**
145  * Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
146  * none. @a cmd_name may be an alias.
147  *
148  * Same as svn_opt_get_canonical_subcommand2(), but acts on
149  * #svn_opt_subcommand_desc_t.
150  *
151  * @deprecated Provided for backward compatibility with the 1.3 API.
152  */
156  const char *cmd_name);
157 
158 
159 /**
160  * Return pointer to an @c apr_getopt_option_t for the option whose
161  * option code is @a code, or @c NULL if no match. @a option_table must end
162  * with an element whose every field is zero. If @c command is non-NULL,
163  * then return the subcommand-specific option description instead of the
164  * generic one, if a specific description is defined.
165  *
166  * The returned value may be statically allocated, or allocated in @a pool.
167  *
168  * @since New in 1.4.
169  */
170 const apr_getopt_option_t *
172  const apr_getopt_option_t *option_table,
173  const svn_opt_subcommand_desc2_t *command,
174  apr_pool_t *pool);
175 
176 
177 /**
178  * Return the first entry from @a option_table whose option code is @a code,
179  * or @c NULL if no match. @a option_table must end with an element whose
180  * every field is zero.
181  *
182  * @deprecated Provided for backward compatibility with the 1.3 API.
183  */
185 const apr_getopt_option_t *
187  const apr_getopt_option_t *option_table);
188 
189 
190 /**
191  * Return @c TRUE iff subcommand @a command supports option @a
192  * option_code, else return @c FALSE. If @a global_options is
193  * non-NULL, it is a zero-terminated array, and all subcommands take
194  * the options listed in it.
195  *
196  * @since New in 1.5.
197  */
200  int option_code,
201  const int *global_options);
202 
203 /**
204  * Same as svn_opt_subcommand_takes_option3(), but with @c NULL for @a
205  * global_options.
206  *
207  * @deprecated Provided for backward compatibility with the 1.4 API.
208  */
212  int option_code);
213 
214 
215 /**
216  * Return @c TRUE iff subcommand @a command supports option @a option_code,
217  * else return @c FALSE.
218  *
219  * Same as svn_opt_subcommand_takes_option2(), but acts on
220  * #svn_opt_subcommand_desc_t.
221  *
222  * @deprecated Provided for backward compatibility with the 1.3 API.
223  */
227  int option_code);
228 
229 
230 /**
231  * Print a generic (not command-specific) usage message to @a stream.
232  *
233  * ### @todo Why is @a stream a stdio file instead of an svn stream?
234  *
235  * If @a header is non-NULL, print @a header followed by a newline. Then
236  * loop over @a cmd_table printing the usage for each command (getting
237  * option usages from @a opt_table). Then if @a footer is non-NULL, print
238  * @a footer followed by a newline.
239  *
240  * Use @a pool for temporary allocation.
241  *
242  * @since New in 1.4.
243  */
244 void
245 svn_opt_print_generic_help2(const char *header,
246  const svn_opt_subcommand_desc2_t *cmd_table,
247  const apr_getopt_option_t *opt_table,
248  const char *footer,
249  apr_pool_t *pool,
250  FILE *stream);
251 
252 
253 /**
254  * Same as svn_opt_print_generic_help2(), but acts on
255  * #svn_opt_subcommand_desc_t.
256  *
257  * @deprecated Provided for backward compatibility with the 1.3 API.
258  */
260 void
261 svn_opt_print_generic_help(const char *header,
262  const svn_opt_subcommand_desc_t *cmd_table,
263  const apr_getopt_option_t *opt_table,
264  const char *footer,
265  apr_pool_t *pool,
266  FILE *stream);
267 
268 
269 /**
270  * Print an option @a opt nicely into a @a string allocated in @a pool.
271  * If @a doc is set, include the generic documentation string of @a opt,
272  * localized to the current locale if a translation is available.
273  */
274 void
275 svn_opt_format_option(const char **string,
276  const apr_getopt_option_t *opt,
277  svn_boolean_t doc,
278  apr_pool_t *pool);
279 
280 
281 
282 /**
283  * Get @a subcommand's usage from @a table, and print it to @c stdout.
284  * Obtain option usage from @a options_table. If not @c NULL, @a
285  * global_options is a zero-terminated list of global options. Use @a
286  * pool for temporary allocation. @a subcommand may be a canonical
287  * command name or an alias. ### @todo Why does this only print to
288  * @c stdout, whereas svn_opt_print_generic_help() gives us a choice?
289  *
290  * @since New in 1.5.
291  */
292 void
293 svn_opt_subcommand_help3(const char *subcommand,
294  const svn_opt_subcommand_desc2_t *table,
295  const apr_getopt_option_t *options_table,
296  const int *global_options,
297  apr_pool_t *pool);
298 
299 /**
300  * Same as svn_opt_subcommand_help3(), but with @a global_options
301  * always NULL.
302  *
303  * @deprecated Provided for backward compatibility with the 1.4 API.
304  */
306 void
307 svn_opt_subcommand_help2(const char *subcommand,
308  const svn_opt_subcommand_desc2_t *table,
309  const apr_getopt_option_t *options_table,
310  apr_pool_t *pool);
311 
312 
313 /**
314  * Same as svn_opt_subcommand_help2(), but acts on
315  * #svn_opt_subcommand_desc_t.
316  *
317  * @deprecated Provided for backward compatibility with the 1.3 API.
318  */
320 void
321 svn_opt_subcommand_help(const char *subcommand,
322  const svn_opt_subcommand_desc_t *table,
323  const apr_getopt_option_t *options_table,
324  apr_pool_t *pool);
325 
326 
327 
328 /* Parsing revision and date options. */
329 
330 /**
331  * Various ways of specifying revisions.
332  *
333  * @note
334  * In contexts where local mods are relevant, the `working' kind
335  * refers to the uncommitted "working" revision, which may be modified
336  * with respect to its base revision. In other contexts, `working'
337  * should behave the same as `committed' or `current'.
338  */
340  /** No revision information given. */
342 
343  /** revision given as number */
345 
346  /** revision given as date */
348 
349  /** rev of most recent change */
351 
352  /** (rev of most recent change) - 1 */
354 
355  /** .svn/entries current revision */
357 
358  /** current, plus local mods */
360 
361  /** repository youngest */
363 };
364 
365 /**
366  * A revision value, which can be specified as a number or a date.
367  *
368  * @note This union was formerly an anonymous inline type in
369  * @c svn_opt_revision_t, and was converted to a named type just to
370  * make things easier for SWIG.
371  *
372  * @since New in 1.3.
373  */
375 {
376  /** The revision number */
378 
379  /** the date of the revision */
380  apr_time_t date;
382 
383 /** A revision, specified in one of @c svn_opt_revision_kind ways. */
384 typedef struct svn_opt_revision_t
385 {
386  enum svn_opt_revision_kind kind; /**< See svn_opt_revision_kind */
387  svn_opt_revision_value_t value; /**< Extra data qualifying the @c kind */
389 
390 /** A revision range, specified in one of @c svn_opt_revision_kind ways. */
392 {
393  /** The first revision in the range */
395 
396  /** The last revision in the range */
399 
400 /**
401  * Set @a *start_revision and/or @a *end_revision according to @a arg,
402  * where @a arg is "N" or "N:M", like so:
403  *
404  * - If @a arg is "N", set @a *start_revision to represent N, and
405  * leave @a *end_revision untouched.
406  *
407  * - If @a arg is "N:M", set @a *start_revision and @a *end_revision
408  * to represent N and M respectively.
409  *
410  * N and/or M may be one of the special revision descriptors
411  * recognized by revision_from_word(), or a date in curly braces.
412  *
413  * If @a arg is invalid, return -1; else return 0.
414  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
415  *
416  * @note It is typical, though not required, for @a *start_revision and
417  * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
418  *
419  * Use @a pool for temporary allocations.
420  */
421 int
423  svn_opt_revision_t *end_revision,
424  const char *arg,
425  apr_pool_t *pool);
426 
427 /**
428  * Parse @a arg, where @a arg is "N" or "N:M", into a
429  * @c svn_opt_revision_range_t and push that onto @a opt_ranges.
430  *
431  * - If @a arg is "N", set the @c start field of the
432  * @c svn_opt_revision_range_t to represent N and the @c end field
433  * to @c svn_opt_revision_unspecified.
434  *
435  * - If @a arg is "N:M", set the @c start field of the
436  * @c svn_opt_revision_range_t to represent N and the @c end field
437  * to represent M.
438  *
439  * If @a arg is invalid, return -1; else return 0. It is invalid to omit
440  * a revision (as in, ":", "N:" or ":M").
441  *
442  * Use @a pool to allocate @c svn_opt_revision_range_t pushed to the array.
443  *
444  * @since New in 1.5.
445  */
446 int
447 svn_opt_parse_revision_to_range(apr_array_header_t *opt_ranges,
448  const char *arg,
449  apr_pool_t *pool);
450 
451 /**
452  * Resolve peg revisions and operational revisions in the following way:
453  *
454  * - If @a is_url is set and @a peg_rev->kind is
455  * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to
456  * @c svn_opt_revision_head.
457  *
458  * - If @a is_url is not set, and @a peg_rev->kind is
459  * @c svn_opt_revision_unspecified, @a peg_rev->kind defaults to
460  * @c svn_opt_revision_base.
461  *
462  * - If @a op_rev->kind is @c svn_opt_revision_unspecified, @a op_rev
463  * defaults to @a peg_rev.
464  *
465  * Both @a peg_rev and @a op_rev may be modified as a result of this
466  * function. @a is_url should be set if the path the revisions refer to is
467  * a url, and unset otherwise.
468  *
469  * If @a notice_local_mods is set, @c svn_opt_revision_working is used,
470  * instead of @c svn_opt_revision_base.
471  *
472  * Use @a pool for allocations.
473  *
474  * @since New in 1.5.
475  */
476 svn_error_t *
478  svn_opt_revision_t *op_rev,
479  svn_boolean_t is_url,
480  svn_boolean_t notice_local_mods,
481  apr_pool_t *pool);
482 
483 
484 /* Parsing arguments. */
485 
486 /**
487  * Pull remaining target arguments from @a os into @a *targets_p,
488  * converting them to UTF-8, followed by targets from @a known_targets
489  * (which might come from, for example, the "--targets" command line
490  * option), which are already in UTF-8.
491  *
492  * On each URL target, do some IRI-to-URI encoding and some
493  * auto-escaping. On each local path, canonicalize case and path
494  * separators.
495  *
496  * Allocate @a *targets_p and its elements in @a pool.
497  *
498  * If a path has the same name as a Subversion working copy
499  * administrative directory, return SVN_ERR_RESERVED_FILENAME_SPECIFIED;
500  * if multiple reserved paths are encountered, return a chain of
501  * errors, all of which are SVN_ERR_RESERVED_FILENAME_SPECIFIED. Do
502  * not return this type of error in a chain with any other type of
503  * error, and if this is the only type of error encountered, complete
504  * the operation before returning the error(s).
505  *
506  * @deprecated Provided for backward compatibility with the 1.5 API.
507  * @see svn_client_args_to_target_array()
508  */
510 svn_error_t *
511 svn_opt_args_to_target_array3(apr_array_header_t **targets_p,
512  apr_getopt_t *os,
513  apr_array_header_t *known_targets,
514  apr_pool_t *pool);
515 
516 /**
517  * This is the same as svn_opt_args_to_target_array3() except that it
518  * silently ignores paths that have the same name as a working copy
519  * administrative directory.
520  *
521  * @since New in 1.2.
522  *
523  * @deprecated Provided for backward compatibility with the 1.4 API.
524  */
526 svn_error_t *
527 svn_opt_args_to_target_array2(apr_array_header_t **targets_p,
528  apr_getopt_t *os,
529  apr_array_header_t *known_targets,
530  apr_pool_t *pool);
531 
532 
533 /**
534  * The same as svn_opt_args_to_target_array2() except that, in
535  * addition, if @a extract_revisions is set, then look for trailing
536  * "@rev" syntax on the first two paths. If the first target in @a
537  * *targets_p ends in "@rev", replace it with a canonicalized version of
538  * the part before "@rev" and replace @a *start_revision with the value
539  * of "rev". If the second target in @a *targets_p ends in "@rev",
540  * replace it with a canonicalized version of the part before "@rev"
541  * and replace @a *end_revision with the value of "rev". Ignore
542  * revision specifiers on any further paths. "rev" can be any form of
543  * single revision specifier, as accepted by svn_opt_parse_revision().
544  *
545  * @deprecated Provided for backward compatibility with the 1.1 API.
546  */
548 svn_error_t *
549 svn_opt_args_to_target_array(apr_array_header_t **targets_p,
550  apr_getopt_t *os,
551  apr_array_header_t *known_targets,
552  svn_opt_revision_t *start_revision,
553  svn_opt_revision_t *end_revision,
554  svn_boolean_t extract_revisions,
555  apr_pool_t *pool);
556 
557 
558 /**
559  * Parse revprop key/value pair from @a revprop_spec (name[=value]) into
560  * @a revprops, making copies of both with @a pool. If @a revprops is
561  * @c NULL, allocate a new apr_hash_t in it. @a revprops maps
562  * const char * revprop names to svn_string_t * revprop values for use
563  * with svn_repos_get_commit_editor5 and other get_commit_editor APIs.
564  *
565  * @since New in 1.6.
566  */
567 svn_error_t *
568 svn_opt_parse_revprop(apr_hash_t **revprops, const char *revprop_spec,
569  apr_pool_t *pool);
570 
571 
572 /**
573  * If no targets exist in @a *targets, add `.' as the lone target.
574  *
575  * (Some commands take an implicit "." string argument when invoked
576  * with no arguments. Those commands make use of this function to
577  * add "." to the target array if the user passes no args.)
578  */
579 void
580 svn_opt_push_implicit_dot_target(apr_array_header_t *targets,
581  apr_pool_t *pool);
582 
583 
584 /**
585  * Parse @a num_args non-target arguments from the list of arguments in
586  * @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without
587  * doing any UTF-8 conversion. Allocate @a *args_p and its values in @a pool.
588  */
589 svn_error_t *
590 svn_opt_parse_num_args(apr_array_header_t **args_p,
591  apr_getopt_t *os,
592  int num_args,
593  apr_pool_t *pool);
594 
595 
596 /**
597  * Parse all remaining arguments from @a os->argv, return them as
598  * <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
599  * Allocate @a *args_p and its values in @a pool.
600  */
601 svn_error_t *
602 svn_opt_parse_all_args(apr_array_header_t **args_p,
603  apr_getopt_t *os,
604  apr_pool_t *pool);
605 
606 /**
607  * Parse a working-copy or URL in @a path, extracting any trailing
608  * revision specifier of the form "@rev" from the last component of
609  * the path.
610  *
611  * Some examples would be:
612  *
613  * "foo/bar" -> "foo/bar", (unspecified)
614  * "foo/bar@13" -> "foo/bar", (number, 13)
615  * "foo/bar@HEAD" -> "foo/bar", (head)
616  * "foo/bar@{1999-12-31}" -> "foo/bar", (date, 1999-12-31)
617  * "http://a/b@27" -> "http://a/b", (number, 27)
618  * "http://a/b@COMMITTED" -> "http://a/b", (committed) [*]
619  * "http://a/b@{1999-12-31} -> "http://a/b", (date, 1999-12-31)
620  * "http://a/b@%7B1999-12-31%7D -> "http://a/b", (date, 1999-12-31)
621  * "foo/bar@1:2" -> error
622  * "foo/bar@baz" -> error
623  * "foo/bar@" -> "foo/bar", (base)
624  * "foo/@bar@" -> "foo/@bar", (base)
625  * "foo/bar/@13" -> "foo/bar/", (number, 13)
626  * "foo/bar@@13" -> "foo/bar@", (number, 13)
627  * "foo/@bar@HEAD" -> "foo/@bar", (head)
628  * "foo@/bar" -> "foo@/bar", (unspecified)
629  * "foo@HEAD/bar" -> "foo@HEAD/bar", (unspecified)
630  * "@foo/bar" -> error
631  * "@foo/bar@" -> "@foo/bar", (unspecified)
632  *
633  * [*] Syntactically valid but probably not semantically useful.
634  *
635  * If a trailing revision specifier is found, parse it into @a *rev and
636  * put the rest of the path into @a *truepath, allocating from @a pool;
637  * or return an @c SVN_ERR_CL_ARG_PARSING_ERROR (with the effect on
638  * @a *truepath undefined) if the revision specifier is invalid.
639  * If no trailing revision specifier is found, set @a *truepath to
640  * @a path and @a rev->kind to @c svn_opt_revision_unspecified.
641  *
642  * This function does not require that @a path be in canonical form.
643  * No canonicalization is done and @a *truepath will only be in
644  * canonical form if @a path is in canonical form.
645  *
646  * @since New in 1.1.
647  */
648 svn_error_t *
650  const char **truepath,
651  const char *path,
652  apr_pool_t *pool);
653 
654 /**
655  * Central dispatcher function for various kinds of help message.
656  * Prints one of:
657  * * subcommand-specific help (svn_opt_subcommand_help)
658  * * generic help (svn_opt_print_generic_help)
659  * * version info
660  * * simple usage complaint: "Type '@a pgm_name help' for usage."
661  *
662  * If @a os is not @c NULL and it contains arguments, then try
663  * printing help for them as though they are subcommands, using @a
664  * cmd_table and @a option_table for option information. If not @c
665  * NULL, @a global_options is a zero-terminated array of options taken
666  * by all subcommands.
667  *
668  * Else, if @a print_version is TRUE, then print version info, in
669  * brief form if @a quiet is also TRUE; if @a quiet is FALSE, then if
670  * @a version_footer is non-NULL, print it following the version
671  * information.
672  *
673  * Else, if @a os is not @c NULL and does not contain arguments, print
674  * generic help, via svn_opt_print_generic_help2() with the @a header,
675  * @a cmd_table, @a option_table, and @a footer arguments.
676  *
677  * Else, when @a os is @c NULL, print the simple usage complaint.
678  *
679  * Use @a pool for temporary allocations.
680  *
681  * Notes: The reason this function handles both version printing and
682  * general usage help is that a confused user might put both the
683  * --version flag *and* subcommand arguments on a help command line.
684  * The logic for handling such a situation should be in one place.
685  *
686  * @since New in 1.5.
687  */
688 svn_error_t *
689 svn_opt_print_help3(apr_getopt_t *os,
690  const char *pgm_name,
691  svn_boolean_t print_version,
692  svn_boolean_t quiet,
693  const char *version_footer,
694  const char *header,
695  const svn_opt_subcommand_desc2_t *cmd_table,
696  const apr_getopt_option_t *option_table,
697  const int *global_options,
698  const char *footer,
699  apr_pool_t *pool);
700 
701 /**
702  * Same as svn_opt_print_help3(), but with @a global_options always @c
703  * NULL.
704  *
705  * @deprecated Provided for backward compatibility with the 1.4 API.
706  */
707 
709 svn_error_t *
710 svn_opt_print_help2(apr_getopt_t *os,
711  const char *pgm_name,
712  svn_boolean_t print_version,
713  svn_boolean_t quiet,
714  const char *version_footer,
715  const char *header,
716  const svn_opt_subcommand_desc2_t *cmd_table,
717  const apr_getopt_option_t *option_table,
718  const char *footer,
719  apr_pool_t *pool);
720 
721 
722 /**
723  * Same as svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t.
724  *
725  * @deprecated Provided for backward compatibility with the 1.3 API.
726  */
728 svn_error_t *
729 svn_opt_print_help(apr_getopt_t *os,
730  const char *pgm_name,
731  svn_boolean_t print_version,
732  svn_boolean_t quiet,
733  const char *version_footer,
734  const char *header,
735  const svn_opt_subcommand_desc_t *cmd_table,
736  const apr_getopt_option_t *option_table,
737  const char *footer,
738  apr_pool_t *pool);
739 
740 #ifdef __cplusplus
741 }
742 #endif /* __cplusplus */
743 
744 #endif /* SVN_OPTS_H */