rc.mli 7.94 KB
Newer Older
MARCHE Claude's avatar
manager  
MARCHE Claude committed
1 2
(**************************************************************************)
(*                                                                        *)
Jean-Christophe Filliâtre's avatar
headers  
Jean-Christophe Filliâtre committed
3
(*  Copyright (C) 2010-                                                   *)
MARCHE Claude's avatar
MARCHE Claude committed
4 5 6
(*    François Bobot                                                     *)
(*    Jean-Christophe Filliâtre                                          *)
(*    Claude Marché                                                      *)
Jean-Christophe Filliâtre's avatar
headers  
Jean-Christophe Filliâtre committed
7
(*    Andrei Paskevich                                                    *)
MARCHE Claude's avatar
manager  
MARCHE Claude committed
8 9 10
(*                                                                        *)
(*  This software is free software; you can redistribute it and/or        *)
(*  modify it under the terms of the GNU Library General Public           *)
Jean-Christophe Filliâtre's avatar
headers  
Jean-Christophe Filliâtre committed
11
(*  License version 2.1, with the special exception on linking            *)
MARCHE Claude's avatar
manager  
MARCHE Claude committed
12 13 14 15 16 17 18 19
(*  described in file LICENSE.                                            *)
(*                                                                        *)
(*  This software is distributed in the hope that it will be useful,      *)
(*  but WITHOUT ANY WARRANTY; without even the implied warranty of        *)
(*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                  *)
(*                                                                        *)
(**************************************************************************)

Francois Bobot's avatar
Francois Bobot committed
20
(** Rc file management *)
MARCHE Claude's avatar
manager  
MARCHE Claude committed
21

Francois Bobot's avatar
Francois Bobot committed
22
(** {2 Exception} *)
23

24 25 26 27 28 29 30 31 32
type rc_value =
  | RCint of int
  | RCbool of bool
  | RCfloat of float
  | RCstring of string
  | RCident of string

(* exception SyntaxError *)
exception ExtraParameters of string
Francois Bobot's avatar
Francois Bobot committed
33 34 35 36
(** [ExtraParameters name] One section of name [name] has two many
    parameters : more than one if [name] is a family, more than none
    if [name] is a section *)

37
exception MissingParameters of string
Francois Bobot's avatar
Francois Bobot committed
38 39 40
(** [MissingParameters name] One section of a family [name] has no
    parameters *)

41 42
(* exception UnknownSection of string *)
exception UnknownField of string
Francois Bobot's avatar
Francois Bobot committed
43 44
(** [UnknownField key] The key [key] appeared in a section but is not
    expected there *)
45 46
(* exception MissingSection of string *)
exception MissingField of string
Francois Bobot's avatar
Francois Bobot committed
47
(** [MissingField key] The field [key] is required but not given *)
48
exception DuplicateSection of string
Francois Bobot's avatar
Francois Bobot committed
49
(** [DuplicateSection name] section [name] appears more than once *)
50
exception DuplicateField of string * rc_value * rc_value
Francois Bobot's avatar
Francois Bobot committed
51
(** [DuplicateField key] key [key] appears more than once *)
52
exception StringExpected of string * rc_value
Francois Bobot's avatar
Francois Bobot committed
53 54 55
(** [StringExpected key value] string expected *)
(* exception IdentExpected of string * rc_value *)
(* (\** [IdentExpected key value] string expected *\) *)
56
exception IntExpected of string * rc_value
Francois Bobot's avatar
Francois Bobot committed
57
(** [IntExpected key value] int expected *)
58
exception BoolExpected of string * rc_value
Francois Bobot's avatar
Francois Bobot committed
59 60 61 62
(** [BoolExpected key value] bool expected *)


(** {2 RC API} *)
63

MARCHE Claude's avatar
manager  
MARCHE Claude committed
64

Francois Bobot's avatar
Francois Bobot committed
65 66 67 68 69 70
type t (** Rc parsed file *)
type section (** section in rc file *)
type family  = (string * section) list (** A family in rc files *)

val empty : t (** An empty Rc *)
val empty_section : section (** An empty section *)
MARCHE Claude's avatar
manager  
MARCHE Claude committed
71

72
val get_section : t -> string -> section option
Francois Bobot's avatar
Francois Bobot committed
73 74 75 76 77 78
(** [get_section rc name]
    @return None if the section is not in the rc file
    @raise DuplicateSection if multiple section has the name [name]
    @raise ExtraParameters if [name] is a family in [rc] instead of a section
*)

79
val get_family  : t -> string -> family
Francois Bobot's avatar
Francois Bobot committed
80 81 82 83
(** [get_family rc name] return all the sections of the family [name]
    in [rc]
    @raise MissingParameters if [name] correspond also too a section in [rc]
 *)
84 85

val set_section : t -> string -> section -> t
Francois Bobot's avatar
Francois Bobot committed
86 87 88
(** [set_section rc name section] add a section [section] with name [name] in
    [rc]. Remove former section [name] if present in [rc] *)

89
val set_family  : t -> string -> family  -> t
Francois Bobot's avatar
Francois Bobot committed
90 91 92 93
(** [set_family rc name family] add all the section in [family] using
    the associated [string] as argument of the family [name] in the rc
    file [rc]. Remove all the former sections of family [name] if
    present in [rc] *)
94 95

val get_int  : ?default:int      -> section -> string -> int
Francois Bobot's avatar
Francois Bobot committed
96 97 98 99 100 101 102 103 104 105
(** [get_int ~default section key] one key to one value

    @raise Bad_value_type if the value associated to [key] is not of type
    {!int}

    @raise Key_not_found if default is not given and no value is
    associated to [key]

    @raise Multiple_value if the key appears multiple time.
*)
106

107 108
val get_into : section -> string -> int option

109
val get_intl : ?default:int list -> section -> string -> int list
Francois Bobot's avatar
Francois Bobot committed
110 111 112 113 114
(** [get_intl ~default section key] one key to many value

    @raise Bad_value_type if the value associated to [key] is not of
    type {!int}

François Bobot's avatar
Doc api  
François Bobot committed
115
    @raise MissingField if default is not given and no values are
Francois Bobot's avatar
Francois Bobot committed
116 117
    associated to [key]
*)
118

119 120 121 122
val set_int :?default:int -> section -> string -> int -> section
(** [set_int ?default section key value] add the association [key] to [value]
    in the section if value is not default.
    Remove all former associations with this [key]
Francois Bobot's avatar
Francois Bobot committed
123
*)
124

125 126 127 128
val set_intl : ?default:int list -> section -> string -> int list -> section
(** [set_int ?default section key lvalue] add the associations [key] to all the
    [lvalue] in the section if value is not default.
    Remove all former associations with this [key]
Francois Bobot's avatar
Francois Bobot committed
129
*)
130 131

val get_bool  : ?default:bool       -> section -> string -> bool
Francois Bobot's avatar
Francois Bobot committed
132
(** Same as {!get_int} but on bool *)
133 134

val get_booll  : ?default:bool list -> section -> string -> bool list
Francois Bobot's avatar
Francois Bobot committed
135
(** Same as {!get_intl} but on bool *)
136

137 138
val get_boolo : section -> string -> bool option

139
val set_bool : ?default:bool -> section -> string -> bool -> section
Francois Bobot's avatar
Francois Bobot committed
140
(** Same as {!set_int} but on bool *)
141

142
val set_booll : ?default:bool list -> section -> string -> bool list -> section
Francois Bobot's avatar
Francois Bobot committed
143
(** Same as {!set_intl} but on bool *)
144 145


Francois Bobot's avatar
Francois Bobot committed
146 147
val get_string  : ?default:string       -> section -> string -> string
(** Same as {!get_int} but on string *)
148

Francois Bobot's avatar
Francois Bobot committed
149 150
val get_stringl  : ?default:string list -> section -> string -> string list
(** Same as {!get_intl} but on string *)
151

152 153
val get_stringo : section -> string -> string option

154
val set_string : ?default:string -> section -> string -> string -> section
Francois Bobot's avatar
Francois Bobot committed
155
(** Same as {!set_int} but on string *)
156

157 158
val set_stringl : ?default:string list ->
  section -> string -> string list -> section
Francois Bobot's avatar
Francois Bobot committed
159
(** Same as {!set_intl} but on string *)
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181

(* val ident  : ?default:string      -> section -> string -> string *)
(*   (\** raise Bad_value_type *)
(*       raise Key_not_found *)
(*       raise Multiple_value *)
(*   *\) *)

(* val identl : ?default:string list -> section -> string -> string list *)
(*   (\** raise Bad_value_type *)
(*       raise Key_not_found *\) *)

(* val set_ident : section -> string -> string -> section *)
(*   (\** raise Yet_defined_key *)
(*       raise Bad_value_type *)
(*   *\) *)

(* val set_identl : section -> string -> string list -> section *)
(*   (\** raise Yet_defined_key *)
(*       raise Bad_value_type *)
(*   *\) *)

val check_exhaustive : section -> Util.Sstr.t -> unit
Francois Bobot's avatar
Francois Bobot committed
182 183 184 185
(** [check_exhaustive section keys] check that only the keys in [keys]
    appear inside the section [section]

    @raise UnknownField if it is not the case
186
*)
Francois Bobot's avatar
Francois Bobot committed
187

188 189 190
exception CannotOpen of string * string
exception SyntaxErrorFile of string * string

191 192
val from_channel : in_channel -> t
(** [from_channel cin] returns the Rc of the input channel [cin]
193
    @raise SyntaxErrorFile in case of incorrect syntax
194
    @raise ExtraParameters if a section header has more than one argument
Francois Bobot's avatar
Francois Bobot committed
195
*)
MARCHE Claude's avatar
manager  
MARCHE Claude committed
196

197
val from_file : string -> t
Francois Bobot's avatar
Francois Bobot committed
198
(** [from_file filename] returns the Rc of the file [filename]
199 200
    @raise CannotOpen is [filename] does not exist
    @raise SyntaxErrorFile in case of incorrect syntax
Francois Bobot's avatar
Francois Bobot committed
201 202
    @raise ExtraParameters if a section header has more than one argument
*)
MARCHE Claude's avatar
manager  
MARCHE Claude committed
203

204 205 206 207 208 209 210 211
val to_formatter : Format.formatter -> t -> unit
  (** [to_formatter fmt rc] writes the Rc [rc] to the formatter [fmt] *)

val to_channel : out_channel -> t -> unit
  (** [to_channel cout rc] writes the Rc [rc] to the output channel [out] *)

val to_file : string -> t -> unit
  (** [to_file filename rc] writes the Rc [rc] to the file [filename] *)
MARCHE Claude's avatar
datadir  
MARCHE Claude committed
212

MARCHE Claude's avatar
manager  
MARCHE Claude committed
213
val get_home_dir : unit -> string
Francois Bobot's avatar
Francois Bobot committed
214
  (** [get_home_dir ()] returns the home dir of the user *)
MARCHE Claude's avatar
manager  
MARCHE Claude committed
215 216