File | SuperCollider 3.12.2 Help

Source: File.sc

Subclasses: AtsFile

Description

A class for reading and writing files. Not sound files.

Class Methods

File.new(pathName, mode)

Create a File instance and open the file. If the open fails, isOpen will return false.

Arguments:

pathName

A String containing the path name of the file to open.

mode

a String indicating one of the following modes:

"r": Opens a file for reading. The file must exist.
"w": Creates an empty file for writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
"a": Appends to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
"rb", "wb", "ab": same as above, but data is binary
"r+": Opens a file for update both reading and writing. The file must exist.
"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.
"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.
"rb+", "wb+", "ab+": same as above, but data is binary

File.open(pathName, mode)

Same as *new, but a more intuitive name.

File.getcwd

POSIX standard 'get current working directory'.// example; File.getcwd;

File.use(pathName, mode, function)

Open the file, evaluate the function with the file as argument, and close it again. If the process fails, close the file and throw an error.

File.readAllString(pathName)

Open the file at the given path, call -readAllString, and return the string. Whether the process succeeds or fails, the file will always be closed.// write a file File.use("~/test.txt".standardizePath, "w", { |f| f.write("The green fox fell into the blue lake") }); // read it again File.readAllString("~/test.txt".standardizePath);

File.readAllSignal(pathName)

Open the file at the given path, call -readAllSignal, and return the signal. Whether the process succeeds or fails, the file will always be closed.

File.readAllStringHTML(pathName)

Open the file at the given path, call -readAllStringHTML, and return the string. Whether the process succeeds or fails, the file will always be closed.

File.readAllStringRTF(pathName)

Open the file at the given path, call -readAllStringRTF, and return the string. Whether the process succeeds or fails, the file will always be closed.

Filesystem utilities

File.exists(pathName)

Answers if a file exists at that path.

NOTE: Some filesystems, like the one used by macOS, are case insensitive. On such systems, this method will return true for "fOo" even if the file is actually named "Foo". For a workaround, see *existsCaseSensitive below.

Returns:

a Boolean

File.existsCaseSensitive(pathName)

Like *exists but ensure case sensitivity of the last path component on case insensitive filesystems. On case sensitive systems, it falls back to using exists.

NOTE: This is slower than the normal exists method, so use it only when really needed.

File.systemIsCaseSensitive

Answers if the filesystem is case sensitive or not.

File.mkdir(pathName)

Create directory at path, including any missing parent directories.

Returns:

a Boolean, as follows:

true -- A new directory was created at path.
false -- A directory already existed at path; a new one was not created.

File.delete(pathName)

Deletes the file at that path. Use only for good, never for evil.

Returns:

a Boolean, as follows:

true -- You can assume that the path no longer exists. (Either it existed and was deleted, or it didn't exist and it still doesn't exist.)
false -- The file could not be deleted (probably a permissions error). Your code should assume that the path still exists.

File.deleteAll(pathName)

Deletes the file and all children at that path. Use only for good, never for evil.

Returns:

a Boolean, as follows:

true -- At least one file was deleted.
false -- No files were deleted.

If deletion fails, a PrimitiveFailedError object will be thrown.

File.realpath(pathName)

Follow symbolic links (and aliases on macOS) and any parent directory references (like "..") and return the true absolute path.

Returns:

a String or nil if path did not exist.

File.copy(pathNameFrom, pathNameTo)

Copy file, symlink or directory. this method will fail if pathNameTo already exists.

Symlinks are copied as symlinks (re-created).

File.type(pathName)

Get file type as one of \error, \not_found, \regular, \directory, \symlink, \block, \character, \fifo, \socket, \unknown

Returns:

a Symbol

File.fileSize(pathName)

Get size of file in bytes.

Returns:

an Integer

File.mtime(pathName)

Get last modification time in seconds since the Epoch.

Returns:

an Integer

Error handling in filesystem utilities

If one of the above filesystem primitives fails, in most cases, a PrimitiveFailedError object will be thrown:File.mkdir("/usr/oh-no-you-cant");

ERROR: Primitive '_FileMkDir' failed.
caught exception 'boost::filesystem::create_directory: Permission denied: "/usr/oh-no-you-cant"' in primitive in method Meta_File:mkdir

The methods Function: -try and Function: -protect can detect and handle these errors. See Understanding errors for details.

Currently, File: *copy, File: *fileSize, File: *mkdir, File: *mtime, and File: *type throw errors upon failure. (File: *delete does not throw an error, but instead returns a Boolean.)

Inherited class methods

Instance Methods

.open(pathName, mode)

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.

NOTE: 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.

.close

Close the file.

.readAllString

Reads the entire file as a String.

.readAllStringHTML

Reads the entire file as a String, stripping HTML tags.

.readAllStringRTF

Reads the entire file as a String, stripping RTF formatting.

.readAllSignal

Reads the entire file as a Signal, where every chunk of four bytes is interpreted as a 32-bit floating point sample.

.seek(offset: 0, origin: 0)

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:

0: offset is from the beginning of the file
1: offset is relative to the current position in the file
2: offset is from the end of the file

.pos

.pos = toPos

Sets or returns the current position in the file (in bytes). 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.

.length

Returns the current file size in bytes.

Inherited instance methods

Examples

// write some string to a file:
(
var f, g;
f = File("~/test.txt".standardizePath,"w");
f.write("Does this work?\n is this thing on ?\n");
f.close;
)

// read it again:
(
g = File("~/test.txt".standardizePath,"r");
g.readAllString.postln;
g.close;
)

// try the above with File.use:

File.use("~/test.txt".standardizePath, "w", { |f| f.write("Doesn't this work?\n is this thing really on ?\n"); });
File.use("~/test.txt".standardizePath, "r", { |f| f.readAllString.postln });

// more file writing/reading examples:
(
var h, k;
h = File("~/test.dat".standardizePath, "wb");
h.inspect;
h.write( FloatArray[1.1, 2.2, 3.3, pi, 3.sqrt] );
h.close;

k = File("~/test.dat".standardizePath, "rb");
(k.length div: 4).do({ k.getFloat.postln; });
k.close;
)

(
var f, g;
f = File("~/test.txt".standardizePath,"w");
100.do({ f.putChar([$a, $b, $c, $d, $e, $\n].choose); });
f.close;

g = File("~/test.txt".standardizePath,"r");
g.readAllString.postln;
g.close;

g = File("~/test.txt".standardizePath,"r");
g.getLine(1024).postln;
"*".postln;
g.getLine(1024).postln;
"**".postln;
g.getLine(1024).postln;
"***".postln;
g.getLine(1024).postln;
"****".postln;
g.close;
)

(
//var f, g;
f = File("~/test.dat".standardizePath,"wb");
f.inspect;
100.do({ f.putFloat(1.0.rand); });

f.inspect;
f.close;

g = File("~/test.dat".standardizePath,"rb");
100.do({
    g.getFloat.postln;
});
g.inspect;
g.close;
)

(
//var f, g;
f = File("~/test.dat".standardizePath,"r");
f.inspect;
f.close;
)

helpfile source: /usr/local/share/SuperCollider/HelpSource/Classes/File.schelp
link::Classes/File::

File : UnixFILE : IOStream : Stream : AbstractFunction : Object

File.new(pathName, mode)

Arguments:

File.open(pathName, mode)

File.getcwd

File.use(pathName, mode, function)

File.readAllString(pathName)

File.readAllSignal(pathName)

File.readAllStringHTML(pathName)

File.readAllStringRTF(pathName)

File.exists(pathName)

Returns:

File.existsCaseSensitive(pathName)

File.systemIsCaseSensitive

File.mkdir(pathName)

Returns:

File.delete(pathName)

Returns:

File.deleteAll(pathName)

Returns:

File.realpath(pathName)

Returns:

File.copy(pathNameFrom, pathNameTo)

File.type(pathName)

Returns:

File.fileSize(pathName)

Returns:

File.mtime(pathName)

Returns:

.open(pathName, mode)

.close

.readAllString

.readAllStringHTML

.readAllStringRTF

.readAllSignal

.seek(offset: 0, origin: 0)

.pos

.pos = toPos

.length