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

• The first byte in a file is numbered 0.
• This library is only reliable when working with ASCII text. Other 8-bit encodings that are backwards compatible with ASCII (such as DOS and Windows codepages) may be used, but no encoding conversion will be done. You can still, of course, manually read and write bytes and convert them between big endian UCS-2 (the Unicode encoding used by NewtonScript) and other encodings.
• Despite the NEWT/0 documentation saying that the Open method is like "fopen" in the C programming language, NEWT/0 does not support "text mode", not even on Win32. This implementation does not have explicit "text" and "binary" modes either, but the GetS and Print methods do line ending conversion as needed.
• All functions are supposed to throw an exception if their parameters are not of the expected types. However, NSM does not support exceptions yet, so it will just quit on error.
• The NEWT/0 documentation does not specify what happens in the case of an I/O error (such as a full disk), so this implementation ignores most errors.

Methods

Close

file:Close()

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.

EOF

file:EOF()

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
:DoSomething(file:GetS());


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

GetC

file:GetC()

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

GetS

file:GetS()

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.

Open

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:

• "a": Write only. Creates the file if it doesn't exist. The current file position is set to the end of the file.
• "a+": Read and write. Creates the file if it doesn't exist. The current file position is set to the end of the file.
• "r": Read only. Fails if the file doesn't exist. The current file position is set to the beginning of the file.
• "r+": Read and write. Fails if the file doesn't exist. The current file position is set to the beginning of the file.
• "w": Write only. Creates a new file or replaces it if it exists. The current file position is set to the beginning of the file.
• "w+": Read and write. Creates a new file or replaces it if it exists. The current file position is set to the beginning of the file.

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.

Print

file:Print(string)

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.

PutC

file:PutC(byte)

Writes a byte to the file.

byte must be an integer.

The return value is undefined.

Read

file:Read(length)

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.

Rewind

file:Rewind()

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

The return value is undefined.

Seek

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:

• 'set: The offset is absolute (relative to the start of the file). offset may not be negative.
• 'curr: The offset is relative to the current position. offset may be negative.
• '|end|: The offset is relative to the end of the file. offset may be negative.

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.

Tell

file:Tell()

Returns the current file position (an integer).

Write

file:Write(binaryObject)

Writes the contents of a binary object to the file.

The return value is undefined.