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:

open B0_kit.V000 (* Defines the ~~ operator *)
let meta =
  B0_meta.empty
  |> ~~ B0_meta.authors ["The project programmers"]
  |> ~~ B0_meta.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_binding.

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.

type spdxid = string

The type for SPDX license identifiers. If your license is not in the list you can use anything if prefixed by "LicenseRef-".

val licenses : spdxid list key

licenses describes a list of licenses. Some processors like file generators consider the first license of this list to be the main license of your project and use it accordingly.

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 deprecated : bool key

deprecated tags deprectated 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 long : bool key

long tags entities associated with a lengthy process. 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.

val run : bool key

run tags entities that should be run in a particular context. Defaults to false.

val sample : bool key

sample tags entities that exist for demonstration purposes.

val warning : string key

warning is a warning shown on entity usage.