Модуль 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 repeated_label : (string option * 'a) list -> string option

Обнаруживает повторяющуюся метку — для использования с кортежами с метками.

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

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, string) Result.t

Нормализует имя файла Foo.ml в foo.ml с использованием NFC и приведения к нижнему регистру. Возвращает Error, если входные данные не являются допустимой последовательностью байтов UTF-8

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. При достижении EOF в ic вызывает исключение End_of_file.

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, если символ не встречается в строке

Начиная с версии 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'. Предназначена для предварительной обработки текста, который впоследствии будет выведен в канал, преобразующий символы конца строки (например, в Windows)

val delete_eol_spaces : string -> string

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

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

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 align_hint : prefix:string ->       main:Format_doc.t -> hint:Format_doc.t -> Format_doc.t * Format_doc.t

aligned_hint main hint выравнивает по вертикали сообщение main и подсказку. Вертикальное выравнивание регулируется с помощью блоков @{<ralign> ... @}: начало блока в подсказке или основном сообщении смещается влево, чтобы концы двух блоков выровнялись по вертикали с учётом уже имеющегося prefix перед основным сообщением. Например:

let main, sub =
  align_hint
    ~prefix:"Error: "
    (doc_printf "@{<ralign>The value @}%a is not an instance variable"
      Style.inline_code "foobar"
    )
    (doc_printf
      "@{<ralign>Did you mean @}%a" Style.inline_code "foobaz"
    ) in
   printf "Error: %a%a" pp_doc main pp_doc sub

выводит следующий текст:

Error:   The value "foobaz" is not an instance variable
Hint: Did you mean "foobar"?

основное сообщение смещено влево, чтобы выровнять "foobaz" и "foobar".

val align_error_hint : main:Format_doc.t -> hint:Format_doc.t -> Format_doc.t * Format_doc.t

То же, что align_hint ~prefix:"Error: "

val aligned_hint : prefix:string ->       Format_doc.formatter ->       ('a, Format_doc.formatter, unit, Format_doc.t option -> unit) format4 ->       'a

aligned_hint ~prefix fmt ... hint выравнивает возможную подсказку с основным сообщением об ошибке, сформированным строкой формата fmt, перед выводом обоих сообщений.

val did_you_mean : ?pp:string Format_doc.printer -> string list -> Format_doc.t option

did_you_mean ~pp choices подсказывает, что пользователь, возможно, имел в виду один из вариантов в choices.

Каждый вариант выводится функцией pp или функцией Style.inline_code, если pp=None.

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 print_see_manual : int list Format_doc.printer

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

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

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 invert_build_path_prefix_map : string -> string list

Возвращает возможные пути (в порядке приоритета), из которых мог возникнуть заданный путь до переписывания с использованием переменной окружения BUILD_PATH_PREFIX_MAP.

val debug_prefix_map_flags : unit -> string list

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

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

module Magic_number: sig .. end

Минимальная поддержка символов Юникода в идентификаторах

В настоящее время в идентификаторах допускаются следующие символы:

Буквы ASCII A-Z a-z
Буквы Latin-1 (U+00C0 – U+00FF, кроме U+00D7 и U+00F7)
Последовательности символов, которые нормализуются в перечисленные выше символы по NFC
цифры 0-9, подчёркивание, апостроф

module Utf8_lexeme: sig .. end

module RuntimeID: sig .. end

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

type filepath = string

type modname = string

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

type alerts = string Stdlib.String.Map.t