libjson

func Builtins ¶

func Builtins(s *Serializer) []*libutil.Builtin

Builtins takes the default serializer for a lisp environment and returns a set of package builtin functions that use it.

The string-numbers and exact-integers modes the builtins set are stored as bindings in the runtime's DefaultPackageName ("json") package, whichever package the builtins are registered in, so template-forked VMs each keep their own copy (#678). Register them through LoadPackage. An environment that has no "json" package falls back to the serializer's fields, which every VM sharing s also shares; do not publish such an environment as a template.

func Canonize ¶ added in v1.74.0

func Canonize(v *lisp.LVal, opts ...TypedOption) (*lisp.LVal, error)

Canonize returns a fresh plain JSON image of v, using exact integer types. It walks values directly, without encoding and decoding a document. For every successful result c, Dump(c, false) == Dump(v, false) == DumpTyped(c); LoadWith(..., LoadOpts{ExactIntegers:true}) and LoadTyped return exactly c, and Canonize(c) equals c. Limits and incremental step charging use the same TypedOptions as DumpTyped. Options may lower the default limits; raising them cannot admit values beyond the default typed limits, since such results would violate the invariant.

Leading tilde strings, invalid UTF-8, integers beyond +/-2^53, nonfinite floats, negative zero, whole-number floats outside the exact/platform int range, int map keys, collisions and changed member order are errors. Opaque native encodings and native numbers are refused: their JSON spelling or treatment of StringNumbers cannot be preserved by a direct value walk. CanonizeBuiltin exposes these data rejections as json:canonize-error, with (message, case keyword, path) data for Lisp handlers.

func CanonizeBuiltin ¶ added in v1.74.0

func CanonizeBuiltin(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal

CanonizeBuiltin implements json:canonize and propagates runtime budget conditions unchanged, while charging each started KiB during the walk.

func Dump ¶

func Dump(v *lisp.LVal, stringNums bool) ([]byte, error)

Dump serializes the structure of v as a JSON formatted byte slice.

Dump has no runtime, so unlike the json:dump-* builtins it is bounded by neither Runtime.MaxAlloc nor an evaluation context. An embedder serializing values a lisp program controls should call a json:dump-* builtin instead (see docs/lang.md, "Allocation Limits").

func DumpDurable ¶ added in v1.75.0

func DumpDurable(env *lisp.LEnv, v *lisp.LVal, reg *DurableRegistry, opts ...TypedOption) ([]byte, error)

DumpDurable writes v as a durable typed JSON document: ["~#durable",[1,VALUE]]. VALUE is v's typed JSON with extension tags. An object (a nonempty list, a vector or array, a sorted map, a tagged value, bytes, an error or a native) that is reached more than once is written once as ["~#obj",[ID,X]] and then as ["~#ref",ID], so LoadDurable restores the sharing and any cycle. An object reached once is written exactly as DumpTyped writes it. The same value graph always gives the same bytes.

env resolves function names and is passed to the native codecs. A native value is written through the codec reg holds for its Go type; reg may be nil when v holds no natives. A registered builtin is written as ["~#builtin",["PKG","NAME"]], the package and name env's registry registered it under (lisp.PackageRegistry.RegisteredBuiltinName), whatever its names bind. A Lisp function, or a builtin no registration names, that a global binds is written as ["~#fn","PKG:NAME"]: PKG is its defining package and NAME the first name, in sorted order, under which PKG binds it.

Lists and arrays whose cells share storage (a list and its tail, a slice of a vector, arrays over one data list) keep that sharing: the storage is written once and each value as a view of it (see durable_views.go). A program literal (a sealed list) is written as ["~#lit",X] and restores as a literal that the mutators refuse.

An error value is written as ["~#error",["CONDITION",[DATA...]]] and restores as an error with the same condition and data, without its call stack or source location (see durable_errors.go).

A lambda no global binds (a closure) is written with its code and the frames it captured (see durable_closures.go).

Refused with an error: internal panics, errors whose condition is empty or not UTF-8, builtins no global binds, macros and special operators (also when a closure captured one), natives with no codec, a native whose payload reaches the native or an object that encloses it (directly or through finished objects), a shared value in the payload of a codec registered without WithSharedPayload, and every value DumpTyped refuses for a reason other than sharing.

opts are typed JSON's limits and charge; see docs/internals/durable-json.md for what each one counts. The byte and value limits never exceed env's per-operation allocation cap. reg must be frozen.

package main

import (
	"fmt"

	"github.com/luthersystems/elps/lisp"
	"github.com/luthersystems/elps/lisp/lisplib/libjson"
)

func main() {
	env := lisp.NewEnv(nil)
	lisp.InitializeUserEnv(env)
	m := lisp.SortedMap()
	m.MapSetLVal(lisp.String("self"), m)
	b, err := libjson.DumpDurable(env, lisp.QExpr([]*lisp.LVal{m, m}), nil)
	fmt.Println(string(b), err)
	back, _ := libjson.LoadDurable(env, b, nil)
	fmt.Println(back.Cells[0] == back.Cells[1])
}

Output:
["~#durable",[1,["~#list",[["~#obj",[0,{"self":["~#ref",0]}]],["~#ref",0]]]]] <nil>
true

func DumpDurableRoots ¶ added in v1.75.0

func DumpDurableRoots(env *lisp.LEnv, roots []DurableRoot, reg *DurableRegistry, opts ...TypedOption) ([]byte, error)

DumpDurableRoots writes named values as one durable document, so values shared between roots stay shared. The roots are written in the order of the slice, and that order decides the object ids, so a caller that wants one encoding per set of names passes them in a fixed order (sorted, for example). The value is the list of alternating names and values, ("name1" value1 "name2" value2 ...), or () for no roots. Names must be nonempty, valid UTF-8 and distinct. See DumpDurable for the rest.

func DumpTyped ¶ added in v1.74.0

func DumpTyped(v *lisp.LVal, opts ...TypedOption) ([]byte, error)

DumpTyped writes v as typed JSON: exactly the bytes of Dump(Tag(v), false), without building Tag(v).

Supported: ints, floats (NaN and the infinities included), strings (which, like symbol, keyword, map key and tagged type names, must be valid UTF-8), bytes, symbols, keywords, lists (quoted or not: the quote flag is not data), arrays of any rank, sorted maps and tagged values. Functions, native values, errors, nested quotes and values that contain themselves are rejected with an error, so a caller that uses the bytes as a key (a memo key, a SHA-256 content hash) can fall back when a value has no encoding.

The encoding is type-faithful and so finer than equal?: 1 and 1.0 encode differently ("1" and "\"~d1\""), and so do a string and a symbol of one spelling. Values of the same types and structure always give the same bytes, whatever order a map was built in and whichever cells are shared; shared structure is written in full at each occurrence, so a small value whose tree expansion passes the value or byte limit is rejected.

func DumpTypedBuiltin ¶ added in v1.74.0

func DumpTypedBuiltin(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal

DumpTypedBuiltin is the runtime adapter for typed dumping across the JSON family.

func DumpWith ¶ added in v1.74.0

func DumpWith(v *lisp.LVal, opts DumpOpts) ([]byte, error)

DumpWith encodes v under opts without changing the existing Dump API.

func Load ¶

func Load(b []byte, stringNums bool) *lisp.LVal

Load parses b as JSON and returns an equivalent LVal.

func LoadDurable ¶ added in v1.75.0

func LoadDurable(env *lisp.LEnv, b []byte, reg *DurableRegistry, opts ...TypedOption) (*lisp.LVal, error)

LoadDurable decodes a document DumpDurable wrote and rebuilds its value graph: each ["~#obj",[ID,X]] is one value, and every ["~#ref",ID] is that same value, so sharing and cycles come back as they were saved. Natives are rebuilt by the codecs reg holds (reg may be nil when the document holds none), ["~#builtin",["PKG","NAME"]] is the builtin env's registry registered as PKG:NAME (lisp.PackageRegistry.RegisteredBuiltin), whatever that name holds now, and ["~#fn","PKG:NAME"] is the function env's registry binds to that global now, which must be a regular function of package PKG. An ["~#error",...] is an error value with its condition and data, and no call stack or source location; the result itself may be one. A ["~#closure",...] is rebuilt with LEnv.RestoreLambda over frames chained to env's root, and nothing is evaluated.

LoadDurable accepts only what DumpDurable writes. It rejects every input LoadTyped rejects inside the value, a missing header or another format version, an object id out of sequence, an object no reference uses, a reference to an object not yet defined or to the object being defined, a native payload that reaches an unfinished object (directly or through finished ones), sharing inside the payload of a codec registered without WithSharedPayload, an unknown native name or version, a builtin that is not registered as a regular function under its package and name, a function name that does not resolve to a regular function of its package, and an error whose condition is empty or internal-panic. A function may be named by any of its package's names for it, and a ~#fn global may hold a registered builtin (one an upgrade moved to Go), so such a document can re-encode to other bytes. It never panics on malformed input; a native codec is called only with a fully restored payload.

Values are freshly allocated, except builtins, which are the registered values, named functions, which are the current global bindings, and natives, which are whatever their codecs return. Memory is bounded by the input, as for LoadTyped. The byte and value limits never exceed env's per-operation allocation cap. Unlike LoadTyped, LoadDurable calls the charge function: ceil(n/1024) units for n input bytes before it decodes, and each codec's declared charge before each LoadNative call. reg must be frozen.

func LoadPackage ¶

func LoadPackage(env *lisp.LEnv) *lisp.LVal

LoadPackage adds the json package to env

func LoadTyped ¶ added in v1.74.0

func LoadTyped(b []byte, opts ...TypedOption) (*lisp.LVal, error)

LoadTyped decodes typed JSON: the same value as Untag of a Strict, ExactIntegers plain load of b, in one pass. Anything DumpTyped could not have produced is rejected with an error: whitespace, a member out of UTF-8 byte order or duplicated, number text other than the canonical text of its value (1.50, 1E5, -0, 01, an int written as a float or past 2^53 as a number), an escape outside the plain encoder's set or a missing mandatory escape, an unknown or misused tag, a tagged empty list, non-canonical base64, trailing bytes, and input over any configured limit. It never panics on malformed input.

Every value it returns is freshly allocated and shares no storage with b or with any other value, so the caller owns it outright. Plain JSON arrays come back as vectors, null as nil, and tagged lists as data lists, as list builds them. A tagged value comes back with its type name and data, and is not checked against any type defined with deftype.

Memory is bounded by the input: every value costs at least one byte of it, and nothing is reserved from a count the input declares.

func LoadTypedBuiltin ¶ added in v1.74.0

func LoadTypedBuiltin(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal

LoadTypedBuiltin is the runtime adapter for typed loading across the JSON family.

func LoadWith ¶ added in v1.50.0

func LoadWith(b []byte, opts LoadOpts) *lisp.LVal

LoadWith parses b as JSON under opts and returns an equivalent LVal.

func RegisterNative ¶ added in v1.75.0

func RegisterNative[T any](r *DurableRegistry, name string, version int, c NativeCodec, opts ...NativeOption) error

RegisterNative registers codec c for native payloads of Go type T. See DurableRegistry.Register.

func Tag ¶ added in v1.74.0

func Tag(v *lisp.LVal, opts ...TypedOption) (*lisp.LVal, error)

Tag transforms v into plain JSON values without losing its data types. Whole floats use ~d followed by appendJSONFloat text, including ~d-0. Limits count logical values and containers, without counting tag wrappers.

func TagBuiltin ¶ added in v1.74.0

func TagBuiltin(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal

TagBuiltin returns a plain JSON value with type tags.

func Untag ¶ added in v1.74.0

func Untag(v *lisp.LVal, opts ...TypedOption) (*lisp.LVal, error)

Untag restores the data types represented by Tag. Unknown tags and malformed forms return an error. Input must contain plain JSON values.

func UntagBuiltin ¶ added in v1.74.0

func UntagBuiltin(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal

UntagBuiltin restores the types of a plain JSON value with type tags.