2 Copyright (C) 2007 Tim Mayberry
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.
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.
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.
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.
26 * More information about boost::filesystem and the TR2 proposal at
28 * http://www.boost.org/libs/filesystem/doc/tr2_proposal.html
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.
34 * My reasons for writing this thin wrapper instead of using glib directly or
35 * using boost::filesystem immediately are:
37 * - Using sys::path instead of strings and Glib::build_filename is more
38 * convenient, terse and forces correct platform agnostic path building.
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.
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).
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.
53 * - Using boost::filesystem directly means another library dependence and would
54 * require more testing on windows because of the character encoding issue.
56 * - The boost::filesystem API changes a bit as part of the TR2 review process etc.
59 #ifndef __filesystem_h__
60 #define __filesystem_h__
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) { }
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; }
81 path& operator/=(const path& rhs);
82 path& operator/=(const std::string& s);
83 path& operator/=(const char* s);
85 const std::string to_string() const { return m_path; }
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.
91 std::string leaf () const;
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).
98 path branch_path () const;
105 class filesystem_error : public std::runtime_error
107 const int m_error_code;
110 explicit filesystem_error(const std::string & what, int error_code=0)
111 : std::runtime_error(what), m_error_code(error_code) { }
113 int system_error() const { return m_error_code; }
116 inline path operator/ (const path& lhs, const path& rhs)
117 { return path(lhs) /= rhs; }
119 /// @return true if path at p exists
120 bool exists(const path & p);
122 /// @return true if path at p is a directory.
123 bool is_directory(const path & p);
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
129 * @throw filesystem_error if mkdir fails for any other reason other than
130 * the directory already exists.
132 * @return true If the directory p was created, otherwise false
134 * @post is_directory(p)
136 bool create_directory(const path & p);
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
142 * @throw filesystem_error if g_mkdir_with_parents fails for any other
143 * reason other than the directory already exists.
145 * @return true If the directory at p was created, otherwise false
147 * @post is_directory(p)
149 bool create_directories(const path & p);
152 * Attempt to delete the file at path p as if by the glib function
155 * @return true if file existed prior to removing it, false if file
156 * at p did not exist.
158 * @throw filesystem_error if removing the file failed for any other
159 * reason other than the file did not exist.
161 bool remove(const path & p);
164 * Renames from_path to to_path as if by the glib function g_rename.
166 void rename (const path& from_path, const path& to_path);
169 * Attempt to copy the contents of the file from_path to a new file
172 * @throw filesystem_error if from_path.empty() || to_path.empty() ||
173 * !exists(from_path) || !is_regular(from_path) || exists(to_path)
175 void copy_file(const path & from_path, const path & to_path);
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.
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.
185 std::string basename (const path& p);
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
192 * @param p a file path.
194 std::string extension (const path& p);