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
26 class 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 */
44 class 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
54 public:
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
249 public:
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
253 protected:
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
280 public:
281 static std::string _internal_data_dir;
282#endif
283
284 public:
285 static TypeHandle get_class_type() {
286 return _type_handle;
287 }
288 static void init_type() {
289 register_type(_type_handle, "Filename");
290 }
291
292 private:
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
DSearchPath
This class stores a list of directories that can be searched, in order, to locate a particular file.
Definition dSearchPath.h:28
Filename
The name of a file, such as a texture file or an Egg file.
Definition filename.h:44
Filename::__nonzero__
bool __nonzero__() const
Returns true if the Filename is valid (not empty), or false if it is an empty string.
Definition filename.I:611
Filename::set_basename
void set_basename(const std::string &s)
Replaces the basename part of the filename.
Definition filename.cxx:754
Filename::compare_timestamps
int compare_timestamps(const Filename &other, bool this_missing_is_old=true, bool other_missing_is_old=true) const
Returns a number less than zero if the file named by this object is older than the given file,...
Definition filename.cxx:1426
Filename::open_append
bool open_append(std::ofstream &stream) const
Opens the indicated ofstream for writing the file, if possible.
Definition filename.cxx:1954
Filename::is_regular_file
bool is_regular_file() const
Returns true if the filename exists on the physical disk and is the name of a regular file (i....
Definition filename.cxx:1303
Filename::scan_directory
bool scan_directory(vector_string &contents) const
Attempts to open the named filename as if it were a directory and looks for the non-hidden files with...
Definition filename.cxx:1727
Filename::set_type
void set_type(Type type)
Sets the type of the file represented by the filename.
Definition filename.I:468
Filename::is_fully_qualified
bool is_fully_qualified() const
Returns true if the filename is fully qualified, e.g.
Definition filename.I:562
Filename::copy_to
bool copy_to(const Filename &other) const
Copies the file to the indicated new filename, by reading the contents and writing it to the new file...
Definition filename.cxx:2449
Filename::get_basename
std::string get_basename() const
Returns the basename part of the filename.
Definition filename.I:367
Filename::resolve_filename
bool resolve_filename(const DSearchPath &searchpath, const std::string &default_extension=std::string())
Searches the given search path for the filename.
Definition filename.cxx:1590
Filename::get_filename_index
Filename get_filename_index(int index) const
If the pattern flag is set for this Filename and the filename string actually includes a sequence of ...
Definition filename.cxx:836
Filename::open_read_append
bool open_read_append(std::fstream &stream) const
Opens the indicated ifstream for reading and writing the file, if possible; writes are appended to th...
Definition filename.cxx:2028
Filename::has_hash
bool has_hash() const
Returns true if the filename is indicated to be a filename pattern (that is, set_pattern(true) was ca...
Definition filename.I:531
Filename::is_executable
bool is_executable() const
Returns true if the filename exists and is executable.
Definition filename.cxx:1396
Filename::get_fullpath_wo_extension
std::string get_fullpath_wo_extension() const
Returns the full filename–directory and basename parts–except for the extension.
Definition filename.I:377
Filename::is_text
bool is_text() const
Returns true if the Filename has been indicated to represent a text file via a previous call to set_t...
Definition filename.I:456
Filename::to_os_short_name
std::string to_os_short_name() const
This works like to_os_generic(), but it returns the "short name" version of the filename,...
Definition filename.cxx:1202
Filename::to_os_specific
std::string to_os_specific() const
Converts the filename from our generic Unix-like convention (forward slashes starting with the root a...
Definition filename.cxx:1123
Filename::open_read
bool open_read(std::ifstream &stream) const
Opens the indicated ifstream for reading the file, if possible.
Definition filename.cxx:1872
Filename::get_home_directory
static const Filename & get_home_directory()
Returns a path to the user's home directory, if such a thing makes sense in the current OS,...
Definition filename.cxx:474
Filename::rmdir
bool rmdir() const
The inverse of mkdir(): this removes the directory named by this Filename, if it is in fact a directo...
Definition filename.cxx:2568
Filename::rename_to
bool rename_to(const Filename &other) const
Renames the file to the indicated new filename.
Definition filename.cxx:2350
Filename::open_read_write
bool open_read_write(std::fstream &stream, bool truncate=false) const
Opens the indicated fstream for read/write access to the file, if possible.
Definition filename.cxx:1986
Filename::is_binary
bool is_binary() const
Returns true if the Filename has been indicated to represent a binary file via a previous call to set...
Definition filename.I:435
Filename::set_hash_to_end
void set_hash_to_end(const std::string &s)
Replaces the part of the filename from the beginning of the hash sequence to the end of the filename.
Definition filename.cxx:856
Filename::get_hash
int get_hash() const
Returns a hash code that attempts to be mostly unique for different Filenames.
Definition filename.cxx:2593
Filename::get_common_appdata_directory
static const Filename & get_common_appdata_directory()
Returns a path to a system-defined directory appropriate for creating a subdirectory for storing appl...
Definition filename.cxx:645
Filename::from_os_specific_w
static Filename from_os_specific_w(const std::wstring &os_specific, Type type=T_general)
The wide-string variant of from_os_specific().
Definition filename.cxx:394
Filename::unlink
bool unlink() const
Permanently deletes the file associated with the filename, if possible.
Definition filename.cxx:2330
Filename::expand_from
static Filename expand_from(const std::string &user_string, Type type=T_general)
Returns the same thing as from_os_specific(), but embedded environment variable references (e....
Definition filename.cxx:407
Filename::standardize
void standardize()
Converts the filename to standard form by replacing consecutive slashes with a single slash,...
Definition filename.cxx:900
Filename::set_dirname
void set_dirname(const std::string &s)
Replaces the directory part of the filename.
Definition filename.cxx:704
Filename::set_fullpath_wo_extension
void set_fullpath_wo_extension(const std::string &s)
Replaces the full filename–directory and basename parts–except for the extension.
Definition filename.cxx:766
Filename::is_writable
bool is_writable() const
Returns true if the filename exists on the physical disk and is either a directory or a regular file ...
Definition filename.cxx:1333
Filename::set_binary
void set_binary()
Indicates that the filename represents a binary file.
Definition filename.I:414
Filename::is_binary_or_text
bool is_binary_or_text() const
Returns true either is_binary() or is_text() is true; that is, that the filename has been specified a...
Definition filename.I:445
Filename::set_basename_wo_extension
void set_basename_wo_extension(const std::string &s)
Replaces the basename part of the filename, without the file extension.
Definition filename.cxx:783
Filename::get_filesystem_encoding
static TextEncoder::Encoding get_filesystem_encoding()
Specifies the default encoding to be used for all subsequent Filenames objects.
Definition filename.I:639
Filename::get_temp_directory
static const Filename & get_temp_directory()
Returns a path to a system-defined temporary directory.
Definition filename.cxx:539
Filename::get_user_appdata_directory
static const Filename & get_user_appdata_directory()
Returns a path to a system-defined directory appropriate for creating a subdirectory for storing appl...
Definition filename.cxx:589
Filename::chdir
bool chdir() const
Changes directory to the specified location.
Definition filename.cxx:2314
Filename::touch
bool touch() const
Updates the modification time of the file to the current time.
Definition filename.cxx:2234
Filename::to_os_specific_w
std::wstring to_os_specific_w() const
The wide-string variant on to_os_specific().
Definition filename.cxx:1163
Filename::make_dir
bool make_dir() const
Creates all the directories in the path to the file specified in the filename, except for the basenam...
Definition filename.cxx:2495
Filename::get_pattern
bool get_pattern() const
Returns the flag indicating whether this is a filename pattern.
Definition filename.I:519
Filename::make_true_case
bool make_true_case()
On a case-insensitive operating system (e.g.
Definition filename.cxx:1053
Filename::set_filesystem_encoding
static void set_filesystem_encoding(TextEncoder::Encoding encoding)
Specifies the default encoding to be used for all subsequent Filenames.
Definition filename.I:630
Filename::set_text
void set_text()
Indicates that the filename represents a text file.
Definition filename.I:424
Filename::get_timestamp
time_t get_timestamp() const
Returns a time_t value that represents the time the file was last modified, to within whatever precis...
Definition filename.cxx:1506
Filename::get_fullpath
std::string get_fullpath() const
Returns the entire filename: directory, basename, extension.
Definition filename.I:338
Filename::make_canonical
bool make_canonical()
Converts this filename to a canonical name by replacing the directory part with the fully-qualified d...
Definition filename.cxx:1011
Filename::temporary
static Filename temporary(const std::string &dirname, const std::string &prefix, const std::string &suffix=std::string(), Type type=T_general)
Generates a temporary filename within the indicated directory, using the indicated prefix.
Definition filename.cxx:424
Filename::from_os_specific
static Filename from_os_specific(const std::string &os_specific, Type type=T_general)
This named constructor returns a Panda-style filename (that is, using forward slashes,...
Definition filename.cxx:328
Filename::get_hash_to_end
std::string get_hash_to_end() const
Returns the part of the filename beginning at the hash sequence (if any), and continuing to the end o...
Definition filename.I:540
Filename::set_extension
void set_extension(const std::string &s)
Replaces the file extension.
Definition filename.cxx:804
Filename::to_os_generic
std::string to_os_generic() const
This is similar to to_os_specific(), but it is designed to generate a filename that can be understood...
Definition filename.cxx:1182
Filename::find_on_searchpath
int find_on_searchpath(const DSearchPath &searchpath)
Performs the reverse of the resolve_filename() operation: assuming that the current filename is fully...
Definition filename.cxx:1698
Filename::extract_components
void extract_components(vector_string &components) const
Extracts out the individual directory components of the path into a series of strings.
Definition filename.cxx:872
Filename::is_directory
bool is_directory() const
Returns true if the filename exists on the physical disk and is a directory name, false otherwise.
Definition filename.cxx:1368
Filename::to_os_long_name
std::string to_os_long_name() const
This is the opposite of to_os_short_name(): it returns the "long name" of the filename,...
Definition filename.cxx:1236
Filename::atomic_compare_and_exchange_contents
bool atomic_compare_and_exchange_contents(std::string &orig_contents, const std::string &old_contents, const std::string &new_contents) const
Uses native file-locking mechanisms to atomically replace the contents of a (small) file with the spe...
Definition filename.cxx:2653
Filename::get_fullpath_w
std::wstring get_fullpath_w() const
Returns the entire filename as a wide-character string.
Definition filename.I:346
Filename::atomic_read_contents
bool atomic_read_contents(std::string &contents) const
Uses native file-locking mechanisms to atomically read the contents of a (small) file.
Definition filename.cxx:2797
Filename::open_write
bool open_write(std::ofstream &stream, bool truncate=true) const
Opens the indicated ifstream for writing the file, if possible.
Definition filename.cxx:1908
Filename::make_relative_to
bool make_relative_to(Filename directory, bool allow_backups=true)
Adjusts this filename, which must be a fully-specified pathname beginning with a slash,...
Definition filename.cxx:1649
Filename::get_extension
std::string get_extension() const
Returns the file extension.
Definition filename.I:400
Filename::set_fullpath
void set_fullpath(const std::string &s)
Replaces the entire filename: directory, basename, extension.
Definition filename.cxx:695
Filename::mkdir
bool mkdir() const
Creates the directory named by this filename.
Definition filename.cxx:2551
Filename::is_local
bool is_local() const
Returns true if the filename is local, e.g.
Definition filename.I:549
Filename::get_basename_wo_extension
std::string get_basename_wo_extension() const
Returns the basename part of the filename, without the file extension.
Definition filename.I:386
Filename::get_dirname
std::string get_dirname() const
Returns the directory part of the filename.
Definition filename.I:358
Filename::make_absolute
void make_absolute()
Converts the filename to a fully-qualified pathname from the root (if it is a relative pathname),...
Definition filename.cxx:968
Filename::get_type
Type get_type() const
Returns the type of the file represented by the filename, as previously set by set_type().
Definition filename.I:485
Filename::pattern_filename
static Filename pattern_filename(const std::string &filename)
Constructs a filename that represents a sequence of numbered files.
Definition filename.I:160
Filename::set_pattern
void set_pattern(bool pattern)
Sets the flag indicating whether this is a filename pattern.
Definition filename.I:503
Filename::exists
bool exists() const
Returns true if the filename exists on the physical disk, false otherwise.
Definition filename.cxx:1270
Filename::get_access_timestamp
time_t get_access_timestamp() const
Returns a time_t value that represents the time the file was last accessed, if this information is av...
Definition filename.cxx:1534
Filename::get_file_size
std::streamsize get_file_size() const
Returns the size of the file in bytes, or 0 if there is an error.
Definition filename.cxx:1560
TypeHandle
TypeHandle is the identifier used to differentiate C++ class types.
Definition typeHandle.h:81
dtoolbase.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
filename.I
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
pandaFileStream.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
register_type.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
register_type
void register_type(TypeHandle &type_handle, const std::string &name)
This inline function is just a convenient way to call TypeRegistry::register_type(),...
Definition register_type.I:22
textEncoder.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
typeHandle.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
vector_string.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.