package libsail

  1. Overview
  2. Docs
package libsail
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Libsail.Sail_fileSource

This module contains all the logic for working with source files.

File paths

Sourcemodule Path : sig ... end

As per the OCaml stdlib Filename module, paths are represented by strings.

Sourcetype path = Path.t

Handles

Sourcetype handle = private int

Handles are references to opened files that we have read. See open_file.

Sourceval handle_compare : handle -> handle -> int
Sourceval handle_equal : handle -> handle -> bool
Sourcemodule HandleSet : sig ... end
Sourcemodule HandleMap : sig ... end
Sourceval open_file : path -> handle

Open a file and return a handle to it's contents. Note that the file is not actually held open -- we read the contents, then close the handle storing the file information and contents in memory. As such there is no close_file. Repeatedly calling this file on the same string will return the same handle.

Sourceval add_virtual_file : contents:string -> string -> path * handle
Sourceval get_virtual_file : string -> handle option
Sourceval to_path : handle -> path

The path that was passed to open_file, or in the case of add_virtual_file was created at the same time as the handle.

Sourceval contents : handle -> string

The contents of a Sail file as a string, without any pending edits (see the LSP section of this file).

Special handles

Sourceval dummy : handle

This is special handle that resolves to a internal file that is always empty.

Sourceval interactive_repl : handle

This is a special handle that contains inputs to the sail -i REPL.

Sourceval repl_prompt_line : unit -> int
Sourceval add_to_repl_contents : command:string -> int * int
Sourceval argv : handle

This is a special handle that treats the Sail argv array as a file for error reporting, with one member of the argv array per line.

Sourceval sail_argv : unit -> string Array.t

This returns the argv array used by Sail. It combines OCaml's Sys.argv with the value of either SAIL_ENCODED_FLAGS (arguments separated by the ASCII unit separator 0x1f) or SAIL_FLAGS (space separated) using the first only if both are present.

Sourcemodule Position : sig ... end
Sourcetype position = Position.position
Sourceval bol_of_lnum : int -> handle -> int option

Returns the byte-offset for a line number.

Sourceval write_file : contents:string -> handle -> unit

Replace the contents of a file. Note that this only changes the in-memory contents of the file, and does not flush the changes to disk.

Language-server-protocol (LSP) file lifecycle

Sourceval editor_take_file : contents:string -> string -> handle

The LSP takes control of a file by sending us a DidOpenTextDocument message, with the contents of the file as seen by the editor.

Sourceval editor_drop_file : handle -> unit

The LSP can stop editing a file using the DidCloseTextDocument message, in which case we need to manage the file.

Sourcetype editor_position = {
  1. line : int;
  2. character : int;
}

The LSP protocol uses line + character offsets as positions. Both are zero-based, and character is counted in UTF-16 code units (as the LSP protocol specifies), not bytes. The conversion to the byte offsets Sail's lexer uses happens lazily, when edits are applied and in editor_position and lexing_position.

Sourcetype text_edit = {
  1. range : editor_range;
  2. text : string;
}

Note that the empty string represents a delete operation as per LSP.

Sourcetype text_edit_size =
  1. | Single_line of int
  2. | Multiple_lines of {
    1. pre : int;
    2. newlines : int;
    3. post : int;
    }
Sourceval edit_file : handle -> text_edit -> unit

Store a pending text edit to a file. This is used by editor_position and lexing_position to synchonize locations between the last type-checked version of the file, and any changes that have subsequently been made in the editor. Note that it does not change the actual contents of the file.

Sourceval editor_position : position -> editor_position option

Take a Sail AST position, and return the where it will visibly appear in the user's editor. Returns None if the position no longer exists in the editor buffer, for example, the user may have deleted the position.

Sourceval lexing_position : handle -> editor_position -> position option

Take a cursor position in the editor, and map it to a position in the Sail AST. Returns None if the cursor position is within a pending edit that has not yet been processed by Sail.

Sourceval apply_edits : handle -> unit

Bake the queued edits (see edit_file) into the file's contents, bringing them in sync with the editor, and clear the queue. This is where the UTF-16 code-unit offsets carried by edits are resolved to byte offsets.

Sourceval utf16_length : string -> int

The length of a UTF-8 string in UTF-16 code units. LSP character offsets and lengths are counted in UTF-16 code units, so this converts a byte length (or, applied to a substring, a byte offset) into the LSP's units.

Channel interface

Sourcemodule In_channel : sig ... end

This module aims to provide a drop-in replacement for the stdlib in_channel functionality used by Sail, essentially providing an iterator style interface to the file contents.