| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: wx/filename.h |
| 3 | // Purpose: wxFileName - encapsulates a file path |
| 4 | // Author: Robert Roebling, Vadim Zeitlin |
| 5 | // Modified by: |
| 6 | // Created: 28.12.00 |
| 7 | // RCS-ID: $Id$ |
| 8 | // Copyright: (c) 2000 Robert Roebling |
| 9 | // Licence: wxWindows licence |
| 10 | ///////////////////////////////////////////////////////////////////////////// |
| 11 | |
| 12 | #ifndef _WX_FILENAME_H_ |
| 13 | #define _WX_FILENAME_H_ |
| 14 | |
| 15 | /* |
| 16 | TODO: |
| 17 | |
| 18 | 1. support for drives under Windows |
| 19 | 2. more file operations: |
| 20 | a) chmod() |
| 21 | b) [acm]time() - get and set |
| 22 | c) file size |
| 23 | d) file permissions with readable accessors for most common bits |
| 24 | such as IsReadable() &c |
| 25 | e) rename()? |
| 26 | 3. SameFileAs() function to compare inodes under Unix |
| 27 | */ |
| 28 | |
| 29 | #include "wx/arrstr.h" |
| 30 | #include "wx/filefn.h" |
| 31 | #include "wx/datetime.h" |
| 32 | |
| 33 | #if wxUSE_FILE |
| 34 | class WXDLLIMPEXP_BASE wxFile; |
| 35 | #endif |
| 36 | |
| 37 | // ---------------------------------------------------------------------------- |
| 38 | // constants |
| 39 | // ---------------------------------------------------------------------------- |
| 40 | |
| 41 | // the various values for the path format: this mainly affects the path |
| 42 | // separator but also whether or not the path has the drive part (as under |
| 43 | // Windows) |
| 44 | enum wxPathFormat |
| 45 | { |
| 46 | wxPATH_NATIVE = 0, // the path format for the current platform |
| 47 | wxPATH_UNIX, |
| 48 | wxPATH_BEOS = wxPATH_UNIX, |
| 49 | wxPATH_MAC, |
| 50 | wxPATH_DOS, |
| 51 | wxPATH_WIN = wxPATH_DOS, |
| 52 | wxPATH_OS2 = wxPATH_DOS, |
| 53 | wxPATH_VMS, |
| 54 | |
| 55 | wxPATH_MAX // Not a valid value for specifying path format |
| 56 | }; |
| 57 | |
| 58 | // the kind of normalization to do with the file name: these values can be |
| 59 | // or'd together to perform several operations at once |
| 60 | enum wxPathNormalize |
| 61 | { |
| 62 | wxPATH_NORM_ENV_VARS = 0x0001, // replace env vars with their values |
| 63 | wxPATH_NORM_DOTS = 0x0002, // squeeze all .. and . and prepend cwd |
| 64 | wxPATH_NORM_TILDE = 0x0004, // Unix only: replace ~ and ~user |
| 65 | wxPATH_NORM_CASE = 0x0008, // if case insensitive => tolower |
| 66 | wxPATH_NORM_ABSOLUTE = 0x0010, // make the path absolute |
| 67 | wxPATH_NORM_LONG = 0x0020, // make the path the long form |
| 68 | wxPATH_NORM_SHORTCUT = 0x0040, // resolve the shortcut, if it is a shortcut |
| 69 | wxPATH_NORM_ALL = 0x00ff & ~wxPATH_NORM_CASE |
| 70 | }; |
| 71 | |
| 72 | // what exactly should GetPath() return? |
| 73 | enum |
| 74 | { |
| 75 | wxPATH_GET_VOLUME = 0x0001, // include the volume if applicable |
| 76 | wxPATH_GET_SEPARATOR = 0x0002 // terminate the path with the separator |
| 77 | }; |
| 78 | |
| 79 | // MkDir flags |
| 80 | enum |
| 81 | { |
| 82 | wxPATH_MKDIR_FULL = 0x0001 // create directories recursively |
| 83 | }; |
| 84 | |
| 85 | // ---------------------------------------------------------------------------- |
| 86 | // wxFileName: encapsulates a file path |
| 87 | // ---------------------------------------------------------------------------- |
| 88 | |
| 89 | class WXDLLIMPEXP_BASE wxFileName |
| 90 | { |
| 91 | public: |
| 92 | // constructors and assignment |
| 93 | |
| 94 | // the usual stuff |
| 95 | wxFileName() { Clear(); } |
| 96 | wxFileName(const wxFileName& filepath) { Assign(filepath); } |
| 97 | |
| 98 | // from a full filename: if it terminates with a '/', a directory path |
| 99 | // is contructed (the name will be empty), otherwise a file name and |
| 100 | // extension are extracted from it |
| 101 | wxFileName( const wxString& fullpath, wxPathFormat format = wxPATH_NATIVE ) |
| 102 | { Assign( fullpath, format ); } |
| 103 | |
| 104 | // from a directory name and a file name |
| 105 | wxFileName(const wxString& path, |
| 106 | const wxString& name, |
| 107 | wxPathFormat format = wxPATH_NATIVE) |
| 108 | { Assign(path, name, format); } |
| 109 | |
| 110 | // from a volume, directory name, file base name and extension |
| 111 | wxFileName(const wxString& volume, |
| 112 | const wxString& path, |
| 113 | const wxString& name, |
| 114 | const wxString& ext, |
| 115 | wxPathFormat format = wxPATH_NATIVE) |
| 116 | { Assign(volume, path, name, ext, format); } |
| 117 | |
| 118 | // from a directory name, file base name and extension |
| 119 | wxFileName(const wxString& path, |
| 120 | const wxString& name, |
| 121 | const wxString& ext, |
| 122 | wxPathFormat format = wxPATH_NATIVE) |
| 123 | { Assign(path, name, ext, format); } |
| 124 | |
| 125 | // the same for delayed initialization |
| 126 | |
| 127 | void Assign(const wxFileName& filepath); |
| 128 | |
| 129 | void Assign(const wxString& fullpath, |
| 130 | wxPathFormat format = wxPATH_NATIVE); |
| 131 | |
| 132 | void Assign(const wxString& volume, |
| 133 | const wxString& path, |
| 134 | const wxString& name, |
| 135 | const wxString& ext, |
| 136 | bool hasExt, |
| 137 | wxPathFormat format = wxPATH_NATIVE); |
| 138 | |
| 139 | void Assign(const wxString& volume, |
| 140 | const wxString& path, |
| 141 | const wxString& name, |
| 142 | const wxString& ext, |
| 143 | wxPathFormat format = wxPATH_NATIVE) |
| 144 | { Assign(volume, path, name, ext, !ext.empty(), format); } |
| 145 | |
| 146 | void Assign(const wxString& path, |
| 147 | const wxString& name, |
| 148 | wxPathFormat format = wxPATH_NATIVE); |
| 149 | |
| 150 | void Assign(const wxString& path, |
| 151 | const wxString& name, |
| 152 | const wxString& ext, |
| 153 | wxPathFormat format = wxPATH_NATIVE); |
| 154 | |
| 155 | void AssignDir(const wxString& dir, wxPathFormat format = wxPATH_NATIVE); |
| 156 | |
| 157 | // assorted assignment operators |
| 158 | |
| 159 | wxFileName& operator=(const wxFileName& filename) |
| 160 | { Assign(filename); return *this; } |
| 161 | |
| 162 | wxFileName& operator=(const wxString& filename) |
| 163 | { Assign(filename); return *this; } |
| 164 | |
| 165 | // reset all components to default, uninitialized state |
| 166 | void Clear(); |
| 167 | |
| 168 | // static pseudo constructors |
| 169 | static wxFileName FileName(const wxString& file, |
| 170 | wxPathFormat format = wxPATH_NATIVE); |
| 171 | static wxFileName DirName(const wxString& dir, |
| 172 | wxPathFormat format = wxPATH_NATIVE); |
| 173 | |
| 174 | // file tests |
| 175 | |
| 176 | // is the filename valid at all? |
| 177 | bool IsOk() const |
| 178 | { |
| 179 | // we're fine if we have the path or the name or if we're a root dir |
| 180 | return m_dirs.size() != 0 || !m_name.empty() || !m_relative || |
| 181 | !m_ext.empty() || m_hasExt; |
| 182 | } |
| 183 | |
| 184 | // does the file with this name exists? |
| 185 | bool FileExists() const; |
| 186 | static bool FileExists( const wxString &file ); |
| 187 | |
| 188 | // does the directory with this name exists? |
| 189 | bool DirExists() const; |
| 190 | static bool DirExists( const wxString &dir ); |
| 191 | |
| 192 | // VZ: also need: IsDirWritable(), IsFileExecutable() &c (TODO) |
| 193 | |
| 194 | // time functions |
| 195 | #if wxUSE_DATETIME |
| 196 | // set the file last access/mod and creation times |
| 197 | // (any of the pointers may be NULL) |
| 198 | bool SetTimes(const wxDateTime *dtAccess, |
| 199 | const wxDateTime *dtMod, |
| 200 | const wxDateTime *dtCreate); |
| 201 | |
| 202 | // set the access and modification times to the current moment |
| 203 | bool Touch(); |
| 204 | |
| 205 | // return the last access, last modification and create times |
| 206 | // (any of the pointers may be NULL) |
| 207 | bool GetTimes(wxDateTime *dtAccess, |
| 208 | wxDateTime *dtMod, |
| 209 | wxDateTime *dtCreate) const; |
| 210 | |
| 211 | // convenience wrapper: get just the last mod time of the file |
| 212 | wxDateTime GetModificationTime() const |
| 213 | { |
| 214 | wxDateTime dtMod; |
| 215 | (void)GetTimes(NULL, &dtMod, NULL); |
| 216 | return dtMod; |
| 217 | } |
| 218 | #endif // wxUSE_DATETIME |
| 219 | |
| 220 | #ifdef __WXMAC__ |
| 221 | bool MacSetTypeAndCreator( wxUint32 type , wxUint32 creator ) ; |
| 222 | bool MacGetTypeAndCreator( wxUint32 *type , wxUint32 *creator ) ; |
| 223 | // gets the 'common' type and creator for a certain extension |
| 224 | static bool MacFindDefaultTypeAndCreator( const wxString& ext , wxUint32 *type , wxUint32 *creator ) ; |
| 225 | // registers application defined extensions and their default type and creator |
| 226 | static void MacRegisterDefaultTypeAndCreator( const wxString& ext , wxUint32 type , wxUint32 creator ) ; |
| 227 | // looks up the appropriate type and creator from the registration and then sets |
| 228 | bool MacSetDefaultTypeAndCreator() ; |
| 229 | #endif |
| 230 | |
| 231 | // various file/dir operations |
| 232 | |
| 233 | // retrieve the value of the current working directory |
| 234 | void AssignCwd(const wxString& volume = wxEmptyString); |
| 235 | static wxString GetCwd(const wxString& volume = wxEmptyString); |
| 236 | |
| 237 | // change the current working directory |
| 238 | bool SetCwd(); |
| 239 | static bool SetCwd( const wxString &cwd ); |
| 240 | |
| 241 | // get the value of user home (Unix only mainly) |
| 242 | void AssignHomeDir(); |
| 243 | static wxString GetHomeDir(); |
| 244 | |
| 245 | #if wxUSE_FILE |
| 246 | // get a temp file name starting with the specified prefix and open the |
| 247 | // file passed to us using this name for writing (atomically if |
| 248 | // possible) |
| 249 | void AssignTempFileName(const wxString& prefix, wxFile *fileTemp = NULL); |
| 250 | static wxString CreateTempFileName(const wxString& prefix, |
| 251 | wxFile *fileTemp = NULL); |
| 252 | #endif // wxUSE_FILE |
| 253 | |
| 254 | // directory creation and removal. |
| 255 | bool Mkdir( int perm = 0777, int flags = 0); |
| 256 | static bool Mkdir( const wxString &dir, int perm = 0777, int flags = 0 ); |
| 257 | |
| 258 | bool Rmdir(); |
| 259 | static bool Rmdir( const wxString &dir ); |
| 260 | |
| 261 | // operations on the path |
| 262 | |
| 263 | // normalize the path: with the default flags value, the path will be |
| 264 | // made absolute, without any ".." and "." and all environment |
| 265 | // variables will be expanded in it |
| 266 | // |
| 267 | // this may be done using another (than current) value of cwd |
| 268 | bool Normalize(int flags = wxPATH_NORM_ALL, |
| 269 | const wxString& cwd = wxEmptyString, |
| 270 | wxPathFormat format = wxPATH_NATIVE); |
| 271 | |
| 272 | // get a path path relative to the given base directory, i.e. opposite |
| 273 | // of Normalize |
| 274 | // |
| 275 | // pass an empty string to get a path relative to the working directory |
| 276 | // |
| 277 | // returns true if the file name was modified, false if we failed to do |
| 278 | // anything with it (happens when the file is on a different volume, |
| 279 | // for example) |
| 280 | bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, |
| 281 | wxPathFormat format = wxPATH_NATIVE); |
| 282 | |
| 283 | // make the path absolute |
| 284 | // |
| 285 | // this may be done using another (than current) value of cwd |
| 286 | bool MakeAbsolute(const wxString& cwd = wxEmptyString, |
| 287 | wxPathFormat format = wxPATH_NATIVE) |
| 288 | { return Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | |
| 289 | wxPATH_NORM_TILDE, cwd, format); } |
| 290 | |
| 291 | #if defined(__WIN32__) && !defined(__WXWINCE__) && wxUSE_OLE |
| 292 | // if the path is a shortcut, return the target and optionally, |
| 293 | // the arguments |
| 294 | bool GetShortcutTarget(const wxString& shortcutPath, |
| 295 | wxString& targetFilename, |
| 296 | wxString* arguments = NULL); |
| 297 | #endif |
| 298 | |
| 299 | // Comparison |
| 300 | |
| 301 | // compares with the rules of the given platforms format |
| 302 | bool SameAs(const wxFileName& filepath, |
| 303 | wxPathFormat format = wxPATH_NATIVE) const; |
| 304 | |
| 305 | // compare with another filename object |
| 306 | bool operator==(const wxFileName& filename) const |
| 307 | { return SameAs(filename); } |
| 308 | bool operator!=(const wxFileName& filename) const |
| 309 | { return !SameAs(filename); } |
| 310 | |
| 311 | // compare with a filename string interpreted as a native file name |
| 312 | bool operator==(const wxString& filename) const |
| 313 | { return SameAs(wxFileName(filename)); } |
| 314 | bool operator!=(const wxString& filename) const |
| 315 | { return !SameAs(wxFileName(filename)); } |
| 316 | |
| 317 | // are the file names of this type cases sensitive? |
| 318 | static bool IsCaseSensitive( wxPathFormat format = wxPATH_NATIVE ); |
| 319 | |
| 320 | // is this filename absolute? |
| 321 | bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE) const; |
| 322 | |
| 323 | // is this filename relative? |
| 324 | bool IsRelative(wxPathFormat format = wxPATH_NATIVE) const |
| 325 | { return !IsAbsolute(format); } |
| 326 | |
| 327 | // Returns the characters that aren't allowed in filenames |
| 328 | // on the specified platform. |
| 329 | static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); |
| 330 | |
| 331 | // Information about path format |
| 332 | |
| 333 | // get the string separating the volume from the path for this format, |
| 334 | // return an empty string if this format doesn't support the notion of |
| 335 | // volumes at all |
| 336 | static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); |
| 337 | |
| 338 | // get the string of path separators for this format |
| 339 | static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); |
| 340 | |
| 341 | // get the string of path terminators, i.e. characters which terminate the |
| 342 | // path |
| 343 | static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); |
| 344 | |
| 345 | // get the canonical path separator for this format |
| 346 | static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE) |
| 347 | { return GetPathSeparators(format)[0u]; } |
| 348 | |
| 349 | // is the char a path separator for this format? |
| 350 | static bool IsPathSeparator(wxChar ch, wxPathFormat format = wxPATH_NATIVE); |
| 351 | |
| 352 | // Dir accessors |
| 353 | size_t GetDirCount() const { return m_dirs.size(); } |
| 354 | void AppendDir(const wxString& dir); |
| 355 | void PrependDir(const wxString& dir); |
| 356 | void InsertDir(size_t before, const wxString& dir); |
| 357 | void RemoveDir(size_t pos); |
| 358 | void RemoveLastDir() { RemoveDir(GetDirCount() - 1); } |
| 359 | |
| 360 | // Other accessors |
| 361 | void SetExt( const wxString &ext ) { m_ext = ext; m_hasExt = !m_ext.empty(); } |
| 362 | void ClearExt() { m_ext = wxEmptyString; m_hasExt = false; } |
| 363 | void SetEmptyExt() { m_ext = wxT(""); m_hasExt = true; } |
| 364 | wxString GetExt() const { return m_ext; } |
| 365 | bool HasExt() const { return m_hasExt; } |
| 366 | |
| 367 | void SetName( const wxString &name ) { m_name = name; } |
| 368 | wxString GetName() const { return m_name; } |
| 369 | bool HasName() const { return !m_name.empty(); } |
| 370 | |
| 371 | void SetVolume( const wxString &volume ) { m_volume = volume; } |
| 372 | wxString GetVolume() const { return m_volume; } |
| 373 | bool HasVolume() const { return !m_volume.empty(); } |
| 374 | |
| 375 | // full name is the file name + extension (but without the path) |
| 376 | void SetFullName(const wxString& fullname); |
| 377 | wxString GetFullName() const; |
| 378 | |
| 379 | const wxArrayString& GetDirs() const { return m_dirs; } |
| 380 | |
| 381 | // flags are combination of wxPATH_GET_XXX flags |
| 382 | wxString GetPath(int flags = wxPATH_GET_VOLUME, |
| 383 | wxPathFormat format = wxPATH_NATIVE) const; |
| 384 | |
| 385 | // Replace current path with this one |
| 386 | void SetPath( const wxString &path, wxPathFormat format = wxPATH_NATIVE ); |
| 387 | |
| 388 | // Construct full path with name and ext |
| 389 | wxString GetFullPath( wxPathFormat format = wxPATH_NATIVE ) const; |
| 390 | |
| 391 | // Return the short form of the path (returns identity on non-Windows platforms) |
| 392 | wxString GetShortPath() const; |
| 393 | |
| 394 | // Return the long form of the path (returns identity on non-Windows platforms) |
| 395 | wxString GetLongPath() const; |
| 396 | |
| 397 | // Is this a file or directory (not necessarily an existing one) |
| 398 | bool IsDir() const { return m_name.empty() && m_ext.empty(); } |
| 399 | |
| 400 | // various helpers |
| 401 | |
| 402 | // get the canonical path format for this platform |
| 403 | static wxPathFormat GetFormat( wxPathFormat format = wxPATH_NATIVE ); |
| 404 | |
| 405 | // split a fullpath into the volume, path, (base) name and extension |
| 406 | // (all of the pointers can be NULL) |
| 407 | static void SplitPath(const wxString& fullpath, |
| 408 | wxString *volume, |
| 409 | wxString *path, |
| 410 | wxString *name, |
| 411 | wxString *ext, |
| 412 | bool *hasExt = NULL, |
| 413 | wxPathFormat format = wxPATH_NATIVE); |
| 414 | |
| 415 | static void SplitPath(const wxString& fullpath, |
| 416 | wxString *volume, |
| 417 | wxString *path, |
| 418 | wxString *name, |
| 419 | wxString *ext, |
| 420 | wxPathFormat format) |
| 421 | { |
| 422 | SplitPath(fullpath, volume, path, name, ext, NULL, format); |
| 423 | } |
| 424 | |
| 425 | // compatibility version: volume is part of path |
| 426 | static void SplitPath(const wxString& fullpath, |
| 427 | wxString *path, |
| 428 | wxString *name, |
| 429 | wxString *ext, |
| 430 | wxPathFormat format = wxPATH_NATIVE); |
| 431 | |
| 432 | // split a path into volume and pure path part |
| 433 | static void SplitVolume(const wxString& fullpathWithVolume, |
| 434 | wxString *volume, |
| 435 | wxString *path, |
| 436 | wxPathFormat format = wxPATH_NATIVE); |
| 437 | |
| 438 | // deprecated methods, don't use any more |
| 439 | // -------------------------------------- |
| 440 | |
| 441 | #ifndef __DIGITALMARS__ |
| 442 | wxString GetPath( bool withSep, wxPathFormat format = wxPATH_NATIVE ) const |
| 443 | { return GetPath(withSep ? wxPATH_GET_SEPARATOR : 0, format); } |
| 444 | #endif |
| 445 | wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE ) const |
| 446 | { return GetPath(wxPATH_GET_SEPARATOR, format); } |
| 447 | |
| 448 | private: |
| 449 | // check whether this dir is valid for Append/Prepend/InsertDir() |
| 450 | static bool IsValidDirComponent(const wxString& dir); |
| 451 | |
| 452 | // the drive/volume/device specification (always empty for Unix) |
| 453 | wxString m_volume; |
| 454 | |
| 455 | // the path components of the file |
| 456 | wxArrayString m_dirs; |
| 457 | |
| 458 | // the file name and extension (empty for directories) |
| 459 | wxString m_name, |
| 460 | m_ext; |
| 461 | |
| 462 | // when m_dirs is empty it may mean either that we have no path at all or |
| 463 | // that our path is '/', i.e. the root directory |
| 464 | // |
| 465 | // we use m_relative to distinguish between these two cases, it will be |
| 466 | // true in the former and false in the latter |
| 467 | // |
| 468 | // NB: the path is not absolute just because m_relative is false, it still |
| 469 | // needs the drive (i.e. volume) in some formats (Windows) |
| 470 | bool m_relative; |
| 471 | |
| 472 | // when m_ext is empty, it may be because we don't have any extension or |
| 473 | // because we have an empty extension |
| 474 | // |
| 475 | // the difference is important as file with name "foo" and without |
| 476 | // extension has full name "foo" while with empty extension it is "foo." |
| 477 | bool m_hasExt; |
| 478 | }; |
| 479 | |
| 480 | #endif // _WX_FILENAME_H_ |
| 481 | |