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
  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::exists
  36 answers if a file exists at that path.
  37
  38 method::delete
  39 deletes the file at that path. Use only for good, never for evil.
  40
  41 method::getcwd
  42 POSIX standard 'get current working directory'.
  43 code::
  44 // example;
  45 File.getcwd;
  46 ::
  47
  48 method::use
  49 open the file, evaluate the function with the file and close it.
  50
  51 InstanceMethods::
  52
  53 private::prOpen, prClose
  54
  55 method::open
  56 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.
  57 note::
  58 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.
  59 ::
  60
  61 method::close
  62 Close the file.
  63
  64 method::readAllString
  65 Reads the entire file as a link::Classes/String::.
  66
  67 method::readAllStringRTF
  68 Reads the entire file as a link::Classes/String::, stripping RTF formatting.
  69
  70 method::seek
  71 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:
  72 definitionList::
  73 ## 0 || offset is from the beginning of the file
  74 ## 1 || offset is relative to the current position in the file
  75 ## 2 || offset is from the end of the file
  76 ::
  77
  78 method::pos
  79 sets or returns the current position in the file (in bytes).
  80 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.
  81
  82 method::length
  83 returns the current file size in bytes.
  84
  85 Examples::
  86
  87 code::
  88 // write some string to a file:
  89 (
  90 var f, g;
  91 f = File("test","w");
  92 f.write("Does this work?\n is this thing on ?\n");
  93 f.close;
  94 )
  95
  96 // read it again:
  97 (
  98 g = File("test","r");
  99 g.readAllString.postln;
 100 g.close;
 101 )
 102
 103 // try the above with File.use:
 104
 105 File.use("test", "w", { |f| f.write("Doesn't this work?\n is this thing really on ?\n"); });
 106 File.use("test", "r", { |f| f.readAllString.postln });
 107
 108
 109 // more file writing/reading examples:
 110 (
 111 var h, k;
 112 h = File("test2", "wb");
 113 h.inspect;
 114 h.write( FloatArray[1.1, 2.2, 3.3, pi, 3.sqrt] );
 115 h.close;
 116
 117 k = File("test2", "rb");
 118 (k.length div: 4).do({ k.getFloat.postln; });
 119 k.close;
 120 )
 121
 122
 123 (
 124 var f, g;
 125 f = File("test3","w");
 126 100.do({ f.putChar([$a, $b, $c, $d, $e, $\n].choose); });
 127 f.close;
 128
 129 g = File("test3","r");
 130 g.readAllString.postln;
 131 g.close;
 132
 133 g = File("test3","r");
 134 g.getLine(1024).postln;
 135 "*".postln;
 136 g.getLine(1024).postln;
 137 "**".postln;
 138 g.getLine(1024).postln;
 139 "***".postln;
 140 g.getLine(1024).postln;
 141 "****".postln;
 142 g.close;
 143 )
 144
 145 (
 146 //var f, g;
 147 f = File("test3","wb");
 148 f.inspect;
 149 100.do({ f.putFloat(1.0.rand); });
 150
 151 f.inspect;
 152 f.close;
 153
 154 g = File("test3","rb");
 155 100.do({
 156         g.getFloat.postln;
 157 });
 158 g.inspect;
 159 g.close;
 160 )
 161
 162 (
 163 //var f, g;
 164 f = File("test3","r");
 165 f.inspect;
 166 f.getLine(1024).postln;
 167 f.close;
 168 )
 169 ::