glitr/convert

Types

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)

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)))

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)

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

pub opaque type ObjectConverterBuilder(current, base)

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

pub opaque type ObjectDefinition(current, base)

Functions

pub fn bool() -> Converter(Bool)

Basic converter for a Bool value

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()

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

Decode a GlitrValue using the provided converter.

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())
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.

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),
  ]
)
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.

pub fn float() -> Converter(Float)

Basic converter for a Float value

pub fn int() -> Converter(Int)

Basic converter for a Int value

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.

pub fn null() -> Converter(Nil)

Basic converter for a Nil value

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
pub fn optional(of: Converter(a)) -> Converter(Option(a))

Basic converter for a Option value.

of is a converter for the optional value.

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()

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.

pub fn string() -> Converter(String)

Basic converter for a String value

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

Generate a converter from a builder type

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