package ocf

  1. Overview
  2. Docs
package ocf
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module OcfSource

Reading and writing configuration files in JSON syntax

Sourcetype path = string list

To represent option names from root.

Sourcemodule SMap : Map.S with type key = string

Errors

Sourcetype error =
  1. | Json_error of string
    (*

    JSON could not be read or written

    *)
  2. | Invalid_value of Yojson.Safe.t
    (*

    Unexpected JSON value

    *)
  3. | Invalid_path of path
    (*

    Invalid path used (empty list)

    *)
  4. | Path_conflict of path
    (*

    When adding an option, an option path cannot be the prefix of another one.

    *)
  5. | Error_at_path of path * error
    (*

    Error while reading the option at the given path.

    *)
  6. | Exn_at_path of path * exn
    (*

    Exception raised while reading the option at the given path

    *)
Sourceexception Error of error
Sourceval string_of_error : error -> string

Convenient functions to raise Error

Sourceval json_error : string -> 'a
Sourceval invalid_value : Yojson.Safe.t -> 'a
Sourceval invalid_path : path -> 'a
Sourceval path_conflict : path -> 'a
Sourceval error_at_path : path -> error -> 'a
Sourceval exn_at_path : path -> exn -> 'a

Wrappers

A wrapper is a pair of functions to read and write values of some type from and to JSON.

Sourcemodule Wrapper : sig ... end
Sourcetype 'a wrapper = 'a Wrapper.t

Options and option groups

Sourcetype 'a conf_option

An option with a value of type 'a. When the option is found in a JSON code (see Reading options), the value is modified in place. Use get to retrieve the option value.

Sourceval option : ?doc:string -> ?cb:('a -> unit) -> 'a wrapper -> 'a -> 'a conf_option

option wrapper v creates an option with initial value v and using the given wrapper to read and write from and to JSON.

  • parameter doc

    an optional description for the option.

  • parameter cb

    an optional function to call each time the option is read.

Sourceval get : 'a conf_option -> 'a

get option returns the value of the given option.

Sourceval set : 'a conf_option -> 'a -> unit

set option value sets the value of the given option and calls the associated callback if any.

Sourcetype 'a group

A group is used to group options and other groups. An `Open group is a group in which other options and groups can be added. Nothing can be added to a `Closed group.

Sourceval group : [ `Open ] group

Create a new empty open group.

Sourceval add : [ `Open ] group -> path -> 'a conf_option -> [ `Open ] group

add group path option adds the given option to group at path.

Sourceval add_group : [ `Open ] group -> path -> 'a group -> [ `Open ] group

add_group group path g adds the group g to group at path.

Sourceval as_group : 'a conf_option -> [ `Closed ] group

as_group option creates a group from option, i.e. like if the given option had an empty access path. Useful for options created from a record wrapper using the ppx extension and that must be read as root element of a JSON file.

Convenient functions to create options

Sourceval int : ?doc:string -> ?cb:(int -> unit) -> int -> int conf_option
Sourceval float : ?doc:string -> ?cb:(float -> unit) -> float -> float conf_option
Sourceval bool : ?doc:string -> ?cb:(bool -> unit) -> bool -> bool conf_option
Sourceval string : ?doc:string -> ?cb:(string -> unit) -> string -> string conf_option
Sourceval list : ?doc:string -> ?cb:('a list -> unit) -> 'a wrapper -> 'a list -> 'a list conf_option
Sourceval option_ : ?doc:string -> ?cb:('a option -> unit) -> 'a wrapper -> 'a option -> 'a option conf_option
Sourceval pair : ?doc:string -> ?cb:(('a * 'b) -> unit) -> 'a wrapper -> 'b wrapper -> ('a * 'b) -> ('a * 'b) conf_option
Sourceval triple : ?doc:string -> ?cb:(('a * 'b * 'c) -> unit) -> 'a wrapper -> 'b wrapper -> 'c wrapper -> ('a * 'b * 'c) -> ('a * 'b * 'c) conf_option
Sourceval string_map : ?doc:string -> ?cb:('map -> unit) -> fold: ((string -> 'a -> Wrapper.assocs -> Wrapper.assocs) -> 'map -> Wrapper.assocs -> Wrapper.assocs) -> add:(string -> 'a -> 'map -> 'map) -> empty:'map -> 'a wrapper -> 'map -> 'map conf_option

See Wrapper.string_map for parameters.

Reading options

Sourceval from_json : 'a group -> Yojson.Safe.t -> unit
Sourceval from_string : 'a group -> string -> unit
Sourceval from_file : ?fail_if_not_exist:bool -> 'a group -> string -> unit
  • parameter fail_if_not_exist

    is false by default. In this case, no file is read and the values of the options of the group are not modified.

  • raises Sys_error

    if file does not exist and fail_if_not_exist is true.

  • raises Error

    if another error occurs.

Writing options

The following functions output the current state of the group, i.e. the options it contains, with their current value.

The with_doc parameter indicates whether to output doc associated to options. Default is true.

Sourceval to_json : ?with_doc:bool -> 'a group -> Yojson.Safe.t
Sourceval to_string : ?with_doc:bool -> 'a group -> string
Sourceval to_file : ?with_doc:bool -> 'a group -> string -> unit

Building command line arguments

Sourceval to_arg : 'a conf_option -> ?doc:Arg.doc -> Arg.key -> Arg.key * Arg.spec * Arg.doc

to_arg option key build a command line option description to use with the Arg module. If doc is not provided, then the description string of the option is used, if there is one; else the doc string is empty (preventing the option to appear in the list of options, see Arg module documentation). key is the option name, like "-n".