1Misc(3)                          OCaml library                         Misc(3)
2
3
4

NAME

6       Misc - Miscellaneous useful types and functions
7

Module

9       Module   Misc
10

Documentation

12       Module Misc
13        : sig end
14
15
16       Miscellaneous useful types and functions
17
18       Warning: this module is unstable and part of Compiler_libs .
19
20
21
22
23
24
25       val fatal_error : string -> 'a
26
27
28
29
30       val fatal_errorf : ('a, Format.formatter, unit, 'b) format4 -> 'a
31
32
33
34
35       exception Fatal_error
36
37
38
39
40
41       val  try_finally  :  ?always:(unit  -> unit) -> ?exceptionally:(unit ->
42       unit) -> (unit -> 'a) -> 'a
43
44
45       try_finally work ~always ~exceptionally is designed to run code in work
46       that  may fail with an exception, and has two kind of cleanup routines:
47       always , that must be run after any execution of  the  function  (typi‐
48       cally,  freeing  system  resources), and exceptionally , that should be
49       run only if work or always failed with an exception (typically, undoing
50       user-visible  state  changes that would only make sense if the function
51       completes correctly). For example:
52
53
54             let objfile = outputprefix ^ ".cmo" in
55             let oc = open_out_bin objfile in
56             Misc.try_finally
57               (fun () ->
58                  bytecode
59                  ++ Timings.(accumulate_time (Generate sourcefile))
60                      (Emitcode.to_file oc modulename objfile);
61                  Warnings.check_fatal ())
62               ~always:(fun () -> close_out oc)
63               ~exceptionally:(fun _exn -> remove_file objfile);
64
65
66       If exceptionally fail with an exception, it is propagated as usual.
67
68       If always or exceptionally use exceptions internally  for  control-flow
69       but do not raise, then try_finally is careful to preserve any exception
70       backtrace coming from work or always for easier debugging.
71
72
73
74       val reraise_preserving_backtrace : exn -> (unit -> unit) -> 'a
75
76
77       reraise_preserving_backtrace e f is (f (); raise  e)  except  that  the
78       current backtrace is preserved, even if f uses exceptions internally.
79
80
81
82       val map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list
83
84
85
86
87       val map_left_right : ('a -> 'b) -> 'a list -> 'b list
88
89
90
91
92       val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
93
94
95
96
97       val replicate_list : 'a -> int -> 'a list
98
99
100
101
102       val list_remove : 'a -> 'a list -> 'a list
103
104
105
106
107       val split_last : 'a list -> 'a list * 'a
108
109
110
111       type ref_and_value =
112        | R : 'a ref * 'a -> ref_and_value
113
114
115
116
117
118       val protect_refs : ref_and_value list -> (unit -> 'a) -> 'a
119
120
121       protect_refs  l  f temporarily sets r to v for each R (r, v) in l while
122       executing f . The previous contents of the references is restored  even
123       if f raises an exception, without altering the exception backtrace.
124
125
126       module Stdlib : sig end
127
128
129
130
131
132       val find_in_path : string list -> string -> string
133
134
135
136
137       val find_in_path_rel : string list -> string -> string
138
139
140
141
142       val find_in_path_uncap : string list -> string -> string
143
144
145
146
147       val remove_file : string -> unit
148
149
150
151
152       val expand_directory : string -> string -> string
153
154
155
156
157       val split_path_contents : ?sep:char -> string -> string list
158
159
160
161
162       val create_hashtable : int -> ('a * 'b) list -> ('a, 'b) Hashtbl.t
163
164
165
166
167       val copy_file : in_channel -> out_channel -> unit
168
169
170
171
172       val copy_file_chunk : in_channel -> out_channel -> int -> unit
173
174
175
176
177       val string_of_file : in_channel -> string
178
179
180
181
182       val  output_to_file_via_temporary  :  ?mode:open_flag list -> string ->
183       (string -> out_channel -> 'a) -> 'a
184
185
186
187
188       val protect_writing_to_file : filename:string -> f:(out_channel ->  'a)
189       -> 'a
190
191       Open  the  given  filename  for  writing  (in  binary  mode),  pass the
192       out_channel to the given function, then close the channel. If the func‐
193       tion raises an exception then filename will be removed.
194
195
196
197       val log2 : int -> int
198
199
200
201
202       val align : int -> int -> int
203
204
205
206
207       val no_overflow_add : int -> int -> bool
208
209
210
211
212       val no_overflow_sub : int -> int -> bool
213
214
215
216
217       val no_overflow_mul : int -> int -> bool
218
219
220
221
222       val no_overflow_lsl : int -> int -> bool
223
224
225
226       module Int_literal_converter : sig end
227
228
229
230
231
232       val chop_extensions : string -> string
233
234
235
236
237       val search_substring : string -> string -> int -> int
238
239
240
241
242       val  replace_substring  :  before:string  ->  after:string -> string ->
243       string
244
245
246
247
248       val rev_split_words : string -> string list
249
250
251
252
253       val get_ref : 'a list ref -> 'a list
254
255
256
257
258       val set_or_ignore : ('a -> 'b option) -> 'b option ref -> 'a -> unit
259
260
261
262
263       val fst3 : 'a * 'b * 'c -> 'a
264
265
266
267
268       val snd3 : 'a * 'b * 'c -> 'b
269
270
271
272
273       val thd3 : 'a * 'b * 'c -> 'c
274
275
276
277
278       val fst4 : 'a * 'b * 'c * 'd -> 'a
279
280
281
282
283       val snd4 : 'a * 'b * 'c * 'd -> 'b
284
285
286
287
288       val thd4 : 'a * 'b * 'c * 'd -> 'c
289
290
291
292
293       val for4 : 'a * 'b * 'c * 'd -> 'd
294
295
296
297       module LongString : sig end
298
299
300
301
302
303       val edit_distance : string -> string -> int -> int option
304
305
306       edit_distance a b cutoff computes the edit distance between  strings  a
307       and  b  .  To  help  efficiency, it uses a cutoff: if the distance d is
308       smaller than cutoff , it returns Some d , else None .
309
310       The distance algorithm currently used is Damerau-Levenshtein:  it  com‐
311       putes  the  number  of insertion, deletion, substitution of letters, or
312       swapping of adjacent letters to go from one word to the other. The par‐
313       ticular algorithm may change in the future.
314
315
316
317       val spellcheck : string list -> string -> string list
318
319
320       spellcheck env name takes a list of names env that exist in the current
321       environment and an erroneous name , and returns a list  of  suggestions
322       taken  from  env  , that are close enough to name that it may be a typo
323       for one of them.
324
325
326
327       val did_you_mean : Format.formatter -> (unit -> string list) -> unit
328
329
330       did_you_mean ppf get_choices hints that the user may have meant one  of
331       the option returned by calling get_choices . It does nothing if the re‐
332       turned list is empty.
333
334       The unit -> ...  thunking is meant to delay any potentially-slow compu‐
335       tation  (typically  computing  edit-distance  with many things from the
336       current environment) to when the hint message is  to  be  printed.  You
337       should   print   an   understandable   error   message  before  calling
338       did_you_mean , so that users get a clear notification  of  the  failure
339       even if producing the hint is slow.
340
341
342
343       val cut_at : string -> char -> string * string
344
345
346       String.cut_at  s  c returns a pair containing the sub-string before the
347       first occurrence of c in s , and the sub-string after the first  occur‐
348       rence of c in s .  let (before, after) = String.cut_at s c in
349           before ^ String.make 1 c ^ after is the identity if s contains c .
350
351       Raise Not_found if the character does not appear in the string
352
353
354       Since 4.01
355
356
357
358       val ordinal_suffix : int -> string
359
360
361       ordinal_suffix  n  is the appropriate suffix to append to the numeral n
362       as an ordinal number: 1 -> "st" , 2 -> "nd" , 3 -> "rd" , 4 ->  "th"  ,
363       and  so on.  Handles larger numbers (e.g., 42 -> "nd" ) and the numbers
364       11--13 (which all get "th" ) correctly.
365
366
367       module Color : sig end
368
369
370
371
372       module Error_style : sig end
373
374
375
376
377
378       val normalise_eol : string -> string
379
380
381       normalise_eol s returns a fresh copy of s with any '\r' characters  re‐
382       moved.  Intended  for  pre-processing  text  which will subsequently be
383       printed on a channel which performs EOL transformations (i.e. Windows)
384
385
386
387       val delete_eol_spaces : string -> string
388
389
390       delete_eol_spaces s returns a fresh copy of s with any end of line spa‐
391       ces  removed.  Intended  to  normalize  the  output of the toplevel for
392       tests.
393
394
395
396       val pp_two_columns : ?sep:string -> ?max_lines:int ->  Format.formatter
397       -> (string * string) list -> unit
398
399
400       pp_two_columns  ?sep ?max_lines ppf l prints the lines in l as two col‐
401       umns separated by sep ("|" by default).  max_lines can be used to indi‐
402       cate a maximum number of lines to print -- an ellipsis gets inserted at
403       the middle if the input has too many lines.
404
405       Example:
406
407       pp_two_columns  ~max_lines:3  Format.std_formatter  [  "abc",  "hello";
408       "def", "zzz"; "a"  , "bllbl"; "bb" , "dddddd"; ]
409
410       prints
411
412       abc | hello ...  bb  | dddddd
413
414
415
416
417       val show_config_and_exit : unit -> unit
418
419       configuration variables
420
421
422
423       val show_config_variable_and_exit : string -> unit
424
425
426
427
428       val  get_build_path_prefix_map  : unit -> Build_path_prefix_map.map op‐
429       tion
430
431       Returns the map encoded in the BUILD_PATH_PREFIX_MAP environment  vari‐
432       able.
433
434
435
436       val debug_prefix_map_flags : unit -> string list
437
438       Returns the list of --debug-prefix-map flags to be passed to the assem‐
439       bler, built from the BUILD_PATH_PREFIX_MAP environment variable.
440
441
442
443       val print_if : Format.formatter -> bool ref -> (Format.formatter ->  'a
444       -> unit) -> 'a -> 'a
445
446
447       print_if ppf flag fmt x prints x with fmt on ppf if b is true.
448
449
450       type filepath = string
451
452
453
454
455       type modname = string
456
457
458
459
460       type crcs = (modname * Digest.t option) list
461
462
463
464
465       type alerts = string Stdlib.String.Map.t
466
467
468
469
470       module Magic_number : sig end
471
472
473
474
475
476
477
478OCamldoc                          2023-07-20                           Misc(3)
Impressum