std::dynamic
Import with import std::dynamic.
Exports
Section titled “Exports”type Dynamic
Section titled “type 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)
Dynamic.field
Section titled “Dynamic.field”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"))
Dynamic.index
Section titled “Dynamic.index”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))
Dynamic.path
Section titled “Dynamic.path”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"))
Dynamic.as_string
Section titled “Dynamic.as_string”fn as_string(d: Dynamic) -> Result<String, Error>
type function on Dynamic
d as a String, or Err when it holds anything else.
Dynamic.as_int
Section titled “Dynamic.as_int”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"))))
Dynamic.as_float
Section titled “Dynamic.as_float”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)
Dynamic.as_bool
Section titled “Dynamic.as_bool”fn as_bool(d: Dynamic) -> Result<Bool, Error>
type function on Dynamic
d as a Bool, or Err when it holds anything else.
Dynamic.as_list
Section titled “Dynamic.as_list”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.
Dynamic.as_dict
Section titled “Dynamic.as_dict”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.
Dynamic.is_null
Section titled “Dynamic.is_null”fn is_null(d: Dynamic) -> Bool
type function on Dynamic
Whether d is the source’s null (JSON null, Go nil).
Dynamic.has
Section titled “Dynamic.has”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.
Dynamic.as_maybe
Section titled “Dynamic.as_maybe”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"))
Dynamic.at_field
Section titled “Dynamic.at_field”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"
)
Dynamic.at_index
Section titled “Dynamic.at_index”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.
Dynamic.equal
Section titled “Dynamic.equal”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.
Dynamic.hash
Section titled “Dynamic.hash”impl Hashable for Dynamic
fn hash(d: Dynamic) -> Int
impl Hashable.hash
A hash of the contents, alike for equal values.
Dynamic.inspect
Section titled “Dynamic.inspect”impl Debug for Dynamic
fn inspect(d: Dynamic) -> String
impl Debug.inspect
enum PathSegment
Section titled “enum PathSegment”enum PathSegment Field String Index Int end
One segment of an Error’s path: Field for a field name, Index for
a list index.
PathSegment.inspect
Section titled “PathSegment.inspect”impl Debug for PathSegment
fn inspect(value: PathSegment) -> String
impl Debug.inspect
PathSegment.to_string
Section titled “PathSegment.to_string”impl Display for PathSegment
fn to_string(value: PathSegment) -> String
impl Display.to_string
struct Error
Section titled “struct Error”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.
Error.to_string
Section titled “Error.to_string”impl Display for Error
fn to_string(e: Error) -> String
impl Display.to_string
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect