Module Stk.TextbufferSource

Text buffer sharable by several views.

A textbuffer holds a (Utf-8) string and associated tags in a Rope.t. The buffer also maintains cursors, updating their position when text is modified.

A widget wanting to display the buffer contents must register by providing functions to call when buffer is modified (text or tags).

A history is kept for undoing/redoing actions.

Sourcetype t

A text buffer.

Sourceval create : ?source_language:string -> ?word_char_re:Pcre.regexp -> unit -> t

Create a new text buffer. Options arguments:

  • source_langage: sets a source language by name.
  • word_char_re: regular expression of word characters. Default is default_word_char_re.
Sourceval lines : t -> Rope.range array

lines t returns an array with the range of each line of t.

Sourceval line_count : t -> int

line_count t returns the number of lines in t.

Sourceval size : t -> int

size t returns the number of utf8 characters in t.

Sourceval modified : t -> bool

Get the modified flag of t. This flag is set to true when t is modified. The history keeps track of this flag, so undoing or redoing can change this flag.

Sourceval set_modified : t -> bool -> unit

set_modified t b sets modified flag of t to b. A typical use is to set the flag to false after saving the contents of buffer to a file.

Sourceval set_map_in : t -> (Uchar.t -> Uchar.t) option -> unit

set_map_in t f sets a function (or removes it) used to map inserted contents. When such a function is set, it is applied on strings passed to insertion functions (insert, insert_at_cursor, set_text, ...

Sourceval set_map_out : t -> (Uchar.t -> Uchar.t) option -> unit

set_map_out t f sets a function (or removes it) used to map retrieved contents. When such a function is set, it is applied when retrieving contents from the buffer (to_string, chars, ...).

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

Pretty-print contents of text buffer.

Logging

This module has its own Logs source "stk.textbuffer". See Log.

include Log.LOG
include Logs.LOG

Log functions

val msg : Logs.level -> 'a Logs.log

See Logs.msg.

val app : 'a Logs.log

app is msg App.

val err : 'a Logs.log

err is msg Error.

val warn : 'a Logs.log

warn is msg Warning.

val info : 'a Logs.log

info is msg Info.

val debug : 'a Logs.log

debug is msg Debug.

val kmsg : (unit -> 'b) -> Logs.level -> ('a, 'b) Logs.msgf -> 'b

See Logs.kmsg.

Logging result value Errors

val on_error : ?level:Logs.level -> ?header:string -> ?tags:Logs.Tag.set -> pp:(Format.formatter -> 'b -> unit) -> use:('b -> 'a) -> ('a, 'b) result -> 'a

See Logs.on_error.

val on_error_msg : ?level:Logs.level -> ?header:string -> ?tags:Logs.Tag.set -> use:(unit -> 'a) -> ('a, [ `Msg of string ]) result -> 'a

See Logs.on_error_msg.

val set_level : Logs.level option -> unit

Positions and ranges

All position and offset are 0-based and expressed in UTF8 characters (not bytes).

Sourcetype line_offset = {
  1. line : int;
    (*

    line number

    *)
  2. bol : int;
    (*

    offset of beginning of line

    *)
  3. offset : int;
    (*

    offset from the beginning of line

    *)
}

A line_offset defines a line number and a character position on this line.

Sourceval line_offset : line:int -> bol:int -> offset:int -> line_offset
Sourceval pp_line_offset : Format.formatter -> line_offset -> unit
Sourceval compare_line_offset : line_offset -> line_offset -> int
Sourceval order_line_offsets : line_offset -> line_offset -> line_offset * line_offset

order_line_offsets lo1 lo2 returns (lo1, lo2) if lo1 is before or equal to lo2, else returns (lo2, lo1).

Sourcetype line_range = {
  1. lstart : line_offset;
    (*

    left of first char

    *)
  2. lstop : line_offset;
    (*

    right of last char

    *)
}

Range accross lines, defined by two line_offset positions.

Sourceval line_range : start:line_offset -> stop:line_offset -> line_range

line_range ~start ~stop creates a line_range from start to stop characters.

Sourceval pp_line_range : Format.formatter -> line_range -> unit

Pretty-prints a line range.

Sourceval range_of_line_range : line_range -> Rope.range

range_of_line_range lr converts lr to a Rope.range.

Sourceval line_of_offset : t -> int -> int

line_of_offset t o returns the line number of t corresponding to offset o.

Sourceval line_char_of_offset : t -> int -> int * int

line_char_of_offset t o returns the pair (line, char) corresponding to offset o.

Sourceval offset_of_line_char : t -> line:int -> char:int -> int

offset_of_line_char t ~line ~char returns the absolute offset in t corresponding to line and character char.

Sourceval line_offset_of_offset : t -> int -> line_offset

line_offset_of_offset t o returns a line_offset position from the given absolute offset o.

Sourceval line_range_of_range : t -> Rope.range -> line_range
Sourceval line_ranges_of_ranges : t -> Rope.range list -> line_range list

line_ranges_of_ranges t ranges returns a list of line_range from a list of Rope.range. Returnd ranges are merged when possible.

Cursors

A text buffer can handle several cursors. Some cursors can be associated to a widget. In this case, they will be removed when the widget is unregistered, and changes of these cursors will be signaled only to this widget.

Cursor positions are automatically updated after each change (insertion, deletion) in the buffer.

Sourcetype cursor
Sourcetype cursor_gravity = [
  1. | `Left
  2. | `Right
]

Cursor gravity defines how a cursor moves when text is inserted at its position. `Left gravity means that the cursor stays at the same position, `Right means that the cursor moves to the right of the inserted text, as when user types text.

Sourceval compare_cursor : cursor -> cursor -> int

Cursor comparison.

Sourceval equal_cursor : cursor -> cursor -> bool

Cursor equality.

Sourceval pp_cursor : t -> Format.formatter -> cursor -> unit

Pretty-prints a cursor (with its position).

Sourceval pp_cursor_id : Format.formatter -> cursor -> unit

Pretty-prints a cursor id.

Sourcemodule Cursor_map : Map.S with type key = cursor

A map with cursors as keys. This is useful for views on a text buffer (like Textview.textview widget).

Sourceval create_cursor : ?widget:Stk.Oid.Map.key -> ?gravity:cursor_gravity -> ?line:int -> ?char:int -> ?offset:int -> t -> cursor

create_cursor t creates a new cursor in buffer. Optional arguments are:

  • widget: indicates a widget id. Changes regarding this cursor will be signaled only to this widget.
  • gravity: the gravity of the cursor. Default is `Right.
  • line, char and offset: indicate position of cursor. If offset is given, it is used. Else line and char are used, with default value 0 for each.
Sourceval last_used_cursor : t -> cursor option

Get last used cursor field of textbuffer. This can be useful for editors handling several cursors.

Sourceval set_last_used_cursor : t -> cursor -> unit

Set last used cursor for textbuffer.

Sourceval remove_cursor : t -> cursor -> unit

remove_cursor t c removes cursor c from t. This cursor cannot be used anymore.

Sourceval create_insert_cursor : ?widget:Stk.Oid.Map.key -> t -> cursor

create_insert_cursor t creates a new cursor in t. If last_used_cursor of t is not None and is a valid cursor, then this cursor is duplicated, setting gravity of new cursor to `Right. Else a new cursor is created at offset 0. Optonal argument widget indicates a widget id. Changes regarding this cursor will be signaled only to this widget.

Sourceval dup_cursor : t -> ?widget:Stk.Oid.Map.key -> ?gravity:cursor_gravity -> cursor -> cursor option

dup_cursor t c returns a new cursor, if c is a valid cursor. The new cursor is at the same position than c. The cursor can be associated to widget id, if provided. gravity argument allows to force the gravity of new cursor rather than having the same as c.

Sourceval cursor_offset : t -> cursor -> int

cursor_offset t c returns absolute offset of c, or 0 if cursor is invalid.

Sourceval cursor_line_offset : t -> cursor -> line_offset

cursor_line_offset t c returns position of c as a line_offset.

Moving cursors

All these functions returns the new absolute offset of the cursor, or None if the cursor is invalid.

Sourceval move_cursor : t -> ?line:int -> ?char:int -> ?offset:int -> cursor -> int option

move_cursor t c moves the cursor c according to optional parameters:

  • offset: move cursor to absolute offset.
  • line and char: if offset is not provided, then move cursor to the given line (default is 0) and char (default is 0).
Sourceval move_cursor_to_cursor : t -> src:cursor -> dst:cursor -> int option

move_cursor_to_cursor t ~src ~dst moves cursor src at the same position as dst. Returns the new absolute offset of the cursor, or None if src or dst is invalid.

Sourceval move_cursor_to_line_start : t -> cursor -> int option

Moves cursor to the start of the current line of the cursor.

Sourceval move_cursor_to_line_end : t -> cursor -> int option

Moves cursor to the end of the current line of the cursor.

Sourceval line_forward_cursor : t -> cursor -> int -> int option

line_forward_cursor t c n moves cursor n lines forward. If possible, keep the same char position on line.

Sourceval line_backward_cursor : t -> cursor -> int -> int option

Same as line_forward_cursor but moves backward.

Sourceval forward_cursor : t -> cursor -> int -> int option

forward_cursor t c n moves c n characters forward.

Sourceval backward_cursor : t -> cursor -> int -> int option

backward_cursor t c n moves c n characters backward.

Sourceval forward_cursor_to_word_end : t -> cursor -> int option

forward_cursor_to_word_end t c moves c to the next word end.

Sourceval backward_cursor_to_word_start : t -> cursor -> int option

backward_cursor_to_word_start t c moves c to the previous word start.

Regions

Sourcetype region
Sourceval create_region : ?start_gravity:cursor_gravity -> start:int -> ?stop_gravity:cursor_gravity -> stop:int -> t -> region

create_region ~start ~stop t creates a new region defined by two cursors at the given absolute positions. start_gravity (default is `Left) and stop_gravity (default is `Right) can be used to specify different gravities for cursors.

Sourceval remove_region : t -> region -> unit

Removes the given region from t.

Events

Sourcetype Events.ev +=
  1. | Delete_range : ((line_range * string) -> unit) Events.ev
  2. | Insert_text : ((line_range * string) -> unit) Events.ev
  3. | Cursor_moved : ((cursor * line_offset) -> unit) Events.ev
  4. | Modified_changed : (bool -> unit) Events.ev
  5. | Source_language_changed : (string option -> unit) Events.ev

Textbuffer events:

  • Delete (range, string): A range was deleted which corresponds to string.
  • Insert_text (range, string): A string was inserted, now at range.
  • Cursor_moved (c, line_offset): The given cursor moved to a new position.
  • Modified_changed bool: The modified status changed to the given boolean.
  • Source_language_changed lang: the source language changed to Some name, or None for no language.
Sourceval connect : t -> 'a Events.ev -> 'a -> Events.callback_id

connect t ev cb connects callback cb to be called when event ev is triggered by t.

Sourceval disconnect : t -> Events.callback_id -> unit

disconnect t id disconnect callback with id from t.

Retrieving contents

Sourceval to_string : ?start:int -> ?size:int -> t -> string

to_string t returns contents of t as a string. Optional arguments:

  • start indicates a start position (default is 0).
  • size indicates a size of string to get (default is to get the contents of t until the end, i.e. size t - start.
Sourceval chars : map_out:bool -> ?start:int -> ?size:int -> t -> (Uchar.t * (Stk.Rope.TagSet.t * Stk.Rope.Tag.t option)) list

Same as to_string but returns a list of characters with their associated tags: for each character, a pair (tag set, language tag option). Argument map_out indicates if the characters must be mapped using buffer'a map_out function if present.

Sourceval get_line : t -> int -> Rope.range

get_line t n returns the range of line n in t.

Sourceval line_chars : map_out:bool -> t -> int -> (Uchar.t * (Stk.Rope.TagSet.t * Stk.Rope.Tag.t option)) list

Same as chars but returns chars for the given line.

Sourceval line_to_string : t -> int -> string

line_to_string t n returns line n as a string.

Inserting and deleting

Sourceval insert_at_cursor : t -> cursor -> ?readonly:(Stk.Rope.TagSet.t option -> Stk.Rope.TagSet.t option -> bool) -> ?tags:Texttag.T.t list -> string -> unit

insert_at_cursor t c s inserts the string s at the position of the cursor c. Optional arguments:

  • readonly: a function taking tags of characters before and after the insertion position and returning whether can be inserted here. Can be used to define readonly ranges in a buffer based on tags.
  • tags: tags associated to each inserted character.
Sourceval insert : t -> ?readonly:(Stk.Rope.TagSet.t option -> Stk.Rope.TagSet.t option -> bool) -> ?tags:Texttag.TSet.id list -> int -> string -> unit

insert t offset s is the same as insert_at_cursor but inserts at the given offset.

Sourceval set_text : t -> string -> unit

set_text t s replaces contents of buffer with string s.

Sourceval delete : ?readonly:(Stk.Rope.TagSet.t -> bool) -> ?start:int -> ?size:int -> t -> string

delete t deletes contents from t. Options arguments:

  • readonly: a function taking the tags of a character and returning whether this character can be deleted. Only characters which are not readonly will be deleted.
  • start: start of range to delete. Default is 0.
  • size: size of range to delete. Default is size t - start.

The function returns the deleted text.

Tags

Tags are associated to each character of the underlying rope used by a text buffer. The text buffer does not associate properties to these tags. The theme of the Textview displaying a text buffer associated properties (color, font, ...) to tags.

Sourceval add_tag : t -> Texttag.T.t -> ?start:int -> ?size:int -> unit -> unit

add_tag t tag () adds the given tag to contents of t. Optional arguments:

  • start: indicates the start of range to tag (default is 0).
  • size: indicate the size of range to tag (default is size t - start).
Sourceval remove_tag : t -> Texttag.T.t -> ?start:int -> ?size:int -> unit -> unit

remove_tag t tag () removes the given tag from contents of t. Optional arguments:

  • start: indicates the start of range to tag (default is 0).
  • size: indicate the size of range to tag (default is size t - start).

Source language

A text buffer can be given a source language, using its name. The name if used as key for language lexers registered in Higlo library. Higlo lexeme are mapped to Texttag.Lang tags. These tags are given properties in the Texttag.Theme used in Textview, so that each lexeme can be styled.

Sourceval source_language : t -> string option

Returns the source language of the buffer, if any.

Sourceval set_source_language : t -> string option -> unit

Sets the source language of the buffer, or None for no language.

Word characters

A regular expression is used in buffer to determine what is a Word character. This is used by functions acting on words in the buffer.

Sourceval default_word_char_re : Pcre.regexp

A word is defined by default by this regular PCRE expression: "(*UCP)\\w", with iflags contains `UTF8, as buffer contains UTF8 strings.

Sourceval set_word_char_re : t -> Pcre.regexp -> unit

Sets the word character regular expression of t.

Sourceval set_word_char_re_string : t -> string -> unit

Same as set_word_char_re but regular expression is given as string. It is compiled to a regular expression with the `UTF8 flag.

History

A textbuffer keeps tracks of changes in a history, allowing undo/redo.

Sourceval max_undo_levels : t -> int

Get max undo levels.

Sourceval set_max_undo_levels : t -> int -> unit

set_max_undo_levels t n sets max undo levels of t to n.

Sourceval reset_history : t -> unit

reset_history t clears the list of stored changes in t.

Sourceval begin_action : t -> unit

Begins a action. An action will be considered will be considered as one change (as a list of changes) in the history.

Sourceval end_action : t -> unit

Ends the current action. All the changes of the action are added to the history as a single change.

Sourceval undo : t -> unit

Undo last change.

Sourceval redo : t -> unit

Redo last undone change.

Interfacing with views

Sourcetype change =
  1. | Del of line_range * string
    (*

    Deletion of range, string deleted

    *)
  2. | Ins of line_range * string
    (*

    Insertion of string at range

    *)
  3. | Group of change list
    (*

    list of changes

    *)

A change in the buffer.

Sourceval pp_change : Format.formatter -> change -> unit
Sourceval register_widget : t -> widget:Widget.widget -> on_change:(change -> unit) -> on_cursor_change:(cursor -> prev:line_offset -> now:line_offset -> unit) -> on_tag_change:(line_range list -> unit) -> cursor option

register_widget t ~widget ~on_change ~on_cursor_change ~on_tag_change registers the given widget as view on t. on_change will be called when contents of the textbuffer changes. on_cursor_change will be called when a cursor not associated to a widget or associated to this widget moves. on_tag_change will be called when tags of a part of the contents changed. If the widget is already registered, then returns None, else returns Some c where c is a new cursor created with create_insert_cursor ~widget t.

Sourceval unregister_widget : t -> Widget.widget -> unit

unregister_widget t widget unregisters the given widget from the views of t. Cursor of this widget are removed (and not usable any more).