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