X-Git-Url: https://main.carlh.net/gitweb/?a=blobdiff_plain;f=libs%2Fpbd%2Fpbd%2Ffile_utils.h;h=e9baaa3e81cd592e9289496400c7f35efd352a86;hb=ae4e84fd51daa868f6f5f457935c2c186a2bb659;hp=ce5422db132ef8646e820c07552e409e0d36c4ea;hpb=e0aaed6d65f160c328cb8b56d7c6552ee15d65e2;p=ardour.git diff --git a/libs/pbd/pbd/file_utils.h b/libs/pbd/pbd/file_utils.h index ce5422db13..e9baaa3e81 100644 --- a/libs/pbd/pbd/file_utils.h +++ b/libs/pbd/pbd/file_utils.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2007 Tim Mayberry + Copyright (C) 2007 Tim Mayberry This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -25,75 +25,245 @@ #include +#include "pbd/libpbd_visibility.h" #include "pbd/search_path.h" namespace PBD { -using std::string; -using std::vector; +/** + * Get a list of path entries in a directory or within a directory tree + * if recursing. + * @note paths in result will be absolute + * + * @param result A vector of absolute paths to the directory entries in filename + * encoding. + * @param paths A Searchpath + * @param files_only Only include file entries in result + * @param recurse Recurse into child directories + */ +LIBPBD_API void +get_paths (std::vector& result, + const Searchpath& paths, + bool files_only = true, + bool recurse = false); /** - * Get a list of files in a directory. - * @note You must join path with result to get the absolute path - * to the file. + * Get a list of files in a Searchpath. + * @note paths in result will be absolute. * - * @param path An Absolute path to a directory - * @param result A vector of filenames. + * @param path A Searchpath + * @param result A vector of paths to files. */ -void -get_files_in_directory (const sys::path& path, - vector& result); +LIBPBD_API void +get_files (std::vector& result, + const Searchpath& paths); /** - * Takes a directory path and returns all the files in the directory - * matching a particular pattern. + * Takes a Searchpath and returns all the files contained in the + * directory paths that match a particular pattern. * - * @param directory A directory path + * @param result A vector in which to place the resulting matches. + * @param paths A Searchpath * @param pattern A Glib::PatternSpec used to match the files. + */ +LIBPBD_API void +find_files_matching_pattern (std::vector& result, + const Searchpath& paths, + const Glib::PatternSpec& pattern); + +/** + * Takes a Searchpath and returns all the files contained in the + * directory paths that match a particular pattern. + * + * This is a convenience method to avoid explicitly declaring + * temporary variables such as: + * find_files_matching_pattern (result, paths, string("*.ext")) + * * @param result A vector in which to place the resulting matches. + * @param paths A Searchpath + * @param pattern A string representing the Glib::PatternSpec used + * to match the files. */ -void -find_matching_files_in_directory (const sys::path& directory, - const Glib::PatternSpec& pattern, - vector& result); +LIBPBD_API void +find_files_matching_pattern (std::vector& result, + const Searchpath& paths, + const std::string& pattern); + +/** + * Takes a search path and a file name and places the full path + * to that file in result if it is found within the search path. + * + * @note the parameter order of this function doesn't match the + * others. At the time of writing it is the most widely used file + * utility function so I didn't change it but it may be worth + * doing at some point if it causes any confusion. + * + * @return true If file is found within the search path. + */ +LIBPBD_API bool +find_file (const Searchpath& search_path, + const std::string& filename, + std::string& result); + /** - * Takes a number of directory paths and returns all the files matching - * a particular pattern. + * Find files in paths that match a regular expression + * @note This function does not recurse. * - * @param paths A vector containing the Absolute paths - * @param pattern A Glib::PatternSpec used to match the files * @param result A vector in which to place the resulting matches. + * @param paths A Searchpath + * @param regexp A regular expression */ -void -find_matching_files_in_directories (const vector& directory_paths, - const Glib::PatternSpec& pattern, - vector& result); +LIBPBD_API void +find_files_matching_regex (std::vector& results, + const Searchpath& paths, + const std::string& regexp, + bool recurse = false); /** - * Takes a SearchPath and puts a list of all the files in the search path - * that match pattern into the result vector. + * Find paths in a Searchpath that match a supplied filter(functor) + * @note results include files and directories. * - * @param search_path A SearchPath - * @param pattern A Glib::PatternSpec used to match the files * @param result A vector in which to place the resulting matches. + * @param paths A Searchpath + * @param filter A functor to use to filter paths + * @param arg additonal argument to filter if required + * @param pass_fullpath pass the full path to the filter or just the basename + * @param return_fullpath put the full path in results or just the basename + * @param recurse Recurse into child directories to find paths. */ -void -find_matching_files_in_search_path (const SearchPath& search_path, - const Glib::PatternSpec& pattern, - vector& result); +LIBPBD_API void +find_paths_matching_filter (std::vector& results, + const Searchpath& paths, + bool (*filter)(const std::string &, void *), + void *arg, + bool pass_fullpath, + bool return_fullpath, + bool recurse = false); /** - * Takes a search path and a file name and place the full path - * to that file in result if it is found within the search path. + * Find paths in a Searchpath that match a supplied filter(functor) + * @note results include only files. * - * @return true If file is found within the search path. + * @param result A vector in which to place the resulting matches. + * @param paths A Searchpath + * @param filter A functor to use to filter paths + * @param arg additonal argument to filter if required + * @param pass_fullpath pass the full path to the filter or just the basename + * @param return_fullpath put the full path in results or just the basename + * @param recurse Recurse into child directories to find files. + */ +LIBPBD_API void +find_files_matching_filter (std::vector& results, + const Searchpath& paths, + bool (*filter)(const std::string &, void *), + void *arg, + bool pass_fullpath, + bool return_fullpath, + bool recurse = false); + +/** + * Attempt to copy the contents of the file from_path to a new file + * at path to_path. If to_path exists it is overwritten. + * + * @return true if file was successfully copied + */ +LIBPBD_API bool copy_file(const std::string & from_path, const std::string & to_path); + +/** + * Attempt to copy all regular files from from_path to a new directory. + * This method does not recurse. + */ +LIBPBD_API void copy_files(const std::string & from_path, const std::string & to_dir); + +/** + * Attempt to copy all regular files from from_path to a new directory. + */ +LIBPBD_API void copy_recurse(const std::string & from_path, const std::string & to_dir); + +/** + * Update the access and modification times of file at @path, creating file if it + * doesn't already exist. + * @path file path to touch + * @return true if file exists or was created and access time updated. */ -bool -find_file_in_search_path (const SearchPath& search_path, - const string& filename, - sys::path& result); - +LIBPBD_API bool touch_file (const std::string& path); + +/** + * Take a (possibly) relative path and make it absolute + * @return An absolute path + */ +LIBPBD_API std::string get_absolute_path (const std::string &); + +/** + * Take a path/filename and return the suffix (characters beyond the last '.' + * @return A string containing the suffix, which will be empty + * if there are no '.' characters in the path/filename. + */ +LIBPBD_API std::string get_suffix (const std::string &); + +/** + * Find out if `needle' is a file or directory within the + * directory `haystack'. + * @return true if it is. + */ +LIBPBD_API bool path_is_within (const std::string &, std::string); + +/** + * @return true if p1 and p2 both resolve to the same file + * @param p1 a file path. + * @param p2 a file path. + * + * Uses g_stat to check for identical st_dev and st_ino values. + */ +LIBPBD_API bool equivalent_paths (const std::string &p1, const std::string &p2); + +/// @return true if path at p exists and is writable, false otherwise +LIBPBD_API bool exists_and_writable(const std::string & p); + +/** + * Remove all the files in a directory recursively leaving the directory + * structure in place. + * @note dir will not be removed + * + * @param dir The directory to clear of files. + * @param size of removed files in bytes. + * @param list of files that were removed. + */ +LIBPBD_API int clear_directory (const std::string& dir, size_t* size = 0, + std::vector* removed_files = 0); + +/** + * Remove all the contents of a directory recursively. + * including the dir itself (`rm -rf $dir`) + * + * @param dir The directory to remove recursively + */ +LIBPBD_API void remove_directory (const std::string& dir); + +/** + * Create a temporary writable directory in which to create + * temporary files. The directory will be created under the + * top level "domain" directory. + * + * For instance tmp_writable_directory ("pbd", "foo") on POSIX + * systems may return a path to a new directory something like + * to /tmp/pbd/foo-1423 + * + * @param domain The top level directory + * @param prefix A prefix to use when creating subdirectory name + * + * @return new temporary directory + */ +LIBPBD_API std::string tmp_writable_directory (const char* domain, const std::string& prefix); + +/** If @param path exists, unlink it. If it doesn't exist, create it. + * + * @return zero if required action was successful, non-zero otherwise. + */ + +LIBPBD_API int toggle_file_existence (std::string const &); + } // namespace PBD #endif