et_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_DEPRECATED
svn_error_t *
svn_opt_args_to_target_array(apr_array_header_t **targets_p,
                             apr_getopt_t *os,
                             const 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);


/**
 * Parse revprop key/value pair from @a revprop_spec (name[=value]) into
 * @a revprops, making copies of both with @a pool.  If @a revprops is
 * @c NULL, allocate a new apr_hash_t in it.  @a revprops maps
 * const char * revprop names to svn_string_t * revprop values for use
 * with svn_repos_get_commit_editor5 and other get_commit_editor APIs.
 *
 * @since New in 1.6.
 */
svn_error_t *
svn_opt_parse_revprop(apr_hash_t **revprops, const char *revprop_spec,
                      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 path 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@"                     -> "foo/bar",       (unspecified)
 *   - "foo/@bar@"                    -> "foo/@bar",      (unspecified)
 *   - "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)
 *   - "@foo/bar"                     -> "@foo/bar",      (unspecified)
 *   - "@foo/bar@"                    -> "@foo/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 (with the effect on
 * @a *truepath undefined) 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.
 *
 * This function does not require that @a path be in canonical form.
 * No canonicalization is done and @a *truepath will only be in
 * canonical form if @a path is in canonical form.
 *
 * @since New in 1.1.
 * @since Since 1.6.5, this returns an error if @a path contains a peg
 * specifier with no path before it, such as "@abc".
 * @since Since 1.9.0, this no longer returns an error if @a path contains a peg
 * specifier with no path before it, such as "@abc".
 */
svn_error_t *
svn_opt_parse_path(svn_opt_revision_t *rev,
                   const char **truepath,
                   const char *path,
                   apr_pool_t *pool);

/**
 * Central dispatcher function for various kinds of help message.
 * Prints one of:
 *   * subcommand-specific help (svn_opt_subcommand_help)
 *   * generic help (svn_opt_print_generic_help)
 *   * version info
 *   * simple usage complaint: "Type '@a pgm_name help' for usage."
 *
 * If @a os is not @c NULL and it contains arguments, then try
 * printing help for them as though they are subcommands, using @a
 * cmd_table and @a option_table for option information.  If not @c
 * NULL, @a global_options is a zero-terminated array of options taken
 * by all subcommands.
 *
 * Else, 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. If @a verbose is TRUE, also print information about
 * the running system and loaded shared libraries, where available.
 *
 * Else, if @a os is not @c NULL and does not contain arguments, print
 * generic help, via svn_opt_print_generic_help2() with the @a header,
 * @a cmd_table, @a option_table, and @a footer arguments.
 *
 * Else, when @a os is @c NULL, print the simple usage complaint.
 *
 * 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.11.
 */
svn_error_t *
svn_opt_print_help5(apr_getopt_t *os,
                    const char *pgm_name,
                    svn_boolean_t print_version,
                    svn_boolean_t quiet,
                    svn_boolean_t verbose,
                    const char *version_footer,
                    const char *header,
                    const svn_opt_subcommand_desc3_t *cmd_table,
                    const apr_getopt_option_t *option_table,
                    const int *global_options,
                    const char *footer,
                    apr_pool_t *pool);

/**
 * Same as svn_opt_print_help5(), but with a different
 * version of the subcommand description table.
 *
 * @since New in 1.8.
 * @deprecated Provided for backward compatibility with the 1.10 API.
 */
SVN_DEPRECATED
svn_error_t *
svn_opt_print_help4(apr_getopt_t *os,
                    const char *pgm_name,
                    svn_boolean_t print_version,
                    svn_boolean_t quiet,
                    svn_boolean_t verbose,
                    const char *version_footer,
                    const char *header,
                    const svn_opt_subcommand_desc2_t *cmd_table,
                    const apr_getopt_option_t *option_table,
                    const int *global_options,
                    const char *footer,
                    apr_pool_t *pool);

/**
 * Same as svn_opt_print_help4(), but with @a verbose always @c FALSE.
 *
 * @deprecated Provided for backward compatibility with the 1.7 API.
 */

SVN_DEPRECATED
svn_error_t *
svn_opt_print_help3(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 int *global_options,
                    const char *footer,
                    apr_pool_t *pool);

/**
 * Same as svn_opt_print_help3(), but with @a global_options always @c
 * NULL.
 *
 * @deprecated Provided for backward compatibility with the 1.4 API.
 */

SVN_DEPRECATED
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 svn_opt_print_help2(), but acts on #svn_opt_subcommand_desc_t.
 *
 * @deprecated Provided for backward compatibility with the 1.3 API.
 */
SVN_DEPRECATED
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_OPT_H */