Module Config_file

module Config_file: sig .. end
This module implements a mechanism to handle configuration files. A configuration file is defined as a set of variable = value lines, where value can be a simple string (types int, string, bool...), a list of values between brackets (lists) or parentheses (tuples), or a set of variable = value lines between braces. The configuration file is automatically loaded and saved, and configuration parameters are manipulated inside the program as easily as references.

Object implementation by Jean-Baptiste Rouquier.

Low level interface

Skip this section on a first reading...
module Raw: sig .. end
The type of cp freshly parsed from configuration file, not yet wrapped in their proper type.

type 'a wrappers = {
   to_raw : 'a -> Raw.cp;
   of_raw : Raw.cp -> 'a;
A type used to specialize polymorphics classes and define new classes. Predefined wrappers are provided.
exception Wrong_type of (Pervasives.out_channel -> unit)
An exception raised by Config_file.cp.set_raw when the argument doesn't have a suitable Config_file.Raw.cp type. The function explains the problem and flush the output.

High level interface

The two main classes

class type ['a] cp = object .. end
A Configuration Parameter, in short cp, ie a value we can store in and read from a configuration file.
type groupable_cp = < get_default_formatted : Format.formatter -> unit;
get_formatted : Format.formatter -> unit; get_help : string;
get_help_formatted : Format.formatter -> unit; get_name : string list;
get_short_name : string option; get_spec : Arg.spec; reset : unit;
set_raw : Raw.cp -> unit >
Unification over all possible 'a cp: contains the main methods of 'a cp except the methods using the type 'a. A group manipulates only groupable_cp for homogeneity.
exception Double_name
Raised in case a name is already used. See
exception Missing_cp of groupable_cp
An exception possibly raised if we want to check that every cp is defined in a configuration file. See
class group : object .. end
A group of cps, that can be loaded and saved, or used to generate command line arguments.

Predefined cp classes

The last three non-optional arguments are always name (of type string list), default_value and help (of type string).

name is the path to the cp: ["section";"subsection"; ...; "foo"]. It can consists of a single element but must not be empty.

short_name will be added a "-" and used in

group, if provided, adds the freshly defined option to it (something like initializer group#add self).

help needs not contain newlines, it will be automatically truncated where needed. It is mandatory but can be "".

class int_cp : ?group:group -> string list -> ?short_name:string -> int -> string -> [int] cp
class float_cp : ?group:group -> string list -> ?short_name:string -> float -> string -> [float] cp
class bool_cp : ?group:group -> string list -> ?short_name:string -> bool -> string -> [bool] cp
class string_cp : ?group:group -> string list -> ?short_name:string -> string -> string -> [string] cp
class ['a] list_cp : 'a wrappers -> ?group:group -> string list -> ?short_name:string -> 'a list -> string -> ['a list] cp
class ['a] option_cp : 'a wrappers -> ?group:group -> string list -> ?short_name:string -> 'a option -> string -> ['a option] cp
class ['a] enumeration_cp : (string * 'a) list -> ?group:group -> string list -> ?short_name:string -> 'a -> string -> ['a] cp
class [['a, 'b]] tuple2_cp : 'a wrappers -> 'b wrappers -> ?group:group -> string list -> ?short_name:string -> 'a * 'b -> string -> [('a * 'b)] cp
class [['a, 'b, 'c]] tuple3_cp : 'a wrappers -> 'b wrappers -> 'c wrappers -> ?group:group -> string list -> ?short_name:string -> 'a * 'b * 'c -> string -> [('a * 'b * 'c)] cp
class [['a, 'b, 'c, 'd]] tuple4_cp : 'a wrappers -> 'b wrappers -> 'c wrappers -> 'd wrappers -> ?group:group -> string list -> ?short_name:string -> 'a * 'b * 'c * 'd -> string -> [('a * 'b * 'c * 'd)] cp
class string2_cp : ?group:group -> string list -> ?short_name:string -> string * string -> string -> [[string, string]] tuple2_cp
class font_cp : ?group:group -> string list -> ?short_name:string -> string -> string -> string_cp
class filename_cp : ?group:group -> string list -> ?short_name:string -> string -> string -> string_cp

Predefined wrappers

val int_wrappers : int wrappers
val float_wrappers : float wrappers
val bool_wrappers : bool wrappers
val string_wrappers : string wrappers
val list_wrappers : 'a wrappers -> 'a list wrappers
val option_wrappers : 'a wrappers -> 'a option wrappers
val enumeration_wrappers : (string * 'a) list -> 'a wrappers
If you have a type suit = Spades | Hearts | Diamond | Clubs, then
enumeration_wrappers ["spades",Spades"hearts",Hearts"diamond",Diamond"clubs",Clubs]

will allow you to use cp of this type.
For sum types with not only constant constructors,
you will need to define your own cp class.
val tuple2_wrappers : 'a wrappers ->
'b wrappers -> ('a * 'b) wrappers
val tuple3_wrappers : 'a wrappers ->
'b wrappers ->
'c wrappers -> ('a * 'b * 'c) wrappers
val tuple4_wrappers : 'a wrappers ->
'b wrappers ->
'c wrappers ->
'd wrappers -> ('a * 'b * 'c * 'd) wrappers

Defining new cp classes

class ['a] cp_custom_type : 'a wrappers -> ?group:group -> string list -> ?short_name:string -> 'a -> string -> ['a] cp
To define a new cp class, you just have to provide an implementation for the wrappers between your type foo and the type Raw.cp.

Backward compatibility


All the functions from the module Options are available, except:

The old configurations files are readable by this module.