src/utils/lib/options.mli

   1 (* Copyright 2001, 2002 b8_bavard, b8_fee_carabine, INRIA *)
   2 (*
   3     This file is part of mldonkey.
   4
   5     mldonkey is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU General Public License as published by
   7     the Free Software Foundation; either version 2 of the License, or
   8     (at your option) any later version.
   9
  10     mldonkey is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with mldonkey; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 *)
  19
  20 (*d This module implements a simple mechanism to handle program options files.
  21   An options file is defined as a set of [variable = value] lines,
  22   where value can be a simple string, a list of values (between brackets
  23 or parentheses) or a set of [variable = value] lines between braces.
  24 The option file is automatically loaded and saved, and options are
  25 manipulated inside the program as easily as references. *)
  26
  27 type 'a option_class
  28 (*d The abstract type for a class of options. A class is a set of options
  29 which use the same conversion functions from loading and saving.*)
  30
  31 type 'a option_record
  32 (*d The abstract type for an option *)
  33
  34 type options_file
  35 type options_section
  36
  37 type option_info = {
  38     option_name : string;
  39     option_shortname : string;
  40     option_desc : string;
  41     option_value : string;
  42     option_help : string;
  43     option_advanced : bool;
  44     option_default : string;
  45     option_type : string;
  46     option_restart : bool; (* changing this option requires a restart *)
  47     option_public : bool; (* send this option to GUIs even for non-admin users *)
  48     option_internal : bool; (* this option should not be changed by users *)
  49   }
  50
  51 exception SideEffectOption
  52
  53 val create_options_file : string -> options_file
  54 val options_file_name : options_file -> string
  55 val set_options_file : options_file -> string -> unit
  56 val prune_file : options_file -> unit
  57 (*4 Operations on option files *)
  58
  59 val set_before_save_hook : options_file -> (unit -> unit) -> unit
  60 val set_after_save_hook : options_file -> (unit -> unit) -> unit
  61 val set_after_load_hook : options_file -> (unit -> unit) -> unit
  62
  63 val load : options_file -> unit
  64 (*d [load ()] loads the option file. All options whose value is specified
  65 in the option file are updated. *)
  66
  67 val append : options_file -> string -> unit
  68 (*d [append filename] loads the specified option file. All options whose
  69 value is specified in this file are updated. *)
  70
  71 val save : options_file -> unit
  72 (*d [save ()] saves all the options values to the option file. *)
  73 val save_with_help : options_file -> unit
  74 val save_with_help_private : options_file -> unit
  75 (*d [save_with_help ()] saves all the options values to the option file,
  76 with the help provided for each option. *)
  77
  78 val file_section : options_file -> string list -> string -> options_section
  79
  80 (*4 Creating options *)
  81 val define_option : options_section ->
  82   string list ->  ?desc: string ->
  83   ?restart: bool -> ?public: bool -> ?internal: bool ->
  84   string -> 'a option_class -> 'a -> 'a option_record
  85 val define_expert_option : options_section ->
  86   string list ->    ?desc: string ->
  87   ?restart: bool -> ?public: bool -> ?internal: bool ->
  88   string -> 'a option_class -> 'a -> 'a option_record
  89 val define_header_option : options_file ->
  90   string list ->  string -> 'a option_class -> 'a -> 'a option_record
  91 val option_hook : 'a option_record -> (unit -> unit) -> unit
  92
  93 val string_option : string option_class
  94 val color_option : string option_class
  95 val font_option : string option_class
  96 val int_option : int option_class
  97 val int64_option : int64 option_class
  98 val percent_option : int option_class
  99 val port_option : int option_class
 100 val bool_option : bool option_class
 101 val float_option : float option_class
 102 val path_option : string list option_class
 103 val string2_option : (string * string) option_class
 104 val filename_option : string option_class
 105
 106   (* parameterized options *)
 107 val list_option : 'a option_class -> 'a list option_class
 108 val array_option : 'a option_class -> 'a array option_class
 109 val hasharray_option : 'a -> (int * 'a * 'b) option_class -> ('a, 'b) Hashtbl.t array option_class
 110 val safelist_option : 'a option_class -> 'a list option_class
 111 val intmap_option : ('a -> int) -> 'a option_class -> 'a Intmap.t option_class
 112 val listiter_option : 'a option_class -> 'a list option_class
 113 val option_option : 'a option_class -> 'a option option_class
 114 val smalllist_option : 'a option_class -> 'a list option_class
 115 val sum_option : (string * 'a) list -> 'a option_class
 116 val tuple2_option :
 117   'a option_class * 'b option_class -> ('a * 'b) option_class
 118 val tuple3_option : 'a option_class * 'b option_class * 'c option_class ->
 119   ('a * 'b * 'c) option_class
 120 val tuple4_option : 'a option_class * 'b option_class * 'c option_class
 121    * 'd option_class->
 122   ('a * 'b * 'c * 'd) option_class
 123
 124 (*4 Using options *)
 125
 126 val ( !! ) : 'a option_record -> 'a
 127 val ( =:= ) : 'a option_record -> 'a -> unit
 128
 129 val shortname : 'a option_record -> string
 130 val option_type : 'a option_record -> string
 131 val get_help : 'a option_record -> string
 132 val advanced : 'a option_record -> bool
 133
 134 (*4 Creating new option classes *)
 135
 136 val get_class : 'a option_record -> 'a option_class
 137
 138 val class_hook : 'a option_class -> ('a option_record -> unit) -> unit
 139
 140 type option_value =
 141   Module of option_module
 142 | StringValue of  string
 143 | IntValue of int64
 144 | FloatValue of float
 145 | List of option_value list
 146 | SmallList of option_value list
 147 | OnceValue of option_value
 148 | DelayedValue of (out_channel -> string -> unit)
 149
 150 and option_module =
 151   (string * option_value) list
 152
 153 val define_option_class :
 154   string -> (option_value -> 'a) -> ('a -> option_value) -> 'a option_class
 155
 156 val to_value : 'a option_class -> 'a -> option_value
 157 val from_value : 'a option_class -> option_value -> 'a
 158
 159 val value_to_string : option_value -> string
 160 val string_to_value : string -> option_value
 161 val stringoption_to_value : string option -> option_value
 162 val value_to_stringoption : option_value -> string option
 163 val value_to_int : option_value -> int
 164 val int_to_value : int -> option_value
 165 val value_to_int64 : option_value -> int64
 166 val int64_to_value : int64 -> option_value
 167 val value_to_percent : option_value -> int
 168 val percent_to_value : int -> option_value
 169 val value_to_port : option_value -> int
 170 val port_to_value : int -> option_value
 171 val bool_of_string : string -> bool
 172 val value_to_bool : option_value -> bool
 173 val bool_to_value : bool -> option_value
 174 val value_to_float : option_value -> float
 175 val float_to_value : float -> option_value
 176 val value_to_string2 : option_value -> string * string
 177 val string2_to_value : string * string -> option_value
 178 val value_to_list : (option_value -> 'a) -> option_value -> 'a list
 179 val list_to_value : ('a -> option_value) -> 'a list -> option_value
 180 val smalllist_to_value : ('a -> option_value) -> 'a list -> option_value
 181 val value_to_path : option_value -> string list
 182 val path_to_value : string list -> option_value
 183
 184 val value_to_tuple2 :
 185   (option_value * option_value -> 'a) -> option_value -> 'a
 186 val tuple2_to_value :
 187   ('a -> option_value * option_value) -> 'a -> option_value
 188
 189
 190 val filename_to_value : string -> option_value
 191 val value_to_filename : option_value -> string
 192
 193 val set_simple_option : options_file -> string -> string -> unit
 194 val simple_options : string -> options_file -> bool -> option_info list
 195 val get_simple_option : options_file -> string -> string
 196
 197 val set_string_wrappers : 'a option_class ->
 198   ('a -> string) -> (string -> 'a) -> unit
 199
 200 val simple_args : string -> options_file -> (string * Arg.spec * string) list
 201
 202 val prefixed_args :
 203   string -> options_file -> (string * Arg.spec * string) list
 204
 205 val once_value : option_value -> option_value
 206 val strings_of_option : 'a option_record  -> option_info
 207
 208 val array_to_value : ('a -> option_value) -> 'a array -> option_value
 209 val value_to_array : (option_value -> 'a) -> option_value -> 'a array
 210
 211 val restore_default : 'a option_record -> unit
 212 val set_option_desc : 'a option_record -> string -> unit
 213
 214 val sections : options_file -> options_section list
 215 val strings_of_section_options :
 216   string -> options_section -> option_info list
 217
 218 val section_name : options_section -> string
 219 val iter_file : (Obj.t option_record -> unit) -> options_file -> unit
 220 val iter_section : (Obj.t option_record -> unit) -> options_section -> unit
 221
 222