ocf 0.8.0 · OCaml Package

Reading and writing configuration files in JSON syntax

type path = string list

To represent option names from root.

module SMap : Map.S with type key = string

Errors

type error =

| Json_error of string
(*
JSON could not be read or written
*)
| Invalid_value of Yojson.Safe.t
(*
Unexpected JSON value
*)
| Invalid_path of path
(*
Invalid path used (empty list)
*)
| Path_conflict of path
(*
When adding an option, an option path cannot be the prefix of another one.
*)
| Error_at_path of path * error
(*
Error while reading the option at the given path.
*)
| Exn_at_path of path * exn
(*
Exception raised while reading the option at the given path
*)

exception Error of error

val string_of_error : error -> string

Convenient functions to raise `Error`

val json_error : string -> 'a

val invalid_value : Yojson.Safe.t -> 'a

val invalid_path : path -> 'a

val path_conflict : path -> 'a

val error_at_path : path -> error -> 'a

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

module Wrapper : sig ... end

type 'a wrapper = 'a Wrapper.t

Options and option groups

type '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.

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

val get : 'a conf_option -> 'a

get option returns the value of the given option.

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

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

type '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.

val group : [ `Open ] group

Create a new empty open group.

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

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

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

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

val 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

val int : ?doc:string -> ?cb:(int -> unit) -> int -> int conf_option

val float : ?doc:string -> ?cb:(float -> unit) -> float -> float conf_option

val bool : ?doc:string -> ?cb:(bool -> unit) -> bool -> bool conf_option

val string : 
  ?doc:string ->
  ?cb:(string -> unit) ->
  string ->
  string conf_option

val list : 
  ?doc:string ->
  ?cb:('a list -> unit) ->
  'a wrapper ->
  'a list ->
  'a list conf_option

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

val pair : 
  ?doc:string ->
  ?cb:(('a * 'b) -> unit) ->
  'a wrapper ->
  'b wrapper ->
  ('a * 'b) ->
  ('a * 'b) conf_option

val triple : 
  ?doc:string ->
  ?cb:(('a * 'b * 'c) -> unit) ->
  'a wrapper ->
  'b wrapper ->
  'c wrapper ->
  ('a * 'b * 'c) ->
  ('a * 'b * 'c) conf_option

val 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

val from_json : 'a group -> Yojson.Safe.t -> unit

val from_string : 'a group -> string -> unit

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

val to_json : ?with_doc:bool -> 'a group -> Yojson.Safe.t

val to_string : ?with_doc:bool -> 'a group -> string

val to_file : ?with_doc:bool -> 'a group -> string -> unit

Building command line arguments

val 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".

package ocf