package pidgin

  1. Overview
  2. Docs

Module Pidgin.ReprSource

Broadly speaking, Pidgin describes a "generic" key-value language that serves as an intermediate format between several other key-value formats (such as JSON, TOML, YAML, etc.). Repr describes the abstract representation of this language.

Types

The generic representation of the language is relatively straightforward (and compact), closely resembling the representation chosen to describe JSON.

To construct terms that are more complex than those offered by the generic representation, the module provides combinators that allow for a high degree of flexibility in description.

Since type t is non-abstract, this allows for the creation of data structures that may seem unusual (such as empty records); however, in practice, checking static invariants complicates the use of the library and results in a lack of flexibility. Since conversion functions to t` are generally associated with validation functions, it is assumed that the validations will handle these unusual cases.

Sourcetype t =
  1. | Null
  2. | Bool of bool
  3. | Int of int
  4. | Float of float
  5. | String of string
  6. | List of t list
  7. | Record of (string * t) list

The generic representation of language.

Sourcetype 'a conv = 'a -> t

Describes a function that converts an arbitrary value to t. Since 'a is in contravariant position, 'a conv is a contravariant functor that can be used with using.

Sourcemodule type PROJECTABLE = sig ... end

Describes a module in which t can be projected into a pidgin representation.

Term construction

Combinators for constructing values in the representation t.

Sourceval null : 'a conv

Discard the input and returns Null.

Sourceval bool : bool conv

bool converter.

Sourceval int : int conv

int converter.

Sourceval float : float conv

float converter.

Sourceval string : string conv

string converter.

Sourceval char : char conv

char converter

Sourceval list : t list conv

list converter.

Sourceval list_of : 'a conv -> 'a list conv

list_of conv l build a list of t using conv.

Sourceval record : ?normalize_keys:bool -> (string * t) list conv

Build a record. If the flag normalize_keys is true (default value) keys are lowercased and trimmed.

Specific terms

Make use of the minimal nature of ASTs to construct more complex expressions. Mostly using records.

Sourceval option : 'a conv -> 'a option conv

option conv converter for option. use null for describing None and conv for Some.

Sourceval sum : ('a -> string * t) -> 'a -> t

sum f x produce a sum-type for a given x. The function f return a couple of constructor-name and value. The result is wrapped into the following record: {constr = "constr-name"; value = value}.

Sourceval pair : 'a conv -> 'b conv -> ('a * 'b) conv

pair fst snd (a, b) produce a product type for a given pair a, b. The result is wrapped into the following record: {first = a; second = b}.

Sourceval result : ok:'a conv -> error:'b conv -> ('a, 'b) result conv

result ~ok ~error is a converter for result values. It uses sum under the hood.

Sourceval either : left:'a conv -> right:'b conv -> ('a, 'b) Either.t conv

either ~ok ~error is a converter for Either values. It uses sum under the hood.

Sourceval triple : ('a -> t) -> ('b -> t) -> ('c -> t) -> ('a * 'b * 'c) conv

triple ca cb cd is a converter for triples. Under the hood, triple are pair.

Sourceval int32 : int32 conv

int32 is a converter for int32. It use {constr = "int32"; value = string n} as an underlying representation.

Sourceval int64 : int64 conv

int64 is a converter for int64. It use {constr = "int64"; value = string n} as an underlying representation.

Sourceval nel : t Nel.t conv

Non empty list converter.

Sourceval nel_of : 'a conv -> 'a Nel.t conv

nel_of conv l build a non-empty-list of t using conv.

Specific converters

Sourceval into : (module PROJECTABLE with type t = 'a) -> 'a conv

into (module Proj) converts value using Proj.to_pidgin.

Mapping

Sourceval using : ('b -> 'a) -> 'a conv -> 'b conv

using f conv is a contramap. If we have a function from b to a, then we can get a conversion from a to t to b to t.

Sourceval replace : 'b -> 'b conv -> 'a conv

replace k is using (fun _ -> k).

Equality

Sourceval equal : t -> t -> bool

Equality between terms.

Misc

Sourceval to_string : t -> string

Convert a Repr to a string.

Case analysis using folds

Enables case analysis by using folds (catamorphisms) to standardize access to the various branches of the AST.

Sourceval fold : null:(unit -> 'a) -> bool:(bool -> 'a) -> int:(int -> 'a) -> float:(float -> 'a) -> string:(string -> 'a) -> list:(t list -> 'a) -> record:((string * t) list -> 'a) -> t -> 'a

Exhaustive match over t.

Sourceval fold_partial : ?null:(unit -> 'a) -> ?bool:(bool -> 'a) -> ?int:(int -> 'a) -> ?float:(float -> 'a) -> ?string:(string -> 'a) -> ?list:(t list -> 'a) -> ?record:((string * t) list -> 'a) -> (t -> 'a) -> t -> 'a

Partial match over t.

Infix operators

Sourcemodule Infix : sig ... end

Some infix helpers.

include module type of Infix
Sourceval (<$>) : ('b -> 'a) -> 'a conv -> 'b conv

f <$> conv is using f conv.