pooka/json

Any JSON value.

null

true or false

A number written without a fraction or exponent, such as 42.

A number written with a fraction or exponent, such as 2.5 or 1e3.

A string, with its escapes already resolved.

An array.

An object, as its entries in the order they were written. A key that appears twice is kept twice; get returns the first.

A promise an application value can make without joining Json's closed family. The class chooses its JSON shape; the ordinary writers handle the text.

import pooka/json
import pooka/json.{Encodable}

class Bird(name: String) with Encodable {
  to_json() -> json.Json {
    json.JObject([#("name", json.JString(name))])
  }
}

assert json.encode_value(Bird("Ada")) == "{\"name\":\"Ada\"}"

Why a text is not JSON.

The text stopped in the middle of a value.

A byte that cannot appear where it was found, as its numeric value.

A broken escape or invalid UTF-8 inside a string.

A syntactically valid number whose magnitude is outside the BEAM Float range.

An input byte or nesting limit was exceeded before building the value tree.

Read one JSON document.

import pooka/json

assert json.decode("[1, true]") == Ok(json.JArray([json.JInt(1), json.JBool(True)]))
assert json.decode("[1,") == Error(json.UnexpectedEnd())

A sentence for the person who wrote the text.

import pooka/json

assert json.describe(json.UnexpectedEnd()) == "the JSON text ended too early"

Write a value as compact JSON, with no spaces.

import pooka/json

let owl = json.JObject([#("name", json.JString("Ada")), #("age", json.JInt(3))])
assert json.encode(owl) == "{\"name\":\"Ada\",\"age\":3}"

Write a value as JSON for people, indented by two spaces.

import pooka/json

assert json.encode_pretty(json.JArray([json.JInt(1), json.JInt(2)])) == "[\n  1,\n  2\n]"

Write an application value through its Encodable promise, as compact JSON. Existing Json values continue to use encode directly.

// With the Bird class from Encodable's example:
assert json.encode_value(Bird("Ada")) == "{\"name\":\"Ada\"}"

Write an application value through Encodable, indented by two spaces.

// With the Bird class from Encodable's example:
assert json.encode_value_pretty(Bird("Ada")) == "{\n  \"name\": \"Ada\"\n}"

The value under a key, if this is an object that has it.

import pooka/json

let assert Ok(owl) = json.decode("{\"name\": \"Ada\"}")
assert json.get(owl, "name") == Some(json.JString("Ada"))
assert json.get(owl, "wings") == None

Follow several keys, one object inside another.

import pooka/json

let assert Ok(nest) = json.decode("{\"owl\": {\"name\": \"Ada\"}}")
assert json.path(nest, ["owl", "name"]) == Some(json.JString("Ada"))

The item at a position, counting from zero, if this is an array that has it.

import pooka/json

let assert Ok(row) = json.decode("[10, 20]")
assert json.at(row, 1) == Some(json.JInt(20))

The text, if this is a string.

The number, if this is a whole number.

The number as a Float. JSON does not tell 3 from 3.0, so both are accepted here.

The truth value, if this is true or false.

The items, if this is an array.

The entries, if this is an object.

Is this null?

Parse untrusted input with explicit byte and container-depth budgets. A scalar has depth zero. A negative budget rejects every input.

assert json.decode_with_limits("[[1]]", 100, 1) == Error(json.LimitExceeded("depth"))