simgear/misc/sg_path.hxx

   1 /**
   2  * \file sg_path.hxx
   3  * Routines to abstract out path separator differences between MacOS
   4  * and the rest of the world.
   5  */
   6
   7 // Written by Curtis L. Olson, started April 1999.
   8 //
   9 // Copyright (C) 1999  Curtis L. Olson - http://www.flightgear.org/~curt
  10 //
  11 // This library is free software; you can redistribute it and/or
  12 // modify it under the terms of the GNU Library General Public
  13 // License as published by the Free Software Foundation; either
  14 // version 2 of the License, or (at your option) any later version.
  15 //
  16 // This library is distributed in the hope that it will be useful,
  17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19 // Library General Public License for more details.
  20 //
  21 // You should have received a copy of the GNU General Public License
  22 // along with this program; if not, write to the Free Software
  23 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  24 //
  25 // $Id$
  26
  27
  28 #ifndef _SG_PATH_HXX
  29 #define _SG_PATH_HXX
  30
  31 #include <sys/types.h>
  32
  33 #include <simgear/compiler.h>
  34 #include <string>
  35 #include <ctime>
  36
  37 #include <simgear/math/sg_types.hxx>
  38
  39 #ifdef _MSC_VER
  40   typedef int mode_t;
  41 #endif
  42
  43 /**
  44  * A class to hide path separator difference across platforms and assist
  45  * in managing file system path names.
  46  *
  47  * Paths can be input in any platform format and will be converted
  48  * automatically to the proper format.
  49  */
  50
  51 class SGPath {
  52
  53 public:
  54
  55     struct Permissions
  56     {
  57       bool read : 1;
  58       bool write : 1;
  59     };
  60     typedef Permissions (*PermissionChecker)(const SGPath&);
  61
  62     /** Default constructor */
  63     explicit SGPath(PermissionChecker validator = NULL);
  64
  65     /** Copy contructor */
  66     SGPath(const SGPath& p);
  67
  68     SGPath& operator=(const SGPath& p);
  69
  70     /**
  71      * Construct a path based on the starting path provided.
  72      * @param p initial path
  73      */
  74     SGPath( const std::string& p, PermissionChecker validator = NULL );
  75
  76     /**
  77      * Construct a path based on the starting path provided and a relative subpath
  78      * @param p initial path
  79      * @param r relative subpath
  80      */
  81     SGPath( const SGPath& p,
  82             const std::string& r,
  83             PermissionChecker validator = NULL );
  84
  85     /** Destructor */
  86     ~SGPath();
  87
  88     /**
  89      * Set path to a new value
  90      * @param p new path
  91      */
  92     void set( const std::string& p );
  93     SGPath& operator= ( const char* p ) { this->set(p); return *this; }
  94
  95     bool operator==(const SGPath& other) const;
  96     bool operator!=(const SGPath& other) const;
  97
  98     void setPermissionChecker(PermissionChecker validator);
  99     PermissionChecker getPermissionChecker() const;
 100
 101     /**
 102      * Set if file information (exists, type, mod-time) is cached or
 103      * retrieved each time it is queried. Caching is enabled by default
 104      */
 105     void set_cached(bool cached);
 106
 107     /**
 108      * Append another piece to the existing path.  Inserts a path
 109      * separator between the existing component and the new component.
 110      * @param p additional path component */
 111     void append( const std::string& p );
 112
 113     /**
 114      * Get a copy of this path with another piece appended.
 115      *
 116      * @param p additional path component
 117      */
 118     SGPath operator/( const std::string& p ) const;
 119
 120     /**
 121      * Append a new piece to the existing path.  Inserts a search path
 122      * separator to the existing path and the new patch component.
 123      * @param p additional path component */
 124     void add( const std::string& p );
 125
 126     /**
 127      * Concatenate a string to the end of the path without inserting a
 128      * path separator.
 129      * @param p additional path suffix
 130      */
 131     void concat( const std::string& p );
 132
 133     /**
 134      * Returns a string with the absolute pathname that names the same file, whose
 135      * resolution does not involve '.', '..', or symbolic links.
 136      */
 137     std::string realpath() const;
 138
 139     /**
 140      * Get the file part of the path (everything after the last path sep)
 141      * @return file string
 142      */
 143     std::string file() const;
 144
 145     /**
 146      * Get the directory part of the path.
 147      * @return directory string
 148      */
 149     std::string dir() const;
 150
 151     /**
 152      * Get the base part of the path (everything but the final extension.)
 153      * @return the base string
 154      */
 155     std::string base() const;
 156
 157     /**
 158      * Get the base part of the filename (everything before the first '.')
 159      * @return the base filename
 160      */
 161     std::string file_base() const;
 162
 163     /**
 164      * Get the extension part of the path (everything after the final ".")
 165      * @return the extension string
 166      */
 167     std::string extension() const;
 168
 169     /**
 170      * Get the extension part of the path (everything after the final ".")
 171      * converted to lowercase
 172      * @return the extension string
 173      */
 174     std::string lower_extension() const;
 175
 176     /**
 177      * Get the complete extension part of the path (everything after the first ".")
 178      * this might look like 'tar.gz' or 'txt.Z', or might be identical to 'extension' above
 179      * the extension is converted to lowercase.
 180      * @return the extension string
 181      */
 182     std::string complete_lower_extension() const;
 183
 184     /**
 185      * Get the path string
 186      * @return path string
 187      */
 188     std::string str() const { return path; }
 189
 190     /**
 191      * Get the path string
 192      * @return path in "C" string (ptr to char array) form.
 193      */
 194     const char* c_str() const { return path.c_str(); }
 195
 196     /**
 197      * Get the path string in OS native form
 198      */
 199     std::string str_native() const;
 200
 201     /**
 202      * Determine if file exists by attempting to fopen it.
 203      * @return true if file exists, otherwise returns false.
 204      */
 205     bool exists() const;
 206
 207     /**
 208      * Create the designated directory.
 209      *
 210      * @param mode Permissions. See:
 211      *    http://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation
 212      * @return 0 on success, or <0 on failure.
 213      */
 214     int create_dir(mode_t mode = 0755);
 215
 216     /**
 217      * Check if reading file is allowed. Readabilty does not imply the existance
 218      * of the file.
 219      *
 220      * @note By default all files will be marked as readable. No check is made
 221      *       if the operating system allows the given file to be read. Derived
 222      *       classes may actually implement custom read/write rights.
 223      */
 224     bool canRead() const;
 225     bool canWrite() const;
 226
 227     bool isFile() const;
 228     bool isDir() const;
 229
 230     /**
 231      * Opposite sense to isAbsolute
 232      */
 233     bool isRelative() const { return !isAbsolute(); }
 234
 235     /**
 236      * Is this an absolute path?
 237      * I.e starts with a directory seperator, or a single character + colon
 238      */
 239     bool isAbsolute() const;
 240
 241     /**
 242      * check for default constructed path
 243      */
 244     bool isNull() const;
 245
 246     /**
 247      * delete the file, if possible
 248      */
 249     bool remove();
 250
 251     /**
 252      * modification time of the file
 253      */
 254     time_t modTime() const;
 255
 256     /**
 257      * rename the file / directory we point at, to a new name
 258      * this may fail if the new location is on a different volume / share,
 259      * or if the destination already exists, or is not writeable
 260      */
 261     bool rename(const SGPath& newName);
 262
 263     enum StandardLocation
 264     {
 265       HOME,
 266       DESKTOP,
 267       DOWNLOADS,
 268       DOCUMENTS,
 269       PICTURES
 270     };
 271
 272     static SGPath standardLocation( StandardLocation type,
 273                                     const SGPath& def = SGPath() );
 274
 275     /**
 276      * Get a path stored in the environment variable with the given \a name.
 277      *
 278      * @param name  Name of the environment variable
 279      * @param def   Default path to return if the environment variable does not
 280      *              exist or is empty.
 281      */
 282     static SGPath fromEnv(const char* name, const SGPath& def = SGPath());
 283
 284     /**
 285      * Get path to user's home directory
 286      */
 287     static SGPath home(const SGPath& def = SGPath());
 288
 289     /**
 290      * Get path to the user's desktop directory
 291      */
 292     static SGPath desktop(const SGPath& def = SGPath());
 293
 294         /**
 295      * Get path to the user's documents directory
 296      */
 297     static SGPath documents(const SGPath& def = SGPath());
 298
 299 private:
 300
 301     void fix();
 302
 303     void validate() const;
 304     void checkAccess() const;
 305
 306     std::string path;
 307     PermissionChecker _permission_checker;
 308
 309     mutable bool _cached : 1;
 310     mutable bool _rwCached : 1;
 311     bool _cacheEnabled : 1; ///< cacheing can be disbled if required
 312     mutable bool _canRead : 1;
 313     mutable bool _canWrite : 1;
 314     mutable bool _exists : 1;
 315     mutable bool _isDir : 1;
 316     mutable bool _isFile : 1;
 317     mutable time_t _modTime;
 318 };
 319
 320 /// Output to an ostream
 321 template<typename char_type, typename traits_type>
 322 inline
 323 std::basic_ostream<char_type, traits_type>&
 324 operator<<(std::basic_ostream<char_type, traits_type>& s, const SGPath& p)
 325 { return s << "Path \"" << p.str() << "\""; }
 326
 327
 328 /**
 329  * Split a directory string into a list of it's parent directories.
 330  */
 331 string_list sgPathBranchSplit( const std::string &path );
 332
 333 /**
 334  * Split a directory search path into a vector of individual paths
 335  */
 336 string_list sgPathSplit( const std::string &search_path );
 337
 338
 339 #endif // _SG_PATH_HXX
 340
 341