OCaml library to read and write configuration files in JSON syntax
Library ocf
Module Ocf
type path = string list

To represent option names from root.

module SMap : Map.S with type key = string


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


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