man-pages/man3/Misc.3o.html
2021-03-31 01:06:50 +01:00

989 lines
12 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of Misc</TITLE>
</HEAD><BODY>
<H1>Misc</H1>
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
Misc - Miscellaneous useful types and functions
<A NAME="lbAC">&nbsp;</A>
<H2>Module</H2>
Module Misc
<A NAME="lbAD">&nbsp;</A>
<H2>Documentation</H2>
<P>
Module
<B>Misc</B>
<BR>&nbsp;:&nbsp;
<B>sig end</B>
<P>
<P>
Miscellaneous useful types and functions
<P>
Warning: this module is unstable and part of
<B>Compiler_libs</B>
.
<P>
<P>
<P>
<P>
<P>
<P>
<I>val fatal_error </I>
:
<B>string -&gt; 'a</B>
<P>
<P>
<P>
<P>
<I>val fatal_errorf </I>
:
<B>('a, Format.formatter, unit, 'b) format4 -&gt; 'a</B>
<P>
<P>
<P>
<P>
<I>exception Fatal_error </I>
<P>
<P>
<P>
<P>
<P>
<I>val try_finally </I>
:
<B>?always:(unit -&gt; unit) -&gt; ?exceptionally:(unit -&gt; unit) -&gt; (unit -&gt; 'a) -&gt; 'a</B>
<P>
<P>
<B>try_finally work ~always ~exceptionally</B>
is designed to run code
in
<B>work</B>
that may fail with an exception, and has two kind of
cleanup routines:
<B>always</B>
, that must be run after any execution
of the function (typically, freeing system resources), and
<B>exceptionally</B>
, that should be run only if
<B>work</B>
or
<B>always</B>
failed with an exception (typically, undoing user-visible state
changes that would only make sense if the function completes
correctly). For example:
<P>
<P>
<B>let objfile = outputprefix ^ .cmo in</B>
<B>let oc = open_out_bin objfile in</B>
<B>Misc.try_finally</B>
<B>(fun () -&gt;</B>
<B>bytecode</B>
<B>++ Timings.(accumulate_time (Generate sourcefile))</B>
<B>(Emitcode.to_file oc modulename objfile);</B>
<B>Warnings.check_fatal ())</B>
<B>~always:(fun () -&gt; close_out oc)</B>
<B>~exceptionally:(fun _exn -&gt; remove_file objfile);</B>
<B><P>
</B>
If
<B>exceptionally</B>
fail with an exception, it is propagated as
usual.
<P>
If
<B>always</B>
or
<B>exceptionally</B>
use exceptions internally for
control-flow but do not raise, then
<B>try_finally</B>
is careful to
preserve any exception backtrace coming from
<B>work</B>
or
<B>always</B>
for easier debugging.
<P>
<P>
<P>
<I>val map_end </I>
:
<B>('a -&gt; 'b) -&gt; 'a list -&gt; 'b list -&gt; 'b list</B>
<P>
<P>
<P>
<P>
<I>val map_left_right </I>
:
<B>('a -&gt; 'b) -&gt; 'a list -&gt; 'b list</B>
<P>
<P>
<P>
<P>
<I>val for_all2 </I>
:
<B>('a -&gt; 'b -&gt; bool) -&gt; 'a list -&gt; 'b list -&gt; bool</B>
<P>
<P>
<P>
<P>
<I>val replicate_list </I>
:
<B>'a -&gt; int -&gt; 'a list</B>
<P>
<P>
<P>
<P>
<I>val list_remove </I>
:
<B>'a -&gt; 'a list -&gt; 'a list</B>
<P>
<P>
<P>
<P>
<I>val split_last </I>
:
<B>'a list -&gt; 'a list * 'a</B>
<P>
<P>
<P>
<P>
<I>val may </I>
:
<B>('a -&gt; unit) -&gt; 'a option -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val may_map </I>
:
<B>('a -&gt; 'b) -&gt; 'a option -&gt; 'b option</B>
<P>
<P>
<P>
<I>type ref_and_value </I>
=
<BR>&nbsp;|&nbsp;R
<B>: </B>
<B>'a ref * 'a</B>
<B>-&gt; </B>
<B>ref_and_value</B>
<BR>&nbsp;
<P>
<P>
<P>
<P>
<I>val protect_refs </I>
:
<B>ref_and_value list -&gt; (unit -&gt; 'a) -&gt; 'a</B>
<P>
<P>
<B>protect_refs l f</B>
temporarily sets
<B>r</B>
to
<B>v</B>
for each
<B>R (r, v)</B>
in
<B>l</B>
while executing
<B>f</B>
. The previous contents of the references is restored
even if
<B>f</B>
raises an exception.
<P>
<P>
<I>module Stdlib : </I>
<B>sig end</B>
<P>
<P>
<P>
<P>
<P>
<I>val find_in_path </I>
:
<B>string list -&gt; string -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val find_in_path_rel </I>
:
<B>string list -&gt; string -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val find_in_path_uncap </I>
:
<B>string list -&gt; string -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val remove_file </I>
:
<B>string -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val expand_directory </I>
:
<B>string -&gt; string -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val split_path_contents </I>
:
<B>?sep:char -&gt; string -&gt; string list</B>
<P>
<P>
<P>
<P>
<I>val create_hashtable </I>
:
<B>int -&gt; ('a * 'b) list -&gt; ('a, 'b) Hashtbl.t</B>
<P>
<P>
<P>
<P>
<I>val copy_file </I>
:
<B>in_channel -&gt; out_channel -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val copy_file_chunk </I>
:
<B>in_channel -&gt; out_channel -&gt; int -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val string_of_file </I>
:
<B>in_channel -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val output_to_file_via_temporary </I>
:
<B>?mode:open_flag list -&gt;</B>
<B>string -&gt; (string -&gt; out_channel -&gt; 'a) -&gt; 'a</B>
<P>
<P>
<P>
<P>
<I>val log2 </I>
:
<B>int -&gt; int</B>
<P>
<P>
<P>
<P>
<I>val align </I>
:
<B>int -&gt; int -&gt; int</B>
<P>
<P>
<P>
<P>
<I>val no_overflow_add </I>
:
<B>int -&gt; int -&gt; bool</B>
<P>
<P>
<P>
<P>
<I>val no_overflow_sub </I>
:
<B>int -&gt; int -&gt; bool</B>
<P>
<P>
<P>
<P>
<I>val no_overflow_mul </I>
:
<B>int -&gt; int -&gt; bool</B>
<P>
<P>
<P>
<P>
<I>val no_overflow_lsl </I>
:
<B>int -&gt; int -&gt; bool</B>
<P>
<P>
<P>
<I>module Int_literal_converter : </I>
<B>sig end</B>
<P>
<P>
<P>
<P>
<P>
<I>val chop_extensions </I>
:
<B>string -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val search_substring </I>
:
<B>string -&gt; string -&gt; int -&gt; int</B>
<P>
<P>
<P>
<P>
<I>val replace_substring </I>
:
<B>before:string -&gt; after:string -&gt; string -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val rev_split_words </I>
:
<B>string -&gt; string list</B>
<P>
<P>
<P>
<P>
<I>val get_ref </I>
:
<B>'a list ref -&gt; 'a list</B>
<P>
<P>
<P>
<P>
<I>val set_or_ignore </I>
:
<B>('a -&gt; 'b option) -&gt; 'b option ref -&gt; 'a -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val fst3 </I>
:
<B>'a * 'b * 'c -&gt; 'a</B>
<P>
<P>
<P>
<P>
<I>val snd3 </I>
:
<B>'a * 'b * 'c -&gt; 'b</B>
<P>
<P>
<P>
<P>
<I>val thd3 </I>
:
<B>'a * 'b * 'c -&gt; 'c</B>
<P>
<P>
<P>
<P>
<I>val fst4 </I>
:
<B>'a * 'b * 'c * 'd -&gt; 'a</B>
<P>
<P>
<P>
<P>
<I>val snd4 </I>
:
<B>'a * 'b * 'c * 'd -&gt; 'b</B>
<P>
<P>
<P>
<P>
<I>val thd4 </I>
:
<B>'a * 'b * 'c * 'd -&gt; 'c</B>
<P>
<P>
<P>
<P>
<I>val for4 </I>
:
<B>'a * 'b * 'c * 'd -&gt; 'd</B>
<P>
<P>
<P>
<I>module LongString : </I>
<B>sig end</B>
<P>
<P>
<P>
<P>
<P>
<I>val edit_distance </I>
:
<B>string -&gt; string -&gt; int -&gt; int option</B>
<P>
<P>
<B>edit_distance a b cutoff</B>
computes the edit distance between
strings
<B>a</B>
and
<B>b</B>
. To help efficiency, it uses a cutoff: if the
distance
<B>d</B>
is smaller than
<B>cutoff</B>
, it returns
<B>Some d</B>
, else
<B>None</B>
.
<P>
The distance algorithm currently used is Damerau-Levenshtein: it
computes the number of insertion, deletion, substitution of
letters, or swapping of adjacent letters to go from one word to the
other. The particular algorithm may change in the future.
<P>
<P>
<P>
<I>val spellcheck </I>
:
<B>string list -&gt; string -&gt; string list</B>
<P>
<P>
<B>spellcheck env name</B>
takes a list of names
<B>env</B>
that exist in
the current environment and an erroneous
<B>name</B>
, and returns a
list of suggestions taken from
<B>env</B>
, that are close enough to
<B>name</B>
that it may be a typo for one of them.
<P>
<P>
<P>
<I>val did_you_mean </I>
:
<B>Format.formatter -&gt; (unit -&gt; string list) -&gt; unit</B>
<P>
<P>
<B>did_you_mean ppf get_choices</B>
hints that the user may have meant
one of the option returned by calling
<B>get_choices</B>
. It does nothing
if the returned list is empty.
<P>
The
<B>unit -&gt; ...</B>
thunking is meant to delay any potentially-slow
computation (typically computing edit-distance with many things
from the current environment) to when the hint message is to be
printed. You should print an understandable error message before
calling
<B>did_you_mean</B>
, so that users get a clear notification of
the failure even if producing the hint is slow.
<P>
<P>
<P>
<I>val cut_at </I>
:
<B>string -&gt; char -&gt; string * string</B>
<P>
<P>
<B>String.cut_at s c</B>
returns a pair containing the sub-string before
the first occurrence of
<B>c</B>
in
<B>s</B>
, and the sub-string after the
first occurrence of
<B>c</B>
in
<B>s</B>
.
<B>let (before, after) = String.cut_at s c in</B>
<B>before ^ String.make 1 c ^ after</B>
is the identity if
<B>s</B>
contains
<B>c</B>
.
<P>
Raise
<B>Not_found</B>
if the character does not appear in the string
<P>
<P>
<B>Since</B>
4.01
<P>
<P>
<I>module Color : </I>
<B>sig end</B>
<P>
<P>
<P>
<P>
<I>module Error_style : </I>
<B>sig end</B>
<P>
<P>
<P>
<P>
<P>
<I>val normalise_eol </I>
:
<B>string -&gt; string</B>
<P>
<P>
<B>normalise_eol s</B>
returns a fresh copy of
<B>s</B>
with any '\r' characters
removed. Intended for pre-processing text which will subsequently be printed
on a channel which performs EOL transformations (i.e. Windows)
<P>
<P>
<P>
<I>val delete_eol_spaces </I>
:
<B>string -&gt; string</B>
<P>
<P>
<B>delete_eol_spaces s</B>
returns a fresh copy of
<B>s</B>
with any end of
line spaces removed. Intended to normalize the output of the
toplevel for tests.
<P>
<P>
<P>
<I>val pp_two_columns </I>
:
<B>?sep:string -&gt;</B>
<B>?max_lines:int -&gt; Format.formatter -&gt; (string * string) list -&gt; unit</B>
<P>
<P>
<B>pp_two_columns ?sep ?max_lines ppf l</B>
prints the lines in
<B>l</B>
as two
columns separated by
<B>sep</B>
(&quot;|&quot; by default).
<B>max_lines</B>
can be used to
indicate a maximum number of lines to print -- an ellipsis gets inserted at
the middle if the input has too many lines.
<P>
Example:
<P>
pp_two_columns ~max_lines:3 Format.std_formatter [
&quot;abc&quot;, &quot;hello&quot;;
&quot;def&quot;, &quot;zzz&quot;;
&quot;a&quot; , &quot;bllbl&quot;;
&quot;bb&quot; , &quot;dddddd&quot;;
]
<P>
prints
<P>
abc | hello
...
bb | dddddd
<P>
<P>
<P>
<P>
<P>
<A NAME="lbAE">&nbsp;</A>
<H3>Hook machinery</H3>
<P>
Hooks machinery:
<B>add_hook name f</B>
will register a function that will be called on the
argument of a later call to
<B>apply_hooks</B>
. Hooks are applied in the
lexicographical order of their names.
<P>
<I>type hook_info </I>
= {
<BR>&nbsp;sourcefile&nbsp;:&nbsp;
<B>string</B>
;
<BR>&nbsp;}
<P>
<P>
<P>
<P>
<P>
<I>exception HookExnWrapper </I>
<B>of {</B>
<BR>&nbsp;error&nbsp;:&nbsp;
<B>exn</B>
;
<BR>&nbsp;hook_name&nbsp;:&nbsp;
<B>string</B>
;
<BR>&nbsp;hook_info&nbsp;:&nbsp;
<B>hook_info</B>
;
<BR>&nbsp;}
<P>
<P>
An exception raised by a hook will be wrapped into a
<B>HookExnWrapper</B>
constructor by the hook machinery.
<P>
<P>
<P>
<I>val raise_direct_hook_exn </I>
:
<B>exn -&gt; 'a</B>
<P>
A hook can use
<B>raise_unwrapped_hook_exn</B>
to raise an exception that will
not be wrapped into a
<B>Misc.HookExnWrapper</B>
.
<P>
<P>
<I>module type HookSig = </I>
<B>sig end</B>
<P>
<P>
<P>
<P>
<I>module MakeHooks : </I>
<B>functor (M : sig end) -&gt; sig end</B>
<P>
<P>
<P>
<P>
<P>
<I>val show_config_and_exit </I>
:
<B>unit -&gt; unit</B>
<P>
configuration variables
<P>
<P>
<P>
<I>val show_config_variable_and_exit </I>
:
<B>string -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val get_build_path_prefix_map </I>
:
<B>unit -&gt; Build_path_prefix_map.map option</B>
<P>
Returns the map encoded in the
<B>BUILD_PATH_PREFIX_MAP</B>
environment
variable.
<P>
<P>
<P>
<I>val debug_prefix_map_flags </I>
:
<B>unit -&gt; string list</B>
<P>
Returns the list of
<B>--debug-prefix-map</B>
flags to be passed to the
assembler, built from the
<B>BUILD_PATH_PREFIX_MAP</B>
environment variable.
<P>
<P>
<P>
<I>val print_if </I>
:
<B>Format.formatter -&gt;</B>
<B>bool ref -&gt; (Format.formatter -&gt; 'a -&gt; unit) -&gt; 'a -&gt; 'a</B>
<P>
<P>
<B>print_if ppf flag fmt x</B>
prints
<B>x</B>
with
<B>fmt</B>
on
<B>ppf</B>
if
<B>b</B>
is true.
<P>
<P>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
<DT id="2"><A HREF="#lbAC">Module</A><DD>
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
<DL>
<DT id="4"><A HREF="#lbAE">Hook machinery</A><DD>
</DL>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:05:48 GMT, March 31, 2021
</BODY>
</HTML>