3
* ====================================================================
4
* Copyright (c) 2000-2004 CollabNet. All rights reserved.
6
* This software is licensed as described in the file COPYING, which
7
* you should have received as part of this distribution. The terms
8
* are also available at http://subversion.tigris.org/license-1.html.
9
* If newer versions of this license are posted there, you may use a
10
* newer version instead, at your option.
12
* This software consists of voluntary contributions made by many
13
* individuals. For exact contribution history, see the revision
14
* history and logs, available at http://subversion.tigris.org/.
15
* ====================================================================
19
* @brief A path manipulation library
21
* All incoming and outgoing paths are non-null and in UTF-8, unless
22
* otherwise documented.
24
* No result path ever ends with a separator, no matter whether the
25
* path is a file or directory, because we always canonicalize() it.
27
* All paths passed to the @c svn_path_xxx functions, with the exceptions of
28
* the @c svn_path_canonicalize and @c svn_path_internal_style functions, must
29
* be in canonical form.
36
#include <apr_pools.h>
37
#include <apr_tables.h>
39
#include "svn_string.h"
40
#include "svn_error.h"
45
#endif /* __cplusplus */
49
/** Convert @a path from the local style to the canonical internal style. */
50
const char *svn_path_internal_style (const char *path, apr_pool_t *pool);
52
/** Convert @a path from the canonical internal style to the local style. */
53
const char *svn_path_local_style (const char *path, apr_pool_t *pool);
56
/** Join a base path (@a base) with a component (@a component), allocated in
59
* If either @a base or @a component is the empty path, then the other
60
* argument will be copied and returned. If both are the empty path the
61
* empty path is returned.
63
* If the @a component is an absolute path, then it is copied and returned.
64
* Exactly one slash character ('/') is used to joined the components,
65
* accounting for any trailing slash in @a base.
67
* Note that the contents of @a base are not examined, so it is possible to
68
* use this function for constructing URLs, or for relative URLs or
71
* This function is NOT appropriate for native (local) file
72
* paths. Only for "internal" canonicalized paths, since it uses '/'
73
* for the separator. Further, an absolute path (for @a component) is
74
* based on a leading '/' character. Thus, an "absolute URI" for the
75
* @a component won't be detected. An absolute URI can only be used
78
char *svn_path_join (const char *base,
79
const char *component,
82
/** Join multiple components onto a @a base path, allocated in @a pool. The
83
* components are terminated by a @c NULL.
85
* If any component is the empty string, it will be ignored.
87
* If any component is an absolute path, then it resets the base and
88
* further components will be appended to it.
90
* See @c svn_path_join() for further notes about joining paths.
92
char *svn_path_join_many (apr_pool_t *pool, const char *base, ...);
95
/** Get the basename of the specified canonicalized @a path. The
96
* basename is defined as the last component of the path (ignoring any
97
* trailing slashes). If the @a path is root ("/"), then that is
98
* returned. Otherwise, the returned value will have no slashes in
101
* Example: svn_path_basename("/foo/bar") -> "bar"
103
* The returned basename will be allocated in @a pool.
105
* Note: if an empty string is passed, then an empty string will be returned.
107
char *svn_path_basename (const char *path, apr_pool_t *pool);
109
/** Get the dirname of the specified canonicalized @a path, defined as
110
* the path with its basename removed.
112
* Get the dirname of the specified @a path, defined as the path with its
113
* basename removed. If @a path is root ("/"), it is returned unchanged.
115
* The returned dirname will be allocated in @a pool.
117
char *svn_path_dirname (const char *path, apr_pool_t *pool);
119
/** Return the number of components in the canonicalized @a path. */
121
svn_path_component_count (const char *path);
123
/** Add a @a component (a null-terminated C-string) to the
124
* canonicalized @a path. @a component is allowed to contain
125
* directory separators.
127
* If @a path is non-empty, append the appropriate directory separator
128
* character, and then @a component. If @a path is empty, simply set it to
129
* @a component; don't add any separator character.
131
* If the result ends in a separator character, then remove the separator.
133
void svn_path_add_component (svn_stringbuf_t *path,
134
const char *component);
136
/** Remove one component off the end of the canonicalized @a path. */
137
void svn_path_remove_component (svn_stringbuf_t *path);
139
/** Remove @a n components off the end of the canonizalized @a path.
140
* Equivalent to calling @c svn_remove_component @a n times. */
141
void svn_path_remove_components (svn_stringbuf_t *path, apr_size_t n);
143
/** Divide the canonicalized @a path into @a *dirpath and @a
144
* *base_name, allocated in @a pool.
146
* If @a dirpath or @a base_name is null, then don't set that one.
148
* Either @a dirpath or @a base_name may be @a path's own address, but they
149
* may not both be the same address, or the results are undefined.
151
* If @a path has two or more components, the separator between @a dirpath
152
* and @a base_name is not included in either of the new names.
155
* - <pre>"/foo/bar/baz" ==> "/foo/bar" and "baz"</pre>
156
* - <pre>"/bar" ==> "/" and "bar"</pre>
157
* - <pre>"/" ==> "/" and "/"</pre>
158
* - <pre>"bar" ==> "" and "bar"</pre>
159
* - <pre>"" ==> "" and ""</pre>
161
void svn_path_split (const char *path,
162
const char **dirpath,
163
const char **base_name,
167
/** Return non-zero iff @a path is empty ("") or represents the current
168
* directory -- that is, if prepending it as a component to an existing
169
* path would result in no meaningful change.
171
int svn_path_is_empty (const char *path);
174
/** Return a new path (or URL) like @a path, but transformed such that
175
* some types of path specification redundancies are removed.
177
* This involves collapsing redundant "/./" elements, removing
178
* multiple adjacent separator characters, removing trailing
179
* separator characters, and possibly other semantically inoperative
182
* The returned path may be statically allocated, equal to @a path, or
183
* allocated from @a pool.
185
const char *svn_path_canonicalize (const char *path, apr_pool_t *pool);
188
/** Return an integer greater than, equal to, or less than 0, according
189
* as @a path1 is greater than, equal to, or less than @a path2.
191
int svn_path_compare_paths (const char *path1, const char *path2);
194
/** Return the longest common path shared by two canonicalized paths,
195
* @a path1 and @a path2. If there's no common ancestor, return the
198
* @a path1 and @a path2 may be URLs. In order for two URLs to have
199
* a common ancestor, they must (a) have the same protocol (since two URLs
200
* with the same path but different protocols may point at completely
201
* different resources), and (b) share a common ancestor in their path
202
* component, i.e. 'protocol://' is not a sufficient ancestor.
204
char *svn_path_get_longest_ancestor (const char *path1,
208
/** Convert @a relative canonicalized path to an absolute path and
209
* return the results in @a *pabsolute, allocated in @a pool.
211
* @a relative may be a URL, in which case no attempt is made to convert it,
212
* and a copy of the URL is returned.
215
svn_path_get_absolute (const char **pabsolute,
216
const char *relative,
219
/** Return the path part of the canonicalized @a path in @a
220
* *pdirectory, and the file part in @a *pfile. If @a path is a
221
* directory, set @a *pdirectory to @a path, and @a *pfile to the
222
* empty string. If @a path does not exist it is treated as if it is
223
* a file, since directories do not normally vanish.
226
svn_path_split_if_file(const char *path,
227
const char **pdirectory,
231
/** Find the common prefix of the canonicalized paths in @a targets
232
* (an array of @a const char *'s), and remove redundant paths if @a
233
* remove_redundancies is true.
235
* - Set @a *pcommon to the absolute path of the path or URL common to
236
* all of the targets. If the targets have no common prefix, or
237
* are a mix of URLs and local paths, set @a *pcommon to the
240
* - If @a pcondensed_targets is non-null, set @a *pcondensed_targets
241
* to an array of targets relative to @a *pcommon, and if
242
* @a remove_redundancies is true, omit any paths/URLs that are
243
* descendants of another path/URL in @a targets. If *pcommon
244
* is empty, @a *pcondensed_targets will contain full URLs and/or
245
* absolute paths; redundancies can still be removed (from both URLs
246
* and paths). If @a pcondensed_targets is null, leave it alone.
248
* Else if there is exactly one target, then
250
* - Set @a *pcommon to that target, and
252
* - If @a pcondensed_targets is non-null, set @a *pcondensed_targets
253
* to an array containing zero elements. Else if
254
* @a pcondensed_targets is null, leave it alone.
256
* If there are no items in @a targets, set @a *pcommon and (if
257
* applicable) @a *pcondensed_targets to @c NULL.
259
* NOTE: There is no guarantee that @a *pcommon is within a working
262
svn_path_condense_targets (const char **pcommon,
263
apr_array_header_t **pcondensed_targets,
264
const apr_array_header_t *targets,
265
svn_boolean_t remove_redundancies,
269
/** Copy a list of canonicalized @a targets, one at a time, into @a
270
* pcondensed_targets, omitting any targets that are found earlier in
271
* the list, or whose ancestor is found earlier in the list. Ordering
272
* of targets in the original list is preserved in the condensed list
273
* of targets. Use @a pool for any allocations.
275
* How does this differ in functionality from @c svn_path_condense_targets?
277
* Here's the short version:
279
* 1. Disclaimer: if you wish to debate the following, talk to Karl. :-)
280
* Order matters for updates because a multi-arg update is not
281
* atomic, and CVS users are used to, when doing 'cvs up targetA
282
* targetB' seeing targetA get updated, then targetB. I think the
283
* idea is that if you're in a time-sensitive or flaky-network
284
* situation, a user can say, "I really *need* to update
285
* wc/A/D/G/tau, but I might as well update my whole working copy if
286
* I can." So that user will do 'svn up wc/A/D/G/tau wc', and if
287
* something dies in the middles of the 'wc' update, at least the
288
* user has 'tau' up-to-date.
290
* 2. Also, we have this notion of an anchor and a target for updates
291
* (the anchor is where the update editor is rooted, the target is
292
* the actual thing we want to update). I needed a function that
293
* would NOT screw with my input paths so that I could tell the
294
* difference between someone being in A/D and saying 'svn up G' and
295
* being in A/D/G and saying 'svn up .' -- believe it or not, these
296
* two things don't mean the same thing. @c svn_path_condense_targets
297
* plays with absolute paths (which is fine, so does
298
* @c svn_path_remove_redundancies), but the difference is that it
299
* actually tweaks those targets to be relative to the "grandfather
300
* path" common to all the targets. Updates don't require a
301
* "grandfather path" at all, and even if it did, the whole
302
* conversion to an absolute path drops the crucial difference
303
* between saying "i'm in foo, update bar" and "i'm in foo/bar,
307
svn_path_remove_redundancies (apr_array_header_t **pcondensed_targets,
308
const apr_array_header_t *targets,
312
/** Decompose the canonicalized @a path into an array of <tt>const
313
* char *</tt> components, allocated in @a pool. If @a path is
314
* absolute, the first component will be a lone dir separator (the
317
apr_array_header_t *svn_path_decompose (const char *path,
321
/** Test that @a name is a single path component, that is:
322
* - not @c NULL or empty.
323
* - not a `/'-separated directory path
324
* - not empty or `..'
326
svn_boolean_t svn_path_is_single_path_component (const char *name);
332
* Test to see if a backpath, i.e. '..', is present in @a path.
333
* If not, return @c FALSE.
334
* If so, return @c TRUE.
336
svn_boolean_t svn_path_is_backpath_present (const char *path);
339
/** Test if @a path2 is a child of @a path1.
340
* If not, return @c NULL.
341
* If so, return a copy of the remainder path, allocated in @a pool.
342
* (The remainder is the component which, added to @a path1, yields
343
* @a path2. The remainder does not begin with a dir separator.)
345
* Both paths must be in canonical form, and must either be absolute,
346
* or contain no ".." components.
348
* ### todo: the ".." restriction is unfortunate, and would ideally
349
* be lifted by making the implementation smarter. But this is not
350
* trivial: if the path is "../foo", how do you know whether or not
351
* the current directory is named "foo" in its parent?
353
const char *svn_path_is_child (const char *path1,
360
* Check whether @a path is a valid Subversion path.
362
* A valid Subversion pathname is a UTF-8 string without control
363
* characters. "Valid" means Subversion can store the pathname in
364
* a repository. There may be other, OS-specific, limitations on
365
* what paths can be represented in a working copy.
367
* ASSUMPTION: @a path is a valid UTF-8 string. This function does
368
* not check UTF-8 validity.
370
* Return @c SVN_NO_ERROR if valid and @c SVN_ERR_FS_PATH_SYNTAX if
373
svn_error_t *svn_path_check_valid (const char *path, apr_pool_t *pool);
378
* @defgroup svn_path_uri_stuff URI/URL stuff
382
/** Return @c TRUE iff @a path looks like a valid URL, @c FALSE otherwise. */
383
svn_boolean_t svn_path_is_url (const char *path);
385
/** Return @c TRUE iff @a path is URI-safe, @c FALSE otherwise. */
386
svn_boolean_t svn_path_is_uri_safe (const char *path);
388
/** Return a URI-encoded copy of @a path, allocated in @a pool. */
389
const char *svn_path_uri_encode (const char *path, apr_pool_t *pool);
391
/** Return a URI-decoded copy of @a path, allocated in @a pool. */
392
const char *svn_path_uri_decode (const char *path, apr_pool_t *pool);
394
/** Extend @a url by a single @a component, URI-encoding that @a component
395
* before adding it to the @a url. Return the new @a url, allocated in
396
* @a pool. Notes: if @a component is @c NULL, just return a copy or @a url
397
* allocated in @a pool; if @a component is already URI-encoded, calling
398
* code should just use <tt>svn_path_join (url, component, pool)</tt>. @a url
399
* does not need to be a canonical path, it may have trailing '/'.
401
const char *svn_path_url_add_component (const char *url,
402
const char *component,
408
* Convert @a iri (Internationalized URI) to an URI.
409
* The return value may be the same as @a iri if it was already
410
* a URI. Else, allocate the return value in @a pool. */
411
const char *svn_path_uri_from_iri (const char *iri,
417
* URI-encode certain characters in @a uri that are not valid in an URI, but
418
* doesn't have any special meaning in @a uri at their positions. If no
419
* characters need escaping, just return @a uri.
421
* NOTE: Currently, this function escapes <, >, ", space, {, }, |, \, ^, and `.
422
* This may be extended in the future to do context-dependent escaping.
424
const char *svn_path_uri_autoescape (const char *uri,
429
/** Charset conversion stuff
431
* @defgroup svn_path_charset_stuff Charset conversion stuff
435
/** Convert @a path_utf8 from UTF-8 to the internal encoding used by APR. */
436
svn_error_t *svn_path_cstring_from_utf8 (const char **path_apr,
437
const char *path_utf8,
440
/** Convert @a path_apr from the internal encoding used by APR to UTF-8. */
441
svn_error_t *svn_path_cstring_to_utf8 (const char **path_utf8,
442
const char *path_apr,
450
#endif /* __cplusplus */
453
#endif /* SVN_PATH_H */
added
removed
subversion/include/svn_path.h
