This document describes "N0FileIO", a file I/O library for NSM that implements the same functionality as NEWT/0's "protoFILE" extension. It can also serve as a reference for the latter.

Loading the library

Because the library uses platform-specific native code, each platform has its own version of the library. All versions implement the same functionality and can be downloaded from the NSM Web page.

General usage

First, you create a frame whose _proto slot is protoFILE. In NEWT/0, you would use @protoFILE, but NSM does not support NEWT/0's named magic pointers, so a global variable named protoFILE is used instead.

Then, you send the frame an Open message to open a file. If it succeeds, you can use the other methods described here to do I/O on the file. Finally, you send the frame a Close message to close the file. After that, it is safe to dispose of all references to the frame.

General notes




Closes the file.

Call this method when you are done with the file, before you dispose of the references to the frame.

After this method has been called, you can reuse the file frame to open a new file.

The return value is undefined.



Returns non-nil if the end of the file has been reached or nil if it hasn't.

Note: the end of the file will only be detected if another function has attempted to read past it. For example, don't do this:

while not file:EOF() do

Instead, check the return value of whatever function you are using to read from the file, or call EOF only after it.



Reads a byte and returns an integer. If you try to read past the end of the file, -1 is returned.



Reads a line of text. Returns a string ending with $\n, except if the line is the last line in the file and there is no line separator following it. If you try to read past the end of the file, nil is returned.

Differences from NEWT/0

The NEWT/0 implementation only recognizes lines separated by a line feed. This implementation also recognizes a carriage return or a carriage return followed by a line feed.


file:Open(filename, mode)

Opens a file for use with the other methods.

filename is a string specifying the filename.

mode is a string and may be one of the following:

If mode is not one of the aforementioned strings, the effect is undefined.

You can reuse a file frame to use multiple files, but you must call the Close method to close each one before opening a new one.

Differences from NEWT/0

This implementation returns non-nil if the file was successfully opened or nil if it wasn't.

On all platforms except Win32, only ASCII filenames are supported.

On DOS, only short ("8.3") filenames are currently supported.



Writes a string to the file without a trailing line separator.

The return value is undefined.

Differences from NEWT/0

NEWT/0 writes the string as it is. This implementation converts each $\n in the string to the native line separator.



Writes a byte to the file.

byte must be an integer.

The return value is undefined.



Reads the number of bytes specified by length from the file and returns a binary object of the class 'binary.

length must be an integer.

If length is greater than the number of bytes available, the returned binary object will be shorter than requested.

If length is 0 or there are no more bytes to read, nil is returned.

Differences from NEWT/0

The NEWT/0 documentation does not specify what happens in the case of an error. This implementation returns nil.



Sets the current file position to the beginning of the file.

The return value is undefined.


file:Seek(offset, origin)

Sets the current file position relative to the specified origin.

offset must be an integer.

origin must be a symbol and may be one of the following:

If origin is not one of the aforementioned symbols, the effect is undefined.

The new position relative to the start of the file is returned.



Returns the current file position (an integer).



Writes the contents of a binary object to the file.

The return value is undefined.