prefs.mli (9378B)
1 (* Unison file synchronizer: src/ubase/prefs.mli *) 2 (* $I3: Copyright 1999-2002 (see COPYING for details) $ *) 3 4 type 'a t 5 6 val read : 'a t -> 'a 7 val set : 'a t -> 'a -> unit 8 val name : 'a t -> string list 9 val overrideDefault : 'a t -> 'a -> unit 10 val readDefault : 'a t -> 'a 11 12 type topic = [ 13 | `General 14 | `Sync 15 | `Syncprocess 16 | `Syncprocess_CLI 17 | `CLI 18 | `GUI 19 | `Remote 20 | `Archive ] 21 22 type group = [ 23 | `Basic of topic 24 | `Advanced of topic 25 | `Expert 26 | `Internal of (* Preferences that are not listed *) 27 [ `Pseudo (* Pseudo-preferences for internal propagation *) 28 | `Devel (* Developer-only or build-related preferences *) 29 | `Other ] (* Other non-listed preferences *) 30 ] 31 32 (* Note about command line-only preferences. These preferences are never *) 33 (* sent to a server (ignoring [local] and [send] arguments). Should a client *) 34 (* send such a preference anyway then the server silently ignores it. *) 35 36 (* Convenient functions for registering simple kinds of preferences. Note *) 37 (* that createStringPref creates a preference that can only be set once, *) 38 (* while createStringListPref creates a reference to a list of strings that *) 39 (* accumulates a list of values. *) 40 val createBool : 41 string (* preference name *) 42 -> category:group 43 -> ?cli_only:bool (* only a command line option, not in a profile *) 44 -> ?local:bool (* whether it is local to the client *) 45 -> ?send:(unit->bool) (* whether preference should be sent to server *) 46 -> bool (* initial value *) 47 -> ?deprecated:bool (* preference is deprecated (default false) *) 48 -> string (* documentation string *) 49 -> string (* full (tex) documentation string *) 50 -> bool t (* -> new preference value *) 51 52 val createInt : 53 string (* preference name *) 54 -> category:group 55 -> ?cli_only:bool (* only a command line option, not in a profile *) 56 -> ?local:bool (* whether it is local to the client *) 57 -> ?send:(unit->bool) (* whether preference should be sent to server *) 58 -> int (* initial value *) 59 -> ?deprecated:bool (* preference is deprecated (default false) *) 60 -> string (* documentation string *) 61 -> string (* full (tex) documentation string *) 62 -> int t (* -> new preference value *) 63 64 val createString : 65 string (* preference name *) 66 -> category:group 67 -> ?cli_only:bool (* only a command line option, not in a profile *) 68 -> ?local:bool (* whether it is local to the client *) 69 -> ?send:(unit->bool) (* whether preference should be sent to server *) 70 -> string (* initial value *) 71 -> ?deprecated:bool (* preference is deprecated (default false) *) 72 -> string (* documentation string *) 73 -> string (* full (tex) documentation string *) 74 -> string t (* -> new preference value *) 75 76 val createStringList : 77 string (* preference name *) 78 -> category:group 79 -> ?cli_only:bool (* only a command line option, not in a profile *) 80 -> ?local:bool (* whether it is local to the client *) 81 -> ?send:(unit->bool) (* whether preference should be sent to server *) 82 -> ?deprecated:bool (* preference is deprecated (default false) *) 83 -> string (* documentation string *) 84 -> string (* full (tex) documentation string *) 85 -> string list t (* -> new preference value *) 86 87 val createBoolWithDefault : 88 string (* preference name *) 89 -> category:group 90 -> ?cli_only:bool (* only a command line option, not in a profile *) 91 -> ?local:bool (* whether it is local to the client *) 92 -> ?send:(unit->bool) (* whether preference should be sent to server *) 93 -> ?deprecated:bool (* preference is deprecated (default false) *) 94 -> string (* documentation string *) 95 -> string (* full (tex) documentation string *) 96 -> [`True|`False|`Default] t 97 (* -> new preference value *) 98 99 exception IllegalValue of string 100 (* A more general creation function that allows arbitrary functions for *) 101 (* interning and printing values. The interning function should raise *) 102 (* IllegalValue if it is passed a string it cannot deal with. *) 103 val create : 104 string (* preference name *) 105 -> category:group 106 -> ?cli_only:bool (* only a command line option, not in a profile *) 107 -> ?local:bool (* whether it is local to the client *) 108 -> ?send:(unit->bool) (* whether the pref should be sent to server *) 109 -> 'a (* initial value *) 110 -> ?deprecated:bool (* preference is deprecated (default false) *) 111 -> string (* documentation string *) 112 -> string (* full (tex) documentation string *) 113 -> ('a->string->'a) (* interning function for preference values 114 (1st arg is old value of preference) *) 115 -> ('a -> string list) (* printing function for preference values *) 116 -> 'a Umarshal.t 117 -> 'a t (* -> new preference value *) 118 119 (* Create an alternate name for a preference (the new name will not appear *) 120 (* in usage messages or generated documentation) *) 121 val alias : 'a t (* existing preference *) 122 -> string (* new name *) 123 -> unit 124 125 (* Mark a preference name as intentionally removed. A removed preference *) 126 (* does not exist (can't be specified on command line or in a profile) but *) 127 (* will be silently ignored when sent by a remote host (to not break *) 128 (* compatibility with old clients). *) 129 val markRemoved : string -> unit 130 131 (* Reset all preferences to their initial values *) 132 val resetToDefaults : unit -> unit 133 134 (* ------------------------------------------------------------------------- *) 135 136 (* Parse command-line arguments, exiting program if there are any problems. *) 137 (* If a StringList preference named "rest" has been registered, then any *) 138 (* anonymous arguments on the command line will be added to its value. *) 139 val parseCmdLine : 140 string (* Usage message *) 141 -> unit 142 143 (* Make a preliminary scan without setting any preferences *) 144 (* Note: Command line include options are not processed; they will appear in *) 145 (* the map. *) 146 val scanCmdLine : string -> (string list) Util.StringMap.t 147 148 val printUsage : string -> unit 149 val printUsageForMan : unit -> unit 150 151 (* ---------------------------------------------------------------------- *) 152 153 (* The name of the preferences file (if any), not including the .prf *) 154 val profileName : string option ref 155 156 (* Calculate the full pathname of a preference file *) 157 val profilePathname : ?add_ext:bool -> string -> string 158 159 (* Check whether the profile file is unchanged *) 160 val profileUnchanged : unit -> bool 161 162 (* Add a new preference to the file on disk (the result is a diagnostic *) 163 (* message that can be displayed to the user to verify where the new pref *) 164 (* went) *) 165 val add : string -> string -> string 166 167 (* Add a comment line to the preferences file on disk *) 168 val addComment : string -> unit 169 170 (* Scan a given preferences file and return a list of tuples of the form *) 171 (* ((locName, lineno), name, value), without changing any of the preferences *) 172 val readAFile : ?fail:bool -> ?add_ext:bool -> string 173 -> ((string * int) * string * string) list 174 175 (* Parse the preferences file, raising Fatal if there are any problems *) 176 val loadTheFile : unit -> unit 177 178 (* Parse the given strings as if they were part of the preferences file *) 179 val loadStrings : string list -> unit 180 181 (* ------------------------------------------------------------------------- *) 182 183 type dumpedPrefs 184 185 val mdumpedPrefs : dumpedPrefs Umarshal.t 186 187 (* Dump current values of all preferences into a value that can be 188 marshalled and sent over the network or stored in a file for fast 189 retrieval *) 190 val dump : int -> dumpedPrefs 191 192 (* Load new values of all preferences from a string created by dump *) 193 val load : dumpedPrefs -> int -> unit 194 195 (* ------------------------------------------------------------------------- *) 196 197 type typ = 198 [`BOOL | `INT | `STRING | `STRING_LIST | `BOOLDEF | `CUSTOM | `UNKNOWN] 199 200 val canonicalName : string -> string 201 val typ : string -> typ 202 val documentation : string -> string * string 203 val category : string -> group option 204 val list : bool -> string list 205 val topic_title : group -> string 206 207 (* ------------------------------------------------------------------------- *) 208 209 val printFullDocs : [`TeX | `man] -> unit 210 val dumpPrefsToStderr : unit -> unit