nucleus/library/filesystem/filename.h

   1 #ifndef FILENAME_CLASS
   2 #define FILENAME_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : filename                                                          *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1993-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19 #include <basis/byte_array.h>
  20 #include <basis/contracts.h>
  21 #include <structures/string_array.h>
  22
  23 // forward declarations.
  24 class status_info;
  25
  26 //hmmm: this doesn't really belong here, does it...
  27 // define useful constant for filesystem path length.
  28 #ifndef MAX_ABS_PATH
  29   #ifdef __WIN32__
  30     #define MAX_ABS_PATH MAX_PATH
  31   #else
  32     #define MAX_ABS_PATH PATH_MAX
  33   #endif
  34 /*
  35   #ifdef __WIN32__
  36   // winsock support...
  37 //  #undef FD_SETSIZE
  38 //  #define FD_SETSIZE 1000
  39     // if you don't set this, you can only select on a default of 64 sockets.
  40   #include <winsock2.h>
  41     #include <windows.h>
  42     #define MAX_ABS_PATH MAX_PATH
  43   #else
  44     #ifdef __APPLE__
  45       #include <sys/syslimits.h>
  46     #else
  47       #include <limits.h>
  48     #endif
  49     #define MAX_ABS_PATH PATH_MAX
  50   #endif
  51 */
  52 #endif
  53
  54 namespace filesystem {
  55
  56 //! Provides operations commonly needed on file names.
  57
  58 class filename : public basis::astring, public virtual basis::packable
  59 {
  60 public:
  61   filename();  //!< blank constructor.
  62   filename(const basis::astring &name);
  63     //!< creates a filename from any part of a full pathname, if possible.
  64     /*!< if the name contains quotes, they are stripped out. */
  65   filename(const basis::astring &directory, const basis::astring &name_of_file);
  66     //!< constructs a filename from a "directory" and the "name_of_file".
  67     /*!< the "name_of_file" can itself be a directory. */
  68   filename(const filename &to_copy);  //!< copy constructor.
  69
  70   DEFINE_CLASS_NAME("filename");
  71
  72   virtual ~filename();
  73
  74   bool good() const;
  75     //!< returns true if the filename seems to be valid.
  76     /*!< this means that not only was the pathname parsed and found valid,
  77     but the file actually exists. */
  78
  79   void reset(const basis::astring &name);
  80     //!< changes the file name held by the object.
  81
  82   const basis::astring &raw() const;
  83     //!< returns the astring that we're holding onto for the path.
  84   basis::astring &raw();
  85     //!< accesses the astring that we're holding onto for the path.
  86     /*!< important note: if you change the string with this non-const raw()
  87     method, you MUST call canonicalize() on it again afterwards. */
  88
  89   filename &operator = (const filename &to_copy);
  90     //!< provides assignment for this object, plus a simple string.
  91   filename &operator = (const basis::astring &to_copy);
  92     //!< provides assignment for this object, plus a simple string.
  93     /*!< the latter version invokes canonicalize to clean the string up. */
  94
  95   void canonicalize();
  96     //!< cleans up the filename as needed for the current operating system.
  97     /*!< reforms the name by replacing any alternate directory separators with
  98     the operating system's preferred character. */
  99
 100   bool exists() const;
 101     //!< returns true if the file exists.
 102
 103   bool unlink() const;
 104     //!< actually removes the file, if possible.
 105     /*!< if the file was successfully deleted, then true is returned. */
 106
 107   filename parent() const;
 108     //!< returns the parent filename for this one.
 109
 110   basis::astring pop();
 111     //!< removes the deepest component of the pathname.
 112     /*!< the component might be a file or directory name, but popping beyond
 113     the top-level directory will not succeed.  the returned string contains
 114     the component that was removed.  it will be a blank string if nothing
 115     could be popped. */
 116
 117   void push(const basis::astring &to_push);
 118     //!< pushes a new filename onto the current pathname.
 119     /*!< this only makes sense as a real pathname if this is currently a
 120     directory name and the component "to_push" is a child of that directory
 121     (or one intends to create that component as a child).  this is the
 122     opposite of pop. */
 123
 124   filename basename() const;
 125     //!< returns the base of the filename; no directory.
 126   filename dirname() const;
 127     //!< returns the directory for the filename.
 128     /*!< if no directory name can be found in the filename, then "." is
 129     returned. */
 130   basis::astring dirname(bool add_slash) const;
 131     //!< returns the directory for the filename and optionally adds a slash.
 132     /*!< if "add_slash" is true, then the default directory separator will be
 133     present on the end of the string. */
 134   bool had_directory() const { return _had_directory; }
 135     //!< returns true if the name that we were given had a non-empty directory.
 136     /*!< this allows one to distinguish between a file with the current
 137     directory (.) attached and a file with no directory specified. */
 138
 139   char drive(bool interact_with_fs = false) const;
 140     //!< returns the drive letter for the file, without the colon.
 141     /*!< this only makes sense for a fully qualified MS-DOS style name.  if no
 142     drive letter is found, then '\0' is returned.  if "interact_with_fs" is
 143     true, then the file system will be checked for the actual drive if no
 144     drive letter was found in the contents. */
 145
 146   basis::astring extension() const;
 147     //!< returns the extension for the file, if one is present.
 148
 149   basis::astring rootname() const;
 150     //!< returns the root part of the basename without an extension.
 151
 152   // status functions return true if the characteristic embodied in
 153   // the name is also true.
 154
 155   bool is_directory() const;
 156   bool is_writable() const;
 157   bool is_readable() const;
 158   bool is_executable() const;
 159
 160   // is_normal makes sure that the file or directory is not a named pipe or other
 161   // special type of file.  symbolic links are considered normal.
 162   bool is_normal() const;
 163
 164   enum write_modes {
 165     ALLOW_NEITHER = 0x0,
 166     ALLOW_READ = 0x1, ALLOW_WRITE = 0x2,
 167     ALLOW_BOTH = ALLOW_READ | ALLOW_WRITE
 168   };
 169
 170   enum ownership_modes {
 171     NO_RIGHTS = 0x0,
 172     USER_RIGHTS = 0x1, GROUP_RIGHTS = 0x2, OTHER_RIGHTS = 0x4,
 173     ALL_RIGHTS = USER_RIGHTS | GROUP_RIGHTS | OTHER_RIGHTS
 174   };
 175
 176   bool chmod(int write_mode, int owner_mode) const;
 177     //!< changes the access rights on the file.
 178
 179   //! the default separator for directories per operating system.
 180   /*! the PC uses the backward slash to separate file and directory names from
 181   each other, while Unix uses the forward slash. */
 182   enum directory_separator { pc_separator = '\\', unix_separator = '/' };
 183
 184   static bool separator(char is_it);
 185     //!< returns true if the character "is_it" in question is a separator.
 186
 187   static basis::astring default_separator();
 188     //!< returns the default separator character for this OS.
 189
 190   static bool legal_character(char to_check);
 191     //!< returns true if "to_check" is a valid character in a filename.
 192     /*!< this does not consider separator characters; it only looks at the
 193     the name components.  also, it is appropriate for the union of the
 194     operating systems we support. */
 195
 196   static void detooth_filename(basis::astring &to_clean, char replacement = '_');
 197     //!< takes any known illegal file system characters out of "to_clean".
 198     /*!< this prepares "to_clean" for use as a component in a larger filename
 199     by ensuring that the file system will not reject the name (as long as a
 200     suitable directory path is prepended to the name and permissions allow
 201     the file to be created or accessed).  the "replacement" is used as the
 202     character that is substituted instead of illegal characters. */
 203
 204   void separate(bool &rooted, structures::string_array &pieces) const;
 205     //!< breaks the filename into its component parts.
 206     /*!< this returns an array containing the component names for the path in
 207     this filename object.  if the "rooted" flag is set to true, then the path
 208     was absolute (i.e. started at '/' in unix.  this notion is not needed for
 209     dos/windoze, as the first component will be something like 'a:'). */
 210
 211   void join(bool rooted, const structures::string_array &pieces);
 212     //!< undoes a separate() operation to get the filename back.
 213     /*!< "this" is set to a filename made from each of the "pieces".  if there
 214     are any directory separators inside the pieces themselves, then they will
 215     be removed by canonicalize().  if separate() said the path was rooted,
 216     then join needs to be told that. */
 217
 218   // these implement the packing functionality.
 219   virtual void pack(basis::byte_array &packed_form) const;
 220   virtual bool unpack(basis::byte_array &packed_form);
 221   virtual int packed_size() const;
 222
 223   bool compare_prefix(const filename &to_compare, basis::astring &sequel);
 224     //!< examines "this" filename to see if it's a prefix of "to_compare".
 225     /*!< this returns true if all of "this" is the same as the first portion
 226     of "to_compare".  that is, if "this" is a prefix of "to_compare", then
 227     true is returned.  this will always fail if there are fewer components in
 228     "to_compare".  it will always succeed if the two filenames are identical.
 229     on success, the "sequel" is set to the portion of "to_compare" that's
 230     not included in this filename. */
 231
 232   bool compare_prefix(const filename &to_compare);
 233     //!< this simpler form doesn't bother with computing the sequel.
 234
 235   bool compare_suffix(const filename &to_compare, basis::astring &prequel);
 236     //!< compares the back end of a filename to this.
 237     /*!< this is similar to compare_prefix() but it checks to see if the
 238     back end of "this" filename is the same as "to_compare".  if "this" is
 239     longer than "to_compare", then failure occurs.  only if all of the bits
 240     in "this" are seen in the back of "to_compare" is true returned. */
 241
 242   bool compare_suffix(const filename &to_compare);
 243
 244   static basis::astring null_device();
 245     //!< returns the name for the black hole device that consumes all input, i.e. /dev/null.
 246
 247 private:
 248   bool _had_directory;  //!< true if _some_ directory was specified on init.
 249 ///  basis::astring *_contents;  //!< the full path is held here.
 250
 251   int find_last_separator(const basis::astring &look_at) const;
 252     //!< locates the last separator character in the filename.
 253
 254   bool get_info(status_info *to_fill) const;
 255     //!< returns information for the filename.
 256
 257   // helper functions do the real work for comparing.
 258   bool base_compare_prefix(const filename &to_compare, structures::string_array &first,
 259           structures::string_array &second);
 260   bool base_compare_suffix(const filename &to_compare, structures::string_array &first,
 261           structures::string_array &second);
 262 };
 263
 264 } //namespace.
 265
 266 #endif
 267