Textadept 12.5 API Documentation

  1. _G
  2. _L
  3. args
  4. buffer
  5. events
  6. io
  7. keys
  8. lexer
  9. lfs
  10. os
  11. string
  12. textadept
  13. textadept.bookmarks
  14. textadept.editing
  15. textadept.history
  16. textadept.keys
  17. textadept.macros
  18. textadept.menu
  19. textadept.run
  20. textadept.session
  21. textadept.snippets
  22. ui
  23. ui.command_entry
  24. ui.dialogs
  25. ui.find
  26. view

The _G Module

Extends Lua’s _G table to provide extra functions and fields for Textadept.

Fields defined by _G

BSD

Whether or not Textadept is running on BSD.

CURSES

Whether or not Textadept is running in a terminal. Curses feature incompatibilities are listed in the Appendix.

GTK

Whether or not Textadept is running as a GTK GUI application.

LINUX

Whether or not Textadept is running on Linux.

OSX

Whether or not Textadept is running on macOS.

QT

Whether or not Textadept is running as a Qt GUI application.

WIN32

Whether or not Textadept is running on Windows.

_BUFFERS <table>

Table of all open buffers in Textadept. Numeric keys have buffer values and buffer keys have their associated numeric keys.

Usage:

See also:

_CHARSET

The filesystem’s character encoding. This is used when working with files.

_COPYRIGHT

Textadept’s copyright information.

_HOME

The path to Textadept’s home, or installation, directory.

_LEXERPATH

A ‘;’-separated list of directory paths that contain lexers for syntax highlighting.

_RELEASE

The Textadept release version string.

_THEME

Textadept’s current UI mode, either “light” or “dark”. Manually changing this field has no effect.

_USERHOME

The path to the user’s ~/.textadept/ directory, where all preferences and user-data is stored. On Windows machines ~/ is the value of the “USERHOME” environment variable (typically C:\Users\username\ or C:\Documents and Settings\username\). On macOS and Linux/BSD machines ~/ is the value of “$HOME” (typically /Users/username/ and /home/username/, respectively).

_VIEWS <table>

Table of all views in Textadept. Numeric keys have view values and view keys have their associated numeric keys.

Usage:

See also:

arg <table>

Table of command line parameters passed to Textadept.

See also:

buffer <table>

The current buffer in the current view.

keys <table>

Map of key bindings to commands, with language-specific key tables assigned to a lexer name key.

snippets <table>

Map of snippet triggers with their snippet text or functions that return such text, with language-specific snippets tables assigned to a lexer name key.

view <table>

The current view.

Functions defined by _G

assert(v[, message=’assertion failed!’[, …]])

Asserts that value v is not false or nil and returns v, or calls error() with message as the error message, defaulting to “assertion failed!”. If message is a format string, the remaining arguments are passed to string.format() and the resulting string becomes the error message.

Parameters:

assert_type(v, expected_type, narg)

Asserts that value v has type string expected_type and returns v, or calls error() with an error message that implicates function argument number narg. This is intended to be used with API function arguments so users receive more helpful error messages.

Parameters:

Usage:

move_buffer(from, to)

Moves the buffer at index from to index to in the _BUFFERS table, shifting other buffers as necessary. This changes the order buffers are displayed in in the tab bar and buffer browser.

Parameters:

quit([status[, events]])

Attempts to quit Textadept. Emits events.QUIT unless events is false.

Parameters:

reset()

Resets the Lua State by reloading all initialization scripts. This function is useful for modifying user scripts (such as ~/.textadept/init.lua) on the fly without having to restart Textadept. arg is set to nil when reinitializing the Lua State. Any scripts that need to differentiate between startup and reset can test arg.

timeout(interval, f[, …])

Calls function f with the given arguments after interval seconds. If f returns true, calls f repeatedly every interval seconds as long as f returns true. A nil or false return value stops repetition. Note: in the terminal version, timeout functions will not be called until an active Find & Replace pane session finishes, and until an active dialog closes.

Parameters:

The _L Module

Map of all messages used by Textadept to their localized form. If the localized version of a given message does not exist, the non-localized message is returned. Use rawget() to check if a localization exists. Note: the terminal version ignores any “_” or “&” mnemonics the GUI version would use.

The args Module

Processes command line arguments for Textadept.

Functions defined by args

args.register(short, long, narg, f, description)

Registers a command line option with short and long versions short and long, respectively. narg is the number of arguments the option accepts, f is the function called when the option is set, and description is the option’s description when displaying help. Normally, options are not considered command line arguments, so they do not prevent events.ARG_NONE from being emitted. However, if f returns true, this option counts as an argment and it will prevent events.ARG_NONE from being emitted.

Parameters:

The buffer Module

A Textadept buffer or view object. Constants are documented in the fields they apply to. While you can work with individual buffer and view instances, it is really only useful to work with the global one. (In fact, you are strongly discouraged from working with non-global instances.) Many of these functions and fields are derived from buffer- and view-specific functionality of the Scintilla editing component, and additional information can be found on the Scintilla website. Any buffer and view fields set on startup (e.g. in ~/.textadept/init.lua) will be the default, initial values for all buffers.

Note: This buffer and view API is largely interchangeable. That is, view.field and view:function are often equivalent to buffer.field and buffer:function, respectively. While this reference chooses one notation over the other, these choices are not always strict requirements. Still, it is recommended to follow this convention. Functions and fields related to manipulating buffer text and selections should use buffer, while functions and fields related to displaying buffer text and other visuals should use view.

  1. Create Buffers and Views
  2. View Information
  3. Work with Files
  4. Move Within Lines
  5. Move Between Lines
  6. Move Between Pages
  7. Move Between Buffers
  8. Other Movements
  9. Retrieve Text
  10. Set Text
  11. Replace Text
  12. Delete Text
  13. Transform Text
  14. Split and Join Lines
  15. Undo and Redo
  16. Employ the Clipboard
  17. Make Simple Selections
  18. Make Movement Selections
  19. Modal Selection
  20. Make and Modify Multiple Selections
  21. Make Rectangular Selections
  22. Simple Search
  23. Search and Replace
  24. Query Position Information
  25. Query Line and Line Number Information
  26. Query Measurement Information
  27. Configure Line Margins
  28. Mark Lines with Markers
  29. Annotate Lines
  30. Mark Text with Indicators
  31. Display an Autocompletion List
  32. Display Images in Lists
  33. Show a Call Tip
  34. Fold or Hide Lines
  35. Scroll the View
  36. Configure Indentation and Line Endings
  37. Configure Character Settings
  38. Configure the Color Theme
  39. Override Style Settings
  40. Assign Caret, Selection, Whitespace, and Line Colors
  41. Configure Caret Display
  42. Configure Selection Display
  43. Configure Whitespace Display
  44. Configure Scrollbar Display and Scrolling Behavior
  45. Configure Mouse Cursor Display
  46. Configure Wrapped Line Display
  47. Configure Text Zoom
  48. Configure Long Line Display
  49. Configure Fold Settings and Folded Line Display
  50. Highlight Matching Braces
  51. Configure Indentation Guide Display
  52. Configure File Types
  53. Manually Style Text
  54. Query Style Information
  55. Miscellaneous

Create Buffers and Views

buffer:new()

Creates a new buffer, displays it in the current view, and returns it. Emits events.BUFFER_NEW.

Return:

See also:

view:split([vertical=false])

Splits the view into top and bottom views (unless vertical is true), focuses the new view, and returns both the old and new views. If vertical is false, splits the view vertically into left and right views. Emits events.VIEW_NEW.

Parameters:

Return:

view:unsplit()

Unsplits the view if possible, returning true on success.

Return:

View Information

view.buffer <table>

The buffer the view currently contains. (Read-only)

view.size

The split resizer’s pixel position if the view is a split one.

Work with Files

buffer:reload()

Reloads the buffer’s file contents, discarding any changes.

buffer:save()

Saves the buffer to its file, returning true on success. If the buffer does not have a file, the user is prompted for one. Emits events.FILE_BEFORE_SAVE and events.FILE_AFTER_SAVE.

Return:

See also:

buffer:save_as([filename])

Saves the buffer to file filename or the user-specified filename, returning true on success. Emits events.FILE_AFTER_SAVE.

Parameters:

Return:

buffer:close([force=false])

Closes the buffer, prompting the user to continue if there are unsaved changes (unless force is true), and returns true if the buffer was closed.

Parameters:

Return:

See also:

buffer:set_encoding(encoding)

Converts the buffer’s contents to encoding encoding.

Parameters:

Usage:

See also:

buffer.filename

The absolute file path associated with the buffer.

buffer.modify

Whether or not the buffer has unsaved changes. (Read-only)

buffer:set_save_point()

Indicates the buffer has no unsaved changes.

buffer.encoding

The string encoding of the file, or nil for binary files.

Move Within Lines

Movements within buffers scroll the caret into view if it is not already visible.

buffer:char_left()

Moves the caret left one character.

buffer:char_right()

Moves the caret right one character.

buffer:word_part_left()

Moves the caret to the previous part of the current word. Word parts are delimited by underscore characters or changes in capitalization. buffer.word_chars contains the set of characters that constitute words.

buffer:word_part_right()

Moves the caret to the next part of the current word. Word parts are delimited by underscore characters or changes in capitalization. buffer.word_chars contains the set of characters that constitute words.

buffer:word_left_end()

Moves the caret left one word, positioning it at the end of the previous word. buffer.word_chars contains the set of characters that constitute words.

buffer:word_right_end()

Moves the caret right one word, positioning it at the end of the current word. buffer.word_chars contains the set of characters that constitute words.

buffer:word_left()

Moves the caret left one word. buffer.word_chars contains the set of characters that constitute words.

buffer:word_right()

Moves the caret right one word. buffer.word_chars contains the set of characters that constitute words.

buffer:home()

Moves the caret to the beginning of the current line.

buffer:line_end()

Moves the caret to the end of the current line.

buffer:home_display()

Moves the caret to the beginning of the current wrapped line.

buffer:line_end_display()

Moves the caret to the end of the current wrapped line.

buffer:home_wrap()

Moves the caret to the beginning of the current wrapped line or, if already there, to the beginning of the actual line.

buffer:line_end_wrap()

Moves the caret to the end of the current wrapped line or, if already there, to the end of the actual line.

buffer:vc_home()

Moves the caret to the first visible character on the current line or, if already there, to the beginning of the current line.

buffer:vc_home_display()

Moves the caret to the first visible character on the current wrapped line or, if already there, to the beginning of the current wrapped line.

buffer:vc_home_wrap()

Moves the caret to the first visible character on the current wrapped line or, if already there, to the beginning of the actual line.

Move Between Lines

Movements within buffers scroll the caret into view if it is not already visible.

buffer:goto_pos(pos)

Moves the caret to position pos and scrolls it into view.

Parameters:

buffer:goto_line(line)

Moves the caret to the beginning of line number line and scrolls it into view, event if line is hidden.

Parameters:

See also:

buffer:line_up()

Moves the caret up one line.

buffer:line_down()

Moves the caret down one line.

buffer.caret_sticky

The caret’s preferred horizontal position when moving between lines.

buffer:choose_caret_x()

Identifies the current horizontal caret position as the caret’s preferred horizontal position when moving between lines.

buffer:toggle_caret_sticky()

Cycles between buffer.caret_sticky option settings buffer.CARETSTICKY_ON and buffer.CARETSTICKY_OFF.

Move Between Pages

Movements within buffers scroll the caret into view if it is not already visible.

buffer:stuttered_page_up()

Moves the caret to the top of the page or, if already there, up one page.

buffer:stuttered_page_down()

Moves the caret to the bottom of the page or, if already there, down one page.

buffer:page_up()

Moves the caret up one page.

buffer:page_down()

Moves the caret down one page.

Move Between Buffers

Movements between buffers do not scroll the caret into view if it is not visible.

view:goto_buffer(buffer)

Switches to buffer buffer or the buffer buffer number of buffers relative to the current one. Emits events.BUFFER_BEFORE_SWITCH and events.BUFFER_AFTER_SWITCH.

Parameters:

Other Movements

Movements within buffers scroll the caret into view if it is not already visible.

buffer:para_up()

Moves the caret up one paragraph. Paragraphs are surrounded by one or more blank lines.

buffer:para_down()

Moves the caret down one paragraph. Paragraphs are surrounded by one or more blank lines.

buffer:move_caret_inside_view()

Moves the caret into view if it is not already, removing any selections.

buffer:document_start()

Moves the caret to the beginning of the buffer.

buffer:document_end()

Moves the caret to the end of the buffer.

Retrieve Text

buffer:get_text()

Returns the buffer’s text.

buffer:get_sel_text()

Returns the selected text. Multiple selections are included in order, and delimited by buffer.copy_separator. Rectangular selections are included from top to bottom with end of line characters. Virtual space is not included.

Return:

buffer.copy_separator

The delimiters used between multiple selections in buffer:get_sel_text(). The default value is ''.

buffer:text_range(start_pos, end_pos)

Returns the range of text between positions start_pos and end_pos.

Parameters:

buffer:get_line(line)

Returns the text on line number line, including end of line characters.

Parameters:

Return:

buffer:get_cur_line()

Returns the current line’s text and the caret’s position on that line.

Return:

buffer.char_at <table>

List of character bytes per position. (Read-only)

Set Text

buffer:set_text(text)

Replaces the buffer’s text with string text.

Parameters:

buffer:add_text(text)

Adds string text to the buffer at the caret position and moves the caret to the end of the added text without scrolling it into view.

Parameters:

buffer:insert_text(pos, text)

Inserts string text at position pos, removing any selections. If pos is -1, inserts text at the caret position. If the caret is after the pos, it is moved appropriately, but not scrolled into view.

Parameters:

buffer:append_text(text)

Appends string text to the end of the buffer without modifying any existing selections or scrolling the text into view.

Parameters:

buffer:line_duplicate()

Duplicates the current line on a new line below.

buffer:selection_duplicate()

Duplicates the selected text to its right. If multiple lines are selected, duplication starts at the end of the selection. If no text is selected, duplicates the current line on a new line below.

buffer:new_line()

Types a new line at the caret position according to buffer.eol_mode.

Replace Text

Replacing an arbitrary range of text makes use of a target range, a user-defined defined region of text that some buffer functions operate on in order to avoid altering the current selection or scrolling the view.

buffer:replace_sel(text)

Replaces the selected text with string text, scrolling the caret into view.

Parameters:

buffer:set_target_range(start_pos, end_pos)

Defines the target range’s beginning and end positions as start_pos and end_pos, respectively.

Parameters:

buffer:target_from_selection()

Defines the target range’s beginning and end positions as the beginning and end positions of the main selection, respectively.

buffer:replace_target(text)

Replaces the text in the target range with string text sans modifying any selections or scrolling the view. Setting the target and calling this function with an empty string is another way to delete text.

Parameters:

Return:

Delete Text

buffer:clear()

Deletes the selected text or the character at the caret.

buffer:delete_range(pos, length)

Deletes the range of text from position pos to pos + length.

Parameters:

buffer:delete_back()

Deletes the character behind the caret if no text is selected. Otherwise, deletes the selected text.

buffer:delete_back_not_line()

Deletes the character behind the caret unless either the caret is at the beginning of a line or text is selected. If text is selected, deletes it.

buffer:del_word_left()

Deletes the word to the left of the caret, including any leading non-word characters. buffer.word_chars contains the set of characters that constitute words.

buffer:del_word_right()

Deletes the word to the right of the caret, including any trailing non-word characters. buffer.word_chars contains the set of characters that constitute words.

buffer:del_word_right_end()

Deletes the word to the right of the caret, excluding any trailing non-word characters. buffer.word_chars contains the set of characters that constitute words.

buffer:del_line_left()

Deletes the range of text from the caret to the beginning of the current line.

buffer:del_line_right()

Deletes the range of text from the caret to the end of the current line.

buffer:line_delete()

Deletes the current line.

buffer:clear_all()

Deletes the buffer’s text.

Transform Text

buffer:tab()

Indents the text on the selected lines or types a Tab character (“\t”) at the caret position.

buffer:line_indent()

Indents the text on the current or selected lines.

buffer:back_tab()

Un-indents the text on the selected lines.

buffer:line_dedent()

Un-indents the text on the current or selected lines.

buffer:line_transpose()

Swaps the current line with the previous one.

buffer:line_reverse()

Reverses the order of the selected lines.

buffer:upper_case()

Converts the selected text to upper case letters.

buffer:lower_case()

Converts the selected text to lower case letters.

buffer:move_selected_lines_up()

Shifts the selected lines up one line.

buffer:move_selected_lines_down()

Shifts the selected lines down one line.

Split and Join Lines

Splitting and joining lines uses a target range (a user-defined defined region of text that some buffer functions operate on).

buffer:lines_split(width)

Splits the lines in the target range into lines width pixels wide. If width is 0, splits the lines in the target range into lines as wide as the view.

Parameters:

See also:

buffer:lines_join()

Joins the lines in the target range, inserting spaces between the words joined at line boundaries.

See also:

Undo and Redo

buffer:can_undo()

Returns whether or not there is an action to be undone.

Return:

buffer:can_redo()

Returns whether or not there is an action to be redone.

Return:

buffer:undo()

Undoes the most recent action.

buffer:redo()

Redoes the next undone action.

buffer:begin_undo_action()

Starts a sequence of actions to be undone or redone as a single action. May be nested.

buffer:end_undo_action()

Ends a sequence of actions to be undone or redone as a single action.

buffer:empty_undo_buffer()

Deletes the undo and redo history.

Employ the Clipboard

buffer:cut()

Cuts the selected text to the clipboard. Multiple selections are copied in order with no delimiters. Rectangular selections are copied from top to bottom with end of line characters. Virtual space is not copied.

buffer:copy()

Copies the selected text to the clipboard. Multiple selections are copied in order with no delimiters. Rectangular selections are copied from top to bottom with end of line characters. Virtual space is not copied.

buffer:line_cut()

Cuts the current line to the clipboard.

buffer:line_copy()

Copies the current line to the clipboard.

buffer:copy_range(start_pos, end_pos)

Copies to the clipboard the range of text between positions start_pos and end_pos.

Parameters:

buffer:copy_text(text)

Copies string text to the clipboard.

Parameters:

buffer:paste()

Pastes the clipboard’s contents into the buffer, replacing any selected text according to buffer.multi_paste.

See also:

buffer.multi_paste

The multiple selection paste mode.

Make Simple Selections

buffer:set_sel(start_pos, end_pos)

Selects the range of text between positions start_pos and end_pos, scrolling the selected text into view.

Parameters:

buffer.selection_start

The position of the beginning of the selected text. When set, becomes the anchor, but is not scrolled into view.

buffer.selection_end

The position of the end of the selected text. When set, becomes the current position, but is not scrolled into view.

buffer:swap_main_anchor_caret()

Swaps the main selection’s beginning and end positions.

buffer:select_all()

Selects all of the buffer’s text without scrolling the view.

buffer:set_empty_selection(pos)

Moves the caret to position pos without scrolling the view and removes any selections.

Parameters:

buffer.selection_empty

Whether or not no text is selected. (Read-only)

buffer.selection_is_rectangle

Whether or not the selection is a rectangular selection. (Read-only)

buffer:is_range_word(start_pos, end_pos)

Returns whether or not the the positions start_pos and end_pos are at word boundaries.

Parameters:

Make Movement Selections

buffer:char_left_extend()

Moves the caret left one character, extending the selected text to the new position.

buffer:char_right_extend()

Moves the caret right one character, extending the selected text to the new position.

buffer:word_part_left_extend()

Moves the caret to the previous part of the current word, extending the selected text to the new position. Word parts are delimited by underscore characters or changes in capitalization. buffer.word_chars contains the set of characters that constitute words.

buffer:word_part_right_extend()

Moves the caret to the next part of the current word, extending the selected text to the new position. Word parts are delimited by underscore characters or changes in capitalization. buffer.word_chars contains the set of characters that constitute words.

buffer:word_left_extend()

Moves the caret left one word, extending the selected text to the new position. buffer.word_chars contains the set of characters that constitute words.

buffer:word_right_extend()

Moves the caret right one word, extending the selected text to the new position. buffer.word_chars contains the set of characters that constitute words.

buffer:word_left_end_extend()

Like buffer:word_left_end(), but extends the selected text to the new position.

buffer:word_right_end_extend()

Like buffer:word_right_end(), but extends the selected text to the new position.

buffer:home_extend()

Moves the caret to the beginning of the current line, extending the selected text to the new position.

buffer:line_end_extend()

Moves the caret to the end of the current line, extending the selected text to the new position.

buffer:home_display_extend()

Moves the caret to the beginning of the current wrapped line, extending the selected text to the new position.

buffer:line_end_display_extend()

Moves the caret to the end of the current wrapped line, extending the selected text to the new position.

buffer:home_wrap_extend()

Like buffer:home_wrap(), but extends the selected text to the new position.

buffer:line_end_wrap_extend()

Like buffer:line_end_wrap(), but extends the selected text to the new position.

buffer:vc_home_extend()

Like buffer:vc_home(), but extends the selected text to the new position.

buffer:vc_home_display_extend()

Like buffer:vc_home_display(), but extends the selected text to the new position.

buffer:vc_home_wrap_extend()

Like buffer:vc_home_wrap(), but extends the selected text to the new position.

buffer:line_up_extend()

Moves the caret up one line, extending the selected text to the new position.

buffer:line_down_extend()

Moves the caret down one line, extending the selected text to the new position.

buffer:para_up_extend()

Moves the caret up one paragraph, extending the selected text to the new position. Paragraphs are surrounded by one or more blank lines.

buffer:para_down_extend()

Moves the caret down one paragraph, extending the selected text to the new position. Paragraphs are surrounded by one or more blank lines.

buffer:stuttered_page_up_extend()

Like buffer:stuttered_page_up(), but extends the selected text to the new position.

buffer:stuttered_page_down_extend()

Like buffer:stuttered_page_down(), but extends the selected text to the new position.

buffer:page_up_extend()

Moves the caret up one page, extending the selected text to the new position.

buffer:page_down_extend()

Moves the caret down one page, extending the selected text to the new position.

buffer:document_start_extend()

Moves the caret to the beginning of the buffer, extending the selected text to the new position.

buffer:document_end_extend()

Moves the caret to the end of the buffer, extending the selected text to the new position.

buffer.move_extends_selection

Whether or not regular caret movement alters the selected text. Setting buffer.selection_mode also alters this property.

buffer.selection_mode

The selection mode.

buffer:change_selection_mode(mode)

Changes the selection mode without subsequent caret movement altering selected text (i.e. setting buffer.move_extends_selection).

Parameters:

Make and Modify Multiple Selections

Note: the buffer.selection_n_* fields cannot be used to create selections.

buffer:set_selection(end_pos, start_pos)

Selects the range of text between positions start_pos to end_pos, removing all other selections.

Parameters:

buffer:add_selection(end_pos, start_pos)

Selects the range of text between positions start_pos to end_pos as the main selection, retaining all other selections as additional selections. Since an empty selection (i.e. the current position) still counts as a selection, use buffer:set_selection() first when setting a list of selections.

Parameters:

buffer:multiple_select_add_next()

Adds to the set of selections the next occurrence of the main selection within the target range, makes that occurrence the new main selection, and scrolls it into view. If there is no selected text, the current word is used.

See also:

buffer:multiple_select_add_each()

Adds to the set of selections each occurrence of the main selection within the target range. If there is no selected text, the current word is used.

See also:

buffer.main_selection

The number of the main or most recent selection. Only an existing selection can be made main.

buffer:rotate_selection()

Designates the next additional selection to be the main selection.

buffer:drop_selection_n(n)

Drops existing selection number n.

Parameters:

buffer.selection_n_anchor <table>

List of positions at the beginning of existing selections numbered from 1, the main selection.

buffer.selection_n_caret <table>

List of positions at the end of existing selections numbered from 1, the main selection.

buffer.selection_n_start <table>

List of positions at the beginning of existing selections numbered from 1, the main selection.

buffer.selection_n_end <table>

List of positions at the end of existing selections numbered from 1, the main selection.

buffer.selection_n_anchor_virtual_space <table>

List of positions at the beginning of virtual space selected in existing selections numbered from 1, the main selection.

buffer.selection_n_caret_virtual_space <table>

List of positions at the end of virtual space selected in existing selections numbered from 1, the main selection.

buffer.selection_n_start_virtual_space <table>

List of positions at the beginning of virtual space selected in existing selections numbered from 1, the main selection. (Read-only)

buffer.selection_n_end_virtual_space <table>

List of positions at the end of virtual space selected in existing selections numbered from 1, the main selection. (Read-only)

buffer.selections

The number of active selections. There is always at least one selection. (Read-only)

buffer.multiple_selection

Enable multiple selection. The default value is true.

buffer.additional_selection_typing

Type into multiple selections. The default value is true.

Make Rectangular Selections

buffer.rectangular_selection_anchor

The rectangular selection’s anchor position.

buffer.rectangular_selection_caret

The rectangular selection’s caret position.

buffer.rectangular_selection_anchor_virtual_space

The amount of virtual space for the rectangular selection’s anchor.

buffer.rectangular_selection_caret_virtual_space

The amount of virtual space for the rectangular selection’s caret.

buffer:char_left_rect_extend()

Moves the caret left one character, extending the rectangular selection to the new position.

buffer:char_right_rect_extend()

Moves the caret right one character, extending the rectangular selection to the new position.

buffer:home_rect_extend()

Moves the caret to the beginning of the current line, extending the rectangular selection to the new position.

buffer:line_end_rect_extend()

Moves the caret to the end of the current line, extending the rectangular selection to the new position.

buffer:vc_home_rect_extend()

Like buffer:vc_home(), but extends the rectangular selection to the new position.

buffer:line_up_rect_extend()

Moves the caret up one line, extending the rectangular selection to the new position.

buffer:line_down_rect_extend()

Moves the caret down one line, extending the rectangular selection to the new position.

buffer:page_up_rect_extend()

Moves the caret up one page, extending the rectangular selection to the new position.

buffer:page_down_rect_extend()

Moves the caret down one page, extending the rectangular selection to the new position.

view.rectangular_selection_modifier

The modifier key used in combination with a mouse drag in order to create a rectangular selection.

The default value is view.MOD_ALT.

view.mouse_selection_rectangular_switch

Whether or not pressing view.rectangular_selection_modifier when selecting text normally with the mouse turns on rectangular selection. The default value is true.

buffer:replace_rectangular(text)

Replaces the rectangular selection with string text.

Parameters:

buffer:search_anchor()

Anchors the position that buffer:search_next() and buffer:search_prev() start at to the beginning of the current selection or caret position.

buffer:search_next(flags, text)

Searches for and selects the first occurrence of string text starting at the search anchor using search flags flags, returning that occurrence’s position or -1 if text was not found. Selected text is not scrolled into view.

Parameters:

Return:

See also:

buffer:search_prev(flags, text)

Searches for and selects the last occurrence of string text before the search anchor using search flags flags, returning that occurrence’s position or -1 if text was not found.

Parameters:

Return:

See also:

Search and Replace

The more complex search and replace API uses a target range (a user-defined region of text that some buffer functions operate on, or a region of text that some buffer functions define as output).

buffer.search_flags

The bit-mask of search flags used by buffer:search_in_target().

buffer:target_whole_document()

Defines the target range’s beginning and end positions as the beginning and end positions of the document, respectively.

See also:

buffer:search_in_target(text)

Searches for the first occurrence of string text in the target range bounded by buffer.target_start and buffer.target_end using search flags buffer.search_flags and, if found, sets the new target range to that occurrence, returning its position or -1 if text was not found.

Parameters:

Return:

buffer:replace_target_re(text)

Replaces the text in the target range with string text but first replaces any “\d” sequences with the text of capture number d from the regular expression (or the entire match for d = 0), and then returns the replacement text’s length.

Parameters:

Return:

See also:

buffer.target_text

The text in the target range. (Read-only)

buffer.target_start

The position of the beginning of the target range. This is also set by a successful buffer:search_in_target().

buffer.target_end

The position of the end of the target range. This is also set by a successful buffer:search_in_target().

buffer.target_start_virtual_space

The position of the beginning of virtual space in the target range. This is set to 1 when buffer.target_start or buffer.target_end is set, or when buffer:set_target_range() is called.

buffer.target_end_virtual_space

The position of the end of virtual space in the target range. This is set to 1 when buffer.target_start or buffer.target_end is set, or when buffer:set_target_range() is called.

buffer.tag

List of capture text for capture numbers from a regular expression search. (Read-only)

Query Position Information

buffer.anchor

The anchor’s position.

buffer.current_pos

The caret’s position. When set, does not scroll the caret into view.

buffer:position_before(pos)

Returns the position of the character before position pos (taking multi-byte characters into account), or 1 if there is no character before pos.

Parameters:

Return:

buffer:position_after(pos)

Returns the position of the character after position pos (taking multi-byte characters into account), or buffer.length + 1 if there is no character after pos.

Parameters:

buffer:position_relative(pos, n)

Returns the position n characters before or after position pos (taking multi-byte characters into account). Returns 1 if the position is less than 1 or greater than buffer.length + 1.

Parameters:

Return:

buffer:word_start_position(pos, only_word_chars)

Returns the position of the beginning of the word at position pos. buffer.word_chars contains the set of characters that constitute words. If pos has a non-word character to its left and only_word_chars is false, returns the last word character’s position.

Parameters:

buffer:word_end_position(pos, only_word_chars)

Returns the position of the end of the word at position pos. buffer.word_chars contains the set of characters that constitute words. If pos has a non-word character to its right and only_word_chars is false, returns the first word character’s position.

Parameters:

buffer:position_from_line(line)

Returns the position at the beginning of line number line. Returns -1 if line is greater than buffer.line_count + 1.

Parameters:

Return:

buffer.line_indent_position <table>

List of positions at the ends of indentation per line number. (Read-only)

buffer.line_end_position <table>

List of positions at the ends of lines, but before any end of line characters, per line number. (Read-only)

buffer:find_column(line, column)

Returns the position of column number column on line number line (taking tab and multi-byte characters into account), or the position at the end of line line.

Parameters:

buffer:brace_match(pos, max_re_style)

Returns the position of the matching brace for the brace character at position pos, taking nested braces into account, or -1. The brace characters recognized are ‘(‘, ‘)’, ‘[’, ‘]’, ‘{‘, ‘}’, ‘<’, and ‘>’ and must have the same style.

Parameters:

Return:

Query Line and Line Number Information

buffer.line_count

The number of lines in the buffer. (Read-only) There is always at least one.

view.lines_on_screen

The number of completely visible lines in the view. (Read-only) It is possible to have a partial line visible at the bottom of the view.

view.first_visible_line

The line number of the line at the top of the view.

buffer:line_from_position(pos)

Returns the line number of the line that contains position pos. Returns 1 if pos is less than 1 or buffer.line_count if pos is greater than buffer.length + 1.

Parameters:

Return:

buffer.line_indentation <table>

List of column indentation amounts per line number.

buffer:line_length(line)

Returns the number of bytes on line number line, including end of line characters. To get line length excluding end of line characters, use `buffer.line_end_position[line]

Parameters:

Return:

view:wrap_count(line)

Returns the number of wrapped lines needed to fully display line number line.

Parameters:

Return:

view:visible_from_doc_line(line)

Returns the displayed line number of actual line number line, taking wrapped, annotated, and hidden lines into account, or -1 if line is outside the range of lines in the buffer. Lines can occupy more than one display line if they wrap.

Parameters:

Return:

view:doc_line_from_visible(display_line)

Returns the actual line number of displayed line number display_line, taking wrapped, annotated, and hidden lines into account. If display_line is less than or equal to 1, returns 1. If display_line is greater than the number of displayed lines, returns buffer.line_count.

Parameters:

Return:

Query Measurement Information

buffer.length

The number of bytes in the buffer. (Read-only)

buffer.text_length

The number of bytes in the buffer. (Read-only)

buffer.column <table>

List of column numbers (taking tab widths into account) per position. (Read-only) Multi-byte characters count as single characters.

buffer:count_characters(start_pos, end_pos)

Returns the number of whole characters (taking multi-byte characters into account) between positions start_pos and end_pos.

Parameters:

Return:

view:text_width(style_num, text)

Returns the pixel width string text would have when styled with style number style_num, in the range of 1 to 256.

Parameters:

Return:

view:text_height(line)

Returns the pixel height of line number line.

Parameters:

Return:

Configure Line Margins

The number of line margins is configurable, with each one displaying either line numbers, marker symbols, or text.

view.margins

The number of margins. The default value is 5.

view.margin_type_n <table>

List of margin types for margin numbers from 1 to view.margins (5 by default).

The default value for the first margin is view.MARGIN_NUMBER, followed by view.MARGIN_SYMBOL for the rest.

view.margin_width_n <table>

List of pixel margin widths for margin numbers from 1 to view.margins (5 by default).

view.margin_mask_n <table>

List of bit-masks of markers whose symbols marker symbol margins can display for margin numbers from 1 to view.margins (5 by default). Bit-masks are 32-bit values whose bits correspond to the 32 available markers. The default values are 0, ~view.MASK_FOLDERS, view.MASK_FOLDERS, 0, and 0, for a line margin and logical marker margin.

view.margin_sensitive_n <table>

List of flags that indicate whether or not mouse clicks in margins emit MARGIN_CLICK events for margin numbers from 1 to view.margins (5 by default). The default values are false for the first margin and true for the others.

view.margin_cursor_n <table>

List of cursor types shown over margin numbers from 1 to view.margins (5 by default).

The default values are view.CURSORARROW.

buffer.margin_text <table>

List of text displayed in text margins per line number.

buffer.margin_style <table>

List of style numbers in the text margin per line number. Only some style attributes are active in text margins: font, size, bold, italics, fore, and back.

buffer:margin_text_clear_all()

Clears all text in text margins.

view.margin_options

A bit-mask of margin option settings.

The default value is view.MARGINOPTION_NONE.

view.margin_back_n <table>

List of background colors, in “0xBBGGRR” format, of margin numbers from 1 to view.margins (5 by default). Only affects margins of type view.MARGIN_COLOR.

view:set_fold_margin_color(use_setting, color)

Overrides the fold margin’s default color with color color, in “0xBBGGRR” format, if use_setting is true.

Parameters:

view:set_fold_margin_hi_color(use_setting, color)

Overrides the fold margin’s default highlight color with color color, in “0xBBGGRR” format, if use_setting is true.

Parameters:

view.margin_left

The pixel size of the left margin of the buffer text. The default value is 1.

view.margin_right

The pixel size of the right margin of the buffer text. The default value is 1.

Mark Lines with Markers

Each marker has an assigned symbol that is displayed in properly configured margins. For lines with multiple markers, markers are drawn over one another in ascending order. Markers move in sync with the lines they were added to as text is inserted and deleted. When a line that has a marker on it is deleted, that marker moves to the previous line.

view.new_marker_number()

Returns a unique marker number for use with view:marker_define(). Use this function for custom markers in order to prevent clashes with identifiers of other custom markers.

view:marker_define(marker, symbol)

Assigns marker symbol symbol to marker number marker, in the range of 1 to 32. symbol is shown in marker symbol margins next to lines marked with marker.

Parameters:

view:marker_define_pixmap(marker, pixmap)

Associates marker number marker, in the range of 1 to 32, with XPM image pixmap. The view.MARK_PIXMAP marker symbol must be assigned to marker. pixmap is shown in marker symbol margins next to lines marked with marker.

Parameters:

view:marker_define_rgba_image(marker, pixels)

Associates marker number marker, in the range of 1 to 32, with RGBA image pixels. The dimensions for pixels (view.rgba_image_width and view.rgba_image_height) must have already been defined. pixels is a sequence of 4 byte pixel values (red, blue, green, and alpha) defining the image line by line starting at the top-left pixel. The view.MARK_RGBAIMAGE marker symbol must be assigned to marker. pixels is shown in symbol margins next to lines marked with marker.

Parameters:

See also:

buffer:marker_add(line, marker)

Adds marker number marker, in the range of 1 to 32, to line number line, returning the added marker’s handle which can be used in buffer:marker_delete_handle() and buffer:marker_line_from_handle(), or -1 if line is invalid.

Parameters:

Return:

buffer:marker_add_set(line, marker_mask)

Adds the markers specified in marker bit-mask marker_mask to line number line. The first bit is set to add marker number 1, the second bit for marker number 2, and so on up to marker number 32.

Parameters:

buffer:marker_delete_handle(handle)

Deletes the marker with handle handle returned by buffer:marker_add().

Parameters:

buffer:marker_delete(line, marker)

Deletes marker number marker, in the range of 1 to 32, from line number line. If marker is -1, deletes all markers from line.

Parameters:

buffer:marker_delete_all(marker)

Deletes marker number marker, in the range of 1 to 32, from any line that has it. If marker is -1, deletes all markers from all lines.

Parameters:

buffer:marker_line_from_handle(handle)

Returns the line number of the line that contains the marker with handle handle (returned buffer:marker_add()), or -1 if the line was not found.

Parameters:

Return:

buffer:marker_next(line, marker_mask)

Returns the first line number, starting at line number line, that contains all of the markers represented by marker bit-mask marker_mask. Returns -1 if no line was found. The first bit is set if marker 1 is set, the second bit for marker 2, etc., up to marker 32.

Parameters:

Return:

buffer:marker_previous(line, marker_mask)

Returns the last line number, before or on line number line, that contains all of the markers represented by marker bit-mask marker_mask. Returns -1 if no line was found. The first bit is set if marker 1 is set, the second bit for marker 2, etc., up to marker 32.

Parameters:

Return:

buffer:marker_handle_from_line(line, n)

Returns the handle of the nth marker on line number line, or -1 if no such marker exists.

Parameters:

buffer:marker_get(line)

Returns a bit-mask that represents the markers on line number line. The first bit is set if marker number 1 is present, the second bit for marker number 2, and so on.

Parameters:

Return:

buffer:marker_number_from_line(line, n)

Returns the number of the nth marker on line number line, or -1 if no such marker exists.

Parameters:

view:marker_symbol_defined(marker)

Returns the symbol assigned to marker number marker, in the range of 1 to 32, used in view:marker_define(), view:marker_define_pixmap(), or view:marker_define_rgba_image().

Parameters:

Return:

view.marker_fore <table>

List of foreground colors, in “0xBBGGRR” format, of marker numbers from 1 to 32. (Write-only)

view.marker_fore_translucent <table>

List of foreground colors, in “0xAABBGGRR” format, of marker numbers from 1 to 32. (Write-only)

view.marker_back <table>

List of background colors, in “0xBBGGRR” format, of marker numbers from 1 to 32. (Write-only)

view.marker_back_translucent <table>

List of background colors, in “0xAABBGGRR” format, of marker numbers from 1 to 32.

view.marker_alpha <table>

List of alpha values, ranging from 0 (transparent) to 255 (opaque), of markers drawn in the text area (not the margin) for markers numbers from 1 to 32. (Write-only) The default values are view.ALPHA_NOALPHA, for no alpha.

view:marker_enable_highlight(enabled)

Highlights the margin fold markers for the current fold block if enabled is true.

Parameters:

view.marker_back_selected <table>

List of background colors, in “0xBBGGRR” format, of markers whose folding blocks are selected for marker numbers from 1 to 32. (Write-only)

view.marker_back_selected_translucent <table>

List of background colors, in “0xAABBGGRR” format, of markers whose folding blocks are selected for marker numbers from 1 to 32. (Write-only)

view.marker_layer <table>

Table of layer modes for drawing markers in the text area (not the margin) for marker numbers from 1 to 32.

The default values are view.LAYER_BASE.

view.marker_stroke_width <table>

List of stroke widths in hundredths of a pixel for marker numbers from 1 to 32. (Write-only) The default values are 100, or 1 pixel.

Annotate Lines

Lines may be annotated with styled, read-only text displayed underneath them or next to them (after the end of line characters, or EOL). This may be useful for displaying compiler errors, runtimeerrors, variable values, or other useful information.

buffer.annotation_text <table>

List of annotation text per line number.

buffer.eol_annotation_text <table>

List of EOL annotation text per line number.

buffer.annotation_style <table>

List of style numbers for annotation text per line number. Only some style attributes are active in annotations: font, size/size_fractional, bold/weight, italics, fore, back, and character_set.

buffer.eol_annotation_style <table>

List of style numbers for EOL annotation text per line number. Only some style attributes are active in annotations: font, size/size_fractional, bold/weight, italics, fore, back, and character_set.

buffer:annotation_clear_all()

Clears annotations from all lines.

buffer:eol_annotation_clear_all()

Clears EOL annotations from all lines.

view.annotation_visible

The annotation visibility mode.

The default value is view.ANNOTATION_BOXED.

view.eol_annotation_visible

The EOL annotation visibility mode.

All annotations are drawn with the same shape. The default value is view.EOLANNOTATION_BOXED.

buffer.annotation_lines <table>

List of the number of annotation text lines per line number. (Read-only)

Mark Text with Indicators

Indicators have an assigned indicator style and are displayed along with any existing styles text may already have. They can be hovered over and clicked on. Indicators move along with text.

view.new_indic_number()

Returns a unique indicator number for use with custom indicators. Use this function for custom indicators in order to prevent clashes with identifiers of other custom indicators.

view.indic_style <table>

List of styles for indicator numbers from 1 to 32.

Use view.new_indic_number() for custom indicators. Changing an indicator’s style resets that indicator’s hover style.

view.indic_under <table>

List of flags that indicate whether or not to draw indicators behind text instead of over the top of it for indicator numbers from 1 to 32. The default values are false.

view.indic_hover_style <table>

List of hover styles for indicators numbers from 1 to 32. An indicator’s hover style drawn when either the cursor hovers over that indicator or the caret is within that indicator. The default values are the respective indicator styles.

buffer.indicator_current

The indicator number in the range of 1 to 32 used by buffer:indicator_fill_range() and buffer:indicator_clear_range().

buffer:indicator_fill_range(pos, length)

Fills the range of text from position pos to pos + length with indicator number buffer.indicator_current.

Parameters:

buffer:indicator_clear_range(pos, length)

Clears indicator number buffer.indicator_current over the range of text from position pos to pos + length.

Parameters:

buffer:indicator_start(indicator, pos)

Returns the previous boundary position, starting from position pos, of indicator number indicator, in the range of 1 to 32. Returns 1 if indicator was not found.

Parameters:

buffer:indicator_end(indicator, pos)

Returns the next boundary position, starting from position pos, of indicator number indicator, in the range of 1 to 32. Returns 1 if indicator was not found.

Parameters:

buffer:indicator_all_on_for(pos)

Returns a bit-mask that represents which indicators are on at position pos. The first bit is set if indicator 1 is on, the second bit for indicator 2, etc.

Parameters:

Return:

view.indic_fore <table>

List of foreground colors, in “0xBBGGRR” format, for indicator numbers from 1 to 32. Changing an indicator’s foreground color resets that indicator’s hover foreground color.

view.indic_alpha <table>

List of fill color alpha values, ranging from 0 (transparent) to 255 (opaque), for indicator numbers from 1 to 32 whose styles are either view.INDIC_ROUNDBOX, view.INDIC_STRAIGHTBOX, or view.INDIC_DOTBOX. The default values are view.ALPHA_NOALPHA, for no alpha.

view.indic_outline_alpha <table>

List of outline color alpha values, ranging from 0 (transparent) to 255 (opaque), for indicator numbers from 1 to 32 whose styles are either view.INDIC_ROUNDBOX, view.INDIC_STRAIGHTBOX, or view.INDIC_DOTBOX. The default values are view.ALPHA_NOALPHA, for no alpha.

view.indic_hover_fore <table>

List of hover foreground colors, in “0xBBGGRR” format, for indicator numbers from 1 to 32. The default values are the respective indicator foreground colors.

view.indic_stroke_width <table>

List of stroke widths in hundredths of a pixel for indicator numbers from 1 to 32 whose styles are either view.INDIC_PLAIN, view.INDIC_SQUIGGLE, view.INDIC_TT, view.INDIC_DIAGONAL, view.INDIC_STRIKE, view.INDIC_BOX, view.INDIC_ROUNDBOX, view.INDIC_STRAIGHTBOX, view.INDIC_FULLBOX, view.INDIC_DASH, view.INDIC_DOTS, or view.INDIC_SQUIGGLELOW. The default values are 100, or 1 pixel.

Display an Autocompletion List

There are two types of lists: autocompletion lists and user lists. An autocompletion list is a list of completions shown for the current word. A user list is a more general list of options presented to the user. Both list types update as the user types, have similar behavior options, and may display images alongside text. Autocompletion lists should define a separator character and order before showing the list. User lists should define a separator character, order, and identifier number before showing the list. When a list item is selected, an autocompletion list inserts it while a user list emits an event

buffer.auto_c_separator

The byte value of the character that separates autocompletion and user list list items. The default value is 32 (‘ ‘).

buffer.auto_c_order

The order setting for autocompletion and user lists.

buffer:auto_c_show(len_entered, items)

Displays an autocompletion list constructed from string items (whose items are delimited by buffer.auto_c_separator characters) using len_entered number of characters behind the caret as the prefix of the word to be autocompleted. The sorted order of items (buffer.auto_c_order) must have already been defined.

Parameters:

See also:

view.new_user_list_type()

Returns a unique user list identier number for use with buffer:user_list_show(). Use this function for custom user lists in order to prevent clashes with list identifiers of other custom user lists.

buffer:user_list_show(id, items)

Displays a user list identified by list identifier number id and constructed from string items (whose items are delimited by buffer.auto_c_separator characters). The sorted order of items (buffer.auto_c_order) must have already been defined. When the user selects an item, id is sent in an events.USER_LIST_SELECTION event along with the selection.

Parameters:

buffer:auto_c_select(prefix)

Selects the first item that starts with string prefix in an autocompletion or user list, using the case sensitivity setting buffer.auto_c_ignore_case.

Parameters:

buffer:auto_c_complete()

Completes the current word with the one selected in an autocompletion list.

buffer:auto_c_cancel()

Cancels the displayed autocompletion or user list.

buffer:auto_c_active()

Returns whether or not an autocompletion or user list is visible.

Return:

buffer:auto_c_pos_start()

Returns the position where autocompletion started or where a user list was shown.

Return:

buffer.auto_c_current

The index of the currently selected item in an autocompletion or user list. (Read-only)

buffer.auto_c_current_text

The text of the currently selected item in an autocompletion or user list. (Read-only)

buffer.auto_c_choose_single

Automatically choose the item in a single-item autocompletion list. This option has no effect for a user list. The default value is true.

buffer.auto_c_fill_ups

The set of characters that choose the currently selected item in an autocompletion or user list when the user types one of them. (Write-only) The default value is ''.

buffer:auto_c_stops(chars)

Allows the user to type any character in string set chars in order to cancel an autocompletion or user list. The default set is empty.

Parameters:

buffer.auto_c_auto_hide

Automatically cancel an autocompletion or user list when no entries match typed text. The default value is true.

buffer.auto_c_cancel_at_start

Cancel an autocompletion list when backspacing to a position before where autocompletion started (instead of before the word being completed). This option has no effect for a user list. The default value is true.

buffer.auto_c_ignore_case

Ignore case when searching an autocompletion or user list for matches. The default value is false.

buffer.auto_c_case_insensitive_behavior

The behavior mode for a case insensitive autocompletion or user list when buffer.auto_c_ignore_case is true.

view.auto_c_max_width

The maximum number of characters per item to show in autocompletion and user lists. The default value is 0, which automatically sizes the width to fit the longest item.

view.auto_c_max_height

The maximum number of items per page to show in autocompletion and user lists. The default value is 5.

buffer.auto_c_drop_rest_of_word

Delete any word characters immediately to the right of autocompleted text. The default value is false.

buffer.auto_c_multi

The multiple selection autocomplete mode.

Display Images in Lists

Autocompletion and user lists can render images next to items by appending to each list item the type separator character specific to lists followed by an image’s type number, which uniquely identifies a registered image.

view.new_image_type()

Returns a unique image type identifier number for use with view:register_image() and view:register_rgba_image(). Use this function for custom image types in order to prevent clashes with identifiers of other custom image types.

view:register_image(type, xpm_data)

Registers XPM image xpm_data to type number type for use in autocompletion and user lists.

Parameters:

See also:

view.rgba_image_width

The width of the RGBA image to be defined using view:marker_define_rgba_image() and view:register_rgba_image().

view.rgba_image_height

The height of the RGBA image to be defined using view:marker_define_rgba_image().

view.rgba_image_scale

The scale factor in percent of the RGBA image to be defined using view:marker_define_rgba_image(). This is useful on macOS with a retina display where each display unit is 2 pixels: use a factor of 200 so that each image pixel is displayed using a screen pixel. The default scale, 100, will stretch each image pixel to cover 4 screen pixels on a retina display.

view:register_rgba_image(type, pixels)

Registers RGBA image pixels to type number type for use in autocompletion and user lists. The dimensions for pixels (view.rgba_image_width and view.rgba_image_height) must have already been defined. pixels is a sequence of 4 byte pixel values (red, blue, green, and alpha) defining the image line by line starting at the top-left pixel.

Parameters:

buffer.auto_c_type_separator

The character byte that separates autocompletion and user list items and their image types. Autocompletion and user list items can display both an image and text. Register images and their types using view:register_image() or view:register_rgba_image() before appending image types to list items after type separator characters. The default value is 63 (‘?’).

view:clear_registered_images()

Clears all images registered using view:register_image() and view:register_rgba_image().

Show a Call Tip

A call tip is a small pop-up window that conveys a piece of textual information, such as the arguments and documentation for a function. A call tip may highlight a range of text inside of itself, such as the current argument in a function call.

view:call_tip_show(pos, text)

Displays a call tip at position pos with string text as the call tip’s contents. Any “\001” or “\002” bytes in text are replaced by clickable up or down arrow visuals, respectively. These may be used to indicate that a symbol has more than one call tip, for example.

Parameters:

view:call_tip_set_hlt(start_pos, end_pos)

Highlights a call tip’s text between positions start_pos to end_pos with the color view.call_tip_fore_hlt.

Parameters:

view:call_tip_cancel()

Removes the displayed call tip from view.

view:call_tip_active()

Returns whether or not a call tip is visible.

Return:

view:call_tip_pos_start()

Returns a call tip’s display position.

Return:

view.call_tip_position

Display a call tip above the current line instead of below it. The default value is false.

view.call_tip_use_style

The pixel width of tab characters in call tips. When non-zero, also enables the use of style number view.STYLE_CALLTIP instead of view.STYLE_DEFAULT for call tip styles. The default value is depends on buffer.tab_width and the current font.

view.call_tip_pos_start

The position at which backspacing beyond it hides a visible call tip. (Write-only)

view.call_tip_fore_hlt

A call tip’s highlighted text foreground color, in “0xBBGGRR” format. (Write-only)

Fold or Hide Lines

Code folding allows the user to temporarily hide blocks of source code. The buffer’s lexer normally determines code fold points that the view denotes with fold margin markers, but arbitrary lines may be shown or hidden.

view:toggle_fold(line)

Toggles the fold point on line number line between expanded (where all of its child lines are displayed) and contracted (where all of its child lines are hidden).

Parameters:

view:toggle_fold_show_text(line, text)

Toggles a fold point on line number line between expanded (where all of its child lines are displayed) and contracted (where all of its child lines are hidden), and shows string text next to that line. text is drawn with style number view.STYLE_FOLDDISPLAYTEXT.

Parameters:

See also:

view:fold_line(line, action)

Contracts, expands, or toggles the fold point on line number line, depending on action.

Parameters:

view:fold_children(line, action)

Contracts, expands, or toggles the fold point on line number line, as well as all of its children, depending on action.

Parameters:

view:fold_all(action)

Contracts, expands, or toggles all fold points, depending on action. When toggling, the state of the first fold point determines whether to expand or contract.

Parameters:

view:hide_lines(start_line, end_line)

Hides the range of lines between line numbers start_line to end_line. This has no effect on fold levels or fold flags.

Parameters:

view:show_lines(start_line, end_line)

Shows the range of lines between line numbers start_line to end_line. This has no effect on fold levels or fold flags and the first line cannot be hidden.

Parameters:

view:ensure_visible(line)

Ensures line number line is visible by expanding any fold points hiding it.

Parameters:

view:ensure_visible_enforce_policy(line)

Ensures line number line is visible by expanding any fold points hiding it based on the vertical caret policy previously defined in view:set_visible_policy().

Parameters:

view:set_default_fold_display_text(text)

Sets the default fold display text to string text.

Parameters:

See also:

view:get_default_fold_display_text()

Returns the default fold display text.

buffer.fold_level <table>

List of fold level bit-masks per line number. Fold level masks comprise of an integer level combined with any of the following bit flags:

buffer.fold_parent <table>

List of fold point line numbers per child line number. (Read-only) A line number of -1 means no line was found.

buffer:get_last_child(line, level)

Returns the line number of the last line after line number line whose fold level is greater than level. If level is -1, returns the level of line.

Parameters:

view.fold_expanded <table>

List of flags per line number that indicate whether or not fold points are expanded for those line numbers. Setting expanded fold states does not toggle folds; it only updates fold margin markers. Use view:toggle_fold() instead.

view:contracted_fold_next(line)

Returns the line number of the next contracted fold point starting from line number line, or -1 if none exists.

Parameters:

Return:

view.line_visible <table>

List of flags per line number that indicate whether or not lines are visible for those line numbers. (Read-only)

view.all_lines_visible

Whether or not all lines are visible. (Read-only)

Scroll the View

view.x_offset

The horizontal scroll pixel position. A value of 0 is the normal position with the first text column visible at the left of the view.

view:line_scroll_up()

Scrolls the buffer up one line, keeping the caret visible.

view:line_scroll_down()

Scrolls the buffer down one line, keeping the caret visible.

view:line_scroll(columns, lines)

Scrolls the buffer right columns columns and down lines lines. Negative values are allowed.

Parameters:

view:scroll_caret()

Scrolls the caret into view based on the policies previously defined in view:set_x_caret_policy() and view:set_y_caret_policy().

view:scroll_range(secondary_pos, primary_pos)

Scrolls into view the range of text between positions primary_pos and secondary_pos, with priority given to primary_pos. Similar to view:scroll_caret(), but with primary_pos instead of buffer.current_pos. This is useful for scrolling search results into view.

Parameters:

view:vertical_center_caret()

Centers current line in the view.

view:scroll_to_start()

Scrolls to the beginning of the buffer without moving the caret.

view:scroll_to_end()

Scrolls to the end of the buffer without moving the caret.

Configure Indentation and Line Endings

Indentation settings and end-of-line characters can be configured on a per-buffer and per-file basis.

buffer.use_tabs

Use tabs instead of spaces in indentation. Changing the current setting does not convert any of the buffer’s existing indentation. Use textadept.editing.convert_indentation() to do so. The default value is true.

buffer.tab_width

The number of space characters represented by a tab character. The default value is 8.

buffer.indent

The number of spaces in one level of indentation. The default value is 0, which uses the value of buffer.tab_width.

buffer.tab_indents

Indent text when tabbing within indentation. The default value is true.

buffer.back_space_un_indents

Un-indent text when backspacing within indentation. The default value is true.

buffer.eol_mode

The current end of line mode. Changing the current mode does not convert any of the buffer’s existing end of line characters. Use buffer:convert_eols() to do so.

buffer:convert_eols(mode)

Converts all end of line characters to those in end of line mode mode.

Parameters:

Configure Character Settings

The classification of characters as word, whitespace, or punctuation characters affects the buffer’s behavior when moving between words or searching for whole words. The display of individual characters may be changed.

buffer.word_chars

The string set of characters recognized as word characters. The default value is a string that contains alphanumeric characters, an underscore, and all characters greater than ASCII value 127.

buffer.whitespace_chars

The string set of characters recognized as whitespace characters. Set this only after setting buffer.word_chars. The default value is a string that contains all non-newline characters less than ASCII value 33.

buffer.punctuation_chars

The string set of characters recognized as punctuation characters. Set this only after setting buffer.word_chars. The default value is a string that contains all non-word and non-whitespace characters.

buffer:set_chars_default()

Resets buffer.word_chars, buffer.whitespace_chars, and buffer.punctuation_chars to their respective defaults.

view.representation <table>

Map of alternative string representations of characters. Representations are displayed in the same way control characters are. Use the empty string for the ‘\0’ character when assigning its representation. Characters are strings, not numeric codes, and can be multi-byte characters. Call view:clear_representation() to remove a representation.

view:clear_representation(char)

Removes the alternate string representation for character char (which may be a multi-byte character).

Parameters:

view:clear_all_representations()

Removes all alternate string representations of characters.

view.representation_appearance <table>

Map of characters to their string representation’s appearance.

The default values are view.REPRESENTATION_BLOB.

view.representation_color <table>

Map of characters to their string representation’s color in “0xBBGGRR” format.

Configure the Color Theme

Themes are Lua files that define colors, specify how the view displays text, and assign colors and alpha values to various view properties. Colors are integers that range from 0 to 0xFFFFFF. Alpha transparency values are integers that range from 0 to 255 (view.ALPHA_TRANSPARENT to view.ALPHA_OPAQUE), or view.ALPHA_NOALPHA.

view:set_theme([name][, env])

Sets the view’s color theme to be string name, with the contents of table env available as global variables. User themes override Textadept’s default themes when they have the same name. If name contains slashes, it is assumed to be an absolute path to a theme instead of a theme name.

Parameters:

Usage:

view.colors <table>

Map of color name strings to color values in 0xBBGGRR format. The contents of this map is typically set by a theme. Changing colors manually (e.g. via the command entry) has no effect since colors are referenced by value, not name. Note: for applications running within a terminal emulator, only 16 color values are recognized, regardless of how many colors a user’s terminal actually supports. (A terminal emulator’s settings determines how to actually display these recognized color values, which may end up being mapped to a completely different color set.) In order to use the light variant of a color, some terminals require a style’s bold field must be set along with that normal color. Recognized color values are black (0x000000), red (0x000080), green (0x008000), yellow (0x008080), blue (0x800000), magenta (0x800080), cyan (0x808000), white (0xC0C0C0), light black (0x404040), light red (0x0000FF), light green (0x00FF00), light yellow (0x00FFFF), light blue (0xFF0000), light magenta (0xFF00FF), light cyan (0xFFFF00), and light white (0xFFFFFF).

view.styles <table>

Map of style names to style definition tables. The contents of this map is typically set by a theme. If you are setting it manually (e.g. via the command entry), call view:set_styles() to refresh the view and apply the styles.

Style names consist of the following:

Style definition tables may contain the following fields:

view:set_styles()

Applies defined styles to the view. This should be called any time a style in view.styles changes.

Override Style Settings

The color theme normally dictates default styles, but custom fonts, colors, and attributes may be applied to styles outside of themes. However, these custom settings must be re-applied every time a new buffer or view is created, and every time a lexer is loaded.

view:style_reset_default()

Resets view.STYLE_DEFAULT to its initial state.

view:style_clear_all()

Reverts all styles to having the same properties as view.STYLE_DEFAULT.

view.style_font <table>

List of string font names of text for style numbers from 1 to 256.

view.style_size <table>

List of font sizes of text for style numbers from 1 to 256.

view.style_fore <table>

List of foreground colors, in “0xBBGGRR” format, of text for style numbers from 1 to 256.

view.style_back <table>

List of background colors, in “0xBBGGRR” format, of text for style numbers from 1 to 256.

view.style_bold <table>

List of flags that indicate whether or not text is bold for style numbers from 1 to 256. The default values are false.

view.style_italic <table>

List of flags that indicate whether or not text is italic for style numbers from 1 to 256. The default values are false.

view.style_underline <table>

List of flags that indicate whether or not text is underlined for style numbers from 1 to 256. The default values are false.

view.style_eol_filled <table>

List of flags that indicate whether or not the background colors of styles whose characters occur last on lines extend all the way to the view’s right margin for style numbers from 1 to 256. The default values are false.

view.style_case <table>

List of letter case modes of text for style numbers from 1 to 256.

The default values are view.CASE_MIXED.

view.style_visible <table>

List of flags that indicate whether or not text is visible for style numbers from 1 to 256. The default values are true.

view.style_changeable <table>

List of flags that indicate whether or not text is changeable for style numbers from 1 to 256. The default values are true. Read-only styles do not allow the caret into the range of text.

Assign Caret, Selection, Whitespace, and Line Colors

view.element_color <table>

Map of colors in “0xAABBGGRR” format for UI element identifiers. If the alpha byte is omitted, it is assumed to be 0xFF (opaque).

view.element_is_set <table>

Map of flags for UI element identifiers that indicate whether or not a color has been manually set.

view:reset_element_color(element)

Resets the color of UI element element to its default color.

Parameters:

view.element_base_color <table>

Map of default colors on “0xAABBGGRR” format for UI element identifiers. (Read-only) If the alpha byte is omitted, it is assumed to be 0xFF (opaque).

view.element_allows_translucent <table>

Map of flags for UI element identifiers that indicate whether or not an element supports translucent colors.

view.selection_layer

The layer mode for drawing selections.

The default value is view.LAYER_BASE.

Configure Caret Display

view.caret_style

The caret’s visual style.

Any block setting may be combined with view.CARETSTYLE_BLOCK_AFTER via bitwise OR (|) in order to draw the caret after the end of a selection, as opposed to just inside it.

The default value is view.CARETSTYLE_LINE.

view.caret_width

The line caret’s pixel width in insert mode, between 0 and 20. The default value is 1.

view.caret_period

The time between caret blinks in milliseconds. A value of 0 stops blinking. The default value is 500.

view.caret_line_frame

The caret line’s frame width in pixels. When non-zero, the line that contains the caret is framed instead of colored in. The view.ELEMENT_CARET_LINE_BACK color applies to the frame. The default value is 0.

view.caret_line_highlight_subline

Color the background of the subline that contains the caret a different color, rather than the whole line. The defalt value is false.

view.caret_line_visible_always

Always show the caret line, even when the view is not in focus. The default value is true, but only for the current view, and only while Textadept has focus.

view.caret_line_layer

The caret line layer mode.

The default value is view.LAYER_BASE.

view.additional_carets_visible

Display additional carets. The default value is true.

Allow additional carets to blink. The default value is true.

buffer.virtual_space_options

The virtual space mode.

Configure Selection Display

view.sel_eol_filled

Extend the selection to the view’s right margin. The default value is false.

Configure Whitespace Display

Normally, tab, space, and end of line characters are invisible.

view.view_ws

The whitespace visibility mode.

The default value is view.WS_INVISIBLE.

view.whitespace_size

The pixel size of the dots that represent space characters when whitespace is visible. The default value is 1.

view.tab_draw_mode

The draw mode of visible tabs.

The default value is view.TD_LONGARROW.

view.view_eol

Display end of line characters. The default value is false.

view.extra_ascent

The amount of pixel padding above lines. The default value is 0.

view.extra_descent

The amount of pixel padding below lines. The default is 0.

Configure Scrollbar Display and Scrolling Behavior

view.h_scroll_bar

Display the horizontal scroll bar. The default value is true in the GUI version and false in the terminal version.

view.v_scroll_bar

Display the vertical scroll bar. The default value is true.

view.scroll_width

The horizontal scrolling pixel width. If view.scroll_width_tracking is false, the view uses this static width for horizontal scrolling instead of measuring the width of buffer lines. The default value is 1 in conjunction with view.scroll_width_tracking being true. A value of 2000 is reasonable if view.scroll_width_tracking is false.

view.scroll_width_tracking

Grow (but never shrink) view.scroll_width as needed to match the maximum width of a displayed line. Enabling this may have performance implications for buffers with long lines. The default value is true.

view.end_at_last_line

Disable scrolling past the last line. The default value is true.

view:set_x_caret_policy(policy, x)

Defines scrolling policy bit-mask policy as the policy for keeping the caret x number of pixels away from the horizontal margins.

Parameters:

view:set_y_caret_policy(policy, y)

Defines scrolling policy bit-mask policy as the policy for keeping the caret y number of lines away from the vertical margins.

Parameters:

view:set_visible_policy(policy, y)

Defines scrolling policy bit-mask policy as the policy for keeping the caret y number of lines away from the vertical margins when view:ensure_visible_enforce_policy() redisplays hidden or folded lines. It is similar in operation to view:set_y_caret_policy().

Parameters:

Configure Mouse Cursor Display

view.cursor

The display cursor type.

The default value is view.CURSORNORMAL.

Configure Wrapped Line Display

By default, lines that contain more characters than the view can show do not wrap into view and onto sub-lines.

view.wrap_mode

Long line wrap mode.

The default value is view.WRAP_NONE.

view.wrap_visual_flags

The wrapped line visual flag display mode.

The default value is view.WRAPVISUALFLAG_NONE.

view.wrap_visual_flags_location

The wrapped line visual flag location.

The default value is view.WRAPVISUALFLAGLOC_DEFAULT.

view.wrap_start_indent

The number of spaces of indentation to display wrapped lines with if view.wrap_indent_mode is view.WRAPINDENT_FIXED. The default value is 0.

view.wrap_indent_mode

The wrapped line indent mode.

The default value is view.WRAPINDENT_FIXED.

Configure Text Zoom

view:zoom_in()

Increases the size of all fonts by one point, up to 60.

view:zoom_out()

Decreases the size of all fonts by one point, down to -10.

view.zoom

The number of points to add to the size of all fonts. Negative values are allowed, down to -10. The default value is 0.

Configure Long Line Display

While the view does not enforce a maximum line length, it allows for visual identification of long lines.

view.edge_column

The column number to mark long lines at.

view.edge_mode

The long line mark mode.

view:multi_edge_add_line(column, color)

Adds a new vertical line at column number column with color color, in “0xBBGGRR” format.

Parameters:

view:multi_edge_clear_all()

Clears all vertical lines created by view:multi_edge_add_line().

view.multi_edge_column <table>

List of edge column positions per edge column number. (Read-only) A position of -1 means no edge column was found.

view.edge_color

The color, in “0xBBGGRR” format, of the single edge or background for long lines according to view.edge_mode.

Configure Fold Settings and Folded Line Display

view.folding

Whether or not folding is enabled for the lexers that support it. This option is enabled by default.

view.fold_compact

Whether or not blank lines after an ending fold point are included in that fold. This option is disabled by default.

view.fold_on_zero_sum_lines

Whether or not to mark as a fold point lines that contain both an ending and starting fold point. For example, } else { would be marked as a fold point. This option is disabled by default. This is an alias for

view.fold_by_indentation

Whether or not to fold based on indentation level if a lexer does not have a folder. Some lexers automatically enable this option. It is disabled by default.

view.fold_flags

Bit-mask of folding lines to draw in the buffer. (Read-only)

The default value is view.FOLDFLAG_LINEAFTER_CONTRACTED in the GUI version, and view.FOLDFLAG_NONE in the terminal version.

view.fold_display_text_style

The fold display text mode.

The default value is view.FOLDDISPLAYTEXT_BOXED.

Highlight Matching Braces

view:brace_bad_light(pos)

Highlights the character at position pos as an unmatched brace character using the 'style.bracebad' style. Removes highlighting when pos is -1.

Parameters:

view:brace_bad_light_indicator(use_indicator, indicator)

Highlights unmatched brace characters with indicator number indicator, in the range of 1 to 32, instead of the view.STYLE_BRACEBAD style if use_indicator is true.

Parameters:

view:brace_highlight(pos1, pos2)

Highlights the characters at positions pos1 and pos2 as matching braces using the 'style.bracelight' style. If indent guides are enabled, locates the column with buffer.column and sets view.highlight_guide in order to highlight the indent guide.

Parameters:

view:brace_highlight_indicator(use_indicator, indicator)

Highlights matching brace characters with indicator number indicator, in the range of 1 to 32, instead of the view.STYLE_BRACELIGHT style if use_indicator is true.

Parameters:

Configure Indentation Guide Display

view.indentation_guides

The indentation guide drawing mode. Indentation guides are dotted vertical lines that appear within indentation whitespace at each level of indentation.

The default value is view.IV_LOOKBOTH in the GUI version, and view.IV_NONE in the terminal version.

view.highlight_guide

The indentation guide column number to also highlight when highlighting matching braces, or 0 to stop indentation guide highlighting.

Configure File Types

buffer:set_lexer([name])

Associates string lexer name name or the auto-detected lexer name with the buffer.

Parameters:

Usage:

See also:

buffer:get_lexer(current)

Returns the buffer’s lexer name. If current is true, returns the name of the lexer under the caret in a multiple-language lexer.

Parameters:

buffer.lexer_language

The buffer’s lexer name. (Read-only) If the lexer is a multi-language lexer, buffer:get_lexer() can obtain the lexer under the caret.

Manually Style Text

Plain text can be manually styled after manually setting up styles.

buffer:colorize(start_pos, end_pos)

Instructs the lexer to style and mark fold points in the range of text between start_pos and end_pos. If end_pos is -1, styles and marks to the end of the buffer. This is useful for reprocessing and refreshing a range of text if that range has incorrect highlighting or incorrect fold points.

Parameters:

buffer:clear_document_style()

Clears all styling and folding information.

buffer:start_styling(position, unused)

Begins styling at position position with styling bit-mask style_mask. style_mask specifies which style bits can be set with buffer:set_styling().

Parameters:

Usage:

buffer:set_styling(length, style)

Assigns style number style, in the range from 1 to 256, to the next length characters, starting from the current styling position, and increments the styling position by length. buffer:start_styling() should be called before buffer:set_styling().

Parameters:

Query Style Information

buffer.style_at <table>

List of style numbers per position. (Read-only)

buffer.named_styles

The number of named lexer styles.

buffer:name_of_style(style)

Returns the name of style number style, which is between 1 and 256. Note that due to an implementation detail, the returned style uses ‘.’ instead of ‘’. When setting styles, the ‘’ form is preferred.

Parameters:

Return:

buffer:style_of_name(style_name)

Returns the style number associated with string style_name, or view.STYLE_DEFAULT if style_name is not in use.

Parameters:

Return:

buffer.end_styled

The current styling position or the last correctly styled character’s position. (Read-only)

Miscellaneous

buffer.tab_label

The buffer’s tab label in the tab bar. (Write-only) Textadept sets this automatically based on the buffer’s filename or type, and its save status.

buffer.read_only

Whether or not the buffer is read-only. The default value is false.

buffer:cancel()

Cancels the active selection mode, autocompletion or user list, call tip, etc.

buffer:edit_toggle_overtype()

Toggles buffer.overtype.

buffer.overtype

Enable overtype mode, where typed characters overwrite existing ones. The default value is false.

view.idle_styling

The idle styling mode. This mode has no effect when view.wrap_mode is on.

view.mouse_dwell_time

The number of milliseconds the mouse must idle before generating an events.DWELL_START event. A time of view.TIME_FOREVER will never generate one.

buffer:delete()

Deletes the buffer. Do not call this function. Call buffer:close() instead. Emits events.BUFFER_DELETED.

The events Module

Textadept’s core event structure and handlers.

Textadept emits events when you do things like create a new buffer, press a key, click on a menu, etc. You can even emit events yourself using Lua. Each event has a set of event handlers, which are simply Lua functions called in the order they were connected to an event. For example, if you created a module that needs to do something each time Textadept creates a new buffer, connect a Lua function to the events.BUFFER_NEW event:

events.connect(events.BUFFER_NEW, function()
	-- Do something here.
end)

Events themselves are nothing special. You do not have to declare one before using it. Events are simply strings containing arbitrary event names. When either you or Textadept emits an event, Textadept runs all event handlers connected to the event, passing any given arguments to the event’s handler functions. If an event handler explicitly returns a value that is not nil, Textadept will not call subsequent handlers. This is useful if you want to stop the propagation of an event like a keypress if your event handler handled it, or if you want to use the event framework to pass values.

Fields defined by events

events.APPLEEVENT_ODOC

Emitted when macOS tells Textadept to open a file. Arguments:

events.ARG_NONE

Emitted when no filename or directory command line arguments are passed to Textadept on startup.

events.AUTO_C_CANCELED

Emitted when canceling an autocompletion or user list.

events.AUTO_C_CHAR_DELETED

Emitted after deleting a character while an autocompletion or user list is active.

events.AUTO_C_COMPLETED

Emitted after inserting an item from an autocompletion list into the buffer. Arguments:

events.AUTO_C_SELECTION

Emitted after selecting an item from an autocompletion list, but before inserting that item into the buffer. Automatic insertion can be canceled by calling buffer:auto_c_cancel() before returning from the event handler. Arguments:

events.AUTO_C_SELECTION_CHANGE

Emitted as items are highlighted in an autocompletion or user list. Arguments:

events.BUFFER_AFTER_REPLACE_TEXT

Emitted after replacing the contents of the current buffer. Note that it is not guaranteed that events.BUFFER_BEFORE_REPLACE_TEXT was emitted previously. The buffer must not be modified during this event.

events.BUFFER_AFTER_SWITCH

Emitted right after switching to another buffer. The buffer being switched to is buffer. Emitted by view:goto_buffer().

events.BUFFER_BEFORE_REPLACE_TEXT

Emitted before replacing the contents of the current buffer. Note that it is not guaranteed that events.BUFFER_AFTER_REPLACE_TEXT will be emitted shortly after this event. The buffer must not be modified during this event.

events.BUFFER_BEFORE_SWITCH

Emitted right before switching to another buffer. The buffer being switched from is buffer. Emitted by view:goto_buffer() and buffer.new().

events.BUFFER_DELETED

Emitted after deleting a buffer. Emitted by buffer:delete(). Arguments:

events.BUFFER_NEW

Emitted after creating a new buffer. The new buffer is buffer. Emitted on startup and by buffer.new().

events.BUILD_OUTPUT

Emitted when executing a project’s build shell command. By default, output is printed to the output buffer. In order to override this behavior, connect to the event with an index of 1 and return true. Arguments:

events.CALL_TIP_CLICK

Emitted when clicking on a calltip. This event is not emitted by the Qt version. Arguments:

events.CHAR_ADDED

Emitted after the user types a text character into the buffer. Arguments:

events.COMMAND_TEXT_CHANGED

Emitted when the text in the command entry changes. ui.command_entry:get_text() returns the current text.

events.COMPILE_OUTPUT

Emitted when executing a language’s compile shell command. By default, compiler output is printed to the output buffer. In order to override this behavior, connect to the event with an index of 1 and return true. Arguments:

events.CSI

Emitted when the terminal version receives an unrecognized CSI sequence. Arguments:

events.DOUBLE_CLICK

Emitted after double-clicking the mouse button. Arguments:

events.DWELL_END

Emitted after events.DWELL_START when the user moves the mouse, presses a key, or scrolls the view. Arguments:

events.DWELL_START

Emitted when the mouse is stationary for view.mouse_dwell_time milliseconds. Arguments:

events.ERROR

Emitted when an error occurs. Arguments:

events.FILE_AFTER_SAVE

Emitted right after saving a file to disk. Emitted by buffer:save() and buffer:save_as(). Arguments:

events.FILE_BEFORE_SAVE

Emitted right before saving a file to disk. Emitted by buffer:save(). Arguments:

events.FILE_CHANGED

Emitted when Textadept detects that an open file was modified externally. When connecting to this event, connect with an index of 1 in order to override the default prompt to reload the file. Arguments:

events.FILE_OPENED

Emitted after opening a file in a new buffer. Emitted by io.open_file(). Arguments:

events.FIND

Emitted to find text via the Find & Replace Pane. Emitted by ui.find.find_next() and ui.find.find_prev(). Arguments:

events.FIND_RESULT_FOUND

Emitted when a result is found. It is selected and has been scrolled into view. Arguments:

events.FIND_TEXT_CHANGED

Emitted when the text in the “Find” field of the Find & Replace Pane changes. ui.find.find_entry_text contains the current text.

events.FIND_WRAPPED

Emitted when a text search wraps (passes through the beginning of the buffer), either from bottom to top (when searching for a next occurrence), or from top to bottom (when searching for a previous occurrence). This is useful for implementing a more visual or audible notice when a search wraps in addition to the statusbar message.

events.FOCUS

Emitted when Textadept receives focus. This event is never emitted when Textadept is running in the terminal.

events.INDICATOR_CLICK

Emitted when clicking the mouse on text that has an indicator present. Arguments:

events.INDICATOR_RELEASE

Emitted when releasing the mouse after clicking on text that has an indicator present. Arguments:

events.INITIALIZED

Emitted after Textadept finishes initializing.

events.KEYPRESS

Emitted when pressing a recognized key. If any handler returns true, the key is not handled further (e.g. inserted into the buffer). Arguments:

events.LEXER_LOADED

Emitted after loading a language lexer. This is useful for automatically loading language modules as source files are opened, or setting up language-specific editing features for source files. Arguments:

events.MARGIN_CLICK

Emitted when clicking the mouse inside a sensitive margin. Arguments:

events.MENU_CLICKED

Emitted after selecting a menu item. Arguments:

events.MODE_CHANGED

Emitted by the GUI version when switching between light mode and dark mode. Arguments:

events.MOUSE

Emitted by the terminal version for an unhandled mouse event. A handler should return true if it handled the event. Otherwise Textadept will try again. (This side effect for a false or nil return is useful for sending the original mouse event to a different view that a handler has switched to.) Arguments:

events.QUIT

Emitted when quitting Textadept. When connecting to this event, connect with an index of 1 if the handler needs to run before Textadept closes all open buffers. If a handler returns true, Textadept does not quit. It is not recommended to return false from a quit handler, as that may interfere with Textadept’s normal shutdown procedure. Emitted by quit().

events.REPLACE

Emitted to replace selected (found) text. Emitted by ui.find.replace(). Arguments:

events.REPLACE_ALL

Emitted to replace all occurrences of found text. Emitted by ui.find.replace_all(). Arguments:

events.RESET_AFTER

Emitted after resetting Textadept’s Lua state. Emitted by reset(). Arguments:

events.RESET_BEFORE

Emitted before resetting Textadept’s Lua state. Emitted by reset(). Arguments:

events.RESUME

Emitted when resuming Textadept from a suspended state. This event is only emitted by the terminal version.

events.RUN_OUTPUT

Emitted when executing a language’s or project’s run shell command. By default, output is printed to the output buffer. In order to override this behavior, connect to the event with an index of 1 and return true. Arguments:

events.SAVE_POINT_LEFT

Emitted after leaving a save point.

events.SAVE_POINT_REACHED

Emitted after reaching a save point.

events.SESSION_LOAD

Emitted when loading a session. Arguments:

events.SESSION_SAVE

Emitted when saving a session. Arguments:

events.SUSPEND

Emitted prior to suspending Textadept. This event is only emitted by the terminal version.

events.TAB_CLICKED

Emitted when the user clicks on a buffer tab. When connecting to this event, connect with an index of 1 if the handler needs to run before Textadept switches between buffers. Note that Textadept always displays a context menu on right-click. Arguments:

events.TAB_CLOSE_CLICKED

Emitted when the user clicks a buffer tab’s close button. When connecting to this event, connect with an index of 1 if the handler needs to run before Textadept closes the buffer. This event is only emitted in the Qt GUI version. Arguments:

events.TEST_OUTPUT

Emitted when executing a project’s shell command for running tests. By default, output is printed to the output buffer. In order to override this behavior, connect to the event with an index of 1 and return true. Arguments:

events.UNFOCUS

Emitted when Textadept loses focus. This event is never emitted when Textadept is running in the terminal.

events.UPDATE_UI

Emitted after the view is visually updated. Arguments:

events.URI_DROPPED

Emitted after dragging and dropping a URI into a view. Arguments:

events.USER_LIST_SELECTION

Emitted after selecting an item in a user list. Arguments:

events.VIEW_AFTER_SWITCH

Emitted right after switching to another view. The view being switched to is view. Emitted by ui.goto_view().

events.VIEW_BEFORE_SWITCH

Emitted right before switching to another view. The view being switched from is view. Emitted by ui.goto_view() and view:split().

events.VIEW_NEW

Emitted after creating a new view. The new view is view. Emitted on startup and by view:split().

events.ZOOM

Emitted after changing view.zoom. Emitted by view:zoom_in() and view:zoom_out().

Functions defined by events

events.connect(event, f[, index])

Adds function f to the set of event handlers for event event at position index. If index not given, appends f to the set of handlers. event may be any arbitrary string and does not need to have been previously defined.

Parameters:

Usage:

events.disconnect(event, f)

Removes function f from the set of handlers for event event.

Parameters:

events.emit(event[, …])

Sequentially calls all handler functions for event event with the given arguments. event may be any arbitrary string and does not need to have been previously defined. If any handler explicitly returns a value that is not nil, emit() returns that value and ceases to call subsequent handlers. This is useful for stopping the propagation of an event like a keypress after it has been handled, or for passing back values from handlers.

Parameters:

Usage:

Return:

The io Module

Extends Lua’s io library with Textadept functions for working with files.

Fields defined by io

io.detect_indentation

Whether or not to attempt to detect indentation settings for opened files. If any non-blank line starts with a tab, tabs are used. Otherwise, for the first non-blank line that starts with between two and eight spaces, that number of spaces is used. The default value is true.

io.encodings <table>

List of encodings to attempt to decode files as. The default list contains UTF-8, ASCII, CP1252, and UTF-16.

You should add to this list if you get a “Conversion failed” error when trying to open a file whose encoding is not recognized. Valid encodings are GNU iconv’s encodings and include:

Usage:

io.ensure_final_newline

Whether or not to ensure there is a final newline when saving text files. This has no effect on binary files. The default value is false on Windows, and true on macOS, Linux, and BSD.

io.quick_open_filters <table>

Map of directory paths to filters used by io.quick_open().

io.quick_open_max

The maximum number of files listed in the quick open dialog. The default value is 5000.

io.recent_files <table>

List of recently opened files, the most recent being towards the top.

Functions defined by io

io.close_all_buffers()

Closes all open buffers, prompting the user to continue if there are unsaved buffers, and returns true if the user did not cancel. No buffers are saved automatically. They must be saved manually.

Return:

io.get_project_root([path][, submodule=false])

Returns the root directory of the project that contains filesystem path path. In order to be recognized, projects must be under version control. Recognized VCSes are Bazaar, Fossil, Git, Mercurial, and SVN.

Parameters:

Return:

io.open_file([filenames])

Opens filenames, a string filename or list of filenames, or the user-selected filename(s). Emits events.FILE_OPENED.

Parameters:

io.open_recent_file()

Prompts the user to select a recently opened file to be reopened.

See also:

io.quick_open([paths[, filter]])

Prompts the user to select files to be opened from paths, a string directory path or list of directory paths, using a list dialog. If paths is nil, uses the current project’s root directory, which is obtained from io.get_project_root(). String or list filter determines which files to show in the dialog, with the default filter being io.quick_open_filters[path] (if it exists) or lfs.default_filter. A filter consists of glob patterns that match file and directory paths to include or exclude. Patterns are inclusive by default. Exclusive patterns begin with a ‘!’. If no inclusive patterns are given, any path is initially considered. As a convenience, ‘/’ also matches the Windows directory separator (‘[/\]’ is not needed). The number of files in the list is capped at io.quick_open_max. If filter is nil and paths is ultimately a string, the filter from the io.quick_open_filters table is used. If that filter does not exist, lfs.default_filter is used.

Parameters:

Usage:

io.save_all_files(untitled)

Saves all unsaved buffers to their respective files, prompting the user for filenames for untitled buffers if untitled is true, and returns true on success. Print and output buffers are ignored.

Parameters:

Return:

The keys Module

Manages key bindings in Textadept.

Overview

Define key bindings in the global keys table in key-value pairs. Each pair consists of either a string key sequence and its associated command, a string lexer name (from the lexers/ directory) with a table of key sequences and commands, a string key mode with a table of key sequences and commands, or a key sequence with a table of more sequences and commands. The latter is part of what is called a “key chain”, to be discussed below. When searching for a command to run based on a key sequence, Textadept considers key bindings in the current key mode to have priority. If no key mode is active, language-specific key bindings have priority, followed by the ones in the global table. This means if there are two commands with the same key sequence, Textadept runs the language-specific one. However, if the command returns the boolean value false, Textadept also runs the lower-priority command. (This is useful for overriding commands like autocompletion with language-specific completion, but fall back to word autocompletion if the first command fails.)

Key Sequences

Key sequences are strings built from an ordered combination of modifier keys and the key’s inserted character. Modifier keys are “Control”, “Shift”, and “Alt” on Windows, Linux/BSD, and in the terminal version. On macOS they are “Control” (^), “Alt/Option” (⌥), “Command” (⌘), and “Shift” (⇧). These modifiers have the following string representations:

Modifier Windows / Linux / BSD macOS Terminal
Control 'ctrl' 'ctrl' 'ctrl'
Alt 'alt' 'alt' 'meta'
Command N/A 'cmd' N/A
Shift 'shift' 'shift' 'shift'

The string representation of key values less than 255 is the character that Textadept would normally insert if the “Control”, “Alt”, and “Command” modifiers were not held down. Therefore, a combination of Ctrl+Alt+Shift+A has the key sequence ctrl+alt+A on Windows and Linux/BSD, but a combination of Ctrl+Shift+Tab has the key sequence ctrl+shift+\t. On a United States English keyboard, since the combination of Ctrl+Shift+, has the key sequence ctrl+< (Shift+, inserts a <), Textadept recognizes the key binding as Ctrl+<. This allows key bindings to be language and layout agnostic. For key values greater than 255, Textadept uses the keys.KEYSYMS lookup table. Therefore, Ctrl+Right Arrow has the key sequence ctrl+right. Uncommenting the print() statements in core/keys.lua causes Textadept to print key sequences to standard out (stdout) for inspection.

Commands

A command bound to a key sequence is simply a Lua function. For example:

keys['ctrl+n'] = buffer.new
keys['ctrl+z'] = buffer.undo
keys['ctrl+u'] = function() io.quick_open(_USERHOME) end

Textadept handles buffer and view references properly in static contexts.

Modes

Modes are groups of key bindings such that when a key mode is active, Textadept ignores all key bindings defined outside the mode until the mode is unset. Here is a simple vi mode example:

keys.command_mode = {
	['h'] = buffer.char_left,
	['j'] = buffer.line_up,
	['k'] = buffer.line_down,
	['l'] = buffer.char_right,
	['i'] = function()
		keys.mode = nil
		ui.statusbar_text = 'INSERT MODE'
	end
}
keys['esc'] = function() keys.mode = 'command_mode' end
events.connect(events.UPDATE_UI, function()
	if keys.mode == 'command_mode' then return end
	ui.statusbar_text = 'INSERT MODE'
end)
keys.mode = 'command_mode' -- default mode

Warning: When creating a mode, be sure to define a way to exit the mode, otherwise you will probably have to restart Textadept.

Key Chains

Key chains are a powerful concept. They allow you to assign multiple key bindings to one key sequence. By default, the Esc key cancels a key chain, but you can redefine it via keys.CLEAR. An example key chain looks like:

keys['alt+a'] = {
	a = function1,
	b = function2,
	c = {...}
}

Fields defined by keys

keys.CLEAR

The key that clears the current key chain. It cannot be part of a key chain. The default value is 'esc' for the Esc key.

keys.KEYSYMS <table>

Lookup table for string representations of key codes higher than 255. Key codes can be identified by temporarily uncommenting the print() statements in core/keys.lua. Recognized codes are: esc, \b, \t, \n, down, up, left, right, home, end, pgup, pgdn, del, ins, and f1-f12. The GUI version also recognizes: menu, kpenter, kphome, kpend, kpleft, kpup, kpright, kpdown, kppgup, kppgdn, kpmul, kpadd, kpsub, kpdiv, kpdec, and kp0-kp9.

keys.keychain <table>

The current chain of key sequences. (Read-only.)

keys.mode

The current key mode. When non-nil, all key bindings defined outside of keys[mode] are ignored. The default value is nil.

The lexer Module

Lexes Scintilla documents and source code with Lua and LPeg.

Writing Lua Lexers

Lexers recognize and tag elements of source code for syntax highlighting. Scintilla (the editing component behind Textadept and SciTE) traditionally uses static, compiled C++ lexers which are notoriously difficult to create and/or extend. On the other hand, Lua makes it easy to to rapidly create new lexers, extend existing ones, and embed lexers within one another. Lua lexers tend to be more readable than C++ lexers too.

While lexers can be written in plain Lua, Scintillua prefers using Parsing Expression Grammars, or PEGs, composed with the Lua LPeg library. As a result, this document is devoted to writing LPeg lexers. The following table comes from the LPeg documentation and summarizes all you need to know about constructing basic LPeg patterns. This module provides convenience functions for creating and working with other more advanced patterns and concepts.

Operator Description
lpeg.P(string) Matches string literally.
lpeg.P(n) Matches exactly n number of characters.
lpeg.S(string) Matches any character in set string.
lpeg.R("xy") Matches any character between range x and y.
patt^n Matches at least n repetitions of patt.
patt^-n Matches at most n repetitions of patt.
patt1 * patt2 Matches patt1 followed by patt2.
patt1 + patt2 Matches patt1 or patt2 (ordered choice).
patt1 - patt2 Matches patt1 if patt2 does not also match.
-patt Matches if patt does not match, consuming no input.
#patt Matches patt but consumes no input.

The first part of this document deals with rapidly constructing a simple lexer. The next part deals with more advanced techniques, such as embedding lexers within one another. Following that is a discussion about code folding, or being able to tell Scintilla which code blocks are “foldable” (temporarily hideable from view). After that are instructions on how to use Lua lexers with the aforementioned Textadept and SciTE editors. Finally there are comments on lexer performance and limitations.

Lexer Basics

The lexers/ directory contains all of Scintillua’s Lua lexers, including any new ones you write. Before attempting to write one from scratch though, first determine if your programming language is similar to any of the 100+ languages supported. If so, you may be able to copy and modify, or inherit from that lexer, saving some time and effort. The filename of your lexer should be the name of your programming language in lower case followed by a .lua extension. For example, a new Lua lexer has the name lua.lua.

New Lexer Template

There is a lexers/template.txt file that contains a simple template for a new lexer. Feel free to use it, replacing the ‘?’ with the name of your lexer. Consider this snippet from the template:

-- ? LPeg lexer.

local lexer = lexer
local P, S = lpeg.P, lpeg.S

local lex = lexer.new(...)

[... lexer rules ...]

-- Identifier.
local identifier = lex:tag(lexer.IDENTIFIER, lexer.word)
lex:add_rule('identifier', identifier)

[... more lexer rules ...]

return lex

The first line of code is a Lua convention to store a global variable into a local variable for quick access. The second line simply defines often used convenience variables. The third and last lines define and return the lexer object Scintillua uses; they are very important and must be part of every lexer. Note the ... passed to lexer.new() is literal: the lexer will assume the name of its filename or an alternative name specified by lexer.load() in embedded lexer applications. The fourth line uses something called a “tag”, an essential component of lexers. You will learn about tags shortly. The fifth line defines a lexer grammar rule, which you will learn about later. (Be aware that it is common practice to combine these two lines for short rules.) Note, however, the local prefix in front of variables, which is needed so-as not to affect Lua’s global environment. All in all, this is a minimal, working lexer that you can build on.

Tags

Take a moment to think about your programming language’s structure. What kind of key elements does it have? Most languages have elements like keywords, strings, and comments. The lexer’s job is to break down source code into these elements and “tag” them for syntax highlighting. Therefore, tags are an essential component of lexers. It is up to you how specific your lexer is when it comes to tagging elements. Perhaps only distinguishing between keywords and identifiers is necessary, or maybe recognizing constants and built-in functions, methods, or libraries is desirable. The Lua lexer, for example, tags the following elements: keywords, functions, constants, identifiers, strings, comments, numbers, labels, attributes, and operators. Even though functions and constants are subsets of identifiers, Lua programmers find it helpful for the lexer to distinguish between them all. It is perfectly acceptable to just recognize keywords and identifiers.

In a lexer, LPeg patterns that match particular sequences of characters are tagged with a tag name using the the lexer.tag() function. Let us examine the “identifier” tag used in the template shown earlier:

local identifier = lex:tag(lexer.IDENTIFIER, lexer.word)

At first glance, the first argument does not appear to be a string name and the second argument does not appear to be an LPeg pattern. Perhaps you expected something like:

lex:tag('identifier', (lpeg.R('AZ', 'az')  + '_') * (lpeg.R('AZ', 'az', '09') + '_')^0)

The lexer module actually provides a convenient list of common tag names and common LPeg patterns for you to use. Tag names for programming languages include (but are not limited to) lexer.DEFAULT, lexer.COMMENT, lexer.STRING, lexer.NUMBER, lexer.KEYWORD, lexer.IDENTIFIER, lexer.OPERATOR, lexer.ERROR, lexer.PREPROCESSOR, lexer.CONSTANT, lexer.CONSTANT_BUILTIN, lexer.VARIABLE, lexer.VARIABLE_BUILTIN, lexer.FUNCTION, lexer.FUNCTION_BUILTIN, lexer.FUNCTION_METHOD, lexer.CLASS, lexer.TYPE, lexer.LABEL, lexer.REGEX, lexer.EMBEDDED, and lexer.ANNOTATION. Tag names for markup languages include (but are not limited to) lexer.TAG, lexer.ATTRIBUTE, lexer.HEADING, lexer.BOLD, lexer.ITALIC, lexer.UNDERLINE, lexer.CODE, lexer.LINK, lexer.REFERENCE, and lexer.LIST. Patterns include lexer.any, lexer.alpha, lexer.digit, lexer.alnum, lexer.lower, lexer.upper, lexer.xdigit, lexer.graph, lexer.punct, lexer.space, lexer.newline, lexer.nonnewline, lexer.dec_num, lexer.hex_num, lexer.oct_num, lexer.bin_num, lexer.integer, lexer.float, lexer.number, and lexer.word. You may use your own tag names if none of the above fit your language, but an advantage to using predefined tag names is that the language elements your lexer recognizes will inherit any universal syntax highlighting color theme that your editor uses. You can also “subclass” existing tag names by appending a ‘.subclass’ string to them. For example, the HTML lexer tags unknown tags as lexer.TAG .. '.unknown'. This gives editors the opportunity to style those subclassed tags in a different way than normal tags, or fall back to styling them as normal tags.

Example Tags

So, how might you recognize and tag elements like keywords, comments, and strings? Here are some examples.

Keywords

Instead of matching n keywords with n P('keyword_n') ordered choices, use one of of the following methods:

  1. Use the convenience function lexer.word_match() optionally coupled with lexer.set_word_list(). It is much easier and more efficient to write word matches like:

    local keyword = lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD))
[...]
lex:set_word_list(lexer.KEYWORD, {
  'keyword_1', 'keyword_2', ..., 'keyword_n'
})

local case_insensitive_word = lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD, true))
[...]
lex:set_word_list(lexer.KEYWORD, {
  'KEYWORD_1', 'keyword_2', ..., 'KEYword_n'
})

local hyphenated_keyword = lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD))
[...]
lex:set_word_list(lexer.KEYWORD, {
  'keyword-1', 'keyword-2', ..., 'keyword-n'
})

    The benefit of using this method is that other lexers that inherit from, embed, or embed themselves into your lexer can set, replace, or extend these word lists. For example, the TypeScript lexer inherits from JavaScript, but extends JavaScript’s keyword and type lists with more options.

    This method also allows applications that use your lexer to extend or replace your word lists. For example, the Lua lexer includes keywords and functions for the latest version of Lua (5.4 at the time of writing). However, editors using that lexer might want to use keywords from Lua version 5.1, which is still quite popular.

    Note that calling lex:set_word_list() is completely optional. Your lexer is allowed to expect the editor using it to supply word lists. Scintilla-based editors can do so via Scintilla’s ILexer5 interface.

  2. Use the lexer-agnostic form of lexer.word_match():

    local keyword = lex:tag(lexer.KEYWORD, lexer.word_match{
  'keyword_1', 'keyword_2', ..., 'keyword_n'
})

local case_insensitive_keyword = lex:tag(lexer.KEYWORD, lexer.word_match({
  'KEYWORD_1', 'keyword_2', ..., 'KEYword_n'
}, true))

local hyphened_keyword = lex:tag(lexer.KEYWORD, lexer.word_match{
  'keyword-1', 'keyword-2', ..., 'keyword-n'
})

    For short keyword lists, you can use a single string of words. For example:

    local keyword = lex:tag(lexer.KEYWORD, lexer.word_match('key_1 key_2 ... key_n'))

    You can use this method for static word lists that do not change, or where it does not make sense to allow applications or other lexers to extend or replace a word list.

Comments

Line-style comments with a prefix character(s) are easy to express:

local shell_comment = lex:tag(lexer.COMMENT, lexer.to_eol('#'))
local c_line_comment = lex:tag(lexer.COMMENT, lexer.to_eol('//', true))

The comments above start with a ‘#’ or “//” and go to the end of the line (EOL). The second comment recognizes the next line also as a comment if the current line ends with a ‘' escape character.

C-style “block” comments with a start and end delimiter are also easy to express:

local c_comment = lex:tag(lexer.COMMENT, lexer.range('/*', '*/'))

This comment starts with a “/*” sequence and contains anything up to and including an ending “*/” sequence. The ending “*/” is optional so the lexer can recognize unfinished comments as comments and highlight them properly.

Strings

Most programming languages allow escape sequences in strings such that a sequence like “\"” in a double-quoted string indicates that the ‘"’ is not the end of the string. lexer.range() handles escapes inherently.

local dq_str = lexer.range('"')
local sq_str = lexer.range("'")
local string = lex:tag(lexer.STRING, dq_str + sq_str)

In this case, the lexer treats ‘' as an escape character in a string sequence.

Numbers

Most programming languages have the same format for integers and floats, so it might be as simple as using a predefined LPeg pattern:

local number = lex:tag(lexer.NUMBER, lexer.number)

However, some languages allow postfix characters on integers.

local integer = P('-')^-1 * (lexer.dec_num * S('lL')^-1)
local number = lex:tag(lexer.NUMBER, lexer.float + lexer.hex_num + integer)

Other languages allow separaters within numbers for better readability.

local number = lex:tag(lexer.NUMBER, lexer.number_('_')) -- recognize 1_000_000

Your language may need other tweaks, but it is up to you how fine-grained you want your highlighting to be. After all, you are not writing a compiler or interpreter!

Rules

Programming languages have grammars, which specify valid syntactic structure. For example, comments usually cannot appear within a string, and valid identifiers (like variable names) cannot be keywords. In Lua lexers, grammars consist of LPeg pattern rules, many of which are tagged. Recall from the lexer template the lexer.add_rule() call, which adds a rule to the lexer’s grammar:

lex:add_rule('identifier', identifier)

Each rule has an associated name, but rule names are completely arbitrary and serve only to identify and distinguish between different rules. Rule order is important: if text does not match the first rule added to the grammar, the lexer tries to match the second rule added, and so on. Right now this lexer simply matches identifiers under a rule named “identifier”.

To illustrate the importance of rule order, here is an example of a simplified Lua lexer:

lex:add_rule('keyword', lex:tag(lexer.KEYWORD, ...))
lex:add_rule('identifier', lex:tag(lexer.IDENTIFIER, ...))
lex:add_rule('string', lex:tag(lexer.STRING, ...))
lex:add_rule('comment', lex:tag(lexer.COMMENT, ...))
lex:add_rule('number', lex:tag(lexer.NUMBER, ...))
lex:add_rule('label', lex:tag(lexer.LABEL, ...))
lex:add_rule('operator', lex:tag(lexer.OPERATOR, ...))

Notice how identifiers come after keywords. In Lua, as with most programming languages, the characters allowed in keywords and identifiers are in the same set (alphanumerics plus underscores). If the lexer added the “identifier” rule before the “keyword” rule, all keywords would match identifiers and thus would be incorrectly tagged (and likewise incorrectly highlighted) as identifiers instead of keywords. The same idea applies to function names, constants, etc. that you may want to distinguish between: their rules should come before identifiers.

So what about text that does not match any rules? For example in Lua, the ‘!’ character is meaningless outside a string or comment. Normally the lexer skips over such text. If instead you want to highlight these “syntax errors”, add a final rule:

lex:add_rule('keyword', keyword)
...
lex:add_rule('error', lex:tag(lexer.ERROR, lexer.any))

This identifies and tags any character not matched by an existing rule as a lexer.ERROR.

Even though the rules defined in the examples above contain a single tagged pattern, rules may consist of multiple tagged patterns. For example, the rule for an HTML tag could consist of a tagged tag followed by an arbitrary number of tagged attributes, separated by whitespace. This allows the lexer to produce all tags separately, but in a single, convenient rule. That rule might look something like this:

local ws = lex:get_rule('whitespace') -- predefined rule for all lexers
lex:add_rule('tag', tag_start * (ws * attributes)^0 * tag_end^-1)

Note however that lexers with complex rules like these are more prone to lose track of their state, especially if they span multiple lines.

Summary

Lexers primarily consist of tagged patterns and grammar rules. These patterns match language elements like keywords, comments, and strings, and rules dictate the order in which patterns are matched. At your disposal are a number of convenience patterns and functions for rapidly creating a lexer. If you choose to use predefined tag names (or perhaps even subclassed names) for your patterns, you do not have to update your editor’s theme to specify how to syntax-highlight those patterns. Your language’s elements will inherit the default syntax highlighting color theme your editor uses.

Advanced Techniques

Line Lexers

By default, lexers match the arbitrary chunks of text passed to them by Scintilla. These chunks may be a full document, only the visible part of a document, or even just portions of lines. Some lexers need to match whole lines. For example, a lexer for the output of a file “diff” needs to know if the line started with a ‘+’ or ‘-‘ and then style the entire line accordingly. To indicate that your lexer matches by line, create the lexer with an extra parameter:

local lex = lexer.new(..., {lex_by_line = true})

Now the input text for the lexer is a single line at a time. Keep in mind that line lexers do not have the ability to look ahead to subsequent lines.

Embedded Lexers

Scintillua lexers embed within one another very easily, requiring minimal effort. In the following sections, the lexer being embedded is called the “child” lexer and the lexer a child is being embedded in is called the “parent”. For example, consider an HTML lexer and a CSS lexer. Either lexer stands alone for styling their respective HTML and CSS files. However, CSS can be embedded inside HTML. In this specific case, the CSS lexer is the “child” lexer with the HTML lexer being the “parent”. Now consider an HTML lexer and a PHP lexer. This sounds a lot like the case with CSS, but there is a subtle difference: PHP embeds itself into HTML while CSS is embedded in HTML. This fundamental difference results in two types of embedded lexers: a parent lexer that embeds other child lexers in it (like HTML embedding CSS), and a child lexer that embeds itself into a parent lexer (like PHP embedding itself in HTML).

Parent Lexer

Before embedding a child lexer into a parent lexer, the parent lexer needs to load the child lexer. This is done with the lexer.load() function. For example, loading the CSS lexer within the HTML lexer looks like:

local css = lexer.load('css')

The next part of the embedding process is telling the parent lexer when to switch over to the child lexer and when to switch back. The lexer refers to these indications as the “start rule” and “end rule”, respectively, and are just LPeg patterns. Continuing with the HTML/CSS example, the transition from HTML to CSS is when the lexer encounters a “style” tag with a “type” attribute whose value is “text/css”:

local css_tag = P('<style') * P(function(input, index)
  if input:find('^[^>]+type="text/css"', index) then return true end
end)

This pattern looks for the beginning of a “style” tag and searches its attribute list for the text “type="text/css"”. (In this simplified example, the Lua pattern does not consider whitespace between the ‘=’ nor does it consider that using single quotes is valid.) If there is a match, the functional pattern returns true. However, we ultimately want to style the “style” tag as an HTML tag, so the actual start rule looks like this:

local css_start_rule = #css_tag * tag

Now that the parent knows when to switch to the child, it needs to know when to switch back. In the case of HTML/CSS, the switch back occurs when the lexer encounters an ending “style” tag, though the lexer should still style the tag as an HTML tag:

local css_end_rule = #P('</style>') * tag

Once the parent loads the child lexer and defines the child’s start and end rules, it embeds the child with the lexer.embed() function:

lex:embed(css, css_start_rule, css_end_rule)
Child Lexer

The process for instructing a child lexer to embed itself into a parent is very similar to embedding a child into a parent: first, load the parent lexer into the child lexer with the lexer.load() function and then create start and end rules for the child lexer. However, in this case, call lexer.embed() with switched arguments. For example, in the PHP lexer:

local html = lexer.load('html')
local php_start_rule = lex:tag('php_tag', '<?php' * lexer.space)
local php_end_rule = lex:tag('php_tag', '?>')
html:embed(lex, php_start_rule, php_end_rule)

Note that the use of a ‘php_tag’ tag will require the editor using the lexer to specify how to highlight text with that tag. In order to avoid this, you could use the lexer.PREPROCESSOR tag instead.

Lexers with Complex State

A vast majority of lexers are not stateful and can operate on any chunk of text in a document. However, there may be rare cases where a lexer does need to keep track of some sort of persistent state. Rather than using lpeg.P function patterns that set state variables, it is recommended to make use of Scintilla’s built-in, per-line state integers via lexer.line_state. It was designed to accommodate up to 32 bit-flags for tracking state. lexer.line_from_position() will return the line for any position given to an lpeg.P function pattern. (Any positions derived from that position argument will also work.)

Writing stateful lexers is beyond the scope of this document.

Code Folding

When reading source code, it is occasionally helpful to temporarily hide blocks of code like functions, classes, comments, etc. This is the concept of “folding”. In the Textadept and SciTE editors for example, little indicators in the editor margins appear next to code that can be folded at places called “fold points”. When the user clicks an indicator, the editor hides the code associated with the indicator until the user clicks the indicator again. The lexer specifies these fold points and what code exactly to fold.

The fold points for most languages occur on keywords or character sequences. Examples of fold keywords are “if” and “end” in Lua and examples of fold character sequences are ‘{‘, ‘}’, “/*”, and “*/” in C for code block and comment delimiters, respectively. However, these fold points cannot occur just anywhere. For example, lexers should not recognize fold keywords that appear within strings or comments. The lexer.add_fold_point() function allows you to conveniently define fold points with such granularity. For example, consider C:

lex:add_fold_point(lexer.OPERATOR, '{', '}')
lex:add_fold_point(lexer.COMMENT, '/*', '*/')

The first assignment states that any ‘{‘ or ‘}’ that the lexer tagged as an lexer.OPERATOR is a fold point. Likewise, the second assignment states that any “/*” or “*/” that the lexer tagged as part of a lexer.COMMENT is a fold point. The lexer does not consider any occurrences of these characters outside their tagged elements (such as in a string) as fold points. How do you specify fold keywords? Here is an example for Lua:

lex:add_fold_point(lexer.KEYWORD, 'if', 'end')
lex:add_fold_point(lexer.KEYWORD, 'do', 'end')
lex:add_fold_point(lexer.KEYWORD, 'function', 'end')
lex:add_fold_point(lexer.KEYWORD, 'repeat', 'until')

If your lexer has case-insensitive keywords as fold points, simply add a case_insensitive_fold_points = true option to lexer.new(), and specify keywords in lower case.

If your lexer needs to do some additional processing in order to determine if a tagged element is a fold point, pass a function to lex:add_fold_point() that returns an integer. A return value of 1 indicates the element is a beginning fold point and a return value of -1 indicates the element is an ending fold point. A return value of 0 indicates the element is not a fold point. For example:

local function fold_strange_element(text, pos, line, s, symbol)
  if ... then
    return 1 -- beginning fold point
  elseif ... then
    return -1 -- ending fold point
  end
  return 0
end

lex:add_fold_point('strange_element', '|', fold_strange_element)

Any time the lexer encounters a ‘|’ that is tagged as a “strange_element”, it calls the fold_strange_element function to determine if ‘|’ is a fold point. The lexer calls these functions with the following arguments: the text to identify fold points in, the beginning position of the current line in the text to fold, the current line’s text, the position in the current line the fold point text starts at, and the fold point text itself.

Fold by Indentation

Some languages have significant whitespace and/or no delimiters that indicate fold points. If your lexer falls into this category and you would like to mark fold points based on changes in indentation, create the lexer with a fold_by_indentation = true option:

local lex = lexer.new(..., {fold_by_indentation = true})

Using Lexers

Textadept

Place your lexer in your ~/.textadept/lexers/ directory so you do not overwrite it when upgrading Textadept. Also, lexers in this directory override default lexers. Thus, Textadept loads a user lua lexer instead of the default lua lexer. This is convenient for tweaking a default lexer to your liking. Then add a file extension for your lexer if necessary.

SciTE

Create a .properties file for your lexer and import it in either your SciTEUser.properties or SciTEGlobal.properties. The contents of the .properties file should contain:

file.patterns.[lexer_name]=[file_patterns]
lexer.$(file.patterns.[lexer_name])=scintillua.[lexer_name]
keywords.$(file.patterns.[lexer_name])=scintillua
keywords2.$(file.patterns.[lexer_name])=scintillua
...
keywords9.$(file.patterns.[lexer_name])=scintillua

where [lexer_name] is the name of your lexer (minus the .lua extension) and [file_patterns] is a set of file extensions to use your lexer for. The keyword settings are only needed if another SciTE properties file has defined keyword sets for [file_patterns]. The scintillua keyword setting instructs Scintillua to use the keyword sets defined within the lexer. You can override a lexer’s keyword set(s) by specifying your own in the same order that the lexer calls lex:set_word_list(). For example, the Lua lexer’s first set of keywords is for reserved words, the second is for built-in global functions, the third is for library functions, the fourth is for built-in global constants, and the fifth is for library constants.

SciTE assigns styles to tag names in order to perform syntax highlighting. Since the set of tag names used for a given language changes, your .properties file should specify styles for tag names instead of style numbers. For example:

scintillua.styles.my_tag=$(scintillua.styles.keyword),bold

Migrating Legacy Lexers

Legacy lexers are of the form:

local lexer = require('lexer')
local token, word_match = lexer.token, lexer.word_match
local P, S = lpeg.P, lpeg.S

local lex = lexer.new('?')

-- Whitespace.
lex:add_rule('whitespace', token(lexer.WHITESPACE, lexer.space^1))

-- Keywords.
lex:add_rule('keyword', token(lexer.KEYWORD, word_match{
  [...]
}))

[... other rule definitions ...]

-- Custom.
lex:add_rule('custom_rule', token('custom_token', ...))
lex:add_style('custom_token', lexer.styles.keyword .. {bold = true})

-- Fold points.
lex:add_fold_point(lexer.OPERATOR, '{', '}')

return lex

While Scintillua will mostly handle such legacy lexers just fine without any changes, it is recommended that you migrate yours. The migration process is fairly straightforward:

  1. lexer exists in the default lexer environment, so require('lexer') should be replaced by simply lexer. (Keep in mind local lexer = lexer is a Lua idiom.)
  2. Every lexer created using lexer.new() should no longer specify a lexer name by string, but should instead use ... (three dots), which evaluates to the lexer’s filename or alternative name in embedded lexer applications.
  3. Every lexer created using lexer.new() now includes a rule to match whitespace. Unless your lexer has significant whitespace, you can remove your legacy lexer’s whitespace token and rule. Otherwise, your defined whitespace rule will replace the default one.
  4. The concept of tokens has been replaced with tags. Instead of calling a token() function, call lex:tag() instead.
  5. Lexers now support replaceable word lists. Instead of calling lexer.word_match() with large word lists, call it as an instance method with an identifier string (typically something like lexer.KEYWORD). Then at the end of the lexer (before return lex), call lex:set_word_list() with the same identifier and the usual list of words to match. This allows users of your lexer to call lex:set_word_list() with their own set of words should they wish to.
  6. Lexers no longer specify styling information. Remove any calls to lex:add_style(). You may need to add styling information for custom tags to your editor’s theme.
  7. lexer.last_char_includes() has been deprecated in favor of the new lexer.after_set(). Use the character set and pattern as arguments to that new function.

As an example, consider the following sample legacy lexer:

local lexer = require('lexer')
local token, word_match = lexer.token, lexer.word_match
local P, S = lpeg.P, lpeg.S

local lex = lexer.new('legacy')

lex:add_rule('whitespace', token(lexer.WHITESPACE, lexer.space^1))
lex:add_rule('keyword', token(lexer.KEYWORD, word_match('foo bar baz')))
lex:add_rule('custom', token('custom', 'quux'))
lex:add_style('custom', lexer.styles.keyword .. {bold = true})
lex:add_rule('identifier', token(lexer.IDENTIFIER, lexer.word))
lex:add_rule('string', token(lexer.STRING, lexer.range('"')))
lex:add_rule('comment', token(lexer.COMMENT, lexer.to_eol('#')))
lex:add_rule('number', token(lexer.NUMBER, lexer.number))
lex:add_rule('operator', token(lexer.OPERATOR, S('+-*/%^=<>,.()[]{}')))

lex:add_fold_point(lexer.OPERATOR, '{', '}')

return lex

Following the migration steps would yield:

local lexer = lexer
local P, S = lpeg.P, lpeg.S

local lex = lexer.new(...)

lex:add_rule('keyword', lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD)))
lex:add_rule('custom', lex:tag('custom', 'quux'))
lex:add_rule('identifier', lex:tag(lexer.IDENTIFIER, lexer.word))
lex:add_rule('string', lex:tag(lexer.STRING, lexer.range('"')))
lex:add_rule('comment', lex:tag(lexer.COMMENT, lexer.to_eol('#')))
lex:add_rule('number', lex:tag(lexer.NUMBER, lexer.number))
lex:add_rule('operator', lex:tag(lexer.OPERATOR, S('+-*/%^=<>,.()[]{}')))

lex:add_fold_point(lexer.OPERATOR, '{', '}')

lex:set_word_list(lexer.KEYWORD, {'foo', 'bar', 'baz'})

return lex

Any editors using this lexer would have to add a style for the ‘custom’ tag.

Considerations

Performance

There might be some slight overhead when initializing a lexer, but loading a file from disk into Scintilla is usually more expensive. Actually painting the syntax highlighted text to the screen is often more expensive than the lexing operation. On modern computer systems, I see no difference in speed between Lua lexers and Scintilla’s C++ ones. Optimize lexers for speed by re-arranging lexer.add_rule() calls so that the most common rules match first. Do keep in mind that order matters for similar rules.

In some cases, folding may be far more expensive than lexing, particularly in lexers with a lot of potential fold points. If your lexer is exhibiting signs of slowness, try disabling folding in your text editor first. If that speeds things up, you can try reducing the number of fold points you added, overriding lexer.fold() with your own implementation, or simply eliminating folding support from your lexer.

Limitations

Embedded preprocessor languages like PHP cannot completely embed themselves into their parent languages because the parent’s tagged patterns do not support start and end rules. This mostly goes unnoticed, but code like

<div id="<?php echo $id; ?>">

will not style correctly. Also, these types of languages cannot currently embed themselves into their parent’s child languages either.

A language cannot embed itself into something like an interpolated string because it is possible that if lexing starts within the embedded entity, it will not be detected as such, so a child to parent transition cannot happen. For example, the following Ruby code will not style correctly:

sum = "1 + 2 = #{1 + 2}"

Also, there is the potential for recursion for languages embedding themselves within themselves.

Troubleshooting

Errors in lexers can be tricky to debug. Lexers print Lua errors to io.stderr and _G.print() statements to io.stdout. Running your editor from a terminal is the easiest way to see errors as they occur.

Risks

Poorly written lexers have the ability to crash Scintilla (and thus its containing application), so unsaved data might be lost. However, I have only observed these crashes in early lexer development, when syntax errors or pattern errors are present. Once the lexer actually starts processing and tagging text (either correctly or incorrectly, it does not matter), I have not observed any crashes.

Acknowledgements

Thanks to Peter Odding for his lexer post on the Lua mailing list that provided inspiration, and thanks to Roberto Ierusalimschy for LPeg.

Fields defined by lexer

lexer.ANNOTATION

The tag name for annotation elements.

lexer.ATTRIBUTE

The tag name for function attribute elements, typically in markup.

lexer.BOLD

The tag name for bold elements, typically in markup.

lexer.CLASS

The tag name for class elements.

lexer.CODE

The tag name for code elements, typically in markup.

lexer.COMMENT

The tag name for comment elements.

lexer.CONSTANT

The tag name for constant elements.

lexer.CONSTANT_BUILTIN

The tag name for builtin constant elements.

lexer.DEFAULT

The tag name for default elements.

lexer.EMBEDDED

The tag name for embedded elements.

lexer.ERROR

The tag name for error elements.

lexer.FOLD_BASE

The initial (root) fold level.

lexer.FOLD_BLANK

Flag indicating that the line is blank.

lexer.FOLD_HEADER

Flag indicating the line is fold point.

lexer.FUNCTION

The tag name for function elements.

lexer.FUNCTION_BUILTIN

The tag name for builtin function elements.

lexer.FUNCTION_METHOD

The tag name for function method elements.

lexer.HEADING

The tag name for heading elements, typically in markup.

lexer.IDENTIFIER

The tag name for identifier elements.

lexer.ITALIC

The tag name for builtin italic elements, typically in markup.

lexer.KEYWORD

The tag name for keyword elements.

lexer.LABEL

The tag name for label elements.

The tag name for link elements, typically in markup.

lexer.LIST

The tag name for list item elements, typically in markup.

lexer.NUMBER

The tag name for number elements.

lexer.OPERATOR

The tag name for operator elements.

lexer.PREPROCESSOR

The tag name for preprocessor elements.

lexer.REFERENCE

The tag name for reference elements, typically in markup.

lexer.REGEX

The tag name for regex elements.

lexer.STRING

The tag name for string elements.

lexer.TAG

The tag name for function tag elements, typically in markup.

lexer.TYPE

The tag name for type elements.

lexer.UNDERLINE

The tag name for underlined elements, typically in markup.

lexer.VARIABLE

The tag name for variable elements.

lexer.VARIABLE_BUILTIN

The tag name for builtin variable elements.

lexer.alnum

A pattern that matches any alphanumeric character (‘A’-‘Z’, ‘a’-‘z’, ‘0’-‘9’).

lexer.alpha

A pattern that matches any alphabetic character (‘A’-‘Z’, ‘a’-‘z’).

lexer.any

A pattern that matches any single character.

lexer.bin_num

A pattern that matches a binary number.

lexer.dec_num

A pattern that matches a decimal number.

lexer.detect_extensions <table>

Map of file extensions, without the ‘.’ prefix, to their associated lexer names. This map has precedence over Scintillua’s built-in map.

See also:

lexer.detect_patterns <table>

Map of line patterns to their associated lexer names. These are Lua string patterns, not LPeg patterns. This map has precedence over Scintillua’s built-in map.

See also:

lexer.digit

A pattern that matches any digit (‘0’-‘9’).

lexer.float

A pattern that matches a floating point number.

lexer.fold_level <table>

Table of fold level bit-masks for line numbers starting from 1. (Read-only) Fold level masks are composed of an integer level combined with any of the following bits:

lexer.graph

A pattern that matches any graphical character (‘!’ to ‘~’).

lexer.hex_num

A pattern that matches a hexadecimal number.

lexer.indent_amount <table>

Table of indentation amounts in character columns, for line numbers starting from

  1. (Read-only)

lexer.integer

A pattern that matches either a decimal, hexadecimal, octal, or binary number.

lexer.line_state <table>

Table of integer line states for line numbers starting from 1. Line states can be used by lexers for keeping track of persistent states. For example, the output lexer uses this to mark lines that have warnings or errors.

lexer.lower

A pattern that matches any lower case character (‘a’-‘z’).

lexer.newline

A pattern that matches a sequence of end of line characters.

lexer.nonnewline

A pattern that matches any single, non-newline character.

lexer.number

A pattern that matches a typical number, either a floating point, decimal, hexadecimal, octal, or binary number.

lexer.oct_num

A pattern that matches an octal number.

lexer.property <table>

Map of key-value string pairs.

lexer.property_int <table>

Map of key-value pairs with values interpreted as numbers, or 0 if not found. (Read-only)

lexer.punct

A pattern that matches any punctuation character (‘!’ to ‘/’, ‘:’ to ‘@’, ‘[’ to ‘’’, ‘{‘ to ‘~’).

lexer.space

A pattern that matches any whitespace character (‘\t’, ‘\v’, ‘\f’, ‘\n’, ‘\r’, space).

lexer.style_at <table>

Table of style names at positions in the buffer starting from 1. (Read-only)

lexer.upper

A pattern that matches any upper case character (‘A’-‘Z’).

lexer.word

A pattern that matches a typical word. Words begin with a letter or underscore and consist of alphanumeric and underscore characters.

lexer.xdigit

A pattern that matches any hexadecimal digit (‘0’-‘9’, ‘A’-‘F’, ‘a’-‘f’).

Functions defined by lexer

lexer.add_fold_point(lexer, tag_name, start_symbol, end_symbol)

Adds to lexer lexer a fold point whose beginning and end points are tagged with string tag_name tags and have string content start_symbol and end_symbol, respectively. In the event that start_symbol may or may not be a fold point depending on context, and that additional processing is required, end_symbol may be a function that ultimately returns 1 (indicating a beginning fold point), -1 (indicating an ending fold point), or 0 (indicating no fold point). That function is passed the following arguments:

Parameters:

Usage:

lexer.add_rule(lexer, id, rule)

Adds pattern rule identified by string id to the ordered list of rules for lexer lexer.

Parameters:

See also:

lexer.after_set(set, patt, skip)

Creates and returns a pattern that matches pattern patt only when it comes after one of the characters in string set (or when there are no characters behind patt), skipping over any characters in string skip, which is whitespace by default.

Parameters:

Usage:

lexer.bin_num_(c)

Returns a pattern that matches a binary number, whose digits may be separated by character c.

Parameters:

lexer.dec_num_(c)

Returns a pattern that matches a decimal number, whose digits may be separated by character c.

Parameters:

lexer.detect([filename[, line]])

Returns the name of the lexer often associated with filename filename and/or content line line.

Parameters:

Return:

See also:

lexer.embed(lexer, child, start_rule, end_rule)

Embeds child lexer child in parent lexer lexer using patterns start_rule and end_rule, which signal the beginning and end of the embedded lexer, respectively.

Parameters:

Usage:

lexer.float_(c)

Returns a pattern that matches a floating point number, whose digits may be separated by character c.

Parameters:

lexer.fold(lexer, text, start_line, start_level)

Determines fold points in a chunk of text text using lexer lexer, returning a table of fold levels associated with line numbers. text starts on line number start_line with a beginning fold level of start_level in the buffer.

Parameters:

Return:

lexer.get_rule(lexer, id)

Returns the rule identified by string id.

Parameters:

Return:

lexer.hex_num_(c)

Returns a pattern that matches a hexadecimal number, whose digits may be separated by character c.

Parameters:

lexer.integer_(c)

Returns a pattern that matches either a decimal, hexadecimal, octal, or binary number, whose digits may be separated by character c.

Parameters:

lexer.lex(lexer, text, init_style)

Lexes a chunk of text text (that has an initial style number of init_style) using lexer lexer, returning a list of tag names and positions.

Parameters:

Return:

lexer.line_from_position(pos)

Returns the line number (starting from 1) of the line that contains position pos, which starts from 1.

Parameters:

Return:

lexer.load(name[, alt_name])

Initializes or loads and then returns the lexer of string name name. Scintilla calls this function in order to load a lexer. Parent lexers also call this function in order to load child lexers and vice-versa. The user calls this function in order to load a lexer when using Scintillua as a Lua library.

Parameters:

Return:

lexer.modify_rule(lexer, id, rule)

Replaces in lexer lexer the existing rule identified by string id with pattern rule.

Parameters:

lexer.names([path])

Returns a list of all known lexer names. This function is not available to lexers and requires the LuaFileSystem (lfs) module to be available.

Parameters:

Return:

lexer.new(name, opts)

Creates a returns a new lexer with the given name.

Parameters:

Usage:

lexer.number_(c)

Returns a pattern that matches a typical number, either a floating point, decimal, hexadecimal, octal, or binary number, and whose digits may be separated by character c.

Parameters:

lexer.oct_num_(c)

Returns a pattern that matches an octal number, whose digits may be separated by character c.

Parameters:

lexer.range(s[, e=s[, single_line=false[, escapes[, balanced=false]]]])

Creates and returns a pattern that matches a range of text bounded by strings or patterns s and e. This is a convenience function for matching more complicated ranges like strings with escape characters, balanced parentheses, and block comments (nested or not). e is optional and defaults to s. single_line indicates whether or not the range must be on a single line; escapes indicates whether or not to allow ‘' as an escape character; and balanced indicates whether or not to handle balanced ranges like parentheses, and requires s and e to be different.

Parameters:

Usage:

Return:

lexer.set_word_list(lexer, name, word_list, append)

Sets in lexer lexer the word list identified by string or number name to string or list word_list, appending to any existing word list if append is true. This only has an effect if lexer uses word_match() to reference the given list. Case-insensitivity is specified by word_match().

Parameters:

lexer.starts_line(patt, allow_indent)

Creates and returns a pattern that matches pattern patt only at the beginning of a line, or after any line indentation if allow_indent is true.

Parameters:

Usage:

Return:

lexer.tag(lexer, name, patt)

Creates and returns a pattern that tags pattern patt with name name in lexer lexer. If name is not a predefined tag name, its Scintilla style will likely need to be defined by the editor or theme using this lexer.

Parameters:

Usage:

Return:

lexer.to_eol([prefix[, escape=false]])

Creates and returns a pattern that matches from string or pattern prefix until the end of the line. escape indicates whether the end of the line can be escaped with a ‘' character.

Parameters:

Usage:

Return:

lexer.word_match([lexer], word_list[, case_insensitive=false])

Either returns a pattern for lexer lexer (if given) that matches one word in the word list identified by string word_list, ignoring case if case_sensitive is true, or, if lexer is not given, creates and returns a pattern that matches any single word in list or string word_list, ignoring case if case_insensitive is true. This is a convenience function for simplifying a set of ordered choice word patterns and potentially allowing downstream users to configure word lists. If there is ultimately no word list set via set_word_list(), no error will be raised, but the returned pattern will not match anything.

Parameters:

Usage:

Return:

The lfs Module

Extends the lfs library to find files in directories and determine absolute file paths.

Fields defined by lfs

lfs.default_filter <table>

The filter table containing common binary file extensions and version control directories to exclude when iterating over files and directories using lfs.walk. Extensions excluded: a, bmp, bz2, class, dll, exe, gif, gz, jar, jpeg, jpg, o, pdf, png, so, tar, tgz, tif, tiff, xz, and zip. Directories excluded: .bzr, .git, .hg, .svn, FOSSIL, and node_modules.

Functions defined by lfs

lfs.abspath(filename[, prefix])

Returns the absolute path to string filename. prefix or lfs.currentdir() is prepended to a relative filename. The returned path is not guaranteed to exist.

Parameters:

Return:

lfs.walk(dir[, filter=lfs.default_filter[, n[, include_dirs=false]]])

Returns an iterator that iterates over all files and sub-directories (up to n levels deep) in directory dir and yields each file found. String or list filter determines which files to yield, with the default filter being lfs.default_filter. A filter consists of glob patterns that match file and directory paths to include or exclude. Exclusive patterns begin with a ‘!’. If no inclusive patterns are given, any path is initially considered. As a convenience, ‘/’ also matches the Windows directory separator (‘[/\]’ is not needed).

Parameters:

The os Module

Extends Lua’s os library to provide process spawning capabilities.

Functions defined by os

os.spawn(cmd[, cwd][, env][, stdout_cb[, stderr_cb[, exit_cb]]])

Spawns an interactive child process cmd in a separate thread, returning a handle to that process. On Windows, cmd is passed to cmd.exe: %COMSPEC% /c [cmd].

Parameters:

Usage:

Return:

spawn_proc:close()

Closes standard input for process spawn_proc, effectively sending an EOF (end of file) to it.

spawn_proc:kill([signal=9])

Kills running process spawn_proc, or sends it Unix signal signal.

Parameters:

spawn_proc:read([arg=’l’])

Reads and returns stdout from process spawn_proc, according to string format or number arg. Similar to Lua’s io.read() and blocks for input. spawn_proc must still be running. If an error occurs while reading, returns nil, an error code, and an error message. Ensure any read operations read all stdout available, as the stdout callback function passed to os.spawn() will not be called until the stdout buffer is clear.

Parameters:

Return:

spawn_proc:status()

Returns the status of process spawn_proc, which is either “running” or “terminated”.

Return:

spawn_proc:wait()

Blocks until process spawn_proc finishes (if it has not already done so) and returns its status code.

Return:

spawn_proc:write(…)

Writes string input to the stdin of process spawn_proc. Note: On Linux when using the GTK or terminal version, if more than 65536 bytes (64K) are to be written, it is possible those bytes need to be written in 65536-byte (64K) chunks, or the process may not receive all input. However, it is also possible that there is a limit on how many bytes can be written in a short period of time, perhaps 196608 bytes (192K). The Qt version does not appear to have this limitation.

Parameters:

The string Module

Extends Lua’s string library to provide character set conversions.

Functions defined by string

string.iconv(text, new, old)

Converts string text from encoding old to encoding new using GNU libiconv, returning the string result. Raises an error if the encoding conversion failed. Valid encodings are GNU libiconv’s encodings and include:

Parameters:

The textadept Module

The textadept module. It provides utilities for editing text in Textadept.

The textadept.bookmarks Module

Bookmarks for Textadept.

Fields defined by textadept.bookmarks

textadept.bookmarks.MARK_BOOKMARK

The bookmark mark number.

Functions defined by textadept.bookmarks

textadept.bookmarks.clear()

Clears all bookmarks in the current buffer.

textadept.bookmarks.goto_mark([next])

Prompts the user to select a bookmarked line to move the caret to the beginning of unless next is given. If next is true or false, moves the caret to the beginning of the next or previously bookmarked line, respectively.

Parameters:

textadept.bookmarks.toggle()

Toggles a bookmark on the current line.

The textadept.editing Module

Editing features for Textadept.

Fields defined by textadept.editing

textadept.editing.INDIC_HIGHLIGHT

The word highlight indicator number.

textadept.editing.XPM_IMAGES <table>

Map of image names to registered image numbers.

Fields:

textadept.editing.auto_enclose

Whether or not to auto-enclose selected text when typing a punctuation character, taking textadept.editing.auto_pairs into account. The default value is false.

textadept.editing.auto_indent

Match the previous line’s indentation level after inserting a new line. The default value is true.

textadept.editing.auto_pairs <table>

Map of auto-paired characters like parentheses, brackets, braces, and quotes. The default auto-paired characters are “()”, “[]”, “{}”, “''”, “""”, and “``”. For certain XML-like lexers, “<>” is also auto-paired.

Usage:

textadept.editing.autocomplete_all_words

Autocomplete the current word using words from all open buffers. If true, performance may be slow when many buffers are open. The default value is false.

textadept.editing.autocompleters <table>

Map of autocompleter names to autocompletion functions. Names are typically lexer names and autocompletion functions typically autocomplete symbols. Autocompletion functions must return two values: the number of characters behind the caret that are used as the prefix of the entity to be autocompleted, and a list of completions to be shown. By default, the list of completions should be separated by space characters, but the function may change buffer.auto_c_separator if needed. Also, autocompletion lists are sorted automatically by default, but the function may change buffer.auto_c_order if it wants to control sort order.

Fields:

See also:

textadept.editing.comment_string <table>

Map of lexer names to line comment strings for programming languages, used by editing.toggle_comment(). Keys are lexer names and values are either the language’s line comment prefixes or block comment delimiters separated by a ‘|’ character. If no comment string exists for a given language, the lexer-supplied string is used, if available.

textadept.editing.highlight_words

The word highlight mode.

The default value is textadept.editing.HIGHLIGHT_NONE.

textadept.editing.strip_trailing_spaces

Strip trailing whitespace before saving files. (Does not apply to binary files.) The default value is false.

textadept.editing.typeover_auto_paired

Whether or not to type over an auto-paired complement character. The default value is true.

Functions defined by textadept.editing

textadept.editing.autocomplete(name)

Displays an autocompletion list provided by the autocompleter function associated with string name, and returns true if completions were found.

Parameters:

See also:

textadept.editing.convert_indentation()

Converts indentation between tabs and spaces according to buffer.use_tabs. If buffer.use_tabs is true, buffer.tab_width indenting spaces are converted to tabs. Otherwise, all indenting tabs are converted to buffer.tab_width spaces.

textadept.editing.enclose(left, right[, select=false])

Encloses the selected text or the current word within strings left and right, taking multiple selections into account.

Parameters:

textadept.editing.filter_through(command)

Passes the selected text or all buffer text to string shell command command as standard input (stdin) and replaces the input text with the command’s standard output (stdout). command may contain shell pipes (‘|’). Standard input is as follows:

  1. If no text is selected, the entire buffer is used.
  2. If text is selected and spans a single line, is a multiple selection, or is a rectangular selection, only the selected text is used.
  3. If text is selected and spans multiple lines, all text on the lines that have text selected is passed as stdin. However, if the end of the selection is at the beginning of a line, only the line ending delimiters from the previous line are included. The rest of the line is excluded.

Note: Be careful when using commands that emit stdout while reading stdin (as opposed to emitting stdout only after stdin is closed). Input that generates more output than an OS-specific pipe can hold may hang Textadept. On Linux, this may be 64K. See spawn_proc:write().

Parameters:

textadept.editing.goto_line([line])

Moves the caret to the beginning of line number line or the user-specified line, ensuring that line is visible.

Parameters:

textadept.editing.join_lines()

Joins the currently selected lines or the current line with the line below it. As long as any part of a line is selected, the entire line is eligible for joining.

textadept.editing.paste_reindent()

Pastes the text from the clipboard, taking into account the buffer’s indentation settings and the indentation of the current and preceding lines.

textadept.editing.select_enclosed([left[, right]])

Selects the text between strings left and right that enclose the caret. If that range is already selected, toggles between selecting left and right as well. If left and right are not provided, they are assumed to be one of the delimiter pairs specified in textadept.editing.auto_pairs and are inferred from the current position or selection.

Parameters:

textadept.editing.select_line()

Selects the current line. If a current selection spans multiple lines, expands the selection to include whole lines.

textadept.editing.select_paragraph()

Selects the current paragraph. Paragraphs are surrounded by one or more blank lines.

textadept.editing.select_word(all)

Selects the current word or, if all is true, all occurrences of the current word. If a word is already selected, selects the next occurrence as a multiple selection.

Parameters:

See also:

textadept.editing.toggle_comment()

Comments or uncomments the selected lines based on the current language. As long as any part of a line is selected, the entire line is eligible for commenting/uncommenting.

See also:

The textadept.history Module

Records buffer positions within Textadept views over time and allows for navigating through that history.

This module listens for text edit events and buffer switch events. Each time an insertion or deletion occurs, its location is recorded in the current view’s location history. If the edit is close enough to the previous record, the previous record is amended. Each time a buffer switch occurs, the before and after locations are also recorded.

Fields defined by textadept.history

textadept.history.maximum_history_size

The maximum number of history records to keep per view. The default value is 100.

textadept.history.minimum_line_distance

The minimum number of lines between distinct history records. The default value is 3.

Functions defined by textadept.history

textadept.history.back()

Navigates backwards through the current view’s history.

textadept.history.clear()

Clears all view history.

textadept.history.forward()

Navigates forwards through the current view’s history.

textadept.history.record([filename[, line[, column[, soft=false]]]])

Records the given location in the current view’s history.

Parameters:

The textadept.keys Module

Defines key bindings for Textadept. This set of key bindings is pretty standard among other text editors, at least for basic editing commands and movements.

They are designed to be as consistent as possible between operating systems and platforms so that users familiar with one set of bindings can intuit a given binding on another OS or platform, minimizing the need for memorization.

In general, bindings for macOS are the same as for Windows/Linux/BSD except the “Control” modifier key on Windows/Linux/BSD is replaced by “Command” (⌘) and the “Alt” modifier key is replaced by “Control” (^). The only exception is for word- and paragraph-based movement keys, which use “Alt” (⌥) instead of “Command” (⌘).

In general, bindings for the terminal version are the same as for Windows/Linux/BSD except:

Windows Note: on international keyboard layouts, the “AltGr” key is equivalent to pressing “Ctrl” and “Alt”, so AltGr+key combinations may unexpectedly trigger one of Textadept’s Ctrl+Alt+key bindings. In order to avoid this, you will likely have to disable the Ctrl+Alt+key binding in your ~/.textadept/init.lua by setting it to nil.

Key Bindings

Windows, Linux, and BSD macOS Terminal Command
File      
Ctrl+N ⌘N ^N New file
Ctrl+O ⌘O ^O Open file
None None None Open recent file…
None None None Reload file
Ctrl+S ⌘S ^S
M-S^(*)		 Save file
Ctrl+Shift+S ⌘⇧S M-^S Save file as..
None None None Save all files
Ctrl+W ⌘W ^W Close file
Ctrl+Shift+W ⌘⇧W M-^W Close all files
None None None Load session…
None None None Save session…
Ctrl+Q ⌘Q ^Q
M-Q^(*)		 Quit
Edit      
Ctrl+Z
Alt+Bksp		 ⌘Z ^Z^(†)
M-Bksp		 Undo
Ctrl+Y
Ctrl+Shift+Z		 ⌘⇧Z
⌘Y		 ^Y
M-^Z		 Redo
Ctrl+X
Shift+Del		 ⌘X
⇧⌦		 ^X
S-Del		 Cut
Ctrl+C
Ctrl+Ins		 ⌘C ^C Copy
Ctrl+V
Shift+Ins		 ⌘V ^V
S-Ins		 Paste
Ctrl+Shift+V ⌘⇧V M-^V Paste Reindent
Ctrl+Shift+D ⌘⇧D M-^D Duplicate line/selection
Del ⌦
^D		 Del Delete
Alt+Del ^⌦ M-Del Delete word
Ctrl+A ⌘A ^A Select all
Ctrl+Shift+A ⌘⇧A M-^A Deselect
Ctrl+M ⌘M M-M Match brace
Ctrl+Enter ⌘↩ ^Enter Complete word
Ctrl+/ ⌘/ ^/
M-/		 Toggle block comment
Ctrl+J ⌘J M-J Join lines
Ctrl+| ⌘| ^|
^\		 Filter text through
Ctrl+Shift+M ⌘⇧M M-^M Select between delimiters
Ctrl+D ⌘D ^D Select word
Ctrl+Alt+D ^⌘D M-D Deselect word
Ctrl+L ⌘L ^L Select line
Ctrl+Shift+P ⌘⇧P M-^P Select paragraph
Ctrl+Shift+U^(‡)
Ctrl+Alt+Shift+U		 ⌘⇧U M-^U Upper case selection
Ctrl+U ⌘U ^U Lower case selection
Alt+< ^< M-< Enclose selection as XML tags
Alt+> ^> M-> Enclose selection as single XML tag
Alt+” ^” M-“ Enclose selection in double quotes
Alt+’ ^’ M-‘ Enclose selection in single quotes
Alt+( ^( M-( Enclose selection in parentheses
Alt+[ ^[ None Enclose selection in brackets
Alt+{ ^{ M-{ Enclose selection in braces
Ctrl+Alt+Shift+Up ^⌘⇧⇡ None Move selected lines up
Ctrl+Alt+Shift+Down ^⌘⇧⇣ None Move selected lines down
Ctrl+[
Alt+Left		 ⌘[ M-[
M-Left		 Navigate backward
Ctrl+]
Alt+Right		 ⌘] M-]
M-Right		 Navigate forward
None None None Record location
None None None Clear navigation history
None ⌘, None Preferences
Search      
Ctrl+F ⌘F ^F Find
None None None Find next
None None None Find previous
None None None Replace
None None None Replace all
Ctrl+Alt+F ^⌘F M-F Find incremental
Ctrl+Shift+F ⌘⇧F M-^F Find in files
Ctrl+Alt+G ^⌘G M-G Go to next file found
Ctrl+Alt+Shift+G ^⌘⇧G M-S-G Go to previous file found
Ctrl+G ⌘G ^G Go to line
Tools      
Ctrl+E ⌘E ^E Command entry
Ctrl+P ⌘P ^P Select command
Ctrl+R ⌘R ^R Run
Ctrl+Shift+C ⌘⇧C M-^C Compile
Ctrl+Shift+B ⌘⇧B M-^B Build
Ctrl+Shift+T ⌘⇧T M-^T Run tests
Ctrl+Shift+R ⌘⇧R M-^R Run project
Ctrl+Shift+X ⌘⇧X M-^X Stop
Ctrl+Alt+E ^⌘E M-E Next Error
Ctrl+Alt+Shift+E ^⌘⇧E M-S-E Previous Error
Ctrl+K ⌘K ^K Toggle bookmark
None None None Clear bookmarks
Ctrl+Alt+K ^⌘K M-K Next bookmark
Ctrl+Alt+Shift+K ^⌘⇧K M-S-K Previous bookmark
Ctrl+Shift+K ⌘⇧K M-^K Go to bookmark…
Alt+, ^, M-, Start/stop recording macro
Alt+. ^. M-. Play recorded macro
None None None Save recorded macro
None None None Load saved macro
Ctrl+Alt+U ⌘⇧U M-U Quickly open _USERHOME
Ctrl+Alt+H ⌘⇧H M-H Quickly open _HOME
None None None Quickly open current directory
Ctrl+Shift+O ⌘⇧O M-^O Quickly open current project
None None None Insert snippet…
Tab ⇥ Tab Expand snippet or next placeholder
Shift+Tab ⇧⇥ S-Tab Previous snippet placeholder
Esc Esc Esc Cancel snippet
None None None Complete trigger word
None None None Show style
Buffer      
Ctrl+Tab
Ctrl+PgDn		 ^⇥
⌘⇟		 M-PgDn
^Tab^(§)		 Next buffer
Ctrl+Shift+Tab
Ctrl+PgUp		 ^⇧⇥
⌘⇞		 M-PgUp
S-^Tab^(§)		 Previous buffer
Ctrl+B ⌘B ^B Switch to buffer…
None None None Tab width: 2
None None None Tab width: 3
None None None Tab width: 4
None None None Tab width: 8
Ctrl+Alt+T ^⌘T M-T Toggle use tabs
None None None Convert indentation
None None None CR+LF EOL mode
None None None LF EOL mode
None None None UTF-8 encoding
None None None ASCII encoding
None None None CP-1252 encoding
None None None UTF-16 encoding
Ctrl+Shift+L ⌘⇧L M-^L Select lexer…
View      
Ctrl+Alt+PgDn ^⌘⇟ M-^PgDn
M-PgUp^(§)		 Next view
Ctrl+Alt+PgUp ^⌘⇞ M-^PgUp
M-PgDn^(§)		 Previous view
Ctrl+Alt+_ ^⌘_ M-_ Split view horizontal
Ctrl+Alt+| ^⌘| M-| Split view vertical
Ctrl+Alt+W ^⌘W M-W Unsplit view
Ctrl+Alt+Shift+W ^⌘⇧W M-S-W Unsplit all views
Ctrl+Alt++
Ctrl+Alt+=		 ^⌘+
^⌘=		 M-+
M-=		 Grow view
Ctrl+Alt+- ^⌘- M– Shrink view
Ctrl+} ⌘} M-} Toggle current fold
Ctrl+\ ⌘\ M-\ Toggle wrap mode
None None N/A Toggle indent guides
None None None Toggle view whitespace
None None None Toggle virtual space
Ctrl+= ⌘= N/A Zoom in
Ctrl+- ⌘- N/A Zoom out
Ctrl+0 ⌘0 N/A Reset zoom
Help      
F1 F1 None Open manual
Shift+F1 ⇧F1 None Open LuaDoc
None None None About
Other      
Shift+Enter ⇧↩ None Start a new line below the current one
Ctrl+Shift+Enter ⌘⇧↩ None Start a new line above the current one
Ctrl+Alt+Down ^⌘⇣ M-Down Scroll line down
Ctrl+Alt+Up ^⌘⇡ M-Up Scroll line up
Alt+PgUp ^⇞ N/A Scroll page up
Alt+PgDn ^⇟ N/A Scroll page down
Menu
Shift+F10^(§)		 N/A N/A Show context menu
Ctrl+Alt+Shift+R c ^⌘⇧R c M-S-R c Save macro to alphanumeric register c
Ctrl+Alt+R c ^⌘R c M-R c Load and play macro from alphanumeric register c
Movement      
Down ⇣
^N		 Down Line down
Shift+Down ⇧⇣
^⇧N		 S-Down Line down extend selection
Alt+Shift+Down ^⇧⇣ M-S-Down Line down extend rect. selection
Ctrl+Down ⌥⇣ ^Down Paragraph down
Ctrl+Shift+Down ⌥⇧⇣ S-^Down Paragraph down extend selection
Up ⇡
^P		 Up Line up
Shift+Up ⇧⇡
^⇧P		 S-Up Line up extend selection
Alt+Shift+Up ^⇧⇡ M-S-Up Line up extend rect. selection
Ctrl+Up ⌥⇡ ^Up Paragraph up
Ctrl+Shift+Up ⌥⇧⇡ S-^Up Paragraph up extend selection
Left ⇠
^B		 Left Char left
Shift+Left ⇧⇠
^⇧B		 S-Left Char left extend selection
Alt+Shift+Left ^⇧⇠ M-S-Left Char left extend rect. selection
Ctrl+Left ⌥⇠ ^Left Word left
Ctrl+Shift+Left ⌥⇧⇠ S-^Left Word left extend selection
Ctrl+Alt+Left ^⌥⇠ None Word part left
Ctrl+Alt+Shift+Left ^⌥⇧⇠ None Word part left extend selection
Right ⇢
^F		 Right Char right
Shift+Right ⇧⇢
^⇧F		 S-Right Char right extend selection
Alt+Shift+Right ^⇧⇢ M-S-Right Char right extend rect. selection
Ctrl+Right ⌥⇢ ^Right Word right
Ctrl+Shift+Right ⌥⇧⇢ S-^Right Word right extend selection
Ctrl+Alt+Right ^⌥⇢ None Word part right
Ctrl+Alt+Shift+Right ^⌥⇧⇢ None Word part right extend selection
Home ↖
⌘⇠
^A		 Home Line start
Shift+Home ⇧↖
⌘⇧⇠
^⇧A		 None Line start extend selection
Alt+Shift+Home ^⇧↖ None Line start extend rect. selection
Ctrl+Home ⌘↖ None Document start
Ctrl+Shift+Home ⌘⇧↖ None Document start extend selection
End ↘
⌘⇢
^E		 End Line end
Shift+End ⇧↘
⌘⇧⇢
^⇧E		 None Line end extend selection
Alt+Shift+End ^⇧↘ None Line end extend rect. selection
Ctrl+End ⌘↘ None Document end
Ctrl+Shift+End ⌘⇧↘ None Document end extend selection
PgUp ⇞ PgUp Page up
Shift+PgUp ⇧⇞ None Page up extend selection
Alt+Shift+PgUp ^⇧⇞ None Page up extend rect. selection
PgDn ⇟ PgDn Page down
Shift+PgDn ⇧⇟ None Page down extend selection
Alt+Shift+PgDn ^⇧⇟ None Page down extend rect. selection
Ctrl+Del ⌘⌦ ^Del Delete word right
Ctrl+Shift+Del ⌘⇧⌦ S-^Del Delete line right
Ins Ins Ins Toggle overtype
Bksp ⌫
^H		 Bksp
^H		 Delete back
Ctrl+Bksp ⌘⌫ None Delete word left
Ctrl+Shift+Bksp ⌘⇧⌫ None Delete line left
Tab ⇥ Tab
^I		 Insert tab or indent
Shift+Tab ⇧⇥ S-Tab Dedent
None ^K None Cut to line end
None ^L None Center line vertically
N/A N/A ^^ Mark text at the caret position
N/A N/A ^] Swap caret and mark anchor
Find Fields      
Left ⇠
^B		 Left
^B		 Cursor left
Right ⇢
^F		 Right
^F		 Cursor right
Del ⌦ Del Delete forward
Bksp ⌫ Bksp
^H		 Delete back
Ctrl+V ⌘V ^V Paste
N/A N/A ^X Cut all
N/A N/A ^Y Copy all
N/A N/A ^U Erase all
Home ↖
⌘⇠
^A		 Home
^A		 Home
End ↘
⌘⇢
^E		 End
^E		 End
N/A N/A ^T Transpose characters
N/A N/A Tab Toggle find/replace buttons
Tab ⇥ Down Focus replace field
Shift+Tab ⇧⇥ Up Focus find field
Up ⇡ ^P Cycle back through history
Down ⇣ ^N Cycle forward through history
N/A N/A F1 Toggle “Match Case”
N/A N/A F2 Toggle “Whole Word”
N/A N/A F3 Toggle “Regex”
N/A N/A F4 Toggle “Find in Files”

*: For use when the -p or --preserve command line option is given to the non-Windows terminal version, since ^S and ^Q are flow control sequences.

†: If you prefer ^Z to suspend, you can bind it to ui.suspend().

‡: Some versions of Linux intercept this for Unicode input.

§: Only on Windows or the GTK version on Linux.

The textadept.macros Module

A module for recording, playing, saving, and loading keyboard macros. Menu commands are also recorded. At this time, typing into multiple cursors during macro playback is not supported.

Functions defined by textadept.macros

textadept.macros.load([filename])

Loads a macro from file filename or the user-selected file.

Parameters:

textadept.macros.play([filename])

Plays a recorded or previously loaded macro, or loads and plays the macro from file filename if given.

Parameters:

textadept.macros.record()

Toggles between starting and stopping macro recording.

textadept.macros.save([filename])

Saves a recorded macro to file filename or the user-selected file.

Parameters:

The textadept.menu Module

Defines the menus used by Textadept. Menus are simply tables of menu items and submenus and may be edited in place. A menu item itself is a table whose first element is a menu label and whose second element is a menu command to run. Submenus have title keys assigned to string text.

Fields defined by textadept.menu

textadept.menu.context_menu <table>

The default right-click context menu. Submenus, and menu items can be retrieved by name in addition to table index number.

Usage:

textadept.menu.menubar <table>

The default main menubar. Individual menus, submenus, and menu items can be retrieved by name in addition to table index number. As a convenience, a single menu path may be used, with submenus delineated by ‘/’. Labels are localized as needed, so English labels or their localized equivalent may be used.

Usage:

textadept.menu.tab_context_menu <table>

The default tabbar context menu. Submenus, and menu items can be retrieved by name in addition to table index number.

Functions defined by textadept.menu

textadept.menu.select_command()

Prompts the user to select a menu command to run.

The textadept.run Module

Compile and run source code files with Textadept. Language modules may tweak the textadept.run.compile_commands, and textadept.run.run_commands tables for particular languages. The user may tweak textadept.run.build_commands, textadept.run.test_commands, and textadept.run.run_project_commands for particular projects.

Fields defined by textadept.run

textadept.run.INDIC_ERROR

The run or compile error indicator number.

textadept.run.INDIC_WARNING

The run or compile warning indicator number.

textadept.run.MARK_ERROR

The run or compile error marker number.

textadept.run.MARK_WARNING

The run or compile warning marker number.

textadept.run.build_commands <table>

Map of project root paths and “makefiles” to their associated “build” shell command line strings or functions that return such strings. Functions may also return a working directory and process environment table to operate in. By default, the working directory is the project’s root directory and the environment is Textadept’s environment.

textadept.run.compile_commands <table>

Map of filenames, file extensions, and lexer names to their associated “compile” shell command line strings or functions that return such strings. Command line strings may have the following macros:

Functions may also return a working directory and process environment table to operate in. By default, the working directory is the current file’s parent directory and the environment is Textadept’s environment.

textadept.run.run_commands <table>

Map of filenames, file extensions, and lexer names to their associated “run” shell command line strings or functions that return strings. Command line strings may have the following macros:

Functions may also return a working directory and process environment table to operate in. By default, the working directory is the current file’s parent directory and the environment is Textadept’s environment.

textadept.run.run_in_background

Run shell commands silently in the background. The default value is false.

textadept.run.run_project_commands <table>

Map of project root paths to their associated “run” shell command line strings or functions that return such strings. Functions may also return a working directory and process environment table to operate in. By default, the working directory is the project’s root directory and the environment is Textadept’s environment.

textadept.run.run_without_prompt

Run shell commands without prompting. The default value is false.

textadept.run.test_commands <table>

Map of project root paths to their associated “test” shell command line strings or functions that return such strings. Functions may also return a working directory and process environment table to operate in. By default, the working directory is the project’s root directory and the environment is Textadept’s environment.

Functions defined by textadept.run

textadept.run.build([dir])

Prompts the user with the command entry to build the project whose root path is dir or the current project using the shell command from the textadept.run.build_commands table. The current project is determined by either the buffer’s filename or the current working directory. Emits events.BUILD_OUTPUT.

Parameters:

textadept.run.compile([filename=buffer.filename])

Prompts the user with the command entry to compile file filename or the current file using an appropriate shell command from the textadept.run.compile_commands table. The shell command is determined from the file’s filename, extension, or language, in that order. Emits events.COMPILE_OUTPUT.

Parameters:

textadept.run.goto_error(location)

Jumps to the source of the next or previous recognized compile/run warning or error in the output buffer, or the warning/error on a given line number, depending on the value of location. Displays an annotation with the warning or error message if possible.

Parameters:

textadept.run.run([filename=buffer.filename])

Prompts the user with the command entry to run file filename or the current file using an appropriate shell command from the textadept.run.run_commands table. The shell command is determined from the file’s filename, extension, or language, in that order. Emits events.RUN_OUTPUT.

Parameters:

textadept.run.run_project([dir[, cmd]])

Prompts the user with the command entry to run shell command cmd or the shell command from the textadept.run.run_project_commands table for the project whose root path is dir or the current project. The current project is determined by either the buffer’s filename or the current working directory. Emits events.RUN_OUTPUT.

Parameters:

textadept.run.stop()

Stops the currently running process, if any. If there is more than one running process, the user is prompted to select the process to stop. Processes in the list are sorted from longest lived at the top to shortest lived on the bottom.

textadept.run.test([dir])

Prompts the user with the command entry to run tests for the project whose root path is dir or the current project using the shell command from the textadept.run.test_commands table. The current project is determined by either the buffer’s filename or the current working directory. Emits events.TEST_OUTPUT.

Parameters:

The textadept.session Module

Session support for Textadept.

Fields defined by textadept.session

textadept.session.save_on_quit

Save the session when quitting. The default value is true unless the user passed the command line switch -n or --nosession to Textadept.

Functions defined by textadept.session

textadept.session.load([filename])

Loads session file filename or the user-selected session, returning true if a session file was opened and read. Textadept restores split views, opened buffers, cursor information, recent files, and bookmarks.

Parameters:

Usage:

Return:

textadept.session.save(filename)

Saves the session to file filename or the user-selected file. Saves split views, opened buffers, cursor information, recent files, and bookmarks. Upon quitting, the current session is saved to filename again, unless textadept.session.save_on_quit is false.

Parameters:

Usage:

The textadept.snippets Module

Snippets for Textadept.

Overview

Define snippets in the global snippets table in key-value pairs. Each pair consists of either a string trigger word and its snippet text, or a string lexer name (from the lexers/ directory) with a table of trigger words and snippet texts. When searching for a snippet to insert based on a trigger word, Textadept considers snippets in the current lexer to have priority, followed by the ones in the global table. This means if there are two snippets with the same trigger word, Textadept inserts the one specific to the current lexer, not the global one.

Syntax

Snippets may contain any combination of plain-text sequences, variables, interpolated code, and placeholders.

Plain Text

Plain text consists of any character except ‘$’ and ‘`’. Those two characters are reserved for variables, interpolated code, and placeholders. In order to use either of those two characters literally, prefix them with ‘' (e.g. \$ inserts a literal ‘$’).

Variables

Variables are defined in the textadept.snippets.variables table. Textadept expands them in place using the ‘$’ prefix (e.g. $TM_SELECTED_TEXT references the currently selected text). You can provide default values for empty or undefined variables using the “${variable:default}” syntax (e.g. ${TM_SELECTED_TEXT:no text selected}). The values of variables may be transformed in-place using the “${variable/regex/format/options}” syntax (e.g. ${TM_SELECTED_TEXT/.+/"$0"/} quotes the selected text). The section on placeholder transforms below describes this syntax in more detail.

Interpolated Shell Code

Snippets can execute shell code enclosed within ‘`’ characters, and insert any standard output (stdout) emitted by that code. Textadept omits a trailing newline if it exists. For example, the following snippet evaluates (on macOS and Linux) the currently selected arithmetic expression and replaces it with the result:

snippets.eval = '`echo $(( $TM_SELECTED_TEXT ))`'

Interpolated Lua Code

Snippets can also execute Lua code enclosed within “```” sequences, and insert any string results returned by that code. For example, the following snippet inserts the current date and time:

snippets.date = '```os.date()```'

Lua code is executed within Textadept’s Lua environment, with the addition of snippet variables available as global variables (e.g. TM_SELECTED_TEXT exists as a global).

Placeholders

The true power of snippets lies with placeholders. Using placeholders, you can insert a text template and tab through placeholders one at a time, filling them in. Placeholders may be linked to one another, either mirroring text or transforming it in-place.

Tab Stops

The simplest kind of placeholder is called a tab stop, and its syntax is either $n or ${n}, where n is an integer. When a snippet is inserted, the caret is moved to the “$1” placeholder. Pressing the Tab key jumps to the next placeholder, “$2”, and so on. When there are no more placeholders to jump to, the caret moves to either the “$0” placeholder if it exists, or it moves to the end of the snippet. For example, the following snippet inserts a 3-element vector, with tab stops at each element:

snippets.vec = '[$1, $2, $3]'
Default Values

Placeholders may have default values using the “${n:default}” syntax. For example, the following snippet creates a numeric “for” loop in Lua:

snippets.lua.fori = [[
for ${1:i} = ${2:1}, $3 do
	$0
end]]

Multiline snippets should be indented with tabs. Textadept will apply the buffer’s current indentation settings to the snippet upon insertion.

Placeholders may be nested inside one another. For example, the following snippet inserts a function call with a mandatory first argument, but an optional second one:

snippets.call = '${1:func}($2${3:, $4})'

Upon arriving at the third placeholder, backspacing and pressing Tab completes the snippet with a single argument. On the other hand, pressing Tab again at the third placeholder jumps to the second argument for input.

Note that plain text inside default values may not contain a ‘}’ character either, as it is reserved to indicate the end of the placeholder. Use \} to represent a literal ‘}’.

Mirrors

Multiple placeholders can share the same numeric index. When this happens, Textadept visits the one with a default value if it exists. Otherwise, the editor visits the first one it finds. As you type text into a placeholder, any other placeholders with the same index mirror the typed text. For example, the following snippet inserts beginning and ending HTML/XML tags with the same name:

snippets.tag = '<${1:div}>$0</$1>'

The end tag mirrors whatever name you type into the start tag.

Transforms

Sometimes mirrors are not quite good enough. For example, perhaps the mirror’s content needs to deviate slightly from its linked placeholder, like capitalizing the first letter. Or perhaps the mirror’s contents should depend on the presence (or absence) of text in its linked placeholder. This is where placeholder transforms come in handy.

Transforms use the “${n/regex/format/options}” syntax, where regex is a regular expression (regex) to match against the content of placeholder n, format is a formatted replacement for matched content, and options are regex options to use when matching. format may contain any of the following:

options may include any of the following letters:

For example, the following snippet defines an attribute along with its getter and setter functions:

snippets.attr = [[
	${1:int} ${2:name};

	${1} get${2/./${0:/upcase}/}() { return $2; }
	void set${2/./${0:/upcase}/}(${1} ${3:value}) { $2 = $3; }
]]

Note that the ‘/’ and ‘}’ characters are reserved in certain places within a placeholder transform. Use \/ and \}, respectively, to represent literal versions of those characters where necessary.

Multiple Choices

Placeholders may define a list of options for the user to choose from using the “${n|items|}” syntax, where items is a comma-separated list of options (e.g. ${1|foo,bar,baz|}).

Items may not contain a ‘|’ character, as it is reserved to indicate the end of the choice list. Use \| to represent a literal ‘|’.

Migrating Legacy Snippets

Legacy snippets used the following syntax:

You can migrate your snippets using the following steps:

  1. Substitute ‘%’ with ‘$’ in tab stops and mirrors.
  2. Substitute “%n(default)” default placeholders with “${n:default}”. The following regex and replacement should work for non-nested placeholders: %(\d+)\(([^)]+)\) and ${\1:\2}.
  3. Replace n-based Lua and Shell transforms with placeholder transforms. You can add your own transform function to textadept.snippets.transform_methods if you need to.
  4. Replace bare Lua and Shell transforms with interpolated Lua and shell code.
  5. Substitute “%n{items}” choice placeholders with “${n|items|}”.

Fields defined by textadept.snippets

textadept.snippets.INDIC_PLACEHOLDER

The snippet placeholder indicator number.

textadept.snippets.active

Whether or not a snippet is active.

textadept.snippets.paths <table>

List of directory paths to look for snippet files in. Filenames are of the form lexer.trigger.ext or trigger.ext (.ext is an optional, arbitrary file extension). If the global snippets table does not contain a snippet for a given trigger, this table is consulted for a matching filename, and the contents of that file is inserted as a snippet. Note: If a directory has multiple snippets with the same trigger, the snippet chosen for insertion is not defined and may not be constant.

textadept.snippets.transform_methods <table>

Map of format method names to their functions for text captured in placeholder transforms.

Fields:

textadept.snippets.variables <table>

Map of snippet variable names to string values or functions that return string values. Each time a snippet is inserted, this map is used to set its variables.

Fields:

Functions defined by textadept.snippets

textadept.snippets.cancel()

Cancels the active snippet, removing all inserted text. Returns false if no snippet is active.

Return:

textadept.snippets.insert([text])

Inserts snippet text text or the snippet assigned to the trigger word behind the caret. Otherwise, if a snippet is active, goes to the active snippet’s next placeholder. Returns false if no action was taken.

Parameters:

Return:

See also:

textadept.snippets.previous()

Jumps back to the previous snippet placeholder, reverting any changes from the current one. Returns false if no snippet is active.

Return:

textadept.snippets.select()

Prompts the user to select a snippet to insert from a list of global and language-specific snippets.

The ui Module

Utilities for interacting with Textadept’s user interface.

Fields defined by ui

ui.SHOW_ALL_TABS

Option for ui.tabs that always shows the tab bar, even if only one buffer is open.

ui.buffer_list_zorder

Whether or not to list buffers by their z-order (most recently viewed to least recently viewed) in the switcher dialog. The default value is true.

ui.buffer_statusbar_text

The text displayed in the buffer statusbar. (Write-only)

ui.clipboard_text

The text on the clipboard.

ui.context_menu

The buffer’s context menu, a ui.menu(). This is a low-level field. You probably want to use the higher-level textadept.menu.context_menu.

ui.maximized

Whether or not Textadept’s window is maximized. This field is always false in the terminal version.

ui.menubar <table>

A table of menus defining a menubar. (Write-only). This is a low-level field. You probably want to use the higher-level textadept.menu.menubar.

ui.size <table>

A table containing the width and height pixel values of Textadept’s window.

ui.statusbar_text

The text displayed in the statusbar. (Write-only)

ui.tab_context_menu

The context menu for the buffer’s tab, a ui.menu(). This is a low-level field. You probably want to use the higher-level textadept.menu.tab_context_menu.

ui.tabs

Whether or not to display the tab bar when multiple buffers are open. The default value is true in the GUI version, and false in the terminal version. A third option, ui.SHOW_ALL_TABS may be used to always show the tab bar, even if only one buffer is open.

ui.title

The title text of Textadept’s window. (Write-only)

Functions defined by ui

ui.get_split_table()

Returns a split table that contains Textadept’s current split view structure. This is primarily used in session saving.

Return:

ui.goto_file(filename[, split=false[, preferred_view[, sloppy=false]]])

Switches to the existing view whose buffer’s filename is filename. If no view was found and split is true, splits the current view in order to show the requested file. If split is false, shifts to the next or preferred_view view in order to show the requested file. If sloppy is true, requires only the basename of filename to match a buffer’s buffer.filename. If the requested file was not found, it is opened in the desired view.

Parameters:

ui.goto_view(view)

Shifts to view view or the view view number of views relative to the current one. Emits events.VIEW_BEFORE_SWITCH and events.VIEW_AFTER_SWITCH.

Parameters:

ui.menu(menu_table)

Low-level function for creating a menu from table menu_table and returning the userdata. You probably want to use the higher-level textadept.menu.menubar, textadept.menu.context_menu, or textadept.menu.tab_context_menu tables. Emits events.MENU_CLICKED when a menu item is selected.

Parameters:

Usage:

ui.output(…)

Prints the given strings to the output buffer, and returns that buffer. Opens a new buffer if one has not already been opened for printing output. The output buffer attempts to understand the error messages and warnings produced by various tools.

Parameters:

Return:

See also:

ui.output_silent(…)

Silently prints the given strings to the output buffer, and returns that buffer. Opens a new buffer for printing to if necessary.

Parameters:

Return:

See also:

ui.popup_menu(menu)

Displays a popup menu, typically the right-click context menu.

Parameters:

Usage:

See also:

ui.print(…)

Prints the given value(s) to the output buffer, along with a trailing newline. Opens a new buffer if one has not already been opened for printing output.

Parameters:

ui.print_silent_to(type, message)

Silently prints the given message to the buffer of string type type, and returns that buffer. Opens a new buffer for printing to if necessary.

Parameters:

Return:

See also:

ui.print_to(type, message)

Prints the given message to the buffer of string type type, along with a trailing newline, and returns that buffer. Opens a new buffer for printing to if necessary. If the print buffer is already open in a view, the message is printed to that view. Otherwise the view is split (unless ui.tabs is true) and the print buffer is displayed before being printed to.

Parameters:

Usage:

Return:

See also:

ui.suspend()

Suspends Textadept. This only works in the terminal version. By default, Textadept ignores ^Z suspend signals from the terminal. Emits events.SUSPEND and events.RESUME.

Usage:

ui.switch_buffer()

Prompts the user to select a buffer to switch to. Buffers are listed in the order they were opened unless ui.buffer_list_zorder is true, in which case buffers are listed by their z-order (most recently viewed to least recently viewed). Buffers in the same project as the current buffer are shown with relative paths.

ui.update()

Processes pending UI events, including reading from spawned processes. This function is primarily used in Textadept’s own unit tests.

The ui.command_entry Module

Textadept’s Command Entry. It supports multiple modes that each have their own functionality (such as running Lua code and filtering text through shell commands) and history. In addition to the functions and fields listed below, the command entry also has the same functions and fields that buffers and views do.

Fields defined by ui.command_entry

ui.command_entry.active

Whether or not the command entry is active.

ui.command_entry.editing_keys <table>

A metatable with typical platform-specific key bindings for text entries. This metatable may be used to add basic editing and movement keys to command entry modes. It is automatically added to command entry modes unless a metatable was previously set.

Usage:

ui.command_entry.height

The height in pixels of the command entry.

ui.command_entry.label

The text of the command entry label. (Write-only)

Functions defined by ui.command_entry

ui.command_entry.focus()

Opens the command entry. This is a low-level function. You probably want to use the higher-level ui.command_entry.run().

ui.command_entry.run(label, f[, keys][, lang=’text’[, initial_text[, …]]])

Opens the command entry with label label (and optionally with string initial_text), subjecting it to any key bindings defined in table keys, highlighting text with lexer name lang, and then when the Enter key is pressed, closes the command entry and calls function f (if non-nil) with the command entry’s text as an argument, along with any extra arguments passed to this function. By default with no arguments given, opens a Lua command entry. The command entry does not respond to Textadept’s default key bindings, but instead to the key bindings defined in keys and in ui.command_entry.editing_keys.

Parameters:

Usage:

The ui.dialogs Module

Provides a set of interactive dialog prompts for user input.

Functions defined by ui.dialogs

ui.dialogs.input(options)

Prompts the user with an input dialog defined by dialog options table options, returning the user’s input text. If the user canceled the dialog, returns nil.

Parameters:

Usage:

Return:

ui.dialogs.list(options)

Prompts the user with a list item selection dialog defined by dialog options table options, returning the integer index of the selected item or a table of indices of the selected items (depending on whether or not options.multiple is true). If the user canceled the dialog, returns nil. Text typed into the dialog filters the list items. Spaces are treated as wildcards.

Parameters:

Usage:

Return:

ui.dialogs.message(options)

Prompts the user with a generic message box dialog defined by dialog options table options, returning the selected button’s index. If the user canceled the dialog, returns nil.

Parameters:

Usage:

Return:

ui.dialogs.open(options)

Prompts the user with a file open dialog defined by dialog options table options, returning the string file selected. If options.multiple is true, returns the list of files selected. If the user canceled the dialog, returns nil.

Parameters:

Usage:

Return:

ui.dialogs.progress(options)

Displays a progress dialog, defined by dialog options table options, returning true if the user clicked the “Stop” button, or nil if the dialog finishes.

Parameters:

Usage:

Return:

ui.dialogs.save(options)

Prompts the user with a file save dialog defined by dialog options table options, returning the string file chosen. If the user canceled the dialog, returns nil.

Parameters:

Return:

The ui.find Module

Textadept’s Find & Replace pane.

Fields defined by ui.find

ui.find.INDIC_FIND

The find results highlight indicator number.

ui.find.active

Whether or not the Find & Replace pane is active.

ui.find.entry_font

The font to use in the “Find” and “Replace” entries in “name size” format. (Write-only) The default value is system-dependent.

ui.find.find_entry_text

The text in the “Find” entry.

ui.find.find_in_files_filters <table>

Map of directory paths to filters used when finding in files. This table is updated when the user manually specifies a filter in the “Filter” entry during an “In files” search.

ui.find.find_label_text

The text of the “Find” label. (Write-only) This is primarily used for localization.

ui.find.find_next_button_text

The text of the “Find Next” button. (Write-only) This is primarily used for localization.

ui.find.find_prev_button_text

The text of the “Find Prev” button. (Write-only) This is primarily used for localization.

ui.find.highlight_all_matches

Whether or not to highlight all occurrences of found text in the current buffer. The default value is false.

ui.find.in_files

Find search text in a directory of files. The default value is false.

ui.find.in_files_label_text

The text of the “In files” label. (Write-only) This is primarily used for localization.

ui.find.incremental

Find search text incrementally as it is typed. The default value is false.

ui.find.match_case

Match search text case sensitively. The default value is false.

ui.find.match_case_label_text

The text of the “Match case” label. (Write-only) This is primarily used for localization.

ui.find.regex

Interpret search text as a Regular Expression. The default value is false.

ui.find.regex_label_text

The text of the “Regex” label. (Write-only) This is primarily used for localization.

ui.find.replace_all_button_text

The text of the “Replace All” button. (Write-only) This is primarily used for localization.

ui.find.replace_button_text

The text of the “Replace” button. (Write-only) This is primarily used for localization.

ui.find.replace_entry_text

The text in the “Replace” entry. When searching for text in a directory of files, this is the current file and directory filter.

ui.find.replace_label_text

The text of the “Replace” label. (Write-only) This is primarily used for localization.

ui.find.show_filenames_in_progressbar

Whether to show filenames in the find in files search progressbar. This can be useful for determining whether or not custom filters are working as expected. Showing filenames can slow down searches on computers with really fast SSDs. The default value is false.

ui.find.whole_word

Match search text only when it is surrounded by non-word characters in searches. The default value is false.

ui.find.whole_word_label_text

The text of the “Whole word” label. (Write-only) This is primarily used for localization.

Functions defined by ui.find

ui.find.find_next()

Mimics pressing the “Find Next” button. Emits events.FIND.

ui.find.find_prev()

Mimics pressing the “Find Prev” button. Emits events.FIND.

ui.find.focus([options])

Displays and focuses the Find & Replace Pane.

Parameters:

ui.find.goto_file_found(location)

Jumps to the source of the next or previous find in files search result in the buffer titled “Files Found”, or the result on a given line number, depending on the value of location.

Parameters:

ui.find.replace()

Mimics pressing the “Replace” button. Emits events.REPLACE followed by events.FIND unless any events.REPLACE handler returns true.

ui.find.replace_all()

Mimics pressing the “Replace All” button. Emits events.REPLACE_ALL.

The view Module

See buffer.