subversion/include/svn_path.h - subversion - Git at Google

 /*  svn_path.h: a path manipulation library
  *
  * ====================================================================
  * Copyright (c) 2000-2002 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/.
  * ====================================================================
  */


 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */

 #ifndef SVN_PATH_H
 #define SVN_PATH_H


 #include <apr_pools.h>
 #include <apr_tables.h>
 #include "svn_string.h"
 #include "svn_error.h"


 /*** Notes:
  *
  * No result path ever ends with a separator, no matter whether the
  * path is a file or directory, because we always canonicalize() it.
  *
  * todo: this library really needs a test suite!
  ***/

 /* Convert PATH from the local style to the canonical internal style. */
 void svn_path_internal_style (svn_stringbuf_t *path);

 /* Convert PATH from the canonical internal style to the local style. */
 void svn_path_local_style (svn_stringbuf_t *path);


 /* Join a base path (BASE) with a component (COMPONENT), allocated in POOL.

    If either BASE or COMPONENT is the empty string, then the other argument
    will be copied and returned.

    If the COMPONENT is an absolute path, then it is copied and returned.
    Exactly one slash character ('/') is used to joined the components,
    accounting for any trailing slash in BASE. If BASE has multiple trailing
    slashes, then the result will also have multiple slashes (svn_path_join
    just won't add more).

    Note that the contents of BASE are not examined, so it is possible to
    use this function for constructing URLs, or for relative URLs or
    repository paths.

    This function is NOT appropriate for native (local) file paths. Only
    for "internal" paths, since it uses '/' for the separator. Further,
    an absolute path (for COMPONENT) is based on a leading '/' character.
    Thus, an "absolute URI" for the COMPONENT won't be detected. An
    absolute URI can only be used for the base.
 */
 char *svn_path_join (const char *base,
                      const char *component,
                      apr_pool_t *pool);

 /* Join multiple components onto a BASE path, allocated in POOL. The
    components are terminated by a NULL.

    If any component is the empty string, it will be ignored.

    If any component is an absolute path, then it resets the base and
    further components will be appended to it.

    See svn_path_join() for further notes about joining paths.
 */
 char *svn_path_join_many (apr_pool_t *pool, const char *base, ...);


 /* Get the basename of the specified PATH. The basename is defined as
    the last component of the path (ignoring any trailing slashes). If
    the PATH is root ("/"), then that is returned. Otherwise, the
    returned value will have no slashes in it.

    Example: svn_path_basename("/foo/bar") -> "bar"

    The returned basename will be allocated in POOL.

    Note: if an empty string is passed, then an empty string will be returned.
 */
 char *svn_path_basename (const char *path, apr_pool_t *pool);


 /* Add a COMPONENT (a null-terminated C-string) to PATH.  COMPONENT is
    allowed to contain directory separators.

    If PATH is non-empty, append the appropriate directory separator
    character, and then COMPONENT.  If PATH is empty, simply set it to
    COMPONENT; don't add any separator character.

    If the result ends in a separator character, then remove the separator. */
 void svn_path_add_component (svn_stringbuf_t *path,
                              const svn_stringbuf_t *component);

 /* Same as `svn_path_add_component', except that the COMPONENT argument is
    a C-style '\0'-terminated string, not an svn_stringbuf_t.  */
 void svn_path_add_component_nts (svn_stringbuf_t *path,
                                  const char *component);

 /* Remove one component off the end of PATH. */
 void svn_path_remove_component (svn_stringbuf_t *path);


 /* Divide PATH into *DIRPATH and *BASENAME, return them by reference,
  * in their own storage in POOL.
  *
  * If DIRPATH or BASENAME is null, then that one will not be used.
  *
  * DIRPATH or BASENAME may be PATH's own address, but they may not
  * both be PATH's address; in fact, in general they must not be the
  * same, or the results are undefined.
  *
  * The separator between DIRPATH and BASENAME is not included in
  * either of the new names.
  */
 void svn_path_split (const svn_stringbuf_t *path,
                      svn_stringbuf_t **dirpath,
                      svn_stringbuf_t **basename,
                      apr_pool_t *pool);


 /* Return non-zero iff PATH is empty or represents the current
    directory -- that is, if it is NULL or if prepending it as a
    component to an existing path would result in no meaningful
    change. */
 int svn_path_is_empty (const svn_stringbuf_t *path);


 /* Remove trailing separators that don't affect the meaning of the path.
    (At some future point, this may make other semantically inoperative
    transformations.) */
 void svn_path_canonicalize (svn_stringbuf_t *path);


 /* Return an integer greater than, equal to, or less than 0, according
    as PATH1 is greater than, equal to, or less than PATH2. */
 int svn_path_compare_paths (const svn_stringbuf_t *path1,
                             const svn_stringbuf_t *path2);


 /* Return the longest common path shared by both PATH1 and PATH2.  If
    there's no common ancestor, return NULL.  */
 svn_stringbuf_t *svn_path_get_longest_ancestor (const svn_stringbuf_t *path1,
                                                 const svn_stringbuf_t *path2,
                                                 apr_pool_t *pool);

 /* Convert RELATIVE path to an absolute path and return the results in
    *PABSOLUTE. */
 svn_error_t *
 svn_path_get_absolute(svn_stringbuf_t **pabsolute,
                       const svn_stringbuf_t *relative,
                       apr_pool_t *pool);

 /* Return the path part of PATH in *PDIRECTORY, and the file part in *PFILE.
    If PATH is a directory, it will be returned through PDIRECTORY, and *PFILE
    will be the empty string (not NULL). */
 svn_error_t *
 svn_path_split_if_file(svn_stringbuf_t *path,
                        svn_stringbuf_t **pdirectory,
                        svn_stringbuf_t **pfile,
                        apr_pool_t *pool);

 /* Find the common prefix of the paths in TARGETS, and remove redundancies.
  *
  * The elements in TARGETS must be existing files or directories.
  *
  * If there are multiple targets, or exactly one target and it's not a
  * directory, then
  *
  *   - *PBASENAME is set to the absolute path of the common parent
  *     directory of all of those targets, and
  *
  *   - If PCONDENSED_TARGETS is non-null, *PCONDENSED_TARGETS is set
  *     to an array of targets relative to *PBASENAME, with
  *     redundancies removed (meaning that none of these targets will
  *     be the same as, nor have an ancestor/descendant relationship
  *     with, any of the other targets; nor will any of them be the
  *     same as *PBASENAME).  Else if PCONDENSED_TARGETS is null, it is
  *     left untouched.
  *
  * Else if there is exactly one directory target, then
  *
  *   - *PBASENAME is set to that directory, and
  *
  *   - If PCONDENSED_TARGETS is non-null, *PCONDENSED_TARGETS is set
  *     to an array containing zero elements.  Else if
  *     PCONDENSED_TARGETS is null, it is left untouched.
  *
  * If there are no items in TARGETS, *PBASENAME and (if applicable)
  * *PCONDENSED_TARGETS will be NULL.
  *
  * NOTE: There is no guarantee that *PBASENAME is within a working
  * copy.
  */
 svn_error_t *
 svn_path_condense_targets (svn_stringbuf_t **pbasename,
                            apr_array_header_t **pcondensed_targets,
                            const apr_array_header_t *targets,
                            apr_pool_t *pool);


 /* Copy a list of TARGETS, one at a time, into PCONDENSED_TARGETS,
    omitting any targets that are found earlier in the list, or whose
    ancestor is found earlier in the list.  Ordering of targets in the
    original list is preserved in the condensed list of targets.  Use
    POOL for any allocations.

    How does this differ in functionality from svn_path_condense_targets?

    Here's the short version:

    1.  Disclaimer: if you wish to debate the following, talk to Karl. :-)
        Order matters for updates because a multi-arg update is not
        atomic, and CVS users are used to, when doing 'cvs up targetA
        targetB' seeing targetA get updated, then targetB.  I think the
        idea is that if you're in a time-sensitive or flaky-network
        situation, a user can say, "I really *need* to update
        wc/A/D/G/tau, but I might as well update my whole working copy if
        I can."  So that user will do 'svn up wc/A/D/G/tau wc', and if
        something dies in the middles of the 'wc' update, at least the
        user has 'tau' up-to-date.

    2.  Also, we have this notion of an anchor and a target for updates
        (the anchor is where the update editor is rooted, the target is
        the actual thing we want to update).  I needed a function that
        would NOT screw with my input paths so that I could tell the
        difference between someone being in A/D and saying 'svn up G' and
        being in A/D/G and saying 'svn up .' -- believe it or not, these
        two things don't mean the same thing.  svn_path_condense_targets
        plays with absolute paths (which is fine, so does
        svn_path_remove_redundancies), but the difference is that it
        actually tweaks those targets to be relative to the "grandfather
        path" common to all the targets.  Updates don't require a
        "grandfather path" at all, and even if it did, the whole
        conversion to an absolute path drops the crucial difference
        between saying "i'm in foo, update bar" and "i'm in foo/bar,
        update '.'"
 */
 svn_error_t *
 svn_path_remove_redundancies (apr_array_header_t **pcondensed_targets,
                               const apr_array_header_t *targets,
                               apr_pool_t *pool);


 /* Decompose PATH into an array of svn_stringbuf_t components, allocated
    in POOL.  STYLE indicates the dir separator to split the string on.
    If PATH is absolute, the first component will be a lone dir
    separator (the root directory). */
 apr_array_header_t *svn_path_decompose (const svn_stringbuf_t *path,
                                         apr_pool_t *pool);


 /* Test if PATH2 is a child of PATH1.
    If not, return NULL.
    If so, return the "remainder" path.  (The substring which, when
    appended to PATH1, yields PATH2 -- minus the dirseparator. ) */
 svn_stringbuf_t *svn_path_is_child (const svn_stringbuf_t *path1,
                                     const svn_stringbuf_t *path2,
                                     apr_pool_t *pool);

 /* Compare PATH to an array of const char * URL SCHEMES (like "file",
    "http", etc.) to determine if PATH looks like a URL.  If so, return
    the matching scheme used by PATH, else return NULL.  Returned
    values point to the allocations in SCHEMES. */
 svn_boolean_t svn_path_is_url (const svn_string_t *path);

 /* Return TRUE if PATH is URI-safe, FALSE otherwise. */
 svn_boolean_t svn_path_is_uri_safe (const svn_string_t *path);

 /* Return a URI-encoded copy of PATH, allocated in POOL. */
 svn_stringbuf_t *svn_path_uri_encode (const svn_string_t *path,
                                       apr_pool_t *pool);

 /* Return a URI-decoded copy of PATH, allocated in POOL. */
 svn_stringbuf_t *svn_path_uri_decode (const svn_string_t *path,
                                       apr_pool_t *pool);


 #endif /* SVN_PATH_H */

 #ifdef __cplusplus
 }
 #endif /* __cplusplus */


 /* ----------------------------------------------------------------
  * local variables:
  * eval: (load-file "../../tools/dev/svn-dev.el")
  * end:
  */
	/* svn_path.h: a path manipulation library
	*
	* ====================================================================
	* Copyright (c) 2000-2002 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/.
	* ====================================================================
	*/


	#ifdef __cplusplus
	extern "C" {
	#endif /* __cplusplus */

	#ifndef SVN_PATH_H
	#define SVN_PATH_H



	#include <apr_pools.h>
	#include <apr_tables.h>
	#include "svn_string.h"
	#include "svn_error.h"


	/*** Notes:
	*
	* No result path ever ends with a separator, no matter whether the
	* path is a file or directory, because we always canonicalize() it.
	*
	* todo: this library really needs a test suite!
	***/

	/* Convert PATH from the local style to the canonical internal style. */
	void svn_path_internal_style (svn_stringbuf_t *path);

	/* Convert PATH from the canonical internal style to the local style. */
	void svn_path_local_style (svn_stringbuf_t *path);


	/* Join a base path (BASE) with a component (COMPONENT), allocated in POOL.

	If either BASE or COMPONENT is the empty string, then the other argument
	will be copied and returned.

	If the COMPONENT is an absolute path, then it is copied and returned.
	Exactly one slash character ('/') is used to joined the components,
	accounting for any trailing slash in BASE. If BASE has multiple trailing
	slashes, then the result will also have multiple slashes (svn_path_join
	just won't add more).

	Note that the contents of BASE are not examined, so it is possible to
	use this function for constructing URLs, or for relative URLs or
	repository paths.

	This function is NOT appropriate for native (local) file paths. Only
	for "internal" paths, since it uses '/' for the separator. Further,
	an absolute path (for COMPONENT) is based on a leading '/' character.
	Thus, an "absolute URI" for the COMPONENT won't be detected. An
	absolute URI can only be used for the base.
	*/
	char svn_path_join (const char base,
	const char *component,
	apr_pool_t *pool);

	/* Join multiple components onto a BASE path, allocated in POOL. The
	components are terminated by a NULL.

	If any component is the empty string, it will be ignored.

	If any component is an absolute path, then it resets the base and
	further components will be appended to it.

	See svn_path_join() for further notes about joining paths.
	*/
	char svn_path_join_many (apr_pool_t pool, const char *base, ...);


	/* Get the basename of the specified PATH. The basename is defined as
	the last component of the path (ignoring any trailing slashes). If
	the PATH is root ("/"), then that is returned. Otherwise, the
	returned value will have no slashes in it.

	Example: svn_path_basename("/foo/bar") -> "bar"

	The returned basename will be allocated in POOL.

	Note: if an empty string is passed, then an empty string will be returned.
	*/
	char svn_path_basename (const char path, apr_pool_t *pool);


	/* Add a COMPONENT (a null-terminated C-string) to PATH. COMPONENT is
	allowed to contain directory separators.

	If PATH is non-empty, append the appropriate directory separator
	character, and then COMPONENT. If PATH is empty, simply set it to
	COMPONENT; don't add any separator character.

	If the result ends in a separator character, then remove the separator. */
	void svn_path_add_component (svn_stringbuf_t *path,
	const svn_stringbuf_t *component);

	/* Same as `svn_path_add_component', except that the COMPONENT argument is
	a C-style '\0'-terminated string, not an svn_stringbuf_t. */
	void svn_path_add_component_nts (svn_stringbuf_t *path,
	const char *component);

	/* Remove one component off the end of PATH. */
	void svn_path_remove_component (svn_stringbuf_t *path);



	/* Divide PATH into DIRPATH and BASENAME, return them by reference,
	* in their own storage in POOL.
	*
	* If DIRPATH or BASENAME is null, then that one will not be used.
	*
	* DIRPATH or BASENAME may be PATH's own address, but they may not
	* both be PATH's address; in fact, in general they must not be the
	* same, or the results are undefined.
	*
	* The separator between DIRPATH and BASENAME is not included in
	* either of the new names.
	*/
	void svn_path_split (const svn_stringbuf_t *path,
	svn_stringbuf_t **dirpath,
	svn_stringbuf_t **basename,
	apr_pool_t *pool);


	/* Return non-zero iff PATH is empty or represents the current
	directory -- that is, if it is NULL or if prepending it as a
	component to an existing path would result in no meaningful
	change. */
	int svn_path_is_empty (const svn_stringbuf_t *path);


	/* Remove trailing separators that don't affect the meaning of the path.
	(At some future point, this may make other semantically inoperative
	transformations.) */
	void svn_path_canonicalize (svn_stringbuf_t *path);


	/* Return an integer greater than, equal to, or less than 0, according
	as PATH1 is greater than, equal to, or less than PATH2. */
	int svn_path_compare_paths (const svn_stringbuf_t *path1,
	const svn_stringbuf_t *path2);


	/* Return the longest common path shared by both PATH1 and PATH2. If
	there's no common ancestor, return NULL. */
	svn_stringbuf_t svn_path_get_longest_ancestor (const svn_stringbuf_t path1,
	const svn_stringbuf_t *path2,
	apr_pool_t *pool);

	/* Convert RELATIVE path to an absolute path and return the results in
	PABSOLUTE. /
	svn_error_t *
	svn_path_get_absolute(svn_stringbuf_t **pabsolute,
	const svn_stringbuf_t *relative,
	apr_pool_t *pool);

	/* Return the path part of PATH in PDIRECTORY, and the file part in PFILE.
	If PATH is a directory, it will be returned through PDIRECTORY, and *PFILE
	will be the empty string (not NULL). */
	svn_error_t *
	svn_path_split_if_file(svn_stringbuf_t *path,
	svn_stringbuf_t **pdirectory,
	svn_stringbuf_t **pfile,
	apr_pool_t *pool);

	/* Find the common prefix of the paths in TARGETS, and remove redundancies.
	*
	* The elements in TARGETS must be existing files or directories.
	*
	* If there are multiple targets, or exactly one target and it's not a
	* directory, then
	*
	* - *PBASENAME is set to the absolute path of the common parent
	* directory of all of those targets, and
	*
	* - If PCONDENSED_TARGETS is non-null, *PCONDENSED_TARGETS is set
	* to an array of targets relative to *PBASENAME, with
	* redundancies removed (meaning that none of these targets will
	* be the same as, nor have an ancestor/descendant relationship
	* with, any of the other targets; nor will any of them be the
	* same as *PBASENAME). Else if PCONDENSED_TARGETS is null, it is
	* left untouched.
	*
	* Else if there is exactly one directory target, then
	*
	* - *PBASENAME is set to that directory, and
	*
	* - If PCONDENSED_TARGETS is non-null, *PCONDENSED_TARGETS is set
	* to an array containing zero elements. Else if
	* PCONDENSED_TARGETS is null, it is left untouched.
	*
	* If there are no items in TARGETS, *PBASENAME and (if applicable)
	* *PCONDENSED_TARGETS will be NULL.
	*
	* NOTE: There is no guarantee that *PBASENAME is within a working
	* copy.
	*/
	svn_error_t *
	svn_path_condense_targets (svn_stringbuf_t **pbasename,
	apr_array_header_t **pcondensed_targets,
	const apr_array_header_t *targets,
	apr_pool_t *pool);


	/* Copy a list of TARGETS, one at a time, into PCONDENSED_TARGETS,
	omitting any targets that are found earlier in the list, or whose
	ancestor is found earlier in the list. Ordering of targets in the
	original list is preserved in the condensed list of targets. Use
	POOL for any allocations.

	How does this differ in functionality from svn_path_condense_targets?

	Here's the short version:

	1. Disclaimer: if you wish to debate the following, talk to Karl. :-)
	Order matters for updates because a multi-arg update is not
	atomic, and CVS users are used to, when doing 'cvs up targetA
	targetB' seeing targetA get updated, then targetB. I think the
	idea is that if you're in a time-sensitive or flaky-network
	situation, a user can say, "I really need to update
	wc/A/D/G/tau, but I might as well update my whole working copy if
	I can." So that user will do 'svn up wc/A/D/G/tau wc', and if
	something dies in the middles of the 'wc' update, at least the
	user has 'tau' up-to-date.

	2. Also, we have this notion of an anchor and a target for updates
	(the anchor is where the update editor is rooted, the target is
	the actual thing we want to update). I needed a function that
	would NOT screw with my input paths so that I could tell the
	difference between someone being in A/D and saying 'svn up G' and
	being in A/D/G and saying 'svn up .' -- believe it or not, these
	two things don't mean the same thing. svn_path_condense_targets
	plays with absolute paths (which is fine, so does
	svn_path_remove_redundancies), but the difference is that it
	actually tweaks those targets to be relative to the "grandfather
	path" common to all the targets. Updates don't require a
	"grandfather path" at all, and even if it did, the whole
	conversion to an absolute path drops the crucial difference
	between saying "i'm in foo, update bar" and "i'm in foo/bar,
	update '.'"
	*/
	svn_error_t *
	svn_path_remove_redundancies (apr_array_header_t **pcondensed_targets,
	const apr_array_header_t *targets,
	apr_pool_t *pool);


	/* Decompose PATH into an array of svn_stringbuf_t components, allocated
	in POOL. STYLE indicates the dir separator to split the string on.
	If PATH is absolute, the first component will be a lone dir
	separator (the root directory). */
	apr_array_header_t svn_path_decompose (const svn_stringbuf_t path,
	apr_pool_t *pool);



	/* Test if PATH2 is a child of PATH1.
	If not, return NULL.
	If so, return the "remainder" path. (The substring which, when
	appended to PATH1, yields PATH2 -- minus the dirseparator. ) */
	svn_stringbuf_t svn_path_is_child (const svn_stringbuf_t path1,
	const svn_stringbuf_t *path2,
	apr_pool_t *pool);

	/* Compare PATH to an array of const char * URL SCHEMES (like "file",
	"http", etc.) to determine if PATH looks like a URL. If so, return
	the matching scheme used by PATH, else return NULL. Returned
	values point to the allocations in SCHEMES. */
	svn_boolean_t svn_path_is_url (const svn_string_t *path);

	/* Return TRUE if PATH is URI-safe, FALSE otherwise. */
	svn_boolean_t svn_path_is_uri_safe (const svn_string_t *path);

	/* Return a URI-encoded copy of PATH, allocated in POOL. */
	svn_stringbuf_t svn_path_uri_encode (const svn_string_t path,
	apr_pool_t *pool);

	/* Return a URI-decoded copy of PATH, allocated in POOL. */
	svn_stringbuf_t svn_path_uri_decode (const svn_string_t path,
	apr_pool_t *pool);


	#endif /* SVN_PATH_H */

	#ifdef __cplusplus
	}
	#endif /* __cplusplus */


	/* ----------------------------------------------------------------
	* local variables:
	* eval: (load-file "../../tools/dev/svn-dev.el")
	* end:
	*/