package forester

  1. Overview
  2. Docs
A tool for tending mathematical forests

Install 

dune-project
 Dependency

sr.ht Readme Edit opam file Versions (17)

Authors

  1. J
    Jonathan Sterling

Maintainers

  1. J
    Jonathan Sterling

Sources

4.0.1.tar.gz
md5=1781b3d67f7ff4edaeb5cfdedba46b9e
sha512=879a583fd3ddf1cf44039fbe9a1d7280e9cc9cc0340506561dc8c6bb6b792db7c512a682d4d09d6c6b0b3b14940665573c9d94580c9ce0a87ee05822fbe4c229

doc/forester.core/Core/Range/index.html

Module Core.RangeSource

include module type of struct include Asai.Range end

Types

Sourcetype string_source = Asai.Range.string_source = {
  1. title : string option;
    (*

    The title of a string source. A diagnostic handler can use the title of a string source in lieu of a file path.

    *)
  2. content : string;
    (*

    The content of a string source

    *)
}

The string source of a position or a range.

  • since 0.2.0
Sourcetype source = [
  1. | `File of string
    (*

    A file source specified by its file path.

    *)
  2. | `String of string_source
    (*

    A string (in-memory) source.

    *)
]

The source of a position or a range. The `String source can be used for representing inputs in REPL.

  • since 0.2.0
Sourcetype position = Asai.Range.position = {
  1. source : source;
    (*

    The source (e.g., the file) that contains the position.

    *)
  2. offset : int;
    (*

    The 0-indexed byte offset of the position relative to the beginning of the source.

    *)
  3. start_of_line : int;
    (*

    The 0-indexed byte offset pointing to the start of the line that contains the position.

    *)
  4. line_num : int;
    (*

    The 1-indexed line number of the line that contains the position.

    *)
}

The type of positions; this is isomorphic to Lexing.position, but with arguably better field names.

The abstract type of ranges.

Sourcetype 'a located = 'a Asai.Range.located = {
  1. loc : t option;
  2. value : 'a;
}

An auxiliary type to package data with an optional range.

Ranges

Sourceval make : (position * position) -> t

make (beginning, ending) builds the range [beginning, ending) (not including the byte at the ending position) from a pair of positions beginning and ending. A range is empty if its beginning and ending positions are the same.

  • raises Invalid_argument

    if the positions do not share the same source or if ending comes before beginning. (It is okay if ending equals to beginning, which means the range is empty.) The comparison of source file paths is done by String.equal without any path normalization.

Sourceval eof : position -> t

eof pos builds a special range referring to the end of the source. The input pos must be pointing at the end position; for example, if the position referring to a string source, pos.offset should be the length of the string.

  • since 0.3.0
Sourceval view : t -> [ `Range of position * position | `End_of_file of position ]

view range returns a view of the range.

  • since 0.3.0
Sourceval split : t -> position * position

split range returning the pair of the beginning and ending positions of range. It is the left-inverse of make.

Sourceval source : t -> source

source range returns the source associated with range.

Sourceval begin_line_num : t -> int

begin_line_num range returns the 1-indexed line number of the beginning position.

Sourceval end_line_num : t -> int

end_line_num range returns the 1-indexed line number of the ending position.

Sourceval begin_offset : t -> int

begin_offset range returns the 0-indexed offset of the (inclusive) beginning position.

Sourceval end_offset : t -> int

end_offset range returns the 0-indexed offset of the (exclusive) ending position.

Sourceval locate_opt : t option -> 'a -> 'a located

locate_opt r v is {loc = r; value = v}.

Sourceval locate : t -> 'a -> 'a located

locate r v is {loc = Some r; value = v}.

Other Helper Functions

Sourceval title : source -> string option

title src gets the title of a string source or the path of a file source, or None if it does not exist.

  • since 0.2.0

Support of Lexing

Sourceval of_lex_position : ?source:source -> Lexing.position -> position

of_lex_position pos converts an OCaml lexer position pos of type Lexing.position into a position. The input pos must be byte-indexed. (Therefore, the OCaml tool ocamllex is compatible, but the OCaml library sedlex is not because it uses Unicode code points.)

  • parameter source

    The source of the new position. The default source is `File pos.pos_fname.

Sourceval of_lex_range : ?source:source -> (Lexing.position * Lexing.position) -> t

of_lex_range (begining, ending) takes a pair of OCaml lexer positions and creates a range. It is make (of_lex_position begining, of_lex_position ending).

  • parameter source

    The source of the new range. The default source is `File begining.pos_fname.

  • raises Invalid_argument

    if the optional argument source is not given and begining.pos_fname and ending.pos_fname differ. The comparison is done by String.equal without any path normalization.

Sourceval of_lexbuf : ?source:source -> Lexing.lexbuf -> t

of_lexbuf lexbuf constructs a range from the current lexeme that lexbuf points to. It is of_lex_range (Lexing.lexeme_start_p lexbuf, Lexing.lexeme_end_p lexbuf).

  • parameter source

    The source of the new range. The default source is `File (Lexing.lexeme_start_p lexbuf).pos_fname.

Sourceval locate_lex : ?source:source -> (Lexing.position * Lexing.position) -> 'a -> 'a located

locate_lex ps v is a helper function to create a value annotated with a range. It is locate (Some (of_lex_range ps)) v and is designed to work with the OCaml parser generator Menhir. You can add the following code to your Menhir grammar to generate annotated data:

%inline
locate(X):
  | e = X
    { Asai.Range.locate_lex $loc e }
  • parameter source

    The source of the range. The default source is `File (Lexing.lexeme_start_p lexbuf).pos_fname.

Debugging

Ugly printer for debugging

Sourceval dump_source : Format.formatter -> source -> unit
Sourceval dump_position : Format.formatter -> position -> unit
Sourceval dump : Format.formatter -> t -> unit
Sourceval pp_located : ('b -> 'a -> 'c) -> 'b -> 'a located -> 'c