config-file 1.2.1 · OCaml Package

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 Configuration Parameter, in short cp, freshly parsed from a 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 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 flushes the output.

High level interface

The two main classes

class type 'a cp = object ... end

A Configuration Parameter, in short cp, i.e. a value we can store in and read from a configuration file.

type groupable_cp =
  < get_name : string list
  ; get_short_name : string option
  ; get_help : string
  ; get_formatted : Format.formatter -> unit
  ; get_default_formatted : Format.formatter -> unit
  ; get_help_formatted : Format.formatter -> unit
  ; 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 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

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

deprecated