---

svn_opt.h

/**
 * @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. */
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.
 */  
const svn_opt_subcommand_desc_t *
svn_opt_get_canonical_subcommand (const svn_opt_subcommand_desc_t *table,
                                  const char *cmd_name);


/**
 * 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.
 */
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.
 */
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.
 */
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
 * @c svn_opt_print_generic_help gives us a choice?)
 */
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, 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 */
  union {
    svn_revnum_t number;
    apr_time_t date;
  } 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 @c 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. */

/**
 * @since New in 1.2.
 *
 * 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 is a Subversion administrative
 * directory.
 *
 * Allocate @a *targets_p and its elements in @a pool.
 */
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);


/**
 * @deprecated Provided for backward compatibility with the 1.1 API.
 *
 * The same as @c 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 @c svn_opt_parse_revision.
 */
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);

/**
 * @since New in 1.1.
 *
 * 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) [*]
 *   - 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.
 */
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 @c svn_opt_print_generic_help 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.
 */
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 */

---