features.mli (3482B)
1 (* Unison file synchronizer: src/features.mli *) 2 (* Copyright 2021, Tõivo Leedjärv 3 4 This program is free software: you can redistribute it and/or modify 5 it under the terms of the GNU General Public License as published by 6 the Free Software Foundation, either version 3 of the License, or 7 (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 GNU General Public License for more details. 13 14 You should have received a copy of the GNU General Public License 15 along with this program. If not, see <http://www.gnu.org/licenses/>. 16 *) 17 18 type t 19 (** The type of a feature. *) 20 21 type id = string 22 (** The type of feature's identifier. Features are identified by their name. *) 23 24 val enabled : t -> bool 25 (** Test whether a feature is currently enabled (included in the current 26 set of enabled features). 27 28 Feature negotiation must have been completed to get the correct result. *) 29 30 val register : string -> ?arcFormatChange:bool -> 31 (id list -> bool -> string option) option -> t 32 (** [register n f] registers a supported feature with a unique identifier [n]. 33 34 [f] is an optional validation function that will be called during feature 35 negotiation. [f] will receive as the first argument the feature set to be 36 enabled as a result of negotiation and as the second argument a boolean 37 indicating whether the tested feature is included in the negotiated set. 38 [f] must return [Some msg] if the negotiation result must be rejected with 39 the error message [msg], otherwise it must return [None]. 40 41 [archFormatChange] is an optional argument which indicates whether the 42 feature, if enabled, changes the archive format that is stored on disk. 43 In other words, it indicates if the archive stored while this feature was 44 enabled requires the existence of this feature to be read back in. 45 46 @return feature value that can be tested by {!Features.enabled} function. 47 @raise {!Util.Fatal} if [n] is not unique. *) 48 49 val dummy : t 50 (** A feature value that will never be included in feature negotiation or 51 the set of enabled features. *) 52 53 val all : unit -> id list 54 (** Set of all supported features registered by {!Features.register}. *) 55 56 val empty : id list 57 (** Empty set of features. *) 58 59 val changingArchiveFormat : unit -> id list 60 (** Set of all currently enabled features that impact the on-disk archive 61 format. The same features must exist in order to read in the archive. *) 62 63 val mem : id -> id list -> bool 64 (** [mem n s] tests whether feature with id [n] belongs to feature set [s]. *) 65 66 val inter : id list -> id list -> id list 67 (** Feature set intersection. *) 68 69 val validate : id list -> unit 70 (** [validate s] calls validation functions associated with each registered 71 feature in arbitrary order, with only features in [s] considered enabled. 72 73 @raise {!Util.Fatal} at first failed validation. *) 74 75 val getEnabled : unit -> id list 76 (** Set of enabled features. *) 77 78 val resetEnabled : unit -> unit 79 (** Make the set of enabled features empty. Can be used to reset the results 80 of previous feature negotiation. *) 81 82 val setEnabled : id list -> unit 83 (** [setEnabled s] makes [s] the set of enabled features. *) 84 85 val validateEnabled : unit -> unit 86 (** Same as {!Features.validate} with the set of currently enabled features. *) 87