Module Prelude.Prereq

Functions to test for the availability of external prerequisite commands.

Types

type validator =
  1. | Exists of string
    (*

    tests mere existence of an executable by name (perhaps in $PATH)

    *)
  2. | Succeeds of string list
    (*

    tests that the execution of the given argv actually succeeds with exit status 0

    *)
  3. | Stdout of string list * Stdlib.in_channel -> bool
    (*

    executes the argv and applies the function to the standard output

    *)
  4. | Stderr of string list * Stdlib.in_channel -> bool
    (*

    executes the argv and applies the function to the standard error

    *)

Different ways to check for the availability of a command.

Prerequisite Checking

val check : validator list -> (string, string) Stdlib.result list

(check prereqs) tests for the existence of all the commands in prereqs.

In the list of results, (Ok cmd) indicates that cmd passed the existence check, and (Error cmd) indicates that it failed.

If a Stdout or Stderr validator raised an unexpected exception, then the exception is appended to the command name.

Validation Result Helpers

val succeeds : ('a, 'b) Stdlib.result list -> bool

succeeds is true iff all the validation results are (Ok _).

val to_alist : ('a, 'a) Stdlib.result list -> ('a * bool) list

to_alist converts a validation result to an association list.

val fails : ('a, string) Stdlib.result list -> unit

fails raises a Failed_prerequisite exception if any of the validation results are Error _; otherwise it returns ().

The payload of the exception is a list of all the failed command names.

N.B. the exception will be caught and printed nicely by syserrors.

Validator Helpers

Function to help in writing validation functions for Stdout or Stderr.

val minversion : string -> Stdlib.in_channel -> bool

(minversion vnum) is a validation function to check that the command has a version number >= vnum.

The validator reads the first line (only) of the output on the channel and expects it to be exactly a version string, no more no less. This means you need to compose your argv to return just the version number.

Both vnum and the program's output will be processed with version_of_string.

Cmdliner Helpers

Functions to interoperate with Daniel Bünzli's Cmdliner.

val cmdliner : ?escape:(string -> string) -> ?sections:string list -> validator list -> string

(cmdliner ?escape ?sections prereqs) returns a string suitable for a `P element in a Cmdliner man page (say in a (`S "PREREQUISITES") section).

escape is a function that will be used to escape strings so that they don't get interpreted by the documentation markup language (default: no escaping). Cmdliner.Manpage.escape is recommended.

sections is a list of man page section numbers; it must be either the empty list (the default) or a parallel list of the same length as prereqs. Section numbers should be of the form "1", "8", "1p", and the like.