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 path An absolute path to a directory in the filename encoding
  39  * @param result A vector of absolute paths to the directory entries in filename
  40  * encoding.
  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 std::string& directory_path,
  47            bool files_only = true,
  48            bool recurse = false);
  49
  50 /**
  51  * Get a list of files in a directory.
  52  * @note paths in result will be absolute.
  53  *
  54  * @param path An Absolute path to a directory
  55  * @param result A vector of paths to files.
  56  */
  57 LIBPBD_API void
  58 get_files (std::vector<std::string>& result,
  59            const std::string& path);
  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  * @return true If file is found within the search path.
  97  */
  98 LIBPBD_API bool
  99 find_file (const Searchpath& search_path,
 100            const std::string& filename,
 101            std::string& result);
 102
 103
 104 /**
 105  * @return files in dirpath that match a regular expression
 106  */
 107 LIBPBD_API void
 108 find_files_matching_regex (std::vector<std::string>& results,
 109                            const Searchpath& dirpath,
 110                            const std::string& regexp);
 111
 112 /**
 113  * @return paths in a Searchpath that match a supplied filter(functor)
 114  * @note results include files and directories
 115  */
 116 LIBPBD_API void
 117 find_paths_matching_filter (std::vector<std::string>&,
 118                             const Searchpath& paths,
 119                             bool (*filter)(const std::string &, void *),
 120                             void *arg,
 121                             bool match_fullpath,
 122                             bool return_fullpath,
 123                             bool recurse = false);
 124
 125 /**
 126  * @return files in a Searchpath that match a supplied filter(functor)
 127  */
 128 LIBPBD_API void
 129 find_files_matching_filter (std::vector<std::string>&,
 130                             const Searchpath& paths,
 131                             bool (*filter)(const std::string &, void *),
 132                             void *arg,
 133                             bool match_fullpath,
 134                             bool return_fullpath,
 135                             bool recurse = false);
 136
 137 /**
 138  * Attempt to copy the contents of the file from_path to a new file
 139  * at path to_path. If to_path exists it is overwritten.
 140  *
 141  * @return true if file was successfully copied
 142  */
 143 LIBPBD_API bool copy_file(const std::string & from_path, const std::string & to_path);
 144
 145 /**
 146  * Attempt to copy all regular files from from_path to a new directory.
 147  * This method does not recurse.
 148  */
 149 LIBPBD_API void copy_files(const std::string & from_path, const std::string & to_dir);
 150
 151 /**
 152  * Take a (possibly) relative path and make it absolute
 153  * @return An absolute path
 154  */
 155 LIBPBD_API std::string get_absolute_path (const std::string &);
 156
 157 /**
 158  * Find out if `needle' is a file or directory within the
 159  * directory `haystack'.
 160  * @return true if it is.
 161  */
 162 LIBPBD_API bool path_is_within (const std::string &, std::string);
 163
 164 /**
 165  * @return true if p1 and p2 both resolve to the same file
 166  * @param p1 a file path.
 167  * @param p2 a file path.
 168  *
 169  * Uses g_stat to check for identical st_dev and st_ino values.
 170  */
 171 LIBPBD_API bool equivalent_paths (const std::string &p1, const std::string &p2);
 172
 173 /// @return true if path at p exists and is writable, false otherwise
 174 LIBPBD_API bool exists_and_writable(const std::string & p);
 175
 176 /**
 177  * Remove all the files in a directory recursively leaving the directory
 178  * structure in place.
 179  * @note dir will not be removed
 180  *
 181  * @param dir The directory to clear of files.
 182  * @param size of removed files in bytes.
 183  * @param list of files that were removed.
 184  */
 185 LIBPBD_API int clear_directory (const std::string& dir, size_t* size = 0,
 186                                 std::vector<std::string>* removed_files = 0);
 187
 188 /**
 189  * Remove all the contents of a directory recursively.
 190  * @note dir will not be removed
 191  *
 192  * @param dir The directory to remove files from.
 193  */
 194 LIBPBD_API void remove_directory (const std::string& dir);
 195
 196 } // namespace PBD
 197
 198 #endif