gleam/dynamic

Types

Decoder

pub type Decoder(t) =
  fn(Dynamic) -> Result(t, String)

Dynamic

Dynamic data is data that we don"t know the type of yet. We likely get data like this from interop with Erlang, or from IO with the outside world.

pub external type Dynamic

Functions

any

pub fn any(
  from data: Dynamic,
  of decoders: List(fn(Dynamic) -> Result(a, String)),
) -> Result(a, String)

Join multiple decoders into one. When run they will each be tried in turn until one succeeds, or they all fail.

Examples

> import gleam/result
> let bool_or_string = any(_, of: [
>   string,
>   fn(x) { result.map(bool(x), fn(_) { "a bool" }) }
> ])
> bool_or_string(from("ok"))
Ok("ok")

> bool_or_string(from(True))
Ok("a bool")

> bool_or_string(from(1))
Error("Unexpected value")

atom

pub external fn atom(
  from: Dynamic,
) -> Result(atom_mod.Atom, String)

Check to see whether a Dynamic value is an atom, and return the atom if it is.

Examples

> import gleam/atom
> atom(from(atom.create_from_string("hello")))
OK("hello")

> atom(from(123))
Error("Expected an Atom, got `123`")

bit_string

pub external fn bit_string(
  from: Dynamic,
) -> Result(BitString, String)

Check to see whether a Dynamic value is a bit_string, and return the bit_string if it is.

Examples

> bit_string(from("Hello")) == bit_string.from_string("Hello")
True

> bit_string(from(123))
Error("Expected a BitString, got `123`")

bool

pub external fn bool(from: Dynamic) -> Result(Bool, String)

Check to see whether a Dynamic value is an bool, and return the bool if it is.

Examples

> bool(from(True))
Ok(True)

> bool(from(123))
Error("Expected a Bool, got `123`")

element

pub external fn element(
  from: Dynamic,
  position: Int,
) -> Result(Dynamic, String)

Check to see if the Dynamic value is a tuple large enough to have a certain index, and return the value of that index if it is.

Examples

> element(from(tuple(1, 2)), 0)
Ok(from(1))

> element(from(tuple(1, 2)), 2)
Error("Expected a tuple of at least 3 size, got a tuple of 2 size")

> element(from(""), 2)
Error("Expected a tuple, got a binary")

field

pub external fn field(
  from: Dynamic,
  named: a,
) -> Result(Dynamic, String)

Check to see if a Dynamic value is a map with a specific field, and return the value of the field if it is.

This will not succeed on a record.

Examples

> import gleam/map
> field(from(map.new("Hello", "World")), "Hello")
Ok(Dynamic)

> field(from(123), "Hello")
Error("Expected a map with key `\"Hello\"`, got an Int")

float

pub external fn float(from: Dynamic) -> Result(Float, String)

Check to see whether a Dynamic value is an float, and return the float if it is.

Examples

> float(from(2.0))
Ok(2.0)

> float(from(123))
Error("Expected a Float, got `123`")

from

pub external fn from(a) -> Dynamic

Convert any Gleam data into Dynamic data.

int

pub external fn int(from: Dynamic) -> Result(Int, String)

Check to see whether a Dynamic value is an int, and return the int if it is.

Examples

> int(from(123))
Ok(123)

> int(from("Hello"))
Error("Expected an Int, got `\"Hello World\"`")

list

pub external fn list(
  from: Dynamic,
) -> Result(List(Dynamic), String)

Check to see whether a Dynamic value is a list, and return the list if it is.

If you wish to decode all the elements in the list use the typed_list instead.

Examples

> list(from(["a", "b", "c"]))
Ok([from("a"), from("b"), from("c")])

> list(1)
Error("Expected an Int, got a binary")

map

pub external fn map(
  from: Dynamic,
) -> Result(Map(Dynamic, Dynamic), String)

Check to see if the Dynamic value is map.

Examples

> import gleam/map as map_mod
> map(from(map_mod.new()))
Ok(map_mod.new())

> map(from(1))
Error("Expected a 2 element tuple, got an int")

> map(from(""))
Error("Expected a map, got a binary")

option

pub fn option(
  from dynamic: Dynamic,
  of decoder: fn(Dynamic) -> Result(a, String),
) -> Result(Option(a), String)

Check to see if a Dynamic value is an Option of a particular type, and return the Option if it is.

The second argument is a decoder function used to decode the elements of the list. The list is only decoded if all elements in the list can be successfully decoded using this function.

Examples

> option(from("Hello"), string)
Ok(Some("Hello"))

> option(from(atom.from_string("null")), string)
Ok(None)

> option(from(123), string)
Error("Expected a bit_string, got an int")

string

pub fn string(from: Dynamic) -> Result(String, String)

Check to see whether a Dynamic value is a string, and return the string if it is.

Examples

> string(from("Hello"))
Ok("Hello")

> string(from(123))
Error("Expected a String, got `123`")

thunk

pub external fn thunk(
  from: Dynamic,
) -> Result(fn() -> Dynamic, String)

Check to see whether a Dynamic value is a function that takes no arguments, and return the function if it is.

Examples

> import gleam/result
> let f = fn() { 1 }
> thunk(from(f)) |> result.is_ok
True

> thunk(from(123))
Error("Expected a zero arity function, got `123`")

tuple2

pub external fn tuple2(
  from: Dynamic,
) -> Result(tuple(Dynamic, Dynamic), String)

Check to see if the Dynamic value is a 2 element tuple.

If you do not wish to decode all the elements in the tuple use the typed_tuple2 function instead.

Examples

> tuple2(from(tuple(1, 2)))
Ok(tuple(from(1), from(2)))

> tuple2(from(tuple(1, 2)))
Error("Expected a 2 element tuple")

> tuple2(from(""))
Error("Expected a tuple, got a binary")

typed_list

pub fn typed_list(
  from dynamic: Dynamic,
  of decoder_type: fn(Dynamic) -> Result(a, String),
) -> Result(List(a), String)

Check to see whether a Dynamic value is a list of a particular type, and return the list if it is.

The second argument is a decoder function used to decode the elements of the list. The list is only decoded if all elements in the list can be successfully decoded using this function.

If you do not wish to decode all the elements in the list use the list function instead.

Examples

> typed_list(from(["a", "b", "c"]), of: string)
Ok(["a", "b", "c"])

> typed_list(from([1, 2, 3]), of: string)
Error("Expected an Int, got a binary")

> typed_list(from("ok"), of: string)
Error("Expected a List, got a binary")

typed_tuple2

pub fn typed_tuple2(
  from tup: Dynamic,
  first decode_first: fn(Dynamic) -> Result(a, String),
  second decode_second: fn(Dynamic) -> Result(b, String),
) -> Result(tuple(a, b), String)

Check to see if the Dynamic value is a 2 element tuple containing two specifically typed elements.

If you wish to decode all the elements in the list use the typed_tuple2 instead.

Examples

> typed_tuple2(from(tuple(1, 2)), int, int)
Ok(tuple(1, 2))

> typed_tuple2(from(tuple(1, 2.0)), int, float)
Ok(tuple(1, 2.0))

> typed_tuple2(from(tuple(1, 2, 3)), int, float)
Error("Expected a 2 element tuple, got a 3 element tuple")

> typed_tuple2(from(""), int, float)
Error("Expected a tuple, got a binary")

unsafe_coerce

pub external fn unsafe_coerce(Dynamic) -> a

Unsafely cast a Dynamic value into any other type.

This is an escape hatch for the type system that may be useful when wrapping native Erlang APIs. It is to be used as a last measure only!

If you can avoid using this function, do!