libs/pbd/pbd/file_utils.h

   1 /*
   2  * Copyright (C) 2007-2016 Tim Mayberry <mojofunk@gmail.com>
   3  * Copyright (C) 2008-2015 Paul Davis <paul@linuxaudiosystems.com>
   4  * Copyright (C) 2014-2015 Robin Gareus <robin@gareus.org>
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19  */
  20
  21 #ifndef PBD_FILE_UTILS_INCLUDED
  22 #define PBD_FILE_UTILS_INCLUDED
  23
  24 #include <string>
  25 #include <vector>
  26
  27 #include <glibmm/pattern.h>
  28
  29 #include "pbd/libpbd_visibility.h"
  30 #include "pbd/search_path.h"
  31
  32 namespace PBD {
  33
  34 /**
  35  * Get a list of path entries in a directory or within a directory tree
  36  * if recursing.
  37  * @note paths in result will be absolute
  38  *
  39  * @param result A vector of absolute paths to the directory entries in filename
  40  * encoding.
  41  * @param paths A Searchpath
  42  * @param files_only Only include file entries in result
  43  * @param recurse Recurse into child directories
  44  */
  45 LIBPBD_API void
  46 get_paths (std::vector<std::string>& result,
  47            const Searchpath& paths,
  48            bool files_only = true,
  49            bool recurse = false);
  50
  51 /**
  52  * Get a list of files in a Searchpath.
  53  * @note paths in result will be absolute.
  54  *
  55  * @param path A Searchpath
  56  * @param result A vector of paths to files.
  57  */
  58 LIBPBD_API void
  59 get_files (std::vector<std::string>& result,
  60            const Searchpath& paths);
  61
  62 /**
  63  * Takes a Searchpath and returns all the files contained in the
  64  * directory paths that match a particular pattern.
  65  *
  66  * @param result A vector in which to place the resulting matches.
  67  * @param paths A Searchpath
  68  * @param pattern A Glib::PatternSpec used to match the files.
  69  */
  70 LIBPBD_API void
  71 find_files_matching_pattern (std::vector<std::string>& result,
  72                              const Searchpath& paths,
  73                              const Glib::PatternSpec& pattern);
  74
  75 /**
  76  * Takes a Searchpath and returns all the files contained in the
  77  * directory paths that match a particular pattern.
  78  *
  79  * This is a convenience method to avoid explicitly declaring
  80  * temporary variables such as:
  81  * find_files_matching_pattern (result, paths, string("*.ext"))
  82  *
  83  * @param result A vector in which to place the resulting matches.
  84  * @param paths A Searchpath
  85  * @param pattern A string representing the Glib::PatternSpec used
  86  * to match the files.
  87  */
  88 LIBPBD_API void
  89 find_files_matching_pattern (std::vector<std::string>& result,
  90                              const Searchpath& paths,
  91                              const std::string& pattern);
  92
  93 /**
  94  * Takes a search path and a file name and places the full path
  95  * to that file in result if it is found within the search path.
  96  *
  97  * @note the parameter order of this function doesn't match the
  98  * others. At the time of writing it is the most widely used file
  99  * utility function so I didn't change it but it may be worth
 100  * doing at some point if it causes any confusion.
 101  *
 102  * @return true If file is found within the search path.
 103  */
 104 LIBPBD_API bool
 105 find_file (const Searchpath& search_path,
 106            const std::string& filename,
 107            std::string& result);
 108
 109
 110 /**
 111  * Find files in paths that match a regular expression
 112  * @note This function does not recurse.
 113  *
 114  * @param result A vector in which to place the resulting matches.
 115  * @param paths A Searchpath
 116  * @param regexp A regular expression
 117  */
 118 LIBPBD_API void
 119 find_files_matching_regex (std::vector<std::string>& results,
 120                            const Searchpath& paths,
 121                            const std::string& regexp,
 122                            bool recurse = false);
 123
 124 /**
 125  * Find paths in a Searchpath that match a supplied filter(functor)
 126  * @note results include files and directories.
 127  *
 128  * @param result A vector in which to place the resulting matches.
 129  * @param paths A Searchpath
 130  * @param filter A functor to use to filter paths
 131  * @param arg additonal argument to filter if required
 132  * @param pass_fullpath pass the full path to the filter or just the basename
 133  * @param return_fullpath put the full path in results or just the basename
 134  * @param recurse Recurse into child directories to find paths.
 135  */
 136 LIBPBD_API void
 137 find_paths_matching_filter (std::vector<std::string>& results,
 138                             const Searchpath& paths,
 139                             bool (*filter)(const std::string &, void *),
 140                             void *arg,
 141                             bool pass_fullpath,
 142                             bool return_fullpath,
 143                             bool recurse = false);
 144
 145 /**
 146  * Find paths in a Searchpath that match a supplied filter(functor)
 147  * @note results include only files.
 148  *
 149  * @param result A vector in which to place the resulting matches.
 150  * @param paths A Searchpath
 151  * @param filter A functor to use to filter paths
 152  * @param arg additonal argument to filter if required
 153  * @param pass_fullpath pass the full path to the filter or just the basename
 154  * @param return_fullpath put the full path in results or just the basename
 155  * @param recurse Recurse into child directories to find files.
 156  */
 157 LIBPBD_API void
 158 find_files_matching_filter (std::vector<std::string>& results,
 159                             const Searchpath& paths,
 160                             bool (*filter)(const std::string &, void *),
 161                             void *arg,
 162                             bool pass_fullpath,
 163                             bool return_fullpath,
 164                             bool recurse = false);
 165
 166 /**
 167  * Attempt to copy the contents of the file from_path to a new file
 168  * at path to_path. If to_path exists it is overwritten.
 169  *
 170  * @return true if file was successfully copied
 171  */
 172 LIBPBD_API bool copy_file(const std::string & from_path, const std::string & to_path);
 173
 174 /**
 175  * Attempt to copy all regular files from from_path to a new directory.
 176  * This method does not recurse.
 177  */
 178 LIBPBD_API void copy_files(const std::string & from_path, const std::string & to_dir);
 179
 180 /**
 181  * Attempt to copy all regular files from from_path to a new directory.
 182  */
 183 LIBPBD_API void copy_recurse(const std::string & from_path, const std::string & to_dir);
 184
 185 /**
 186  * Update the access and modification times of file at @path, creating file if it
 187  * doesn't already exist.
 188  * @path file path to touch
 189  * @return true if file exists or was created and access time updated.
 190  */
 191 LIBPBD_API bool touch_file (const std::string& path);
 192
 193 /** try hard-link a file
 194  * @return true if file was successfully linked
 195  */
 196 LIBPBD_API bool hard_link (const std::string& existing_file, const std::string& new_path);
 197
 198 /**
 199  * Take a (possibly) relative path and make it absolute
 200  * @return An absolute path
 201  */
 202 LIBPBD_API std::string get_absolute_path (const std::string &);
 203
 204 /**
 205  * The equivalent of ::realpath on POSIX systems, on Windows hard
 206  * links/junctions etc are not resolved.
 207  */
 208 LIBPBD_API std::string canonical_path (const std::string& path);
 209
 210 /**
 211  * Take a path/filename and return the suffix (characters beyond the last '.'
 212  * @return A string containing the suffix, which will be empty
 213  * if there are no '.' characters in the path/filename.
 214  */
 215 LIBPBD_API std::string get_suffix (const std::string &);
 216
 217 /**
 218  * Find out if `needle' is a file or directory within the
 219  * directory `haystack'.
 220  * @return true if it is.
 221  */
 222 LIBPBD_API bool path_is_within (const std::string &, std::string);
 223
 224 /**
 225  * @return true if p1 and p2 both resolve to the same file
 226  * @param p1 a file path.
 227  * @param p2 a file path.
 228  *
 229  * Uses g_stat to check for identical st_dev and st_ino values.
 230  */
 231 LIBPBD_API bool equivalent_paths (const std::string &p1, const std::string &p2);
 232
 233 /// @return true if path at p exists and is writable, false otherwise
 234 LIBPBD_API bool exists_and_writable(const std::string & p);
 235
 236 /**
 237  * Remove all the files in a directory recursively leaving the directory
 238  * structure in place.
 239  * @note dir will not be removed
 240  *
 241  * @param dir The directory to clear of files.
 242  * @param size of removed files in bytes.
 243  * @param list of files that were removed.
 244  */
 245 LIBPBD_API int clear_directory (const std::string& dir, size_t* size = 0,
 246                                 std::vector<std::string>* removed_files = 0);
 247
 248 /**
 249  * Remove all the contents of a directory recursively.
 250  * including the dir itself (`rm -rf $dir`)
 251  *
 252  * @param dir The directory to remove recursively
 253  */
 254 LIBPBD_API void remove_directory (const std::string& dir);
 255
 256 /**
 257  * Create a temporary writable directory in which to create
 258  * temporary files. The directory will be created under the
 259  * top level "domain" directory.
 260  *
 261  * For instance tmp_writable_directory ("pbd", "foo") on POSIX
 262  * systems may return a path to a new directory something like
 263  * to /tmp/pbd/foo-1423
 264  *
 265  * @param domain The top level directory
 266  * @param prefix A prefix to use when creating subdirectory name
 267  *
 268  * @return new temporary directory
 269  */
 270 LIBPBD_API std::string tmp_writable_directory (const char* domain, const std::string& prefix);
 271
 272 /** If @param path exists, unlink it. If it doesn't exist, create it.
 273  *
 274  * @return zero if required action was successful, non-zero otherwise.
 275  */
 276
 277 LIBPBD_API int toggle_file_existence (std::string const &);
 278
 279 } // namespace PBD
 280
 281 #endif