contrib/subversion/subversion/include/private/svn_opt_private.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_opt_private.h
  24  * @brief Subversion-internal option parsing APIs.
  25  */
  26
  27 #ifndef SVN_OPT_PRIVATE_H
  28 #define SVN_OPT_PRIVATE_H
  29
  30 #include <apr_pools.h>
  31 #include <apr_tables.h>
  32 #include <apr_getopt.h>
  33
  34 #include "svn_error.h"
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif /* __cplusplus */
  39
  40 /* Extract the peg revision, if any, from UTF8_TARGET.
  41  *
  42  * If PEG_REVISION is not NULL, return the peg revision in *PEG_REVISION.
  43  * *PEG_REVISION will be an empty string if no peg revision is found.
  44  * Return the true target portion in *TRUE_TARGET.
  45  *
  46  * UTF8_TARGET need not be canonical. *TRUE_TARGET will not be canonical
  47  * unless UTF8_TARGET is.
  48  *
  49  * It is an error if *TRUE_TARGET results in the empty string after the
  50  * split, which happens in case UTF8_TARGET has a leading '@' character
  51  * with no additional '@' characters to escape the first '@'.
  52  *
  53  * Note that *PEG_REVISION will still contain the '@' symbol as the first
  54  * character if a peg revision was found. If a trailing '@' symbol was
  55  * used to escape other '@' characters in UTF8_TARGET, *PEG_REVISION will
  56  * point to the string "@", containing only a single character.
  57  *
  58  * All allocations are done in POOL.
  59  */
  60 svn_error_t *
  61 svn_opt__split_arg_at_peg_revision(const char **true_target,
  62                                    const char **peg_revision,
  63                                    const char *utf8_target,
  64                                    apr_pool_t *pool);
  65
  66 /* Attempt to transform URL_IN, which is a URL-like user input, into a
  67  * valid URL:
  68  *   - escape IRI characters and some other non-URI characters
  69  *   - check that no back-path ("..") components are present
  70  *   - call svn_uri_canonicalize()
  71  * URL_IN is in UTF-8 encoding and has no peg revision specifier.
  72  * Set *URL_OUT to the result, allocated from POOL.
  73  */
  74 svn_error_t *
  75 svn_opt__arg_canonicalize_url(const char **url_out,
  76                               const char *url_in,
  77                               apr_pool_t *pool);
  78
  79 /*
  80  * Attempt to transform PATH_IN, which is a local path-like user input, into a
  81  * valid local path:
  82  *   - Attempt to get the correct capitalization by trying to actually find
  83  *     the path specified.
  84  *   - If the path does not exist (which is valid) the given capitalization
  85  *     is used.
  86  *   - canonicalize the separator ("/") characters
  87  *   - call svn_dirent_canonicalize()
  88  * PATH_IN is in UTF-8 encoding and has no peg revision specifier.
  89  * Set *PATH_OUT to the result, allocated from POOL.
  90  */
  91 svn_error_t *
  92 svn_opt__arg_canonicalize_path(const char **path_out,
  93                                const char *path_in,
  94                                apr_pool_t *pool);
  95
  96 /*
  97  * Pull remaining target arguments from OS into *TARGETS_P,
  98  * converting them to UTF-8, followed by targets from KNOWN_TARGETS
  99  * (which might come from, for example, the "--targets" command line
 100  * option), which are already in UTF-8.
 101  *
 102  * On each URL target, do some IRI-to-URI encoding and some
 103  * auto-escaping.  On each local path, canonicalize case and path
 104  * separators.
 105  *
 106  * Allocate *TARGETS_P and its elements in POOL.
 107  *
 108  * If a path has the same name as a Subversion working copy
 109  * administrative directory, return SVN_ERR_RESERVED_FILENAME_SPECIFIED;
 110  * if multiple reserved paths are encountered, return a chain of
 111  * errors, all of which are SVN_ERR_RESERVED_FILENAME_SPECIFIED.  Do
 112  * not return this type of error in a chain with any other type of
 113  * error, and if this is the only type of error encountered, complete
 114  * the operation before returning the error(s).
 115  */
 116 svn_error_t *
 117 svn_opt__args_to_target_array(apr_array_header_t **targets_p,
 118                               apr_getopt_t *os,
 119                               const apr_array_header_t *known_targets,
 120                               apr_pool_t *pool);
 121
 122 /**
 123  * Return a human-readable description of @a revision.  The result
 124  * will be allocated statically or from @a result_pool.
 125  *
 126  * @since New in 1.7.
 127  */
 128 const char *
 129 svn_opt__revision_to_string(const svn_opt_revision_t *revision,
 130                             apr_pool_t *result_pool);
 131
 132 /**
 133  * Create a revision range structure from two revisions.  Return a new range
 134  * allocated in @a result_pool with the start and end initialized to
 135  * (deep copies of) @a *start_revision and @a *end_revision.
 136  */
 137 svn_opt_revision_range_t *
 138 svn_opt__revision_range_create(const svn_opt_revision_t *start_revision,
 139                                const svn_opt_revision_t *end_revision,
 140                                apr_pool_t *result_pool);
 141
 142 /**
 143  * Create a revision range structure from two revnums.  Return a new range
 144  * allocated in @a result_pool with the start and end kinds initialized to
 145  * #svn_opt_revision_number and values @a start_revnum and @a end_revnum.
 146  */
 147 svn_opt_revision_range_t *
 148 svn_opt__revision_range_from_revnums(svn_revnum_t start_revnum,
 149                                      svn_revnum_t end_revnum,
 150                                      apr_pool_t *result_pool);
 151
 152 #ifdef __cplusplus
 153 }
 154 #endif /* __cplusplus */
 155
 156 #endif /* SVN_OPT_PRIVATE_H */