Модуль Misc

module Misc: sig .. end

Различные полезные типы и функции

Предупреждение: этот модуль нестабилен и является частью compiler-libs.

Сообщения об ошибках критичных ошибок

val fatal_error : string -> 'a

Вызвать исключение Fatal_error с заданной строкой.

val fatal_errorf : ('a, Format.formatter, unit, 'b) format4 -> 'a

Форматировать аргументы в соответствии с заданной строкой формата и вызвать Fatal_error с полученной строкой.

exception Fatal_error

Исключения и завершение работы

val try_finally : ?always:(unit -> unit) -> ?exceptionally:(unit -> unit) -> (unit -> 'a) -> 'a

try_finally work ~always ~exceptionally предназначен для выполнения кода в work, который может завершиться исключением, и имеет два типа процедур очистки: always, которые должны выполняться после любого выполнения функции (обычно, освобождение системных ресурсов), и exceptionally, которые должны выполняться только в том случае, если work или always завершились с исключением (обычно, отмена видимых пользователю изменений состояния, которые имеют смысл только в том случае, если функция завершилась успешно). Например:

      let objfile = outputprefix ^ ".cmo" in
      let oc = open_out_bin objfile in
      Misc.try_finally
        (fun () ->
           bytecode
           ++ Timings.(accumulate_time (Generate sourcefile))
               (Emitcode.to_file oc modulename objfile);
           Warnings.check_fatal ())
        ~always:(fun () -> close_out oc)
        ~exceptionally:(fun _exn -> remove_file objfile);

Если exceptionally завершится исключением, оно будет распространено в обычном порядке.

Если always или exceptionally используют исключения внутри для управления потоком, но не поднимают их, то try_finally позаботится о сохранении любого трассировки исключений, исходящих от work или always, для более удобной отладки.

val reraise_preserving_backtrace : exn -> (unit -> unit) -> 'a

reraise_preserving_backtrace e f (f (); raise e), за исключением того, что текущая трассировка сохраняется, даже если f использует исключения внутри.

Операции со списками

val map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list

map_end f l t это map f l @ t, только более эффективно.

val rev_map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list

map_end f l t это map f (rev l) @ t, только более эффективно.

val map_left_right : ('a -> 'b) -> 'a list -> 'b list

Как List.map, с гарантированным порядком вычисления слева направо

val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool

То же, что и List.for_all, но для бинарного предиката. Кроме того, этот for_all2 никогда не терпит неудачу: если у двух списков разная длина, он возвращает false.

val replicate_list : 'a -> int -> 'a list

replicate_list elem n - это список с n элементами, все идентичными elem.

val list_remove : 'a -> 'a list -> 'a list

list_remove x l возвращает копию l с удаленным первым элементом, равным x.

val split_last : 'a list -> 'a list * 'a

Возвращает последний элемент и остальные элементы данного списка.

Операции с хеш-таблицами

val create_hashtable : int -> ('a * 'b) list -> ('a, 'b) Hashtbl.t

Создает хеш-таблицу с заданным начальным размером и заполняет ее заданными связями.

Расширения стандартной библиотеки

module Stdlib: sig .. end

Операции с файлами и путями к файлам

val find_in_path : string list -> string -> string

Поиск файла в списке каталогов.

val find_in_path_rel : string list -> string -> string

Поиск относительного файла в списке каталогов.

val normalized_unit_filename : string -> string

Нормализовать имя файла Foo.ml до foo.ml

val find_in_path_normalized : string list -> string -> string

То же, что и Misc.find_in_path_rel, но также ищет нормализованное имя файла, т.е. если имя является Foo.ml, разрешить /path/Foo.ml и /path/foo.ml соответствовать.

val remove_file : string -> unit

Удалить заданный файл, если он существует и является обычным файлом. Ничего не делает для других типов файлов. Никогда не вызывает ошибки.

val expand_directory : string -> string -> string

expand_directory alt file в конечном итоге расширяет + в начале файла до alt (альтернативный корневой каталог)

val split_path_contents : ?sep:char -> string -> string list

split_path_contents ?sep s интерпретирует s как значение переменной "PATH" и возвращает соответствующий список каталогов. s разделяется с помощью разделителя, специфичного для платформы, или ~sep, если он передан.

Возвращает пустой список, если s пуст.

val copy_file : in_channel -> out_channel -> unit

copy_file ic oc считывает содержимое файла ic и копирует его в oc. Останавливается при встрече EOF в ic.

val copy_file_chunk : in_channel -> out_channel -> int -> unit

copy_file_chunk ic oc n считывает n байта из ic и копирует их в oc. Вызывает End_of_file при встрече EOF в ic.

val string_of_file : in_channel -> string

string_of_file ic считывает содержимое файла ic и копирует его в строку. Останавливается при встрече EOF в ic.

val output_to_file_via_temporary : ?mode:open_flag list ->       string -> (string -> out_channel -> 'a) -> 'a

Выводит данные во временный файл, а затем переименовывает его (насколько это возможно атомарно) в желаемое имя выходного файла. output_to_file_via_temporary filename fn открывает временный файл, который передается fn (имя + выходной канал). Когда fn возвращается, канал закрывается, а временный файл переименовывается в filename.

val protect_writing_to_file : filename:string -> f:(out_channel -> 'a) -> 'a

Открыть заданный filename для записи (в двоичном режиме), передать out_channel в заданную функцию, затем закрыть канал. Если функция вызывает исключение, то filename будет удален.

val concat_null_terminated : string list -> string

concat_null_terminated [x1;x2; ... xn] это x1 ^ "\000" ^ x2 ^ "\000" ^ ... ^ xn ^ "\000"

val split_null_terminated : string -> string list

split_null_terminated s аналогично String.split_on_char '\000', но игнорирует заключительный разделитель, если он есть

val chop_extensions : string -> string

Возвращает данное имя файла без расширений. Расширение - это самая длинная постфиксная часть, начинающаяся с точки и не включающая разделитель каталогов, .xyz.uvw например.

Возвращает данное имя, если оно не содержит расширение.

Операции с целыми числами

val log2 : int -> int

log2 n возвращает s, такое, что n = 1 lsl s если n является степенью 2

val align : int -> int -> int

align n a округляет n вверх до кратного a (степени 2).

val no_overflow_add : int -> int -> bool

no_overflow_add n1 n2 возвращает true, если вычисление n1 + n2 не приводит к переполнению.

val no_overflow_sub : int -> int -> bool

no_overflow_sub n1 n2 возвращает true, если вычисление n1 - n2 не приводит к переполнению.

val no_overflow_mul : int -> int -> bool

no_overflow_mul n1 n2 возвращает true, если вычисление n1 * n2 не приводит к переполнению.

val no_overflow_lsl : int -> int -> bool

no_overflow_lsl n k возвращает true, если вычисление n lsl k не приводит к переполнению.

val letter_of_int : int -> string

module Int_literal_converter: sig .. end

val find_first_mono : (int -> bool) -> int

find_first_mono p принимает предикат целого числа p : int -> bool, который мы предполагаем: 1. монотонный по натуральным числам: если a <= b тогда p a подразумевает p b, 2. удовлетворяется для некоторых натуральных чисел в диапазоне 0; max_int (это эквивалентно: p max_int = true).

find_first_mono p - это наименьшее натуральное число N, которое удовлетворяет p, вычисляемое в O(log(N)) вызовах p.

Наша реализация поддерживает два случая, когда условия на p не соблюдаются:

Если p всегда false, мы молча возвращаем max_int вместо цикла или аварийного завершения.
Если p не монотонный, но в конечном итоге истинный, мы возвращаем какое-то удовлетворяющее значение.

Операции со строками

val search_substring : string -> string -> int -> int

search_substring pat str start возвращает позицию первого вхождения строки pat в строке str. Поиск начинается со смещения start в str. Вызвать Not_found если pat не встречается.

val replace_substring : before:string -> after:string -> string -> string

replace_substring ~before ~after str заменяет все вхождения before на after в str и возвращает получившуюся строку.

val rev_split_words : string -> string list

rev_split_words s разделяет s на разделенные пробелами слова и возвращает список слов в обратном порядке.

val cut_at : string -> char -> string * string

String.cut_at s c возвращает пару, содержащую подстроку перед первым вхождением c в s, и подстроку после первого вхождения c в s. let (before, after) = String.cut_at s c in before ^ String.make 1 c ^ after является тождественным отображением, если s содержит c.

Вызвать Not_found если символ не появляется в строке

Since 4.01

val ordinal_suffix : int -> string

ordinal_suffix n — это подходящий суффикс для добавления к числу n в качестве порядкового номера: 1 —> "st", 2 —> "nd", 3 —> "rd", 4 —> "th", и так далее. Обрабатывает более крупные числа (например, 42 —> "nd") и числа 11—13 (которые все получают "th") корректно.

val normalise_eol : string -> string

normalise_eol s возвращает свежую копию s с удаленными символами '\r'. Предназначено для предобработки текста, который впоследствии будет выведен на канал, выполняющий преобразования EOL (например, Windows).

val delete_eol_spaces : string -> string

delete_eol_spaces s возвращает свежую копию s с удаленными пробелами в конце строк. Предназначено для нормализации вывода верхнего уровня для тестов.

Операции со ссылками

type ref_and_value =

`\|`	`R : 'a ref * 'a -> ref_and_value`

val protect_refs : ref_and_value list -> (unit -> 'a) -> 'a

protect_refs l f временно устанавливает r в значение v для каждой R (r, v) в l во время выполнения f. Предыдущее содержимое ссылок восстанавливается, даже если f вызывает исключение, без изменения стека вызовов исключения.

val get_ref : 'a list ref -> 'a list

get_ref lr возвращает содержимое ссылки на список lr и сбрасывает её содержимое до пустого списка.

val set_or_ignore : ('a -> 'b option) -> 'b option ref -> 'a -> unit

set_or_ignore f opt x устанавливает opt в значение f x если оно возвращает Some _, или оставляет его без изменений, если возвращает None.

Операции с тройками и четвёрками

val fst3 : 'a * 'b * 'c -> 'a

val snd3 : 'a * 'b * 'c -> 'b

val thd3 : 'a * 'b * 'c -> 'c

val fst4 : 'a * 'b * 'c * 'd -> 'a

val snd4 : 'a * 'b * 'c * 'd -> 'b

val thd4 : 'a * 'b * 'c * 'd -> 'c

val for4 : 'a * 'b * 'c * 'd -> 'd

Проверка орфографии и предложения «Вы имели в виду»

val edit_distance : string -> string -> int -> int option

edit_distance a b cutoff вычисляет расстояние редактирования между строками a и b. Для повышения эффективности используется пороговое значение: если расстояние d меньше cutoff, возвращается Some d, иначе None.

В настоящее время используется алгоритм Дамерау-Левенштейна: он вычисляет количество вставок, удалений, замен букв или перестановки соседних букв для перехода от одного слова к другому. В будущем алгоритм может измениться.

val spellcheck : string list -> string -> string list

spellcheck env name принимает список имён env из текущей среды и ошибочное name, и возвращает список предложений из env, которые достаточно близки к name для того, чтобы это могло быть опечаткой одного из них.

val did_you_mean : Format.formatter -> (unit -> string list) -> unit

did_you_mean ppf get_choices подразумевает, что пользователь мог иметь в виду один из вариантов, возвращенных вызовом get_choices. Ничего не делает, если возвращаемый список пуст.

Толщинка unit -> ... предназначена для отсрочки потенциально медленных вычислений (обычно вычисления расстояния редактирования со многими элементами из текущей среды) до момента, когда сообщение подсказки должно быть напечатано. Вы должны напечатать понятное сообщение об ошибке перед вызовом did_you_mean, чтобы пользователи получали ясное уведомление об ошибке, даже если создание подсказки происходит медленно.

module Color: sig .. end

Обнаружение поддержки цвета

Обработка стилей для вывода в терминал

module Style: sig .. end

module Error_style: sig .. end

Форматированный вывод

val print_if : Format.formatter ->       bool ref -> (Format.formatter -> 'a -> unit) -> 'a -> 'a

print_if ppf flag fmt x печатает x с fmt на ppf если b истинно.

val pp_two_columns : ?sep:string ->       ?max_lines:int -> Format.formatter -> (string * string) list -> unit

pp_two_columns ?sep ?max_lines ppf l печатает строки в l в виде двух столбцов, разделенных sep («|» по умолчанию). max_lines можно использовать для указания максимального количества строк для печати — многоточие вставляется посередине, если вход содержит слишком много строк.

Пример:

pp_two_columns ~max_lines:3 Format.std_formatter [
      "abc", "hello";
      "def", "zzz";
      "a"  , "bllbl";
      "bb" , "dddddd";
    ]

печатает

    abc | hello
    ...
    bb  | dddddd

val print_see_manual : Format.formatter -> int list -> unit

См. раздел руководства

Отображение переменных конфигурации

val show_config_and_exit : unit -> unit

Отобразить значения всех переменных конфигурации компилятора из модуля Config, затем выйти из программы с кодом 0.

val show_config_variable_and_exit : string -> unit

Отобразить значение заданной переменной конфигурации, затем выйти из программы с кодом 0.

Обработка карт сборки

Карты сборки заставляют компилятор нормализовать имена файлов, встроенные в объектные файлы, что приводит к более воспроизводимым сборкам.

val get_build_path_prefix_map : unit -> Build_path_prefix_map.map option

Возвращает карту, закодированную в переменной окружения BUILD_PATH_PREFIX_MAP.

val debug_prefix_map_flags : unit -> string list

Возвращает список флагов --debug-prefix-map для передачи ассемблеру, составленный из переменной окружения BUILD_PATH_PREFIX_MAP.

Обработка магических чисел

module Magic_number: sig .. end

Разные псевдонимы типов

type filepath = string

type modname = string

type crcs = (modname * Digest.t option) list

type alerts = string Stdlib.String.Map.t