2 Copyright (C) 2007 Tim Mayberry
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or
7 (at your option) any later version.
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
20 #ifndef PBD_FILE_UTILS_INCLUDED
21 #define PBD_FILE_UTILS_INCLUDED
26 #include <glibmm/pattern.h>
28 #include "pbd/libpbd_visibility.h"
29 #include "pbd/search_path.h"
34 * Get a list of path entries in a directory or within a directory tree
36 * @note paths in result will be absolute
38 * @param result A vector of absolute paths to the directory entries in filename
40 * @param paths A Searchpath
41 * @param files_only Only include file entries in result
42 * @param recurse Recurse into child directories
45 get_paths (std::vector<std::string>& result,
46 const Searchpath& paths,
47 bool files_only = true,
48 bool recurse = false);
51 * Get a list of files in a Searchpath.
52 * @note paths in result will be absolute.
54 * @param path A Searchpath
55 * @param result A vector of paths to files.
58 get_files (std::vector<std::string>& result,
59 const Searchpath& paths);
62 * Takes a Searchpath and returns all the files contained in the
63 * directory paths that match a particular pattern.
65 * @param result A vector in which to place the resulting matches.
66 * @param paths A Searchpath
67 * @param pattern A Glib::PatternSpec used to match the files.
70 find_files_matching_pattern (std::vector<std::string>& result,
71 const Searchpath& paths,
72 const Glib::PatternSpec& pattern);
75 * Takes a Searchpath and returns all the files contained in the
76 * directory paths that match a particular pattern.
78 * This is a convenience method to avoid explicitly declaring
79 * temporary variables such as:
80 * find_files_matching_pattern (result, paths, string("*.ext"))
82 * @param result A vector in which to place the resulting matches.
83 * @param paths A Searchpath
84 * @param pattern A string representing the Glib::PatternSpec used
88 find_files_matching_pattern (std::vector<std::string>& result,
89 const Searchpath& paths,
90 const std::string& pattern);
93 * Takes a search path and a file name and places the full path
94 * to that file in result if it is found within the search path.
96 * @note the parameter order of this function doesn't match the
97 * others. At the time of writing it is the most widely used file
98 * utility function so I didn't change it but it may be worth
99 * doing at some point if it causes any confusion.
101 * @return true If file is found within the search path.
104 find_file (const Searchpath& search_path,
105 const std::string& filename,
106 std::string& result);
110 * Find files in paths that match a regular expression
111 * @note This function does not recurse.
113 * @param result A vector in which to place the resulting matches.
114 * @param paths A Searchpath
115 * @param regexp A regular expression
118 find_files_matching_regex (std::vector<std::string>& results,
119 const Searchpath& paths,
120 const std::string& regexp);
123 * Find paths in a Searchpath that match a supplied filter(functor)
124 * @note results include files and directories.
126 * @param result A vector in which to place the resulting matches.
127 * @param paths A Searchpath
128 * @param filter A functor to use to filter paths
129 * @param arg additonal argument to filter if required
130 * @param pass_fullpath pass the full path to the filter or just the basename
131 * @param return_fullpath put the full path in results or just the basename
132 * @param recurse Recurse into child directories to find paths.
135 find_paths_matching_filter (std::vector<std::string>& results,
136 const Searchpath& paths,
137 bool (*filter)(const std::string &, void *),
140 bool return_fullpath,
141 bool recurse = false);
144 * Find paths in a Searchpath that match a supplied filter(functor)
145 * @note results include only files.
147 * @param result A vector in which to place the resulting matches.
148 * @param paths A Searchpath
149 * @param filter A functor to use to filter paths
150 * @param arg additonal argument to filter if required
151 * @param pass_fullpath pass the full path to the filter or just the basename
152 * @param return_fullpath put the full path in results or just the basename
153 * @param recurse Recurse into child directories to find files.
156 find_files_matching_filter (std::vector<std::string>& results,
157 const Searchpath& paths,
158 bool (*filter)(const std::string &, void *),
161 bool return_fullpath,
162 bool recurse = false);
165 * Attempt to copy the contents of the file from_path to a new file
166 * at path to_path. If to_path exists it is overwritten.
168 * @return true if file was successfully copied
170 LIBPBD_API bool copy_file(const std::string & from_path, const std::string & to_path);
173 * Attempt to copy all regular files from from_path to a new directory.
174 * This method does not recurse.
176 LIBPBD_API void copy_files(const std::string & from_path, const std::string & to_dir);
179 * Take a (possibly) relative path and make it absolute
180 * @return An absolute path
182 LIBPBD_API std::string get_absolute_path (const std::string &);
185 * Take a path/filename and return the suffix (characters beyond the last '.'
186 * @return A string containing the suffix, which will be empty
187 * if there are no '.' characters in the path/filename.
189 LIBPBD_API std::string get_suffix (const std::string &);
192 * Find out if `needle' is a file or directory within the
193 * directory `haystack'.
194 * @return true if it is.
196 LIBPBD_API bool path_is_within (const std::string &, std::string);
199 * @return true if p1 and p2 both resolve to the same file
200 * @param p1 a file path.
201 * @param p2 a file path.
203 * Uses g_stat to check for identical st_dev and st_ino values.
205 LIBPBD_API bool equivalent_paths (const std::string &p1, const std::string &p2);
207 /// @return true if path at p exists and is writable, false otherwise
208 LIBPBD_API bool exists_and_writable(const std::string & p);
211 * Remove all the files in a directory recursively leaving the directory
212 * structure in place.
213 * @note dir will not be removed
215 * @param dir The directory to clear of files.
216 * @param size of removed files in bytes.
217 * @param list of files that were removed.
219 LIBPBD_API int clear_directory (const std::string& dir, size_t* size = 0,
220 std::vector<std::string>* removed_files = 0);
223 * Remove all the contents of a directory recursively.
224 * @note dir will not be removed
226 * @param dir The directory to remove files from.
228 LIBPBD_API void remove_directory (const std::string& dir);