Textadept API Documentation

Modules

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

The _G Module


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

Fields defined by _G

BSD (bool)

Whether or not Textadept is running on BSD.

CURSES (bool)

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

LINUX (bool)

Whether or not Textadept is running on Linux.

OSX (bool)

Whether or not Textadept is running on Mac OSX as a GUI application.

WIN32 (bool)

Whether or not Textadept is running on Windows.

_CHARSET (string)

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

_HOME (string)

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

_RELEASE (string)

The Textadept release version string.

_USERHOME (string)

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 Linux, BSD, and Mac OSX machines ~/ is the value of “$HOME” (typically /home/username/ and /Users/username/ respectively).

Functions defined by _G

quit()

Emits a QUIT event, and unless any handler returns false, quits Textadept.

See also:

reset()

Resets the Lua State by reloading all initialization scripts. Language modules for opened files are NOT reloaded. Re-opening the files that use them will reload those modules instead. This function is useful for modifying user scripts (such as ~/.textadept/init.lua and ~/.textadept/modules/textadept/keys.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.

spawn(argv, cwd, env, stdout_cb, stderr_cb, exit_cb)

Spawns an interactive child process argv in a separate thread, returning a handle to that process. At the moment, only the Win32 terminal version spawns processes in the same thread.

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)

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

Parameters:

spawn_proc:read(arg)

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 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.

spawn_proc:write()

Writes string input to the stdin of process spawn_proc. Note: On Linux, 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).

Parameters:

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.

Parameters:

Tables defined by _G

_BUFFERS

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

Usage:

See also:

_VIEWS

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

Usage:

See also:

arg

Table of command line parameters passed to Textadept.

See also:

_G.buffer

The current buffer in the current view.

_G.view

The current view.


The _L Module


Map of all messages used by Textadept to their localized form. If the table does not contain the localized version of a given message, it returns a string that starts with “No Localization:” via a metamethod.


The _M Module


A table of loaded Textadept language modules.

Language modules are a special kind of module that Textadept automatically loads when editing source code in a particular programming language. The only thing “special” about them is they are named after a lexer. Otherwise they are plain Lua modules. The ~/.textadept/modules/ directory houses language modules (along with other modules).

A language module is designed to provide extra functionality for a single programming language. Some examples of what language modules can do:

Examples of these features are described in the sections below.

Block Comment

Many languages have different syntaxes for single line comments and multi-line comments in source code. Textadept’s block comment feature only uses one of those syntaxes for a given language. If you prefer the other syntax, or if Textadept does not support block comments for a particular language, modify the textadept.editing.comment_string table. For example:

textadept.editing.comment_string.ansi_c = '//' -- change from /* ... */

Compile and Run

Textadept knows most of the commands that compile and/or run code in source files. However, it does not know all of them, and the ones that it does know may not be completely accurate in all cases. Compile and run commands are read from the textadept.run.compile_commands and textadept.run.run_commands tables using the appropriate lexer key, and thus can be defined or modified. For Lua, it would look like:

textadept.run.compile_commands.lua = 'luac "%f"'
textadept.run.run_commands.lua = 'lua "%f"'

Double-clicking on compile or runtime errors jumps to the error’s location. If Textadept does not recognize your language’s errors properly, add an error pattern to textadept.run.error_patterns. The Lua error pattern looks like:

local patterns = textadept.run.error_patterns
if not patterns.lua then patterns.lua = {} end
patterns.lua[#patterns.lua + 1] = '^luac?: (.-):(%d+): (.+)$'

Buffer Properties

By default, Textadept uses 2 spaces for indentation. Some languages have different indentation guidelines, however. As described in the manual, use events.LEXER_LOADED to change this and any other language-specific editor properties. For example:

events.connect(events.LEXER_LOADED, function(lexer)
  if lexer == 'python' then
    buffer.tab_width = 4
    buffer.use_tabs = false
    buffer.view_ws = buffer.WS_VISIBLEALWAYS
  end
end

Autocompletion and Documentation

Textadept has the capability to autocomplete symbols for programming languages and display API documentation. In order for these to work for a given language, an autocompleter and API file(s) must exist. All of Textadept’s included language modules have examples of autocompleters and API documentation, as well as most of its officially supported language modules.

Snippets

Snippets for common language constructs are useful. Some snippets for common Lua control structures look like this:

snippets.lua = {
  f = "function %1(name)(%2(args))\n\t%0\nend",
  ['for'] = "for i = %1(1), %2(10)%3(, -1) do\n\t%0\nend",
  fori = "for %1(i), %2(val) in ipairs(%3(table)) do\n\t%0\nend",
  forp = "for %1(k), %2(v) in pairs(%3(table)) do\n\t%0\nend",
}

Commands

Additional editing features for the language can be useful. For example, the C module has a feature to add a ‘;’ to the end of the current line and insert a new line. This command is bound to the Shift+Enter (⇧↩ on Mac OSX | S-Enter in curses) key for easy access:

keys.ansi_c = {
  ['s\n'] = function()
    buffer:line_end()
    buffer:add_text(';')
    buffer:new_line()
  end
}

When defining key bindings for other commands, you may make use of a Ctrl+L (⌘L on Mac OSX | M-L in curses) keychain. Traditionally this prefix has been reserved for use by language modules (although neither Textadept nor its modules utilize it at the moment). Users may define this keychain for new or existing modules and it will not conflict with any default key bindings. For example:

keys.lua[not OSX and not CURSES and 'cl' or 'ml'] = {
  ...
}

Menus

It may be useful to add language-specific menu options to the top-level menu and/or right-click context menu in order to access module features without using key bindings. For example:

local lua_menu = {
  title = 'Lua',
  {'Item 1', function() ... end},
  {'Item 2', function() ... end}
}
local tools = textadept.menu.menubar[_L['_Tools']]
tools[#tools + 1] = lua_menu
textadept.menu.context_menu[#textadept.menu.context_menu + 1] = lua_menu

The _M.ansi_c Module


The ansi_c module. It provides utilities for editing C code.

Tables defined by _M.ansi_c

keys.ansi_c

Table of C-specific key bindings.

snippets.ansi_c

Table of C-specific snippets.

_M.ansi_c.tags

List of ctags files to use for autocompletion in addition to the current project’s top-level tags file or the current directory’s tags file.


The _M.lua Module


The lua module. It provides utilities for editing Lua code.

Tables defined by _M.lua

keys.lua

Container for Lua-specific key bindings.

snippets.lua

Container for Lua-specific snippets.

_M.lua.expr_types

Map of expression patterns to their types. Used for type-hinting when showing autocompletions for variables. Expressions are expected to match after the ‘=’ sign of a statement.

Usage:

_M.lua.tags

List of “fake” ctags files to use for autocompletion. The kind ’m' is recognized as a module, ‘f’ as a function, ’t' as a table and ‘F’ as a module or table field. The modules/lua/tadoc.lua script can generate tags and api files for Lua modules via LuaDoc.


The _SCINTILLA Module


Scintilla constants, functions, and properties. Do not modify anything in this module. Doing so will have unpredictable consequences.

Functions defined by _SCINTILLA

_SCINTILLA.next_image_type()

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

Usage:

See also:

_SCINTILLA.next_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.

Usage:

See also:

_SCINTILLA.next_marker_number()

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

Usage:

See also:

_SCINTILLA.next_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.

Usage:

See also:

Tables defined by _SCINTILLA

_SCINTILLA.constants

Map of Scintilla constant names to their numeric values.

See also:

_SCINTILLA.functions

Map of Scintilla function names to tables containing their IDs, return types, wParam types, and lParam types. Types are as follows:

_SCINTILLA.properties

Map of Scintilla property names to table values containing their “get” function IDs, “set” function IDs, return types, and wParam types. The wParam type will be non-zero if the property is indexable. Types are the same as in the functions table.

See also:


The args Module


Processes command line arguments for Textadept.

Fields defined by args

events.ARG_NONE (string)

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

Functions defined by args

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

Registers a command line switch with short and long versions short and long, respectively. narg is the number of arguments the switch accepts, f is the function called when the switch is tripped, and description is the switch’s description when displaying help.

Parameters:


The buffer Module


A Textadept buffer object. Constants are documented in the fields they apply to. While you can work with individual buffer instances, it is really only useful to work with the global one.

Fields defined by buffer

buffer.ALPHA_NOALPHA (number, Read-only)

buffer.ALPHA_OPAQUE (number, Read-only)

buffer.ALPHA_TRANSPARENT (number, Read-only)

buffer.ANNOTATION_BOXED (number, Read-only)

buffer.ANNOTATION_HIDDEN (number, Read-only)

buffer.ANNOTATION_INDENTED (number, Read-only)

buffer.ANNOTATION_STANDARD (number, Read-only)

buffer.AUTOMATICFOLD_CHANGE (number, Read-only)

buffer.AUTOMATICFOLD_CLICK (number, Read-only)

buffer.AUTOMATICFOLD_SHOW (number, Read-only)

buffer.CARETSTICKY_OFF (number, Read-only)

buffer.CARETSTICKY_ON (number, Read-only)

buffer.CARETSTICKY_WHITESPACE (number, Read-only)

buffer.CARETSTYLE_BLOCK (number, Read-only)

buffer.CARETSTYLE_INVISIBLE (number, Read-only)

buffer.CARETSTYLE_LINE (number, Read-only)

buffer.CARET_EVEN (number, Read-only)

buffer.CARET_JUMPS (number, Read-only)

buffer.CARET_SLOP (number, Read-only)

buffer.CARET_STRICT (number, Read-only)

buffer.CASEINSENSITIVEBEHAVIOUR_IGNORECASE (number, Read-only)

buffer.CASEINSENSITIVEBEHAVIOUR_RESPECTCASE (number, Read-only)

buffer.CASE_LOWER (number, Read-only)

buffer.CASE_MIXED (number, Read-only)

buffer.CASE_UPPER (number, Read-only)

buffer.CURSORARROW (number, Read-only)

buffer.CURSORNORMAL (number, Read-only)

buffer.CURSORREVERSEARROW (number, Read-only)

buffer.CURSORWAIT (number, Read-only)

buffer.EDGE_BACKGROUND (number, Read-only)

buffer.EDGE_LINE (number, Read-only)

buffer.EDGE_MULTILINE (number, Read-only)

buffer.EDGE_NONE (number, Read-only)

buffer.EOL_CR (number, Read-only)

buffer.EOL_CRLF (number, Read-only)

buffer.EOL_LF (number, Read-only)

buffer.FIND_MATCHCASE (number, Read-only)

buffer.FIND_REGEXP (number, Read-only)

buffer.FIND_WHOLEWORD (number, Read-only)

buffer.FIND_WORDSTART (number, Read-only)

buffer.FOLDACTION_CONTRACT (number, Read-only)

buffer.FOLDACTION_EXPAND (number, Read-only)

buffer.FOLDACTION_TOGGLE (number, Read-only)

buffer.FOLDFLAG_LEVELNUMBERS (number, Read-only)

buffer.FOLDFLAG_LINEAFTER_CONTRACTED (number, Read-only)

buffer.FOLDFLAG_LINEAFTER_EXPANDED (number, Read-only)

buffer.FOLDFLAG_LINEBEFORE_CONTRACTED (number, Read-only)

buffer.FOLDFLAG_LINEBEFORE_EXPANDED (number, Read-only)

buffer.FOLDFLAG_LINESTATE (number, Read-only)

buffer.FOLDLEVELBASE (number, Read-only)

buffer.FOLDLEVELHEADERFLAG (number, Read-only)

buffer.FOLDLEVELNUMBERMASK (number, Read-only)

buffer.FOLDLEVELWHITEFLAG (number, Read-only)

buffer.INDIC_BOX (number, Read-only)

buffer.INDIC_COMPOSITIONTHICK (number, Read-only)

buffer.INDIC_COMPOSITIONTHIN (number, Read-only)

buffer.INDIC_DASH (number, Read-only)

buffer.INDIC_DIAGONAL (number, Read-only)

buffer.INDIC_DOTBOX (number, Read-only)

buffer.INDIC_DOTS (number, Read-only)

buffer.INDIC_FULLBOX (number, Read-only)

buffer.INDIC_HIDDEN (number, Read-only)

buffer.INDIC_MAX (number, Read-only)

buffer.INDIC_PLAIN (number, Read-only)

buffer.INDIC_ROUNDBOX (number, Read-only)

buffer.INDIC_SQUIGGLE (number, Read-only)

buffer.INDIC_SQUIGGLELOW (number, Read-only)

buffer.INDIC_SQUIGGLEPIXMAP (number, Read-only)

buffer.INDIC_STRAIGHTBOX (number, Read-only)

buffer.INDIC_STRIKE (number, Read-only)

buffer.INDIC_TEXTFORE (number, Read-only)

buffer.INDIC_TT (number, Read-only)

buffer.IV_LOOKBOTH (number, Read-only)

buffer.IV_LOOKFORWARD (number, Read-only)

buffer.IV_NONE (number, Read-only)

buffer.IV_REAL (number, Read-only)

buffer.MARGINOPTION_NONE (number, Read-only)

buffer.MARGINOPTION_SUBLINESELECT (number, Read-only)

buffer.MARGIN_BACK (number, Read-only)

buffer.MARGIN_COLOUR (number, Read-only)

buffer.MARGIN_FORE (number, Read-only)

buffer.MARGIN_NUMBER (number, Read-only)

buffer.MARGIN_RTEXT (number, Read-only)

buffer.MARGIN_SYMBOL (number, Read-only)

buffer.MARGIN_TEXT (number, Read-only)

buffer.MARKER_MAX (number, Read-only)

buffer.MARKNUM_FOLDER (number, Read-only)

buffer.MARKNUM_FOLDEREND (number, Read-only)

buffer.MARKNUM_FOLDERMIDTAIL (number, Read-only)

buffer.MARKNUM_FOLDEROPEN (number, Read-only)

buffer.MARKNUM_FOLDEROPENMID (number, Read-only)

buffer.MARKNUM_FOLDERSUB (number, Read-only)

buffer.MARKNUM_FOLDERTAIL (number, Read-only)

buffer.MARK_ARROW (number, Read-only)

buffer.MARK_ARROWDOWN (number, Read-only)

buffer.MARK_ARROWS (number, Read-only)

buffer.MARK_AVAILABLE (number, Read-only)

buffer.MARK_BACKGROUND (number, Read-only)

buffer.MARK_BOOKMARK (number, Read-only)

buffer.MARK_BOXMINUS (number, Read-only)

buffer.MARK_BOXMINUSCONNECTED (number, Read-only)

buffer.MARK_BOXPLUS (number, Read-only)

buffer.MARK_BOXPLUSCONNECTED (number, Read-only)

buffer.MARK_CHARACTER (number, Read-only)

buffer.MARK_CIRCLE (number, Read-only)

buffer.MARK_CIRCLEMINUS (number, Read-only)

buffer.MARK_CIRCLEMINUSCONNECTED (number, Read-only)

buffer.MARK_CIRCLEPLUS (number, Read-only)

buffer.MARK_CIRCLEPLUSCONNECTED (number, Read-only)

buffer.MARK_DOTDOTDOT (number, Read-only)

buffer.MARK_EMPTY (number, Read-only)

buffer.MARK_FULLRECT (number, Read-only)

buffer.MARK_LCORNER (number, Read-only)

buffer.MARK_LCORNERCURVE (number, Read-only)

buffer.MARK_LEFTRECT (number, Read-only)

buffer.MARK_MINUS (number, Read-only)

buffer.MARK_PIXMAP (number, Read-only)

buffer.MARK_PLUS (number, Read-only)

buffer.MARK_RGBAIMAGE (number, Read-only)

buffer.MARK_ROUNDRECT (number, Read-only)

buffer.MARK_SHORTARROW (number, Read-only)

buffer.MARK_SMALLRECT (number, Read-only)

buffer.MARK_TCORNER (number, Read-only)

buffer.MARK_TCORNERCURVE (number, Read-only)

buffer.MARK_UNDERLINE (number, Read-only)

buffer.MARK_VLINE (number, Read-only)

buffer.MASK_FOLDERS (number, Read-only)

buffer.MOD_ALT (number, Read-only)

buffer.MOD_CTRL (number, Read-only)

buffer.MOD_META (number, Read-only)

buffer.MOD_SHIFT (number, Read-only)

buffer.MOD_SUPER (number, Read-only)

buffer.MOUSE_DRAG (number, Read-only)

buffer.MOUSE_PRESS (number, Read-only)

buffer.MOUSE_RELEASE (number, Read-only)

buffer.MULTIAUTOC_EACH (number, Read-only)

buffer.MULTIAUTOC_ONCE (number, Read-only)

buffer.MULTIPASTE_EACH (number, Read-only)

buffer.MULTIPASTE_ONCE (number, Read-only)

buffer.ORDER_CUSTOM (number, Read-only)

buffer.ORDER_PERFORMSORT (number, Read-only)

buffer.ORDER_PRESORTED (number, Read-only)

buffer.SEL_LINES (number, Read-only)

buffer.SEL_RECTANGLE (number, Read-only)

buffer.SEL_STREAM (number, Read-only)

buffer.SEL_THIN (number, Read-only)

buffer.STYLE_BRACEBAD (number, Read-only)

buffer.STYLE_BRACELIGHT (number, Read-only)

buffer.STYLE_CALLTIP (number, Read-only)

buffer.STYLE_CONTROLCHAR (number, Read-only)

buffer.STYLE_DEFAULT (number, Read-only)

buffer.STYLE_FOLDDISPLAYTEXT (number, Read-only)

buffer.STYLE_INDENTGUIDE (number, Read-only)

buffer.STYLE_LINENUMBER (number, Read-only)

buffer.STYLE_MAX (number, Read-only)

buffer.TIME_FOREVER (number, Read-only)

buffer.UPDATE_CONTENT (number, Read-only)

buffer.UPDATE_H_SCROLL (number, Read-only)

buffer.UPDATE_SELECTION (number, Read-only)

buffer.UPDATE_V_SCROLL (number, Read-only)

buffer.VISIBLE_SLOP (number, Read-only)

buffer.VISIBLE_STRICT (number, Read-only)

buffer.VS_NONE (number, Read-only)

buffer.VS_RECTANGULARSELECTION (number, Read-only)

buffer.VS_USERACCESSIBLE (number, Read-only)

buffer.WRAPINDENT_FIXED (number, Read-only)

buffer.WRAPINDENT_INDENT (number, Read-only)

buffer.WRAPINDENT_SAME (number, Read-only)

buffer.WRAPVISUALFLAGLOC_DEFAULT (number, Read-only)

buffer.WRAPVISUALFLAGLOC_END_BY_TEXT (number, Read-only)

buffer.WRAPVISUALFLAGLOC_START_BY_TEXT (number, Read-only)

buffer.WRAPVISUALFLAG_END (number, Read-only)

buffer.WRAPVISUALFLAG_MARGIN (number, Read-only)

buffer.WRAPVISUALFLAG_NONE (number, Read-only)

buffer.WRAPVISUALFLAG_START (number, Read-only)

buffer.WRAP_CHAR (number, Read-only)

buffer.WRAP_NONE (number, Read-only)

buffer.WRAP_WHITESPACE (number, Read-only)

buffer.WRAP_WORD (number, Read-only)

buffer.WS_INVISIBLE (number, Read-only)

buffer.WS_VISIBLEAFTERINDENT (number, Read-only)

buffer.WS_VISIBLEALWAYS (number, Read-only)

buffer.additional_caret_fore (number)

The foreground color, in “0xBBGGRR” format, of additional carets.

buffer.additional_carets_blink (bool)

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

buffer.additional_carets_visible (bool)

Display additional carets. The default value is true.

buffer.additional_sel_alpha (number)

The alpha value, ranging from 0 (transparent) to 255 (opaque), of additional selections. The default value is buffer.ALPHA_NOALPHA, for no alpha.

buffer.additional_sel_back (number, Write-only)

The background color, in “0xBBGGRR” format, of additional selections. This field has no effect when calling buffer.set_sel_back(false, ...).

buffer.additional_sel_fore (number, Write-only)

The foreground color, in “0xBBGGRR” format, of additional selections. This field has no effect when calling buffer.set_sel_fore(false, ...).

buffer.additional_selection_typing (bool)

Type into multiple selections. The default value is false.

buffer.all_lines_visible (bool, Read-only)

Whether or not all lines are visible.

buffer.anchor (number)

The anchor’s position.

buffer.annotation_lines (table, Read-only)

Table of the number of annotation text lines for line numbers starting from zero.

buffer.annotation_style (table)

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

buffer.annotation_text (table)

Table of annotation text for line numbers starting from zero.

buffer.annotation_visible (number)

The annotation visibility mode.

The default value is buffer.ANNOTATION_HIDDEN.

buffer.auto_c_auto_hide (bool)

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

buffer.auto_c_cancel_at_start (bool)

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_case_insensitive_behaviour (number)

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

The default value is buffer.CASEINSENSITIVEBEHAVIOUR_RESPECTCASE.

buffer.auto_c_choose_single (bool)

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

buffer.auto_c_current (number, Read-only)

The index of the currently selected item in an autocompletion or user list.

buffer.auto_c_current_text (string, Read-only)

The text of the currently selected item in an autocompletion or user list.

buffer.auto_c_drop_rest_of_word (bool)

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

buffer.auto_c_fill_ups (string, Write-only)

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

buffer.auto_c_ignore_case (bool)

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

buffer.auto_c_max_height (number)

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

buffer.auto_c_max_width (number)

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.

buffer.auto_c_multi (number)

The multiple selection autocomplete mode.

The default value is buffer.MULTIAUTOC_ONCE.

buffer.auto_c_order (number)

The order setting for autocompletion and user lists.

The default value is buffer.ORDER_PRESORTED.

buffer.auto_c_separator (number)

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

buffer.auto_c_type_separator (number)

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 buffer.register_image() or buffer.register_rgba_image() before appending image types to list items after type separator characters. The default value is 63 (‘?’).

buffer.back_space_un_indents (bool)

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

buffer.call_tip_fore_hlt (number, Write-only)

A call tip’s highlighted text foreground color, in “0xBBGGRR” format.

buffer.call_tip_pos_start (number, Write-only)

The position in which backspacing beyond it hides a visible call tip.

buffer.call_tip_position (boolean)

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

buffer.call_tip_use_style (number)

The pixel width of tab characters in call tips. When non-zero, also enables the use of style number buffer.STYLE_CALLTIP instead of buffer.STYLE_DEFAULT for call tip styles. The default value is 0.

buffer.caret_fore (number)

The caret’s foreground color, in “0xBBGGRR” format.

buffer.caret_line_back (number)

The background color, in “0xBBGGRR” format, of the line that contains the caret.

buffer.caret_line_back_alpha (number)

The caret line’s background alpha value, ranging from 0 (transparent) to 255 (opaque). The default value is buffer.ALPHA_NOALPHA, for no alpha.

buffer.caret_line_visible (bool)

Color the background of the line that contains the caret a different color. The default value is false.

buffer.caret_line_visible_always (bool)

Always show the caret line, even when the window is not in focus. The default value is false, showing the line only when the window is in focus.

buffer.caret_period (number)

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

buffer.caret_sticky (number)

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

The default value is buffer.CARETSTICKY_OFF.

buffer.caret_style (number)

The caret’s visual style.

The default value is buffer.CARETSTYLE_LINE.

buffer.caret_width (number)

The line caret’s pixel width in insert mode, either 0, 1, 2, or 3. The default value is 1.

buffer.char_at (table, Read-only)

Table of character bytes at positions starting from zero.

buffer.column (table, Read-only)

Table of column numbers (taking tab widths into account) for positions starting from zero. Multi-byte characters count as single characters.

buffer.current_pos (number)

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

buffer.cursor (number)

The display cursor type.

The default value is buffer.CURSORNORMAL.

buffer.edge_colour (number)

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

buffer.edge_column (number)

The column number to mark long lines at.

buffer.edge_mode (number)

The long line mark mode.

buffer.encoding (string or nil)

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

buffer.end_at_last_line (bool)

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

buffer.end_styled (number, Read-only)

The current styling position or the last correctly styled character’s position.

buffer.eol_mode (number)

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.

The default value is buffer.EOL_CRLF on Windows platforms, buffer.EOL_LF otherwise.

buffer.extra_ascent (number)

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

buffer.extra_descent (number)

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

buffer.filename (string)

The absolute file path associated with the buffer.

buffer.first_visible_line (number)

The line number of the line at the top of the view, starting from zero.

buffer.fold_display_text_style (number)

The fold display text mode.

The default value is buffer.FOLDDISPLAYTEXT_HIDDEN.

buffer.fold_expanded (table)

Table of flags that indicate whether or not fold points are expanded for line numbers starting from zero. Setting expanded fold states does not toggle folds; it only updates fold margin markers. Use buffer.toggle_fold() instead.

buffer.fold_flags (number, Read-only)

Bit-mask of folding lines to draw in the buffer.

The default value is 0.

buffer.fold_level (table)

Table of fold level bit-masks for line numbers starting from zero. Fold level masks comprise of an integer level combined with any of the following bit flags:

buffer.fold_parent (table, Read-only)

Table of fold point line numbers for child line numbers starting from zero. A line number of -1 means no line was found.

buffer.h_scroll_bar (bool)

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

buffer.highlight_guide (number)

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

buffer.idle_styling (number)

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

The default value is buffer.IDLESTYLING_NONE.

buffer.indent (number)

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

buffer.indentation_guides (number)

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 buffer.IV_NONE.

buffer.indic_alpha (table)

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

buffer.indic_fore (table)

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

buffer.indic_hover_fore (table)

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

buffer.indic_hover_style (table)

Table of hover styles for indicators numbers from 0 to 31. 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.indic_outline_alpha (table)

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

buffer.indic_style (table)

Table of styles for indicator numbers from 0 to 31.

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

buffer.indic_under (table)

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

buffer.indicator_current (number)

The indicator number in the range of 0 to 31 used by buffer.indicator_fill_range() and buffer.indicator_clear_range().

buffer.length (number, Read-only)

The number of bytes in the buffer.

buffer.line_count (number, Read-only)

The number of lines in the buffer. There is always at least one.

buffer.line_end_position (table, Read-only)

Table of positions at the ends of lines, but before any end of line characters, for line numbers starting from zero.

buffer.line_indent_position (table, Read-only)

Table of positions at the ends of indentation for line numbers starting from zero.

buffer.line_indentation (table)

Table of column indentation amounts, for line numbers starting from zero.

buffer.line_visible (table, Read-only)

Table of flags that indicate whether or not lines are visible for line numbers starting from zero.

buffer.lines_on_screen (number, Read-only)

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

buffer.main_selection (number)

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

buffer.margin_back_n (table)

Table of background colors, in “0xBBGGRR” format, of margin numbers from 0 to buffer.margins - 1 (4 by default). Only affects margins of type buffer.MARGIN_COLOUR.

buffer.margin_cursor_n (table)

Table of cursor types shown over margin numbers from 0 to buffer.margins - 1 (4 by default).

The default values are buffer.CURSORREVERSEARROW.

buffer.margin_left (number)

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

buffer.margin_mask_n (table)

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

buffer.margin_options (number)

A bit-mask of margin option settings.

The default value is buffer.MARGINOPTION_NONE.

buffer.margin_right (number)

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

buffer.margin_sensitive_n (table)

Table of flags that indicate whether or not mouse clicks in margins emit MARGIN_CLICK events for margin numbers from 0 to buffer.margins - 1 (4 by default). The default values are false.

buffer.margin_style (table)

Table of style numbers for line numbers starting from zero in the text margin. Only some style attributes are active in text margins: font, size, bold, italics, fore, and back.

buffer.margin_text (table)

Table of text displayed in text margins for line numbers starting from zero.

buffer.margin_type_n (table)

Table of margin types for margin numbers from 0 to buffer.margins - 1 (4 by default).

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

buffer.margin_width_n (table)

Table of pixel margin widths for margin numbers from 0 to buffer.margins - 1 (4 by default).

buffer.margins (number)

The number of margins. The default value is 5.

buffer.marker_alpha (table, Write-only)

Table of alpha values, ranging from 0 (transparent) to 255 (opaque), of markers drawn in the text area (not the margin) for markers numbers from 0 to 31. The default values are buffer.ALPHA_NOALPHA, for no alpha.

buffer.marker_back (table, Write-only)

Table of background colors, in “0xBBGGRR” format, of marker numbers from 0 to 31.

buffer.marker_back_selected (table, Write-only)

Table of background colors, in “0xBBGGRR” format, of markers whose folding blocks are selected for marker numbers from 0 to 31.

buffer.marker_fore (table, Write-only)

Table of foreground colors, in “0xBBGGRR” format, of marker numbers from 0 to 31.

buffer.modify (bool)

Whether or not the buffer has unsaved changes.

buffer.mouse_dwell_time (number)

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

buffer.mouse_selection_rectangular_switch (bool)

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

buffer.multi_paste (number)

The multiple selection paste mode.

The default value is buffer.MULTIPASTE_ONCE.

buffer.multiple_selection (bool)

Enable multiple selection. The default value is false.

buffer.overtype (bool)

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

buffer.property (table)

Map of key-value string pairs used by lexers.

buffer.property_expanded (table, Read-only)

Map of key-value string pairs used by lexers with %() variable replacement performed in values.

buffer.property_int (table, Read-only)

Map of key-value pairs used by lexers with values interpreted as numbers, or 0 if not found.

buffer.punctuation_chars (string)

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.read_only (bool)

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

buffer.rectangular_selection_anchor (number)

The rectangular selection’s anchor position.

buffer.rectangular_selection_anchor_virtual_space (number)

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

buffer.rectangular_selection_caret (number)

The rectangular selection’s caret position.

buffer.rectangular_selection_caret_virtual_space (number)

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

buffer.rectangular_selection_modifier (number)

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

The default value is buffer.MOD_CTRL.

buffer.representation (table)

The 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. Call buffer.clear_representation() to remove a representation.

buffer.rgba_image_height (number)

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

buffer.rgba_image_scale (number)

The scale factor in percent of the RGBA image to be defined using buffer.marker_define_rgba_image(). This is useful on OSX 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.

buffer.rgba_image_width (number)

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

buffer.scroll_width (number)

The horizontal scrolling pixel width. For performance, the view does not measure the display width of the buffer to determine the properties of the horizontal scroll bar, but uses an assumed width instead. To ensure the width of the currently visible lines can be scrolled use buffer.scroll_width_tracking. The default value is 2000.

buffer.scroll_width_tracking (bool)

Continuously update the horizontal scrolling width to match the maximum width of a displayed line beyond buffer.scroll_width. The default value is false.

buffer.search_flags (number)

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

The default value is 0.

buffer.sel_alpha (number)

The selection’s alpha value, ranging from 0 (transparent) to 255 (opaque). The default value is buffer.ALPHA_NOALPHA, for no alpha.

buffer.sel_eol_filled (bool)

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

buffer.selection_empty (bool, Read-only)

Whether or not no text is selected.

buffer.selection_end (number)

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

buffer.selection_is_rectangle (bool, Read-only)

Whether or not the selection is a rectangular selection.

buffer.selection_mode (number)

The selection mode.

When set, caret movement alters the selected text until this field is set again to the same value or until buffer.cancel() is called.

buffer.selection_n_anchor (table)

Table of positions at the beginning of existing selections numbered from zero, the main selection.

buffer.selection_n_anchor_virtual_space (table)

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

buffer.selection_n_caret (table)

Table of positions at the end of existing selections numbered from zero, the main selection.

buffer.selection_n_caret_virtual_space (table)

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

buffer.selection_n_end (table)

Table of positions at the end of existing selections numbered from zero, the main selection.

buffer.selection_n_start (table)

Table of positions at the beginning of existing selections numbered from zero, the main selection.

buffer.selection_start (number)

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

buffer.selections (number, Read-only)

The number of active selections. There is always at least one selection.

buffer.style_at (table, Read-only)

Table of style numbers at positions starting from zero.

buffer.style_back (table)

Table of background colors, in “0xBBGGRR” format, of text for style numbers from 0 to 255.

buffer.style_bold (table)

Table of flags that indicate whether or not text is bold for style numbers from 0 to 255. The default values are false.

buffer.style_case (table)

Table of letter case modes of text for style numbers from 0 to 255.

The default values are buffer.CASE_MIXED.

buffer.style_changeable (table)

Table of flags that indicate whether or not text is changeable for style numbers from 0 to 255. The default values are true. Currently, read-only styles do not allow the caret into the range of text, but ranges that contain read-only text are deletable.

buffer.style_eol_filled (table)

Table 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 0 to 255. The default values are false.

buffer.style_font (table)

Table of string font names of text for style numbers from 0 to 255.

buffer.style_fore (table)

Table of foreground colors, in “0xBBGGRR” format, of text for style numbers from 0 to 255.

buffer.style_italic (table)

Table of flags that indicate whether or not text is italic for style numbers from 0 to 255. The default values are false.

buffer.style_name (table, Read-only)

Table of style names for style numbers from 0 to 255.

buffer.style_size (table)

Table of font sizes of text for style numbers from 0 to 255.

buffer.style_underline (table)

Table of flags that indicate whether or not text is underlined for style numbers from 0 to 255. The default values are false.

buffer.style_visible (table)

Table of flags that indicate whether or not text is visible for style numbers from 0 to 255. The default values are true.

buffer.tab_draw_mode (number)

The draw mode of visible tabs.

The default value is buffer.TD_LONGARROW.

buffer.tab_indents (bool)

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

buffer.tab_label (string)

The buffer’s tab label in the tab bar.

buffer.tab_width (number)

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

buffer.tag (table, Read-only)

List of capture text for capture numbers from a regular expression search.

buffer.target_end (number)

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

buffer.target_start (number)

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

buffer.target_text (string, Read-only)

The text in the target range.

buffer.text_length (number, Read-only)

The number of bytes in the buffer.

buffer.use_tabs (bool)

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.v_scroll_bar (bool)

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

buffer.view_eol (bool)

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

buffer.view_ws (number)

The whitespace visibility mode.

The default value is buffer.WS_INVISIBLE.

buffer.virtual_space_options (number)

The virtual space mode.

When virtual space is enabled, the caret may move into the space past end of line characters. The default value is buffer.VS_NONE.

buffer.whitespace_chars (string)

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.whitespace_size (number)

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

buffer.word_chars (string)

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.wrap_indent_mode (number)

The wrapped line indent mode.

The default value is buffer.WRAPINDENT_FIXED.

buffer.wrap_mode (number)

Long line wrap mode.

The default value is buffer.WRAP_NONE.

buffer.wrap_start_indent (number)

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

buffer.wrap_visual_flags (number)

The wrapped line visual flag display mode.

The default value is buffer.WRAPVISUALFLAG_NONE.

buffer.wrap_visual_flags_location (number)

The wrapped line visual flag drawing mode.

The default value is buffer.WRAPVISUALFLAGLOC_DEFAULT.

buffer.x_offset (number)

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.

buffer.zoom (number)

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

Functions defined by buffer

buffer.add_selection(buffer, 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 still counts as a selection, use buffer.set_selection() first when setting a list of selections.

Parameters:

See also:

buffer.add_text(buffer, 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.annotation_clear_all(buffer)

Clears annotations from all lines.

Parameters:

buffer.append_text(buffer, text)

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

Parameters:

buffer.auto_c_active(buffer)

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

Parameters:

Return:

buffer.auto_c_cancel(buffer)

Cancels an autocompletion or user list.

Parameters:

buffer.auto_c_complete(buffer)

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

Parameters:

buffer.auto_c_pos_start(buffer)

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

Parameters:

Return:

buffer.auto_c_select(buffer, 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_show(buffer, 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:

buffer.auto_c_stops(buffer, 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.back_tab(buffer)

Un-indents the text on the selected lines.

Parameters:

buffer.begin_undo_action(buffer)

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

Parameters:

buffer.brace_bad_light(buffer, pos)

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

Parameters:

buffer.brace_bad_light_indicator(buffer, use_indicator, indicator)

Highlights unmatched brace characters with indicator number indicator, in the range of 0 to 31, instead of the buffer.STYLE_BRACEBAD style if use_indicator is true.

Parameters:

buffer.brace_highlight(buffer, 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 buffer.highlight_guide in order to highlight the indent guide.

Parameters:

buffer.brace_highlight_indicator(buffer, use_indicator, indicator)

Highlights matching brace characters with indicator number indicator, in the range of 0 to 31, instead of the buffer.STYLE_BRACELIGHT style if use_indicator is true.

Parameters:

buffer.brace_match(buffer, pos)

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:

buffer.call_tip_active(buffer)

Returns whether or not a call tip is visible.

Parameters:

Return:

buffer.call_tip_cancel(buffer)

Removes a call tip from view.

Parameters:

buffer.call_tip_pos_start(buffer)

Returns a call tip’s display position.

Parameters:

Return:

buffer.call_tip_set_hlt(buffer, start_pos, end_pos)

Highlights a call tip’s text between positions start_pos, starting from zero, to end_pos with the color buffer.call_tip_fore_hlt.

Parameters:

buffer.call_tip_show(buffer, 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:

buffer.can_redo(buffer)

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

Parameters:

Return:

buffer.can_undo(buffer)

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

Parameters:

Return:

buffer.cancel(buffer)

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

Parameters:

buffer.char_left(buffer)

Moves the caret left one character.

Parameters:

buffer.char_left_extend(buffer)

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

Parameters:

buffer.char_left_rect_extend(buffer)

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

Parameters:

buffer.char_right(buffer)

Moves the caret right one character.

Parameters:

buffer.char_right_extend(buffer)

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

Parameters:

buffer.char_right_rect_extend(buffer)

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

Parameters:

buffer.choose_caret_x(buffer)

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

Parameters:

See also:

buffer.clear(buffer)

Deletes the selected text or the character at the caret.

Parameters:

buffer.clear_all(buffer)

Deletes the buffer’s text.

Parameters:

buffer.clear_document_style(buffer)

Clears all styling and folding information.

Parameters:

buffer.clear_registered_images(buffer)

Clears all images registered using buffer.register_image() and buffer.register_rgba_image().

Parameters:

buffer.clear_representation(buffer, char)

Removes the alternate string representation for character char.

Parameters:

buffer.clear_selections(buffer)

Removes all selections and moves the caret to the beginning of the buffer.

Parameters:

buffer.colourise(buffer, 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.

Parameters:

buffer.contracted_fold_next(buffer, line)

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

Parameters:

Return:

buffer.convert_eols(buffer, mode)

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

Parameters:

buffer.copy(buffer)

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.

Parameters:

buffer.copy_allow_line(buffer)

Copies the selected text or the current line to the clipboard.

Parameters:

buffer.copy_range(buffer, start_pos, end_pos)

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

Parameters:

buffer.copy_text(buffer, text)

Copies string text to the clipboard.

Parameters:

buffer.count_characters(buffer, 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:

buffer.cut(buffer)

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.

Parameters:

buffer.del_line_left(buffer)

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

Parameters:

buffer.del_line_right(buffer)

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

Parameters:

buffer.del_word_left(buffer)

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.

Parameters:

buffer.del_word_right(buffer)

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.

Parameters:

buffer.del_word_right_end(buffer)

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.

Parameters:

buffer.delete(buffer)

Deletes the buffer. Do not call this function. Call io.close_buffer() instead. Emits a BUFFER_DELETED event.

Parameters:

See also:

buffer.delete_back(buffer)

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

Parameters:

buffer.delete_back_not_line(buffer)

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.

Parameters:

buffer.delete_range(buffer, pos, length)

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

Parameters:

buffer.doc_line_from_visible(buffer, display_line)

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

Parameters:

Return:

buffer.document_end(buffer)

Moves the caret to the end of the buffer.

Parameters:

buffer.document_end_extend(buffer)

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

Parameters:

buffer.document_start(buffer)

Moves the caret to the beginning of the buffer.

Parameters:

buffer.document_start_extend(buffer)

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

Parameters:

buffer.drop_selection_n(buffer, n)

Drops existing selection number n.

Parameters:

buffer.edit_toggle_overtype(buffer)

Toggles buffer.overtype.

Parameters:

buffer.empty_undo_buffer(buffer)

Deletes the undo and redo history.

Parameters:

buffer.end_undo_action(buffer)

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

Parameters:

buffer.ensure_visible(buffer, line)

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

Parameters:

buffer.ensure_visible_enforce_policy(buffer, line)

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

Parameters:

buffer.find_column(buffer, 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.fold_all(buffer, 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:

buffer.fold_children(buffer, line, action)

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

Parameters:

buffer.fold_line(buffer, line, action)

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

Parameters:

buffer.get_cur_line(buffer)

Returns the current line’s text and the caret’s position on that line, starting from zero.

Parameters:

Return:

buffer.get_last_child(buffer, 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:

buffer.get_lexer(buffer, 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.get_line(buffer, line)

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

Parameters:

Return:

buffer.get_line_sel_end_position(buffer, line)

Returns the position of the end of the selected text on line number line, or -1 if line has no selection.

Parameters:

buffer.get_line_sel_start_position(buffer, line)

Returns the position of the beginning of the selected text on line number line, or -1 if line has no selection.

Parameters:

buffer.get_sel_text(buffer)

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

Parameters:

Return:

buffer.get_text(buffer)

Returns the buffer’s text.

Parameters:

buffer.goto_line(buffer, line)

Moves the caret to the beginning of line number line and scrolls it into view, regardless of whether line is hidden or not.

Parameters:

buffer.goto_pos(buffer, pos)

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

Parameters:

buffer.hide_lines(buffer, 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 and the first line cannot be hidden.

Parameters:

buffer.home(buffer)

Moves the caret to the beginning of the current line.

Parameters:

buffer.home_display(buffer)

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

Parameters:

buffer.home_display_extend(buffer)

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

Parameters:

buffer.home_extend(buffer)

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

Parameters:

buffer.home_rect_extend(buffer)

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

Parameters:

buffer.home_wrap(buffer)

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

Parameters:

buffer.home_wrap_extend(buffer)

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

Parameters:

buffer.indicator_all_on_for(buffer, pos)

Returns a bit-mask that represents which indicators are on at position pos. Bit 0 is set if indicator 0 is on, bit 1 for indicator 1, etc.

Parameters:

Return:

buffer.indicator_clear_range(buffer, pos, length)

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

Parameters:

buffer.indicator_end(buffer, indicator, pos)

Returns the next boundary position, starting from position pos, of indicator number indicator, in the range of 0 to 31. Returns buffer.length if indicator was not found.

Parameters:

buffer.indicator_fill_range(buffer, pos, length)

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

Parameters:

buffer.indicator_start(buffer, indicator, pos)

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

Parameters:

buffer.insert_text(buffer, 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.is_range_word(buffer, start_pos, end_pos)

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

Parameters:

buffer.line_copy(buffer)

Copies the current line to the clipboard.

Parameters:

buffer.line_cut(buffer)

Cuts the current line to the clipboard.

Parameters:

buffer.line_delete(buffer)

Deletes the current line.

Parameters:

buffer.line_down(buffer)

Moves the caret down one line.

Parameters:

buffer.line_down_extend(buffer)

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

Parameters:

buffer.line_down_rect_extend(buffer)

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

Parameters:

buffer.line_duplicate(buffer)

Duplicates the current line on a new line below.

Parameters:

buffer.line_end(buffer)

Moves the caret to the end of the current line.

Parameters:

buffer.line_end_display(buffer)

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

Parameters:

buffer.line_end_display_extend(buffer)

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

Parameters:

buffer.line_end_extend(buffer)

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

Parameters:

buffer.line_end_rect_extend(buffer)

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

Parameters:

buffer.line_end_wrap(buffer)

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

Parameters:

buffer.line_end_wrap_extend(buffer)

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

Parameters:

buffer.line_from_position(buffer, pos)

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

Parameters:

Return:

buffer.line_length(buffer, 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] - buffer.position_from_line(line).

Parameters:

Return:

buffer.line_scroll(buffer, columns, lines)

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

Parameters:

buffer.line_scroll_down(buffer)

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

Parameters:

buffer.line_scroll_up(buffer)

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

Parameters:

buffer.line_transpose(buffer)

Swaps the current line with the previous one.

Parameters:

buffer.line_up(buffer)

Moves the caret up one line.

Parameters:

buffer.line_up_extend(buffer)

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

Parameters:

buffer.line_up_rect_extend(buffer)

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

Parameters:

buffer.lines_join(buffer)

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

Parameters:

buffer.lines_split(buffer, pixel_width, 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:

buffer.lower_case(buffer)

Converts the selected text to lower case letters.

Parameters:

buffer.margin_text_clear_all(buffer)

Clears all text in text margins.

Parameters:

buffer.marker_add(buffer, line, marker)

Adds marker number marker, in the range of 0 to 31, 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 0 if line is invalid.

Parameters:

Return:

buffer.marker_add_set(buffer, 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 0, the second bit for marker number 1, and so on up to marker number 31.

Parameters:

buffer.marker_define(buffer, marker, symbol)

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

Parameters:

See also:

buffer.marker_define_pixmap(buffer, marker, pixmap)

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

Parameters:

buffer.marker_define_rgba_image(buffer, marker, pixels)

Associates marker number marker, in the range of 0 to 31, with RGBA image pixels. The dimensions for pixels (buffer.rgba_image_width and buffer.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 buffer.MARK_RGBAIMAGE marker symbol must be assigned to marker. pixels is shown in symbol margins next to lines marked with marker.

Parameters:

buffer.marker_delete(buffer, line, marker)

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

Parameters:

buffer.marker_delete_all(buffer, marker)

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

Parameters:

buffer.marker_delete_handle(buffer, handle)

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

Parameters:

buffer.marker_enable_highlight(buffer, enabled)

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

Parameters:

buffer.marker_get(buffer, line)

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

Parameters:

Return:

buffer.marker_line_from_handle(buffer, handle)

Returns the line number that marker handle handle, returned by buffer.marker_add(), was added to, or -1 if the line was not found.

Parameters:

Return:

buffer.marker_next(buffer, line, marker_mask)

Returns the first line number, starting at line number line, that has had all of the markers represented by marker bit-mask marker_mask added to it. Returns -1 if no line was found. Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31.

Parameters:

Return:

buffer.marker_previous(buffer, line, marker_mask)

Returns the last line number, before or on line number line, that has had all of the markers represented by marker bit-mask marker_mask added to it. Returns -1 if no line was found. Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31.

Parameters:

Return:

buffer.marker_symbol_defined(buffer, marker)

Returns the symbol assigned to marker number marker, in the range of 0 to 31, used in buffer.marker_define(), buffer.marker_define_pixmap(), or buffer.marker_define_rgba_image().

Parameters:

Return:

buffer.move_caret_inside_view(buffer)

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

Parameters:

buffer.move_selected_lines_down(buffer)

Shifts the selected lines down one line.

Parameters:

buffer.move_selected_lines_up(buffer)

Shifts the selected lines up one line.

Parameters:

buffer.multi_edge_add_line(buffer, column, color)

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

Parameters:

buffer.multi_edge_clear_all(buffer)

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

Parameters:

buffer.multiple_select_add_each(buffer)

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.

Parameters:

buffer.multiple_select_add_next(buffer)

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.

Parameters:

buffer.new()

Creates and returns a new buffer. Emits a BUFFER_NEW event.

Return:

See also:

buffer.new_line(buffer)

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

Parameters:

buffer.page_down(buffer)

Moves the caret down one page.

Parameters:

buffer.page_down_extend(buffer)

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

Parameters:

buffer.page_down_rect_extend(buffer)

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

Parameters:

buffer.page_up(buffer)

Moves the caret up one page.

Parameters:

buffer.page_up_extend(buffer)

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

Parameters:

buffer.page_up_rect_extend(buffer)

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

Parameters:

buffer.para_down(buffer)

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

Parameters:

buffer.para_down_extend(buffer)

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

Parameters:

buffer.para_up(buffer)

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

Parameters:

buffer.para_up_extend(buffer)

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

Parameters:

buffer.paste(buffer)

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

Parameters:

buffer.position_after(buffer, pos)

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

Parameters:

buffer.position_before(buffer, pos)

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

Parameters:

Return:

buffer.position_from_line(buffer, line)

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

Parameters:

Return:

buffer.position_relative(buffer, pos, n)

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

Parameters:

Return:

buffer.redo(buffer)

Redoes the next undone action.

Parameters:

buffer.register_image(buffer, type, xpm_data)

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

Parameters:

buffer.register_rgba_image(buffer, type, pixels)

Registers RGBA image pixels to type number type for use in autocompletion and user lists. The dimensions for pixels (buffer.rgba_image_width and buffer.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.replace_sel(buffer, text)

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

Parameters:

buffer.replace_target(buffer, 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:

buffer.replace_target_re(buffer, 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:

buffer.rotate_selection(buffer)

Designates the next additional selection to be the main selection.

Parameters:

buffer.scroll_caret(buffer)

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

Parameters:

See also:

buffer.scroll_range(buffer, 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 buffer.scroll_caret(), but with primary_pos instead of buffer.current_pos. This is useful for scrolling search results into view.

Parameters:

buffer.scroll_to_end(buffer)

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

Parameters:

buffer.scroll_to_start(buffer)

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

Parameters:

buffer.search_anchor(buffer)

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

Parameters:

buffer.search_in_target(buffer, 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:

See also:

buffer.search_next(buffer, 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(buffer, 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:

buffer.select_all(buffer)

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

Parameters:

buffer.selection_duplicate(buffer)

Duplicates the selected text to its right. If no text is selected, duplicates the current line on a new line below.

Parameters:

buffer.set_chars_default(buffer)

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

Parameters:

See also:

buffer.set_empty_selection(buffer, pos)

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

Parameters:

buffer.set_encoding(buffer, encoding)

Converts the current buffer’s contents to encoding encoding.

Parameters:

Usage:

buffer.set_fold_margin_colour(buffer, use_setting, color)

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

Parameters:

buffer.set_fold_margin_hi_colour(buffer, use_setting, color)

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

Parameters:

buffer.set_lexer(buffer, lexer)

Associates lexer name lexer or the auto-detected lexer name with the buffer and then loads the appropriate language module if that module exists.

Parameters:

Usage:

buffer.set_save_point(buffer)

Indicates the buffer has no unsaved changes.

Parameters:

buffer.set_sel(buffer, start_pos, end_pos)

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

Parameters:

buffer.set_sel_back(buffer, use_setting, color)

Overrides the selection’s default background color with color color, in “0xBBGGRR” format, if use_setting is true. Overwrites any existing buffer.additional_sel_back color.

Parameters:

buffer.set_sel_fore(buffer, use_setting, color)

Overrides the selection’s default foreground color with color color, in “0xBBGGRR” format, if use_setting is true. Overwrites any existing buffer.additional_sel_fore color.

Parameters:

buffer.set_selection(buffer, end_pos, start_pos)

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

Parameters:

buffer.set_styling(buffer, length, style)

Assigns style number style, in the range from 0 to 255, 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:

buffer.set_target_range(buffer, start_pos, end_pos)

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

Parameters:

buffer.set_text(buffer, text)

Replaces the buffer’s text with string text.

Parameters:

buffer.set_visible_policy(buffer, policy, y)

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

Parameters:

buffer.set_whitespace_back(buffer, use_setting, color)

Overrides the background color of whitespace with color color, in “0xBBGGRR” format, if use_setting is true.

Parameters:

buffer.set_whitespace_fore(buffer, use_setting, color)

Overrides the foreground color of whitespace with color color, in “0xBBGGRR” format, if use_setting is true.

Parameters:

buffer.set_x_caret_policy(buffer, 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:

buffer.set_y_caret_policy(buffer, 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:

buffer.show_lines(buffer, 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:

buffer.start_styling(buffer, position, style_mask)

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:

See also:

buffer.stuttered_page_down(buffer)

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

Parameters:

buffer.stuttered_page_down_extend(buffer)

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

Parameters:

buffer.stuttered_page_up(buffer)

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

Parameters:

buffer.stuttered_page_up_extend(buffer)

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

Parameters:

buffer.style_clear_all(buffer)

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

Parameters:

buffer.style_reset_default(buffer)

Resets buffer.STYLE_DEFAULT to its initial state.

Parameters:

buffer.swap_main_anchor_caret(buffer)

Swaps the main selection’s beginning and end positions.

Parameters:

buffer.tab(buffer)

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

Parameters:

buffer.target_from_selection(buffer)

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

Parameters:

buffer.target_whole_document(buffer)

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

Parameters:

buffer.text_height(buffer, line)

Returns the pixel height of line number line.

Parameters:

Return:

buffer.text_range(buffer, start_pos, end_pos)

Returns the range of text between positions start_pos and end_pos.

Parameters:

buffer.text_width(buffer, style_num, text)

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

Parameters:

Return:

buffer.toggle_caret_sticky(buffer)

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

Parameters:

See also:

buffer.toggle_fold(buffer, 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:

buffer.toggle_fold_display_text(buffer, 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 after the line. text is drawn with style number buffer.STYLE_FOLDDISPLAYTEXT.

Parameters:

buffer.undo(buffer)

Undoes the most recent action.

Parameters:

buffer.upper_case(buffer)

Converts the selected text to upper case letters.

Parameters:

buffer.user_list_show(buffer, 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 a USER_LIST_SELECTION event along with the selection.

Parameters:

See also:

buffer.vc_home(buffer)

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

Parameters:

buffer.vc_home_display(buffer)

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.

Parameters:

buffer.vc_home_display_extend(buffer)

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

Parameters:

buffer.vc_home_extend(buffer)

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

Parameters:

buffer.vc_home_rect_extend(buffer)

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

Parameters:

buffer.vc_home_wrap(buffer)

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

Parameters:

buffer.vc_home_wrap_extend(buffer)

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

Parameters:

buffer.vertical_centre_caret(buffer)

Centers current line in the view.

Parameters:

buffer.visible_from_doc_line(buffer, line)

Returns the displayed line number of actual line number line, taking 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:

buffer.word_end_position(buffer, 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.word_left(buffer)

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

Parameters:

buffer.word_left_end(buffer)

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.

Parameters:

buffer.word_left_end_extend(buffer)

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

Parameters:

buffer.word_left_extend(buffer)

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.

Parameters:

buffer.word_part_left(buffer)

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.

Parameters:

buffer.word_part_left_extend(buffer)

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.

Parameters:

buffer.word_part_right(buffer)

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.

Parameters:

buffer.word_part_right_extend(buffer)

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.

Parameters:

buffer.word_right(buffer)

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

Parameters:

buffer.word_right_end(buffer)

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.

Parameters:

buffer.word_right_end_extend(buffer)

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

Parameters:

buffer.word_right_extend(buffer)

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.

Parameters:

buffer.word_start_position(buffer, 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.wrap_count(buffer, line)

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

Parameters:

Return:

buffer.zoom_in(buffer)

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

Parameters:

buffer.zoom_out(buffer)

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

Parameters:


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 true or false boolean value, 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.

Fields defined by events

events.APPLEEVENT_ODOC (string)

Emitted when Mac OSX tells Textadept to open a file. Arguments:

events.AUTO_C_CANCELED (string)

Emitted when canceling an autocompletion or user list.

events.AUTO_C_CHAR_DELETED (string)

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

events.AUTO_C_COMPLETED (string)

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

events.AUTO_C_SELECTION (string)

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

events.BUFFER_AFTER_SWITCH (string)

Emitted right after switching to another buffer. Emitted by view.goto_buffer().

events.BUFFER_BEFORE_SWITCH (string)

Emitted right before switching to another buffer. Emitted by view.goto_buffer().

events.BUFFER_DELETED (string)

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

events.BUFFER_NEW (string)

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

events.CALL_TIP_CLICK (string)

Emitted when clicking on a calltip. Arguments:

events.CHAR_ADDED (string)

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

events.CSI (string)

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

events.DOUBLE_CLICK (string)

Emitted after double-clicking the mouse button. Arguments:

events.DWELL_END (string)

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

events.DWELL_START (string)

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

events.ERROR (string)

Emitted when an error occurs. Arguments:

events.FIND (string)

Emitted to find text via the Find & Replace Pane. Arguments:

events.FOCUS (string)

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

events.INDICATOR_CLICK (string)

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

events.INDICATOR_RELEASE (string)

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

events.INITIALIZED (string)

Emitted after Textadept finishes initializing.

events.KEYPRESS (string)

Emitted when pressing a key. If any handler returns true, the key is not inserted into the buffer. Arguments:

events.MARGIN_CLICK (string)

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

events.MENU_CLICKED (string)

Emitted after selecting a menu item. Arguments:

events.MOUSE (string)

Emitted by the terminal version for an unhandled mouse event. Arguments:

events.QUIT (string)

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 (string)

Emitted to replace selected (found) text. Arguments:

events.REPLACE_ALL (string)

Emitted to replace all occurrences of found text. Arguments:

events.RESET_AFTER (string)

Emitted after resetting the Lua state. Emitted by reset().

events.RESET_BEFORE (string)

Emitted before resetting the Lua state. Emitted by reset().

events.RESUME (string)

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

events.SAVE_POINT_LEFT (string)

Emitted after leaving a save point.

events.SAVE_POINT_REACHED (string)

Emitted after reaching a save point.

events.SUSPEND (string)

Emitted when suspending Textadept. If any handler returns true, Textadept does not suspend. This event is only emitted by the terminal version.

events.TAB_CLICKED (string)

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. Arguments:

events.UPDATE_UI (string)

Emitted after the view is visually updated. Arguments:

events.URI_DROPPED (string)

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

events.USER_LIST_SELECTION (string)

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

events.VIEW_AFTER_SWITCH (string)

Emitted right after switching to another view. Emitted by ui.goto_view().

events.VIEW_BEFORE_SWITCH (string)

Emitted right before switching to another view. Emitted by ui.goto_view().

events.VIEW_NEW (string)

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

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:

See also:

events.disconnect(event, f)

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

Parameters:

See also:

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 true or false, 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.

Parameters:

Usage:

Return:


The io Module


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

Fields defined by io

events.FILE_AFTER_SAVE (string)

Emitted right after saving a file to disk. Emitted by io.save_file() and io.save_file_as(). Arguments:

events.FILE_BEFORE_SAVE (string)

Emitted right before saving a file to disk. Emitted by io.save_file(). Arguments:

events.FILE_CHANGED (string)

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 (string)

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

io.quick_open_max (number)

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

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:

See also:

io.close_buffer()

Closes the current buffer, prompting the user to continue if there are unsaved changes, and returns true if the buffer was closed.

Return:

io.get_project_root(path)

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, Git, Mercurial, and SVN.

Parameters:

Return:

io.open_file(filenames)

Opens filenames, a string filename or list of filenames, or the user-selected filenames. Emits a FILE_OPENED event.

Parameters:

See also:

io.open_recent_file()

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

See also:

io.quick_open(paths, filter, opts)

Prompts the user to select files to be opened from paths, a string directory path or list of directory paths, using a filtered list dialog. If paths is nil, uses the current project’s root directory, which is obtained from io.get_project_root(). Files shown in the dialog do not match any pattern in either string or table filter (or lfs.default_filter if filter is nil). A filter table contains:

Any filter patterns starting with ‘!’ exclude files and directories that do not match the pattern that follows. The number of files in the list is capped at quick_open_max. If filter is nil and paths is ultimately a string, the filter from the io.quick_open_filters table is used in place of lfs.default_filter if the former exists. opts is an optional table of additional options for ui.dialogs.filteredlist().

Parameters:

Usage:

See also:

io.reload_file()

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

io.save_all_files()

Saves all unsaved buffers to their respective files.

See also:

io.save_file()

Saves the current buffer to its file. Emits FILE_BEFORE_SAVE and FILE_AFTER_SAVE events.

io.save_file_as(filename)

Saves the current buffer to file filename or the user-specified filename. Emits a FILE_AFTER_SAVE event.

Parameters:

Tables defined by io

io.encodings

List of encodings to attempt to decode files as. 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.quick_open_filters

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

See also:

io.recent_files

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


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 language (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 language modules to override commands like autocompletion, 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 curses. On Mac OSX they are “Control” (^), “Alt/Option” (), “Command” (), and “Shift” (). These modifiers have the following string representations:

Modifier Linux / Win32 Mac OSX curses
Control 'c' 'c' 'c'
Alt 'a' 'a' 'm'
Command N/A 'm' N/A
Shift 's' 's' 's'

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 caA on Windows and Linux, but a combination of Ctrl+Shift+Tab has the key sequence cs\t. On a United States English keyboard, since the combination of Ctrl+Shift+, has the key sequence c< (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 cright. 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['cn'] = buffer.new
keys['cz'] = buffer.undo
keys['cu'] = function() io.quick_open(_USERHOME) end

Textadept handles buffer 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

Key Chains

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

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

Fields defined by keys

keys.CLEAR (string)

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.MODE (string)

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

Tables defined by keys

keys.KEYSYMS

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.

_G.keys

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

keys.keychain

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


The lexer Module


Lexes Scintilla documents with Lua and LPeg.

Overview

Lexers highlight the syntax of source code. 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.

Lexers are Parsing Expression Grammars, or PEGs, composed with the Lua LPeg library. 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 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 match.
-patt Equivalent to ("" - patt).
#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 custom coloring and 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 LPeg lexers with the aforementioned Textadept and SciTE editors. Finally there are comments on lexer performance and limitations.

Lexer Basics

The lexers/ directory contains all lexers, including your new one. Before attempting to write one from scratch though, first determine if your programming language is similar to any of the 80+ languages supported. If so, you may be able to copy and modify 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.

Note: Try to refrain from using one-character language names like “c”, “d”, or “r”. For example, Scintillua uses “ansi_c”, “dmd”, and “rstats”, respectively.

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 ‘?’s with the name of your lexer:

-- ? LPeg lexer.

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

local M = {_NAME = '?'}

-- Whitespace.
local ws = token(l.WHITESPACE, l.space^1)

M._rules = {
  {'whitespace', ws},
}

M._tokenstyles = {

}

return M

The first 3 lines of code simply define often used convenience variables. The 5th and last lines define and return the lexer object Scintilla uses; they are very important and must be part of every lexer. The sixth line defines something called a “token”, an essential building block of lexers. You will learn about tokens shortly. The rest of the code defines a set of grammar rules and token styles. You will learn about those later. Note, however, the M. prefix in front of _rules and _tokenstyles: not only do these tables belong to their respective lexers, but any non-local variables need the M. prefix too so-as not to affect Lua’s global environment. All in all, this is a minimal, working lexer that you can build on.

Tokens

Take a moment to think about your programming language’s structure. What kind of key elements does it have? In the template shown earlier, one predefined element all languages have is whitespace. Your language probably also has elements like comments, strings, and keywords. Lexers refer to these elements as “tokens”. Tokens are the fundamental “building blocks” of lexers. Lexers break down source code into tokens for coloring, which results in the syntax highlighting familiar to you. It is up to you how specific your lexer is when it comes to tokens. 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, defines 11 tokens: whitespace, comments, strings, numbers, keywords, built-in functions, constants, built-in libraries, identifiers, labels, and operators. Even though constants, built-in functions, and built-in libraries 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, tokens consist of a token name and an LPeg pattern that matches a sequence of characters recognized as an instance of that token. Create tokens using the lexer.token() function. Let us examine the “whitespace” token defined in the template shown earlier:

local ws = token(l.WHITESPACE, l.space^1)

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:

local ws = token('whitespace', S('\t\v\f\n\r ')^1)

The lexer (l) module actually provides a convenient list of common token names and common LPeg patterns for you to use. Token names include lexer.DEFAULT, lexer.WHITESPACE, lexer.COMMENT, lexer.STRING, lexer.NUMBER, lexer.KEYWORD, lexer.IDENTIFIER, lexer.OPERATOR, lexer.ERROR, lexer.PREPROCESSOR, lexer.CONSTANT, lexer.VARIABLE, lexer.FUNCTION, lexer.CLASS, lexer.TYPE, lexer.LABEL, lexer.REGEX, and lexer.EMBEDDED. Patterns include lexer.any, lexer.ascii, lexer.extend, lexer.alpha, lexer.digit, lexer.alnum, lexer.lower, lexer.upper, lexer.xdigit, lexer.cntrl, lexer.graph, lexer.print, lexer.punct, lexer.space, lexer.newline, lexer.nonnewline, lexer.nonnewline_esc, lexer.dec_num, lexer.hex_num, lexer.oct_num, lexer.integer, lexer.float, and lexer.word. You may use your own token names if none of the above fit your language, but an advantage to using predefined token names is that your lexer’s tokens will inherit the universal syntax highlighting color theme used by your text editor.

Example Tokens

So, how might you define other tokens like comments, strings, and keywords? Here are some examples.

Comments

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

local shell_comment = token(l.COMMENT, '#' * l.nonnewline^0)
local c_line_comment = token(l.COMMENT, '//' * l.nonnewline_esc^0)

The comments above start with a ‘#’ or “//” and go to the end of the line. 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 = token(l.COMMENT, '/*' * (l.any - '*/')^0 * P('*/')^-1)

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

It is tempting to think that a string is not much different from the block comment shown above in that both have start and end delimiters:

local dq_str = '"' * (l.any - '"')^0 * P('"')^-1
local sq_str = "'" * (l.any - "'")^0 * P("'")^-1
local simple_string = token(l.STRING, dq_str + sq_str)

However, 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. The above token incorrectly matches such a string. Instead, use the lexer.delimited_range() convenience function.

local dq_str = l.delimited_range('"')
local sq_str = l.delimited_range("'")
local string = token(l.STRING, dq_str + sq_str)

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

Keywords

Instead of matching n keywords with n P('keyword_n') ordered choices, use another convenience function: lexer.word_match(). It is much easier and more efficient to write word matches like:

local keyword = token(l.KEYWORD, l.word_match{
  'keyword_1', 'keyword_2', ..., 'keyword_n'
})

local case_insensitive_keyword = token(l.KEYWORD, l.word_match({
  'KEYWORD_1', 'keyword_2', ..., 'KEYword_n'
}, nil, true))

local hyphened_keyword = token(l.KEYWORD, l.word_match({
  'keyword-1', 'keyword-2', ..., 'keyword-n'
}, '-'))

By default, characters considered to be in keywords are in the set of alphanumeric characters and underscores. The last token demonstrates how to allow ‘-’ (hyphen) characters to be in keywords as well.

Numbers

Most programming languages have the same format for integer and float tokens, so it might be as simple as using a couple of predefined LPeg patterns:

local number = token(l.NUMBER, l.float + l.integer)

However, some languages allow postfix characters on integers.

local integer = P('-')^-1 * (l.dec_num * S('lL')^-1)
local number = token(l.NUMBER, l.float + l.hex_num + integer)

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 token structure. For example, comments usually cannot appear within a string. Grammars consist of rules, which are simply combinations of tokens. Recall from the lexer template the _rules table, which defines all the rules used by the lexer grammar:

M._rules = {
  {'whitespace', ws},
}

Each entry in a lexer’s _rules table consists of a rule name and its associated pattern. 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, the lexer tries the second rule, and so on. This simple grammar says to match whitespace tokens under a rule named “whitespace”.

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

M._rules = {
  {'whitespace', ws},
  {'keyword', keyword},
  {'identifier', identifier},
  {'string', string},
  {'comment', comment},
  {'number', number},
  {'label', label},
  {'operator', operator},
}

Note 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 specified the “identifier” rule before the “keyword” rule, all keywords would match identifiers and thus incorrectly highlight as identifiers instead of keywords. The same idea applies to function, constant, etc. tokens 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 an additional end rule:

M._rules = {
  {'whitespace', ws},
  {'error', token(l.ERROR, l.any)},
}

This identifies and highlights any character not matched by an existing rule as an lexer.ERROR token.

Even though the rules defined in the examples above contain a single token, rules may consist of multiple tokens. For example, a rule for an HTML tag could consist of a tag token followed by an arbitrary number of attribute tokens, allowing the lexer to highlight all tokens separately. The rule might look something like this:

{'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.

Summary

Lexers primarily consist of tokens and grammar rules. At your disposal are a number of convenience patterns and functions for rapidly creating a lexer. If you choose to use predefined token names for your tokens, you do not have to define how the lexer highlights them. The tokens will inherit the default syntax highlighting color theme your editor uses.

Advanced Techniques

Styles and Styling

The most basic form of syntax highlighting is assigning different colors to different tokens. Instead of highlighting with just colors, Scintilla allows for more rich highlighting, or “styling”, with different fonts, font sizes, font attributes, and foreground and background colors, just to name a few. The unit of this rich highlighting is called a “style”. Styles are simply strings of comma-separated property settings. By default, lexers associate predefined token names like lexer.WHITESPACE, lexer.COMMENT, lexer.STRING, etc. with particular styles as part of a universal color theme. These predefined styles include lexer.STYLE_CLASS, lexer.STYLE_COMMENT, lexer.STYLE_CONSTANT, lexer.STYLE_ERROR, lexer.STYLE_EMBEDDED, lexer.STYLE_FUNCTION, lexer.STYLE_IDENTIFIER, lexer.STYLE_KEYWORD, lexer.STYLE_LABEL, lexer.STYLE_NUMBER, lexer.STYLE_OPERATOR, lexer.STYLE_PREPROCESSOR, lexer.STYLE_REGEX, lexer.STYLE_STRING, lexer.STYLE_TYPE, lexer.STYLE_VARIABLE, and lexer.STYLE_WHITESPACE. Like with predefined token names and LPeg patterns, you may define your own styles. At their core, styles are just strings, so you may create new ones and/or modify existing ones. Each style consists of the following comma-separated settings:

Setting Description
font:name The name of the font the style uses.
size:int The size of the font the style uses.
[not]bold Whether or not the font face is bold.
weight:int The weight or boldness of a font, between 1 and 999.
[not]italics Whether or not the font face is italic.
[not]underlined Whether or not the font face is underlined.
fore:color The foreground color of the font face.
back:color The background color of the font face.
[not]eolfilled Does the background color extend to the end of the line?
case:char The case of the font (‘u’: upper, ‘l’: lower, ’m': normal).
[not]visible Whether or not the text is visible.
[not]changeable Whether the text is changeable or read-only.

Specify font colors in either “#RRGGBB” format, “0xBBGGRR” format, or the decimal equivalent of the latter. As with token names, LPeg patterns, and styles, there is a set of predefined color names, but they vary depending on the current color theme in use. Therefore, it is generally not a good idea to manually define colors within styles in your lexer since they might not fit into a user’s chosen color theme. Try to refrain from even using predefined colors in a style because that color may be theme-specific. Instead, the best practice is to either use predefined styles or derive new color-agnostic styles from predefined ones. For example, Lua “longstring” tokens use the existing lexer.STYLE_STRING style instead of defining a new one.

Example Styles

Defining styles is pretty straightforward. An empty style that inherits the default theme settings is simply an empty string:

local style_nothing = ''

A similar style but with a bold font face looks like this:

local style_bold = 'bold'

If you want the same style, but also with an italic font face, define the new style in terms of the old one:

local style_bold_italic = style_bold..',italics'

This allows you to derive new styles from predefined ones without having to rewrite them. This operation leaves the old style unchanged. Thus if you had a “static variable” token whose style you wanted to base off of lexer.STYLE_VARIABLE, it would probably look like:

local style_static_var = l.STYLE_VARIABLE..',italics'

The color theme files in the lexers/themes/ folder give more examples of style definitions.

Token Styles

Lexers use the _tokenstyles table to assign tokens to particular styles. Recall the token definition and _tokenstyles table from the lexer template:

local ws = token(l.WHITESPACE, l.space^1)

...

M._tokenstyles = {

}

Why is a style not assigned to the lexer.WHITESPACE token? As mentioned earlier, lexers automatically associate tokens that use predefined token names with a particular style. Only tokens with custom token names need manual style associations. As an example, consider a custom whitespace token:

local ws = token('custom_whitespace', l.space^1)

Assigning a style to this token looks like:

M._tokenstyles = {
  custom_whitespace = l.STYLE_WHITESPACE
}

Do not confuse token names with rule names. They are completely different entities. In the example above, the lexer assigns the “custom_whitespace” token the existing style for WHITESPACE tokens. If instead you want to color the background of whitespace a shade of grey, it might look like:

local custom_style = l.STYLE_WHITESPACE..',back:$(color.grey)'
M._tokenstyles = {
  custom_whitespace = custom_style
}

Notice that the lexer peforms Scintilla/SciTE-style “$()” property expansion. You may also use “%()”. Remember to refrain from assigning specific colors in styles, but in this case, all user color themes probably define the “color.grey” property.

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, use the _LEXBYLINE field:

M._LEXBYLINE = 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 at subsequent lines.

Embedded Lexers

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 within 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 = l.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 index
  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 a value instead of nil. In this case, the value returned does not matter because 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_lexer() function:

l.embed_lexer(M, css, css_start_rule, css_end_rule)

The first parameter is the parent lexer object to embed the child in, which in this case is M. The other three parameters are the child lexer object loaded earlier followed by its start and end rules.

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, swap the lexer object arguments to lexer.embed_lexer(). For example, in the PHP lexer:

local html = l.load('html')
local php_start_rule = token('php_tag', '<?php ')
local php_end_rule = token('php_tag', '?>')
l.embed_lexer(html, M, php_start_rule, php_end_rule)

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’s _foldsymbols table allows you to conveniently define fold points with such granularity. For example, consider C:

M._foldsymbols = {
  [l.OPERATOR] = {['{'] = 1, ['}'] = -1},
  [l.COMMENT] = {['/*'] = 1, ['*/'] = -1},
  _patterns = {'[{}]', '/%*', '%*/'}
}

The first assignment states that any ‘{’ or ‘}’ that the lexer recognized as an lexer.OPERATOR token is a fold point. The integer 1 indicates the match is a beginning fold point and -1 indicates the match is an ending fold point. Likewise, the second assignment states that any “/*” or “*/” that the lexer recognizes as part of a lexer.COMMENT token is a fold point. The lexer does not consider any occurences of these characters outside their defined tokens (such as in a string) as fold points. Finally, every _foldsymbols table must have a _patterns field that contains a list of Lua patterns that match fold points. If the lexer encounters text that matches one of those patterns, the lexer looks up the matched text in its token’s table in order to determine whether or not the text is a fold point. In the example above, the first Lua pattern matches any ‘{’ or ‘}’ characters. When the lexer comes across one of those characters, it checks if the match is an lexer.OPERATOR token. If so, the lexer identifies the match as a fold point. The same idea applies for the other patterns. (The ‘%’ is in the other patterns because ‘*’ is a special character in Lua patterns that needs escaping.) How do you specify fold keywords? Here is an example for Lua:

M._foldsymbols = {
  [l.KEYWORD] = {
    ['if'] = 1, ['do'] = 1, ['function'] = 1,
    ['end'] = -1, ['repeat'] = 1, ['until'] = -1
  },
  _patterns = {'%l+'}
}

Any time the lexer encounters a lower case word, if that word is a lexer.KEYWORD token and in the associated list of fold points, the lexer identifies the word as a fold point.

If your lexer has case-insensitive keywords as fold points, simply add a _case_insensitive = true option to the _foldsymbols table and specify keywords in lower case.

If your lexer needs to do some additional processing to determine if a match is a fold point, assign a function that returns an integer. Returning 1 or -1 indicates the match is a fold point. Returning 0 indicates it is not. For example:

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

M._foldsymbols = {
  ['strange_token'] = {['|'] = fold_strange_token},
  _patterns = {'|'}
}

Any time the lexer encounters a ‘|’ that is a “strange_token”, it calls the fold_strange_token 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 matched text starts at, and the matched 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, use the _FOLDBYINDENTATION field:

M._FOLDBYINDENTATION = true

Using Lexers

Textadept

Put 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 type 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])=[lexer_name]

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.

Please note that Lua lexers ignore any styling information in .properties files. Your theme file in the lexers/themes/ directory contains styling information.

Considerations

Performance

There might be some slight overhead when initializing a lexer, but loading a file from disk into Scintilla is usually more expensive. On modern computer systems, I see no difference in speed between LPeg lexers and Scintilla’s C++ ones. Optimize lexers for speed by re-arranging rules in the _rules table so that the most common rules match first. Do keep in mind that order matters for similar rules.

Limitations

Embedded preprocessor languages like PHP cannot completely embed in their parent languages in that the parent’s tokens do not support start and end rules. This mostly goes unnoticed, but code like

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

or

<div <?php if ($odd) { echo 'class="odd"'; } ?>>

will not style correctly.

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 styling 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 inspired me, and thanks to Roberto Ierusalimschy for LPeg.

Fields defined by lexer

lexer.CLASS (string)

The token name for class tokens.

lexer.COMMENT (string)

The token name for comment tokens.

lexer.CONSTANT (string)

The token name for constant tokens.

lexer.DEFAULT (string)

The token name for default tokens.

lexer.ERROR (string)

The token name for error tokens.

lexer.FOLD_BASE (number)

The initial (root) fold level.

lexer.FOLD_BLANK (number)

Flag indicating that the line is blank.

lexer.FOLD_HEADER (number)

Flag indicating the line is fold point.

lexer.FUNCTION (string)

The token name for function tokens.

lexer.IDENTIFIER (string)

The token name for identifier tokens.

lexer.KEYWORD (string)

The token name for keyword tokens.

lexer.LABEL (string)

The token name for label tokens.

lexer.LEXERPATH (string)

The path used to search for a lexer to load. Identical in format to Lua’s package.path string. The default value is package.path.

lexer.NUMBER (string)

The token name for number tokens.

lexer.OPERATOR (string)

The token name for operator tokens.

lexer.PREPROCESSOR (string)

The token name for preprocessor tokens.

lexer.REGEX (string)

The token name for regex tokens.

lexer.STRING (string)

The token name for string tokens.

lexer.STYLE_BRACEBAD (string)

The style used for unmatched brace characters.

lexer.STYLE_BRACELIGHT (string)

The style used for highlighted brace characters.

lexer.STYLE_CALLTIP (string)

The style used by call tips if buffer.call_tip_use_style is set. Only the font name, size, and color attributes are used.

lexer.STYLE_CLASS (string)

The style typically used for class definitions.

lexer.STYLE_COMMENT (string)

The style typically used for code comments.

lexer.STYLE_CONSTANT (string)

The style typically used for constants.

lexer.STYLE_CONTROLCHAR (string)

The style used for control characters. Color attributes are ignored.

lexer.STYLE_DEFAULT (string)

The style all styles are based off of.

lexer.STYLE_EMBEDDED (string)

The style typically used for embedded code.

lexer.STYLE_ERROR (string)

The style typically used for erroneous syntax.

lexer.STYLE_FOLDDISPLAYTEXT (string)

The style used for fold display text.

lexer.STYLE_FUNCTION (string)

The style typically used for function definitions.

lexer.STYLE_IDENTIFIER (string)

The style typically used for identifier words.

lexer.STYLE_INDENTGUIDE (string)

The style used for indentation guides.

lexer.STYLE_KEYWORD (string)

The style typically used for language keywords.

lexer.STYLE_LABEL (string)

The style typically used for labels.

lexer.STYLE_LINENUMBER (string)

The style used for all margins except fold margins.

lexer.STYLE_NUMBER (string)

The style typically used for numbers.

lexer.STYLE_OPERATOR (string)

The style typically used for operators.

lexer.STYLE_PREPROCESSOR (string)

The style typically used for preprocessor statements.

lexer.STYLE_REGEX (string)

The style typically used for regular expression strings.

lexer.STYLE_STRING (string)

The style typically used for strings.

lexer.STYLE_TYPE (string)

The style typically used for static types.

lexer.STYLE_VARIABLE (string)

The style typically used for variables.

lexer.STYLE_WHITESPACE (string)

The style typically used for whitespace.

lexer.TYPE (string)

The token name for type tokens.

lexer.VARIABLE (string)

The token name for variable tokens.

lexer.WHITESPACE (string)

The token name for whitespace tokens.

lexer.alnum (pattern)

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

lexer.alpha (pattern)

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

lexer.any (pattern)

A pattern that matches any single character.

lexer.ascii (pattern)

A pattern that matches any ASCII character (codes 0 to 127).

lexer.cntrl (pattern)

A pattern that matches any control character (ASCII codes 0 to 31).

lexer.dec_num (pattern)

A pattern that matches a decimal number.

lexer.digit (pattern)

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

lexer.extend (pattern)

A pattern that matches any ASCII extended character (codes 0 to 255).

lexer.float (pattern)

A pattern that matches a floating point number.

lexer.fold_level (table, Read-only)

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

lexer.graph (pattern)

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

lexer.hex_num (pattern)

A pattern that matches a hexadecimal number.

lexer.indent_amount (table, Read-only)

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

lexer.integer (pattern)

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

lexer.line_state (table)

Table of integer line states for line numbers starting from zero. Line states can be used by lexers for keeping track of persistent states.

lexer.lower (pattern)

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

lexer.newline (pattern)

A pattern that matches any set of end of line characters.

lexer.nonnewline (pattern)

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

lexer.nonnewline_esc (pattern)

A pattern that matches any single, non-newline character or any set of end of line characters escaped with ‘\’.

lexer.oct_num (pattern)

A pattern that matches an octal number.

lexer.print (pattern)

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

lexer.property (table)

Map of key-value string pairs.

lexer.property_expanded (table, Read-only)

Map of key-value string pairs with $() and %() variable replacement performed in values.

lexer.property_int (table, Read-only)

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

lexer.punct (pattern)

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

lexer.space (pattern)

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

lexer.style_at (table, Read-only)

Table of style names at positions in the buffer starting from 1.

lexer.upper (pattern)

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

lexer.word (pattern)

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

lexer.xdigit (pattern)

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

Functions defined by lexer

lexer.delimited_range(chars, single_line, no_escape, balanced)

Creates and returns a pattern that matches a range of text bounded by chars characters. This is a convenience function for matching more complicated delimited ranges like strings with escape characters and balanced parentheses. single_line indicates whether or not the range must be on a single line, no_escape indicates whether or not to ignore ‘\’ as an escape character, and balanced indicates whether or not to handle balanced ranges like parentheses and requires chars to be composed of two characters.

Parameters:

Usage:

Return:

See also:

lexer.embed_lexer(parent, child, start_rule, end_rule)

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

Parameters:

Usage:

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

Determines fold points in a chunk of text text with lexer lexer. text starts at position start_pos on line number start_line with a beginning fold level of start_level in the buffer. If lexer has a _fold function or a _foldsymbols table, that field is used to perform folding. Otherwise, if lexer has a _FOLDBYINDENTATION field set, or if a fold.by.indentation property is set, folding by indentation is done.

Parameters:

Return:

lexer.fold_line_comments(prefix)

Returns a fold function (to be used within the lexer’s _foldsymbols table) that folds consecutive line comments that start with string prefix.

Parameters:

Usage:

lexer.last_char_includes(s)

Creates and returns a pattern that verifies that string set s contains the first non-whitespace character behind the current match position.

Parameters:

Usage:

Return:

lexer.lex(lexer, text, init_style)

Lexes a chunk of text text (that has an initial style number of init_style) with lexer lexer. If lexer has a _LEXBYLINE flag set, the text is lexed one line at a time. Otherwise the text is lexed as a whole.

Parameters:

Return:

lexer.line_from_position(pos)

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

Parameters:

Return:

lexer.load(name, alt_name, cache)

Initializes or loads and 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.nested_pair(start_chars, end_chars)

Returns a pattern that matches a balanced range of text that starts with string start_chars and ends with string end_chars. With single-character delimiters, this function is identical to delimited_range(start_chars..end_chars, false, true, true).

Parameters:

Usage:

Return:

See also:

lexer.starts_line(patt)

Creates and returns a pattern that matches pattern patt only at the beginning of a line.

Parameters:

Usage:

Return:

lexer.token(name, patt)

Creates and returns a token pattern with token name name and pattern patt. If name is not a predefined token name, its style must be defined in the lexer’s _tokenstyles table.

Parameters:

Usage:

Return:

lexer.word_match(words, word_chars, case_insensitive)

Creates and returns a pattern that matches any single word in list words. Words consist of alphanumeric and underscore characters, as well as the characters in string set word_chars. case_insensitive indicates whether or not to ignore case when matching words. This is a convenience function for simplifying a set of ordered choice word patterns.

Parameters:

Usage:

Return:

Tables defined by lexer

lexer.lexer

Individual fields for a lexer instance.

Fields:


The lfs Module


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

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.dir_foreach(dir, f, filter, n, include_dirs, level)

Iterates over all files and sub-directories (up to n levels deep) in directory dir, calling function f with each file found. Files passed to f do not match any pattern in string or table filter (or lfs.default_filter when filter is nil). A filter table contains:

Any filter patterns starting with ‘!’ exclude files and directories that do not match the pattern that follows.

Parameters:

See also:

Tables defined by lfs

lfs.default_filter

The filter table containing common binary file extensions and version control directories to exclude when iterating over files and directories using dir_foreach.

See also:


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 iconv, returning the string result. Valid encodings are GNU iconv’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 (number)

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(on, line)

Toggles the bookmark on line number line or the current line, unless on is given. If on is true or false, adds or removes the bookmark, respectively.

Parameters:


The textadept.editing Module


Editing features for Textadept.

Fields defined by textadept.editing

textadept.editing.INDIC_BRACEMATCH (number)

The matching brace highlight indicator number.

textadept.editing.INDIC_HIGHLIGHT (number)

The word highlight indicator number.

textadept.editing.auto_indent (bool)

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

textadept.editing.autocomplete_all_words (bool)

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.strip_trailing_spaces (bool)

Strip trailing whitespace before saving files. The default value is false.

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.block_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:

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.

See also:

textadept.editing.enclose(left, right)

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). Standard input is as follows:

  1. 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.
  2. If text is selected and spans a single line, only the selected text is used.
  3. If no text is selected, the entire buffer is used.

Parameters:

textadept.editing.goto_line(line)

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

Parameters:

textadept.editing.highlight_word()

Highlights all occurrences of the selected text or all occurrences of the current word.

See also:

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.match_brace(select)

Goes to the current character’s matching brace, selecting the text in between if select is true.

Parameters:

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.

Parameters:

textadept.editing.select_line()

Selects the current line.

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.show_documentation()

Displays a call tip with documentation for the symbol under or directly behind the caret. Documentation is read from API files in the api_files table. If a call tip is already shown, cycles to the next one if it exists. Symbols are determined by using buffer.word_chars.

See also:

textadept.editing.transpose_chars()

Transposes characters intelligently. If the caret is at the end of a line, transposes the two characters before the caret. Otherwise, the characters to the left and right are.

Tables defined by textadept.editing

textadept.editing.XPM_IMAGES

Map of image names to registered image numbers.

Fields:

textadept.editing.api_files

Map of lexer names to API documentation file tables. Each line in an API file consists of a symbol name (not a fully qualified symbol name), a space character, and that symbol’s documentation. “\n” represents a newline character.

See also:

textadept.editing.auto_pairs

Map of auto-paired characters like parentheses, brackets, braces, and quotes. The ASCII values of opening characters are assigned to strings that contain complement characters. The default auto-paired characters are “()”, “[]”, “{}”, “''”, and “""”.

Usage:

textadept.editing.autocompleters

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. Autocompletion lists are sorted automatically.

See also:

textadept.editing.brace_matches

Table of brace characters to highlight. The ASCII values of brace characters are keys and are assigned non-nil values. The default brace characters are ‘(’, ‘)’, ‘[’, ‘]’, ‘{’, and ‘}’.

Usage:

textadept.editing.comment_string

Map of lexer names to line comment strings for programming languages, used by the block_comment() function. Keys are lexer names and values are either the language’s line comment prefixes or block comment delimiters separated by a ‘|’ character.

See also:

textadept.editing.typeover_chars

Table of characters to move over when typed. The ASCII values of characters are keys and are assigned non-nil values. The default characters are ‘)’, ‘]’, ‘}’, ‘'’, and ‘"’.

Usage:


The textadept.file_types Module


Handles file type detection for Textadept.

Fields defined by textadept.file_types

events.LEXER_LOADED (string)

Emitted after loading a language lexer. This is useful for overriding a language module’s key bindings or other properties since the module is not loaded when Textadept starts. Arguments:

Functions defined by textadept.file_types

textadept.file_types.select_lexer()

Prompts the user to select a lexer for the current buffer.

See also:

Tables defined by textadept.file_types

textadept.file_types.extensions

Map of file extensions to their associated lexer names. If the file type is not recognized by its first-line, each file extension is matched against the file’s extension.

textadept.file_types.lexers

List of available lexer names.

textadept.file_types.patterns

Map of first-line patterns to their associated lexer names. Each pattern is matched against the first line in the file.


The textadept.keys Module


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

Key Bindings

Linux / Win32 Mac OSX Terminal Command
File
Ctrl+N ⌘N M-^N New file
Ctrl+O ⌘O ^O Open file
Ctrl+Alt+O ^⌘O M-^O Open recent file…
Ctrl+Shift+O ⌘⇧O M-O Reload file
Ctrl+S ⌘S ^S Save file
Ctrl+Shift+S ⌘⇧S M-^S Save file as..
Ctrl+W ⌘W ^W Close file
Ctrl+Shift+W ⌘⇧W M-^W Close all files
None None None Load session…
None None None Load session…
Ctrl+Q ⌘Q ^Q Quit
Edit
Ctrl+Z
Alt+Bksp
⌘Z ^Z
M-Z
Undo
Ctrl+Y
Ctrl+Shift+Z
⌘⇧Z ^Y
M-S-Z
Redo
Ctrl+X
Shift+Del
⌘X
⇧⌦
^X Cut
Ctrl+C
Ctrl+Ins
⌘C ^C Copy
Ctrl+V
Shift+Ins
⌘V ^V Paste
Ctrl+D ⌘D None Duplicate line
Del
^D
Del
^D
Delete
Alt+Del ^⌦ M-Del
M-D
Delete word
Ctrl+A ⌘A M-A Select all
Ctrl+M ^M M-M Match brace
Ctrl+Enter ^Esc M-Enter Complete word
Ctrl+Alt+Shift+H ⌘⇧H None Highlight word
Ctrl+/ ^/ M-/ Toggle block comment
Ctrl+T ^T ^T Transpose characters
Ctrl+Shift+J ^J M-J Join lines
Ctrl+| ⌘| ^\ Filter text through
Ctrl+Shift+M ^⇧M M-S-M Select to matching brace
Ctrl+< ⌘< M-< Select between XML tags
Ctrl+> ⌘> None Select in XML tag
Ctrl+“ ⌘" M-“ Select in double quotes
Ctrl+‘ ⌘' M-‘ Select in single quotes
Ctrl+( ⌘( M-( Select in parentheses
Ctrl+[ ⌘[ M-[ Select in brackets
Ctrl+{ ⌘{ M-{ Select in braces
Ctrl+Shift+D ⌘⇧D M-S-W Select word
Ctrl+Shift+N ⌘⇧N M-S-N Select line
Ctrl+Shift+P ⌘⇧P M-S-P Select paragraph
Ctrl+Alt+U ^U M-^U Upper case selection
Ctrl+Alt+Shift+U ^⇧U M-^L Lower case selection
Alt+< ^< M-> Enclose as XML tags
Alt+> ^> None Enclose as single XML tag
Alt+“ ^“ None Enclose in double quotes
Alt+‘ ^‘ None Enclose in single quotes
Alt+( ^( M-) Enclose in parentheses
Alt+[ ^[ M-] Enclose in brackets
Alt+{ ^{ M-} Enclose in braces
Ctrl+Shift+Up ^⇧⇡ S-^Up Move selected lines up
Ctrl+Shift+Down ^⇧⇣ S-^Down Move selected lines down
Search
Ctrl+F ⌘F M-F
M-S-F
Find
Ctrl+G
F3
⌘G M-G Find next
Ctrl+Shift+G
Shift+F3
⌘⇧G M-S-G Find previous
Ctrl+Alt+R ^R M-R Replace
Ctrl+Alt+Shift+R ^⇧R M-S-R Replace all
Ctrl+Alt+F ^⌘F M-^F Find incremental
Ctrl+Shift+F ⌘⇧F None Find in files
Ctrl+Alt+G ^⌘G None Goto next file found
Ctrl+Alt+Shift+G ^⌘⇧G None Goto previous file found
Ctrl+J ⌘J ^J Jump to line
Tools
Ctrl+E ⌘E M-C Command entry
Ctrl+Shift+E ⌘⇧E M-S-C Select command
Ctrl+R ⌘R ^R Run
Ctrl+Shift+R ⌘⇧R M-^R Compile
Ctrl+Shift+A ⌘⇧A None Set Arguments…
Ctrl+Shift+B ⌘⇧B M-^B Build
Ctrl+Shift+X ⌘⇧X M-^X Stop
Ctrl+Alt+E ^⌘E M-X Next Error
Ctrl+Alt+Shift+E ^⌘⇧E M-S-X Previous Error
Ctrl+Space ⌥Esc ^Space Complete symbol
Ctrl+H ^H M-H
M-S-H
Show documentation
Tab Tab Expand snippet or next placeholder
Ctrl+K ⌥⇥ M-K Insert snippet…
Shift+Tab ⇧⇥ S-Tab Previous snippet placeholder
Ctrl+Shift+K ⌥⇧⇥ M-S-K Cancel snippet
Ctrl+F2 ⌘F2 F1 Toggle bookmark
Ctrl+Shift+F2 ⌘⇧F2 F6 Clear bookmarks
F2 F2 F2 Next bookmark
Shift+F2 ⇧F2 F3 Previous bookmark
Alt+F2 ⌥F2 F4 Goto bookmark…
Ctrl+U ⌘U ^U Quickly open _USERHOME
None None None Quickly open _HOME
Ctrl+Alt+Shift+O ^⌘⇧O M-S-O Quickly open current directory
Ctrl+Alt+Shift+P ^⌘⇧P M-^P Quickly open current project
Ctrl+I ⌘I M-S-I Show style
Buffer
Ctrl+Tab ^⇥ M-N Next buffer
Ctrl+Shift+Tab ^⇧⇥ M-P Previous buffer
Ctrl+B ⌘B M-B
M-S-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+Shift+T ^⇧T M-T
M-S-T
Toggle use tabs
Ctrl+Alt+I ^I M-I 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 ISO-8859-1 encoding
None None None UTF-16 encoding
Ctrl+Shift+L ⌘⇧L M-S-L Select lexer…
F5 F5 ^L
F5
Refresh syntax highlighting
View
Ctrl+Alt+N ^⌥⇥ M-^V N Next view
Ctrl+Alt+P ^⌥⇧⇥ M-^V P Previous view
Ctrl+Alt+S
Ctrl+Alt+H
^S M-^V S
M-^V H
Split view horizontal
Ctrl+Alt+V ^V M-^V V Split view vertical
Ctrl+Alt+W ^W M-^V W Unsplit view
Ctrl+Alt+Shift+W ^⇧W M-^V S-W Unsplit all views
Ctrl+Alt++
Ctrl+Alt+=
^+
^=
M-^V +
M-^V =
Grow view
Ctrl+Alt+- ^- M-^V - Shrink view
Ctrl+* ⌘* M-* Toggle current fold
Ctrl+Alt+Enter ^↩ None Toggle view EOL
Ctrl+Alt+\ ^\ None Toggle wrap mode
Ctrl+Alt+Shift+I ^⇧I N/A Toggle indent guides
Ctrl+Alt+Shift+S ^⇧S None Toggle view whitespace
Ctrl+Alt+Shift+V ^⇧V 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
Movement
Down
^N
^N
Down
Line down
Shift+Down ⇧⇣
^⇧N
S-Down Line down extend selection
Ctrl+Down ^⇣ ^Down Scroll line down
Alt+Shift+Down ⌥⇧⇣ M-S-Down Line down extend rect. selection
Up
^P
^P
Up
Line up
Shift+Up ⇧⇡
^⇧P
S-Up Line up extend selection
Ctrl+Up ^⇡ ^Up Scroll line up
Alt+Shift+Up ⌥⇧⇡ M-S-Up Line up extend rect. selection
Left
^B
^B
Left
Char left
Shift+Left ⇧⇠
^⇧B
S-Left Char left extend selection
Ctrl+Left ^⇠
^⌘B
^Left Word left
Ctrl+Shift+Left ^⇧⇠
^⌘⇧B
S-^Left Word left extend selection
Alt+Shift+Left ⌥⇧⇠ M-S-Left Char left extend rect. selection
Right
^F
^F
Right
Char right
Shift+Right ⇧⇢
^⇧F
S-Right Char right extend selection
Ctrl+Right ^⇢
^⌘F
^Right Word right
Ctrl+Shift+Right ^⇧⇢
^⌘⇧F
S-^Right Word right extend selection
Alt+Shift+Right ⌥⇧⇢ M-S-Right Char right extend rect. selection
Home ⌘⇠
^A
^A
Home
Line start
Shift+Home ⌘⇧⇠
^⇧A
M-S-A Line start extend selection
Ctrl+Home ⌘⇡
⌘↖
M-^A Document start
Ctrl+Shift+Home ⌘⇧⇡
⌘⇧↖
None Document start extend selection
Alt+Shift+Home ⌥⇧↖ None Line start extend rect. selection
End ⌘⇢
^E
^E
End
Line end
Shift+End ⌘⇧⇢
^⇧E
M-S-E Line end extend selection
Ctrl+End ⌘⇣
⌘↘
M-^E Document end
Ctrl+Shift+End ⌘⇧⇣
⌘⇧↘
None Document end extend selection
Alt+Shift+End ⌥⇧↘ None Line end extend rect. selection
PgUp PgUp Page up
Shift+PgUp ⇧⇞ M-S-U Page up extend selection
Alt+Shift+PgUp ⌥⇧⇞ None Page up extend rect. selection
PgDn PgDn Page down
Shift+PgDn ⇧⇟ M-S-D 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
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 ^K 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
UTF-8 Input
Ctrl+Shift+U xxxx Enter ⌘⇧U xxxx M-U xxxx Enter Insert U-xxxx char.
Find Fields
Left
^B
^B
Left
Cursor left
Right
^F
^F
Right
Cursor right
Del Del Delete forward
Bksp ^H
Bksp
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
^A Home
End
⌘⇢
^E
^E End
N/A N/A ^T Transpose characters
N/A N/A Tab Focus find buttons
N/A N/A S-Tab Focus replace buttons
Tab Down Focus replace field
Shift+Tab ⇧⇥ Up Focus find field
Down ^P Cycle back through history
Up ^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”

†: Some terminals interpret ^Z as suspend.

‡: Ctrl+Enter in Win32 curses.


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.

Functions defined by textadept.menu

textadept.menu.select_command()

Prompts the user to select a menu command to run.

Tables defined by textadept.menu

textadept.menu.context_menu

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

The default main menubar. Individual menus, submenus, and menu items can be retrieved by name in addition to table index number.

Usage:

textadept.menu.tab_context_menu

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


The textadept.run Module


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

Fields defined by textadept.run

textadept.run.MARK_ERROR (number)

The run or compile error marker number.

textadept.run.MARK_WARNING (number)

The run or compile warning marker number.

events.BUILD_OUTPUT (string)

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

events.COMPILE_OUTPUT (string)

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

events.RUN_OUTPUT (string)

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

textadept.run.run_in_background (bool)

Run shell commands silently in the background. This only applies when the message buffer is open, though it does not have to be visible. The default value is false.

Functions defined by textadept.run

textadept.run.build(root_directory)

Builds the project whose root path is root_directory or the current project using the shell command from the build_commands table. If a “makefile” type of build file is found, prompts the user for the full build command. The current project is determined by either the buffer’s filename or the current working directory. Emits BUILD_OUTPUT events.

Parameters:

See also:

textadept.run.compile(filename)

Compiles file filename or the current file using an appropriate shell command from the compile_commands table. The shell command is determined from the file’s filename, extension, or language in that order. Emits COMPILE_OUTPUT events.

Parameters:

See also:

textadept.run.goto_error(line, next)

Jumps to the source of the recognized compile/run warning or error on line number line in the message buffer. If line is nil, jumps to the next or previous warning or error, depending on boolean next. Displays an annotation with the warning or error message if possible.

Parameters:

See also:

textadept.run.run(filename)

Runs file filename or the current file using an appropriate shell command from the run_commands table. The shell command is determined from the file’s filename, extension, or language in that order. Emits RUN_OUTPUT events.

Parameters:

See also:

textadept.run.stop()

Stops the currently running process, if any.

Tables defined by textadept.run

textadept.run.build_commands

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 to operate in. By default, it is the project’s root directory.

textadept.run.compile_commands

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 to operate in. By default, it is the current file’s parent directory.

textadept.run.error_patterns

Map of file extensions and lexer names to their associated lists of string patterns that match warning and error messages emitted by compile and run commands for those file extensions and lexers. Patterns match single lines and contain captures for a filename, line number, column number (optional), and warning or error message (optional). Double-clicking a warning or error message takes the user to the source of that warning/error. Note: (.-) captures in patterns are interpreted as filenames; (%d+) captures are interpreted as line numbers first, and then column numbers; and any other capture is treated as warning/error message text.

textadept.run.run_commands

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 to operate in. By default, it is the current file’s parent directory.


The textadept.session Module


Session support for Textadept.

Fields defined by textadept.session

textadept.session.default_session (string)

The path to the default session file, _USERHOME/session, or _USERHOME/session_term if CURSES is true.

textadept.session.max_recent_files (number)

The maximum number of recent files to save in session files. Recent files are stored in io.recent_files. The default value is 10.

textadept.session.save_on_quit (bool)

Save the session when quitting. The session file saved is always textadept.session.default_session, even if a different session was loaded with textadept.session.load(). 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:

See also:

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.

Parameters:

Usage:

See also:


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 language (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.

Special Sequences

%n(text)

Represents a placeholder, where n is an integer and text is default placeholder text. Textadept moves the caret to placeholders in numeric order each time it calls textadept.snippets._insert(), finishing at either the “%0” placeholder if it exists or at the end of the snippet. Examples are

snippets['foo'] = 'foobar%1(baz)'
snippets['bar'] = 'start\n\t%0\nend'

%n{list}

Also represents a placeholder (where n is an integer), but presents a list of choices for placeholder text constructed from comma-separated list. Examples are

snippets['op'] = 'operator(%1(1), %2(1), "%3{add,sub,mul,div}")'

%n

Represents a mirror, where n is an integer. Mirrors with the same n as a placeholder mirror any user input in the placeholder. If no placeholder exists for n, the first occurrence of that mirror in the snippet becomes the placeholder, but with no default text. Examples are

snippets['foo'] = '%1(mirror), %1, on the wall'
snippets['q'] = '"%1"'

%n<Lua code>
%n[Shell code]

Represents a transform, where n is an integer that has an associated placeholder, Lua code is arbitrary Lua code, and Shell code is arbitrary Shell code. Textadept executes the code as text is typed into placeholder n. If the transform omits n, Textadept executes the transform’s code the moment the editor inserts the snippet.

Textadept runs Lua code in its Lua State and replaces the transform with the code’s return text. The code may use the temporary text and selected_text global variables which contain placeholder n’s text and the text originally selected when the snippet was inserted, respectively. An example is

snippets['attr'] = [[
%1(int) %2(foo) = %3;

%1 get%2<text:gsub('^.', function(c) return c:upper() end)>() {
    return %2;
}
void set%2<text:gsub('^.', function(c) return c:upper() end)>(%1 value) {
    %2 = value;
}
]]

Textadept executes shell code using Lua’s io.popen() and replaces the transform with the process' standard output (stdout). The code may use a % character to represent placeholder n’s text. An example is

snippets['env'] = '$%1(HOME) = %1[echo $%]'

%%

Stands for a single ‘%’ since ‘%’ by itself has a special meaning in snippets.

%(
%{

Stands for a single ‘(’ or ‘{’, respectively, after a %n mirror. Otherwise, the mirror would be interpreted as a placeholder or transform. Note: it is currently not possible to escape a ‘<’ or ‘[’ immediately after a %n mirror due to %<...> and %[...] sequences being interpreted as code to execute.

\t

A single unit of indentation based on the buffer’s indentation settings (buffer.use_tabs and buffer.tab_width).

\n

A single set of line ending delimiters based on the buffer’s end of line mode (buffer.eol_mode).

Fields defined by textadept.snippets

textadept.snippets.INDIC_PLACEHOLDER (number)

The snippet placeholder indicator number.

Functions defined by textadept.snippets

textadept.snippets._cancel_current()

Cancels the active snippet, removing all inserted text.

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.

Tables defined by textadept.snippets

_G.snippets

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. This table also contains the textadept.snippets module.

textadept.snippets._paths

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.


The ui Module


Utilities for interacting with Textadept’s user interface.

Fields defined by ui

ui.bufstatusbar_text (string, Write-only)

The text displayed in the buffer statusbar.

ui.clipboard_text (string)

The text on the clipboard.

ui.context_menu (userdata)

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 (bool)

Whether or not Textadept’s window is maximized.

ui.silent_print (bool)

Whether or not to print messages to buffers silently. This is not guaranteed to be a constant value, as Textadept may change it for the editor’s own purposes. This flag should be used only in conjunction with a group of ui.print() and ui._print() function calls. The default value is false, and focuses buffers when messages are printed to them.

ui.statusbar_text (string, Write-only)

The text displayed in the statusbar.

ui.tab_context_menu (userdata)

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 (bool)

Whether or not to display the tab bar when multiple buffers are open. The default value is true.

ui.title (string, Write-only)

The title text of Textadept’s window.

Functions defined by ui

ui._print(buffer_type, …)

Prints the given string messages to the buffer of string type buffer_type. Opens a new buffer for printing messages to if necessary. If the message 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 message buffer is displayed before being printed to.

Parameters:

Usage:

ui.dialog(kind, …)

Low-level function for prompting the user with a gtdialog of kind kind with the given string and table arguments, returning a formatted string of the dialog’s output. You probably want to use the higher-level functions in the ui.dialogs module. Table arguments containing strings are allowed and expanded in place. This is useful for filtered list dialogs with many items.

Parameters:

Return:

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, preferred_view, sloppy)

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 last part of filename to match a buffer’s 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 VIEW_BEFORE_SWITCH and VIEW_AFTER_SWITCH events.

Parameters:

See also:

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 a MENU_CLICKED event when a menu item is selected.

Parameters:

Usage:

See also:

ui.print()

Prints the given string messages to the message buffer. Opens a new buffer if one has not already been opened for printing messages.

Parameters:

ui.set_theme(name, props)

Switches the editor theme to string name and (optionally) assigns the properties contained in table props. 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:

ui.switch_buffer()

Prompts the user to select a buffer to switch to.

Tables defined by ui

ui.menubar

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.

See also:

ui.size

A table containing the width and height pixel values of Textadept’s window.


The ui.command_entry Module


Textadept’s Command Entry.

Modes

The command entry supports multiple modes that have their own sets of key bindings stored in a separate table in _G.keys under a mode prefix key. Mode names are arbitrary, but cannot conflict with lexer names or key sequence strings (e.g. 'lua' or 'send') due to the method Textadept uses for looking up key bindings. An example mode is “lua_command” mode for executing Lua commands:

local function complete_lua() ... end
local function run_lua() ... end
keys['ce'] = function() ui.command_entry.enter_mode('lua_command') end
keys.lua_command = {
  ['\t'] = complete_lua,
  ['\n'] = function() return ui.command_entry.finish_mode(run_lua) end
}

In this case, Ctrl+E opens the command entry and enters “lua_command” key mode where the Tab and Enter keys have special, defined functionality. (By default, Textadept pre-defines Esc to exit any command entry mode.) Tab shows a list of Lua completions for the entry text and Enter exits “lua_command” key mode and executes the entered code. The command entry handles all other editing and movement keys normally.

Fields defined by ui.command_entry

ui.command_entry.height (number)

The height in pixels of the command entry.

Functions defined by ui.command_entry

ui.command_entry.enter_mode(mode, lexer, height)

Opens the command entry in key mode mode, highlighting text with lexer name lexer, and displaying height number of lines at a time. Key bindings will be looked up in keys[mode] instead of keys. The Esc key exits the current mode, closes the command entry, and restores normal key lookup. This function is useful for binding keys to enter a command entry mode.

Parameters:

Usage:

See also:

ui.command_entry.finish_mode(f)

Exits the current key mode, closes the command entry, and calls function f (if given) with the command entry’s text as an argument. This is useful for binding keys to exit a command entry mode and perform an action with the entered text.

Parameters:

Usage:

ui.command_entry.focus()

Opens the command entry.

Tables defined by ui.command_entry

ui.command_entry.editing_keys

A metatable with typical platform-specific key bindings for text entries. This metatable may be used to add basic editing keys to command entry modes. It is automatically added to command entry modes unless a metatable was previously set.

Usage:


The ui.dialogs Module


Provides a set of interactive dialog prompts for user input.

Functions defined by ui.dialogs

ui.dialogs.dropdown(options)

Prompts the user with a drop-down item selection dialog defined by dialog options table options, returning the selected button’s index along with the index of the selected item. If options.string_output is true, returns the selected button’s label along with the selected item’s text. If the dialog closed due to options.exit_onchange, returns 4 along with either the selected item’s index or its text. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Usage:

Return:

ui.dialogs.filesave(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:

ui.dialogs.fileselect(options)

Prompts the user with a file selection dialog defined by dialog options table options, returning the string file selected. If options.select_multiple is true, returns the list of files selected. If the user canceled the dialog, returns nil.

Parameters:

Usage:

Return:

ui.dialogs.filteredlist(options)

Prompts the user with a filtered list item selection dialog defined by dialog options table options, returning the selected button’s index along with the index or indices of the selected item or items (depending on whether or not options.select_multiple is true). If options.string_output is true, returns the selected button’s label along with the text of the selected item or items. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete". Spaces in the filter text are treated as wildcards.

Parameters:

Usage:

Return:

ui.dialogs.inputbox(options)

Prompts the user with an inputbox dialog defined by dialog options table options, returning the selected button’s index along with the user’s input text (the latter as a string or table, depending on the type of options.informative_text). If options.string_output is true, returns the selected button’s label along with the user’s input text. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Usage:

Return:

ui.dialogs.msgbox(options)

Prompts the user with a generic message box dialog defined by dialog options table options, returning the selected button’s index. If options.string_output is true, returns the selected button’s label. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Usage:

Return:

ui.dialogs.ok_msgbox(options)

Prompts the user with a generic message box dialog defined by dialog options table options and with localized “Ok” and “Cancel” buttons, returning the selected button’s index. If options.string_output is true, returns the selected button’s label. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Return:

ui.dialogs.optionselect(options)

Prompts the user with an option selection dialog defined by dialog options table options, returning the selected button’s index along with the indices of the selected options. If options.string_output is true, returns the selected button’s label along with the text of the selected options. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Usage:

Return:

ui.dialogs.secure_inputbox(options)

Prompts the user with a masked inputbox dialog defined by dialog options table options, returning the selected button’s index along with the user’s input text (the latter as a string or table, depending on the type of options.informative_text). If options.string_output is true, returns the selected button’s label along with the user’s input text. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Return:

ui.dialogs.secure_standard_inputbox(options)

Prompts the user with a masked inputbox dialog defined by dialog options table options and with localized “Ok” and “Cancel” buttons, returning the selected button’s index along with the user’s input text (the latter as a string or table, depending on the type of options.informative_text). If options.string_output is true, returns the selected button’s label along with the user’s input text. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Return:

ui.dialogs.standard_dropdown(options)

Prompts the user with a drop-down item selection dialog defined by dialog options table options and with localized “Ok” and “Cancel” buttons, returning the selected button’s index along with the selected item’s index. If options.string_output is true, returns the selected button’s label along with the selected item’s text. If the dialog closed due to options.exit_onchange, returns 4 along with either the selected item’s index or its text. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Return:

ui.dialogs.standard_inputbox(options)

Prompts the user with an inputbox dialog defined by dialog options table options and with localized “Ok” and “Cancel” buttons, returning the selected button’s index along with the user’s input text (the latter as a string or table, depending on the type of options.informative_text). If options.string_output is true, returns the selected button’s label along with the user’s input text. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Return:

ui.dialogs.textbox(options)

Prompts the user with a multiple-line textbox dialog defined by dialog options table options, returning the selected button’s index. If options.string_output is true, returns the selected button’s label. If options.editable is true, also returns the textbox’s text. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Usage:

Return:

ui.dialogs.yesno_msgbox(options)

Prompts the user with a generic message box dialog defined by dialog options table options and with localized “Yes”, “No”, and “Cancel” buttons, returning the selected button’s index. If options.string_output is true, returns the selected button’s label. If the dialog timed out, returns 0 or "timeout". If the user canceled the dialog, returns -1 or "delete".

Parameters:

Return:


The ui.find Module


Textadept’s Find & Replace pane.

Fields defined by ui.find

ui.find.INDIC_FIND (number)

The find in files highlight indicator number.

events.FIND_WRAPPED (string)

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.

ui.find.find_entry_text (string)

The text in the “Find” entry.

ui.find.find_in_files_timeout (number)

The approximate interval in seconds between prompts for continuing an “In files” search. The default value is 10 seconds.

ui.find.find_label_text (string, Write-only)

The text of the “Find” label. This is primarily used for localization.

ui.find.find_next_button_text (string, Write-only)

The text of the “Find Next” button. This is primarily used for localization.

ui.find.find_prev_button_text (string, Write-only)

The text of the “Find Prev” button. This is primarily used for localization.

ui.find.in_files (bool)

Find search text in a list of files. The default value is false.

ui.find.in_files_label_text (string, Write-only)

The text of the “In files” label. This is primarily used for localization.

ui.find.match_case (bool)

Match search text case sensitively. The default value is false.

ui.find.match_case_label_text (string, Write-only)

The text of the “Match case” label. This is primarily used for localization.

ui.find.regex (bool)

Interpret search text as a Regular Expression. The default value is false.

ui.find.regex_label_text (string, Write-only)

The text of the “Regex” label. This is primarily used for localization.

ui.find.replace_all_button_text (string, Write-only)

The text of the “Replace All” button. This is primarily used for localization.

ui.find.replace_button_text (string, Write-only)

The text of the “Replace” button. This is primarily used for localization.

ui.find.replace_entry_text (string)

The text in the “Replace” entry.

ui.find.replace_label_text (string, Write-only)

The text of the “Replace” label. This is primarily used for localization.

ui.find.whole_word (bool)

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 (string, Write-only)

The text of the “Whole word” label. This is primarily used for localization.

Functions defined by ui.find

ui.find.find_in_files(dir, filter)

Searches directory dir or the user-specified directory for files that match search text and search options (subject to optional filter filter), and prints the results to a buffer titled “Files Found”, highlighting found text. Use the find_text, match_case, whole_word, and regex fields to set the search text and option flags, respectively.

Parameters:

See also:

ui.find.find_incremental(text, next, anchor)

Begins an incremental search using the command entry if text is nil. Otherwise, continues an incremental search by searching for the next or previous instance of string text, depending on boolean next. anchor indicates whether or not to search for text starting from the caret position instead of the position where the incremental search began. Only the match_case find option is recognized. Normal command entry functionality is unavailable until the search is finished or by pressing Esc ( on Mac OSX | Esc in curses).

Parameters:

ui.find.find_next()

Mimics pressing the “Find Next” button.

ui.find.find_prev()

Mimics pressing the “Find Prev” button.

ui.find.focus()

Displays and focuses the Find & Replace Pane.

ui.find.goto_file_found(line_num, next)

Jumps to the source of the find in files search result on line number line_num in the buffer titled “Files Found” or, if line_num is nil, jumps to the next or previous search result, depending on boolean next.

Parameters:

ui.find.replace()

Mimics pressing the “Replace” button.

ui.find.replace_all()

Mimics pressing the “Replace All” button.

Tables defined by ui.find

ui.find.find_in_files_filter

The table of Lua patterns matching files and directories to exclude when finding in files. The filter table contains:

Any patterns starting with ‘!’ exclude files and directories that do not match the pattern that follows. The default value is lfs.default_filter, a filter for common binary file extensions and version control directories.

See also:


The view Module


A Textadept view object.

Fields defined by view

view.size (number)

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

Functions defined by view

view.goto_buffer(view, buffer)

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

Parameters:

See also:

view.split(view, vertical)

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 a VIEW_NEW event.

Parameters:

Return:

See also:

view.unsplit(view)

Unsplits the view if possible, returning true on success.

Parameters:

Return:

Tables defined by view

view.buffer

The buffer the view contains. (Read-only)