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 contents of directory.
  35  * @note paths in result will be absolute
  36  *
  37  * @param path An absolute path to a directory in the filename encoding
  38  * @param result A vector of absolute paths to the directory entries in filename
  39  * encoding.
  40  * @param files_only Only include file entries in result
  41  * @param recurse Recurse into child directories
  42  */
  43 LIBPBD_API void
  44 get_directory_contents (const std::string& path,
  45                         std::vector<std::string>& result,
  46                         bool files_only = true,
  47                         bool recurse = false);
  48
  49 /**
  50  * Get a list of files in a directory.
  51  * @note You must join path with result to get the absolute path
  52  * to the file.
  53  *
  54  * @param path An Absolute path to a directory
  55  * @param result A vector of filenames.
  56  */
  57 LIBPBD_API void
  58 get_files_in_directory (const std::string& path,
  59                         std::vector<std::string>& result);
  60
  61 /**
  62  * Takes a directory path and returns all the files in the directory
  63  * matching a particular pattern.
  64  *
  65  * @param directory A directory path
  66  * @param pattern A Glib::PatternSpec used to match the files.
  67  * @param result A vector in which to place the resulting matches.
  68  */
  69 LIBPBD_API void
  70 find_matching_files_in_directory (const std::string& directory,
  71                                   const Glib::PatternSpec& pattern,
  72                                   std::vector<std::string>& result);
  73
  74 /**
  75  * Takes a number of directory paths and returns all the files matching
  76  * a particular pattern.
  77  *
  78  * @param paths A vector containing the Absolute paths
  79  * @param pattern A Glib::PatternSpec used to match the files
  80  * @param result A vector in which to place the resulting matches.
  81  */
  82 LIBPBD_API void
  83 find_matching_files_in_directories (const std::vector<std::string>& directory_paths,
  84                                     const Glib::PatternSpec& pattern,
  85                                     std::vector<std::string>& result);
  86
  87 /**
  88  * Takes a Searchpath and puts a list of all the files in the search path
  89  * that match pattern into the result vector.
  90  *
  91  * @param search_path A Searchpath
  92  * @param pattern A Glib::PatternSpec used to match the files
  93  * @param result A vector in which to place the resulting matches.
  94  */
  95 LIBPBD_API void
  96 find_matching_files_in_search_path (const Searchpath& search_path,
  97                                     const Glib::PatternSpec& pattern,
  98                                     std::vector<std::string>& result);
  99
 100 /**
 101  * Takes a search path and a file name and place the full path
 102  * to that file in result if it is found within the search path.
 103  *
 104  * @return true If file is found within the search path.
 105  */
 106 LIBPBD_API bool
 107 find_file_in_search_path (const Searchpath& search_path,
 108                           const std::string& filename,
 109                           std::string& result);
 110
 111
 112 /**
 113  * @return files in dirpath that match a regular expression
 114  */
 115 LIBPBD_API void
 116 find_files_matching_regex (std::vector<std::string>& results,
 117                            const Searchpath& dirpath,
 118                            const std::string& regexp);
 119
 120 /**
 121  * @return files in a Searchpath that match a supplied filter(functor)
 122  */
 123 LIBPBD_API void
 124 find_files_matching_filter (std::vector<std::string>&,
 125                             const Searchpath& paths,
 126                             bool (*filter)(const std::string &, void *),
 127                             void *arg,
 128                             bool match_fullpath,
 129                             bool return_fullpath,
 130                             bool recurse = false);
 131
 132 /**
 133  * Attempt to copy the contents of the file from_path to a new file
 134  * at path to_path. If to_path exists it is overwritten.
 135  *
 136  * @return true if file was successfully copied
 137  */
 138 LIBPBD_API bool copy_file(const std::string & from_path, const std::string & to_path);
 139
 140 /**
 141  * Attempt to copy all regular files from from_path to a new directory.
 142  * This method does not recurse.
 143  */
 144 LIBPBD_API void copy_files(const std::string & from_path, const std::string & to_dir);
 145
 146 /**
 147  * Take a (possibly) relative path and make it absolute
 148  * @return An absolute path
 149  */
 150 LIBPBD_API std::string get_absolute_path (const std::string &);
 151
 152 /**
 153  * Find out if `needle' is a file or directory within the
 154  * directory `haystack'.
 155  * @return true if it is.
 156  */
 157 LIBPBD_API bool path_is_within (const std::string &, std::string);
 158
 159 /**
 160  * @return true if p1 and p2 both resolve to the same file
 161  * @param p1 a file path.
 162  * @param p2 a file path.
 163  *
 164  * Uses g_stat to check for identical st_dev and st_ino values.
 165  */
 166 LIBPBD_API bool equivalent_paths (const std::string &p1, const std::string &p2);
 167
 168 /// @return true if path at p exists and is writable, false otherwise
 169 LIBPBD_API bool exists_and_writable(const std::string & p);
 170
 171 } // namespace PBD
 172
 173 #endif