The Battle for Wesnoth  1.15.10+dev
filesystem.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2018 by David White <dave@whitevine.net>
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 /**
16  * @file
17  * Declarations for File-IO.
18  */
19 
20 #pragma once
21 
22 #include <ctime>
23 #include <iosfwd>
24 #include <memory>
25 #include <string>
26 #include <vector>
27 
28 #include "exceptions.hpp"
29 
30 class config;
31 class game_config_view;
32 struct SDL_RWops;
33 
34 namespace filesystem {
35 
36 using scoped_istream = std::unique_ptr<std::istream>;
37 using scoped_ostream = std::unique_ptr<std::ostream>;
38 
39 typedef std::unique_ptr<SDL_RWops, void(*)(SDL_RWops*)> rwops_ptr;
40 
41 rwops_ptr make_read_RWops(const std::string &path);
42 rwops_ptr make_write_RWops(const std::string &path);
43 
44 /** An exception object used when an IO error occurs */
45 struct io_exception : public game::error {
46  io_exception() : game::error("") {}
47  io_exception(const std::string& msg) : game::error(msg) {}
48 };
49 
50 struct file_tree_checksum;
51 
55 
56 // A list of file and directory blacklist patterns
58 {
59 public:
61  : file_patterns_(), directory_patterns_()
62  {}
63  blacklist_pattern_list(const std::vector<std::string>& file_patterns, const std::vector<std::string>& directory_patterns)
64  : file_patterns_(file_patterns), directory_patterns_(directory_patterns)
65  {}
66 
67  bool match_file(const std::string& name) const;
68 
69  bool match_dir(const std::string& name) const;
70 
71  void add_file_pattern(const std::string& pattern)
72  {
73  file_patterns_.push_back(pattern);
74  }
75 
76  void add_directory_pattern(const std::string& pattern)
77  {
78  directory_patterns_.push_back(pattern);
79  }
80 
81  void remove_blacklisted_files_and_dirs(std::vector<std::string>& files, std::vector<std::string>& directories) const;
82 
83 private:
84  std::vector<std::string> file_patterns_;
85  std::vector<std::string> directory_patterns_;
86 };
87 
89  {
90  /* Blacklist dot-files/dirs, which are hidden files in UNIX platforms */
91  ".+",
92  "#*#",
93  "*~",
94  "*-bak",
95  "*.swp",
96  "*.pbl",
97  "*.ign",
98  "_info.cfg",
99  "*.exe",
100  "*.bat",
101  "*.cmd",
102  "*.com",
103  "*.scr",
104  "*.sh",
105  "*.js",
106  "*.vbs",
107  "*.o",
108  "*.ini",
109  /* Remove junk created by certain file manager ;) */
110  "Thumbs.db",
111  /* Eclipse plugin */
112  "*.wesnoth",
113  "*.project",
114  },
115  {
116  ".+",
117  /* macOS metadata-like cruft (http://floatingsun.net/2007/02/07/whats-with-__macosx-in-zip-files/) */
118  "__MACOSX",
119  }
120 };
121 
122 /**
123  * Populates 'files' with all the files and
124  * 'dirs' with all the directories in dir.
125  * If files or dirs are nullptr they will not be used.
126  *
127  * mode: determines whether the entire path or just the filename is retrieved.
128  * filter: determines if we skip images and sounds directories
129  * reorder: triggers the special handling of _main.cfg and _final.cfg
130  * checksum: can be used to store checksum info
131  */
132 void get_files_in_dir(const std::string &dir,
133  std::vector<std::string>* files,
134  std::vector<std::string>* dirs=nullptr,
138  file_tree_checksum* checksum = nullptr);
139 
140 std::string get_dir(const std::string &dir);
141 
142 // The location of various important files:
143 std::string get_prefs_file();
144 std::string get_credentials_file();
145 std::string get_default_prefs_file();
146 std::string get_save_index_file();
147 std::string get_saves_dir();
148 std::string get_intl_dir();
149 std::string get_screenshot_dir();
150 std::string get_addons_dir();
151 
152 /**
153  * Get the next free filename using "name + number (3 digits) + extension"
154  * maximum 1000 files then start always giving 999
155  */
156 std::string get_next_filename(const std::string& name, const std::string& extension);
157 void set_user_config_dir(const std::string& path);
158 void set_user_data_dir(std::string path);
159 
160 std::string get_user_config_dir();
161 std::string get_user_data_dir();
162 std::string get_cache_dir();
163 
165 {
166  /**
167  * Here the version is given as a string instead of a version_info, because the
168  * logic of how many components are significant ("1.16" rather than
169  * "1.16.0") is encapsulated in find_other_version_saves_dirs().
170  */
171  std::string version;
172  std::string path;
173 
174  // constructor because emplace_back() doesn't use aggregate initialization
175  other_version_dir(const std::string& v, const std::string& p)
176  : version(v)
177  , path(p)
178  {
179  }
180 };
181 
182 /**
183  * Searches for directories containing saves created by other versions of Wesnoth.
184  *
185  * The directories returned will exist, but might not contain any saves. Changes to
186  * the filesystem (by running other versions or by deleting old directories) may
187  * change the results returned by the function.
188  */
189 std::vector<other_version_dir> find_other_version_saves_dirs();
190 
191 std::string get_cwd();
192 bool set_cwd(const std::string& dir);
193 
194 std::string get_exe_dir();
195 
196 bool make_directory(const std::string& dirname);
197 bool delete_directory(const std::string& dirname, const bool keep_pbl = false);
198 bool delete_file(const std::string& filename);
199 
200 bool looks_like_pbl(const std::string& file);
201 
202 // Basic disk I/O:
203 
204 /** Basic disk I/O - read file. */
205 std::string read_file(const std::string& fname);
206 filesystem::scoped_istream istream_file(const std::string& fname, bool treat_failure_as_error = true);
207 filesystem::scoped_ostream ostream_file(const std::string& fname, bool create_directory = true);
208 /** Throws io_exception if an error occurs. */
209 void write_file(const std::string& fname, const std::string& data);
210 
211 std::string read_map(const std::string& name);
212 
213 /**
214  * Creates a directory if it does not exist already.
215  *
216  * @param dirname Path to directory. All parents should exist.
217  * @returns True if the directory exists or could be
218  * successfully created; false otherwise.
219  */
220 bool create_directory_if_missing(const std::string& dirname);
221 /**
222  * Creates a recursive directory tree if it does not exist already
223  * @param dirname Full path of target directory. Non existing parents
224  * will be created
225  * @return True if the directory exists or could be
226  * successfully created; false otherwise.
227  */
228 bool create_directory_if_missing_recursive(const std::string& dirname);
229 
230 /** Returns true if the given file is a directory. */
231 bool is_directory(const std::string& fname);
232 
233 /** Returns true if a file or directory with such name already exists. */
234 bool file_exists(const std::string& name);
235 
236 /** Get the modification time of a file. */
237 std::time_t file_modified_time(const std::string& fname);
238 
239 /** Returns true if the file ends with '.gz'. */
240 bool is_gzip_file(const std::string& filename);
241 
242 /** Returns true if the file ends with '.bz2'. */
243 bool is_bzip2_file(const std::string& filename);
244 
245 inline bool is_compressed_file(const std::string& filename) {
246  return is_gzip_file(filename) || is_bzip2_file(filename);
247 }
248 
250 {
252  explicit file_tree_checksum(const config& cfg);
253  void write(config& cfg) const;
254  void reset() {nfiles = 0;modified = 0;sum_size=0;}
255  // @todo make variables private!
256  std::size_t nfiles, sum_size;
257  std::time_t modified;
258  bool operator==(const file_tree_checksum &rhs) const;
259  bool operator!=(const file_tree_checksum &rhs) const
260  { return !operator==(rhs); }
261 };
262 
263 /** Get the time at which the data/ tree was last modified at. */
264 const file_tree_checksum& data_tree_checksum(bool reset = false);
265 
266 /** Returns the size of a file, or -1 if the file doesn't exist. */
267 int file_size(const std::string& fname);
268 
269 /** Returns the sum of the sizes of the files contained in a directory. */
270 int dir_size(const std::string& path);
271 
272 bool ends_with(const std::string& str, const std::string& suffix);
273 
274 /**
275  * Returns the base filename of a file, with directory name stripped.
276  * Equivalent to a portable basename() function.
277  *
278  * If @a remove_extension is true, the filename extension will be stripped
279  * from the returned value.
280  */
281 std::string base_name(const std::string& file, const bool remove_extension = false);
282 
283 /**
284  * Returns the directory name of a file, with filename stripped.
285  * Equivalent to a portable dirname()
286  */
287 std::string directory_name(const std::string& file);
288 
289 /**
290  * Finds the nearest parent in existence for a file or directory.
291  *
292  * @note The file's own existence is not checked.
293  *
294  * @returns An absolute path to the closest parent of the given path, or an
295  * empty string if none could be found. While on POSIX platforms this
296  * cannot happen (unless the original path was already empty), on
297  * Windows it might be the case that the original path refers to a
298  * drive letter or network share that does not exist.
299  */
300 std::string nearest_extant_parent(const std::string& file);
301 
302 /**
303  * Returns the absolute path of a file.
304  *
305  * @param path Original path.
306  * @param normalize_separators Whether to substitute path separators with the
307  * platform's preferred format.
308  * @param resolve_dot_entries Whether to resolve . and .. directory entries.
309  * This requires @a path to refer to a valid
310  * existing object.
311  *
312  * @returns An absolute path -- that is, a path that is independent of the
313  * current working directory for the process. If resolve_dot_entries
314  * is set to true, the returned path has . and .. components resolved;
315  * however, if resolution fails because a component does not exist, an
316  * empty string is returned instead.
317  */
318 std::string normalize_path(const std::string& path,
319  bool normalize_separators = false,
320  bool resolve_dot_entries = false);
321 
322 /**
323  * Sanitizes a path to remove references to the user's name.
324  */
325 std::string sanitize_path(const std::string& path);
326 
327 /**
328  * Returns whether the path is the root of the file hierarchy.
329  *
330  * @note This function is unreliable for paths that do not exist -- it will
331  * always return @a false for those.
332  */
333 bool is_root(const std::string& path);
334 
335 /**
336  * Returns the name of the root device if included in the given path.
337  *
338  * This only properly makes sense on Windows with paths containing a drive
339  * letter or UNC at the start -- otherwise, it will return the empty string. To
340  * ensure that a suitable root name can be found you might want to use
341  * normalize_path() first with @a resolve_dot_entries set to true.
342  */
343 std::string root_name(const std::string& path);
344 
345 /**
346  * Returns whether the path seems to be relative.
347  */
348 bool is_relative(const std::string& path);
349 
350 /**
351  * Returns whether @a c is a path separator.
352  *
353  * @note / is always a path separator. Additionally, on Windows \\ is a
354  * path separator as well.
355  */
356 bool is_path_sep(char c);
357 
358 /**
359  * Returns the standard path separator for the current platform.
360  */
361 char path_separator();
362 
363 /**
364  * The paths manager is responsible for recording the various paths
365  * that binary files may be located at.
366  * It should be passed a config object which holds binary path information.
367  * This is in the format
368  *@verbatim
369  * [binary_path]
370  * path=<path>
371  * [/binary_path]
372  * Binaries will be searched for in [wesnoth-path]/data/<path>/images/
373  *@endverbatim
374  */
376 {
380 
381  void set_paths(const game_config_view& cfg);
382 
383 private:
385  binary_paths_manager& operator=(const binary_paths_manager& o);
386 
387  void cleanup();
388 
389  std::vector<std::string> paths_;
390 };
391 
393 
394 /**
395  * Returns a vector with all possible paths to a given type of binary,
396  * e.g. 'images', 'sounds', etc,
397  */
398 const std::vector<std::string>& get_binary_paths(const std::string& type);
399 
400 /**
401  * Returns a complete path to the actual file of a given @a type
402  * or an empty string if the file isn't present.
403  */
404 std::string get_binary_file_location(const std::string& type, const std::string& filename);
405 
406 /**
407  * Returns a complete path to the actual directory of a given @a type
408  * or an empty string if the directory isn't present.
409  */
410 std::string get_binary_dir_location(const std::string &type, const std::string &filename);
411 
412 /**
413  * Returns a complete path to the actual WML file or directory
414  * or an empty string if the file isn't present.
415  */
416 std::string get_wml_location(const std::string &filename,
417  const std::string &current_dir = std::string());
418 
419 /**
420  * Returns a short path to @a filename, skipping the (user) data directory.
421  */
422 std::string get_short_wml_path(const std::string &filename);
423 
424 /**
425  * Returns an image path to @a filename for binary path-independent use in saved games.
426  *
427  * Example:
428  * units/konrad-fighter.png ->
429  * data/campaigns/Heir_To_The_Throne/images/units/konrad-fighter.png
430  */
431 std::string get_independent_image_path(const std::string &filename);
432 
433 /**
434  * Returns the appropriate invocation for a Wesnoth-related binary, assuming
435  * that it is located in the same directory as the running wesnoth binary.
436  * This is just a string-transformation based on argv[0], so the returned
437  * program is not guaranteed to actually exist. '-debug' variants are handled
438  * correctly.
439  */
440 std::string get_program_invocation(const std::string &program_name);
441 
442 /**
443  * Returns the localized version of the given filename, if it exists.
444  */
445 std::string get_localized_path(const std::string& file, const std::string& suff = "");
446 
447 }
std::string get_binary_dir_location(const std::string &type, const std::string &filename)
Returns a complete path to the actual directory of a given type or an empty string if the directory i...
bool delete_directory(const std::string &dirname, const bool keep_pbl)
Definition: filesystem.cpp:945
std::string get_program_invocation(const std::string &program_name)
Returns the appropriate invocation for a Wesnoth-related binary, assuming that it is located in the s...
std::string get_next_filename(const std::string &name, const std::string &extension)
Get the next free filename using "name + number (3 digits) + extension" maximum 1000 files then start...
Definition: filesystem.cpp:490
bool delete_file(const std::string &filename)
Definition: filesystem.cpp:984
static bool create_directory_if_missing(const bfs::path &dirpath)
Definition: filesystem.cpp:297
bool looks_like_pbl(const std::string &file)
void add_directory_pattern(const std::string &pattern)
Definition: filesystem.hpp:76
void set_user_data_dir(std::string newprefdir)
Definition: filesystem.cpp:608
static bool file_exists(const bfs::path &fpath)
Definition: filesystem.cpp:263
bool ends_with(const std::string &str, const std::string &suffix)
rwops_ptr make_read_RWops(const std::string &path)
filesystem::scoped_istream istream_file(const std::string &fname, bool treat_failure_as_error)
The paths manager is responsible for recording the various paths that binary files may be located at...
Definition: filesystem.hpp:375
std::string version
Here the version is given as a string instead of a version_info, because the logic of how many compon...
Definition: filesystem.hpp:171
other_version_dir(const std::string &v, const std::string &p)
Definition: filesystem.hpp:175
std::string get_screenshot_dir()
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:109
std::string get_binary_file_location(const std::string &type, const std::string &filename)
Returns a complete path to the actual file of a given type or an empty string if the file isn&#39;t prese...
std::string normalize_path(const std::string &fpath, bool normalize_separators, bool resolve_dot_entries)
Returns the absolute path of a file.
std::string get_saves_dir()
static bfs::path get_dir(const bfs::path &dirpath)
Definition: filesystem.cpp:274
io_exception(const std::string &msg)
Definition: filesystem.hpp:47
void clear_binary_paths_cache()
std::string get_cwd()
Definition: filesystem.cpp:876
void write(std::ostream &out, const configr_of &cfg, unsigned int level)
Definition: parser.cpp:763
rwops_ptr make_write_RWops(const std::string &path)
std::string get_user_data_dir()
Definition: filesystem.cpp:789
std::vector< std::string > directory_patterns_
Definition: filesystem.hpp:85
std::string get_intl_dir()
void write_file(const std::string &fname, const std::string &data)
Throws io_exception if an error occurs.
void get_files_in_dir(const std::string &dir, std::vector< std::string > *files, std::vector< std::string > *dirs, name_mode mode, filter_mode filter, reorder_mode reorder, file_tree_checksum *checksum)
Populates &#39;files&#39; with all the files and &#39;dirs&#39; with all the directories in dir.
Definition: filesystem.cpp:349
std::string root_name(const std::string &path)
Returns the name of the root device if included in the given path.
std::string nearest_extant_parent(const std::string &file)
Finds the nearest parent in existence for a file or directory.
bool is_directory(const std::string &fname)
Returns true if the given file is a directory.
std::unique_ptr< std::istream > scoped_istream
Definition: filesystem.hpp:36
std::string path
Definition: game_config.cpp:38
std::string get_short_wml_path(const std::string &filename)
Returns a short path to filename, skipping the (user) data directory.
std::string get_independent_image_path(const std::string &filename)
Returns an image path to filename for binary path-independent use in saved games. ...
std::vector< std::string > file_patterns_
Definition: filesystem.hpp:84
std::string sanitize_path(const std::string &path)
Sanitizes a path to remove references to the user&#39;s name.
std::string get_default_prefs_file()
std::string read_file(const std::string &fname)
Basic disk I/O - read file.
Definition: filesystem.cpp:995
void add_file_pattern(const std::string &pattern)
Definition: filesystem.hpp:71
std::string read_map(const std::string &name)
bool is_path_sep(char c)
Returns whether c is a path separator.
std::unique_ptr< std::ostream > scoped_ostream
Definition: filesystem.hpp:37
bool is_gzip_file(const std::string &filename)
Returns true if the file ends with &#39;.gz&#39;.
std::string get_cache_dir()
Definition: filesystem.cpp:794
const std::vector< std::string > & get_binary_paths(const std::string &type)
Returns a vector with all possible paths to a given type of binary, e.g.
std::string get_exe_dir()
Definition: filesystem.cpp:904
bool is_relative(const std::string &path)
Returns whether the path seems to be relative.
void set_user_config_dir(const std::string &newconfigdir)
Definition: filesystem.cpp:746
int dir_size(const std::string &pname)
Returns the sum of the sizes of the files contained in a directory.
std::string get_wml_location(const std::string &filename, const std::string &current_dir)
Returns a complete path to the actual WML file or directory or an empty string if the file isn&#39;t pres...
std::vector< std::string > paths_
Definition: filesystem.hpp:389
mock_party p
An exception object used when an IO error occurs.
Definition: filesystem.hpp:45
bool operator==(const config &a, const config &b)
Definition: config.cpp:1450
bool make_directory(const std::string &dirname)
Definition: filesystem.cpp:934
std::string name
Definition: sdl_ttf.cpp:70
bool is_compressed_file(const std::string &filename)
Definition: filesystem.hpp:245
bool is_root(const std::string &path)
Returns whether the path is the root of the file hierarchy.
std::unique_ptr< SDL_RWops, void(*)(SDL_RWops *)> rwops_ptr
Definition: filesystem.hpp:39
std::string get_localized_path(const std::string &file, const std::string &suff)
Returns the localized version of the given filename, if it exists.
const file_tree_checksum & data_tree_checksum(bool reset=false)
Get the time at which the data/ tree was last modified at.
char path_separator()
Returns the standard path separator for the current platform.
std::string base_name(const std::string &file, const bool remove_extension)
Returns the base filename of a file, with directory name stripped.
int file_size(const std::string &fname)
Returns the size of a file, or -1 if the file doesn&#39;t exist.
bool set_cwd(const std::string &dir)
Definition: filesystem.cpp:889
std::string get_user_config_dir()
Definition: filesystem.cpp:760
bool is_bzip2_file(const std::string &filename)
Returns true if the file ends with &#39;.bz2&#39;.
std::time_t file_modified_time(const std::string &fname)
Get the modification time of a file.
Base class for all the errors encountered by the engine.
Definition: exceptions.hpp:27
std::string get_addons_dir()
std::string get_credentials_file()
bool operator!=(const file_tree_checksum &rhs) const
Definition: filesystem.hpp:259
blacklist_pattern_list(const std::vector< std::string > &file_patterns, const std::vector< std::string > &directory_patterns)
Definition: filesystem.hpp:63
std::vector< other_version_dir > find_other_version_saves_dirs()
Searches for directories containing saves created by other versions of Wesnoth.
Definition: filesystem.cpp:823
std::string get_prefs_file()
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:59
mock_char c
std::string get_save_index_file()
std::string directory_name(const std::string &file)
Returns the directory name of a file, with filename stripped.
static bool create_directory_if_missing_recursive(const bfs::path &dirpath)
Definition: filesystem.cpp:321
static const blacklist_pattern_list default_blacklist
Definition: filesystem.hpp:88
filesystem::scoped_ostream ostream_file(const std::string &fname, bool create_directory)