X-Git-Url: http://matita.cs.unibo.it/gitweb/?a=blobdiff_plain;f=helm%2Focaml%2Fregistry%2Fhelm_registry.mli;h=e1c0289a511c85eb127e1664fc1a0ac6187ff296;hb=712f1ea34c4f03e89b017c75f07fda2006d1d817;hp=02c0df76b8ec1bb4d3a4b3a5216c251644c69ec8;hpb=cdc2c0c2ba2831239dcaad706bba8c73ab27723f;p=helm.git diff --git a/helm/ocaml/registry/helm_registry.mli b/helm/ocaml/registry/helm_registry.mli index 02c0df76b..e1c0289a5 100644 --- a/helm/ocaml/registry/helm_registry.mli +++ b/helm/ocaml/registry/helm_registry.mli @@ -25,23 +25,54 @@ (** Configuration repository for HELM applications. * - * key ::= path - * path ::= component ( '.' component )* - * component ::= ( alpha | num | '_' )+ + * ++ Keys format ++ * - * Suggested usage .: - * e.g. gTopLevel.prooffile, http_getter.port, ... + * key ::= path + * path ::= component ( '.' component )* + * component ::= ( lowercase_alpha | num | '_' )+ + * # with the only exception that sequences of '_' longer than 1 aren't valid + * # components * - * Configuration file example: + * 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: + * - the whole key is uppercased + * - 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 * @param expected_type * @param value @@ -54,8 +85,11 @@ exception Malformed_key of string (** raised when an error is encountered while parsing a configuration file * @param fname file name - * @param lno line number *) -exception Parse_error of string * int + * @param line line number + * @param col column number + * @param msg error description + *) +exception Parse_error of string * int * int * string (** raised when a given pair fails validity test(s) * @param pair pair @@ -66,22 +100,47 @@ exception Invalid_value of (string * string) * string * 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 + (** 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 + (** {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_int: string -> int -val get_float: string -> float -val get_string_list: string -> string list +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. + *) -val set_int: key:string -> value:int -> unit -val set_float: key:string -> value:float -> unit -val set_string_list: key:string -> value:string list -> unit +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 @@ -107,14 +166,20 @@ val add_validator: * Validators aren't saved. load_from/save_to sequences don't preserve comments *) - (** @param fname file to which save current configuration *) + (** @param fname file to which save current configuration + * If xmllint is available then it will be used for pretty printing fname, + * otherwise fname will be in the usual pxp ugly format *) val save_to: string -> unit - (** @param fname file from which load new configuration *) -val load_from: 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 -(* (* DEBUGGING *) -val dump: unit -> unit -*) +(* val dump: unit -> unit *)