HelpSource/Classes/File.schelp

   1 class:: File
   2 summary:: A class for reading and writing files
   3 related:: Classes/FileReader
   4 categories:: Files
   5
   6 description::
   7 A class for reading and writing files. Not sound files.
   8
   9 ClassMethods::
  10
  11 private::prGetcwd, prType
  12
  13 method::new
  14 Create a File instance and open the file. If the open fails, link::Classes/UnixFILE#-isOpen#isOpen:: will return false.
  15
  16 argument::pathName
  17 a link::Classes/String:: containing the path name of the file to open.
  18
  19 argument::mode
  20 a link::Classes/String:: indicating one of the following modes:
  21 definitionList::
  22 ## "r" || Opens a file for reading. The file must exist.
  23 ## "w" || Creates an empty file for writing. If a file with the same name already exists its content is erased and thefile is treated as a new empty file.
  24 ## "a" || Appends to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
  25 ## "rb", "wb", "ab" || same as above, but data is binary
  26 ## "r+" || Opens a file for update both reading and writing. The file must exist.
  27 ## "w+" || Creates an empty file for both reading and writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
  28 ## "a+" || Opens a file for reading and appending. All writing operations are performed at the end of the file, protecting the previous content to be overwritten. You can reposition the internal pointer using the seek method to anywhere in the file for reading, but writing operations will move it back to the end of file. The file is created if it does not exist.
  29 ## "rb+", wb+", "ab+" || same as above, but data is binary
  30 ::
  31
  32 method::open
  33 same as link::#*new::, but a more intuitive name.
  34
  35 method::getcwd
  36 POSIX standard 'get current working directory'.
  37 code::
  38 // example;
  39 File.getcwd;
  40 ::
  41
  42 method::use
  43 open the file, evaluate the function with the file and close it.
  44
  45 subsection:: Filesystem utilities
  46
  47 method::exists
  48 answers if a file exists at that path.
  49 note::
  50 Some filesystems, like the one used by OSX, are case insensitive.
  51 On such systems, this method will return true for "fOo" even if the file is actually named "Foo".
  52 For a workaround, see link::#*existsCaseSensitive:: below.
  53 ::
  54 returns:: a link::Classes/Boolean::
  55
  56 method::existsCaseSensitive
  57 Like link::#*exists:: but ensure case sensitivity emphasis:: of the last path component :: on case insensitive filesystems. On case sensitive systems, it falls back to using code::exists::.
  58
  59 note::
  60 This is slower than the normal code::exists:: method, so use it only when really needed.
  61 ::
  62
  63 method::systemIsCaseSensitive
  64 answers if the filesystem is case sensitive or not.
  65
  66 method::mkdir
  67 create directory at path, including any missing parent directories.
  68
  69 method::delete
  70 deletes the file at that path. Use only for good, never for evil.
  71
  72 method::realpath
  73 follow symbolic links (and aliases on OSX) and any parent directory references (like "..") and return the true absolute path.
  74 returns:: a link::Classes/String:: or code::nil:: if path did not exist.
  75
  76 method::copy
  77 copy file, symlink or directory. this method will fail if pathNameTo already exists.
  78
  79 symlinks are copied as symlinks (re-created).
  80
  81 method::type
  82 get file type as one of code::\error, \not_found, \regular, \directory, \symlink, \block, \character, \fifo, \socket, \unknown::
  83 returns:: a link::Classes/Symbol::
  84
  85 method::fileSize
  86 get size of file in bytes.
  87 returns:: an link::Classes/Integer::
  88
  89 method::mtime
  90 get last modification time in seconds since the Epoch.
  91 returns:: an link::Classes/Integer::
  92
  93
  94 InstanceMethods::
  95
  96 private::prOpen, prClose
  97
  98 method::open
  99 Open the file. Files are automatically opened upon creation, so this call is only necessary if you are closing and opening the same file object repeatedly.
 100 note::
 101 it is possible when saving files with a standard file dialog to elect to "hide the extension" and save it as RTF. When opening the file you must specify the real filename: "filename.rtf", even though you can't see in file load dialogs or in the Finder.
 102 ::
 103
 104 method::close
 105 Close the file.
 106
 107 method::readAllString
 108 Reads the entire file as a link::Classes/String::.
 109
 110 method::readAllStringRTF
 111 Reads the entire file as a link::Classes/String::, stripping RTF formatting.
 112
 113 method::seek
 114 moves the read/write pointer to a given location in the file, where offset is location given in bytes, and origin is the reference of the offset:
 115 definitionList::
 116 ## 0 || offset is from the beginning of the file
 117 ## 1 || offset is relative to the current position in the file
 118 ## 2 || offset is from the end of the file
 119 ::
 120
 121 method::pos
 122 sets or returns the current position in the file (in bytes).
 123 when used as a setter, this method is a shortcut for seek(0, value). so setting the pos moves the current file position to a given location from the beginning of the file. the value is clipped so that it lies between 0 inclusively and the file length exclusively.
 124
 125 method::length
 126 returns the current file size in bytes.
 127
 128 Examples::
 129
 130 code::
 131 // write some string to a file:
 132 (
 133 var f, g;
 134 f = File("test","w");
 135 f.write("Does this work?\n is this thing on ?\n");
 136 f.close;
 137 )
 138
 139 // read it again:
 140 (
 141 g = File("test","r");
 142 g.readAllString.postln;
 143 g.close;
 144 )
 145
 146 // try the above with File.use:
 147
 148 File.use("test", "w", { |f| f.write("Doesn't this work?\n is this thing really on ?\n"); });
 149 File.use("test", "r", { |f| f.readAllString.postln });
 150
 151
 152 // more file writing/reading examples:
 153 (
 154 var h, k;
 155 h = File("test2", "wb");
 156 h.inspect;
 157 h.write( FloatArray[1.1, 2.2, 3.3, pi, 3.sqrt] );
 158 h.close;
 159
 160 k = File("test2", "rb");
 161 (k.length div: 4).do({ k.getFloat.postln; });
 162 k.close;
 163 )
 164
 165
 166 (
 167 var f, g;
 168 f = File("test3","w");
 169 100.do({ f.putChar([$a, $b, $c, $d, $e, $\n].choose); });
 170 f.close;
 171
 172 g = File("test3","r");
 173 g.readAllString.postln;
 174 g.close;
 175
 176 g = File("test3","r");
 177 g.getLine(1024).postln;
 178 "*".postln;
 179 g.getLine(1024).postln;
 180 "**".postln;
 181 g.getLine(1024).postln;
 182 "***".postln;
 183 g.getLine(1024).postln;
 184 "****".postln;
 185 g.close;
 186 )
 187
 188 (
 189 //var f, g;
 190 f = File("test3","wb");
 191 f.inspect;
 192 100.do({ f.putFloat(1.0.rand); });
 193
 194 f.inspect;
 195 f.close;
 196
 197 g = File("test3","rb");
 198 100.do({
 199         g.getFloat.postln;
 200 });
 201 g.inspect;
 202 g.close;
 203 )
 204
 205 (
 206 //var f, g;
 207 f = File("test3","r");
 208 f.inspect;
 209 f.getLine(1024).postln;
 210 f.close;
 211 )
 212 ::