Config_file (p.config-file.1.2.2.doc.config-file.Config

Low level interface

Skip this section on a first reading...

Sourcemodule Raw : sig ... end

The type of Configuration Parameter, in short cp, freshly parsed from a configuration file, not yet wrapped in their proper type.

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

Sourceexception 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

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

Source

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.

Sourceexception Double_name

Raised in case a name is already used. See Config_file.group.add.

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

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

Sourceclass int_cp : ?group:group -> string list -> ?short_name:string -> int -> string -> int cp

Source

class float_cp : ?group:group -> string list -> ?short_name:string -> float -> string -> 
  float
    cp

Source

class bool_cp : ?group:group -> string list -> ?short_name:string -> bool -> string -> 
  bool
    cp

Source

class string_cp : ?group:group -> string list -> ?short_name:string -> string -> string -> 
  string
    cp

Source

class 'a list_cp : 'a wrappers -> ?group:group -> string list -> ?short_name:string -> 
  'a list -> string -> 'a list cp

Source

class 'a option_cp : 'a wrappers -> ?group:group -> string list -> ?short_name:string -> 
  'a
    option -> string -> 'a option cp

Source

class 'a enumeration_cp : (string * 'a) list -> ?group:group -> string list -> ?short_name:string -> 'a -> 
  string -> 'a cp

Source

class ['a, 'b] tuple2_cp : 'a wrappers -> 'b wrappers -> ?group:group -> string list -> ?short_name:
  string -> ('a * 'b) -> string -> ('a * 'b) cp

Source

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

Source

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

Source

class string2_cp : ?group:group -> string list -> ?short_name:string -> (string * string) -> 
  string -> [string, string] tuple2_cp

Source

class font_cp : ?group:group -> string list -> ?short_name:string -> string -> string -> 
  string_cp

Source

class filename_cp : ?group:group -> string list -> ?short_name:string -> string -> string -> 
  string_cp

Predefined wrappers

Sourceval int_wrappers : int wrappers

Sourceval float_wrappers : float wrappers

Sourceval bool_wrappers : bool wrappers

Sourceval string_wrappers : string wrappers

Sourceval list_wrappers : 'a wrappers -> 'a list wrappers

Sourceval option_wrappers : 'a wrappers -> 'a option wrappers

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

Sourceval tuple2_wrappers : 'a wrappers -> 'b wrappers -> ('a * 'b) wrappers

Source

val tuple3_wrappers : 
  'a wrappers ->
  'b wrappers ->
  'c wrappers ->
  ('a * 'b * 'c) wrappers

Source

val tuple4_wrappers : 
  'a wrappers ->
  'b wrappers ->
  'c wrappers ->
  'd wrappers ->
  ('a * 'b * 'c * 'd) wrappers

Defining new cp classes

Source

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