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