Panda3D
Loading...
Searching...
No Matches
filename.h
Go to the documentation of this file.
1/**
2 * PANDA 3D SOFTWARE
3 * Copyright (c) Carnegie Mellon University. All rights reserved.
4 *
5 * All use of this software is subject to the terms of the revised BSD
6 * license. You should have received a copy of this license along
7 * with this source code in a file named "LICENSE."
8 *
9 * @file filename.h
10 * @author drose
11 * @date 1999-01-18
12 */
13
14#ifndef FILENAME_H
15#define FILENAME_H
16
17#include "dtoolbase.h"
18#include "pandaFileStream.h"
19#include "typeHandle.h"
20#include "register_type.h"
21#include "vector_string.h"
22#include "textEncoder.h"
23
24#include <assert.h>
25
26class DSearchPath;
27
28/**
29 * The name of a file, such as a texture file or an Egg file. Stores the full
30 * pathname, and includes functions for extracting out the directory prefix
31 * part and the file extension and stuff.
32 *
33 * A Filename is also aware of the mapping between the Unix-like filename
34 * convention we use internally, and the local OS's specific filename
35 * convention, and it knows how to perform basic OS-specific I/O, like testing
36 * for file existence and searching a searchpath, as well as the best way to
37 * open an fstream for reading or writing.
38 *
39 * Note that the methods of Filename that interact with the filesystem (such
40 * as exists(), open_read(), etc.) directly interface with the operating system
41 * and are not aware of Panda's virtual file system. To interact with the VFS,
42 * use the methods on VirtualFileSystem instead.
43 */
44class EXPCL_DTOOL_DTOOLUTIL Filename {
45PUBLISHED:
46 enum Type {
47 // These type values must fit within the bits allocated for F_type, below.
48 T_general = 0x00,
49 T_dso = 0x01,
50 T_executable = 0x02,
51 // Perhaps other types will be added later.
52 };
53
54public:
55 enum Flags {
56 F_type = 0x0f,
57 F_binary = 0x10,
58 F_text = 0x20,
59 F_pattern = 0x40,
60 };
61
62 INLINE Filename(const char *filename);
63 INLINE Filename(const std::string &filename);
64 INLINE Filename(const std::wstring &filename);
65 INLINE Filename(const Filename &copy);
66 INLINE Filename(std::string &&filename) noexcept;
67 INLINE Filename(Filename &&from) noexcept;
68
69PUBLISHED:
70 INLINE Filename();
71 Filename(const Filename &dirname, const Filename &basename);
72
73#ifdef HAVE_PYTHON
74 EXTENSION(Filename(PyObject *path));
75
76 EXTENSION(PyObject *__reduce__(PyObject *self) const);
77#endif
78
79 // Static constructors to explicitly create a filename that refers to a text
80 // or binary file. This is in lieu of calling set_text() or set_binary() or
81 // set_type().
82 INLINE static Filename text_filename(const Filename &filename);
83 INLINE static Filename text_filename(const std::string &filename);
84 INLINE static Filename binary_filename(const Filename &filename);
85 INLINE static Filename binary_filename(const std::string &filename);
86 INLINE static Filename dso_filename(const std::string &filename);
87 INLINE static Filename executable_filename(const std::string &filename);
88
89 INLINE static Filename pattern_filename(const std::string &filename);
90
91 static Filename from_os_specific(const std::string &os_specific,
92 Type type = T_general);
93 static Filename from_os_specific_w(const std::wstring &os_specific,
94 Type type = T_general);
95 static Filename expand_from(const std::string &user_string,
96 Type type = T_general);
97 static Filename temporary(const std::string &dirname, const std::string &prefix,
98 const std::string &suffix = std::string(),
99 Type type = T_general);
100
101 static const Filename &get_home_directory();
102 static const Filename &get_temp_directory();
103 static const Filename &get_user_appdata_directory();
104 static const Filename &get_common_appdata_directory();
105
106 // Assignment is via the = operator.
107 INLINE Filename &operator = (const std::string &filename);
108 INLINE Filename &operator = (const std::wstring &filename);
109 INLINE Filename &operator = (const char *filename);
110 INLINE Filename &operator = (const Filename &copy);
111 INLINE Filename &operator = (std::string &&filename) noexcept;
112 INLINE Filename &operator = (Filename &&from) noexcept;
113
114 // And retrieval is by any of the classic string operations.
115 INLINE operator const std::string & () const;
116 INLINE const char *c_str() const;
117 INLINE bool empty() const;
118 INLINE size_t length() const;
119 INLINE char operator [] (size_t n) const;
120
121 EXTENSION(PyObject *__repr__() const);
122 EXTENSION(PyObject *__fspath__() const);
123
124 INLINE std::string substr(size_t begin) const;
125 INLINE std::string substr(size_t begin, size_t end) const;
126 INLINE void operator += (const std::string &other);
127 INLINE Filename operator + (const std::string &other) const;
128
129 INLINE Filename operator / (const Filename &other) const;
130 EXTENSION(Filename __truediv__(const Filename &other) const);
131
132 // Or, you can use any of these.
133 INLINE std::string get_fullpath() const;
134 INLINE std::wstring get_fullpath_w() const;
135 INLINE std::string get_dirname() const;
136 INLINE std::string get_basename() const;
137 INLINE std::string get_fullpath_wo_extension() const;
138 INLINE std::string get_basename_wo_extension() const;
139 INLINE std::string get_extension() const;
140
141 // You can also use any of these to reassign pieces of the filename.
142 void set_fullpath(const std::string &s);
143 void set_dirname(const std::string &s);
144 void set_basename(const std::string &s);
145 void set_fullpath_wo_extension(const std::string &s);
146 void set_basename_wo_extension(const std::string &s);
147 void set_extension(const std::string &s);
148
149 // Setting these flags appropriately is helpful when opening or searching
150 // for a file; it helps the Filename resolve OS-specific conventions (for
151 // instance, that dynamic library names should perhaps be changed from .so
152 // to .dll).
153 INLINE void set_binary();
154 INLINE void set_text();
155 INLINE bool is_binary() const;
156 INLINE bool is_text() const;
157 INLINE bool is_binary_or_text() const;
158
159 INLINE void set_type(Type type);
160 INLINE Type get_type() const;
161
162 INLINE void set_pattern(bool pattern);
163 INLINE bool get_pattern() const;
164
165 INLINE bool has_hash() const;
166 Filename get_filename_index(int index) const;
167
168 INLINE std::string get_hash_to_end() const;
169 void set_hash_to_end(const std::string &s);
170
171 void extract_components(vector_string &components) const;
172 void standardize();
173
174 // The following functions deal with the outside world.
175
176 INLINE bool is_local() const;
177 INLINE bool is_fully_qualified() const;
178 void make_absolute();
179 void make_absolute(const Filename &start_directory);
180
181 bool make_canonical();
182 bool make_true_case();
183
184 std::string to_os_specific() const;
185 std::wstring to_os_specific_w() const;
186 std::string to_os_generic() const;
187 std::string to_os_short_name() const;
188 std::string to_os_long_name() const;
189
190 bool exists() const;
191 bool is_regular_file() const;
192 bool is_writable() const;
193 bool is_directory() const;
194 bool is_executable() const;
195 int compare_timestamps(const Filename &other,
196 bool this_missing_is_old = true,
197 bool other_missing_is_old = true) const;
198 time_t get_timestamp() const;
199 time_t get_access_timestamp() const;
200 std::streamsize get_file_size() const;
201
202 bool resolve_filename(const DSearchPath &searchpath,
203 const std::string &default_extension = std::string());
204 bool make_relative_to(Filename directory, bool allow_backups = true);
205 int find_on_searchpath(const DSearchPath &searchpath);
206
207 bool scan_directory(vector_string &contents) const;
208#ifdef HAVE_PYTHON
209 EXTENSION(PyObject *scan_directory() const);
210#endif
211
212 bool open_read(std::ifstream &stream) const;
213 bool open_write(std::ofstream &stream, bool truncate = true) const;
214 bool open_append(std::ofstream &stream) const;
215 bool open_read_write(std::fstream &stream, bool truncate = false) const;
216 bool open_read_append(std::fstream &stream) const;
217
218#ifdef USE_PANDAFILESTREAM
219 bool open_read(pifstream &stream) const;
220 bool open_write(pofstream &stream, bool truncate = true) const;
221 bool open_append(pofstream &stream) const;
222 bool open_read_write(pfstream &stream, bool truncate = false) const;
223 bool open_read_append(pfstream &stream) const;
224#endif // USE_PANDAFILESTREAM
225
226 bool chdir() const;
227 bool touch() const;
228 bool unlink() const;
229 BLOCKING bool rename_to(const Filename &other) const;
230 BLOCKING bool copy_to(const Filename &other) const;
231
232 bool make_dir() const;
233 bool mkdir() const;
234 bool rmdir() const;
235
236 // Comparison operators are handy.
237 INLINE bool operator == (const std::string &other) const;
238 INLINE bool operator != (const std::string &other) const;
239 INLINE bool operator < (const std::string &other) const;
240 INLINE int compare_to(const Filename &other) const;
241 INLINE bool __nonzero__() const;
242 int get_hash() const;
243
244 INLINE void output(std::ostream &out) const;
245
246 INLINE static void set_filesystem_encoding(TextEncoder::Encoding encoding);
247 INLINE static TextEncoder::Encoding get_filesystem_encoding();
248
249public:
250 bool atomic_compare_and_exchange_contents(std::string &orig_contents, const std::string &old_contents, const std::string &new_contents) const;
251 bool atomic_read_contents(std::string &contents) const;
252
253protected:
254 void locate_basename();
255 void locate_extension();
256 void locate_hash();
257 size_t get_common_prefix(const std::string &other) const;
258 static int count_slashes(const std::string &str);
259 bool r_make_canonical(const Filename &cwd);
260
261 std::string _filename;
262 // We'll make these size_t instead of string::size_type to help out
263 // cppParser.
264 size_t _dirname_end;
265 size_t _basename_start;
266 size_t _basename_end;
267 size_t _extension_start;
268 size_t _hash_start;
269 size_t _hash_end;
270
271 int _flags;
272
273 static TextEncoder::Encoding _filesystem_encoding;
274 static TVOLATILE AtomicAdjust::Pointer _home_directory;
275 static TVOLATILE AtomicAdjust::Pointer _temp_directory;
276 static TVOLATILE AtomicAdjust::Pointer _user_appdata_directory;
277 static TVOLATILE AtomicAdjust::Pointer _common_appdata_directory;
278
279#ifdef ANDROID
280public:
281 static std::string _internal_data_dir;
282#endif
283
284public:
285 static TypeHandle get_class_type() {
286 return _type_handle;
287 }
288 static void init_type() {
289 register_type(_type_handle, "Filename");
290 }
291
292private:
293 static TypeHandle _type_handle;
294};
295
296INLINE std::ostream &operator << (std::ostream &out, const Filename &n) {
297 n.output(out);
298 return out;
299}
300
301#include "filename.I"
302
303#endif
This class stores a list of directories that can be searched, in order, to locate a particular file.
Definition dSearchPath.h:28
The name of a file, such as a texture file or an Egg file.
Definition filename.h:44
TypeHandle is the identifier used to differentiate C++ class types.
Definition typeHandle.h:81
An STL function object class, this is intended to be used on any ordered collection of class objects ...
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
void register_type(TypeHandle &type_handle, const std::string &name)
This inline function is just a convenient way to call TypeRegistry::register_type(),...
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.