X-Git-Url: http://matita.cs.unibo.it/gitweb/?a=blobdiff_plain;f=helm%2Focaml%2Fregistry%2Fhelm_registry.mli;h=1ef1aa3b7749c2ca6a913dc75ffcf6c0fe3f1f6a;hb=4167cea65ca58897d1a3dbb81ff95de5074700cc;hp=f50d9b4a9711485e8aa86f5f1c2cf65f0cd79ceb;hpb=27ebca99c83f84c5a3915695e3f78b36c4fbcedf;p=helm.git diff --git a/helm/ocaml/registry/helm_registry.mli b/helm/ocaml/registry/helm_registry.mli index f50d9b4a9..1ef1aa3b7 100644 --- a/helm/ocaml/registry/helm_registry.mli +++ b/helm/ocaml/registry/helm_registry.mli @@ -1,4 +1,4 @@ -(* Copyright (C) 2004, HELM Team. +(* Copyright (C) 2004-2005, HELM Team. * * This file is part of HELM, an Hypertextual, Electronic * Library of Mathematics, developed at the Computer Science @@ -29,7 +29,7 @@ * * key ::= path * path ::= component ( '.' component )* - * component ::= ( lowercase_alpha | num | '_' )+ + * component ::= ( alpha | num | '_' )+ * # with the only exception that sequences of '_' longer than 1 aren't valid * # components * @@ -51,9 +51,15 @@ * a configuration file (via "save_to" function below) . * * Mapping between keys and environment variables is as follows: - * - the whole key is uppercased * - each "." is converted to "__" - * E.g.: my.foo_ish.application -> MY__FOO_ISH__APPLICATION + * 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 @@ -66,11 +72,9 @@ exception Key_not_found of string * @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 - * @param expected_type - * @param value - * @param msg *) -exception Type_error of string * string * 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 *) @@ -84,11 +88,6 @@ exception Malformed_key of string *) exception Parse_error of string * int * int * string - (** raised when a given pair fails validity test(s) - * @param pair pair - * @param descr description of the failed test *) -exception Invalid_value of (string * string) * string - (** {2 Generic untyped interface} * Using the functions below this module could be used as a repository of * key/value pairs *) @@ -96,71 +95,95 @@ exception Invalid_value of (string * string) * string (** 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) *) -val get_string: string -> string (* alias for bare "get" above *) -val get_int: string -> int -val get_float: string -> float -val get_bool: string -> bool -val get_string_list: string -> string list - - (* alias for bare "set" above *) -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 -val set_string_list: key:string -> value:string list -> unit - -(** {3 Optional values interface} - * Functions below took as first argument respectively a "getter" and a "setter" - * function. A getter is one of the get_* function above, a setter is one of the - * set_* function above. Returned value is a get (set) function typed as the - * given getter (setter) whith optional values. None is returned for missing - * keys and None can be assigned to a key removing it from the registry. - *) +(** {3 Unmarshallers} *) -val get_opt: - (string -> 'a) (* getter *) -> - string -> 'a option -val set_opt: - (key:string -> value:'a -> unit) (* setter *) -> - key:string -> value:'a option -> unit - -(** {2 Validators} - * Each key may have zero or more associated validators, that are predicates - * "this value is valid for this key". Each time a value is set, all validators - * associated to the corresponding key are executed, if at least one of them - * fails, Invalid_value exception will be raised *) - -type validator_id - - (** register a new validator for a given key - * @param key key to which validator applies - * @param validator a function applying to a value returning true if that - * value is valid, false otherwise - * @param descr validator description, for the final user when a validation - * attempt fails - * @return validator_id should be used to remove the validator later on *) -val add_validator: - key:string -> validator:(string -> bool) -> descr:string -> - validator_id -(* val remove_validator: validator_id -> unit *) - -(** {2 Persistent configuration} - * Validators aren't saved. load_from/save_to sequences don't preserve comments - *) +val string: string -> string +val int: string -> int +val float: string -> float +val bool: string -> bool + +(** {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 *) +val save_to: string -> unit (** @param fname file from which load new configuration. If it's an absolute * file name "path" argument is ignored. @@ -171,8 +194,6 @@ val add_validator: *) val load_from: ?path:string list -> string -> unit -(* -(* DEBUGGING *) -val dump: unit -> unit -*) + (** removes all keys *) +val clear: unit -> unit