Gist (typegist.Typegist.Type.Gist)

Names

type name = string

The type for unqualified names (without the module path). For example t, int, signal, Left, `Left. See also qualified_name.

type qualified_name = string

The type for qualified names. These are names prefixed by the module path to access them from the top-level scope. For example Buffer.t, int, Sys.signal, Either.Left, `Left. See also name.

type applied_name = string

The type for applied type names. This can be the qualified name of a type definition (e.g. Buffer.t) or a qualified type constructor name with instantiated variables (e.g. (int, string) Hashtbl.t). This is what we use for naming gists, in particular for monomorphic instances of polymorphic types.

module Name : sig ... end

Name munging.

Metadata

module Meta : sig ... end

Gist metadata.

Gists

type 'a t

The type for representing a type of type 'a.

type 'a gist := 'a t

See t.

type v =

| V : 'a t -> v

The type for existential gists.

Properties

val name : 'a t -> applied_name

name g is the applied name of g or "" if g is a nameless type expression.

val doc : 'a t -> string

doc g is the documentation string of g.

val id : 'a t -> 'a Stdlib.Type.Id.t

id g is the typed identifier of g.

val meta : 'a t -> 'a Meta.t

meta g is the metadata of g.

module Expr : sig ... end

Type expressions for gist processors.

val expr : 'a t -> 'a Expr.t

expr g is the type expression of g.

val gists : 'a t -> v list

gists g is the list of unique (as per id) gists found in g's expression. This includes g if g is recursive.

Predicates

val is_recursive : 'a t -> bool

is_recursive g is true if and only if g is a recursive definition. This means that the id of g can be found in the list returned by gists. This talks about the gist definition, not the represented type. For example is_recursive (list int) is false despite list being a recursive type.

val has_gist : 'a t -> 'b t -> bool

has_gist sub g is true iff sub can be found in g's definition.

val is_nameless : 'a t -> bool

is_nameless g is true iff name g = "".

Updating

update and rebind allow to update gist metadata and make sure other gists use the up-to-date definition, see this entry of the cookbook. In contrast of_gist updates and attributes a new identity to a gist, see this entry in the cookbook for an example where this may be useful.

val update : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a Meta.t ->
  ?expr:'a Expr.t ->
  'a t ->
  'a t

update ?name ?doc ?meta g update the given properties in g. The result has the same id.

val rebind : 'a t -> 'b t -> 'b t

rebind r g substitutes by r all gist occurences identified by id r in the type expression of g. Returns r if id g = id r. See this example.

val replace : 'a t -> by:'a t -> 'b t -> 'b t

replace g ~by g' replaces all occurences of g in g' by the by gist. In constrast to rebind, by may change the identity of g.

val of_gist : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a Meta.t ->
  ?expr:'a Expr.t ->
  'a t ->
  'a t

of_gist g is like update but it attributes a new identity to the result. Note that the result cannot be used to rebind g.

Formatting

val pp_def : Stdlib.Format.formatter -> 'a t -> unit

pp_def g formats an OCaml looking type definition for g. If the name of g is "" this is Expr.pp, otherwise it has the form type applied_name = ….

val pp_type_arg : single:bool -> Stdlib.Format.formatter -> 'a t -> unit

pp_type_arg ~single g prints g as a type argument for a polymorphic type. If single is true it is expected to be the single argument, if false it is expected to be in a list of arguments, this affects parenthesising which for example differs for 'a between 'a list and ('a, 'b) Hashtbl.t.

Representations

val todo : ?doc:string -> ?meta:'a Meta.t -> qualified_name -> 'a t

todo name represents the type name but remains to be described. Generic functions raise Invalid_argument when they hit the stub.

Scalars

Scalar gist values represent the built-in scalar types.

module Scalar : sig ... end

Scalar types for gist processors.

val unit : unit t

unit represents the unit type.

val bool : bool t

bool represents the bool type.

val char : char t

char represents the char type.

val uchar : Stdlib.Uchar.t t

uchar represents the Uchar.t type.

val int : int t

int represents the int type.

val int32 : int32 t

int32 represent the int32 type.

val int64 : int64 t

int64 represents the int64 type.

val nativeint : nativeint t

nativeint represents the nativeint type.

val float : float t

float represents the float type.

Fields and products

Tuples, records and variant cases are all products of types. The representation distinguishes them in different top-level cases but otherwise they share the same representation: a product of typed and possibly named fields.

module Field : sig ... end

Fields.

module Product : sig ... end

Products for gist processors.

val field' : 
  ('p, 'v) Field.t ->
  ('p, 'v -> 'ctor, 'ret) Product.cons ->
  ('p, 'ctor, 'ret) Product.cons

field f p adds f to the construction of p.

val field : 
  ?doc:string ->
  ?meta:('p, 'v) Meta.t2 ->
  ?set:('p -> 'v -> unit) ->
  ?iset:('p -> 'v -> 'p) ->
  string ->
  'v t ->
  ('p -> 'v) ->
  ('p, 'v -> 'ctor, 'ret) Product.cons ->
  ('p, 'ctor, 'ret) Product.cons

field name g get cons defines a named field for a product 'v. This just combines Field.make and field'. This is for record fields and variant inline records.

val comp : 
  ?doc:string ->
  ?meta:('p, 'v) Meta.t2 ->
  ?iset:('p -> 'v -> 'p) ->
  'v t ->
  ('p -> 'v) ->
  ('p, 'v -> 'ctor, 'ret) Product.cons ->
  ('p, 'ctor, 'ret) Product.cons

comp is like field but it is nameless. Use it for tuple or variant case components.

val finish : ('p, 'p, 'ret) Product.cons -> 'ret

finish finishes the construction of the product.

Tuples

Tuple gist values represent finite arity tuples. See examples.

module Tuple : sig ... end

Tuples for gist processors.

val tuple : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'p Meta.t ->
  'ctor ->
  ('p, 'ctor, 'p t) Product.cons

tuple ctor starts a tuple type whose values are constructed with ctor to be satured with Type.Gist.comp fields and finished with finish.

val t2 : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:('a * 'b) Meta.t ->
  'a t ->
  'b t ->
  ('a * 'b) t

t2 c0 c1 represents pairs of type c0 * c1.

val t3 : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:('a * 'b * 'c) Meta.t ->
  'a t ->
  'b t ->
  'c t ->
  ('a * 'b * 'c) t

t3 c0 c1 c2 represents triplets of type c0 * c1 * c2.

val t4 : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:('a * 'b * 'c * 'd) Meta.t ->
  'a t ->
  'b t ->
  'c t ->
  'd t ->
  ('a * 'b * 'c * 'd) t

t4 c0 c1 c2 c3 represents quadruplets of type c0 * c1 * c2 * c3.

Records

Record gist values represent record types. See examples.

module Record : sig ... end

Records for gist processors.

val record : 
  ?doc:string ->
  ?meta:'r Meta.t ->
  applied_name ->
  'ctor ->
  ('r, 'ctor, 'r t) Product.cons

record name ctor starts a record type named named whose values are constructed with ctor to be satured with Type.Gist.fields and finished with finish.

Variants

Variant gist values represent variant types. A couple of standard variants are distinguished and have direct combinators to construct them. See examples.

module Variant : sig ... end

Variants for gist processors.

module Variant_like : sig ... end

Variant likes for gist processors.

val option : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a option Meta.t ->
  'a t ->
  'a option t

option g represents an 'a option type for the type represented by g.

val either : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:('a, 'b) Stdlib.Either.t Meta.t ->
  'a t ->
  'b t ->
  ('a, 'b) Stdlib.Either.t t

either l r represents an ('l, 'r) Either.t type for the types represented by l and g.

val result : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:('a, 'b) Stdlib.result Meta.t ->
  'a t ->
  'b t ->
  ('a, 'b) Stdlib.result t

result ok error represents a ('ok, 'error) result type for the types represented by ok and error.

val list : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a list Meta.t ->
  'a t ->
  'a list t

list elt represents a 'elt list type for the type represented by elt.

Generic variants

Generic variants (and polymorphic variants) are described by a list of case types and a function that indicates which case to use for a value of the type. See examples.

val case : 
  ?doc:string ->
  Variant.Case.name ->
  'ctor ->
  ('v, 'ctor, 'v Variant.Case.t) Product.cons

case name ctor starts a variant case type with constructor name name whose values are constructed with ctor to be saturated with either Type.Gist.comp or Type.Gist.field (for inline records) and finished with finish.

val variant : 
  ?doc:string ->
  ?meta:'v Meta.t ->
  ?name:applied_name ->
  'v Variant.Case.t list ->
  case_index:('v -> int) ->
  'v t

variant ~name cases case_index is a variant type with cases described by cases and whose values are attributed a case in the cases list with the zero-based case_index function. name should only be possibly omitted if you are describing a polymorphic variant.

val variant_of_enum : 
  ?doc:string ->
  ?meta:'v Meta.t ->
  ?name:applied_name ->
  (Variant.Case.name * 'v) list ->
  'v t

variant_of_enum ~name cases is a variant from the given 0-ary case enumeration. name should only be possibly omitted if you are describing a polymorphic variant.

Array likes

Array like gist values represent linear array types. A couple of standard array types are distinguished and have direct combinators to construct them. See examples.

module Array_like : sig ... end

Array likes for gist processors.

val bytes : bytes t

bytes represents mutable the type for sequence of bytes.

val utf_8_bytes : bytes t

utf_8_bytes represents the type for mutable, UTF-8 encoded, text strings.

val binary_string : string t

binary_string represents the type for immutable sequences of bytes.

val utf_8_string : string t

string_as_utf_8 represent the type for immutable, UTF-8 encoded, text strings.

val array : 
  ?name:string ->
  ?doc:string ->
  ?meta:'elt array Meta.t ->
  'elt t ->
  'elt array t

array elt represents the type for arrays with elements of type elt.

val iarray : 
  ?name:string ->
  ?doc:string ->
  ?meta:'elt iarray Meta.t ->
  'elt t ->
  'elt iarray t

array elt represents the type for immutable arrays with elements of type elt.

val bigarray1 : 
  ?name:string ->
  ?doc:string ->
  ?meta:('elt, 'b, 'c) Stdlib.Bigarray.Array1.t Meta.t ->
  'elt t ->
  ('elt, 'b) Stdlib.Bigarray.kind ->
  'c Stdlib.Bigarray.layout ->
  ('elt, 'b, 'c) Stdlib.Bigarray.Array1.t t

bigarray1 elt kind layout represents the type of linear bigarrays stored with kind according to layout and accessed with elt elements.

Other bigarrays dimensions are supported as views over linear bigarrays. See bigarray2, bigarray3 and bigarraygen.

val bigbytes : 
  (int, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout)
    Stdlib.Bigarray.Array1.t
    t

bigbytes is bigarray1 ~name:"bigbytes" int Int8_unsigned C_layout.

val floatarray : floatarray t

floatarray is an array_module for floatarrays.

val dynarray : 
  ?name:string ->
  ?doc:string ->
  ?meta:'elt Stdlib.Dynarray.t Meta.t ->
  'elt t ->
  'elt Stdlib.Dynarray.t t

dynarray elt is an array_module for an Dynarray.t type with elements of type elt.

val weak : 
  ?name:string ->
  ?doc:string ->
  ?meta:'elt Stdlib.Weak.t Meta.t ->
  'elt t ->
  'elt Stdlib.Weak.t t

weak elt is an array_module for a Weak.t type with elements of type elt.

val array_module : 
  ?name:string ->
  ?doc:string ->
  ?meta:'array Meta.t ->
  'elt t ->
  ('elt, 'array) Array_like.module' ->
  'array t

array_module elt array represents an array type array with elements of type elt.

Map likes

Map like gist values represent key-value maps. This is either mutable map types like hashtables or immutable key-value maps. See examples.

module Map_like : sig ... end

Map likes for gist processors.

val hashtbl : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:('k, 'v) Stdlib.Hashtbl.t Meta.t ->
  'k t ->
  'v t ->
  ('k, 'v) Stdlib.Hashtbl.t t

hashtbl k v represents the Hashtbl.t type with type of keys k and type of values of type v.

val map : 
  qualified_name ->
  (module Map : Stdlib.Map.S)
  ->
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'v Map.t Meta.t ->
  Map.key t ->
  'v t ->
  'v Map.t t

map "Map.t" (module Map) k v represents the Map.t type with type of keys k and type of values of type v.

val hashtbl_module : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'hashtbl Meta.t ->
  'k t ->
  'v t ->
  ('k, 'v, 'hashtbl) Map_like.hashtbl_module ->
  'hashtbl t

hashbl_module k v h represents a hashtbl of type h with keys of type k and values of type v.

val map_module : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'map Meta.t ->
  'k t ->
  'v t ->
  ('k, 'v, 'map) Map_like.map_module ->
  'map t

map_module k v m represents a map of type m with keys of type k and values of type v.

Cell likes

Cell like gist values represent cell types. A couple of standard cell types are distinguished and have direct combinators to construct them. See examples.

module Cell_like : sig ... end

Cell likes for gist processors.

val lazy' : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a lazy_t Meta.t ->
  'a t ->
  'a lazy_t t

lazy' g represents a lazy cell type on values of type g.

val ref : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a Stdlib.ref Meta.t ->
  'a t ->
  'a Stdlib.ref t

ref g represents a reference cell type on values of type g.

val atomic : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a Stdlib.Atomic.t Meta.t ->
  'a t ->
  'a Stdlib.Atomic.t t

atomic g represents an atomic cell type on values of type g.

val cell_module : 
  ?name:string ->
  ?doc:string ->
  ?meta:'cell Meta.t ->
  'a t ->
  ('a, 'cell) Cell_like.module' ->
  'cell t

cell_module contents cell represents a cell type cell with contents type contents.

Functions

Function gist values represent function types. See examples.

module Func : sig ... end

Functions for gist processors.

val func : 
  ?name:string ->
  ?doc:string ->
  ?meta:('a -> 'b) Meta.t ->
  'a t ->
  'b t ->
  ('a -> 'b) t

func a b represents a function from domain of type a to a range of type b.

val (@->) : 'a t -> 'b t -> ('a -> 'b) t

a @-> b is func a b.

Abstract types

Abstract gist values represent abstract types by lists of public versioned representations. See examples.

module Abstract : sig ... end

Abstract type representations.

val abstract : 
  ?doc:string ->
  ?meta:'a Meta.t ->
  ?version_index:('a -> int) ->
  applied_name ->
  'a Abstract.Version.t list ->
  'a t

abstract name versions represents the abstract type name by the public representations versions. If versions is the empty list, the abstract type remains fully opaque.

The zero-based version_index function attribute versions from the list versions to the values of the type. It defaults to Fun.const (List.length versions - 1) which assumes all values are expressed in the last (latest) public representation of versions.

Views

A view gist value represent a type by the type of another gist value. See examples.

module View : sig ... end

Views for gist processors.

val view : 
  ?name:applied_name ->
  ?doc:string ->
  ?meta:'a Meta.t ->
  inject:('a -> 'b) ->
  project:('b -> 'a) ->
  'b t ->
  'a t

view inject project g represents a type by viewing as values the type g with inject and back with project.

Recursion

Recursive gist values tie the knot for representing recursive types. See examples.

val rec' : 'a t lazy_t -> 'a t

rec' g is the recursive type defined by g.

Other `Stdlib` types

These gists are for standard library types which are not directly expressed in the representation. They are provided here so that they are given a unique identity or polymorphic definition that libraries and processors can agree on. Some types may be missing do not hesitate to open an issue about it.

val complex : Stdlib.Complex.t t

complex represents the Complex.t type by a record gist.

val bigarray2 : 
  ?doc:string ->
  ?meta:('elt, 'b, 'c) Stdlib.Bigarray.Array2.t Meta.t ->
  'elt t ->
  ('elt, 'b) Stdlib.Bigarray.kind ->
  'c Stdlib.Bigarray.layout ->
  ('elt, 'b, 'c) Stdlib.Bigarray.Array2.t t

bigarray2 elt kind layout represents the type of 2D bigarrays by viewing them as their dimension sizes tupled with a reshaped bigarray1.

val bigarray3 : 
  ?doc:string ->
  ?meta:('elt, 'b, 'c) Stdlib.Bigarray.Array3.t Meta.t ->
  'elt t ->
  ('elt, 'b) Stdlib.Bigarray.kind ->
  'c Stdlib.Bigarray.layout ->
  ('elt, 'b, 'c) Stdlib.Bigarray.Array3.t t

bigarray3 elt kind layout represents the type of 3D bigarrays by viewing them as their dimensions sizes tupled with a reshaped bigarray1.

val bigarraygen : 
  ?doc:string ->
  ?meta:('elt, 'b, 'c) Stdlib.Bigarray.Genarray.t Meta.t ->
  'elt t ->
  ('elt, 'b) Stdlib.Bigarray.kind ->
  'c Stdlib.Bigarray.layout ->
  ('elt, 'b, 'c) Stdlib.Bigarray.Genarray.t t

bigarraygen elt kind layout represents the type of generic bigarrays by viewing them as their dimensions sizes tupled with a reshaped bigarray1.

val digest : Stdlib.Digest.t t

digest represents the Digest.t type by a binary_string under a new identity.

val digest_blake128 : Stdlib.Digest.BLAKE128.t t

digest_blake128 represents the Digest.BLAKE128.t type by a binary_string under a new identity.

val digest_blake256 : Stdlib.Digest.BLAKE256.t t

digest_blake256 represents the Digest.BLAKE256.t type by a binary_string under a new identity.

val digest_blake512 : Stdlib.Digest.BLAKE512.t t

digest_blake512 represents the Digest.BLAKE512.t type by a binary_string under a new identity.

val digest_md5 : Stdlib.Digest.MD5.t t

digest_md5 represents the Digest.MD5.t type by a binary_string under a new identity.

val float_fp_class : Stdlib.Float.fpclass t

float_fp_class represents the Float.fpclass as a variant gist.

val gc_stat : Stdlib.Gc.stat t

gc_stat represents the Gc.stat type by a record gist.

val gc_control : Stdlib.Gc.control t

gc_stat represents the Gc.control type by a record gist.

val pqueue_max : 
  applied_name ->
  (module Pqueue : Stdlib.Pqueue.Max)
  ->
  ?doc:string ->
  ?meta:Pqueue.t Meta.t ->
  Pqueue.elt t ->
  Pqueue.t t

pqueue_min name (module Pqueue) elt represents the given Pqueue.t type by viewing it as type of list of type elt. Injecting into the list does not consume the queue elements.

val pqueue_max_poly : 
  applied_name ->
  (module Pqueue : Stdlib.Pqueue.MaxPoly)
  ->
  ?doc:string ->
  ?meta:'a Pqueue.t Meta.t ->
  'a Pqueue.elt t ->
  'a Pqueue.t t

pqueue_min_poly name (module Pqueue) elt represents the given Pqueue.t type by viewing it as type of list of type elt. Injecting into the list does not consume the queue elements.

val pqueue_min : 
  applied_name ->
  (module Pqueue : Stdlib.Pqueue.Min)
  ->
  ?doc:string ->
  ?meta:Pqueue.t Meta.t ->
  Pqueue.elt t ->
  Pqueue.t t

pqueue_min name (module Pqueue) elt represents the given Pqueue.t type by viewing it as type of list of type elt. Injecting into the list does not consume the queue elements.

val pqueue_min_poly : 
  applied_name ->
  (module Pqueue : Stdlib.Pqueue.MinPoly)
  ->
  ?doc:string ->
  ?meta:'a Pqueue.t Meta.t ->
  'a Pqueue.elt t ->
  'a Pqueue.t t

pqueue_min_poly name (module Pqueue) elt represents the given Pqueue.t type by viewing it as type of list of type elt. Injecting into the list does not consume the queue elements.

val queue : 
  ?doc:string ->
  ?meta:'a Stdlib.Queue.t Meta.t ->
  'a t ->
  'a Stdlib.Queue.t t

queue elt represents a 'elt Queue.t type for the type represented by elt by viewing the queue as a list. Injecting into the list does not consume the queue elements.

val random_state : Stdlib.Random.State.t t

random_state represents the Random.State.t type as a view over its serialization to binary strings (see Random.State.to_binary_string).

val set : 
  applied_name ->
  (module Set : Stdlib.Set.S)
  ->
  ?doc:string ->
  ?meta:Set.t Meta.t ->
  Set.elt t ->
  Set.t t

set name (module Set) elt represents the given Set.t type by viewing it as type of list of type elt.

val stack : 
  ?doc:string ->
  ?meta:'a Stdlib.Stack.t Meta.t ->
  'a t ->
  'a Stdlib.Stack.t t

stack elt represents a 'elt Stack.t type for the type represented by elt by viewing the queue as a list. Injecting into the list does not consume the stack elements.

val sys_signal : Stdlib.Sys.signal t

sys_signal represents the Sys.signal type by an int scalar under a new identity.

Names

Metadata

Gists

Properties

Predicates

Updating

Formatting

Representations

Scalars

Fields and products

Tuples

Records

Variants

Generic variants

Array likes

Map likes

Cell likes

Functions

Abstract types

Views

Recursion

Other Stdlib types

Other `Stdlib` types