Расположение модуля

module Location: sig .. end

Расположения исходного кода (диапазоны позиций), используемые в дереве разбора.

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

type t = Warnings.loc = {

	`loc_start : Lexing.position;`
	`loc_end : Lexing.position;`
	`loc_ghost : bool;`

}

t представляет диапазон символов в исходном коде.

loc_ghost=false, если AST, описываемое расположением, можно разобрать, используя это расположение. Во всех остальных случаях loc_ghost должно быть равно true. У большинства расположений, созданных парсером, loc_ghost=false. Если loc_ghost=true, расположение обычно является приблизительной оценкой.

Эта информация используется такими инструментами, как merlin, которым необходимо сопоставлять исходный код с деревьями разбора или последующими AST. ocamlprof пропускает инструментирование фиктивных узлов.

Пример: для `let f x = x` имеем:

элемент структуры с расположением "let f x = x"
шаблон "f" с расположением "f"
выражение "fun x -> x" с расположением "x = x" и loc_ghost=true
шаблон "x" с расположением "x"
выражение "x" с расположением "x". В этом случае у всех узлов loc_ghost=false, кроме узла "fun x -> x", поскольку Parser.expression (Lexing.from_string "x = x") не удалось бы разобрать. Напротив, для `let f = fun x -> x` у всех узлов loc_ghost=false.

Директивы строк могут произвольно изменять имена файлов и номера строк; это не связано с loc_ghost, которое описывает диапазон символов от loc_start.pos_cnum до loc_end.pos_cnum в разобранной строке.

Примечание об использовании Lexing.position в этом модуле. Если pos_fname = "", используйте вместо него !input_name. Если pos_lnum = -1, то pos_bol = 0. Используйте pos_cnum и повторно разберите файл, чтобы получить номера строк и символов. В противном случае все поля корректны.

val none : t

Произвольное значение типа t; описывает пустой фиктивный диапазон.

val is_none : t -> bool

true для Location.none, false для любого другого расположения

val in_file : string -> t

Возвращает пустой фиктивный диапазон, расположенный в указанном файле.

val init : Lexing.lexbuf -> string -> unit

Задает имени файла и номеру строки lexbuf значения, соответствующие началу указанного файла.

val curr : Lexing.lexbuf -> t

Получает расположение текущего токена из lexbuf.

val symbol_rloc : unit -> t

val symbol_gloc : unit -> t

val rhs_loc : int -> t

rhs_loc n возвращает расположение символа в позиции n, начиная с 1, в текущем правиле парсера.

val rhs_interval : int -> int -> t

val get_pos_info : Lexing.position -> string * int * int

файл, строка, символ

type 'a loc = {

	`txt : 'a;`
	`loc : t;`

}

val mknoloc : 'a -> 'a loc

val mkloc : 'a -> t -> 'a loc

val map : ('a -> 'b) -> 'a loc -> 'b loc

Сведения о входных данных

val input_name : string ref

val input_lexbuf : Lexing.lexbuf option ref

val input_phrase_buffer : Buffer.t option ref

Функции для toplevel

val echo_eof : unit -> unit

val reset : unit -> unit

Перезапись пути

val rewrite_absolute_path : string -> string

rewrite_absolute_path path переписывает path с учетом переменной BUILD_PATH_PREFIX_MAP, если она задана. Функция не проверяет, является ли path абсолютным путем. Результат определяется следующим образом:

Если BUILD_PATH_PREFIX_MAP не задана, просто возвращается path.
в противном случае выполняется перезапись с использованием сопоставления (а если подходящих префиксов нет, возвращается path).

См. спецификацию BUILD_PATH_PREFIX_MAP

val rewrite_find_first_existing : string -> string option

rewrite_find_first_existing path использует сопоставление BUILD_PATH_PREFIX_MAP и пытается найти исходный путь, который сопоставляется с существующим в файловой системе путем. Возможны следующие возвращаемые значения:

None означает, что либо
- BUILD_PATH_PREFIX_MAP не задана и path не существует, либо
- в сопоставлении не найдены исходные префиксы path,
Some target означает, что target существует, и выполняется одно из условий:
- BUILD_PATH_PREFIX_MAP не задана и target = path, либо
- target — первый файл (в порядке приоритета), в который сопоставлен path и который существует в файловой системе.
Not_found вызвана — значит, в сопоставлении найдены исходные префиксы, соответствующие path, но ни один из них не существует в файловой системе. Вызывающий код должен перехватить это исключение и вывести соответствующее сообщение об ошибке.

См. спецификацию BUILD_PATH_PREFIX_MAP

val rewrite_find_all_existing_dirs : string -> string list

rewrite_find_all_existing_dirs dir накапливает список существующих каталогов dirs, полученных в результате сопоставления потенциально абстрактного каталога dir со всеми парами сопоставления в переменной окружения BUILD_PATH_PREFIX_MAP, если она задана. Список dirs будет упорядочен по приоритету (первый элемент имеет наивысший приоритет).

Возможны следующие результаты:

[] означает, что либо
- BUILD_PATH_PREFIX_MAP не задана и dir не является существующим каталогом, либо
- если она задана, то для dir не найдено подходящих префиксов.
Some dirs означает, что dirs содержит найденные каталоги. Выполняется одно из условий:
- BUILD_PATH_PREFIX_MAP не задана и dirs = [dir], либо
- она задана, а dirs — это сопоставленные существующие каталоги.
Вызвано Not_found — значит, в сопоставлении найдены исходные префиксы, соответствующие dir, но ни один из результатов сопоставления не является существующим каталогом (возможно, из-за неправильной настройки). Вызывающий код должен перехватить это исключение и вывести соответствующее сообщение об ошибке.

См. спецификацию BUILD_PATH_PREFIX_MAP

val absolute_path : string -> string

absolute_path path сначала формирует абсолютный путь s из path, добавляя текущий рабочий каталог, если path был относительным. Затем s переписывается с использованием rewrite_absolute_path. Наконец, результат нормализуется путем устранения вхождений '.' или '..'.

Вывод расположений

val show_filename : string -> string

В режиме -absname возвращает абсолютный путь для этого имени файла. В противном случае возвращает имя файла без изменений.

val print_filename : Format.formatter -> string -> unit

val print_loc : Format.formatter -> t -> unit

val print_locs : Format.formatter -> t list -> unit

val separate_new_message : Format.formatter -> unit

module Doc: sig .. end

Подсветка расположений для toplevel

val highlight_terminfo : Lexing.lexbuf -> Format.formatter -> t list -> unit

Вывод сообщений об ошибках и предупреждений

Тип отчетов и функции их вывода

type msg = Format_doc.t loc

val msg : ?loc:t ->       ('a, Format_doc.formatter, unit, msg) format4 -> 'a

type report_kind =

`\|`	`Report_error`
`\|`	`Report_warning of string`
`\|`	`Report_warning_as_error of string`
`\|`	`Report_alert of string`
`\|`	`Report_alert_as_error of string`

type report = {

	`kind : report_kind;`
	`main : msg;`
	`sub : msg list;`
	`footnote : Format_doc.t option;`

}

type report_printer = {

	`pp : report_printer -> Format.formatter -> report -> unit;`
	`pp_report_kind : report_printer -> report -> Format.formatter -> report_kind -> unit;`
	`pp_main_loc : report_printer -> report -> Format.formatter -> t -> unit;`
	`pp_main_txt : report_printer -> report -> Format.formatter -> Format_doc.t -> unit;`
	`pp_submsgs : report_printer -> report -> Format.formatter -> msg list -> unit;`
	`pp_submsg : report_printer -> report -> Format.formatter -> msg -> unit;`
	`pp_submsg_loc : report_printer -> report -> Format.formatter -> t -> unit;`
	`pp_submsg_txt : report_printer -> report -> Format.formatter -> Format_doc.t -> unit;`

}

Функция вывода для report, определенная с помощью открытой рекурсии. Ее цель — упростить создание новых функций вывода за счет повторного использования кода существующих функций.

Функции вывода отчетов, используемые компилятором

val batch_mode_printer : report_printer

val terminfo_toplevel_printer : Lexing.lexbuf -> report_printer

val best_toplevel_printer : unit -> report_printer

Определяет возможности терминала и выбирает подходящую функцию вывода

Вывод `report`

val print_report : Format.formatter -> report -> unit

Выводит отчет об ошибке или предупреждении.

val report_printer : (unit -> report_printer) ref

Перехватчик для переопределения функции вывода отчетов.

Перехватчик — это unit -> report_printer, а не просто report_printer: это полезно, поскольку позволяет определить тип вывода (файл, терминал и т. д.) и выбрать соответствующую функцию вывода.

val default_report_printer : unit -> report_printer

Исходная функция вывода отчетов для использования в перехватчиках.

Вывод предупреждений

Преобразование `Warnings.t` в `report`

val report_warning : t -> Warnings.t -> report option

report_warning loc w создает отчет для указанного предупреждения w или возвращает None, если предупреждение не следует выводить.

val warning_reporter : (t -> Warnings.t -> report option) ref

Перехватчик для перехвата предупреждений.

val default_warning_reporter : t -> Warnings.t -> report option

Исходная функция обработки предупреждений для использования в перехватчиках.

Вывод предупреждений

val formatter_for_warnings : Format.formatter ref

val print_warning : t -> Format.formatter -> Warnings.t -> unit

Выводит предупреждение. Это просто композиция report_warning и print_report.

val prerr_warning : t -> Warnings.t -> unit

То же, что и print_warning, но в качестве форматтера вывода используется !formatter_for_warnings.

Вывод оповещений

Преобразование `Alert.t` в `report`

val report_alert : t -> Warnings.alert -> report option

report_alert loc w создает отчет для указанного оповещения w или возвращает None, если оповещение не следует выводить.

val alert_reporter : (t -> Warnings.alert -> report option) ref

Перехватчик для перехвата оповещений.

val default_alert_reporter : t -> Warnings.alert -> report option

Исходная функция обработки оповещений для использования в перехватчиках.

Вывод оповещений

val print_alert : t -> Format.formatter -> Warnings.alert -> unit

Выводит оповещение. Это просто композиция report_alert и print_report.

val prerr_alert : t -> Warnings.alert -> unit

То же, что и print_alert, но в качестве форматтера вывода используется !formatter_for_warnings.

val deprecated : ?def:t -> ?use:t -> t -> string -> unit

Выводит оповещение об устаревании.

val alert : ?def:t ->       ?use:t -> kind:string -> t -> string -> unit

Выводит произвольное оповещение.

val auto_include_alert : string -> unit

Выводит оповещение о том, что -I +lib автоматически добавлен в путь загрузки

val deprecated_script_alert : string -> unit

deprecated_script_alert command выводит оповещение о том, что command foo устарел и заменен на command ./foo

Вывод сообщений об ошибках

type error = report

error — это report, которое report_kind должно быть Report_error.

type delayed_msg = unit -> Format_doc.t option

val error : ?loc:t ->       ?sub:msg list ->       ?footnote:delayed_msg -> string -> error

val errorf : ?loc:t ->       ?sub:msg list ->       ?footnote:delayed_msg ->       ('a, Format_doc.formatter, unit, error) format4 -> 'a

val aligned_error_hint : ?loc:t ->       ?sub:msg list ->       ?footnote:delayed_msg ->       ('a, Format_doc.formatter, unit, Format_doc.t option -> error)       format4 -> 'a

aligned_error_hint ?loc ?sub ?footnote fmt ... aligned_hint создает отчет об ошибке, в котором потенциальное сообщение aligned_hint выровнено по основному сообщению об ошибке перед добавлением в список дополнительных сообщений.

val error_of_printer : ?loc:t ->       ?sub:msg list ->       ?footnote:delayed_msg ->       (Format_doc.formatter -> 'a -> unit) -> 'a -> error

val error_of_printer_file : (Format_doc.formatter -> 'a -> unit) -> 'a -> error

Автоматический вывод сообщений об ошибках для возбужденных исключений

val register_error_of_exn : (exn -> error option) -> unit

Каждый модуль компилятора, определяющий пользовательский тип исключения, которое может отображаться пользователю как ошибка, должен зарегистрировать функцию вывода для этого исключения с помощью register_error_of_exn. Результатом функции вывода является значение error, содержащее расположение, сообщение и, при необходимости, дополнительные сообщения (каждое из них также имеет расположение).

val error_of_exn : exn -> [ `Already_displayed | `Ok of error ] option

exception Error of error

Возбуждение Error e сигнализирует об ошибке e; исключение будет перехвачено, и сообщение об ошибке будет выведено.

exception Already_displayed_error

Возбуждение Already_displayed_error сигнализирует об ошибке, сообщение о которой уже выведено. Исключение будет перехвачено, но ничего выводиться не будет.

val raise_errorf : ?loc:t ->       ?sub:msg list ->       ?footnote:delayed_msg ->       ('a, Format_doc.formatter, unit, 'b) format4 -> 'a

val report_exception : Format.formatter -> exn -> unit

Повторно возбуждает исключение, если оно неизвестно.

Расположение модуля

Сведения о входных данных

Функции для toplevel

Перезапись пути

Вывод расположений

Подсветка расположений для toplevel

Вывод сообщений об ошибках и предупреждений

Тип отчетов и функции их вывода

Функции вывода отчетов, используемые компилятором

Вывод report

Вывод предупреждений

Преобразование Warnings.t в report

Вывод предупреждений

Вывод оповещений

Преобразование Alert.t в report

Вывод оповещений

Вывод сообщений об ошибках

Автоматический вывод сообщений об ошибках для возбужденных исключений

Вывод `report`

Преобразование `Warnings.t` в `report`

Преобразование `Alert.t` в `report`