The Battle for Wesnoth  1.15.2+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 <string>
27 #include <vector>
28 #include <memory>
29 
30 #include "exceptions.hpp"
32 
33 class config;
34 
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:
154 std::string get_prefs_file();
155 std::string get_credentials_file();
156 std::string get_default_prefs_file();
157 std::string get_save_index_file();
158 std::string get_saves_dir();
159 std::string get_intl_dir();
160 std::string get_screenshot_dir();
161 std::string get_addons_dir();
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);
168 void set_user_config_dir(const std::string& path);
169 void set_user_data_dir(std::string path);
170 
171 std::string get_user_config_dir();
172 std::string get_user_data_dir();
173 std::string get_cache_dir();
174 
175 std::string get_cwd();
176 std::string get_exe_dir();
177 
178 bool make_directory(const std::string& dirname);
179 bool delete_directory(const std::string& dirname, const bool keep_pbl = false);
180 bool delete_file(const std::string &filename);
181 
182 bool looks_like_pbl(const std::string& file);
183 
184 // Basic disk I/O:
185 
186 /** Basic disk I/O - read file. */
187 std::string read_file(const std::string &fname);
188 filesystem::scoped_istream istream_file(const std::string& fname, bool treat_failure_as_error = true);
189 filesystem::scoped_ostream ostream_file(const std::string& fname, bool create_directory = true);
190 /** Throws io_exception if an error occurs. */
191 void write_file(const std::string& fname, const std::string& data);
192 
193 std::string read_map(const std::string& name);
194 
195 /**
196  * Creates a directory if it does not exist already.
197  *
198  * @param dirname Path to directory. All parents should exist.
199  * @returns True if the directory exists or could be
200  * successfully created; false otherwise.
201  */
202 bool create_directory_if_missing(const std::string& dirname);
203 /**
204  * Creates a recursive directory tree if it does not exist already
205  * @param dirname Full path of target directory. Non existing parents
206  * will be created
207  * @return True if the directory exists or could be
208  * successfully created; false otherwise.
209  */
210 bool create_directory_if_missing_recursive(const std::string& dirname);
211 
212 /** Returns true if the given file is a directory. */
213 bool is_directory(const std::string& fname);
214 
215 /** Returns true if a file or directory with such name already exists. */
216 bool file_exists(const std::string& name);
217 
218 /** Get the modification time of a file. */
219 std::time_t file_modified_time(const std::string& fname);
220 
221 /** Returns true if the file ends with '.gz'. */
222 bool is_gzip_file(const std::string& filename);
223 
224 /** Returns true if the file ends with '.bz2'. */
225 bool is_bzip2_file(const std::string& filename);
226 
227 inline bool is_compressed_file(const std::string& filename) {
228  return is_gzip_file(filename) || is_bzip2_file(filename);
229 }
230 
232 {
234  explicit file_tree_checksum(const config& cfg);
235  void write(config& cfg) const;
236  void reset() {nfiles = 0;modified = 0;sum_size=0;}
237  // @todo make variables private!
238  std::size_t nfiles, sum_size;
239  std::time_t modified;
240  bool operator==(const file_tree_checksum &rhs) const;
241  bool operator!=(const file_tree_checksum &rhs) const
242  { return !operator==(rhs); }
243 };
244 
245 /** Get the time at which the data/ tree was last modified at. */
246 const file_tree_checksum& data_tree_checksum(bool reset = false);
247 
248 /** Returns the size of a file, or -1 if the file doesn't exist. */
249 int file_size(const std::string& fname);
250 
251 /** Returns the sum of the sizes of the files contained in a directory. */
252 int dir_size(const std::string& path);
253 
254 bool ends_with(const std::string& str, const std::string& suffix);
255 
256 /**
257  * Returns the base filename of a file, with directory name stripped.
258  * Equivalent to a portable basename() function.
259  *
260  * If @a remove_extension is true, the filename extension will be stripped
261  * from the returned value.
262  */
263 std::string base_name(const std::string& file, const bool remove_extension = false);
264 
265 /**
266  * Returns the directory name of a file, with filename stripped.
267  * Equivalent to a portable dirname()
268  */
269 std::string directory_name(const std::string& file);
270 
271 /**
272  * Finds the nearest parent in existence for a file or directory.
273  *
274  * @note The file's own existence is not checked.
275  *
276  * @returns An absolute path to the closest parent of the given path, or an
277  * empty string if none could be found. While on POSIX platforms this
278  * cannot happen (unless the original path was already empty), on
279  * Windows it might be the case that the original path refers to a
280  * drive letter or network share that does not exist.
281  */
282 std::string nearest_extant_parent(const std::string& file);
283 
284 /**
285  * Returns the absolute path of a file.
286  *
287  * @param path Original path.
288  * @param normalize_separators Whether to substitute path separators with the
289  * platform's preferred format.
290  * @param resolve_dot_entries Whether to resolve . and .. directory entries.
291  * This requires @a path to refer to a valid
292  * existing object.
293  *
294  * @returns An absolute path -- that is, a path that is independent of the
295  * current working directory for the process. If resolve_dot_entries
296  * is set to true, the returned path has . and .. components resolved;
297  * however, if resolution fails because a component does not exist, an
298  * empty string is returned instead.
299  */
300 std::string normalize_path(const std::string& path,
301  bool normalize_separators = false,
302  bool resolve_dot_entries = false);
303 
304 /**
305  * Sanitizes a path to remove references to the user's name.
306  */
307 std::string sanitize_path(const std::string& path);
308 
309 /**
310  * Returns whether the path is the root of the file hierarchy.
311  *
312  * @note This function is unreliable for paths that do not exist -- it will
313  * always return @a false for those.
314  */
315 bool is_root(const std::string& path);
316 
317 /**
318  * Returns the name of the root device if included in the given path.
319  *
320  * This only properly makes sense on Windows with paths containing a drive
321  * letter or UNC at the start -- otherwise, it will return the empty string. To
322  * ensure that a suitable root name can be found you might want to use
323  * normalize_path() first with @a resolve_dot_entries set to true.
324  */
325 std::string root_name(const std::string& path);
326 
327 /**
328  * Returns whether the path seems to be relative.
329  */
330 bool is_relative(const std::string& path);
331 
332 /**
333  * Returns whether @a c is a path separator.
334  *
335  * @note / is always a path separator. Additionally, on Windows \\ is a
336  * path separator as well.
337  */
338 bool is_path_sep(char c);
339 
340 /**
341  * Returns the standard path separator for the current platform.
342  */
343 char path_separator();
344 
345 /**
346  * The paths manager is responsible for recording the various paths
347  * that binary files may be located at.
348  * It should be passed a config object which holds binary path information.
349  * This is in the format
350  *@verbatim
351  * [binary_path]
352  * path=<path>
353  * [/binary_path]
354  * Binaries will be searched for in [wesnoth-path]/data/<path>/images/
355  *@endverbatim
356  */
358 {
360  binary_paths_manager(const config& cfg);
362 
363  void set_paths(const config& cfg);
364 
365 private:
367  binary_paths_manager& operator=(const binary_paths_manager& o);
368 
369  void cleanup();
370 
371  std::vector<std::string> paths_;
372 };
373 
375 
376 /**
377  * Returns a vector with all possible paths to a given type of binary,
378  * e.g. 'images', 'sounds', etc,
379  */
380 const std::vector<std::string>& get_binary_paths(const std::string& type);
381 
382 /**
383  * Returns a complete path to the actual file of a given @a type
384  * or an empty string if the file isn't present.
385  */
386 std::string get_binary_file_location(const std::string& type, const std::string& filename);
387 
388 /**
389  * Returns a complete path to the actual directory of a given @a type
390  * or an empty string if the directory isn't present.
391  */
392 std::string get_binary_dir_location(const std::string &type, const std::string &filename);
393 
394 /**
395  * Returns a complete path to the actual WML file or directory
396  * or an empty string if the file isn't present.
397  */
398 std::string get_wml_location(const std::string &filename,
399  const std::string &current_dir = std::string());
400 
401 /**
402  * Returns a short path to @a filename, skipping the (user) data directory.
403  */
404 std::string get_short_wml_path(const std::string &filename);
405 
406 /**
407  * Returns an image path to @a filename for binary path-independent use in saved games.
408  *
409  * Example:
410  * units/konrad-fighter.png ->
411  * data/campaigns/Heir_To_The_Throne/images/units/konrad-fighter.png
412  */
413 std::string get_independent_image_path(const std::string &filename);
414 
415 /**
416  * Returns the appropriate invocation for a Wesnoth-related binary, assuming
417  * that it is located in the same directory as the running wesnoth binary.
418  * This is just a string-transformation based on argv[0], so the returned
419  * program is not guaranteed to actually exist. '-debug' variants are handled
420  * correctly.
421  */
422 std::string get_program_invocation(const std::string &program_name);
423 
424 /**
425  * Returns the localized version of the given filename, if it exists.
426  */
427 std::string get_localized_path(const std::string& file, const std::string& suff = "");
428 
429 }
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:867
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:493
bool delete_file(const std::string &filename)
Definition: filesystem.cpp:906
static bool create_directory_if_missing(const bfs::path &dirpath)
Definition: filesystem.cpp:300
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:606
static bool file_exists(const bfs::path &fpath)
Definition: filesystem.cpp:266
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)
Definition: filesystem.cpp:925
The paths manager is responsible for recording the various paths that binary files may be located at...
Definition: filesystem.hpp:357
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 get_saves_dir()
static bfs::path get_dir(const bfs::path &dirpath)
Definition: filesystem.cpp:277
io_exception(const std::string &msg)
Definition: filesystem.hpp:50
void clear_binary_paths_cache()
std::string get_cwd()
Definition: filesystem.cpp:814
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:780
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.
Definition: filesystem.cpp:986
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.
Definition: filesystem.cpp:917
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:785
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:826
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:352
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:737
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:371
An exception object used when an IO error occurs.
Definition: filesystem.hpp:48
bool operator==(const config &a, const config &b)
Definition: config.cpp:1405
bool make_directory(const std::string &dirname)
Definition: filesystem.cpp:856
bool is_compressed_file(const std::string &filename)
Definition: filesystem.hpp:227
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.
std::string get_user_config_dir()
Definition: filesystem.cpp:751
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:241
blacklist_pattern_list(const std::vector< std::string > &file_patterns, const std::vector< std::string > &directory_patterns)
Definition: filesystem.hpp:66
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:324
static const blacklist_pattern_list default_blacklist
Definition: filesystem.hpp:99
filesystem::scoped_ostream ostream_file(const std::string &fname, bool create_directory)
Definition: filesystem.cpp:963