hspeakrt v2.2.0

Executes Hamster Speak binaries. This program is public domain.

The exported value is a constructor which takes two arguments. The first
argument is a filename, file descriptor, buffer, or Hamster archive object
(from the "hamarc" package), to load the scripts from. The second argument
is the number of global variables to allocate (in which case they are all
initialized to zero), or a Int32Array to use as storage for the global
variables (in which case it already contains the initial values and it
won't initialize them again).

The properties available on the constructed object are:

.after
  An empty string. You can override it with a string containing a
  JavaScript code to execute before every return in the compiled code. You
  must set it before loading or calling any scripts.

.before(id,buf)
  Returns an empty string. You can override it to return a string
  containing a JavaScript code, which will be prefixed to the function
  when it is compiling it. The arguments are the ID number, and the buffer
  which contains the contents of the .HSZ or .HSX lump. You must set it
  before loading or calling any scripts.

.call(id,...args)
  Call a script, by name or by number. If the script does not exist,
  returns null, otherwise returns a generator. Call the generator's next
  method to start executing it. When done is true, the value will be the
  return value of the script; if done is false, the value is an array,
  where the first element is a "builtin function" number, the second
  element is the string table buffer (or null if there is none), and the
  remaining elements are the arguments; in such a case, call next with
  the return value of the builtin function to continue the script. It is
  OK for multiple scripts (or multiple instances of the same script) to be
  executing at once. (If you specify too few arguments, the values of the
  remaining arguments will be zero. If you specify too many arguments, any
  excess arguments will be ignored.)

.commandNames()
  Read an array with the commands (system call numbers). The key is the
  command number, and the value is the command name, as a string. The
  array may be sparse if not all numbers are used. If the COMMANDS.BIN
  lump does not exist or has an unrecognized format, returns null. If you
  use the .preload() function, you must call .commandNames() at least once
  before calling .preload() if you want to access the command names (after
  calling once, the command names are cached).

.global
  A Int32Array of the global variables. All values default to zero if it
  was freshly allocated by the constructor.

.list()
  Make a list of the scripts. Return value is an array, indexed by the ID
  number of the script. Each element is an object with the properties
  "trigger" and "name", where the trigger is a number and the name is a
  string. If there are no names in the file, the name is null.

.preload()
  Preload all scripts, including their names. Doing this will also detach
  the hamster archive (allowing garbage collection) and will close the
  file if the file was opened in the constructor.

.unload()
  Unload everything, including closing the file if the constructor opened
  the file. Now this Hamster Speak runtime engine is no longer usable; you
  must call the constructor again if you want to load another script.

The properties available on the constructor are:

.getString(buf,num,[enc])
  Read a string from a string table. The first argument is the string
  table (the second element (index 1) of an array yielded by a script),
  The second argument is the strong number (which may be one of the other
  values of the yielded array). The third argument is the string encoding,
  which defaults to "binary", but you may also specify "ascii" or "utf8".

Also, if you wish to alter the random numbers that are returned to
scripts, you can set the "_random" property of the constructed object. The
first argument is the low number, the second argument is the high number,
and the return value is the random integer. Setting this property will
override the definition on the prototype. (OHRRPGCE function 108 sets the
random number seed, so this is how you would do that kind of things.)

(A further note is that this implementation requires lvalues to be
constant numbers; you can't use arithmetic or any other operation to
determine which variable to assign to. But you can still implement another
function to compute global variable numbers and access those; this is what
OHRRPGCE does with builtin function 114 and 115. This implementation does
support computed break/continue though.)