logo

abstract class

sys::File

sys::Obj
  sys::Resource
    sys::File
   1  //
   2  // Copyright (c) 2006, Brian Frank and Andy Frank
   3  // Licensed under the Academic Free License version 3.0
   4  //
   5  // History:
   6  //   26 Mar 06  Brian Frank  Creation
   7  //
   8  
   9  **
  10  ** File is used to represent a Uri path to a file or directory.
  11  **
  12  abstract class File : Resource
  13  {
  14  
  15  //////////////////////////////////////////////////////////////////////////
  16  // Constructor
  17  //////////////////////////////////////////////////////////////////////////
  18  
  19    **
  20    ** Make a File for the Uri which represents a file on the local
  21    ** file system.  If creating a Uri to a directory, then the Uri
  22    ** must end in a trailing "/" slash - Uri.isDir() must return true.
  23    ** If the file exists and it doesn't match Uri.isDir() then IOErr
  24    ** is thrown.  If the file doesn't exist, then it is assumed to
  25    ** to a directory based on Uri.isDir().  If the Uri has a relative
  26    ** path, then it is assumed to be relative to the current working
  27    ** directory.
  28    **
  29    static File make(Uri uri)
  30  
  31    **
  32    ** Make a File for the specified operating system specific path
  33    ** on the local file system.
  34    **
  35    static File os(Str osPath)
  36  
  37    **
  38    ** Create a temporary file which is guaranteed to be a new, empty
  39    ** file with a unique name.  The file name will be generated using
  40    ** the specified prefix and suffix.  If dir is non-null then it is used
  41    ** as the file's parent directory, otherwise the system's default
  42    ** temporary directory is used.  If dir is specified it must be a
  43    ** directory on the local file system.  See `deleteOnExit` if you wish
  44    ** to have the file automatically deleted on exit.  Throw IOErr on error.
  45    **
  46    ** Examples:
  47    **   File.createTemp("x", ".txt") -> `/tmp/x67392.txt`
  48    **   File.createTemp.deleteOnExit -> `/tmp/fan5284.tmp`
  49    **
  50    static File createTemp(Str prefix := "fan", Str suffix := ".tmp", File dir := null)
  51  
  52    **
  53    ** Private constructor
  54    **
  55    private new init(Uri uri)
  56  
  57  //////////////////////////////////////////////////////////////////////////
  58  // Identity
  59  //////////////////////////////////////////////////////////////////////////
  60  
  61    **
  62    ** File equality is based on the un-normalized Uri used to create the File.
  63    **
  64    override Bool equals(Obj that)
  65  
  66    **
  67    ** Return uri.hash.
  68    **
  69    override Int hash()
  70  
  71    **
  72    ** Return uri.toStr.
  73    **
  74    override Str toStr()
  75  
  76  //////////////////////////////////////////////////////////////////////////
  77  // Access
  78  //////////////////////////////////////////////////////////////////////////
  79  
  80    **
  81    ** Return the size of the file in bytes otherwise null if a
  82    ** directory or unknown.
  83    **
  84    abstract Int size()
  85  
  86    **
  87    ** Get or set the time the file was last modified.
  88    ** Modify time is null if unknown.
  89    **
  90    abstract DateTime modified
  91  
  92    **
  93    ** Get this File as an operating system specific path on
  94    ** the local system.  If this File doesn't represent a
  95    ** path on the local file system then return null.
  96    **
  97    abstract Str osPath()
  98  
  99    **
 100    ** Get the parent directory of this file or null.
 101    ** Also see Uri.parent().
 102    **
 103    abstract File parent()
 104  
 105    **
 106    ** List the files contained by this directory.  If the directory is
 107    ** empty or this file doesn't represent a directory, then return
 108    ** an empty list.
 109    **
 110    override abstract File[] list()
 111  
 112    **
 113    ** Normalize this file path to its canonical representation.
 114    **
 115    abstract File normalize()
 116  
 117    **
 118    ** Make a new File instance by joining this file's Uri
 119    ** together with the specified path.
 120    **
 121    ** Example:
 122    **   File.make(`a/b/`) + `c` -> File.make(`a/b/c`)
 123    **   File.make(`a/b`) + `c` -> File.make(`a/c`)
 124    **
 125    abstract File plus(Uri path)
 126  
 127  //////////////////////////////////////////////////////////////////////////
 128  // Management
 129  //////////////////////////////////////////////////////////////////////////
 130  
 131    **
 132    ** Create a file or directory represented by this Uri.  If isDir() is
 133    ** false then create an empty file, or if the file already exists
 134    ** overwrite it to empty.  If isDir() is true then create a directory,
 135    ** or if the directory already exists do nothing.  This method will
 136    ** automatically create any parent directories.  Throw IOErr on error.
 137    ** Return this.
 138    **
 139    override abstract File create()
 140  
 141    **
 142    ** Delete this file.  If this file represents a directory, then
 143    ** recursively delete it.  If the file does not exist, then no
 144    ** action is taken.  Throw IOErr on error.
 145    **
 146    override abstract Void delete()
 147  
 148    **
 149    ** Request that the file or directory represented by this File
 150    ** be deleted when the virtual machine exits.  Long running applications
 151    ** should use this method will care since each file marked to delete will
 152    ** consume resources.  Throw IOErr on error.  Return this.
 153    **
 154    abstract File deleteOnExit()
 155  
 156  //////////////////////////////////////////////////////////////////////////
 157  // IO
 158  //////////////////////////////////////////////////////////////////////////
 159  
 160    **
 161    ** Open a new buffered InStream used to read from this file.  A
 162    ** bufferSize of null or zero will return an unbuffered input stream.
 163    ** Throw IOErr on error.
 164    **
 165    abstract InStream in(Int bufferSize := 4096)
 166  
 167    **
 168    ** Open a new buffered OutStream used to write to this file.  If append is
 169    ** true, then we open the file to append to the end, otherwise it is
 170    ** opened as an empty file.  A bufferSize of null or zero will return an
 171    ** unbuffered input stream.  Throw IOErr on error.
 172    **
 173    abstract OutStream out(Bool append := false, Int bufferSize := 4096)
 174  
 175    **
 176    ** Convenience for [in.readAllBuf]`File.readAllBuf`.
 177    ** The input stream is guaranteed to be closed.
 178    **
 179    Buf readAllBuf()
 180  
 181    **
 182    ** Convenience for [in.readAllLines]`File.readAllLines`.
 183    ** The input stream is guaranteed to be closed.
 184    **
 185    Str[] readAllLines()
 186  
 187    **
 188    ** Convenience for [in.eachLine]`File.eachLine`.
 189    ** The input stream is guaranteed to be closed.
 190    **
 191    Void eachLine(|Str line| f)
 192  
 193    **
 194    ** Convenience for [in.readAllStr]`File.readAllStr`.
 195    ** The input stream is guaranteed to be closed.
 196    **
 197    Str readAllStr(Bool normalizeNewlines := true)
 198  
 199    **
 200    ** Convenience for [in.readProps()]`File.readProps`.
 201    ** The input stream is guaranteed to be closed.
 202    **
 203    Str:Str readProps()
 204  
 205    **
 206    ** Convenience for [out.writeProps()]`File.writeProps`.
 207    ** The output stream is guaranteed to be closed.
 208    **
 209    Void writeProps(Str:Str props)
 210  
 211    **
 212    ** Convenience for [in.readObj]`InStream.readObj`
 213    ** The input stream is guaranteed to be closed.
 214    **
 215    Obj readObj(Str:Obj options := null)
 216  
 217    **
 218    ** Convenience for [out.writeObj]`OutStream.writeObj`
 219    ** The output stream is guaranteed to be closed.
 220    **
 221    Void writeObj(Obj obj, Str:Obj options := null)
 222  
 223    // TODO:
 224    //  - random access as Buf
 225    //  - copy, move, rename, etc
 226  
 227    **
 228    ** Return the platform's file path separator - typically a slash.
 229    **
 230    static const Str sep
 231  
 232  }
 233  
 234  **************************************************************************
 235  ** LocalFile
 236  **************************************************************************
 237  
 238  internal class LocalFile : File
 239  {
 240    private new init()
 241    override Int size()
 242    override DateTime modified
 243    override Str osPath()
 244    override File parent()
 245    override File[] list()
 246    override File normalize()
 247    override File plus(Uri uri)
 248    override File create()
 249    override Void delete()
 250    override File deleteOnExit()
 251    override InStream in(Int bufferSize := 4096)
 252    override OutStream out(Bool append := false, Int bufferSize := 4096)
 253  }
 254  
 255  **************************************************************************
 256  ** ZipEntryFile
 257  **************************************************************************
 258  
 259  internal class ZipEntryFile : File
 260  {
 261    private new init()
 262    override Int size()
 263    override DateTime modified
 264    override Str osPath()
 265    override File parent()
 266    override File[] list()
 267    override File normalize()
 268    override File plus(Uri uri)
 269    override File create()
 270    override Void delete()
 271    override File deleteOnExit()
 272    override InStream in(Int bufferSize := 4096)
 273    override OutStream out(Bool append := false, Int bufferSize := 4096)
 274  }