These Wiki pages will be used to coordinate development of the ChucK I/O API specification. The ChucK I/O API will consist of a main
IO class with methods universal to all types of I/O, and three subclasses:
Your comments, suggestions, and criticisms are much appreciated. The quality of the I/O API specification should primarily be evaluated on the following three criteria:
- Completeness: you can accomplish any I/O task you might want to perform in ChucK (or at least most of them).
- Elegance: ChucK I/O code is intuitive and easy to write.
- Feasibility: it is not too difficult to actually implement all of the components of this API without interfering with existing ChucK code and conventions.
ChucK I/O Conventions
I/O operations in ChucK are asynchronous by default. Calling an I/O function places the desired I/O operation in a queue, so that I/O does not interfere with real-time audio. This means that after some I/O function has been executed, you cannot be sure at any subsequent line of code that the operation has actually finished unless you do one of the following:
- Call the
finishfunction, which waits for all queued I/O operations to finish without advancing time.
- Advance time until the I/O queue is cleared, by writing something like
myIO => now;.
This class cannot be instantiated. In ChucK code, its main purpose is to enable functions to accept and read from any kind of I/O class without regard to the type of I/O that is taking place. This class deliberately includes no "open" methods to start I/O, since this differs greatly depending on whether you are opening a file, a network socket, or a pipe.
fun void close()
- Closes the I/O stream in the appropriate way (close file, close socket, etc.).
fun void finish()
- Wait for queued I/O operations to finish without advancing time.
fun int isIdle()
- Returns true if there are no queued I/O operations, false otherwise.
fun string read(int length)
- Reads up to the specified number of bytes into a string.
fun string readLine()
- Reads everything up to and including the next newline character into a string.
fun int readInt([int flags])
- Reads in one integer. The flags can optionally be used to specify the bit length of the integer to be read in when in binary mode (default is IO.READ_INT32). The value returned will always be a 32-bit signed ChucK integer, regardless of the number of bits read from the file.
fun int readFloat()
- Reads in one float.
fun int eof()
- Returns true if end of file has been reached (or the network connection has been closed), or false otherwise.
fun void write(string s)
- Writes out the specified string.
fun void writef(string s, ...)
- Writes out the specified string, generated using printf-style conversion specifications.
fun void write(int i)
- Writes out the specified int.
fun void write(float f)
- Writes out the specified float.
Chucking an IO object to now (for example, as in
myIO => now;) causes time to be advanced until all queued I/O operations for that object have completed.
The ChucK and un-ChucK operators can also be used to read and write from a file in "Pac-Man" fashion.
For example, to write a series of variables to an IO object, you could write:
This would have the same effect as:myIO =< myInt1 =< myInt2 =< myFloat =< myStr;
myIO.write(myInt1); myIO.write(myInt2); myIO.write(myFloat); myIO.write(myStr);
To read a series of variables from an IO object, you could write:
This would have the same effect as:myIO => myFloat => myInt1 => myStr => myInt2
myIO.readFloat() => myFloat; myIO.readInt() => myInt1; myIO.readLine() => myStr; myIO.readInt() => myInt2;
- These flags can optionally be passed to the
readIntfunction when in binary mode to specify the bit length of the integer to be read.
TODO: write example code for this class.