encoding::json +linux +x86_64

This module provides an implementation of the JavaScript Object Notation (JSON) format, as defined by RFC 8259. Note that several other, incompatible specifications exist. This implementation does not include any extensions; only features which are strictly required by the spec are implemented.

A lexer for JSON values is provided, which may be initialized with lex and provides tokens via next, and which uses a relatively small amount of memory and provides relatively few gurantees regarding the compliance of the input with the JSON grammar.

Additionally, the value type is provided to store any value JSON value, as well as helpers like newobject, get, and set. One can load a JSON value from an input stream into a heap-allocated value via load, which enforces all of JSON's grammar constraints and returns an object which must be freed with finish.

Index

Types

type _null;
type arrayend;
type arraystart;
type colon;
type comma;
type load_option;
type nestlimit;
type objend;
type objstart;
type token;
type value;

// Undocumented types:
type iterator;
type lexer;
type object;

Errors

type error;
type invalid;
type limitreached;

Constants

const OBJECT_BUCKETS: size;

Functions

fn close(*lexer) void;
fn del(*object, const str...) void;
fn dump(io::handle, value) (size | io::error);
fn dumpstr(value) str;
fn dup(value) value;
fn equal(value, value) bool;
fn finish(value) void;
fn get(*object, str) (*value | void);
fn iter(*object) iterator;
fn lex(*lexer) (token | io::EOF | error);
fn load(io::handle, load_option...) (value | error);
fn loadstr(str, load_option...) (value | error);
fn newlexer(io::handle) lexer;
fn newobject() object;
fn next(*iterator) ((const str, const *value) | void);
fn reset(*object) void;
fn set(*object, const str, const value) void;
fn strerror(error) const str;
fn unlex(*lexer, token) void;

Types

type _null[link]

type _null = void;

The JSON null value.

type arrayend[link]

type arrayend = void;

The ']' token, signaling the end of a JSON array.

type arraystart[link]

type arraystart = void;

The '[' token, signaling the start of a JSON array.

type colon[link]

type colon = void;

The ':' token.

type comma[link]

type comma = void;

The ',' token.

type load_option[link]

type load_option = nestlimit;

Options for load.

type nestlimit[link]

type nestlimit = uint;

The maximum number of nested objects or arrays that can be entered before erroring out.

type objend[link]

type objend = void;

The '}' token, signaling the end of a JSON object.

type objstart[link]

type objstart = void;

The '{' token, signaling the start of a JSON object.

type token[link]

type token = (arraystart | arrayend | objstart | objend | colon | comma | str |
f64 | bool | _null);

All tokens which can be returned from the JSON tokenizer.

type value[link]

type value = (f64 | str | bool |
_null | []value | object);

A JSON value.

type iterator[link]

Show undocumented member
type iterator = struct {
	obj: *object,
	i: size,
	j: size,
};

type lexer[link]

Show undocumented member
type lexer = struct {
	src: io::handle,
	buffer: []u8,
	strbuf: strio::stream,
	un: (token | void),
	rb: (rune | void),
	loc: (uint, uint),
	prevloc: (uint, uint),
	nextloc: (uint, uint),
	prevrloc: (uint, uint),
};

type object[link]

Show undocumented member
type object = struct {
	buckets: [OBJECT_BUCKETS][](str, value),
};

Errors

type error[link]

type error = !(invalid | limitreached | io::error);

A tagged union of all possible errors returned from this module.

type invalid[link]

type invalid = !(uint, uint);

An invalid JSON token was encountered at this location (line, column).

type limitreached[link]

type limitreached = !void;

The maximum nesting limit was reached.

Constants

def OBJECT_BUCKETS[link]

def OBJECT_BUCKETS: size;

TODO: Resize table as appropriate

Functions

fn close[link]

fn close(lex: *lexer) void;

Frees state associated with a JSON lexer.

fn del[link]

fn del(obj: *object, keys: const str...) void;

Deletes values from a JSON object, if they are present.

fn dump[link]

fn dump(out: io::handle, val: value) (size | io::error);

Dumps a value into an io::handle as a string without any additional formatting.

fn dumpstr[link]

fn dumpstr(val: value) str;

Dumps a value into a string without any additional formatting. The caller must free the return value.

fn dup[link]

fn dup(val: value) value;

Duplicates a JSON value. The caller must pass the return value to finish to free associated resources when they're done using it.

fn equal[link]

fn equal(a: value, b: value) bool;

Checks two JSON values for equality.

fn finish[link]

fn finish(val: value) void;

Frees state associated with a JSON value.

fn get[link]

fn get(obj: *object, key: str) (*value | void);

Gets a value from a JSON object. The return value is borrowed from the object.

fn iter[link]

fn iter(obj: *object) iterator;

Creates an iterator that enumerates over the key/value pairs in an object.

fn lex[link]

fn lex(lex: *lexer) (token | io::EOF | error);

Returns the next token from a JSON lexer. The return value is borrowed from the lexer and will be overwritten on subsequent calls.

fn load[link]

fn load(src: io::handle, opts: load_option...) (value | error);

Parses a JSON value from the given io::handle, returning the value or an error. The return value is allocated on the heap; use finish to free it up when you're done using it.

By default, this function assumes non-antagonistic inputs, and does not limit recursion depth or memory usage. You may want to set a custom nestlimit, or incorporate an io::limitreader or similar. Alternatively, you can use the JSON lexer (lex) directly if dealing with potentially malicious inputs.

fn loadstr[link]

fn loadstr(input: str, opts: load_option...) (value | error);

Parses a JSON value from the given string, returning the value or an error. The return value is allocated on the heap; use finish to free it up when you're done using it.

See the documentation for load for information on dealing with potentially malicious inputs.

fn newlexer[link]

fn newlexer(src: io::handle) lexer;

Creates a new JSON lexer. The caller may obtain tokens with lex and should pass the result to close when they're done with it.

fn newobject[link]

fn newobject() object;

Initializes a new (empty) JSON object. Call finish to free associated resources when you're done using it.

fn next[link]

fn next(iter: *iterator) ((const str,
const *value) |
void);

Returns the next key/value pair from this iterator, or void if none remain.

fn reset[link]

fn reset(obj: *object) void;

Clears all values from a JSON object, leaving it empty.

fn set[link]

fn set(obj: *object, key: const str, val: const value) void;

Sets a value in a JSON object. The key and value will be duplicated.

fn strerror[link]

fn strerror(err: error) const str;

Converts an error into a human-friendly string.

fn unlex[link]

fn unlex(lex: *lexer, tok: token) void;

"Unlexes" a token from the lexer, such that the next call to lex will return that token again. Only one token can be unlexed at a time, otherwise the program will abort.