libs/pbd/pbd/file_utils.h

   1 /*
   2     Copyright (C) 2007 Tim Mayberry
   3
   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.
   8
   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.
  13
  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.
  17
  18 */
  19
  20 #ifndef PBD_FILE_UTILS_INCLUDED
  21 #define PBD_FILE_UTILS_INCLUDED
  22
  23 #include <string>
  24 #include <vector>
  25
  26 #include <glibmm/pattern.h>
  27
  28 #include "pbd/libpbd_visibility.h"
  29 #include "pbd/search_path.h"
  30
  31 namespace PBD {
  32
  33 /**
  34  * Get a list of path entries in a directory or within a directory tree
  35  * if recursing.
  36  * @note paths in result will be absolute
  37  *
  38  * @param result A vector of absolute paths to the directory entries in filename
  39  * encoding.
  40  * @param paths A Searchpath
  41  * @param files_only Only include file entries in result
  42  * @param recurse Recurse into child directories
  43  */
  44 LIBPBD_API void
  45 get_paths (std::vector<std::string>& result,
  46            const Searchpath& paths,
  47            bool files_only = true,
  48            bool recurse = false);
  49
  50 /**
  51  * Get a list of files in a Searchpath.
  52  * @note paths in result will be absolute.
  53  *
  54  * @param path A Searchpath
  55  * @param result A vector of paths to files.
  56  */
  57 LIBPBD_API void
  58 get_files (std::vector<std::string>& result,
  59            const Searchpath& paths);
  60
  61 /**
  62  * Takes a Searchpath and returns all the files contained in the
  63  * directory paths that match a particular pattern.
  64  *
  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.
  68  */
  69 LIBPBD_API void
  70 find_files_matching_pattern (std::vector<std::string>& result,
  71                              const Searchpath& paths,
  72                              const Glib::PatternSpec& pattern);
  73
  74 /**
  75  * Takes a Searchpath and returns all the files contained in the
  76  * directory paths that match a particular pattern.
  77  *
  78  * This is a convenience method to avoid explicitly declaring
  79  * temporary variables such as:
  80  * find_files_matching_pattern (result, paths, string("*.ext"))
  81  *
  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
  85  * to match the files.
  86  */
  87 LIBPBD_API void
  88 find_files_matching_pattern (std::vector<std::string>& result,
  89                              const Searchpath& paths,
  90                              const std::string& pattern);
  91
  92 /**
  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.
  95  *
  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.
 100  *
 101  * @return true If file is found within the search path.
 102  */
 103 LIBPBD_API bool
 104 find_file (const Searchpath& search_path,
 105            const std::string& filename,
 106            std::string& result);
 107
 108
 109 /**
 110  * Find files in paths that match a regular expression
 111  * @note This function does not recurse.
 112  *
 113  * @param result A vector in which to place the resulting matches.
 114  * @param paths A Searchpath
 115  * @param regexp A regular expression
 116  */
 117 LIBPBD_API void
 118 find_files_matching_regex (std::vector<std::string>& results,
 119                            const Searchpath& paths,
 120                            const std::string& regexp,
 121                            bool recurse = false);
 122
 123 /**
 124  * Find paths in a Searchpath that match a supplied filter(functor)
 125  * @note results include files and directories.
 126  *
 127  * @param result A vector in which to place the resulting matches.
 128  * @param paths A Searchpath
 129  * @param filter A functor to use to filter paths
 130  * @param arg additonal argument to filter if required
 131  * @param pass_fullpath pass the full path to the filter or just the basename
 132  * @param return_fullpath put the full path in results or just the basename
 133  * @param recurse Recurse into child directories to find paths.
 134  */
 135 LIBPBD_API void
 136 find_paths_matching_filter (std::vector<std::string>& results,
 137                             const Searchpath& paths,
 138                             bool (*filter)(const std::string &, void *),
 139                             void *arg,
 140                             bool pass_fullpath,
 141                             bool return_fullpath,
 142                             bool recurse = false);
 143
 144 /**
 145  * Find paths in a Searchpath that match a supplied filter(functor)
 146  * @note results include only files.
 147  *
 148  * @param result A vector in which to place the resulting matches.
 149  * @param paths A Searchpath
 150  * @param filter A functor to use to filter paths
 151  * @param arg additonal argument to filter if required
 152  * @param pass_fullpath pass the full path to the filter or just the basename
 153  * @param return_fullpath put the full path in results or just the basename
 154  * @param recurse Recurse into child directories to find files.
 155  */
 156 LIBPBD_API void
 157 find_files_matching_filter (std::vector<std::string>& results,
 158                             const Searchpath& paths,
 159                             bool (*filter)(const std::string &, void *),
 160                             void *arg,
 161                             bool pass_fullpath,
 162                             bool return_fullpath,
 163                             bool recurse = false);
 164
 165 /**
 166  * Attempt to copy the contents of the file from_path to a new file
 167  * at path to_path. If to_path exists it is overwritten.
 168  *
 169  * @return true if file was successfully copied
 170  */
 171 LIBPBD_API bool copy_file(const std::string & from_path, const std::string & to_path);
 172
 173 /**
 174  * Attempt to copy all regular files from from_path to a new directory.
 175  * This method does not recurse.
 176  */
 177 LIBPBD_API void copy_files(const std::string & from_path, const std::string & to_dir);
 178
 179 /**
 180  * Attempt to copy all regular files from from_path to a new directory.
 181  */
 182 LIBPBD_API void copy_recurse(const std::string & from_path, const std::string & to_dir);
 183
 184 /**
 185  * Update the access and modification times of file at @path, creating file if it
 186  * doesn't already exist.
 187  * @path file path to touch
 188  * @return true if file exists or was created and access time updated.
 189  */
 190 LIBPBD_API bool touch_file (const std::string& path);
 191
 192 /**
 193  * Take a (possibly) relative path and make it absolute
 194  * @return An absolute path
 195  */
 196 LIBPBD_API std::string get_absolute_path (const std::string &);
 197
 198 /**
 199  * The equivalent of ::realpath on POSIX systems, on Windows hard
 200  * links/junctions etc are not resolved.
 201  */
 202 LIBPBD_API std::string canonical_path (const std::string& path);
 203
 204 /**
 205  * Take a path/filename and return the suffix (characters beyond the last '.'
 206  * @return A string containing the suffix, which will be empty
 207  * if there are no '.' characters in the path/filename.
 208  */
 209 LIBPBD_API std::string get_suffix (const std::string &);
 210
 211 /**
 212  * Find out if `needle' is a file or directory within the
 213  * directory `haystack'.
 214  * @return true if it is.
 215  */
 216 LIBPBD_API bool path_is_within (const std::string &, std::string);
 217
 218 /**
 219  * @return true if p1 and p2 both resolve to the same file
 220  * @param p1 a file path.
 221  * @param p2 a file path.
 222  *
 223  * Uses g_stat to check for identical st_dev and st_ino values.
 224  */
 225 LIBPBD_API bool equivalent_paths (const std::string &p1, const std::string &p2);
 226
 227 /// @return true if path at p exists and is writable, false otherwise
 228 LIBPBD_API bool exists_and_writable(const std::string & p);
 229
 230 /**
 231  * Remove all the files in a directory recursively leaving the directory
 232  * structure in place.
 233  * @note dir will not be removed
 234  *
 235  * @param dir The directory to clear of files.
 236  * @param size of removed files in bytes.
 237  * @param list of files that were removed.
 238  */
 239 LIBPBD_API int clear_directory (const std::string& dir, size_t* size = 0,
 240                                 std::vector<std::string>* removed_files = 0);
 241
 242 /**
 243  * Remove all the contents of a directory recursively.
 244  * including the dir itself (`rm -rf $dir`)
 245  *
 246  * @param dir The directory to remove recursively
 247  */
 248 LIBPBD_API void remove_directory (const std::string& dir);
 249
 250 /**
 251  * Create a temporary writable directory in which to create
 252  * temporary files. The directory will be created under the
 253  * top level "domain" directory.
 254  *
 255  * For instance tmp_writable_directory ("pbd", "foo") on POSIX
 256  * systems may return a path to a new directory something like
 257  * to /tmp/pbd/foo-1423
 258  *
 259  * @param domain The top level directory
 260  * @param prefix A prefix to use when creating subdirectory name
 261  *
 262  * @return new temporary directory
 263  */
 264 LIBPBD_API std::string tmp_writable_directory (const char* domain, const std::string& prefix);
 265
 266 /** If @param path exists, unlink it. If it doesn't exist, create it.
 267  *
 268  * @return zero if required action was successful, non-zero otherwise.
 269  */
 270
 271 LIBPBD_API int toggle_file_existence (std::string const &);
 272
 273 } // namespace PBD
 274
 275 #endif