/**
* @copyright
* ====================================================================
* Copyright (c) 2000-2004 CollabNet. All rights reserved.
*
* This software is licensed as described in the file COPYING, which
* you should have received as part of this distribution. The terms
* are also available at http://subversion.tigris.org/license-1.html.
* If newer versions of this license are posted there, you may use a
* newer version instead, at your option.
*
* This software consists of voluntary contributions made by many
* individuals. For exact contribution history, see the revision
* history and logs, available at http://subversion.tigris.org/.
* ====================================================================
* @endcopyright
*
* @file svn_opt.h
* @brief Option and argument parsing for Subversion command lines
*/
#ifndef SVN_OPTS_H
#define SVN_OPTS_H
#include <apr.h>
#include <apr_pools.h>
#include <apr_getopt.h>
#include "svn_types.h"
#include "svn_error.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* All subcommand procedures in Subversion conform to this prototype.
*
* @a os is the apr option state after getopt processing has been run; in
* other words, it still contains the non-option arguments following
* the subcommand. See @a os->argv and @a os->ind.
*
* @a baton is anything you need it to be.
*
* @a pool is used for allocating errors, and for any other allocation
* unless the instance is explicitly documented to allocate from a
* pool in @a baton.
*/
typedef svn_error_t *(svn_opt_subcommand_t)
(apr_getopt_t *os, void *baton, apr_pool_t *pool);
/** The maximum number of aliases a subcommand can have. */
#define SVN_OPT_MAX_ALIASES 3
/** The maximum number of options that can be accepted by a subcommand. */
#define SVN_OPT_MAX_OPTIONS 50
/** Options that have no short option char should use an identifying
* integer equal to or greater than this.
*/
#define SVN_OPT_FIRST_LONGOPT_ID 256
/** One element of a subcommand dispatch table.
*
* @since New in 1.4.
*/
typedef struct svn_opt_subcommand_desc2_t
{
/** The full name of this command. */
const char *name;
/** The function this command invokes. */
svn_opt_subcommand_t *cmd_func;
/** A list of alias names for this command (e.g., 'up' for 'update'). */
const char *aliases[SVN_OPT_MAX_ALIASES];
/** A brief string describing this command, for usage messages. */
const char *help;
/** A list of options accepted by this command. Each value in the
* array is a unique enum (the 2nd field in apr_getopt_option_t)
*/
int valid_options[SVN_OPT_MAX_OPTIONS];
/** A list of option help descriptions, keyed by the option unique enum
* (the 2nd field in apr_getopt_option_t), which override the generic
* descriptions given in an apr_getopt_option_t on a per-subcommand basis.
*/
struct { int optch; const char *desc; } desc_overrides[SVN_OPT_MAX_OPTIONS];
} svn_opt_subcommand_desc2_t;
/** One element of a subcommand dispatch table.
*
* @deprecated Provided for backward compatibility with the 1.3 API.
*
* Like #svn_opt_subcommand_desc2_t but lacking the @c desc_overrides
* member.
*/
typedef struct svn_opt_subcommand_desc_t
{
/** The full name of this command. */
const char *name;
/** The function this command invokes. */
svn_opt_subcommand_t *cmd_func;
/** A list of alias names for this command (e.g., 'up' for 'update'). */
const char *aliases[SVN_OPT_MAX_ALIASES];
/** A brief string describing this command, for usage messages. */
const char *help;
/** A list of options accepted by this command. Each value in the
* array is a unique enum (the 2nd field in apr_getopt_option_t)
*/
int valid_options[SVN_OPT_MAX_OPTIONS];
} svn_opt_subcommand_desc_t;
/**
* Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
* none. @a cmd_name may be an alias.
*
* @since New in 1.4.
*/
const svn_opt_subcommand_desc2_t *
svn_opt_get_canonical_subcommand2(const svn_opt_subcommand_desc2_t *table,
const char *cmd_name);
/**
* Return the entry in @a table whose name matches @a cmd_name, or @c NULL if
* none. @a cmd_name may be an alias.
*
* Same as svn_opt_get_canonical_subcommand2(), but acts on
* #svn_opt_subcommand_desc_t.
*
* @deprecated Provided for backward compatibility with the 1.3 API.
*/
const svn_opt_subcommand_desc_t *
svn_opt_get_canonical_subcommand(const svn_opt_subcommand_desc_t *table,
const char *cmd_name);
/**
* Return pointer to an @c apr_getopt_option_t for the option whose
* option code is @a code, or @c NULL if no match. @a option_table must end
* with an element whose every field is zero. If @c command is non-NULL,
* then the subcommand-specific option description instead of the generic one,
* if a specific description is defined.
*
* The returned value may be statically allocated, or allocated in @a pool.
*
* @since New in 1.4.
*/
const apr_getopt_option_t *
svn_opt_get_option_from_code2(int code,
const apr_getopt_option_t *option_table,
const svn_opt_subcommand_desc2_t *command,
apr_pool_t *pool);
/**
* Return the first entry from @a option_table whose option code is @a code,
* or @c NULL if no match. @a option_table must end with an element whose
* every field is zero.
*
* @deprecated Provided for backward compatibility with the 1.3 API.
*/
const apr_getopt_option_t *
svn_opt_get_option_from_code(int code,
const apr_getopt_option_t *option_table);
/**
* Return @c TRUE iff subcommand @a command supports option @a option_code,
* else return @c FALSE.
*
* @since New in 1.4.
*/
svn_boolean_t
svn_opt_subcommand_takes_option2(const svn_opt_subcommand_desc2_t *command,
int option_code);
/**
* Return @c TRUE iff subcommand @a command supports option @a option_code,
* else return @c FALSE.
*
* Same as svn_opt_subcommand_takes_option2(), but acts on
* #svn_opt_subcommand_desc_t.
*
* @deprecated Provided for backward compatibility with the 1.3 API.
*/
svn_boolean_t
svn_opt_subcommand_takes_option(const svn_opt_subcommand_desc_t *command,
int option_code);
/**
* Print a generic (not command-specific) usage message to @a stream.
*
* (### todo: why is @a stream a stdio file instead of an svn stream?)
*
* If @a header is non-null, print @a header followed by a newline. Then
* loop over @a cmd_table printing the usage for each command (getting
* option usages from @a opt_table). Then if @a footer is non-null, print
* @a footer followed by a newline.
*
* Use @a pool for temporary allocation.
*
* @since New in 1.4.
*/
void
svn_opt_print_generic_help2(const char *header,
const svn_opt_subcommand_desc2_t *cmd_table,
const apr_getopt_option_t *opt_table,
const char *footer,
apr_pool_t *pool,
FILE *stream);
/* Same as svn_opt_print_generic_help2(), but acts on
* #svn_opt_subcommand_desc_t.
*
* @deprecated Provided for backward compatibility with the 1.3 API.
*/
void
svn_opt_print_generic_help(const char *header,
const svn_opt_subcommand_desc_t *cmd_table,
const apr_getopt_option_t *opt_table,
const char *footer,
apr_pool_t *pool,
FILE *stream);
/**
* Print an option @a opt nicely into a @a string allocated in @a pool.
* If @a doc is set, include the generic documentation string of @a opt,
* localized to the current locale if a translation is available.
*/
void
svn_opt_format_option(const char **string,
const apr_getopt_option_t *opt,
svn_boolean_t doc,
apr_pool_t *pool);
/**
* Get @a subcommand's usage from @a table, and print it to @c stdout.
* Obtain option usage from @a options_table. Use @a pool for temporary
* allocation. @a subcommand may be a canonical command name or an
* alias. (### todo: why does this only print to @c stdout, whereas
* svn_opt_print_generic_help() gives us a choice?)
*
* @since New in 1.4.
*/
void
svn_opt_subcommand_help2(const char *subcommand,
const svn_opt_subcommand_desc2_t *table,
const apr_getopt_option_t *options_table,
apr_pool_t *pool);
/**
* Same as svn_opt_subcommand_help2(), but acts on
* #svn_opt_subcommand_desc_t.
*
* @deprecated Provided for backward compatibility with the 1.3 API.
*/
void
svn_opt_subcommand_help(const char *subcommand,
const svn_opt_subcommand_desc_t *table,
const apr_getopt_option_t *options_table,
apr_pool_t *pool);
/* Parsing revision and date options. */
/**
* Various ways of specifying revisions.
*
* @note
* In contexts where local mods are relevant, the `working' kind
* refers to the uncommitted "working" revision, which may be modified
* with respect to its base revision. In other contexts, `working'
* should behave the same as `committed' or `current'.
*/
enum svn_opt_revision_kind {
/** No revision information given. */
svn_opt_revision_unspecified,
/** revision given as number */
svn_opt_revision_number,
/** revision given as date */
svn_opt_revision_date,
/** rev of most recent change */
svn_opt_revision_committed,
/** (rev of most recent change) - 1 */
svn_opt_revision_previous,
/** .svn/entries current revision */
svn_opt_revision_base,
/** current, plus local mods */
svn_opt_revision_working,
/** repository youngest */
svn_opt_revision_head
};
/**
* A revision value, which can be specified as a number or a date.
*
* @note This union was formerly an anonymous inline type in
* @c svn_opt_revision_t, and was converted to a named type just to
* make things easier for SWIG.
*
* @since New in 1.3.
*/
typedef union svn_opt_revision_value_t
{
svn_revnum_t number;
apr_time_t date;
} svn_opt_revision_value_t;
/** A revision, specified in one of @c svn_opt_revision_kind ways. */
typedef struct svn_opt_revision_t
{
enum svn_opt_revision_kind kind; /**< See svn_opt_revision_kind */
svn_opt_revision_value_t value; /**< Extra data qualifying the @c kind */
} svn_opt_revision_t;
/**
* Set @a *start_revision and/or @a *end_revision according to @a arg,
* where @a arg is "N" or "N:M", like so:
*
* - If @a arg is "N", set @a *start_revision to represent N, and
* leave @a *end_revision untouched.
*
* - If @a arg is "N:M", set @a *start_revision and @a *end_revision
* to represent N and M respectively.
*
* N and/or M may be one of the special revision descriptors
* recognized by revision_from_word(), or a date in curly braces.
*
* If @a arg is invalid, return -1; else return 0.
* It is invalid to omit a revision (as in, ":", "N:" or ":M").
*
* @note It is typical, though not required, for @a *start_revision and
* @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
*
* Use @a pool for temporary allocations.
*/
int svn_opt_parse_revision(svn_opt_revision_t *start_revision,
svn_opt_revision_t *end_revision,
const char *arg,
apr_pool_t *pool);
/* Parsing arguments. */
/**
* Pull remaining target arguments from @a os into @a *targets_p,
* converting them to UTF-8, followed by targets from @a known_targets
* (which might come from, for example, the "--targets" command line
* option), which are already in UTF-8.
*
* On each URL target, do some IRI-to-URI encoding and some
* auto-escaping. On each local path, canonicalize case and path
* separators, and silently skip it if it has the same name as a
* Subversion working copy administrative directory.
*
* Allocate @a *targets_p and its elements in @a pool.
*
* @since New in 1.2.
*/
svn_error_t *
svn_opt_args_to_target_array2(apr_array_header_t **targets_p,
apr_getopt_t *os,
apr_array_header_t *known_targets,
apr_pool_t *pool);
/**
* The same as svn_opt_args_to_target_array2() except that, in
* addition, if @a extract_revisions is set, then look for trailing
* "@rev" syntax on the first two paths. If the first target in @a
* *targets_p ends in "@rev", replace it with a canonicalized version of
* the part before "@rev" and replace @a *start_revision with the value
* of "rev". If the second target in @a *targets_p ends in "@rev",
* replace it with a canonicalized version of the part before "@rev"
* and replace @a *end_revision with the value of "rev". Ignore
* revision specifiers on any further paths. "rev" can be any form of
* single revision specifier, as accepted by svn_opt_parse_revision().
*
* @deprecated Provided for backward compatibility with the 1.1 API.
*/
svn_error_t *
svn_opt_args_to_target_array(apr_array_header_t **targets_p,
apr_getopt_t *os,
apr_array_header_t *known_targets,
svn_opt_revision_t *start_revision,
svn_opt_revision_t *end_revision,
svn_boolean_t extract_revisions,
apr_pool_t *pool);
/**
* If no targets exist in @a *targets, add `.' as the lone target.
*
* (Some commands take an implicit "." string argument when invoked
* with no arguments. Those commands make use of this function to
* add "." to the target array if the user passes no args.)
*/
void svn_opt_push_implicit_dot_target(apr_array_header_t *targets,
apr_pool_t *pool);
/**
* Parse @a num_args non-target arguments from the list of arguments in
* @a os->argv, return them as <tt>const char *</tt> in @a *args_p, without
* doing any UTF-8 conversion. Allocate @a *args_p and its values in @a pool.
*/
svn_error_t *
svn_opt_parse_num_args(apr_array_header_t **args_p,
apr_getopt_t *os,
int num_args,
apr_pool_t *pool);
/**
* Parse all remaining arguments from @a os->argv, return them as
* <tt>const char *</tt> in @a *args_p, without doing any UTF-8 conversion.
* Allocate @a *args_p and its values in @a pool.
*/
svn_error_t *
svn_opt_parse_all_args(apr_array_header_t **args_p,
apr_getopt_t *os,
apr_pool_t *pool);
/**
* Parse a working-copy or URL in @a path, extracting any trailing
* revision specifier of the form "@rev" from the last component of
* the path.
*
* Some examples would be:
*
* "foo/bar" -> "foo/bar", (unspecified)
* "foo/bar@13" -> "foo/bar", (number, 13)
* "foo/bar@HEAD" -> "foo/bar", (head)
* "foo/bar@{1999-12-31}" -> "foo/bar", (date, 1999-12-31)
* "http://a/b@27" -> "http://a/b", (number, 27)
* "http://a/b@COMMITTED" -> "http://a/b", (committed) [*]
* "http://a/b@{1999-12-31} -> "http://a/b", (date, 1999-12-31)
* "http://a/b@%7B1999-12-31%7D -> "http://a/b", (date, 1999-12-31)
* "foo/bar@1:2" -> error
* "foo/bar@baz" -> error
* "foo/bar@" -> error
* "foo/bar/@13" -> "foo/bar", (number, 13)
* "foo/bar@@13" -> "foo/bar@", (number, 13)
* "foo/@bar@HEAD" -> "foo/@bar", (head)
* "foo@/bar" -> "foo@/bar", (unspecified)
* "foo@HEAD/bar" -> "foo@HEAD/bar", (unspecified)
*
* [*] Syntactically valid but probably not semantically useful.
*
* If a trailing revision specifier is found, parse it into @a *rev and
* put the rest of the path into @a *truepath, allocating from @a pool;
* or return an @c SVN_ERR_CL_ARG_PARSING_ERROR if the revision
* specifier is invalid. If no trailing revision specifier is found,
* set @a *truepath to @a path and @a rev->kind to @c
* svn_opt_revision_unspecified.
*
* @since New in 1.1.
*/
svn_error_t *
svn_opt_parse_path(svn_opt_revision_t *rev,
const char **truepath,
const char *path,
apr_pool_t *pool);
/**
* Print either generic help, or command-specific help for @a pgm_name.
* If there are arguments in @a os, then try printing help for them as
* though they are subcommands, using @a cmd_table and @a option_table
* for option information.
*
* If @a os is @c NULL, or there are no targets in @a os, then:
*
* - If @a print_version is true, then print version info, in brief
* form if @a quiet is also true; if @a quiet is false, then if
* @a version_footer is non-null, print it following the version
* information.
*
* - Else if @a print_version is not true, then print generic help,
* via svn_opt_print_generic_help2() with the @a header, @a cmd_table,
* @a option_table, and @a footer arguments.
*
* Use @a pool for temporary allocations.
*
* Notes: The reason this function handles both version printing and
* general usage help is that a confused user might put both the
* --version flag *and* subcommand arguments on a help command line.
* The logic for handling such a situation should be in one place.
*
* @since New in 1.4.
*/
svn_error_t *
svn_opt_print_help2(apr_getopt_t *os,
const char *pgm_name,
svn_boolean_t print_version,
svn_boolean_t quiet,
const char *version_footer,
const char *header,
const svn_opt_subcommand_desc2_t *cmd_table,
const apr_getopt_option_t *option_table,
const char *footer,
apr_pool_t *pool);
/* Same as vn_opt_print_help2), but acts on #svn_opt_subcommand_desc_t.
*
* @deprecated Provided for backward compatibility with the 1.3 API.
*/
svn_error_t *
svn_opt_print_help(apr_getopt_t *os,
const char *pgm_name,
svn_boolean_t print_version,
svn_boolean_t quiet,
const char *version_footer,
const char *header,
const svn_opt_subcommand_desc_t *cmd_table,
const apr_getopt_option_t *option_table,
const char *footer,
apr_pool_t *pool);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* SVN_OPTS_H */
syntax highlighted by Code2HTML, v. 0.9.1