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