Skip to content

std::dynamic

Import with import std::dynamic.

type Dynamic

A value of unknown shape: one a host function returned, or one decoded from JSON, a database row or another outside source.

Nomi code cannot build a Dynamic directly. A host function that declares Dynamic in its return type produces one, and Json.to_dynamic makes one from a Json tree.

Read one with the navigators Dynamic.field, Dynamic.index and Dynamic.path, then an extractor such as Dynamic.as_string or Dynamic.as_int. Each step returns a Result whose Error names the path it failed at, so a chain propagates with ?.

import std::json.Json

d = Json.to_dynamic(Json.Obj{"name" => Json.String("Ada"), "age" => Json.Int(36)})
assert Dynamic.as_string(Dynamic.field(d, "name")?) == Ok("Ada")
assert Dynamic.as_int(Dynamic.field(d, "age")?) == Ok(36)
fn field(d: Dynamic, name: String) -> Result<Dynamic, Error>

type function on Dynamic

The value under name in an object. Err when d is an object without that field (expected is object with field "name"), or is not an object at all (expected is object).

import std::json.Json

d = Json.to_dynamic(Json.Obj{"name" => Json.String("Ada")})
assert Dynamic.field(d, "name") |> Result.flat_map(Dynamic.as_string) == Ok("Ada")
assert Result.is_err(Dynamic.field(d, "age"))
fn index(d: Dynamic, i: Int) -> Result<Dynamic, Error>

type function on Dynamic

The element at zero-based index i of a list. Err when d is a list without that index (expected is list with at least 3 elements for index 2), or is not a list at all (expected is list).

import std::json.Json

d = Json.to_dynamic(Json.Arr([Json.Int(7), Json.Int(8)]))
assert Dynamic.index(d, 1) |> Result.flat_map(Dynamic.as_int) == Ok(8)
assert Result.is_err(Dynamic.index(d, 2))
fn path(d: Dynamic, dotted: String) -> Result<Dynamic, Error>

type function on Dynamic

The value at a dotted path of field names: Dynamic.path(d, "a.b.c") is d |> Dynamic.field("a")? |> Dynamic.field("b")? |> Dynamic.field("c"). A path names fields only; use index for a list. An empty segment ("a..b") is an Err.

import std::json.Json

d = Json.to_dynamic(Json.Obj{"user" => Json.Obj{"name" => Json.String("Ada")}})
assert Dynamic.path(d, "user.name") |> Result.flat_map(Dynamic.as_string) == Ok("Ada")
assert Result.is_err(Dynamic.path(d, "user..name"))
fn as_string(d: Dynamic) -> Result<String, Error>

type function on Dynamic

d as a String, or Err when it holds anything else.

fn as_int(d: Dynamic) -> Result<Int, Error>

type function on Dynamic

d as an Int. A Float with no fractional part (JSON’s 36.0) is its whole number; one with a fractional part is an Err.

import std::json.Json

assert Dynamic.as_int(Json.to_dynamic(Json.Float(36.0))) == Ok(36)
assert Result.is_err(Dynamic.as_int(Json.to_dynamic(Json.Float(36.5))))
assert Result.is_err(Dynamic.as_int(Json.to_dynamic(Json.String("36"))))
fn as_float(d: Dynamic) -> Result<Float, Error>

type function on Dynamic

d as a Float. An Int is converted to a Float.

import std::json.Json

assert Dynamic.as_float(Json.to_dynamic(Json.Int(3))) == Ok(3.0)
fn as_bool(d: Dynamic) -> Result<Bool, Error>

type function on Dynamic

d as a Bool, or Err when it holds anything else.

fn as_list(d: Dynamic) -> Result<List<Dynamic>, Error>

type function on Dynamic

d as a List<Dynamic>, or Err when it is not a list. Each element is still a Dynamic, to decode in turn.

fn as_dict(d: Dynamic) -> Result<Map<String, Dynamic>, Error>

type function on Dynamic

d as a Map<String, Dynamic>, or Err when it is not an object. Each value is still a Dynamic, to decode in turn.

fn is_null(d: Dynamic) -> Bool

type function on Dynamic

Whether d is the source’s null (JSON null, Go nil).

fn has(d: Dynamic, name: String) -> Bool

type function on Dynamic

Whether d is an object with a field name. False when d is not an object.

fn as_maybe<T>(d: Dynamic, sub: (Dynamic) -> Result<T, Error>) -> Result<Maybe<T>, Error>

type function on Dynamic

sub applied to d unless d is null: Ok(None) for null, and Ok(Some(value)) when sub returns Ok(value). It reads a JSON field that may be null.

import std::json.Json

assert Dynamic.as_maybe(Json.to_dynamic(Json.Null), Dynamic.as_string) == Ok(None)
assert Dynamic.as_maybe(Json.to_dynamic(Json.String("x")), Dynamic.as_string) == Ok(Some("x"))
fn at_field<T>(d: Dynamic, name: String, sub: (Dynamic) -> Result<T, Error>) -> Result<T, Error>

type function on Dynamic

The field name of d, decoded by sub, with Field(name) put at the front of the path of any error sub returns. Nested calls

d
|> Dynamic.at_field("user", fn user ->
    Dynamic.at_field(user, "zip", Dynamic.as_int)
end)

give an error whose path is [Field("user"), Field("zip")] when as_int fails, which Display writes as decode error at user.zip: expected Int, got String. The chain

d
|> Dynamic.field("user")?
|> Dynamic.field("zip")?
|> Dynamic.as_int()

gives the same failure an empty path, since ? returns the Err as it is.

A missing field already carries [Field(name)] from field, and passes through unchanged.

import std::json.Json

d = Json.to_dynamic(Json.Obj{"user" => Json.Obj{"zip" => Json.String("x")}})
zip = Dynamic.at_field(d, "user", fn user -> Dynamic.at_field(user, "zip", Dynamic.as_int))

assert zip |> Result.map_err(&Display.to_string(&1)) == Err(
    "decode error at user.zip: expected Int, got String"
)
fn at_index<T>(d: Dynamic, i: Int, sub: (Dynamic) -> Result<T, Error>) -> Result<T, Error>

type function on Dynamic

The element at index i of d, decoded by sub, as at_field decodes a field: Index(i) goes at the front of the path of any error sub returns, and a missing index or a d that is not a list passes through unchanged.

impl Equatable for Dynamic

fn equal(a: Dynamic, b: Dynamic) -> Bool

impl Equatable.equal

Two Dynamic values are equal when their contents are, as JSON values: an object’s keys in any order, an Int never equal to a Float.

impl Hashable for Dynamic

fn hash(d: Dynamic) -> Int

impl Hashable.hash

A hash of the contents, alike for equal values.

impl Debug for Dynamic

fn inspect(d: Dynamic) -> String

impl Debug.inspect

enum PathSegment
    Field String
    Index Int
end

One segment of an Error’s path: Field for a field name, Index for a list index.

impl Debug for PathSegment

fn inspect(value: PathSegment) -> String

impl Debug.inspect

impl Display for PathSegment

fn to_string(value: PathSegment) -> String

impl Display.to_string

struct Error
    path: List<PathSegment>
    expected: String
    got: String
end

Why a Dynamic could not be read. expected and got name the mismatch, and path says where it was, one segment per navigator that added one. A chain of ? returns an Err as it is, so d |> Dynamic.field("a")? |> Dynamic.field("b")? |> Dynamic.as_int() gives an empty path when as_int fails. at_field and at_index add their segment to an error their decoder returns. Display writes decode error at a.b[3]: expected Int, got String, with <root> for an empty path.

impl Display for Error

fn to_string(e: Error) -> String

impl Display.to_string

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect