IO Library

The IO library provides basic file system operations and stream-based input and output.

All the functions in this library will throw an exception if an error occurs, unless otherwise noted.

io.stdin

An instance of the InputStream class bound to the standard input stream (the console).

io.stdout

An instance of the OutputStream class bound to the standard output stream (the console).

io.stderr

An instance of the OutputStream class bound to the standard error stream (on Windows, the console, but on other systems, it can be other things).

io.rename(path, newName)

Renames the given file with the new name.

io.remove(path)

Deletes the given file, permanently. This bypasses the operating system's "recycle bin" or "trash" folder, and completely removes the file. Use with care.

io.copy(src, dest)

Copies the file from src to dest.

io.size(path)

Returns the size of the given file in bytes. Note that since MiniD uses 32-bit signed integers, files larger than 2GB will have their sizes reported incorrectly.

io.exists(path)

Returns true if the given file or directory exists, and false otherwise. Does not throw any exceptions.

io.isFile(path)

Returns true if the given pathname refers to a file, and false otherwise. Does not throw any exceptions.

io.isDir(path)

Returns true if the given pathname refers to a directory, and false otherwise. Does not throw any exceptions.

io.currentDir()

Returns a string of the pathname of the current operating path. By default, this is usually where the host program was run from. Does not throw any exceptions.

io.changeDir(path)

Changes the current directory to the given pathname.

io.makeDir(path)

Creates a new directory with the given name.

io.removeDir(path)

Deletes a directory. This can only be used to delete empty directories.

io.listDirs(path [, filter])

Returns an array of all the directory names in the directory given by path. filter is an optional string argument which specifies a file pattern which listDirs uses to only return an array of the directory names which match the pattern.

io.listFiles(path [, filter])

Returns an array of all the file names in the directory given by path. filter is an optional string argument which specifies a file pattern which listFiles uses to only return an array of the file names which match the pattern.

FileMode

This is sort of an enumeration of constants which are used with the File function. Its values and their meanings are explained in the File function.

File(path [, mode])

This function returns an instance of the Stream class which is bound to a file on a permanent storage medium.

When you use this function, you give it a path and optionally a mode. By default, the mode is io.FileMode.In. This will attempt to open the file for reading. If the file doesn't exist, an exception will be thrown. A mode of io.FileMode.Out will open a file for writing. If the file does not exist, it is an error. If it does exist, the existing file will be opened, and the write cursor will be placed at the beginning of the file. The data can then be overwritten. If the mode is io.FileMode.New, any existing file will be deleted and a new, empty file will be created. You can't read or write to it unless you specify one of the other flags. If the mode is io.FileMode.Append, it is the same as io.FileMode.Out, except that the write cursor will start at the very end of the file instead, ready to add more data to the end of the file. Lastly, a mode of io.FileMode.OutNew is simply an Or of the Out and New modes, and will delete any existing file and create a new, empty file for writing. You can combine the file modes with the bitwise Or operator.

class InputStream

This is a class which represents a stream of data which can be read.

readByte(), readShort(), readInt(), readFloat(), readDouble(), readChar(), readWChar(), readDChar()

Reads one data primitive of the indicated type and returns it. readChar() reads a single 8-bit UTF-8 code unit, not any more; it won't handle multi-byte encodings. readWChar() also only reads one 16-bit UTF-16 code unit. There are no multi-unit encodings in UTF-32, so readDChar() will always read a single valid character.

readString()

Reads in a non-human-readable string value. Should only be used as an opposite to OutputStream.writeString().

readln()

Reads a line of text followed by a line-end. The line-end is not included in the returned string. Throws an error if you try to read past the end of the stream.

readf(formatString)

Note: This function is not available in the current release of MiniD. Reads in formatted values, and returns as many values as are specified in the format string.

readChars(length)

Reads the given number of UTF-8 characters and returns them as a string.

opApply()

This is an iterator bootstrap for iterating over all the lines in the given stream. The data in the stream must be text data with line-ends for this to work properly. This gives two values for the foreach indices; the first is the current line number (line numbering starts with 1), and the second is the current line as a string. This stops when the end of the stream is reached.

class OutputStream

This is a class which represents a stream of data which can be written. All methods of this class return a "chaining reference", that is, the object on which they were called. This way, you can write code like "output.writeInt(a).writeInt(b).writeInt(c);".

writeByte(n), writeShort(n), writeInt(n), writeFloat(n), writeDouble(n), writeChar(n), writeWChar(n), writeDChar(n)

Writes one data primitive of the indicated type, as the opposite of the InputStream read functions.

writeString(s)

Writes out a string in a raw format (not meant to be read by humans). Should only be read back in with InputStream.readString().

write(vararg), writeln(vararg)

Writes an unformatted UTF-8 string to the file. writeln() is the same as write(), except it writes a system-dependent line-end after writing its parameters.

writef(vararg), writefln(vararg)

Writes a formatted UTF-8 string to the file. writefln() is the same as writef(), except it writes a system-dependent line-end after writing its parameters.

writeChars(string)

Writes the given string as a sequence of UTF-8 characters, with no length or line-end.

writeJSON(value, bool pretty = false)

Writes formatted JSON data to the output stream. See the baselib documentation of toJSON for more info. This is more efficient than using toJSON and then writing the result as no temporary string is created; the data is written right to the stream as it's generated.

flush()

Flushes the stream. This will empty the output buffer into the destination medium, and should be called before attempting to read from the same data the was just written, in order to maintain data coherence.

class Stream

This is a class which represents a stream of data which can be read and written. It's a conglomeration of both an InputStream and an OutputStream, as well as some other methods for seeking and other utilities. Stream has all the methods of both InputStream and OutputStream, so anything that's legal to do to either of those is legal to do on this class as well. As such, only the functions which are unique to Stream are documented here.

seek(pos, whence)

Moves the stream cursor to a new position in bytes. pos is the integer position, which means different things based on whence. If whence is the character value 'b', pos is an offset from the beginning of the stream. If whence is the character value 'c', then pos is a signed offset from the current position in the stream (you can jump back, using negative numbers, as well as forward). And if whence is 'e', pos is a negative offset from the end of the stream. Not all streams are seekable; unseekable streams will throw an error if you use this function on them.

position([newPosition])

Sets or gets the absolute stream position. If this is called with an integral argument, it sets the stream position (from the beginning, in bytes) to the new position. This is equivalent to using .seek(newPosition, 'b'). If this is called without any arguments, it returns the current stream position in bytes from the beginning of the stream. Throws an error on non-seekable streams.

size()

Returns the total size of the stream. Throws an error on non-seekable streams. This is also a fairly slow method, so you probably shouldn't call it in a loop.

close()

Closes the stream, flushing any output before it does so, and releases system resources. Once a stream has been closed, you cannot do anything with it. It's probably a good idea to close streams when you're done using them, since garbage collection doesn't guarantee that the Stream object will be collected in any timely manner, and so system resources can be held up unnecessarily.

isOpen()

Returns true if the Stream is still open, and false if it has been closed.

input()

Returns an instance of InputStream that represents the input facilities of this Stream.

output()

Returns an instance of OutputStream that represents the output facilities of this Stream.