sashaafm / eetf / Eetf.Decode

Turn Erlang External Term Format (ETF) values into Elm values. Check out the official documentation to better understand how this library and the Erlang side work.

Primitives


type Decoder a

A value that knows how to decode ETF values.

This whole API is similar to elm/json. Maybe check the section about decoders in guide.elm-lang.org to better undestand how to use this module.

string : Decoder String

Decode an Erlang string into an Elm String.

Any Erlang atom or binary will be decoded successfully.

bool : Decoder Basics.Bool

Decode an Erlang boolean into an Elm Bool.

Either the Erlang atom true or false will be decoded sucessfully.

int : Decoder Basics.Int

Decode an Erlang integer into an Elm Int.

float : Decoder Basics.Float

Decode an Erlang float into an Elm Float.

Data structures

list : Decoder a -> Decoder (List a)

Decode an Erlang list into an Elm List.

array : Decoder a -> Decoder (Array a)

Decode an Erlang list into an Elm Array.

dict : Decoder ( comparable, a ) -> Decoder (Dict comparable a)

Decode an Erlang map into an Elm Dict.

The map's keys must be decoded into an Elm comparable due to Dict's limitations regarding the possible type for its keys.

keyValuePairs : Decoder ( a, b ) -> Decoder (List ( a, b ))

Decode an Erlang key-value pair list (usually called a proplist in Erlang, or a Keyword list in Elixir) into an Elm List of pairs.

tuple : Decoder a -> Decoder a

Decode an Erlang tuple of size 1 into an Elm Tuple.

tuple2 : Decoder a -> Decoder b -> Decoder ( a, b )

Decode an Erlang tuple of size 2 into an Elm Tuple.

tuple3 : Decoder a -> Decoder b -> Decoder c -> Decoder ( a, b, c )

Decode an Erlang tuple of size 3 into an Elm Tuple.

tupleN : Basics.Int -> Decoder a -> Decoder a

Decode an Erlang tuple, requiring a particular index.

record : String -> (a -> b) -> Decoder (a -> b)

DecodeErlang records into Elm records. This function is meant to be used with the andMap function like so:

person =
  record "person" Person
  |> andMap (tupleN 1 string)
  |> andMap (tupleN 2 int)

Where the record on the Erlang side is:

-record(person, {name = "Robert", age = 64}).

Object Primitives

field : String -> Decoder a -> Decoder a

Decode an Erlang key-value pair list (usually called a proplist in Erlang, or a Keyword list in Elixir) into an Elm List of pairs.

at : List String -> Decoder a -> Decoder a

Decode a nested Erlang map, requiring certain fields.

index : Basics.Int -> Decoder a -> Decoder a

Decode an Erlang list, requiring a particular index.

Incosistent Structure

maybe : Decoder a -> Decoder (Maybe a)

Helpful for dealing with optional fields.

oneOf : List (Decoder a) -> Decoder a

Try a bunch of different decoders. This can be useful if the Erlang Term may come in a couple of different formats.

A common use-case may be to handle Erlang's dynamic nature more easily. For example, certain function may have different return types (ok vs. {error, Reason}).

Run Decoders

decodeBytes : Decoder a -> Bytes -> Result Error a

Parse the given Bytes sequence into an Erlang Term Value and then run the Decoder on it. This will fail if the Bytes sequence is not a valid Erlang Term.

decodeValue : Decoder a -> Value -> Result Error a

Run a Decoder on some Erlang Term Value.


type alias Value =
Eetf.Term

Represents an External Term Format value.


type Error
    = WrongType String
    | InvalidTupleSize String
    | MapFieldNotFound String
    | IndexOutOfBounds String
    | IndexLesserThanZero String
    | NoMatchingDecoder String
    | UnableToDecode String
    | InvalidTerm String

A structured error describing exactly how the decoder failed. This is meant to help you understand and inform of the problem occurred during the decoding process.

Mapping

map : (a -> b) -> Decoder a -> Decoder b

Transform a decoder.

map2 : (a -> b -> c) -> Decoder a -> Decoder b -> Decoder c

Transform two decoders and then combine the result. This is useful to decode an Erlang map into an Elm Record.

map3 : (a -> b -> c -> d) -> Decoder a -> Decoder b -> Decoder c -> Decoder d

Transform three decoders and then combine the result. This is useful to decode an Erlang map into an Elm Record.

map4 : (a -> b -> c -> d -> e) -> Decoder a -> Decoder b -> Decoder c -> Decoder d -> Decoder e

Transform four decoders and then combine the result. This is useful to decode an Erlang map into an Elm Record.

map5 : (a -> b -> c -> d -> e -> f) -> Decoder a -> Decoder b -> Decoder c -> Decoder d -> Decoder e -> Decoder f

Transform five decoders and then combine the result. This is useful to decode an Erlang map into an Elm Record.

map6 : (a -> b -> c -> d -> e -> f -> g) -> Decoder a -> Decoder b -> Decoder c -> Decoder d -> Decoder e -> Decoder f -> Decoder g

Transform six decoders and then combine the result. This is useful to decode an Erlang map into an Elm Record.

map7 : (a -> b -> c -> d -> e -> f -> g -> h) -> Decoder a -> Decoder b -> Decoder c -> Decoder d -> Decoder e -> Decoder f -> Decoder g -> Decoder h

Transform seven decoders and then combine the result. This is useful to decode an Erlang map into an Elm Record.

map8 : (a -> b -> c -> d -> e -> f -> g -> h -> i) -> Decoder a -> Decoder b -> Decoder c -> Decoder d -> Decoder e -> Decoder f -> Decoder g -> Decoder h -> Decoder i

Transform eight decoders and then combine the result. This is useful to decode an Erlang map into an Elm Record.

Fancy Decoding

succeed : a -> Decoder a

Ignore the Erlang Term and produce a certain Elm value.

fail : String -> Decoder a

A decoder that always fails. This can be useful when using andThen to decode custom types.

andThen : (a -> Decoder b) -> Decoder a -> Decoder b

Create decoders that depend on previous results.

andMap : Decoder a -> Decoder (a -> c) -> Decoder c

Chain Decoders together to continually decode terms and mapping into a single value. Meant to be used alongside record to achieve something like this:

person =
  record "person" Person
  |> andMap (tupleN 1 string)
  |> andMap (tupleN 2 int)