package odig

  1. Overview
  2. Docs

Packages.

Information about how packages are recognized and their data looked up is kept in odig help packaging.

TODO. Add a note about freshness and concurrent access.

Package names

type name = string

The type for package names.

val is_name : string -> bool

is_name n is true iff n is a valid package name. n must not be empty and be a valid path segment.

val name_of_string : string -> (name, [ `Msg of string ]) Pervasives.result

name_of_string s is Ok s if is_name s is true and an error message otherwise

val dir_is_package : Fpath.t -> name option

dir_is_package dir is Some name if a package named name is detected in directory dir.

Note At the moment function will not detect a package name if dir ends with a relative segment.

Packages and lookup

type t

The type for packages.

type set

The type for package sets.

val set : Conf.t -> (set, [ `Msg of string ]) Pervasives.result

set c is the set of all packages in configuration c.

FIXME. Currently results are memoized, which may not be suitable for long running programs.

val conf_cobj_index : Conf.t -> ([ `Pkg of t ] Cobj.Index.t, [ `Msg of string ]) Pervasives.result

conf_cobj_cobjs c is an index for all compilation objects in present in packages of configuration c. Query results are tagged with the package they belong to.

FIXME. Currently results are memoized, which may not be suitable for long running programs. Also this should be simpler to access from a given package.

val lookup : Conf.t -> name -> (t, [ `Msg of string ]) Pervasives.result

lookup c n is the package named n in c. An error is returned if n doesn't exist in c or if n is not a package name.

val find : Conf.t -> name -> t option

find c n tries to find a package named n in c. None is returned if n doesn't exist in c or if n is not a package name.

find_set c ns is (pkgs, not_found) where pkgs are the elements of ns which could be matched to a package in configuration c and not_found are those that could not be found or are not package names.

Basic properties

val field : err:'a -> (t -> ('a, [ `Msg of string ]) Pervasives.result) -> t -> 'a

field ~err field f is v if field p = Ok v and err otherwise.

val name : t -> name

name p is p's name.

val libdir : t -> Fpath.t

libdir p is p's library directory (has the compilation objects).

val docdir : t -> Fpath.t

docdir p is p's documentation directory.

val cobjs : t -> Cobj.set

cobjs p are p's compilation objects.

val conf : t -> Conf.t

conf p is the configuration in which p was found.

Package metadata (opam file)

val opam_file : t -> Fpath.t

opam_file p is p's expected opam file path.

val opam_fields : t -> (string list Astring.String.map, [ `Msg of string ]) Pervasives.result

opam_fields p is the package's opam fields. This is String.Set.empty opam_file p does not exist.

val license_tags : t -> (string list, [ `Msg of string ]) Pervasives.result

license_tags p is p's license: field.

val version : t -> (string option, [ `Msg of string ]) Pervasives.result

version p is p's version: field.

val homepage : t -> (string list, [ `Msg of string ]) Pervasives.result

version p is p's homepage: field.

val online_doc : t -> (string list, [ `Msg of string ]) Pervasives.result

online_doc p is p's doc: field.

val issues : t -> (string list, [ `Msg of string ]) Pervasives.result

issues p is p's bug-report: field.

val tags : t -> (string list, [ `Msg of string ]) Pervasives.result

tags p is p's tags: field.

val maintainers : t -> (string list, [ `Msg of string ]) Pervasives.result

maintainers p is p's maintainer: field.

val authors : t -> (string list, [ `Msg of string ]) Pervasives.result

authors p is p's authors: field.

val repo : t -> (string list, [ `Msg of string ]) Pervasives.result

repo p is p's dev-repo: field.

val deps : ?opts:bool -> t -> (Astring.String.set, [ `Msg of string ]) Pervasives.result

deps p are p's opam dependencies if opt is true (default) includes optional dependencies.

val depopts : t -> (Astring.String.set, [ `Msg of string ]) Pervasives.result

deps p are p's opam optional dependencies.

Standard distribution documentation

See Odoc and Ocamldoc for generated documentation.

val readmes : t -> (Fpath.t list, [ `Msg of string ]) Pervasives.result

readmes p are the readme files of p.

val change_logs : t -> (Fpath.t list, [ `Msg of string ]) Pervasives.result

change_logs p are the change log files of p.

val licenses : t -> (Fpath.t list, [ `Msg of string ]) Pervasives.result

licences p are the license files of p.

Predicates

val equal : t -> t -> bool

equal p p' is true if p and p' have the same name.

val compare : t -> t -> int

compare p p' is a total order on p and p''s names.

Package sets and maps

module Set : Asetmap.Set.S with type elt = t and type t = set

Package sets.

module Map : Asetmap.Map.S_with_key_set with type key = t and type key_set = Set.t

Package maps.

Classifying

val classify : ?cmp:('a -> 'a -> int) -> classes:(t -> 'a list) -> t list -> ('a * Set.t) list

Cache

val cachedir : t -> Fpath.t

cachedir p is p's cache directory, located somewhere in the configuration's Conf.cachedir.

type cache_status = [
  1. | `New
  2. | `Stale
  3. | `Fresh
]

The type for package status.

  • `New indicates that no cached information could be found for the package.
  • `Fresh indicates that cached information corresponds to the package install state. Warning. Freshness only refers to the root information handled by this module. For example a package may be fresh but it's API documentation may be stale.
  • `Stale indicates that cached information does not correspond to the package install's state
val cache_status : t -> (cache_status, [ `Msg of string ]) Pervasives.result

cache_status p is p's cache status.

val refresh_cache : t -> (unit, [ `Msg of string ]) Pervasives.result

refresh_cache p ensures p's cache status becomes `Fresh. Note. Clients usually don't need to call this as it is handled transparently by the API.

val clear_cache : t -> (unit, [ `Msg of string ]) Pervasives.result

clear_cache p deletes p's cachedir. Ensures p's cache status becomes `New.