decode

atom

pub fn atom() -> Decoder(Atom)

Create a decoder that will attempt to transform a Dynamic into an Atom.

Note that in Erlang, values such as undefined, null, nil, and none are all atoms! In Elixir, nil is an atom as well.

atom_field

</>

pub fn atom_field(
  named: String,
  with decoder: Decoder(a),
) -> Decoder(a)

Create a decoder that takes a field name as a string and tries to turn it into an atom in order to access it. If the atom doesn’t exist, the field doesn’t either! And in that case the decoder will fail.

Atoms are commonly used as map fields in Erlang and Elixir; when accessing map keys that are atoms, this saves you the trouble of having to handle atom creation/error handling yourself.

bit_string

</>

pub fn bit_string() -> Decoder(BitString)

Create a decoder that will attempt to transform a Dynamic into a BitString.

bool

</>

pub fn bool() -> Decoder(Bool)

Create a decoder that will attempt to transform a Dynamic into a Bool.

decode_dynamic

</>

pub fn decode_dynamic(
  dynamic: Dynamic,
  with decoder: Decoder(a),
) -> Result(a, String)

Perform the actual decoding! Attempt turn some Dynamic data into the type of Gleam data specified by your decoder.

dynamic

</>

pub fn dynamic() -> Decoder(Dynamic)

Create a decoder that always succeeds with the Dynamic data provided, untouched.

This is useful when you are receiving particularly complex Dynamic data that you want to deal with later in your program (this might be useful when interfacing with Erlang or Elixir libraries, for example), or when you’re going to send it back out to Erlang or Elixir code and aren’t concerned about dealing with its structure in Gleam.

element

</>

pub fn element(
  at position: Int,
  with decoder: Decoder(a),
) -> Decoder(a)

Create a decoder that retrieves an element in a tuple at the given position.

fail

</>

pub fn fail(error: String) -> Decoder(a)

Create a decoder that always fails with the given value, ignoring the provided Dynamic data.

This is usually used with then and one_of.

field

</>

pub fn field(named: a, with decoder: Decoder(b)) -> Decoder(b)

Create a decoder that gets the value for a given field in a map. If the field you’re trying to access is an atom, consider using the atom_field function instead of this one.

float

</>

pub fn float() -> Decoder(Float)

Create a decoder that will attempt to transform a Dynamic into a Float.

from_result

</>

pub fn from_result(result: Result(a, String)) -> Decoder(a)

Create a decoder from a Result. Useful whenn used with then to transform a Dynamic value into a record/type.

int

</>

pub fn int() -> Decoder(Int)

Create a decoder that will attempt to transform a Dynamic into an Int.

list

</>

pub fn list(with decoder: Decoder(a)) -> Decoder(List(a))

Create a decoder for decoding a list of values.

map

</>

pub fn map(
  fun: fn(a) -> b,
  with decoder: Decoder(a),
) -> Decoder(b)

Create a decoder that, if successful, transforms the original value it was decoding into a different value.

Use map rather than then when your transformation function will never fail (that is, when it returns a val, rather than a Result(val, err). Use then when it might!

map2

</>

pub fn map2(
  fun: fn(a, b) -> c,
  decoder1: Decoder(a),
  decoder2: Decoder(b),
) -> Decoder(c)

Create a decoder from two decoders that, if both are successful, transforms those decoded values into a different value.

map2 and its siblings (map3, map4, etc.) are usually used to transform data such as Erlang records or Elixir maps into Gleam records/types.

map3

</>

pub fn map3(
  fun: fn(a, b, c) -> d,
  decoder1: Decoder(a),
  decoder2: Decoder(b),
  decoder3: Decoder(c),
) -> Decoder(d)

map4

</>

pub fn map4(
  fun: fn(a, b, c, d) -> e,
  decoder1: Decoder(a),
  decoder2: Decoder(b),
  decoder3: Decoder(c),
  decoder4: Decoder(d),
) -> Decoder(e)

map5

</>

pub fn map5(
  fun: fn(a, b, c, d, e) -> f,
  decoder1: Decoder(a),
  decoder2: Decoder(b),
  decoder3: Decoder(c),
  decoder4: Decoder(d),
  decoder5: Decoder(e),
) -> Decoder(f)

map6

</>

pub fn map6(
  fun: fn(a, b, c, d, e, f) -> g,
  decoder1: Decoder(a),
  decoder2: Decoder(b),
  decoder3: Decoder(c),
  decoder4: Decoder(d),
  decoder5: Decoder(e),
  decoder6: Decoder(f),
) -> Decoder(g)

map7

</>

pub fn map7(
  fun: fn(a, b, c, d, e, f, g) -> h,
  decoder1: Decoder(a),
  decoder2: Decoder(b),
  decoder3: Decoder(c),
  decoder4: Decoder(d),
  decoder5: Decoder(e),
  decoder6: Decoder(f),
  decoder7: Decoder(g),
) -> Decoder(h)

map8

</>

pub fn map8(
  fun: fn(a, b, c, d, e, f, g, h) -> i,
  decoder1: Decoder(a),
  decoder2: Decoder(b),
  decoder3: Decoder(c),
  decoder4: Decoder(d),
  decoder5: Decoder(e),
  decoder6: Decoder(f),
  decoder7: Decoder(g),
  decoder8: Decoder(h),
) -> Decoder(i)

ok_error_tuple

</>

pub fn ok_error_tuple(
  ok_decoder: Decoder(a),
  error_decoder: Decoder(a),
) -> Decoder(a)

A common pattern in Erlang and Elixir code is to, instead of raising a runtime error upon some function’s anticipated failure (resulting from something like bad arguments, or a failed database query or network request), return an {ok, Success} or {error, Failure} tuple (which would look like {:ok, success} or {:error, Failure} in Elixir) instead.

This function creates a decoder that addresses this common scenario by either running the ok_decoder if the Dynamic is a tuple whose first element is an ok atom, or the error_decoder if the Dynamic is a tuple whose first element is an error atom.

one_of

</>

pub fn one_of(decoders: List(Decoder(a))) -> Decoder(a)

Create a decoder that tries to decode a value with a list of different decoders.

string

</>

pub fn string() -> Decoder(String)

Create a decoder that will attempt to transform a Dynamic into a String.

succeed

</>

pub fn succeed(a: a) -> Decoder(a)

Create a decoder that always succeeds with the given value, ignoring the provided Dynamic data.