glk/README

Glk protocol for JavaScript

~~~~~
This is a library to use Glk from JavaScript code. This program is public
domain, although dispatch.js contains Glk dispatch data which comes from
a program with MIT license, so the dispatch.js file has its own copyright
notice in order to acknowledge this.

It also includes a protocol for encoding Glk dispatches as byte streams,
and internally uses it; you need not touch it directly, though.

Before using it, you may need to modify the startup code and compiling
instructions in glkrun.c for use with the Glk implementation you use. The
present implementation is for GlkTerm.

This module exports an object with property names being all of the Glk
constants and Glk functions, without "glk_" at front. The values of the
constants are numbers. The functions are callable JavaScript functions.

The following describes corresponding Glk types with JavaScript types:

* Integers (glui32, glsi32): A JavaScript number.

* Character (char, signed char, unsigned char): A JavaScript number.

* String of 8-bit characters: A JavaScript string. Must consist only of
codepoints in range 1 to 255.

* String of 32-bit characters: A JavaScript string. Must be valid UTF-16
with no null characters; will internally be converted into UTF-32.

* Opaque objects: These are represented as a JavaScript object, or null
if there is no object (only valid for some functions). The object will be
an object of one of the four classes mentioned below, although they have
no properties, except those inherited from Object, and a new version of
the toString function for debugging purposes. It must be an object that
is returned by a Glk function and has not yet been destroyed; otherwise
it will throw an error (if you create your own objects in JavaScript, even
if they have the correct classes, they will also throw an error).

* Structures: Use a JavaScript array, containing the values in order. If
the Glk function only writes to it and does not read it, you can omit the
values and it will still work.

* Arrays: It must be either a Array, Uint8Array, Int8Array, Uint32Array,
or Int32Array; depending on the type of the data, some types might not be
allowed. There is no length argument; it is implied. Sometimes arrays are
retained by Glk; in this case, the array will be written to once it is no
longer retained, and you may read back the data at that time (for example,
this is needed to handle line input events).

* References: Some Glk functions use references passed in and/or out. In
this case, scalar values need to be wrapped in a JavaScript array with a
single element; if passed out only, then it can be initially empty. If a
reference is allowed to be omitted, you may pass null to omit it.

Other properties of the exported object include:

.Channel()
  The class of Glk sound channels.

.File()
  The class of Glk filerefs.

.Stream()
  The class of Glk streams.

.Window()
  The class of Glk windows.

._classes
  Used internally to create JavaScript objects for opaque references.

._dispatch(id,proto)
  The first argument is a 16-bit Glk function number. The second argument
  is a string in the format described by section 12.1.4 ("Getting Argument
  Prototypes") of the Glk specification. This function returns another
  function, which can be called to call the Glk function. Normally there
  is no need to call _dispatch() directly, although you might use it if
  you need to call extension functions. If id is 1 then calling the
  returned function will terminate the process after sending the dispatch
  call; this is a special case.

._read(buf)
  Receive the buffer from Glk; the entire contents of the buffer is
  overwritten. Used internally; you should not use this yourself,
  although you may override it if needed.

._read1(buf)
  Receive one byte from Glk, and store it in the first cell of the buffer.
  Used internally; you should not use this yourself, although you may
  override it if needed.

._write(buf)
  Send the buffer to Glk. Used internally; you should not use this
  yourself, although you may override it if needed.

.bufToString(buf,len)
  The first argument needs to be a Uint32Array or Uint8Array. The second
  argument is the length of the data. You can use this when requesting
  line events in order to get the data back.