cmarkit 0.3.0 · OCaml Package

Text locations.

A text location identifies a text span in a given UTF-8 encoded file by an inclusive range of absolute byte positions and the line positions on which those occur.

File paths

type fpath = string

The type for file paths.

val file_none : fpath

file_none is "-". A file path to use when there is none.

Positions

Byte positions

type byte_pos = int

The type for zero-based, absolute, byte positions in text. If the text has n bytes, 0 is the first position and n-1 is the last position.

val byte_pos_none : byte_pos

byte_pos_none is -1. A position to use when there is none.

Lines

type line_num = int

The type for one-based, line numbers in the text. Lines increment after a newline which is either a line feed '\n' (U+000A), a carriage return '\r' (U+000D) or a carriage return and a line feed "\r\n" (<U+000D,U+000A>).

val line_num_none : line_num

line_num_none is -1. A line number to use when there is none.

Line positions

type line_pos = line_num * byte_pos

The type for line positions. This identifies a line by its line number and the absolute byte position following its newline (or the start of text for the first line). That byte position:

Indexes the first byte of text of the line if the line is non-empty.
Indexes the first byte of the next newline if the line is empty.
Is out of bounds and equal to the text's length for a last empty line (this includes when the text is empty).

val line_pos_first : line_pos

line_pos_first is 1, 0. Note that this is the only line position of the empty text.

val line_pos_none : line_pos

line_pos_none is (line_none, pos_none).

Text locations

type t

The type for text locations. A text location identifies a text span in an UTF-8 encoded file by an inclusive range of absolute byte positions and the line positions on which they occur.

If the first byte equals the last byte the range contains exactly that byte. If the first byte is greater than the last byte this represents an insertion point before the first byte. In this case information about the last position should be ignored: it can contain anything.

val none : t

none is a position to use when there is none.

val v : 
  file:fpath ->
  first_byte:byte_pos ->
  last_byte:byte_pos ->
  first_line:line_pos ->
  last_line:line_pos ->
  t

v ~file ~first_byte ~last_byte ~first_line ~last_line is a text location with the given arguments, see corresponding accessors for the semantics. If you don't have a file use file_none.

val file : t -> fpath

file l is l's file.

val first_byte : t -> byte_pos

first_byte l is l's first byte. Irrelevant if is_none is true.

val last_byte : t -> byte_pos

last_byte l is l's last byte. Irrelevant if is_none or is_empty is true.

val first_line : t -> line_pos

first_line l is the line position on which first_byte l lies. Irrelevant if is_none is true.

val last_line : t -> line_pos

last_line l is the line position on which last_byte l lies. Irrelevant if is_none or is_empty is true.

Predicates and comparisons

val is_none : t -> bool

is_none t is true iff first_byte < 0.

val is_empty : t -> bool

is_empty t is true iff first_byte t > last_byte t.

val equal : t -> t -> bool

equal t0 t1 is true iff t0 and t1 are equal. This checks that file, first_byte and last_byte are equal. Line information is ignored.

val compare : t -> t -> int

compare t0 t1 orders t0 and t1. The order is compatible with equal. Comparison starts with file, follows with first_byte and ends, if needed, with last_byte. Line information is ignored.

Shrink and stretch

val set_first : t -> first_byte:byte_pos -> first_line:line_pos -> t

set_first l ~first_byte ~first_line sets the the first position of l to given values.

val set_last : t -> last_byte:byte_pos -> last_line:line_pos -> t

set_last l ~last_byte ~last_line sets the last position of l to given values.

val to_first : t -> t

to_first l has both first and last positions set to l's first position. The range spans first_byte. See also before.

val to_last : t -> t

to_last l has both first and last positions set to l's last position. The range spans last_byte. See also after.

val before : t -> t

before t is the empty text location starting at first_byte.

val after : t -> t

after t is the empty empty location starting at last_byte t + 1; note that at the end of input this may be an invalid byte index. The first_line and last_line of the result is last_line t.

val span : t -> t -> t

span l0 l1 is the span from the smallest byte position of l0 and l1 to the largest byte position of l0 and l1. The file path is taken from the greatest byte position.

val reloc : first:t -> last:t -> t

reloc ~first ~last uses the first position of first, the last position of last and the file of last.

Formatting

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

pp_ocaml formats text locations like the OCaml compiler.

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

pp_gnu formats text locations according to the GNU convention.

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

pp is pp_gnu.

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

pp_dump formats raw data for debugging.

package cmarkit