# 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 (Stdlib.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 : `Stdlib.Format.formatter -> unit`;`
`` | `get_formatted : `Stdlib.Format.formatter -> unit`;`
`` | `get_help : `string`;`
`` | `get_help_formatted : `Stdlib.Format.formatter -> unit`;`
`` | `get_name : `string list`;`
`` | `get_short_name : `string option`;`
`` | `get_spec : `Stdlib.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 `Config_file.group.add`

    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 `Config_file.group.read`.

    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 `Config_file.group.command_line_args`.

`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

Deprecated.

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

- `prune_file`: use `group#write ?obsoletes:"foo.ml"`.
- `smalllist_to_value`, `smalllist_option`: use lists or tuples.
- `get_class`.
- `class_hook`: hooks are local to a cp. If you want hooks global to a class, define a new class that inherit from `Config_file.cp_custom_type`.
- `set_simple_option`, `get_simple_option`, `simple_options`, `simple_args`: use `Config_file.group.write`.
- `set_option_hook`: use `Config_file.cp.add_hook`.
- `set_string_wrappers`: define a new class with `Config_file.cp_custom_type`.

The old configurations files are readable by this module.