Process interfaces
JSON lines
Run bpl --worker. Send one JSON request per line on stdin. Each request gets one flushed JSON reply, in order. Names persist between requests.
{"code":"v←ι10"}
{"id":2,"code":"+/v"}The second reply is:
{"id":2,"result":{"value":45.0,"output":[{"kind":"display","data":{"text/plain":"45"}}],"error":null}}id is optional. A reply includes its request’s id, or null if the request has no id. Give an id to any request you might interrupt: {"interrupt":2} cancels request 2 and gets no reply. Wait for an evaluation to finish before starting another.
Build each request with a JSON encoder, such as Python’s json.dumps or JavaScript’s JSON.stringify, so that newlines in the source are escaped, and end it with a newline. Stdout contains only replies. Close stdin to end the session.
Malformed JSON, an invalid field or an invalid encoded array gives an error of kind REQUEST in that request’s result, without ending the session.
Requests
code is BPL source to evaluate. timeout_ms is the time allowed for the evaluation, in milliseconds. "echo":false suppresses implicit display, but not explicit output.
{"id":1,"code":"+/ι10","timeout_ms":2000,"echo":false}bindings assigns encoded values to names in the session. call is a function to apply to one or two encoded args, without generating BPL source.
{"id":2,"call":"+","args":[2,3],"echo":false}Results
output holds the events in order. Each event’s kind is display or explicit, and its data is a MIME bundle with text/plain. If the displayed value has a renderer, data also includes the renderer’s MIME types, such as image/svg+xml. value holds the returned value’s contents and axis labels, without renderers. Keyed entries in value that hold functions are omitted. A result that is a function, or an array that still holds one, has a null value, and output holds its display.
Atoms are encoded directly. All arrays, including rank-zero arrays, are encoded with their shape, row-major data and prototype. Nested items use the same encoding. When an array has keys on at least one axis, its encoding includes axis_keys, with one list of strings or null per axis.
When an array has at least one named axis, its encoding includes axis_names, with one string or null per axis, such as ["city", "month"]. Encoded arrays in requests also accept axis_keys and axis_names.
| Atom | JSON |
|---|---|
| Exact integer | Integer, including arbitrary precision |
| Approximate real | Number with decimal point or exponent |
| Character | String |
| Rational | {"rational":["1","3"]} |
| Complex | {"complex":[1.0,2.0]} |
| Infinity | {"infinity":1} or {"infinity":-1} |
| NaN | {"nan":1} |
Use the tags for infinities and NaN, never raw NaN or Infinity tokens. Integer inputs stay exact. Because JavaScript’s JSON.parse rounds integers larger than 2⁵³, use a parser that keeps integers exact. Error spans are UTF-8 byte ranges into the supplied source. Error reports include call sites as well as the original error location.
Python worker
Python’s Worker manages a persistent bpl --worker subprocess with deadlines and a hard-kill fallback.
from basedpl.worker import Worker
with Worker() as w:
w.eval('v←ι10')
r = w.eval('+/v', timeout=2)
assert r['value'] == 45Call w.interrupt() from another thread to cancel an evaluation. Ctrl-C requests cancellation too. When the process responds to the cancellation, the session and completed assignments are kept. If the process doesn’t respond within the grace period, one second by default, Worker kills it and the session is lost. Worker never replays a request. w.diagnostics holds recent stderr. Worker.request(payload, timeout=...) sends any request and supplies the request’s id.