
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 }