Main Page   Modules   Data Structures   File List   Data Fields   Globals  

svn_opt.h File Reference

Option and argument parsing for Subversion command lines. More...

#include <apr.h>
#include <apr_pools.h>
#include <apr_getopt.h>
#include "svn_types.h"
#include "svn_error.h"

Go to the source code of this file.

Data Structures

struct  svn_opt_revision_t
 A revision, specified in one of svn_opt_revision_kind ways. More...

struct  svn_opt_subcommand_desc_t
 One element of a subcommand dispatch table. More...


Defines

#define SVN_OPT_MAX_ALIASES   3
 The maximum number of aliases a subcommand can have.

#define SVN_OPT_MAX_OPTIONS   50
 The maximum number of options that can be accepted by a subcommand.

#define SVN_OPT_FIRST_LONGOPT_ID   256
 Options that have no short option char should use an identifying integer equal to or greater than this.


Typedefs

typedef svn_error_t *( svn_opt_subcommand_t )(apr_getopt_t *os, void *baton, apr_pool_t *pool)
 All subcommand procedures in Subversion conform to this prototype.

typedef svn_opt_subcommand_desc_t svn_opt_subcommand_desc_t
 One element of a subcommand dispatch table.

typedef svn_opt_revision_t svn_opt_revision_t
 A revision, specified in one of svn_opt_revision_kind ways.


Enumerations

enum  svn_opt_revision_kind {
  svn_opt_revision_unspecified,
  svn_opt_revision_number,
  svn_opt_revision_date,
  svn_opt_revision_committed,
  svn_opt_revision_previous,
  svn_opt_revision_base,
  svn_opt_revision_working,
  svn_opt_revision_head
}
 Various ways of specifying revisions. More...


Functions

const svn_opt_subcommand_desc_tsvn_opt_get_canonical_subcommand (const svn_opt_subcommand_desc_t *table, const char *cmd_name)
 Return the entry in table whose name matches cmd_name, or NULL if none.

const apr_getopt_option_t * svn_opt_get_option_from_code (int code, const apr_getopt_option_t *option_table)
 Return the first entry from option_table whose option code is code, or NULL if no match.

svn_boolean_t svn_opt_subcommand_takes_option (const svn_opt_subcommand_desc_t *command, int option_code)
 Return TRUE iff subcommand command supports option option_code, else return FALSE.

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 a generic (not command-specific) usage message to stream.

void svn_opt_format_option (const char **string, const apr_getopt_option_t *opt, svn_boolean_t doc, apr_pool_t *pool)
 Print an option opt nicely into a string allocated in pool.

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)
 Get subcommand's usage from table, and print it to stdout.

int svn_opt_parse_revision (svn_opt_revision_t *start_revision, svn_opt_revision_t *end_revision, const char *arg, apr_pool_t *pool)
 Set *start_revision and/or *end_revision according to arg, where arg is "N" or "N:M", like so:.

svn_error_tsvn_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)
 Pull remaining target arguments from os into *targets_p, including targets stored in known_targets (which might come from, for example, the "--targets" command line option), converting them to UTF-8.

void svn_opt_push_implicit_dot_target (apr_array_header_t *targets, apr_pool_t *pool)
 If no targets exist in *targets, add `.' as the lone target.

svn_error_tsvn_opt_parse_num_args (apr_array_header_t **args_p, apr_getopt_t *os, int num_args, apr_pool_t *pool)
 Parse num_args non-target arguments from the list of arguments in os->argv, return them as const char * in *args_p, without doing any UTF-8 conversion.

svn_error_tsvn_opt_parse_all_args (apr_array_header_t **args_p, apr_getopt_t *os, apr_pool_t *pool)
 Parse all remaining arguments from os->argv, return them as const char * in *args_p, without doing any UTF-8 conversion.

svn_error_tsvn_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)
 Print either generic help, or command-specific help for pgm_name.


Detailed Description

Option and argument parsing for Subversion command lines.

Definition in file svn_opt.h.


Typedef Documentation

typedef svn_error_t*( svn_opt_subcommand_t)(apr_getopt_t *os, void *baton, apr_pool_t *pool)
 

All subcommand procedures in Subversion conform to this prototype.

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 os->argv and os->ind.

baton is anything you need it to be.

pool is used for allocating errors, and for any other allocation unless the instance is explicitly documented to allocate from a pool in baton.

Definition at line 52 of file svn_opt.h.


Enumeration Type Documentation

enum svn_opt_revision_kind
 

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'.

Enumeration values:
svn_opt_revision_unspecified  No revision information given.
svn_opt_revision_number  revision given as number
svn_opt_revision_date  revision given as date
svn_opt_revision_committed  rev of most recent change
svn_opt_revision_previous  (rev of most recent change) - 1
svn_opt_revision_base  .svn/entries current revision
svn_opt_revision_working  current, plus local mods
svn_opt_revision_head  repository youngest

Definition at line 177 of file svn_opt.h.


Function Documentation

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
 

Pull remaining target arguments from os into *targets_p, including targets stored in known_targets (which might come from, for example, the "--targets" command line option), converting them to UTF-8.

Allocate *targets_p and its elements in pool.

If extract_revisions is set, then this function will attempt to look for trailing "@rev" syntax on the paths. If an @rev is found for the first target in *TARGETS_P, it will overwrite the value of *start_revision. If an @rev is found for the second target in *TARGETS_P, it will overwrite *end_revision. (Extra revisions beyond that are ignored.)

void svn_opt_format_option const char **    string,
const apr_getopt_option_t *    opt,
svn_boolean_t    doc,
apr_pool_t *    pool
 

Print an option opt nicely into a string allocated in pool.

If doc is set, include the generic documentation string of option.

const svn_opt_subcommand_desc_t* svn_opt_get_canonical_subcommand const svn_opt_subcommand_desc_t   table,
const char *    cmd_name
 

Return the entry in table whose name matches cmd_name, or NULL if none.

cmd_name may be an alias.

const apr_getopt_option_t* svn_opt_get_option_from_code int    code,
const apr_getopt_option_t *    option_table
 

Return the first entry from option_table whose option code is code, or NULL if no match.

option_table must end with an element whose every field is zero.

svn_error_t* svn_opt_parse_all_args apr_array_header_t **    args_p,
apr_getopt_t *    os,
apr_pool_t *    pool
 

Parse all remaining arguments from os->argv, return them as const char * in *args_p, without doing any UTF-8 conversion.

Allocate *args_p and its values in 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 num_args non-target arguments from the list of arguments in os->argv, return them as const char * in *args_p, without doing any UTF-8 conversion.

Allocate *args_p and its values in pool.

int svn_opt_parse_revision svn_opt_revision_t   start_revision,
svn_opt_revision_t   end_revision,
const char *    arg,
apr_pool_t *    pool
 

Set *start_revision and/or *end_revision according to arg, where arg is "N" or "N:M", like so:.

  • If arg is "N", set *start_revision's kind to svn_opt_revision_number and its value to the number N; and leave *end_revision untouched.
  • If arg is "N:M", set *start_revision's and *end_revision's kinds to svn_opt_revision_number and values to N and M respectively.
N and/or M may be one of the special revision descriptors recognized by revision_from_word().

If 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 *start_revision and *end_revision to be svn_opt_revision_unspecified kind on entry.

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 a generic (not command-specific) usage message to stream.

(### todo: why is stream a stdio file instead of an svn stream?)

If header is non-null, print header followed by a newline. Then loop over cmd_table printing the usage for each command (getting option usages from opt_table). Then if footer is non-null, print footer followed by a newline.

Use pool for temporary allocation.

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
 

Print either generic help, or command-specific help for pgm_name.

If there are arguments in os, then try printing help for them as though they are subcommands, using cmd_table and option_table for option information.

If os is NULL, or there are no targets in os, then:

  • If print_version is true, then print version info, in brief form if quiet is also true; if quiet is false, then if version_footer is non-null, print it following the version information.
  • Else if print_version is not true, then print generic help, via svn_opt_print_generic_help with the header, cmd_table, option_table, and footer arguments.
Use 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.

void svn_opt_push_implicit_dot_target apr_array_header_t *    targets,
apr_pool_t *    pool
 

If no targets exist in *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_subcommand_help const char *    subcommand,
const svn_opt_subcommand_desc_t   table,
const apr_getopt_option_t *    options_table,
apr_pool_t *    pool
 

Get subcommand's usage from table, and print it to stdout.

Obtain option usage from options_table. Use pool for temporary allocation. subcommand may be a canonical command name or an alias. (### todo: why does this only print to stdout, whereas svn_opt_print_generic_help gives us a choice?)


Generated on Wed Oct 20 01:47:46 2004 for Subversion by doxygen1.2.18