Input (docs.other.pp_loc.Pp

type t

The abstract input type. Informally, an "input" of type t should support:

seeking the cursor to a given initial position (as a number of bytes)
from this position, read the input byte per byte

High-level functions

val file : string -> t

file fname is an input that corresponds to the content of the file named fname.

val string : string -> t

string s is an input that corresponds to the content of the string s.

val bytes : bytes -> t

bytes b is an input that corresponds to the content of the bytes array b.

val in_channel : in_channel -> t

in_channel cin is an input that correspond to the input channel cin. The channel must correspond to a file: it must be possible to call seek_in on the channel without error.

Creating an input using in_channel instead of file is more efficient if one needs to perform successive calls of Pp_loc.pp on the same input. Otherwise (or if having the best performance is not important), it is simpler (and thus recommended) to use file.

Low-level functions

val raw : 
  seek:(int -> (unit, [ `Invalid_position ]) result) ->
  read_char:(unit -> (char, [ `End_of_input ]) result) ->
  line_offsets:(unit -> int array) ->
  t

Creates an input from functions.

parameter seek
a function to move to a given offset in the input. A call to seek will come before any call to read_char. If the call to seek fails and returns Error `Invalid_position, the input is considered to be unreadable and will be treated equivalenty as the empty input. This might happen even if the input is valid, if one tries to highlight an invalid location.

parameter read_char
used to read the next char from the currently seeked position, and seek one char forward.

parameter line_offsets
computes the byte offset of each line in the file. This is used when positions are built from only an offset, or only a pair (line,column).

val managed : (unit -> t * (unit -> unit)) -> t

managed f enables creating an input which lifetime is managed explicitely. In other words, it handles inputs with explicit open and close operations.

For instance, a file (which needs to be explicitely opened then close) is an instance of managed.

If f() returns (i, c), then using the input managed f will first call f() to access the underlying input i, and will terminate by calling c ().