Module B0_meta

Metadata.

Typed key-value dictionaries. These dictionaries are attached to various B0 definitions to specify metadata about them.

The module defines a few standard keys.

The recommended way of formatting constant dictionaries is:

let meta =
  B0_meta.empty
  |> B0_meta.(add authors) ["The project programmers"]
  |> B0_meta.(add homepage) "https://example.org"
  |> B0_meta.tag B0_opam.tag

Keys

type 'a key

The type for keys with lookup value of type 'a.

module Key : sig ... end

Keys.

Metadata

type t

The type for metadata.

val empty : t

empty is the empty metadata.

Predicates

val is_empty : t -> bool

is_empty m is true iff m is empty.

val mem : 'a key -> t -> bool

mem k m is true iff m has a binding for k.

val has_tag : bool key -> t -> bool

has_tag tag m is the value of tag in m or its default value (that is false for those tags created with Key.make_tag).

Raises Invalid_argument if tag has no default; regardless of whether tag is bound in m.

Adding and removing

val tag : bool key -> t -> t

tag k m is add k true m.

val add : 'a key -> 'a -> t -> t

add k v m is m with k bound to v.

val add_some : 'a key -> 'a option -> t -> t

add_some k o m is m if o is None and m with k bound to v if o is Some v.

val add_some_or_default : 'a key -> 'a option -> t -> t

add_some_or_default k o m is m with k bound to v if o is Some v and Key.default k otherwise. Raises Invalid_argument if k has no default (regardless of o's value).

val add_if_undef : 'a key -> 'a -> t -> t

add_if_undef k v m is m with k bound to v if k is unbound in m.

val override : t -> by:t -> t

override m ~by overrides bindings of m by those by. The result has all the bindings of by and those of m which are not in by.

val remove : 'a key -> t -> t

remove k m is m without a binding for k.

Lookup

val find : 'a key -> t -> 'a option

find k m is the binding of k in m (if any).

val find_or_default : 'a key -> t -> 'a

find_or_default k m is the binding of k in m or the default value of k. Raises Invalid_argument if k has no default; regardless of whether k is bound in m.

val get : 'a key -> t -> 'a

get k m is the binding of k in m. Raises Invalid_argument if there is no such binding. This does not lookup the default of k.

Bindings

type binding =
  1. | B : 'a key * 'a -> binding

The type for metadata bindings, a key and its value.

val find_binding : 'a key -> t -> binding option

find_binding k m is the binding for k in m (if any).

val find_binding_by_name : string -> t -> binding option

find_binding_by_name n m is the binding named n in m (if any).

val get_binding : 'a key -> t -> binding

find_binding k m is the binding for k in m. Raises Invalid_argument if there is no such binding.

val get_binding_by_name : string -> t -> binding

get_binding_by_name n m is the binding named n in m. Raises Invalid_argument if there is no such binding.

val pp_binding : binding B0_std.Fmt.t

pp_binding formats a binding using B0_std.Fmt.field and the key's value formatter.

Traversing

val fold : (binding -> 'a -> 'a) -> t -> 'a -> 'a

fold f m acc folds f over the bindings of m starting with acc.

Formatting

val pp : t B0_std.Fmt.t

pp formats metadata using pp_bindings.

val pp_non_empty : t B0_std.Fmt.t

pp_non_empty is B0_std.Fmt.cut followed by pp if metadata is non empty and B0_std.Fmt.nop otherwise.

Standard keys

End-user information

val authors : string list key

authors describes a list of persons with authorship.

val description_tags : string list key

description_tags describes a list of classification tags used for documentation.

val description : string key

description is a long description for the entity.

val homepage : string key

homepage is an URL to a project homepage.

val issues : string key

issues is an URL to an issue tracker.

val licenses : string list key

licenses describes a list of licenses. Each license should be a SPDX license identifier.

val maintainers : string list key

maintainers describe a list of persons with maintainership.

val online_doc : string key

online_doc is an URL to online documentation.

val repo : string key

repo is an URL to a VCS repository.

val synopsis : string key

synopsis is a one line synopsis for an entity.

Entity tags

val bench : bool key

bench tags benchmarking entities. Defaults to false.

val build : bool key

build tags build system entities. Defaults to false.

val dev : bool key

dev tags development entities. Defaults to false.

val doc : bool key

doc tags documentation entities. Defaults to false.

val exe : bool key

exe tags executable entities. Defaults to false.

val test : bool key

test tags testing entities. Defaults to false.

val lib : bool key

lib tags library entities. Defaults to false.

val public : bool key

public indicates if an entity is public. Defaults to false. The semantics depends on the context but it usually means that it exports the entity in an underlying global namespace.