Module Odig.Pkg

module Pkg: sig .. end
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 : Odig.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 : Odig.Conf.t ->
([ `Pkg of t ] Odig.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 : Odig.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 : Odig.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.
val find_set : Odig.Conf.t -> Astring.String.set -> set * Astring.String.set
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 -> Odig.Cobj.set
cobjs p are p's compilation objects.
val conf : t -> Odig.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 Odig.Odoc and Odig.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 Odig.Conf.cachedir.
type cache_status = [ `Fresh | `New | `Stale ] 
The type for package status.
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 Odig.Pkg.cachedir. Ensures p's cache status becomes `New.