glitr/convert

Types

Converter

opaque </>

A converter is an object with the data necessary to encode and decode a specific Gleam type.
You can build converters using the provided constructors.

pub opaque type Converter(a)

GlitrType

</>

This type is used to define the shape of the data.
It isn’t meant to be used directly !
It is better to use converters that use GlitrTypes internally to decode data.

pub type GlitrType {
  String
  Bool
  Float
  Int
  Null
  List(of: GlitrType)
  Dict(key: GlitrType, value: GlitrType)
  Object(fields: List(#(String, GlitrType)))
  Optional(of: GlitrType)
  Result(result: GlitrType, error: GlitrType)
  Enum(variants: List(#(String, GlitrType)))
}

Constructors

```
String
```
```
Bool
```
```
Float
```
```
Int
```
```
Null
```
```
List(of: GlitrType)
```
```
Dict(key: GlitrType, value: GlitrType)
```

Object(fields: List(#(String, GlitrType)))

```
Optional(of: GlitrType)
```

Result(result: GlitrType, error: GlitrType)

Enum(variants: List(#(String, GlitrType)))

GlitrValue

</>

This type is used to represent data values.
It is an intermediate type between encoded data and Gleam types. It isn’t meant to be used directly !

pub type GlitrValue {
  StringValue(value: String)
  BoolValue(value: Bool)
  FloatValue(value: Float)
  IntValue(value: Int)
  NullValue
  ListValue(value: List(GlitrValue))
  DictValue(value: dict.Dict(GlitrValue, GlitrValue))
  ObjectValue(value: List(#(String, GlitrValue)))
  OptionalValue(value: option.Option(GlitrValue))
  ResultValue(value: Result(GlitrValue, GlitrValue))
  EnumValue(variant: String, value: GlitrValue)
}

Constructors

```
StringValue(value: String)
```
```
BoolValue(value: Bool)
```
```
FloatValue(value: Float)
```
```
IntValue(value: Int)
```
```
NullValue
```
```
ListValue(value: List(GlitrValue))
```

DictValue(value: dict.Dict(GlitrValue, GlitrValue))

ObjectValue(value: List(#(String, GlitrValue)))

OptionalValue(value: option.Option(GlitrValue))

ResultValue(value: Result(GlitrValue, GlitrValue))

EnumValue(variant: String, value: GlitrValue)

ObjectConverterBuilder

opaque </>

This is an intermediary type to build converters for a custom Gleam type.
TODO: rename

pub opaque type ObjectConverterBuilder(current, base)

ObjectDefinition

opaque </>

This is an intermediary type to build converters for a custom Gleam type.
TODO: rename

pub opaque type ObjectDefinition(current, base)

Functions

bool

</>

pub fn bool() -> Converter(Bool)

Basic converter for a Bool value

constructor

</>

pub fn constructor(c: fn() -> a) -> ObjectDefinition(Nil, a)

Specify that the next instruction returns a constructed instance of the type to convert.
See object()

decode

</>

pub fn decode(
  converter: Converter(a),
) -> fn(GlitrValue) -> Result(a, List(DecodeError))

Decode a GlitrValue using the provided converter.

dict

</>

pub fn dict(
  key: Converter(a),
  value: Converter(b),
) -> Converter(Dict(a, b))

Basic converter for a Dict value.

key is a converter for the keys. value is a converter for the values.

Example:

let converter: Converter(Dict(String, Int)) = dict(string(), int())

encode

</>

pub fn encode(converter: Converter(a)) -> fn(a) -> GlitrValue

Encode a value into the corresponding GlitrValue using the converter.
If the converter isn’t valid, a NullValue is returned.

enum

</>

pub fn enum(
  tags: fn(a) -> String,
  converters: List(#(String, Converter(a))),
) -> Converter(a)

Create a converter for an enum type

tags is a function that associate a tag to each variant of the enum converters is a list of converters, each associated with a tag

Example:

type Action {
  Open(id: String)
  Close(id: String)
}

let open_converter = object({
  use id <- parameter
  use <- constructor
  Open(id:)
})
|> field("id", fn(v) {
  case v {
    Open(id) -> Ok(id)
    _ -> Error(Nil)
  }
})
|> to_converter

let close_converter = object({
  use id <- parameter
  use <- constructor
  Close(id:)
})
|> field("id", fn(v) {
  case v {
    Close(id) -> Ok(id)
    _ -> Error(Nil)
  }
})
|> to_converter

let action_converter = enum(
  fn(v) {
    case v {
      Open(_) -> "Open"
      Close(_) -> "Close"
    }
  },
  [
    #("Open", open_converter),
    #("Close", close_converter),
  ]
)

field

</>

pub fn field(
  converter: ObjectConverterBuilder(#(a, b), c),
  field_name: String,
  field_getter: fn(c) -> Result(a, Nil),
  field_type: Converter(a),
) -> ObjectConverterBuilder(b, c)

Provide information about the fields of an object converter.

field_name is the key that will be used in the encoded data.
field_getter is a function returning a way to access the field from an instance.
field_type is the converter to use for this field.

See object() for an example.

float

</>

pub fn float() -> Converter(Float)

Basic converter for a Float value

int

</>

pub fn int() -> Converter(Int)

Basic converter for a Int value

list

</>

pub fn list(of: Converter(a)) -> Converter(List(a))

Basic converter for a List value.

of is a converter for the type of the elements.

null

</>

pub fn null() -> Converter(Nil)

Basic converter for a Nil value

object

</>

pub fn object(
  object_converter: ObjectDefinition(a, b),
) -> ObjectConverterBuilder(a, b)

Build a converter for a custom Gleam type.

Example:

type Person {
  Person(name: String, age: Int)
}

let converter = object({
  use name <- parameter
  use age <- parameter
  use <- constructor

  Person(name:, age:)
})
|> field("name", fn(v) { Ok(v.name) }, string())
|> field("age", fn(v) { Ok(v.age) }, int())
|> to_converter

optional

</>

pub fn optional(of: Converter(a)) -> Converter(Option(a))

Basic converter for a Option value.

of is a converter for the optional value.

parameter

</>

pub fn parameter(
  next: fn(a) -> ObjectDefinition(b, c),
) -> ObjectDefinition(#(a, b), c)

Specify a new parameter to be used in an object converter.
See object()

result

</>

pub fn result(
  res: Converter(a),
  error: Converter(b),
) -> Converter(Result(a, b))

Basic converter for a Result value.

res is a converter for the Ok value. error is a converter for the Error value.

string

</>

pub fn string() -> Converter(String)

Basic converter for a String value

to_converter

</>

pub fn to_converter(
  converter: ObjectConverterBuilder(Nil, a),
) -> Converter(a)

Generate a converter from a builder type

type_def

</>

pub fn type_def(converter: Converter(a)) -> GlitrType