Module B0_metaSource

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

Sourcetype 'a key

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

Sourcemodule Key : sig ... end

Keys.

Metadata

Sourcetype t

The type for metadata.

Sourceval empty : t

empty is the empty metadata.

Predicates

Sourceval is_empty : t -> bool

is_empty m is true iff m is empty.

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

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

Sourceval 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

Sourceval tag : bool key -> t -> t

tag k m is add k true m.

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

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

Sourceval 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.

Sourceval 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).

Sourceval 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.

Sourceval 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.

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

remove k m is m without a binding for k.

Lookup

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

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

Sourceval 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.

Sourceval 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

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

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

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

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

Sourceval find_binding_by_name : string -> t -> binding option

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

Sourceval 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.

Sourceval 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.

Sourceval pp_binding : binding B0_std.Fmt.t

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

Traversing

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

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

Formatting

pp formats metadata using pp_binding.

Sourceval 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

Sourceval authors : string list key

authors describes a list of persons with authorship.

Sourceval description_tags : string list key

description_tags describes a list of classification tags used for documentation.

Sourceval description : string key

description is a long description for the entity.

Sourceval homepage : string key

homepage is an URL to a project homepage.

Sourceval issues : string key

issues is an URL to an issue tracker.

Sourcetype spdxid = string

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

Sourceval 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.

Sourceval maintainers : string list key

maintainers describe a list of persons with maintainership.

Sourceval online_doc : string key

online_doc is an URL to online documentation.

Sourceval repo : string key

repo is an URL to a VCS repository.

Sourceval synopsis : string key

synopsis is a one line synopsis for an entity.

Entity tags

Sourceval bench : bool key

bench tags benchmarking entities. Defaults to false.

Sourceval build : bool key

build tags build system entities. Defaults to false.

Sourceval deprecated : bool key

deprecated tags deprectated entities. Defaults to false.

Sourceval dev : bool key

dev tags development entities. Defaults to false.

Sourceval doc : bool key

doc tags documentation entities. Defaults to false.

Sourceval exe : bool key

exe tags executable entities. Defaults to false.

Sourceval test : bool key

test tags testing entities. Defaults to false.

Sourceval lib : bool key

lib tags library entities. Defaults to false.

Sourceval long : bool key

long tags entities associated with a lengthy process. Defaults to false.

Sourceval 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.

Sourceval run : bool key

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

Sourceval sample : bool key

sample tags entities that exist for demonstration purposes.

Sourceval warning : string key

warning is a warning output on entity usage.