libs/pbd/pbd/filesystem.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  * @namespace PBD::sys
  21  *
  22  * The API in this file is intended to be as close as possible to the
  23  * boost::filesystem API but implementing only the subset of it that is required
  24  * by ardour using the glib/glibmm file utility functions in the implementation.
  25  *
  26  * More information about boost::filesystem and the TR2 proposal at
  27  *
  28  * http://www.boost.org/libs/filesystem/doc/tr2_proposal.html
  29  *
  30  * Hopefully the boost::filesystem API will pass TR2 review etc and become part
  31  * of the C++ standard and this code can be removed, or we just end up using
  32  * the boost filesystem library when it matures a bit more.
  33  *
  34  * My reasons for writing this thin wrapper instead of using glib directly or
  35  * using boost::filesystem immediately are:
  36  *
  37  *  - Using sys::path instead of strings and Glib::build_filename is more
  38  *    convenient, terse and forces correct platform agnostic path building.
  39  *
  40  *  - Using boost::filesystem on windows would mean converting between any UTF-8
  41  *    encoded strings(such as when selecting a file/directory in the gtk file
  42  *    chooser) and the native file encoding (UTF-16). It would take some time
  43  *    and testing to find out when this is required and the glib functions already
  44  *    do this if necessary.
  45  *
  46  *  - Using exceptions to indicate errors is more likely to uncover situations
  47  *    where error conditions are being silently ignored(I've already encounted
  48  *    a few examples of this in the ardour code).
  49  *
  50  *  - Many of the glib file utility functions are not wrapped by glibmm so this
  51  *    also provides what I think is a better API.
  52  *
  53  *  - Using boost::filesystem directly means another library dependence and would
  54  *    require more testing on windows because of the character encoding issue.
  55  *
  56  *  - The boost::filesystem API changes a bit as part of the TR2 review process etc.
  57  */
  58
  59 #ifndef __filesystem_h__
  60 #define __filesystem_h__
  61
  62 #include <stdexcept>
  63 #include <string>
  64
  65 namespace PBD {
  66
  67 namespace sys {
  68
  69 class path
  70 {
  71 public:
  72         path() : m_path("") { }
  73         path(const path & p) : m_path(p.m_path) { }
  74         path(const std::string & s) : m_path(s) { }
  75         path(const char* s) : m_path(s) { }
  76
  77         path& operator=(const path& p) { m_path = p.m_path; return *this;}
  78         path& operator=(const std::string& s) { m_path = s; return *this; }
  79         path& operator=(const char* s) { m_path = s; return *this; }
  80
  81         path& operator/=(const path& rhs);
  82         path& operator/=(const std::string& s);
  83         path& operator/=(const char* s);
  84
  85         const std::string to_string() const { return m_path; }
  86
  87         /**
  88          * @return the last component of the path, if the path refers to
  89          * a file then it will be the entire filename including any extension.
  90          */
  91         std::string leaf () const;
  92
  93         /**
  94          * @returns the directory component of a path without any trailing
  95          * path separator or an empty string if the path has no directory
  96          * component(branch path).
  97          */
  98         path branch_path () const;
  99
 100 private:
 101
 102         std::string m_path;
 103 };
 104
 105 class filesystem_error : public std::runtime_error
 106 {
 107         const int m_error_code;
 108
 109 public:
 110         explicit filesystem_error(const std::string & what, int error_code=0)
 111                 : std::runtime_error(what), m_error_code(error_code) { }
 112
 113         int system_error() const { return m_error_code; }
 114 };
 115
 116 inline path operator/ (const path& lhs, const path& rhs)
 117 { return path(lhs) /= rhs; }
 118
 119 /// @return true if path at p exists
 120 bool exists(const path & p);
 121
 122 /// @return true if path at p is a directory.
 123 bool is_directory(const path & p);
 124
 125 /**
 126  * Attempt to create a directory at p as if by the glib function g_mkdir
 127  * with a second argument of S_IRWXU|S_IRWXG|S_IRWXO
 128  *
 129  * @throw filesystem_error if mkdir fails for any other reason other than
 130  * the directory already exists.
 131  *
 132  * @return true If the directory p was created, otherwise false
 133  *
 134  * @post is_directory(p)
 135  */
 136 bool create_directory(const path & p);
 137
 138 /**
 139  * Attempt to create a directory at p as if by the glib function
 140  * g_mkdir_with_parents with a second argument of S_IRWXU|S_IRWXG|S_IRWXO
 141  *
 142  * @throw filesystem_error if g_mkdir_with_parents fails for any other
 143  * reason other than the directory already exists.
 144  *
 145  * @return true If the directory at p was created, otherwise false
 146  *
 147  * @post is_directory(p)
 148  */
 149 bool create_directories(const path & p);
 150
 151 /**
 152  * Attempt to delete the file at path p as if by the glib function
 153  * g_unlink.
 154  *
 155  * @return true if file existed prior to removing it, false if file
 156  * at p did not exist.
 157  *
 158  * @throw filesystem_error if removing the file failed for any other
 159  * reason other than the file did not exist.
 160  */
 161 bool remove(const path & p);
 162
 163 /**
 164  * Renames from_path to to_path as if by the glib function g_rename.
 165  */
 166 void rename (const path& from_path, const path& to_path);
 167
 168 /**
 169  * Attempt to copy the contents of the file from_path to a new file
 170  * at path to_path.
 171  *
 172  * @throw filesystem_error if from_path.empty() || to_path.empty() ||
 173  * !exists(from_path) || !is_regular(from_path) || exists(to_path)
 174  */
 175 void copy_file(const path & from_path, const path & to_path);
 176
 177 /**
 178  * @return The substring of the filename component of the path, starting
 179  * at the beginning of the filename up to but not including the last dot.
 180  *
 181  * boost::filesystem::path::basename differs from g_path_get_basename and
 182  * ::basename and most other forms of basename in that it removes the
 183  * extension from the filename if the filename has one.
 184  */
 185 std::string basename (const path& p);
 186
 187 /**
 188  * @return If the filename contains a dot, return a substring of the
 189  * filename starting the rightmost dot to the end of the string, otherwise
 190  * an empty string.
 191  *
 192  * @param p a file path.
 193  */
 194 std::string extension (const path& p);
 195
 196 } // namespace sys
 197
 198 } // namespace PBD
 199
 200 #endif