NSM is an implementation of a portable NewtonScript virtual machine as described by Apple Computer in Newton Formats and The NewtonScript Programming Language.
This version of NSM is a public alpha version. It is limited in capabilities, but may already be useful for real work in some situations (for example, the documentation you are reading now was converted from another markup language to HTML, RTF, and plain text with a NewtonScript package running in NSM).
NSM does not interpret NewtonScript source code. It takes Newton packages containing NewtonScript bytecode and executes it.
This manual describes how to use NSM.
NSM is a command line program. Its parameters are the packages whose InstallScripts and RemoveScripts are to be executed. Any parameter that begins with a switch character is an option. The switch character depends on the platform.
The following options are supported:
G: Prints a message to the standard error stream when entering or exiting the garbage collector.H heapSize: Sets the heap size in bytes. The default is 8192.I filename: Causes the built-in global function _GetChar (described later in this document) to read from a file instead of standard input.O filename: Causes the built-in global functions Print and Write to write to a file instead of standard output.All options are case insensitive.
Currently, only Newton OS 1.x-compatible packages containing a single "auto" or "form" part are supported. Such packages may be created with Apple's Newton Toolkit, DyneTK, tntk, and possibly other applications. Please refer to other documents from the NSM documentation set for information on how to use them to create packages for NSM.
Note: Although packages must be in Newton OS 1.x format, NSM cannot run arbitrary Newton OS packages. However, it is possible (but not very useful) to create a package that will run on both NSM and the Newton OS.
When installing a package, NSM will execute its InstallScript. The package will remain installed until all packages are installed, so all references to it will remain valid. This way it is possible for a package to provide, for example, global functions that are not implemented in NSM itself and have code in other packages use them. After the last package specified is installed, the packages will be removed and their RemoveScripts will be executed in the reverse order of their installation. This gives packages a chance to clean up after themselves, for example to close any open files.
Packages are installed in the order they are specified. For example, the command line gfns.pkg Something.pkg will cause the following sequence of events:
If everything executed successfully, NSM will quit with an error code of 0. If there was an error, NSM will print an error message and the function call stack to the standard error stream and quit with a nonzero error code.
All instructions except pop-handlers and new-handlers are implemented.
The set-path instruction only supports paths that are symbols or integers. In other words, it does not support path expressions.
Some instructions and functions do not do proper input validation.
Exception handling is not yet implemented at all. All errors are fatal. For this reason (and others), NSM should not be used where reliability is required.
Magic pointers are not supported. Using them will cause undefined behavior.
The following global functions are implemented as described in The NewtonScript Programming Language: Apply, Chr, ExtractByte, Floor, GetSlot, GetVariable, HasSlot, HasVariable, Intern, IsReadOnly, Ord, Perform, PrimClassOf, Print, Real, ReplaceObject, SetLength, StrLen, StuffByte, Write.
Additionally, the global function _GetChar is supported. It reads an 8-bit character from standard input. It takes zero parameters and returns a character or nil if EOF has been reached. The native line separator character will be converted to a carriage return, but other carriage returns will not be removed. This can cause problems on platforms where the line separator is a line feed, while reading files where lines are separated by a carriage return and line feed, as two line separators may be read. No encoding conversion is done; the input is assumed to be encoded in ISO 8859-1. If the file is encoded in UTF-8 and has a BOM at the beginning, the BOM will be taken as three characters, which might cause problems.
On all platforms except DOS, there are additional global functions for using native code libraries. Please read the document The NSM native code interface for more information.
The package gfns.pkg implements several functions described in The NewtonScript Programming Language that are not implemented in NSM itself: Abs, Array, ArrayInsert, ArrayMunger, ArrayRemoveCount, BeginsWith, BinaryMunger, BinEqual, Ceiling, CharPos, DeepClone, DefGlobalFn, DefGlobalVar, Downcase, EndsWith, ExtractBytes, GetFunctionArgCount, GetGlobalFn, GetGlobalVar, GlobalFnExists, GlobalVarExists, InsertionSort, IsAlphanumeric, IsArray, IsBinary, IsCharacter, IsFrame, IsFunction, IsImmediate, IsInstance, IsInteger, IsNumber, IsReal, IsString, IsSubclass, IsSymbol, IsWhiteSpace, LFetch, LSearch, MakeBinary, Map, Max, Min, PerformIfDefined, RemoveSlot, SetAdd, SetContains, SetDifference, SetOverlaps, SetRemove, SetUnion, SignBit, Signum, SPrintObject, StrCompare, StrConcat, StrEqual, StrExactCompare, Stringer, StringToNumber, StrMunger, StrPos, StrReplace, Substr, SymbolCompareLex, TrimString, UndefGlobalFn, UndefGlobalVar, Upcase.
Note: The string functions, where required to be case insensitive, only do so correctly for ASCII characters. StringToNumber only recognizes integers, but returns reals as required by The NewtonScript Programming Language.
In addition to implementing those global functions, the library also implements support for the primitive function stringer and less-than, greater-than, greater-or-equal, and less-or-equal, when used with strings.
NSM was created by Matej Horvat.
Web site: http://matejhorvat.si/en/software/nsm/
Electronic mail: matej.horvat@guest.arnes.si
Special thanks to Morgan Aldridge and Matthias Melcher.