convert - v1.0.0

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)

PartialConverter

opaque </>

Intermediate type to build a converter for an object type

pub opaque type PartialConverter(base)

Functions

bool

</> 
pub fn bool() -> Converter(Bool)

Basic converter for a Bool value

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 <- field("id", fn(v: Action) {
    case v {
      Open(id) -> Ok(id)
      _ -> Error(Nil)
    }
  }, string())
  success(Open(id:))
})

let close_converter = object({
  use id <- field("id", fn(v: Action) {
    case v {
      Close(id) -> Ok(id)
      _ -> Error(Nil)
    }
  }, string())
  success(Close(id:))
})

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

field

</> 
pub fn field(
  field_name: String,
  field_getter: fn(a) -> Result(b, Nil),
  field_type: Converter(b),
  next: fn(b) -> PartialConverter(a),
) -> PartialConverter(a)

Add a field to a PartialConverter
See object for its usage details

‘field_name’ is the field name that will be used in the converted value. It may not be equal to the actual field name.
‘field_getter’ is a function that returns the value of the field from the complete object.
‘field_type’ is a Converter associated to the type of the field.

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.

map

</> 
pub fn map(
  converter: Converter(a),
  encode_map: fn(b) -> a,
  decode_map: fn(a) -> Result(b, List(DecodeError)),
  default_value: b,
) -> Converter(b)

Create a converter by mapping the encode and decode functions from an existing one

Example:

pub type Date {
  Date(year: Int, month: Int, day: Int)
}

// We are storing the date as a string for optimized memory storage
pub fn date_converter() -> Converter(Date) {
  string()
  |> map(
    fn(v: Date) { [v.year, v.month, v.day] |> list.map(int.to_string) |> string.join("/") },
    fn(v: String) { 
      let elems = string.split(v, "/")
      case elems {
        [y, m, d, ..] -> Date(y, m, d)
        [y, m]  -> Date(y, m, -1)
        [y] -> Date(y, -1, -1)
        [] -> Date(-1, -1, -1)
      }
    }
  )
}

null

</> 
pub fn null() -> Converter(Nil)

Basic converter for a Nil value

object

</> 
pub fn object(converter: PartialConverter(a)) -> Converter(a)

Create a Converter from a PartialConverter

Example:

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

let convert = object({
  use name <- field("name", fn(v: Person) { Ok(v.name) }, string())
  use age <- field("age", fn(v: Person) { Ok(v.age) }, int())
  success(Person(name:, age:))
})

optional

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

Basic converter for a Option value.

of is a converter for the optional value.

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

success

</> 
pub fn success(c: a) -> PartialConverter(a)

Used to initialize a PartialConverter
See object for its usage details

type_def

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

Return the GlitrType associated with the converter

✨ Search Document