X-Git-Url: http://matita.cs.unibo.it/gitweb/?p=helm.git;a=blobdiff_plain;f=components%2Fregistry%2Fhelm_registry.mli;fp=components%2Fregistry%2Fhelm_registry.mli;h=77c6f6cc3143ea465d70a5f13fd141485a1e0ef8;hp=0000000000000000000000000000000000000000;hb=f61af501fb4608cc4fb062a0864c774e677f0d76;hpb=58ae1809c352e71e7b5530dc41e2bfc834e1aef1 diff --git a/components/registry/helm_registry.mli b/components/registry/helm_registry.mli new file mode 100644 index 000000000..77c6f6cc3 --- /dev/null +++ b/components/registry/helm_registry.mli @@ -0,0 +1,200 @@ +(* Copyright (C) 2004-2005, HELM Team. + * + * This file is part of HELM, an Hypertextual, Electronic + * Library of Mathematics, developed at the Computer Science + * Department, University of Bologna, Italy. + * + * HELM is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * HELM 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. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with HELM; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, + * MA 02111-1307, USA. + * + * For details, see the HELM World-Wide-Web page, + * http://helm.cs.unibo.it/ + *) + +(** Configuration repository for HELM applications. + * + * ++ Keys format ++ + * + * key ::= path + * path ::= component ( '.' component )* + * component ::= ( alpha | num | '_' )+ + * # with the only exception that sequences of '_' longer than 1 aren't valid + * # components + * + * Suggested usage .: + * e.g. gTopLevel.prooffile, http_getter.port, ... + * + * ++ Configuration file example ++ + * + * gTopLevel.prooffile = "/home/zack/prooffile" + * http_getter.port = "58080" + * + * ++ Environment variable override ++ + * + * each key has an associated environment variable name. At runtime (i.e. when + * "get" requests are performed) a variable with this name will be looked for, + * if it's defined it will override the value present (or absent) in the + * registry. + * Environment variables are _not_ considered when saving the configuration to + * a configuration file (via "save_to" function below) . + * + * Mapping between keys and environment variables is as follows: + * - each "." is converted to "__" + * E.g.: my.Foo_iSH.Application -> my__Foo_iSH__Application + * + * ++ Variable interpolation ++ + * + * Interpolation is supported with the following syntax: + * + * foo.bar = "quux" + * foo.baz = $(foo.bar)/baz + *) + + (** raised when a looked up key can't be found + * @param key looked up key *) +exception Key_not_found of string + + (** raised when a cyclic definitions is found, e.g. after + * Helm_registry.set "a" "$b" + * Helm_registry.set "b" "$a" + * @param msg brief description of the definition cycle *) +exception Cyclic_definition of string + + (** raised when a looked up key doesn't have the required type, parameter is + * an error message *) +exception Type_error of string + + (** raised when a malformed key is encountered + * @param key malformed key *) +exception Malformed_key of string + + (** raised when an error is encountered while parsing a configuration file + * @param fname file name + * @param line line number + * @param col column number + * @param msg error description + *) +exception Parse_error of string * int * int * string + +(** {2 Generic untyped interface} + * Using the functions below this module could be used as a repository of + * key/value pairs *) + + (** lookup key in registry with environment variable override *) +val get: string -> string +val set: key:string -> value:string -> unit +val has: string -> bool + + (** remove a key from the current environment, next get over this key will + * raise Key_not_found until the key will be redefined *) +val unset: string -> unit + + (** @param interpolate defaults to true *) +val fold: + ?prefix:string -> ?interpolate:bool -> + ('a -> string -> string -> 'a) -> 'a -> 'a + + (** @param interpolate defaults to true *) +val iter: + ?prefix:string -> ?interpolate:bool -> + (string -> string -> unit) -> unit + + (** @param interpolate defaults to true *) +val to_list: + ?prefix:string -> ?interpolate:bool -> + unit -> (string * string) list + + (** @param prefix key representing the section whose contents should be listed + * @return section list * key list *) +val ls: string -> string list * string list + +(** {2 Typed interface} + * Three basic types are supported: strings, int and strings list. Strings + * correspond literally to what is written inside double quotes; int to the + * parsing of an integer number from ; strings list to the splitting at blanks + * of it (heading and trailing blanks are removed before splitting) *) + +(** {3 Unmarshallers} *) + +val string: string -> string +val int: string -> int +val float: string -> float +val bool: string -> bool +val pair: (string -> 'a) -> (string -> 'b) -> string -> 'a * 'b + +(** {3 Typed getters} *) + + (** like get, with an additional unmarshaller + * @param unmarshaller conversion function from string to the desired type. + * Use one of the above unmarshallers *) +val get_typed: (string -> 'a) -> string -> 'a + +val get_opt: (string -> 'a) -> string -> 'a option +val get_opt_default: (string -> 'a) -> default:'a -> string -> 'a + + (** never fails with Key_not_found, instead return the empty list *) +val get_list: (string -> 'a) -> string -> 'a list + + (** decode values which are blank separated list of values, of length 2 *) +val get_pair: (string -> 'a) -> (string -> 'b) -> string -> 'a * 'b + +(** {4 Shorthands} *) + +val get_string: string -> string +val get_int: string -> int +val get_float: string -> float +val get_bool: string -> bool + +(** {3 Marshallers} *) + +val of_string: string -> string +val of_int: int -> string +val of_float: float -> string +val of_bool: bool -> string + +(** {3 Typed setters} *) + + (** like set, with an additional marshaller + * @param marshaller conversion function to string. + * Use one of the above marshallers *) +val set_typed: ('a -> string) -> key:string -> value:'a -> unit + +val set_opt: ('a -> string) -> key:string -> value:'a option -> unit +val set_list: ('a -> string) -> key:string -> value:'a list -> unit + +(** {4 Shorthands} *) + +val set_string: key:string -> value:string -> unit +val set_int: key:string -> value:int -> unit +val set_float: key:string -> value:float -> unit +val set_bool: key:string -> value:bool -> unit + +(** {2 Persistent configuration} *) + + (** @param fname file to which save current configuration *) +val save_to: string -> unit + + (** @param fname file from which load new configuration. If it's an absolute + * file name "path" argument is ignored. + * Otherwise given file name is looked up in each directory member of the + * given path. Each matching file is loaded overriding previous settings. If + * no path is given a default path composed of just the current working + * directory is used. + *) +val load_from: ?path:string list -> string -> unit + + (** removes all keys *) +val clear: unit -> unit +