(rontolisp) docs
← rontolisp Package Functions

rontolisp:json-span

(rontolisp:json-span document &rest path) / (rontolisp:json-span address size &rest path)

Finds where a value is in a JSON document's bytes, without making Lisp values of the document. It checks the whole document as rontolisp:json-parse would, follows the path, and answers byte offsets from the document's first byte. An edit is then a splice of those bytes: insert, replace or delete text there.

The document is a string (its UTF-8 bytes) or an (unsigned-byte 8) vector. On the wasm-GC backends it can also be the size bytes at an address of the module's own linear memory, such as the body a Proxy-Wasm host placed there: they are read where they are and never copied, so a body of several megabytes is searched in the memory it already takes.

A path is keys and indexes: a string names an object's key, a non-negative integer an array's element. No path names the document itself.

Values

ValueWhat it is
startthe offset of the value's first byte
endthe offset past its last byte
countan object's members or an array's elements; nil for any other value
cut-start, cut-endthe bytes that deleting the member takes: its key or element and one comma beside it, or everything inside its container when it is the only one; nil for the document itself

A path that leads nowhere answers nil: a key or an index that is not there, or a value the path goes through that is no container of that kind. A key repeated in an object answers its last occurrence, the one json-parse keeps. Offsets count bytes on every backend, as a host's buffer does, so in a string of characters past ASCII they are not character indexes: use an octet vector to cut the text.

Editing

Replace a value between start and end; insert into a container before its closing bracket at (- end 1), writing a comma when count is not zero; delete a member between cut-start and cut-end.

A Proxy-Wasm filter edits the host's buffer in place the same way, by set-buffer's :start and :size, which count bytes too (the SDK):

(proxy-wasm:with-buffer (address size :response-body 0 body-size)
  (multiple-value-bind (start end members)
      (handler-case (rontolisp:json-span address size) (error () nil))
    ;; an object: a field before its closing brace
    (when (and members (eql (proxy-wasm:load8 (+ address start)) 123))
      (proxy-wasm:set-buffer :response-body
                             (concatenate 'string (if (plusp members) "," "")
                                          "\"seen\":true")
                             :start (- end 1) :size 0))))

Given the body as an octet vector in the place of address size, as a test of the filter's logic on the interpreter or the JVM gives it, the call answers the same offsets. To read a value rather than its bytes, use rontolisp:json-value.

Errors

A document json-parse refuses signals that error, under this function's name, so a handler tells "not JSON" from "no such value", which is nil. So does a path segment that is neither a string nor a non-negative integer, and an address on the interpreter or the JVM, which have no linear memory.

CL-USER> (rontolisp:json-span "{\"a\": 1,}" "a")
Error: json-span: expected an object key string

On wasm-GC, catch it with handler-case returning nil, not with ignore-errors under multiple-value-bind: the condition ignore-errors answers as its second value is bound to end there, and arithmetic on it keeps the condition printer, format among it, in the module, which made the filter above 88 KB larger.

Backend support

Works on every backend and in every WASM mode. The interpreter and the JVM run a scan written in rontolisp itself over the document's octets; the wasm-GC backends compile a native one into the program when it is used, which reads a string's bytes or linear memory in place (an octet vector is copied once). On wasm-GC the scan costs about 18 instructions a byte of a document of small members, and 6 a byte inside a string.