Buffered IO Support in XPR

[hypersoft]

Doesn't exist.

[hypersoft]

Strategy: use JavaScript ES6 ArrayBuffer interface.

1. Existing Standard
2. Versatile Interface

This is a high priority, because many features logically depend on this [bug] being the original method/interface for IO operations. Streams are built on byte IO, but the xpr internals don't currently reflect that.

[hypersoft]

Actually, i forgot this doesn't coincide with XPR's flat API model. We could still get to this level if we can implement a simple pointer-logic-layer, because pointers are primitive values.

(1) Krypton, itself could provide some kind of buffer implementation with pointer support, where pointer support means a way to resolve a refrence to a buffer through an unsigned integer value. Or, (2) in the other more likely direction, which would be for Krypton to expand a pointer value provided by XPR into an ArrayBuffer.

"we" go with the second option. this is transparent, and allows the shell and script implementations to decide how to resolve pointer values, as object values. there is no need to provide pointer object unwrapping. The pointer "is" the real data. After obtaining the scriptable reference, a script, statement or function may not even need the pointer, except to refrence the data in the calling of an XPR function which takes a pointer. So, the caller that obtains the pointer by creation or some other primitive api [is a memory managment unit and] will always have the pointer, or will have discarded it.

All that being said, in the sense of platform independence, a pointer is just a number in a table of memory blocks, with some length data specification attached, typically at the addres or in an address-frame stored somewhere in memory managment. There are more semantics like alignment and things of that nature that make sense for actual hardware. But in emulation, we are on the memory managment side which means we allocate whatever, however we want, and we refrence/derefrence those units at our pleasure.

[hypersoft]

Protected Random Addressing.

Get void, transfer void, set non-null will dump the whole stack. So, its an expert system. Do it right, cuz if ya don't: bugs.

[hypersoft]

To fully implement this feature as specified, we had to break XPR's (primitive/string)-only: contract; by providing to/from JavaScript: ArrayBuffer: Object.

It just didn't seem smart to move some XPR related functions into the global namespace, when using the XPR functionalities are a requirement of the feature.

There is a possible contract resolution path using Java's nio.ByteBuffer versus JavaScript's ArrayBuffer, however this will greatly increase complexity by adding several APIs. Using those APIs will be more portable, but in the meantime, we plan that XPR should be ES6 environment compatible, and ArrayBuffer is an ES6 extension.

[hypersoft]

 echo 'XPR.matchSDKs("buffer|stream", "i")' | krypton --print-result

[
  "XPR.base64ToBuffer: ƒ(String source) => Buffer",
  "XPR.bufferBytesTotal: ƒ() => long",
  "XPR.bufferCount: ƒ() => long",
  "XPR.bufferFromArrayBuffer: ƒ(ArrayBuffer transferShare) => Buffer",
  "XPR.bufferLength: ƒ(Buffer buffer) => long",
  "XPR.bufferToArrayBuffer: ƒ(Buffer transferOut) => ArrayBuffer",
  "XPR.bufferToBase64: ƒ(Buffer transferOut) => String",
  "XPR.bufferToInputStream: ƒ(Buffer transferOut) => Stream",
  "XPR.bufferToString: ƒ(Buffer transferOut, CharSet encoding) => String",
  "XPR.closeBufferOutputStream: ƒ(Stream transferOut) => Buffer",
  "XPR.closeStream: ƒ(Stream stream) => void",
  "XPR.createBuffer: ƒ(int width, int length) => Buffer",
  "XPR.freeBuffer: ƒ(Buffer buffer) => void",
  "XPR.getErrorStream: ƒ() => Stream",
  "XPR.getInputStream: ƒ() => Stream",
  "XPR.getOutputStream: ƒ() => Stream",
  "XPR.getStreamType: ƒ(Stream stream) => String",
  "XPR.inputStreamBytes: ƒ(Stream stream) => int",
  "XPR.inputStreamToBuffer: ƒ(Stream transferOut) => Buffer",
  "XPR.openBufferOutputStream: ƒ(int bytes) => Stream",
  "XPR.openFileInputStream: ƒ(Stream stream) => Stream",
  "XPR.openFileOutputStream: ƒ(Stream stream) => Stream",
  "XPR.readInputStream: ƒ(Stream stream, Buffer buffer) => int",
  "XPR.setErrorStream: ƒ(Stream outputStream, CharSet encoding) => boolean",
  "XPR.setInputStream: ƒ(Stream inputStream) => boolean",
  "XPR.setOutputStream: ƒ(Stream outputStream, CharSet encoding) => boolean",
  "XPR.sliceBuffer: ƒ(Buffer buffer, int offset, int length) => Buffer",
  "XPR.stringToBuffer: ƒ(String source, CharSet encoding) => Buffer",
  "XPR.writeOutputStream: ƒ(Stream stream, Buffer buffer, boolean flush) => void"
]