Standard Library: std.json
● Intermediate5 min
Every type, method and function of std.json: what the spec lists, then each declaration in its source, with its examples and the line that declares it.
Spec 2.12 · learn it in JSON.
A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.
What the spec lists
| Method | Gives |
|---|---|
text() | String?: the text of a Text |
int() | Int?: a Number written without a fraction or exponent that fits Int |
bigint() | BigInt?: a Number written without a fraction or exponent, of any size |
float() | Float?: a Number, as the nearest Float; none past Float's range |
decimal() | Decimal?: a Number, exactly |
bool() | Bool?: the value of a Boolean |
list() | [Json]?: the items of an Array |
object() | [String: Json]?: the fields of an Object |
is_null() | Bool: whether it is Null |
len() | Int: the items of an Array or fields of an Object, otherwise 0 |
| Function | Gives |
|---|---|
json.parse(text) ! JsonError | The Json value written in text, which must be standard JSON (RFC 8259) |
json.parse(text, comments: true) ! JsonError | The same, also taking // and /* */ comments and a trailing comma in arrays and objects (JSONC, as configuration files are written) |
json.decode<T>(text) ! JsonError | A T read straight from text, with no Json in between |
json.decode_value<T>(j) ! JsonError | A T read from the Json value j |
json.decode<T>(text, unknown: JsonUnknown.Ignore) | The same, skipping fields T doesn't have (decode_value takes it too) |
json.of(value) | value as a Json |
json.stringify(value, indent: 0) | JSON text for a Json or any value that can be encoded; indent above 0 puts each field on its own line |
json.schema<T>() | The JSON Schema of T as a Json: what ask<T> sends a model (8.4), for modules that work from a type's shape (14.14) |
json.describe(f) -> FnSchema | The function f described: its name, doc comment, parameters with their schemas, the schemas of its result and error, the capabilities it uses, and its example clauses as text |
std.json · json.kav
use std.json: 6 types and 0 functions. stdlib/json/json.kav
Json type
A JSON value whose shape is known only when the program runs. A Number keeps the digits it was written with (decision 0071).
pub type Json = Null |
Boolean(value: Bool) |
Number(digits: String) |
Text(value: String) |
Array(items: [Json]) |
Object(fields: [String: Json])int method
A Number written without a fraction or exponent that fits Int.
pub fn int(self) -> Int?bigint method
A Number written without a fraction or exponent, of any size.
pub fn bigint(self) -> BigInt?float method
A Number, as the nearest Float; none past Float's range.
pub fn float(self) -> Float?len method
The items of an Array or fields of an Object, otherwise 0.
pub fn len(self) -> Intget method
j["key"]: the field, or Null when there is none.
pub fn get(self, key: String) -> Jsonat method
j[i]: the item, or Null when there is none.
pub fn at(self, i: Int) -> JsonJsonError type
Why JSON text could not be read (spec 2.12).
pub type JsonError = Syntax(line: Int, column: Int, message: String) |
TooDeep(limit: Int) |
TooLarge(limit: Int) |
DuplicateKey(key: String, line: Int, column: Int) |
Invalid(problems: [JsonProblem])JsonUnknown type
What decoding does with a field the type doesn't have (spec 2.12): Refuse makes it a problem; Ignore skips it, for reading another service's answers, which may gain fields.
pub type JsonUnknown = Refuse | IgnoreJsonProblem type
One problem decoding found (spec 2.12): where in the document, and what the type wanted there.
pub type JsonProblem {
pub path: String
pub expected: String
}FnSchema type
A function described by json.describe(f) (spec 2.12), for a web framework's OpenAPI description, say.
pub type FnSchema {
pub name: String
/// Its `///` comment, the lines joined by spaces; "" when it has none.
pub doc: String
pub params: [ParamSchema]
/// The schema of what it returns; `{"type": "null"}` for nothing.
pub result: Json
/// The schema of its error; `Null` when it can't fail.
pub error: Json
/// What it `uses`, as written or as worked out (spec 8.1).
pub capabilities: [String]
/// Each `example` clause, as written (spec 7.6).
pub examples: [String]
}ParamSchema type
One parameter of a described function.
pub type ParamSchema {
pub name: String
pub schema: Json
}