Move path related functions from fileops to path

This takes all of the functions that look up simple data about
paths (such as `git_futils_isdir`) and moves them over to path.h
(becoming `git_path_isdir`).  This leaves fileops.h just with
functions that actually manipulate the filesystem or look at
the file contents in some way.

As part of this, the dir.h header which is really just for win32
support was moved into win32 (with some minor changes).

1 files changed, 137 insertions, 12 deletions

diff --git a/src/path.h b/src/path.h
index e59c19ad9..ee3607ce9 100644
--- a/src/path.h
+++ b/src/path.h
@@ -10,6 +10,13 @@
 #include "common.h"
 #include "buffer.h"
 
+/**
+ * Path manipulation utils
+ *
+ * These are path utilities that munge paths without actually
+ * looking at the real filesystem.
+ */
+
 /*
  * The dirname() function shall take a pointer to a character string
  * that contains a pathname, and return a pointer to a string that is a
@@ -52,15 +59,30 @@ extern int git_path_basename_r(git_buf *buffer, const char *path);
 
 extern const char *git_path_topdir(const char *path);
 
+/**
+ * Find offset to root of path if path has one.
+ *
+ * This will return a number >= 0 which is the offset to the start of the
+ * path, if the path is rooted (i.e. "/rooted/path" returns 0 and
+ * "c:/windows/rooted/path" returns 2).  If the path is not rooted, this
+ * returns < 0.
+ */
 extern int git_path_root(const char *path);
 
-extern int git_path_prettify(git_buf *path_out, const char *path, const char *base);
-extern int git_path_prettify_dir(git_buf *path_out, const char *path, const char *base);
-
+/**
+ * Ensure path has a trailing '/'.
+ */
 extern int git_path_to_dir(git_buf *path);
+
+/**
+ * Ensure string has a trailing '/' if there is space for it.
+ */
 extern void git_path_string_to_dir(char* path, size_t size);
 
 #ifdef GIT_WIN32
+/**
+ * Convert backslashes in path to forward slashes.
+ */
 GIT_INLINE(void) git_path_mkposix(char *path)
 {
 	while (*path) {
@@ -75,20 +97,123 @@ GIT_INLINE(void) git_path_mkposix(char *path)
 #endif
 
 extern int git__percent_decode(git_buf *decoded_out, const char *input);
+
+/**
+ * Extract path from file:// URL.
+ */
 extern int git_path_fromurl(git_buf *local_path_out, const char *file_url);
 
+
+/**
+ * Path filesystem utils
+ *
+ * These are path utilities that actually access the filesystem.
+ */
+
+/**
+ * Check if a file exists and can be accessed.
+ * @return GIT_SUCCESS if file exists, < 0 otherwise.
+ */
+extern int git_path_exists(const char *path);
+
+/**
+ * Check if the given path points to a directory.
+ * @return GIT_SUCCESS if it is a directory, < 0 otherwise.
+ */
+extern int git_path_isdir(const char *path);
+
 /**
- * Invoke callback directory by directory up the path until the ceiling
- * is reached (inclusive of a final call at the root_path).
+ * Check if the given path points to a regular file.
+ * @return GIT_SUCCESS if it is a regular file, < 0 otherwise.
+ */
+extern int git_path_isfile(const char *path);
+
+/**
+ * Check if the given path contains the given subdirectory.
+ *
+ * @param parent Directory path that might contain subdir
+ * @param subdir Subdirectory name to look for in parent
+ * @param append_if_exists If true, then subdir will be appended to the parent path if it does exist
+ * @return GIT_SUCCESS if subdirectory exists, < 0 otherwise.
+ */
+extern int git_path_contains_dir(git_buf *parent, const char *subdir, int append_if_exists);
+
+/**
+ * Check if the given path contains the given file.
+ *
+ * @param dir Directory path that might contain file
+ * @param file File name to look for in parent
+ * @param append_if_exists If true, then file will be appended to the path if it does exist
+ * @return GIT_SUCCESS if file exists, < 0 otherwise.
+ */
+extern int git_path_contains_file(git_buf *dir, const char *file, int append_if_exists);
+
+/**
+ * Clean up path, prepending base if it is not already rooted.
+ */
+extern int git_path_prettify(git_buf *path_out, const char *path, const char *base);
+
+/**
+ * Clean up path, prepending base if it is not already rooted and
+ * appending a slash.
+ */
+extern int git_path_prettify_dir(git_buf *path_out, const char *path, const char *base);
+
+/**
+ * Get a directory from a path.
+ *
+ * If path is a directory, this acts like `git_path_prettify_dir`
+ * (cleaning up path and appending a '/').  If path is a normal file,
+ * this prettifies it, then removed the filename a la dirname and
+ * appends the trailing '/'.  If the path does not exist, it is
+ * treated like a regular filename.
+ */
+extern int git_path_find_dir(git_buf *dir, const char *path, const char *base);
+
+/**
+ * Walk each directory entry, except '.' and '..', calling fn(state).
+ *
+ * @param pathbuf buffer the function reads the initial directory
+ * 		path from, and updates with each successive entry's name.
+ * @param fn function to invoke with each entry. The first arg is
+ *		the input state and the second arg is pathbuf. The function
+ *		may modify the pathbuf, but only by appending new text.
+ * @param state to pass to fn as the first arg.
+ */
+extern int git_path_direach(
+	git_buf *pathbuf,
+	int (*fn)(void *, git_buf *),
+	void *state);
+
+/**
+ * Sort function to order two paths.
+ */
+extern int git_path_cmp(
+	const char *name1, int len1, int isdir1,
+	const char *name2, int len2, int isdir2);
+
+/**
+ * Invoke callback up path directory by directory until the ceiling is
+ * reached (inclusive of a final call at the root_path).
+ *
+ * Returning anything other than GIT_SUCCESS from the callback function
+ * will stop the iteration and propogate the error to the caller.
  *
- * If the ceiling is NULL, this will walk all the way up to the root.
- * If the ceiling is not a prefix of the path, the callback will be
- * invoked a single time on the verbatim input path.  Returning anything
- * other than GIT_SUCCESS from the callback function will stop the
- * iteration and propogate the error to the caller.
+ * @param pathbuf Buffer the function reads the directory from and
+ *		and updates with each successive name.
+ * @param ceiling Prefix of path at which to stop walking up.  If NULL,
+ *      this will walk all the way up to the root.  If not a prefix of
+ *      pathbuf, the callback will be invoked a single time on the
+ *      original input path.
+ * @param fn Function to invoke on each path.  The first arg is the
+ *		input satte and the second arg is the pathbuf.  The function
+ *		should not modify the pathbuf.
+ * @param state Passed to fn as the first ath.
  */
 extern int git_path_walk_up(
-	git_buf *path, const char *ceiling,
-	int (*cb)(void *data, git_buf *), void *data);
+	git_buf *pathbuf,
+	const char *ceiling,
+	int (*fn)(void *state, git_buf *),
+	void *state);
 
 #endif