MartinSStewart / elm-codec-bytes / Codec.Bytes

A Codec a contains a Bytes.Decoder a and the corresponding a -> Bytes.Encoder.

Definition


type Codec a

A value that knows how to encode and decode a sequence of bytes.


type alias Endianness =
Bytes.Endianness

The direction bytes are ordered in memory. Refer to the elm/bytes docs for more information.


type alias Encoder =
Bytes.Encode.Encoder

Describes how to generate a sequence of bytes.


type alias Bytes =
Bytes

A sequence of bytes. Refer to the elm/bytes docs for more information.

Decode


type alias Decoder a =
Bytes.Decode.Decoder a

Describes how to turn a sequence of bytes into a nice Elm value.

decoder : Codec a -> Decoder a

Extracts the Decoder contained inside the Codec.

decodeValue : Codec a -> Bytes -> Maybe a

Run a Codec to turn a sequence of bytes into an Elm value.

Encode

encoder : Codec a -> a -> Encoder

Extracts the encoding function contained inside the Codec.

encodeToValue : Codec a -> a -> Bytes

Convert an Elm value into a sequence of bytes.

Primitives

string : Codec String

Codec between a sequence of bytes and an Elm String

bool : Codec Basics.Bool

Codec between a sequence of bytes and an Elm Bool

char : Codec Char

Codec between a sequence of bytes and an Elm Char

signedInt : Codec Basics.Int

Codec between a signed 32-bit integer and an Elm Int. Use this if the byte ordering and number of bytes used isn't a concern.

unsignedInt : Codec Basics.Int

Codec between an unsigned 32-bit integer and an Elm Int. Use this if the byte ordering and number of bytes used isn't a concern.

float64 : Codec Basics.Float

Codec between a 64-bit float and an Elm Float

float32 : Codec Basics.Float

Codec between a 32-bit float and an Elm Float. Due to Elm Floats being 64-bit, encoding and decoding it as a 32-bit float won't exactly equal the original value.

signedInt32 : Endianness -> Codec Basics.Int

Codec between a signed 32-bit integer and an Elm Int

unsignedInt32 : Endianness -> Codec Basics.Int

Codec between an unsigned 32-bit integer and an Elm Int

signedInt16 : Endianness -> Codec Basics.Int

Codec between a signed 16-bit integer and an Elm Int

unsignedInt16 : Endianness -> Codec Basics.Int

Codec between an unsigned 16-bit integer and an Elm Int

signedInt8 : Codec Basics.Int

Codec between a signed 8-bit integer and an Elm Int

unsignedInt8 : Codec Basics.Int

Codec between an unsigned 8-bit integer and an Elm Int

bytes : Codec Bytes

Codec for Bytes. This is useful if you wanted to include binary data that you're going to decode elsewhere such as a PNG file.

Data Structures

maybe : Codec a -> Codec (Maybe a)

Represents an optional value.

list : Codec a -> Codec (List a)

Codec between a sequence of bytes and an Elm List.

array : Codec a -> Codec (Array a)

Codec between a sequence of bytes and an Elm Array.

dict : Codec comparable -> Codec a -> Codec (Dict comparable a)

Codec between a sequence of bytes and an Elm Dict.

set : Codec comparable -> Codec (Set comparable)

Codec between a sequence of bytes and an Elm Set.

tuple : Codec a -> Codec b -> Codec ( a, b )

Codec between a sequence of bytes and an Elm Tuple.

triple : Codec a -> Codec b -> Codec c -> Codec ( a, b, c )

Codec between a sequence of bytes and an Elm triple.

result : Codec error -> Codec value -> Codec (Result error value)

Codec for Result values.

Object Primitives


type ObjectCodec a b

A partially built Codec for an object.

object : b -> ObjectCodec a b

Start creating a Codec for an object. You should pass the main constructor as argument. If you don't have one (for example it's a simple type with no name), you should pass a function that given the field values builds an object.

type alias Point =
    { x : Int
    , y : Int
    }

pointCodec : Codec Point
pointCodec =
    Codec.object Point
        |> Codec.field .x Codec.signedInt
        |> Codec.field .y Codec.signedInt
        |> Codec.buildObject

field : (a -> f) -> Codec f -> ObjectCodec a (f -> b) -> ObjectCodec a b

Specify how to get a value from the object we want to encode and then give a Codec for that value.

buildObject : ObjectCodec a a -> Codec a

Create a Codec from a fully specified ObjectCodec.

Custom Types


type CustomCodec match v

A partially built Codec for a custom type.

custom : match -> CustomCodec match value

Starts building a Codec for a custom type. You need to pass a pattern matching function, see the FAQ for details.

type Semaphore
    = Red Int String Bool
    | Yellow Float
    | Green

semaphoreCodec : Codec Semaphore
semaphoreCodec =
    Codec.custom
        (\redEncoder yellowEncoder greenEncoder value ->
            case value of
                Red i s b ->
                    redEncoder i s b

                Yellow f ->
                    yellowEncoder f

                Green ->
                    greenEncoder
        )
        |> Codec.variant3 0 Red Codec.signedInt Codec.string Codec.bool
        |> Codec.variant1 1 Yellow Codec.float64
        |> Codec.variant0 2 Green
        |> Codec.buildCustom

variant0 : Basics.Int -> v -> CustomCodec (Encoder -> a) v -> CustomCodec a v

Define a variant with 0 parameters for a custom type.

variant1 : Basics.Int -> (a -> v) -> Codec a -> CustomCodec ((a -> Encoder) -> b) v -> CustomCodec b v

Define a variant with 1 parameters for a custom type.

variant2 : Basics.Int -> (a -> b -> v) -> Codec a -> Codec b -> CustomCodec ((a -> b -> Encoder) -> c) v -> CustomCodec c v

Define a variant with 2 parameters for a custom type.

variant3 : Basics.Int -> (a -> b -> c -> v) -> Codec a -> Codec b -> Codec c -> CustomCodec ((a -> b -> c -> Encoder) -> partial) v -> CustomCodec partial v

Define a variant with 3 parameters for a custom type.

variant4 : Basics.Int -> (a -> b -> c -> d -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> CustomCodec ((a -> b -> c -> d -> Encoder) -> partial) v -> CustomCodec partial v

Define a variant with 4 parameters for a custom type.

variant5 : Basics.Int -> (a -> b -> c -> d -> e -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> CustomCodec ((a -> b -> c -> d -> e -> Encoder) -> partial) v -> CustomCodec partial v

Define a variant with 5 parameters for a custom type.

variant6 : Basics.Int -> (a -> b -> c -> d -> e -> f -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> Codec f -> CustomCodec ((a -> b -> c -> d -> e -> f -> Encoder) -> partial) v -> CustomCodec partial v

Define a variant with 6 parameters for a custom type.

variant7 : Basics.Int -> (a -> b -> c -> d -> e -> f -> g -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> Codec f -> Codec g -> CustomCodec ((a -> b -> c -> d -> e -> f -> g -> Encoder) -> partial) v -> CustomCodec partial v

Define a variant with 7 parameters for a custom type.

variant8 : Basics.Int -> (a -> b -> c -> d -> e -> f -> g -> h -> v) -> Codec a -> Codec b -> Codec c -> Codec d -> Codec e -> Codec f -> Codec g -> Codec h -> CustomCodec ((a -> b -> c -> d -> e -> f -> g -> h -> Encoder) -> partial) v -> CustomCodec partial v

Define a variant with 8 parameters for a custom type.

buildCustom : CustomCodec (a -> Encoder) a -> Codec a

Build a Codec for a fully specified custom type.

Mapping

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

Transform a Codec.

Fancy Codecs

constant : a -> Codec a

Create a Codec that encodes nothing and always decodes as the same value.

lazy : (() -> Codec a) -> Codec a

This is useful for recursive structures that are not easily modeled with recursive.

type Peano
    = Peano (Maybe Peano)

{-| This is the same example used in Codec.recursive but adapted for lazy.
-}
peanoCodec : Codec Peano
peanoCodec =
    Codec.maybe (Codec.lazy (\() -> peanoCodec)) |> Codec.map Peano (\(Peano a) -> a)

Warning: lazy is not stack safe! If you have something like Peano (Just (Peano Just (...))) nested within itself sufficiently many times and you try to use peanoCodec on it, you'll get a stack overflow!

recursive : (Codec a -> Codec a) -> Codec a

Create a Codec for a recursive data structure. The argument to the function you need to pass is the fully formed Codec, see the FAQ for details.

type Peano
    = Peano (Maybe Peano)

peanoCodec : Codec Peano
peanoCodec =
    Codec.recursive
        (\finishedCodec ->
            Codec.maybe finishedCodec
                |> Codec.map Peano (\(Peano p) -> p)
        )

Warning: recursive is not stack safe! If you have something like Peano (Just (Peano Just (...))) nested within itself sufficiently many times and you try to use peanoCodec on it, you'll get a stack overflow!

customWithIdCodec : Codec Basics.Int -> match -> CustomCodec match value

Same as custom but here we can choose what codec to use for the integer id we tell apart variants with. This is useful if, for example, you know you won't have ids outside of the range 0 - 255 and can use unsignedInt8 instead of the default signedInt32 to save some space.