_G moduleExtends Lua’s _G table to provide extra functions and fields for Textadept.
BSDWhether or not Textadept is running on BSD.
CURSESWhether or not Textadept is running in a terminal.
GTKWhether or not Textadept is running as a GTK GUI application.
LINUXWhether or not Textadept is running on Linux.
OSXWhether or not Textadept is running on macOS.
QTWhether or not Textadept is running as a Qt GUI application.
WIN32Whether or not Textadept is running on Windows.
_BUFFERSTable of all open buffers in Textadept.
Numeric keys have buffer values and buffer keys have their associated numeric keys as values.
Usage:
local buffer = _BUFFERS[n] -- buffer at index n
local i = _BUFFERS[buffer] -- index of buffer in _BUFFERS
See also: buffer
_CHARSETThe filesystem’s character encoding.
This really only matters on Windows, where there is a mismatch between the UI encoding (UTF-8), and the filesystem encoding (non-UTF-8).
Usage:
local utf8_filename = buffer.filename:iconv('UTF-8', _CHARSET)
local f = io.open(utf8_filename:iconv(_CHARSET, 'UTF-8'))
See also: string.iconv
_COPYRIGHTTextadept’s copyright information.
_HOMEThe path to Textadept’s home, or installation, directory.
_LEXERPATHA ‘;’-separated list of directory paths that contain lexers for syntax highlighting.
The default value contains ~/.textadept/lexers/ and Textadept’s lexers/ directory.
_RELEASEThe Textadept release version string.
_THEMETextadept’s current UI mode, either “light” or “dark”.
Manually changing this field has no effect. It is used internally to set a theme on startup based on the current OS theme.
See also: view.set_theme, events.MODE_CHANGED
_USERHOMEThe 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\). On macOS and Linux/BSD machines ~/ is the value of “$HOME” (typically /Users/username/ and /home/username/, respectively).
_VIEWSTable of all views in Textadept.
Numeric keys have view values and view keys have their associated numeric keys as values.
Usage:
local view = _VIEWS[n] -- view at index n
local i = _VIEWS[view] -- index of view in _VIEWS
See also: view
argTable of command line parameters passed to Textadept, just like in Lua.
See also: args
assert(v[, message=’assertion failed!’[, …]])Asserts a value is truthy or raises an error.
Parameters:
false or nil.string.format() and the result is the error message to show.Returns: v
assert_type(v, expected_type, narg)Asserts that a value has an expected type or raises an error.
Use this with API function arguments so users receive more helpful error messages.
Parameters:
Returns: v
Usage:
assert_type(filename, 'string/nil', 1) -- assert first arg is optional string
assert_type(option.setting, 'number', 'setting') -- assert 'setting' field is a number
bufferThe current buffer in the current view.
keysTextadept’s key bindings, a map of key shortcuts to commands or key chains.
Language-specific keys are in subtables assigned to lexer names.
Usage:
keys['ctrl+n'] = buffer.new
keys.c['shift+\n'] = function() -- language-specific key
buffer:line_end()
buffer:add_text(';')
buffer:new_line()
end
move_buffer(from, to)Moves buffers within the _BUFFERS table, changing their display order in the tab bar and
buffer browser.
Parameters:
quit([status=0[, events=true]])Attempts to quit Textadept.
Parameters:
events.QUIT, which could prevent quitting. Passing
false could result in data loss.reset()Resets Textadept’s Lua State by reloading all initialization scripts.
This allows for testing theme and user script modifications (e.g. ~/.textadept/init.lua) without having to restart Textadept.
arg is nil during re-initialization. Scripts that need to differentiate between startup
and reset can test arg.
See also: events.RESET_BEFORE, events.RESET_AFTER
snippetsMap of snippet triggers to snippet text or functions that return such text.
Language-specific snippets are in subtables assigned to lexer names.
Usage:
snippets.foo = 'bar'
snippets.lua.f = 'function ${1:name}($2)\n\t$0\nend' -- language-specific snippet
timeout(interval, f[, …])Calls a function after a timeout interval.
Terminal version note: timeout functions will not be called until an active Find & Replace pane session finishes, or until an active dialog closes.
Parameters:
true, it will be called again after interval
seconds.viewThe current view.
_L moduleMap of all messages used by Textadept to their localized forms.
If the localized form of a given message does not exist, the non-localized message is
returned. Use Lua’s rawget() to check if a localization exists.
Terminal version note: any “_” or “&” mnemonics the GUI version would use are ignored.
args moduleProcesses command line arguments for Textadept.
You can register your own command line arguments. For example:
args.register('-r', '--read-only', 0, function()
events.connect(events.FILE_OPENED, function()
buffer.read_only = true -- make all opened buffers read-only
end)
textadept.menu.menubar = nil -- hide the menubar
end, "Read-only mode")
Running textadept -r file.txt will open that and all subsequent files in read-only mode.
args.register(short, long, narg, f, description)Registers a command line option.
Parameters:
true, events.ARG_NONE will ultimately not be emitted.Usage:
args.register('-r', '--read-only', 0, function() ... end, 'Read-only mode')
buffer moduleA Textadept buffer or view object.
Any buffer and view fields set on startup (e.g. in ~/.textadept/init.lua) will be the default, initial values for all buffers and views.
Internally, Textadept uses the Scintilla editing component for editing text. It breaks up Scintilla’s monolithic API into two parts: buffers and views. Buffers are responsible for text editing, selections, and navigation. Views are responsible for visual things like text and selection display, margins, markers, and highlights. This is a best-effort attempt to allow for sensible object-oriented scripting with an editing component that combines the data model and view model into one entity. It is not perfect and my not make complete sense at times.
That said, this buffer and view API is largely interchangeable: view.field and
view:function() are often equivalent to buffer.field and buffer:function(), respectively,
and vice-versa.
Only one buffer and one view at a time is considered “current” (i.e. has focus). While
Textadept allows you to work with non-current buffers, you should only work with buffer
unless you know what you are doing. For example, buffer:select_all() will visually
select all text in the current buffer, but buf:select_all() where buf ~= buffer will
not make a visible selection, even if buf is visible in another view. Despite this,
buf:replace_sel('') will still clear that buffer since it previously selected all text.
(Basically, you can make “background” edits of non-current buffers in an object-oriented way.)
buffer.new()Creates a new buffer and displays it in the current view.
Returns: the new buffer
See also: io.open_file, events.BUFFER_NEW
view:split([vertical=false])Splits the view and focuses the new view.
Parameters:
Returns: old view, new view
See also: events.VIEW_NEW
view:unsplit()Unsplits the view if possible.
Returns: whether or not the view was unsplit.
view.bufferThe buffer the view currently contains. (Read-only)
view.sizeThe split resizer’s pixel position if the view is a split one.
See also: ui.get_split_table
Note: this module does not open files. io.open_file() does.
buffer:reload()Reloads the buffer’s file contents, discarding any changes.
buffer:save()Saves the buffer to its file.
If the buffer does not have a file, the user is prompted for one.
Returns: true if the file was saved; nil otherwise.
See also: textadept.editing.strip_trailing_spaces, io.ensure_final_newline, io.save_all_files, events.FILE_BEFORE_SAVE, events.FILE_AFTER_SAVE
buffer:save_as([filename])Saves the buffer to another file.
Parameters:
nil, the user is prompted for one.Returns: true if the file was saved; nil otherwise.
See also: events.FILE_AFTER_SAVE
buffer:close([force=false])Closes the buffer.
Parameters:
Returns: true if the buffer was closed; nil otherwise.
See also: io.close_all_buffers
buffer:set_encoding(encoding)Converts the buffer’s contents to another encoding.
Parameters:
string.iconv()
accepts, or nil for a binary encoding.See also: io.encodings
buffer.filenameThe buffer’s absolute file path (if any).
See also: _CHARSET
buffer.modifyWhether or not the buffer has unsaved changes. (Read-only)
buffer:set_save_point()Mark the buffer as having no unsaved changes.
buffer.encodingThe buffer’s encoding, or nil for a binary file.
Do not change this field manually. Call buffer:set_encoding() instead.
Movements within the current buffer scroll the caret into view if it is not already visible.
buffer:char_left()Moves the caret left one character.
buffer:char_right()Moves the caret right one character.
buffer:word_part_left()Moves the caret to the previous part of the current word.
Word parts are delimited by underscore characters or changes in capitalization.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_part_right()Moves the caret to the next part of the current word.
Word parts are delimited by underscore characters or changes in capitalization.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_left_end()Moves the caret left one word, positioning it at the end of the previous word.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_right_end()Moves the caret right one word, positioning it at the end of the current word.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_left()Moves the caret left one word.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_right()Moves the caret right one word.
buffer.word_chars contains the set of characters that constitute words.
buffer:home()Moves the caret to the beginning of the current line.
buffer:line_end()Moves the caret to the end of the current line.
buffer:home_display()Moves the caret to the beginning of the current wrapped line.
buffer:line_end_display()Moves the caret to the end of the current wrapped line.
buffer:home_wrap()Moves the caret to the beginning of the current wrapped line or, if already there, to the beginning of the actual line.
buffer:line_end_wrap()Moves the caret to the end of the current wrapped line or, if already there, to the end of the actual line.
buffer:vc_home()Moves the caret to the first visible character on the current line or, if already there, to the beginning of the current line.
buffer:vc_home_display()Moves the caret to the first visible character on the current wrapped line or, if already there, to the beginning of the current wrapped line.
buffer:vc_home_wrap()Moves the caret to the first visible character on the current wrapped line or, if already there, to the beginning of the actual line.
Movements within the current buffer scroll the caret into view if it is not already visible.
buffer:goto_pos(pos)Moves the caret to a position and scrolls it into view.
Parameters:
buffer:goto_line(line)Moves the caret to the beginning of a line and scrolls it into view, even if that line is hidden.
Parameters:
See also: textadept.editing.goto_line
buffer:line_up()Moves the caret up one line.
buffer:line_down()Moves the caret down one line.
buffer.caret_stickyThe caret’s preferred horizontal position when moving between lines.
buffer.CARETSTICKY_OFF: Use the same position the caret had on the previous line.buffer.CARETSTICKY_ON: Use the last position the caret was moved to via the mouse,
left/right arrow keys, home/end keys, etc. Typing text does not affect the position.buffer.CARETSTICKY_WHITESPACE: Use the position the caret had on the previous line,
but prior to any inserted indentation.The default value is buffer.CARETSTICKY_OFF.
buffer:choose_caret_x()Declares the current horizontal caret position as the caret’s preferred horizontal position when moving between lines.
buffer:toggle_caret_sticky()Toggles buffer.caret_sticky between buffer.CARETSTICKY_ON and buffer.CARETSTICKY_OFF.
Movements within the current buffer scroll the caret into view if it is not already visible.
buffer:stuttered_page_up()Moves the caret to the top of the page or, if already there, up one page.
buffer:stuttered_page_down()Moves the caret to the bottom of the page or, if already there, down one page.
buffer:page_up()Moves the caret up one page.
buffer:page_down()Moves the caret down one page.
Movements between buffers do not scroll the caret into view if it is not visible.
view:goto_buffer(buffer)Switches to another buffer.
Parameters:
Usage:
view:goto_buffer(_BUFFERS[1]) -- switch to first buffer
view:goto_buffer(-1) -- switch to the buffer before the current one
See also: events.BUFFER_BEFORE_SWITCH, events.BUFFER_AFTER_SWITCH
Movements within the current buffer scroll the caret into view if it is not already visible.
buffer:para_up()Moves the caret up one paragraph.
Paragraphs are surrounded by one or more blank lines.
buffer:para_down()Moves the caret down one paragraph.
Paragraphs are surrounded by one or more blank lines.
buffer:move_caret_inside_view()Moves the caret into view if it is not already, removing any selections.
buffer:document_start()Moves the caret to the beginning of the buffer.
buffer:document_end()Moves the caret to the end of the buffer.
buffer:get_text()Returns the buffer’s text.
buffer:get_sel_text()Returns the selected text.
Multiple selections are included in order, separated by buffer.copy_separator. Rectangular
selections are included from top to bottom with end of line characters. Virtual space is
not included.
buffer.copy_separatorThe string added between multiple selections in buffer:get_sel_text().
The default value is the empty string (no separators).
buffer:text_range(start_pos, end_pos)Returns a range of text.
Parameters:
buffer:get_line(line)Returns the text on a line, including its end of line characters.
Parameters:
buffer:get_cur_line()Returns the current line’s text and the caret’s position on that line.
buffer.char_atMap of buffer positions to their character bytes. (Read-only)
buffer:set_text(text)Replaces the buffer’s text.
Parameters:
buffer:add_text(text)Adds text to the buffer at the caret position, moving the caret without scrolling it into view.
Parameters:
buffer:insert_text(pos, text)Inserts text into the buffer, removing any existing selections.
If the caret is after pos, it is moved appropriately, but not scrolled into view.
Parameters:
-1 for the caret position.buffer:append_text(text)Appends text to the end of the buffer without modifying any existing selections or scrolling that text into view.
Parameters:
buffer:line_duplicate()Duplicates the current line on a new line below.
buffer:selection_duplicate()Duplicates the selected text to its right.
If multiple lines are selected, duplication starts at the end of the selection. If no text is selected, duplicates the current line on a new line below.
buffer:new_line()Types a new line at the caret position according to buffer.eol_mode.
Replacing an arbitrary range of text makes use of a target range, a user-defined defined region of text that some buffer functions operate on in order to avoid altering the current selection or scrolling the view.
buffer:replace_sel(text)Replaces the selected text, scrolling the caret into view.
Parameters:
buffer:set_target_range(start_pos, end_pos)Defines the target range.
Parameters:
buffer:target_from_selection()Defines the target range as the main selection.
buffer:replace_target(text)Replaces the text in the target range without 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:
Returns: length of replacement text
buffer:clear()Deletes the character at the caret if no text is selected, or deletes the selected text.
buffer:delete_range(pos, length)Deletes a range of text.
Parameters:
buffer:delete_back()Deletes the character behind the caret if no text is selected, or deletes the selected text.
buffer:delete_back_not_line()Deletes the character behind the caret if no text is selected and the caret is not at the beginning of a line.
If text is selected, it is deleted.
buffer:del_word_left()Deletes the word to the left of the caret, including any leading non-word characters.
buffer.word_chars contains the set of characters that constitute words.
buffer:del_word_right()Deletes the word to the right of the caret, including any trailing non-word characters.
buffer.word_chars contains the set of characters that constitute words.
buffer:del_word_right_end()Deletes the word to the right of the caret, excluding any trailing non-word characters.
buffer.word_chars contains the set of characters that constitute words.
buffer:del_line_left()Deletes the range of text from the caret to the beginning of the current line.
buffer:del_line_right()Deletes the range of text from the caret to the end of the current line.
buffer:line_delete()Deletes the current line.
buffer:clear_all()Deletes the buffer’s text.
buffer:tab()Indents the text on the selected lines, or types a Tab character (‘\t’) at the caret position if no text is selected.
buffer:line_indent()Indents the text on the current or selected lines.
buffer:back_tab()Un-indents the text on the selected lines.
buffer:line_dedent()Un-indents the text on the current or selected lines.
buffer:line_transpose()Swaps the current line with the one above it.
buffer:line_reverse()Reverses the order of the selected lines.
buffer:upper_case()Converts the selected text to upper case letters.
buffer:lower_case()Converts the selected text to lower case letters.
buffer:move_selected_lines_up()Shifts the selected lines up one line.
buffer:move_selected_lines_down()Shifts the selected lines down one line.
Splitting and joining lines uses a target range (a user-defined defined region of text that some buffer functions operate on).
buffer:lines_split(width)Splits up lines in the target range that exceed a certain width.
Parameters:
0, the width of the view is used.See also: buffer.set_target_range, buffer.target_from_selection, view.text_width
buffer:lines_join()Joins the lines in the target range, inserting spaces between any words joined at line boundaries.
See also: buffer.set_target_range, buffer.target_from_selection, textadept.editing.join_lines
buffer:can_undo()Returns whether or not there is an action that can be undone.
buffer:can_redo()Returns whether or not there is an action that can be redone.
buffer:undo()Undoes the most recent action.
buffer:redo()Redoes the next undone action.
buffer:begin_undo_action()Starts a sequence of actions that can be undone or redone as a single action.
Calls to this function may be nested.
buffer:end_undo_action()Ends a sequence of actions that can be undone or redone as a single action.
buffer:empty_undo_buffer()Deletes the buffer’s undo and redo history.
buffer:cut()Cuts the selected text to the clipboard.
Multiple selections are copied in order, separated by buffer.copy_separator. Rectangular
selections are copied from top to bottom with end of line characters. Virtual space is
not copied.
buffer:copy()Copies the selected text to the clipboard.
Multiple selections are copied in order, separated by buffer.copy_separator. Rectangular
selections are copied from top to bottom with end of line characters. Virtual space is
not copied.
buffer:line_cut()Cuts the current line to the clipboard.
buffer:line_copy()Copies the current line to the clipboard.
buffer:copy_range(start_pos, end_pos)Copies a range of text to the clipboard.
Parameters:
buffer:copy_text(text)Copies the given text to the clipboard.
Parameters:
buffer:paste()Pastes the clipboard’s contents into the buffer, replacing any selected text according to
buffer.multi_paste.
See also: textadept.editing.paste_reindent, ui.clipboard_text
buffer.multi_pastePaste into multiple selections.
buffer.MULTIPASTE_ONCE: Paste into only the main selection.buffer.MULTIPASTE_EACH: Paste into all selections.The default value is buffer.MULTIPASTE_EACH.
buffer:set_sel(start_pos, end_pos)Selects a range of text, scrolling it into view.
Parameters:
buffer.anchor to the same position as buffer.current_pos).buffer.selection_startThe selected text’s start position.
When set, it becomes the anchor, but is not scrolled into view.
buffer.selection_endThe selected text’s end position.
When set, it becomes the current position, but is not scrolled into view.
buffer:swap_main_anchor_caret()Swaps the main selection’s beginning and end positions.
buffer:select_all()Selects all of the buffer’s text without scrolling the view.
buffer:set_empty_selection(pos)Moves the caret to a position without scrolling the view, and removes any selections.
Parameters:
buffer.selection_emptyWhether or not there is no text selected. (Read-only)
buffer.selection_is_rectangleWhether or not the selection is a rectangular selection. (Read-only)
buffer:is_range_word(start_pos, end_pos)Returns whether or not a range’s bounds are at word boundaries.
buffer.word_chars contains the set of characters that constitute words.
Parameters:
buffer:char_left_extend()Moves the caret left one character, extending the selected text to the new position.
buffer:char_right_extend()Moves the caret right one character, extending the selected text to the new position.
buffer:word_part_left_extend()Moves the caret to the previous part of the current word, extending the selected text to the new position.
Word parts are delimited by underscore characters or changes in capitalization.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_part_right_extend()Moves the caret to the next part of the current word, extending the selected text to the new position.
Word parts are delimited by underscore characters or changes in capitalization.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_left_extend()Moves the caret left one word, extending the selected text to the new position.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_right_extend()Moves the caret right one word, extending the selected text to the new position.
buffer.word_chars contains the set of characters that constitute words.
buffer:word_left_end_extend()Like buffer:word_left_end(), but extends the selected text to the new position.
buffer:word_right_end_extend()Like buffer:word_right_end(), but extends the selected text to the new position.
buffer:home_extend()Moves the caret to the beginning of the current line, extending the selected text to the new position.
buffer:line_end_extend()Moves the caret to the end of the current line, extending the selected text to the new position.
buffer:home_display_extend()Moves the caret to the beginning of the current wrapped line, extending the selected text to the new position.
buffer:line_end_display_extend()Moves the caret to the end of the current wrapped line, extending the selected text to the new position.
buffer:home_wrap_extend()Like buffer:home_wrap(), but extends the selected text to the new position.
buffer:line_end_wrap_extend()Like buffer:line_end_wrap(), but extends the selected text to the new position.
buffer:vc_home_extend()Like buffer:vc_home(), but extends the selected text to the new position.
buffer:vc_home_display_extend()Like buffer:vc_home_display(), but extends the selected text to the new position.
buffer:vc_home_wrap_extend()Like buffer:vc_home_wrap(), but extends the selected text to the new position.
buffer:line_up_extend()Moves the caret up one line, extending the selected text to the new position.
buffer:line_down_extend()Moves the caret down one line, extending the selected text to the new position.
buffer:para_up_extend()Moves the caret up one paragraph, extending the selected text to the new position.
Paragraphs are surrounded by one or more blank lines.
buffer:para_down_extend()Moves the caret down one paragraph, extending the selected text to the new position.
Paragraphs are surrounded by one or more blank lines.
buffer:stuttered_page_up_extend()Like buffer:stuttered_page_up(), but extends the selected text to the new position.
buffer:stuttered_page_down_extend()Like buffer:stuttered_page_down(), but extends the selected text to the new position.
buffer:page_up_extend()Moves the caret up one page, extending the selected text to the new position.
buffer:page_down_extend()Moves the caret down one page, extending the selected text to the new position.
buffer:document_start_extend()Moves the caret to the beginning of the buffer, extending the selected text to the new position.
buffer:document_end_extend()Moves the caret to the end of the buffer, extending the selected text to the new position.
buffer.move_extends_selectionAllow caret movement to alter the selected text.
Setting buffer.selection_mode also updates this property.
The default value is false.
buffer.selection_modeThe selection mode.
buffer.SEL_STREAM: Character selection.buffer.SEL_RECTANGLE: Rectangular selection.buffer.SEL_LINES: Line selection.buffer.SEL_THIN: Thin rectangular selection. This is the mode after a rectangular
selection has been typed into and ensures that no characters are selected.When set, caret movement alters the selected text until either this field is set again to
the same value, or until buffer:cancel() is called.
buffer:change_selection_mode(mode)Changes the selection mode without allowing subsequent caret movement to alter selected text.
Parameters:
buffer.SEL_STREAM: Character selection.buffer.SEL_RECTANGLE: Rectangular selection.buffer.SEL_LINES: Line selection.buffer.SEL_THIN: Thin rectangular selection. This is the mode after a rectangular
selection has been typed into and ensures that no characters are selected.Note: the buffer.selection_n_* fields cannot be used to create selections.
buffer:set_selection(end_pos, start_pos)Selects a range of text, removing all other selections.
Parameters:
buffer:add_selection(end_pos, start_pos)Selects a range of text as the main selection, retaining all other selections as additional selections.
Since an empty selection (i.e. the current position) still counts as a selection, use
buffer:set_selection() first when setting a list of selections.
Parameters:
buffer:multiple_select_add_next()Adds to the set of selections the next occurrence of the main selection within the target range, makes that occurrence the new main selection, and scrolls it into view.
If there is no selected text, the current word is used.
See also: textadept.editing.select_word, buffer.set_target_range, buffer.target_whole_document
buffer:multiple_select_add_each()Adds to the set of selections each occurrence of the main selection within the target range.
If there is no selected text, the current word is used.
See also: textadept.editing.select_word, buffer.set_target_range, buffer.target_whole_document
buffer.selectionsThe number of active selections. (Read-only) There is always at least one selection, which may be empty.
buffer.main_selectionThe number of the main selection, which is often the most recent selection.
Only an existing selection can be made main.
buffer:rotate_selection()Makes the next additional selection the main selection.
buffer:drop_selection_n(n)Drops an existing selection.
Parameters:
buffer.selection_n_anchorMap of existing selection numbers to their start positions.
buffer.selection_n_caretMap of existing selection numbers to their end positions.
buffer.selection_n_startMap of existing selection numbers to their start positions.
buffer.selection_n_endMap of existing selection numbers to their end positions.
buffer.selection_n_anchor_virtual_spaceMap of existing selection numbers to their virtual space start positions.
buffer.selection_n_caret_virtual_spaceMap of existing selection numbers to their virtual space end positions.
buffer.selection_n_start_virtual_spaceMap of existing selection numbers to their virtual space start positions. (Read-only)
buffer.selection_n_end_virtual_spaceMap of existing selection numbers to their virtual space end positions. (Read-only)
buffer.multiple_selectionEnable multiple selection.
The default value is true.
buffer.additional_selection_typingType into multiple selections.
The default value is true.
buffer.rectangular_selection_anchorThe rectangular selection’s anchor position.
buffer.rectangular_selection_caretThe rectangular selection’s caret position.
buffer.rectangular_selection_anchor_virtual_spaceThe amount of virtual space for the rectangular selection’s anchor.
buffer.rectangular_selection_caret_virtual_spaceThe amount of virtual space for the rectangular selection’s caret.
buffer:char_left_rect_extend()Moves the caret left one character, extending the rectangular selection to the new position.
buffer:char_right_rect_extend()Moves the caret right one character, extending the rectangular selection to the new position.
buffer:home_rect_extend()Moves the caret to the beginning of the current line, extending the rectangular selection to the new position.
buffer:line_end_rect_extend()Moves the caret to the end of the current line, extending the rectangular selection to the new position.
buffer:vc_home_rect_extend()Like buffer:vc_home(), but extends the rectangular selection to the new position.
buffer:line_up_rect_extend()Moves the caret up one line, extending the rectangular selection to the new position.
buffer:line_down_rect_extend()Moves the caret down one line, extending the rectangular selection to the new position.
buffer:page_up_rect_extend()Moves the caret up one page, extending the rectangular selection to the new position.
buffer:page_down_rect_extend()Moves the caret down one page, extending the rectangular selection to the new position.
view.rectangular_selection_modifierThe modifier key used in combination with a mouse drag in order to create a rectangular selection.
view.MOD_CTRL: The “Control” modifier key.view.MOD_ALT: The “Alt” modifier key.view.MOD_SUPER: The “Super” modifier key, usually defined as the left “Windows” or
“Command” key.The default value is view.MOD_ALT.
view.mouse_selection_rectangular_switchTurn on rectangular selection when pressing view.rectangular_selection_modifier while
selecting text normally with the mouse.
This works around the Linux/BSD window managers that consume Alt+Mouse Drag.
The default value is true.
buffer:replace_rectangular(text)Replaces the rectangular selection’s text.
Parameters:
buffer:search_anchor()Marks the caret position as the position buffer:search_next() and buffer:search_prev()
start from.
If text is selected, the selected text’s start position is used instead.
buffer:search_next(flags, text)Searches for text and selects its first occurrence without scrolling the view.
Searches start where buffer:search_anchor() was called.
Parameters:
buffer.FIND_WHOLEWORD: Match search text only when it is surrounded by non-word characters.buffer.FIND_MATCHCASE: Match search text case sensitively.buffer.FIND_WORDSTART: Match search text only when the previous character is a non-word
character.buffer.FIND_REGEXP: Interpret search text as a regular expression.Returns: found text’s position, or -1 if no text was found
buffer:search_prev(flags, text)Searches for text and selects its previous occurrence without scrolling the view.
Searches start where buffer:search_anchor() was called.
Parameters:
buffer.FIND_WHOLEWORD: Match search text only when it is surrounded by non-word characters.buffer.FIND_MATCHCASE: Match search text case sensitively.buffer.FIND_WORDSTART: Match search text only when the previous character is a non-word
character.buffer.FIND_REGEXP: Interpret search text as a regular expression.Returns: found text’s position, or -1 if no text was found
The more complex search and replace API uses a target range (a user-defined region of text that some buffer functions operate on, or a region of text that some buffer functions define as output).
buffer.search_flagsThe bit-mask of search flags used by buffer:search_in_target().
buffer.FIND_WHOLEWORD: Match search text only when it is surrounded by non-word characters.buffer.FIND_MATCHCASE: Match search text case sensitively.buffer.FIND_WORDSTART: Match search text only when the previous character is a non-word
character.buffer.FIND_REGEXP: Interpret search text as a regular expression.The default value is 0.
buffer:target_whole_document()Defines the target range as the entire buffer’s contents.
See also: buffer.set_target_range, buffer.target_from_selection
buffer:search_in_target(text)Searches the target range for text and updates the target range to the first occurrence found.
buffer.search_flags are the flags used in the search.
Parameters:
Returns: found text’s position, or -1 if no text was found
buffer:replace_target_re(text)Replaces the text in the target range with a regular expression replacement.
Parameters:
Returns: length of replacement text
See also: buffer.replace_target
buffer.target_textThe text in the target range. (Read-only)
buffer.target_startThe target range’s start position.
This is also set by a successful buffer:search_in_target().
buffer.target_endThe target range’s end position.
This is also set by a successful buffer:search_in_target().
buffer.target_start_virtual_spaceThe start position of the target range’s virtual space.
This is reset to 1 when buffer.target_start or buffer.target_end is set, or when
buffer:set_target_range() is called.
buffer.target_end_virtual_spaceThe end position of the target range’s virtual space.
This is reset to 1 when buffer.target_start or buffer.target_end is set, or when
buffer:set_target_range() is called.
buffer.tagMap of a regular expression search’s capture numbers to captured text. (Read-only)
buffer.anchorThe anchor’s position.
buffer.current_posThe caret’s position.
Setting this does not scroll the caret into view.
buffer:position_before(pos)Returns the position before a given position, taking multi-byte characters into account, or
-1 if there is no such position.
Parameters:
buffer:position_after(pos)Returns the position after a given position, taking multi-byte characters into account, or
buffer.length + 1 if there is no such position.
Parameters:
buffer:position_relative(pos, n)Returns the position a relative number of characters away from a given position, taking
multi-byte characters into account, or 1 if there is no such position.
Parameters:
buffer:word_start_position(pos, only_word_chars)Returns a word’s start position.
buffer.word_chars contains the set of characters that constitute words.
Parameters:
true, stops searching at the first non-word character to the
left of pos. Otherwise, the first character to the left of pos sets the type of
the search as word or non-word and the search stops at the first non-matching character.Usage:
-- Consider the buffer text "word....word"
buffer:word_start_position(3, true) --> 1
buffer:word_start_position(7, true) --> 7
buffer:word_start_position(7, false) --> 5
buffer:word_start_position(9, false) --> 5
buffer:word_start_position(9, true) --> 9
buffer:word_end_position(pos, only_word_chars)Returns a word’s end position.
buffer.word_chars contains the set of characters that constitute words.
Parameters:
true, stops searching at the first non-word character to the
right of pos. Otherwise, the first character to the right of pos sets the type of
the search as word or non-word and the search stops at the first non-matching character.Usage:
-- Consider the buffer text "word....word"
buffer:word_end_position(3, true) --> 5
buffer:word_end_position(5, true) --> 5
buffer:word_end_position(5, false) --> 9
buffer:word_end_position(7, true) --> 7
buffer:word_end_position(7, false) --> 9
buffer:position_from_line(line)Returns a line’s start position.
Parameters:
buffer.line_count +
1, -1 will be returned.buffer.line_indent_positionMap of line numbers to their end-of-line-indentation positions. (Read-only)
buffer.line_end_positionMap of line numbers to their end-of-line positions before any end-of-line characters. (Read-only)
buffer:find_column(line, column)Returns the position at a particular line and column, taking tab and multi-byte characters into account.
Parameters:
buffer:brace_match(pos, max_re_style)Returns the position of a matching brace character, taking nested braces into account, or
-1 if no match was found.
Matching braces must have the same style.
Parameters:
0. Reserved for expansion.buffer.line_countThe number of lines in the buffer. (Read-only) There is always at least one.
view.lines_on_screenThe number of completely visible lines in the view. (Read-only) It is possible to have a partial line visible at the bottom of the view.
view.first_visible_lineThe line number of the line at the top of the view.
buffer:line_from_position(pos)Returns the line number that contains a position.
Parameters:
1, 1 is returned. If
pos is greater than buffer.length + 1, buffer.line_count is returned.buffer.line_indentationMap of line numbers to their column indentation amounts.
buffer:line_length(line)Returns the number of bytes on a 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:
view:wrap_count(line)Returns the number of wrapped lines needed to fully display a line.
Parameters:
view:visible_from_doc_line(line)Returns the displayed line number of an actual line number, taking wrapped, annotated, and hidden lines into account.
Lines can occupy more than one display line if they wrap.
Parameters:
-1
is returned.view:doc_line_from_visible(display_line)Returns the actual line number of a displayed line number, taking wrapped, annotated, and hidden lines into account.
Parameters:
1, 1 is returned. If
display_line is greater than the number of displayed lines, buffer.line_count
is returned.buffer.lengthThe number of bytes in the buffer. (Read-only)
buffer.text_lengthThe number of bytes in the buffer. (Read-only)
buffer.columnMap of buffer positions to their column numbers, taking tab and multi-byte characters into account. (Read-only)
buffer:count_characters(start_pos, end_pos)Returns the number of whole characters, taking multi-byte characters into account, between two positions.
Parameters:
view:text_width(style_num, text)Returns the pixel width text would have when styled in a particular style.
Parameters:
1 and 256 to use.view:text_height(line)Returns the pixel height of a line.
Parameters:
The number of line margins is configurable, with each one displaying either line numbers, marker symbols, or text.
view.marginsThe number of margins.
The default value is 5.
view.margin_type_nMap of margin numbers to their types.
Valid margin types are:
view.MARGIN_SYMBOL: A marker symbol margin.view.MARGIN_NUMBER: A line number margin.view.MARGIN_BACK: A marker symbol margin whose background color matches the default text
background color.view.MARGIN_FORE: A marker symbol margin whose background color matches the default text
foreground color.view.MARGIN_TEXT: A text margin.view.MARGIN_RTEXT: A right-justified text margin.view.MARGIN_COLOR: A marker symbol margin whose background color is configurable.The default value for the first margin is view.MARGIN_NUMBER, followed by view.MARGIN_SYMBOL
for the rest.
view.margin_width_nMap of margin numbers to their pixel margin widths.
view.margin_mask_nMap of margin numbers to their marker symbol bit-masks.
Bit-masks are 32-bit values whose bits correspond to the 32 available markers. A margin
whose type is either view.MARGIN_SYMBOL, view.MARGIN_BACK, view.MARGIN_FORE, or
view.MARGIN_COLOR can show any marker whose bit is set in the mask.
The default values are 0, ~view.MASK_FOLDERS, view.MASK_FOLDERS, and 0 for the rest.
Usage:
view.margin_mask_n[2] = ~view.MASK_FOLDERS -- display non-folding markers
view.margin_mask_n[3] = view.MASK_FOLDERS -- only display folding markers
view.margin_sensitive_nMap of margin numbers to whether or not mouse clicks in them emit events.MARGIN_CLICK.
The default values are false for the first margin and true for the others.
view.margin_cursor_nMap of margin numbers to their displayed mouse cursors.
view.CURSORARROW: Normal arrow cursor.view.CURSORREVERSEARROW: Reversed arrow cursor.The default values are view.CURSORARROW.
buffer.margin_textMap of line numbers to their text margin text.
A margin whose type is either view.MARGIN_TEXT or view.MARGIN_RTEXT can show text in
this map.
Usage:
buffer.margin_text[1] = 'Title:'
buffer.margin_styleMap of line numbers to their text margin style numbers.
A margin whose type is either view.MARGIN_TEXT or view.MARGIN_RTEXT will show text in
buffer.margin_text in the styles specified here.
Note: text margins can only draw some style attributes: font, size, bold, italics, fore, and back.
Usage:
buffer.margin_style[1] = buffer:style_of_name(lexer.BOLD)
See also: view.styles, buffer.style_of_name
buffer:margin_text_clear_all()Clears all text margin text.
view.margin_optionsA bit-mask of margin option settings.
view.MARGINOPTION_NONE: None.view.MARGINOPTION_SUBLINESELECT: Select only a wrapped line’s sub-line (rather than the
entire line) when clicking on the line number margin.The default value is view.MARGINOPTION_NONE.
view.margin_back_nMap of margin numbers to marker symbol margin background colors in “0xBBGGRR” format.
A margin whose type is view.MARGIN_COLOR will use the color specified here.
Usage:
view.margin_back_n[4] = view.colors.light_grey
view:set_fold_margin_color(use_setting, color)Overrides the fold margin’s default color.
Parameters:
view:set_fold_margin_hi_color(use_setting, color)Overrides the fold margin’s default highlight color.
Parameters:
view.margin_leftThe pixel size of buffer text’s left margin.
The default value is 1 in the GUI version and 0 in the terminal version.
view.margin_rightThe pixel size of buffer text’s right margin.
The default value is 1 in the GUI version and 0 in the terminal version.
There are 32 markers to mark lines with. Each marker has an assigned symbol that properly configured margins will display. For lines with multiple markers, markers are drawn over one another in ascending order. Markers move in sync with the lines they were added to as text is inserted and deleted. When a line that has a marker on it is deleted, that marker moves to the previous line.
| Marker symbol | Visual or description |
|---|---|
view.MARK_CIRCLE |
● |
view.MARK_SMALLRECT |
■ |
view.MARK_ROUNDRECT |
A rounded rectangle |
view.MARK_LEFTRECT |
▌ |
view.MARK_FULLRECT |
█ |
view.MARK_SHORTARROW |
A small, right-facing arrow |
view.MARK_ARROW |
► |
view.MARK_ARROWS |
››› |
view.MARK_DOTDOTDOT |
… |
view.MARK_BOOKMARK |
A horizontal bookmark flag |
view.MARK_VERTICALBOOKMARK |
A vertical bookmark flag |
view.MARK_PIXMAP |
An XPM image |
view.MARK_RGBAIMAGE |
An RGBA image |
view.MARK_CHARACTER + i |
The character whose ASCII value is i |
view.MARK_EMPTY |
An empty marker |
view.MARK_BACKGROUND |
Changes a line’s background color |
view.MARK_UNDERLINE |
Underlines an entire line |
| Fold symbols | |
view.MARK_ARROW |
► |
view.MARK_ARROWDOWN |
▼ |
view.MARK_MINUS |
− |
view.MARK_BOXMINUS |
⊟ |
view.MARK_BOXMINUSCONNECTED |
A boxed minus sign connected to a vertical line |
view.MARK_CIRCLEMINUS |
⊖ |
view.MARK_CIRCLEMINUSCONNECTED |
A circled minus sign connected to a vertical line |
view.MARK_PLUS |
+ |
view.MARK_BOXPLUS |
⊞ |
view.MARK_BOXPLUSCONNECTED |
A boxed plus sign connected to a vertical line |
view.MARK_CIRCLEPLUS |
⊕ |
view.MARK_CIRCLEMINUSCONNECTED |
A circled plus sign connected to a vertical line |
view.MARK_VLINE |
│ |
view.MARK_TCORNER |
├ |
view.MARK_LCORNER |
└ |
view.MARK_TCORNERCURVE |
A curved, T-shaped corner |
view.MARK_LCORNERCURVE |
A curved, L-shaped corner |
There are 7 pre-defined marker numbers used for code folding marker symbols.
| Marker Number | Description |
|---|---|
view.MARKNUM_FOLDEROPEN |
The first line of an expanded fold |
view.MARKNUM_FOLDERSUB |
A line within an expanded fold |
view.MARKNUM_FOLDERTAIL |
The last line of an expanded fold |
view.MARKNUM_FOLDER |
The first line of a collapsed fold |
view.MARKNUM_FOLDEROPENMID |
The first line of an expanded fold within an expanded fold |
view.MARKNUM_FOLDERMIDTAIL |
The last line of an expanded fold within an expanded fold |
view.MARKNUM_FOLDEREND |
The first line of a collapsed fold within an expanded fold |
view.new_marker_number()Returns a unique marker number for use with view:marker_define().
Use this function for custom markers in order to prevent clashes with the numbers of other custom markers.
view:marker_define(marker, symbol)Assigns a marker symbol to a marker.
Properly configured marker symbol margins will show the symbol next to lines marked with that marker.
Parameters:
1 to 32 to set symbol for.view.MARK_*.view:marker_define_pixmap(marker, pixmap)Assigns an XPM image to a pixmap marker.
Parameters:
view.MARK_PIXMAP symbol.view:marker_define_rgba_image(marker, pixels)Assigns an RGBA image to an RGBA image marker.
Parameters:
view.MARK_RGBAIMAGE symbol.view.rgba_image_width and view.rgba_image_height, must have
already been defined.See also: view.rgba_image_scale
buffer:marker_add(line, marker)Adds a marker to a line.
Parameters:
1 to 32 to add.Returns: handle for use in buffer:marker_delete_handle() and
buffer:marker_line_from_handle(), or -1 if line is invalid
buffer:marker_add_set(line, marker_mask)Adds a set of markers a line.
Parameters:
buffer:marker_delete_handle(handle)Deletes a marker identified by its handle.
Parameters:
buffer:marker_add() or
buffer:marker_handle_from_line().buffer:marker_delete(line, marker)Deletes a marker from a line.
Parameters:
1 to 32 to delete, or -1 to delete all
markers from line.buffer:marker_delete_all(marker)Deletes a marker from any line that has it.
Parameters:
1 to 32 to delete, or -1 to delete all
markers from lines.buffer:marker_line_from_handle(handle)Returns the line number a particular marker is on, or -1 if the marker was not found.
Parameters:
buffer:marker_add() or
buffer:marker_handle_from_line().buffer:marker_next(line, marker_mask)Returns the line number of the next line that contains a set of markers, or -1 if no line
was found.
Parameters:
buffer:marker_previous(line, marker_mask)Returns the line number of the previous line that contains a set of markers, or -1 if no
line was found.
Parameters:
buffer:marker_handle_from_line(line, n)Returns the handle of a marker on a line.
Parameters:
-1 is returned.buffer:marker_get(line)Returns a bit-mask of all of the markers on a line.
The first bit is set if marker number 1 is present, the second bit for marker number 2, and so on.
Parameters:
buffer:marker_number_from_line(line, n)Returns the number of a marker on a line.
Parameters:
-1 is returned.view:marker_symbol_defined(marker)Returns the marker symbol assigned to a marker.
Parameters:
1 to 32 to get the symbol for.view.marker_foreMap of marker numbers to their foreground colors in “0xBBGGRR” format. (Write-only)
view.marker_fore_translucentMap of marker numbers to their foreground colors in “0xAABBGGRR” format. (Write-only)
view.marker_backMap of marker numbers to their background colors in “0xBBGGRR” format. (Write-only)
view.marker_back_translucentMap of marker numbers to their background colors in “0xAABBGGRR” format. (Write-only)
view.marker_alphaMap of marker numbers to their alpha values.
(Write-only)
A marker whose marker symbol is either view.MARK_BACKGROUND or view.MARK_UNDERLINE
will use the alpha value specified here.
The default values are view.ALPHA_NOALPHA, for no alpha.
view.marker_layerMap of marker numbers to their draw layers.
A marker whose marker symbol is either view.MARK_BACKGROUND or view.MARK_UNDERLINE
will use the draw layer specified here.
view.LAYER_BASE: Draw markers opaquely on the background.view.LAYER_UNDER_TEXT: Draw markers translucently under text.view.LAYER_OVER_TEXT: Draw markers translucently over text.The default values are view.LAYER_BASE.
view.marker_stroke_widthMap of marker numbers to their draw stroke widths in hundredths of a pixel.
(Write-only)
The default values are 100, or 1 pixel.
view:marker_enable_highlight(enabled)Enables the highlighting of margin fold markers for the current fold block.
Parameters:
view.marker_back_selectedMap of marker numbers to their selected folding block background colors in “0xBBGGRR” format. (Write-only)
view.marker_back_selected_translucentMap of marker numbers to their selected folding block background colors in “0xAABBGGRR” format. (Write-only)
Lines may be annotated with styled, read-only text displayed underneath them or next to them at the ends of lines (EOL). This may be useful for displaying compiler errors, runtime errors, variable values, or other useful information.
buffer.annotation_textMap of line numbers to their annotation text.
Usage:
buffer.annotation_text[1] = 'error: undefined variable "x"'
buffer.eol_annotation_textMap of line numbers to their EOL annotation text.
Usage:
buffer.eol_annotation_text[1] = 'x = 1'
buffer.annotation_styleMap of line numbers to their annotation style numbers.
Note: annotations can only draw some style attributes: font, size/size_fractional, bold/weight, italics, fore, back, and character_set.
Usage:
buffer.annotation_style[1] = buffer:style_of_name(lexer.ERROR)
See also: view.styles, buffer.style_of_name
buffer.eol_annotation_styleMap of line numbers to their EOL annotation style numbers.
Note: annotations can only draw style attributes: font, size/size_fractional, bold/weight, italics, fore, back, and character_set.
Usage:
buffer.eol_annotation_style[1] = buffer:style_of_name(view.STYLE_FOLDDISPLAYTEXT)
See also: view.styles, buffer.style_of_name
buffer:annotation_clear_all()Clears annotations from all lines.
buffer:eol_annotation_clear_all()Clears EOL annotations from all lines.
view.annotation_visibleThe annotation display style.
view.ANNOTATION_HIDDEN: Annotations are invisible.view.ANNOTATION_STANDARD: Draw annotations left-justified with no decoration.view.ANNOTATION_BOXED: Indent annotations to match the annotated text and outline them
with a box.view.ANNOTATION_INDENTED: Indent non-decorated annotations to match the annotated text.The default value is view.ANNOTATION_BOXED.
view.eol_annotation_visibleThe EOL annotation display style.
view.EOLANNOTATION_HIDDEN: Annotations are invisible.view.EOLANNOTATION_STANDARD: Draw annotations with no decoration.view.EOLANNOTATION_BOXED: Outline annotations with a box.view.EOLANNOTATION_STADIUM: Outline annotations with curved ends.view.EOLANNOTATION_FLAT_CIRCLE: Outline annotations with flat left and curved right ends.view.EOLANNOTATION_ANGLE_CIRCLE: Outline annotations with angled left and curved right ends.view.EOLANNOTATION_CIRCLE_FLAT: Outline annotations with curved left and flat right ends.view.EOLANNOTATION_FLATS: Outline annotations with flat ends.view.EOLANNOTATION_ANGLE_FLAT: Outline annotations with angled left and flat right ends.view.EOLANNOTATION_CIRCLE_ANGLE: Outline annotations with curved left and angled right ends.view.EOLANNOTATION_FLAT_ANGLE: Outline annotations with flat left and angled right ends.view.EOLANNOTATION_ANGLES: Outline annotations with angled ends.All annotations have the same shape.
The default value is view.EOLANNOTATION_BOXED.
buffer.annotation_linesMap of line numbers to how many annotation text lines they have. (Read-only)
There are 32 indicators to mark text with. Indicators have an assigned indicator style and are displayed along with any existing styles text may already have. They can be hovered over and clicked on. Indicators move along with text.
| Indicator style | Description |
|---|---|
view.INDIC_SQUIGGLE |
A squiggly underline |
view.INDIC_PLAIN |
An underline |
view.INDIC_DASH |
A dashed underline |
view.INDIC_DOTS |
A dotted underline |
view.INDIC_STRIKE |
A strike out line |
view.INDIC_BOX |
A bounding box |
view.INDIC_DOTBOX |
A dotted bounding boxa |
view.INDIC_STRAIGHTBOX |
A translucent bounding boxb |
view.INDIC_ROUNDBOX |
A translucent bounding box with rounded cornersb |
view.INDIC_FULLBOX |
A translucent box that extends to the top of its lineb |
view.INDIC_GRADIENT |
A bounding box with a vertical gradient from solid to transparent |
view.INDIC_GRADIENTCENTER |
A bounding box with a centered gradient from solid to transparent |
view.INDIC_TT |
An underline of small ‘T’ shapes |
view.INDIC_DIAGONAL |
An underline of diagonal hatches |
view.INDIC_POINT |
A triangle below the start of the indicator range |
view.INDIC_POINTCHARACTER |
A triangle below the center of the first character |
view.INDIC_POINT_TOP |
A triangle above the start of the indicator range |
view.INDIC_SQUIGGLELOW |
A thin squiggly underline for small fonts |
view.INDIC_SQUIGGLEPIXMAP |
A faster version of view.INDIC_SQUIGGLE |
view.INDIC_COMPOSITIONTHICK |
A thick underline that looks like input composition |
view.INDIC_COMPOSITIONTHIN |
A thin underline that looks like input composition |
view.INDIC_TEXTFORE |
Changes text’s foreground color |
view.INDIC_HIDDEN |
An indicator with no visual effect |
aTranslucency alternates between view.indic_alpha and view.indic_outline_alpha
starting with the top-left pixel. Their default values are 30, and 50, respectively.
bview.indic_alpha and view.indic_outline_alpha set the fill and outline
transparency, respectively. Their default values are 30, and 50, respectively.
view.new_indic_number()Returns a unique indicator number for use with custom indicators.
Use this function for custom indicators in order to prevent clashes with the numbers of other custom indicators.
view.indic_styleMap of indicator numbers to their indicator styles (view.INDIC_*).
Changing an indicator’s style resets that indicator’s hover style (view.indic_hover_style).
buffer.indicator_currentThe indicator number used by buffer:indicator_fill_range() and
buffer:indicator_clear_range().
buffer:indicator_fill_range(pos, length)Draws indicator number buffer.indicator_current over a range of text.
Parameters:
buffer:indicator_clear_range(pos, length)Clears indicator number buffer.indicator_current over a range of text.
Parameters:
buffer:indicator_start(indicator, pos)Returns the previous boundary position of an indicator, or 1 if no indicator was found.
Parameters:
1 to 32.buffer:indicator_end(indicator, pos)Returns the next boundary position of an indicator, or 1 if no indicator was found.
Parameters:
1 to 32.buffer:indicator_all_on_for(pos)Returns a bit-mask of all of indicators at a position.
The first bit is set if indicator 1 is present, the second bit for indicator 2, and so on.
Parameters:
view.indic_foreMap of indicator numbers to their foreground colors in “0xBBGGRR” format.
Changing an indicator’s foreground color resets that indicator’s hover foreground color
(view.indic_hover_fore).
view.indic_alphaMap of indicator numbers to their fill color alpha values.
An indicator whose indicator style is either view.INDIC_ROUNDBOX, view.INDIC_STRAIGHTBOX,
or view.INDIC_DOTBOX will use the alpha value specified here.
The default values are view.ALPHA_NOALPHA, for no alpha.
view.indic_outline_alphaMap of indicator numbers to their outline color alpha values.
An indicator whose indicator style is either view.INDIC_ROUNDBOX, view.INDIC_STRAIGHTBOX,
or view.INDIC_DOTBOX will use the alpha value specified here.
The default values are view.ALPHA_NOALPHA, for no alpha.
view.indic_underMap of indicator numbers to whether or not to draw them behind text instead of over the top of it.
The default values are false.
view.indic_hover_styleMap of indicator numbers to their hover indicator styles.
Textadept draws an indicator’s hover style when the mouse cursor is hovering over that indicator, or when the caret is within the indicator. The default values are their respective indicator styles; there is no visible hover effect.
See also: view.styles, buffer.name_of_style
view.indic_hover_foreMap of indicator numbers to their hover foreground colors in “0xBBGGRR” format.
The default values are their respective indicator foreground colors; there is no visible hover effect.
Usage:
view.indic_hover_fore[indic_link] = 0xFF0000 -- hovering over links colors them blue
view.indic_stroke_widthMap of indicator numbers to their stroke widths in hundredths of a pixel.
An indicator whose indicator style is either view.INDIC_PLAIN, view.INDIC_SQUIGGLE,
view.INDIC_TT, view.INDIC_DIAGONAL, view.INDIC_STRIKE, view.INDIC_BOX,
view.INDIC_ROUNDBOX, view.INDIC_STRAIGHTBOX, view.INDIC_FULLBOX, view.INDIC_DASH,
view.INDIC_DOTS, or view.INDIC_SQUIGGLELOW will use the stroke width specified here.
The default values are 100, or 1 pixel.
There are two types of lists: autocompletion lists and user lists. An autocompletion list is a list of completions shown for the current word. A user list is a more general list of options presented to the user. Both types of list update as the user types, both have similar behavior options, and both may display images alongside text. Autocompletion lists should define a separator character and a list order before showing the list. User lists should define a separator character, a list order, and an identifier number before showing the list. An autocompletion list inserts its selected item, while a user list emits an event with its selected item.
buffer.auto_c_separatorThe byte value of the character that separates autocompletion and user list list items.
The default value is 32, which is a space character (‘ ‘).
buffer.auto_c_orderThe order of an autocompletion or user list.
buffer.ORDER_PRESORTED: Lists passed to buffer:auto_c_show() and buffer:user_list_show()
are in sorted, alphabetical order.buffer.ORDER_PERFORMSORT: Sort lists passed to buffer:auto_c_show() and
buffer:user_list_show().buffer.ORDER_CUSTOM: Lists passed to buffer:auto_c_show() and buffer:user_list_show()
are already in a custom order.The default value is buffer.ORDER_PRESORTED.
buffer:auto_c_show(len_entered, items)Displays an autocompletion list.
Parameters:
buffer.auto_c_separator
characters. The sort order of this list (buffer.auto_c_order) must have already
been specified.See also: textadept.editing.autocompleters, textadept.editing.autocomplete
view.new_user_list_type()Returns a unique user list identifier number for use with buffer:user_list_show().
Use this function for custom user lists in order to prevent clashes with list identifiers of other custom user lists.
buffer:user_list_show(id, items)Displays a user list.
When the user selects an item, events.USER_LIST_SELECTION is emitted.
Parameters:
buffer.auto_c_separator
characters. The sort order of this list (buffer.auto_c_order) must have already
been specified.buffer:auto_c_select(prefix)Selects the first item that matches a prefix in an autocompletion or user list.
If buffer.auto_c_ignore_case is true, searches case-insensitively.
Parameters:
buffer:auto_c_complete()Completes the current word with the one selected in an autocompletion list.
buffer:auto_c_cancel()Cancels the active autocompletion or user list.
buffer:auto_c_active()Returns whether or not an autocompletion or user list is visible.
buffer:auto_c_pos_start()Returns the position where autocompletion started or where a user list was shown.
buffer.auto_c_currentThe index of the currently selected item in an autocompletion or user list. (Read-only)
buffer.auto_c_current_textThe text of the currently selected item in an autocompletion or user list. (Read-only)
buffer.auto_c_choose_singleAutomatically choose the item in a single-item autocompletion list.
This option has no effect for a user list.
The default value is true.
buffer.auto_c_fill_upsThe set of characters that, when the user types one of them, chooses the currently selected item in an autocompletion or user list. (Write-only) The default value is the empty string.
buffer:auto_c_stops(chars)Specify a set of characters that cancels an autocompletion or user list when the user types one of them.
Parameters:
buffer.auto_c_auto_hideAutomatically cancel an autocompletion or user list when no entries match typed text.
The default value is true.
buffer.auto_c_cancel_at_startCancel an autocompletion list when backspacing to a position before where autocompletion started (instead of before the word being completed).
This option has no effect for a user list.
The default value is true.
buffer.auto_c_ignore_caseIgnore case when searching an autocompletion or user list for matches.
The default value is false.
buffer.auto_c_case_insensitive_behaviorPrefer case-sensitive matches even if buffer.auto_c_ignore_case is true.
buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE: Prefer to select case-sensitive matches.buffer.CASEINSENSITIVEBEHAVIOR_IGNORECASE: No preference.The default value is buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE.
view.auto_c_max_widthThe maximum number of characters per item to show in autocompletion and user lists.
The default value is 0, which automatically sizes the width to fit the longest item.
view.auto_c_max_heightThe maximum number of items per page to show in autocompletion and user lists.
The default value is 5.
buffer.auto_c_drop_rest_of_wordDelete any word characters immediately to the right of autocompleted text.
The default value is false.
buffer.auto_c_multiAutocomplete into multiple selections.
buffer.MULTIAUTOC_ONCE: Autocomplete into only the main selection.buffer.MULTIAUTOC_EACH: Autocomplete into all selections.The default value is buffer.MULTIAUTOC_EACH.
Autocompletion and user lists can render images next to items by appending to each list item the type separator character specific to lists followed by an image’s type number that uniquely identifies a registered image.
local image = view.new_image_type()
events.connect(events.VIEW_NEW, function()
view:register_image(image, [[/* XPM */...]])
end)
local function autocomplete()
local list = {
string.format('foo%s%d', string.char(buffer.auto_c_type_separator), image),
'bar',
'baz'
}
buffer.auto_c_order = buffer.ORDER_PERFORMSORT
buffer:auto_c_show(0, table.concat(list, string.char(buffer.auto_c_separator)))
end
view.new_image_type()Returns a unique image type number for use with view:register_image() and
view:register_rgba_image().
Use this function for custom image types in order to prevent clashes with numbers of other custom image types.
view:register_image(type, pixmap)Registers an XPM image to an image type number for use in autocompletion and user lists.
Parameters:
See also: textadept.editing.XPM_IMAGES
view.rgba_image_widthThe width of the RGBA image to be defined using view:marker_define_rgba_image() and
view:register_rgba_image().
view.rgba_image_heightThe height of the RGBA image to be defined using view:marker_define_rgba_image() and
view:register_rgba_image().
view.rgba_image_scaleThe scale factor in percent of the RGBA image to be defined using
view:marker_define_rgba_image() and view:register_rgba_image().
This is useful on macOS with a retina display where each display unit is 2 pixels: use a
factor of 200 so that each image pixel is displayed using a screen pixel.
The default scale, 100, will stretch each image pixel to cover 4 screen pixels on a
retina display.
view:register_rgba_image(type, pixels)Registers an RGBA image to an image type number for use in autocompletion and user lists.
Parameters:
view.rgba_image_width and view.rgba_image_height, must have
already been defined.buffer.auto_c_type_separatorThe character byte that separates autocompletion and user list items and their image types.
Autocompletion and user list items can display both an image and text. Register images and
their types using view:register_image() or view:register_rgba_image() before appending
image types to list items after type separator characters.
The default value is 63 (‘?’).
view:clear_registered_images()Clears all images registered by view:register_image() and view:register_rgba_image().
A call tip is a small pop-up window that conveys a piece of textual information, such as the arguments and documentation for a function. A call tip may highlight an internal range of its own text, such as the current argument in a function call.
view:call_tip_show(pos, text)Displays a call tip.
Parameters:
See also: events.CALL_TIP_CLICK
view:call_tip_set_hlt(start_pos, end_pos)Highlights a range of the call tip’s text with the color view.call_tip_fore_hlt.
Parameters:
view:call_tip_cancel()Hides the active call tip.
view:call_tip_active()Returns whether or not a call tip is visible.
view:call_tip_pos_start()Returns a call tip’s display position.
view.call_tip_positionDisplay a call tip above the current line instead of below it.
The default value is false.
view.call_tip_use_styleThe pixel width of tab characters in call tips.
When non-zero, also enables the use of style number view.STYLE_CALLTIP instead of
view.STYLE_DEFAULT for call tip styles.
The default value is non-zero and depends on buffer.tab_width and the current font.
view.call_tip_pos_startThe position at which backspacing beyond it hides an active call tip. (Write-only)
view.call_tip_fore_hltA call tip’s highlighted text foreground color in “0xBBGGRR” format. (Write-only)
Code folding temporarily hide blocks of source code. The buffer’s lexer normally determines code fold points that the view denotes with fold margin markers, but arbitrary lines may be hidden or shown.
view:toggle_fold(line)Toggles the fold point on a line between expanded (where all of its child lines are visible) and contracted (where all of its child lines are hidden).
Parameters:
view:set_default_fold_display_text(text)Sets the default text shown next to folded lines.
Parameters:
view.STYLE_FOLDDISPLAYTEXT style.Usage:
view:set_default_fold_display_text(' ... ')
view:toggle_fold_show_text(line, text)Toggles the fold point on a line and shows the given text next to that line if it is collapsed.
This overrides any default text set by view:set_default_fold_display_text().
Parameters:
view.STYLE_FOLDDISPLAYTEXT style.view:fold_line(line, action)Contracts, expands, or toggles the fold point on a line.
Parameters:
view.FOLDACTION_CONTRACTview.FOLDACTION_EXPANDview.FOLDACTION_TOGGLEview:fold_children(line, action)Contracts, expands, or toggles the fold points on a line and on all of its child lines.
Parameters:
view.FOLDACTION_CONTRACTview.FOLDACTION_EXPANDview.FOLDACTION_TOGGLEview:fold_all(action)Contracts, expands, or toggles all fold points in the buffer.
When toggling, the state of the first fold point determines whether to expand or contract.
Parameters:
view.FOLDACTION_CONTRACTview.FOLDACTION_EXPANDview.FOLDACTION_TOGGLEview.FOLDACTION_CONTRACT_EVERY_LEVELview:hide_lines(start_line, end_line)Hides a range of lines.
This has no effect on fold levels or fold flags.
Parameters:
view:show_lines(start_line, end_line)Shows a range of lines.
This has no effect on fold levels or fold flags and the first line cannot be hidden.
Parameters:
view:ensure_visible(line)Ensures a line is visible by expanding any fold points hiding it.
Parameters:
view:ensure_visible_enforce_policy(line)Ensures a line is visible by expanding any fold points hiding it based on the vertical caret
policy previously defined in view:set_visible_policy().
Parameters:
view:get_default_fold_display_text()Returns the default text shown next to folded lines.
buffer.fold_levelMap of line numbers to their fold level bit-masks.
Fold level bit-masks comprise an integer level combined with any of the following bit flags:
buffer.FOLDLEVELBASE: The initial fold level.buffer.FOLDLEVELWHITEFLAG: The line is blank.buffer.FOLDLEVELHEADERFLAG: The line is a header, or fold point.buffer.fold_parentMap of line numbers to their parent fold point line numbers.
(Read-only)
A result of -1 means the line has no parent fold point.
buffer:get_last_child(line, level)Returns the line number of a fold point’s last child line.
Parameters:
-1. For any other value, the line number of the last line after line whose
fold level is greater than level is returned.view.fold_expandedMap of line numbers to whether or not their fold points (if any) are expanded.
Setting expanded fold states does not toggle folds; it only updates fold margin markers. Use
view:toggle_fold() instead.
view:contracted_fold_next(line)Returns the line number of the next contracted fold point, or -1 if none exists.
Parameters:
view.line_visibleMap of line numbers to whether or not they are visible. (Read-only)
view.all_lines_visibleWhether or not all lines are visible. (Read-only)
view.x_offsetThe horizontal scroll pixel position.
The default value is 0.
See also: view.first_visible_line
view:line_scroll_up()Scrolls the buffer up one line, keeping the caret visible.
view:line_scroll_down()Scrolls the buffer down one line, keeping the caret visible.
view:line_scroll(columns, lines)Scrolls the buffer by columns and lines.
Parameters:
view:scroll_caret()Scrolls the caret into view based on the policies previously defined in
view:set_x_caret_policy() and view:set_y_caret_policy().
view:scroll_range(secondary_pos, primary_pos)Scrolls a range of text into view.
This is similar to view:scroll_caret(), but with primary_pos instead of the caret.
It is useful for scrolling search results into view.
Parameters:
view:vertical_center_caret()Centers the current line in the view.
view:scroll_to_start()Scrolls to the beginning of the buffer without moving the caret.
view:scroll_to_end()Scrolls to the end of the buffer without moving the caret.
Each buffer and file has its own indentation and end-of-line character settings.
buffer.use_tabsUse tabs instead of spaces in indentation.
Changing this does not convert any of the buffer’s existing indentation. Use
textadept.editing.convert_indentation() to do so.
The default value is true.
buffer.tab_widthThe number of space characters a tab character represents.
The default value is 8.
buffer.indentThe number of spaces in one level of indentation.
The default value is 0, which uses the value of buffer.tab_width.
buffer.tab_indentsIndent text when tabbing within indentation.
The default value is true.
See also: textadept.editing.auto_indent
buffer.back_space_un_indentsUn-indent text when backspacing within indentation.
The default value is true.
buffer.eol_modeThe current end of line mode.
Changing this does not convert any of the buffer’s existing end of line characters. Use
buffer:convert_eols() to do so.
buffer.EOL_CRLF: Carriage return with line feed (“\r\n”).buffer.EOL_CR: Carriage return (“\r”).buffer.EOL_LF: Line feed (“\n”).The default value is buffer.EOL_CRLF on Windows platforms, and buffer.EOL_LF otherwise.
buffer:convert_eols(mode)Changes all end of line characters in the buffer.
This does not change buffer.eol_mode.
Parameters:
buffer.EOL_CRLFbuffer.EOL_CRbuffer.EOL_LFThe classification of characters as word, whitespace, or punctuation characters affects the buffer’s behavior when moving between words or searching for whole words. The display of individual characters may be changed.
buffer.word_charsThe string set of characters recognized as word characters.
The default value is a string that contains alphanumeric characters, an underscore, and all characters greater than ASCII value 127.
buffer.whitespace_charsThe string set of characters recognized as whitespace characters.
Set this only after setting buffer.word_chars.
The default value is a string that contains all non-newline characters less than ASCII value 33.
buffer.punctuation_charsThe string set of characters recognized as punctuation characters.
Set this only after setting buffer.word_chars.
The default value is a string that contains all non-word and non-whitespace characters.
buffer:set_chars_default()Resets buffer.word_chars, buffer.whitespace_chars, and buffer.punctuation_chars to
their respective defaults.
view.representationMap of character strings to their alternative string representations.
Use the empty string for the ‘\0’ character when assigning its representation.
Call view:clear_representation() to remove a representation.
Usage:
view.representation['⌘'] = '⌘ (U+2318)'
view:clear_representation(char)Removes a character’s alternate string representation.
Parameters:
view.representation to remove. It may be a multi-byte
character.view:clear_all_representations()Removes all alternate string representations of characters.
view.representation_appearanceMap of character strings to their representation’s appearance.
view.REPRESENTATION_PLAIN: Draw the representation with no decoration.view.REPRESENTATION_BLOB: Draw the representation within a rounded rectangle and an
inverted color.view.REPRESENTATION_COLOR: Draw the representation using the color set in
view.representation_color.The default values are view.REPRESENTATION_BLOB.
view.representation_colorMap of character strings to their representation’s color in “0xBBGGRR” format.
Themes are Lua files that define colors, specify how the view displays text, and assign colors and alpha values to various view properties.
Colors are numbers in “0xBBGGRR” format that range from 0 (black) to 0xFFFFFF (white). The
low byte (RR) is the red component, the middle byte (GG) is green, and the high byte (BB)
is blue. Each component ranges from 0 to 0xFF (255).
Alpha transparency values are numbers that range from 0 (transparent) to 0xFF (opaque),
and also includes view.ALPHA_NOALPHA for no transparency.
Terminal version note: irrespective of how many colors the terminal actually supports, Textadept only recognizes 16 colors:
0x000000 |
Black | 0x404040 |
Light black |
0x000080 |
Red | 0x0000FF |
Light red |
0x008000 |
Green | 0x00FF00 |
Light green |
0x800000 |
Blue | 0xFF0000 |
Light blue |
0x800080 |
Magenta | 0xFF00FF |
Light magenta |
0x808000 |
Cyan | 0xFFFF00 |
Light cyan |
0xC0C0C0 |
White | 0xFFFFFF |
Light white |
Themes must use these colors, but your terminal emulator will map them to its own palette.
Styles define how to display text, from the default font to line numbers in the margin, to source code comments, strings, and keywords. Each of these elements has a style name assigned to a table of style properties.
| Style name | Target element |
|---|---|
view.STYLE_DEFAULT |
Everything (all elements inherit from this one) |
view.STYLE_LINENUMBER |
The line number margin |
view.STYLE_BRACELIGHT |
Highlighted brace characters |
view.STYLE_BRACEBAD |
A brace character with no match |
view.STYLE_CONTROLCHAR |
Control character blocks |
view.STYLE_INDENTGUIDE |
Indentation guides |
view.STYLE_CALLTIP |
Call tip texta |
view.STYLE_FOLDDISPLAYTEXT |
Text displayed next to folded lines |
lexer.ATTRIBUTE |
Language-specific |
lexer.BOLD |
Language-specific |
lexer.CLASS |
Language-specific |
lexer.CODE |
Language-specific |
lexer.COMMENT |
Language-specific |
lexer.CONSTANT |
Language-specific |
lexer.CONSTANT_BUILTIN |
Language-specific |
lexer.EMBEDDED |
Language-specific |
lexer.ERROR |
Language-specific |
lexer.FUNCTION |
Language-specific |
lexer.FUNCTION_BUILTIN |
Language-specific |
lexer.FUNCTION_METHOD |
Language-specific |
lexer.IDENTIFIER |
Language-specific |
lexer.ITALIC |
Language-specific |
lexer.KEYWORD |
Language-specific |
lexer.LABEL |
Language-specific |
lexer.LINK |
Language-specific |
lexer.NUMBER |
Language-specific |
lexer.OPERATOR |
Language-specific |
lexer.PREPROCESSOR |
Language-specific |
lexer.REFERENCE |
Language-specific |
lexer.REGEX |
Language-specific |
lexer.STRING |
Language-specific |
lexer.TAG |
Language-specific |
lexer.TYPE |
Language-specific |
lexer.UNDERLINE |
Language-specific |
lexer.VARIABLE |
Language-specific |
lexer.VARIABLE_BUILTIN |
Language-specific |
a Only the font, size, fore, and back style properties are supported.
The table above is not an exhaustive list of style names. Some lexers may define their own.
| Style property | Description |
|---|---|
font |
String font name |
size |
Integer font size |
bold |
Use a bold font face (the default value is false) |
weight |
Integer weight or boldness of a font, between 1 and 999 |
italic |
Use an italic font face (the default value is false) |
underline |
Use an underlined font face (the default value is false) |
fore |
Font face foreground color in “0xBBGGRR” format |
back |
Font face background color in “0xBBGGRR” format |
eol_filled |
Extend the background color to the end of the line (the default value is false) |
case |
Font casea |
visible |
The text is visible instead of hidden (the default value is true) |
changeable |
The text is changeable instead of read-only t(he default value is true) |
aview.CASE_UPPER for upper, view.CASE_LOWER for lower, and view.CASE_MIXED
for normal, mixed case. The default value is view.CASE_MIXED.
view:set_theme([name][, env])Sets the view’s color theme.
User themes in ~/.textadept/themes/ override Textadept’s default themes when they have the same name.
Parameters:
Usage:
view:set_theme{font = 'Monospace', size = 12} -- keep current theme, but change font
view:set_theme('my_theme', {font = 'Monospace', size = 12})
view.colorsMap of color name strings to color values in “0xBBGGRR” format.
A theme typically sets this map’s contents. Changing colors manually (e.g. via the command entry) has no effect since colors are referenced by value, not name.
Terminal version note: only 16 color values are recognized: 0x000000 (black), 0x000080 (red), 0x008000 (green), 0x008080 (yellow), 0x800000 (blue), 0x800080 (magenta), 0x808000 (cyan), white (0xC0C0C0), light 0x404040 (black), 0x0000FF (light red), 0x00FF00 (light green), 0x00FFFF (light yellow), 0xFF0000 (light blue), 0xFF00FF (light magenta), 0xFFFF00 (light cyan), and 0xFFFFFF (light white).
view.stylesMap of style names to style definition tables.
A theme typically sets this map’s contents. If you are setting it manually (e.g. via the
command entry), call view:set_styles() to refresh the view and apply the styles.
Predefined style names are view.STYLE_* and lexer.[A-Z]*, and lexers may define their
own. To see the name of the style under the caret, use the “Tools > Show Style” menu item.
Terminal version note: displaying light colors may require a normal foreground color coupled
with a bold = true setting.
Usage:
view.styles[view.STYLE_DEFAULT] = {
font = 'Monospace', size = '10', fore = view.colors.black, back = view.colors.white
}
view.styles[lexer.KEYWORD] = {bold = true}
view.styles[lexer.ERROR] = {fore = view.colors.red, italic = true}
view:set_styles()Applies defined styles to the view.
This should be called any time a style in view.styles changes.
There are 256 different styles to style text with. The color theme normally dictates default styles, but custom fonts, colors, and attributes may be applied to styles outside of themes. However, these custom settings must be re-applied every time a new buffer or view is created, and every time a lexer is loaded.
view:style_reset_default()Resets view.STYLE_DEFAULT to its initial state.
view:style_clear_all()Reverts all styles to having the same properties as view.STYLE_DEFAULT.
view.style_fontMap of style numbers to their text’s string font names.
view.style_sizeMap of style numbers to their text’s integer font sizes.
view.style_foreMap of style numbers to their text’s foreground colors in “0xBBGGRR” format.
view.style_backMap of style numbers to their text’s background colors in “0xBBGGRR” format.
view.style_boldMap of style numbers to whether or not their text is bold.
The default values are false.
view.style_italicMap of style numbers to whether or not their text is italic.
The default values are false.
view.style_underlineMap of style numbers to whether or not their text is underlined.
The default values are false.
view.style_eol_filledMap of style numbers to whether or not their text’s background colors extend all the way to the view’s right margin.
This only happens for styles whose characters occur last on lines.
The default values are false.
view.style_caseMap of style numbers to their text’s letter-cases.
view.CASE_MIXED: Display text normally.view.CASE_UPPER: Display text in upper case.view.CASE_LOWER: Display text in lower case.view.CASE_CAMEL: Display text in camel case.The default values are view.CASE_MIXED.
view.style_visibleMap of style numbers to whether or not their text is visible.
The default values are true.
view.style_changeableMap of style numbers to their text’s mutability.
Read-only styles do not allow the caret into ranges of their text.
The default values are true.
The colors of various UI elements can be changed by assigning colors to their element IDs
in the view.element_color map.
| Element ID | Description |
|---|---|
view.ELEMENT_SELECTION_TEXT |
Main selection text color |
view.ELEMENT_SELECTION_BACK |
Main selection background color |
view.ELEMENT_SELECTION_ADDITIONAL_TEXT |
Additional selection text color |
view.ELEMENT_SELECTION_ADDITIONAL_BACK |
Additional selection background color |
view.ELEMENT_SELECTION_SECONDARY_TEXT |
Secondary selection text colora |
view.ELEMENT_SELECTION_SECONDARY_BACK |
Secondary selection background colora |
view.ELEMENT_SELECTION_INACTIVE_TEXT |
Selection text color when another window has focus |
view.ELEMENT_SELECTION_INACTIVE_BACK |
Selection background color when another window has focus |
view.ELEMENT_SELECTION_INACTIVE_ADDITIONAL_TEXT |
Inactive additional selection text color |
view.ELEMENT_SELECTION_INACTIVE_ADDITIONAL_BACK |
Inactive additional selection background color |
view.ELEMENT_CARET |
Main selection caret color |
view.ELEMENT_CARET_ADDITIONAL |
Additional selection caret color |
view.ELEMENT_CARET_LINE_BACK |
Background color of the line that contains the caret |
view.ELEMENT_WHITE_SPACE |
Visible whitespace color |
view.ELEMENT_WHITE_SPACE_BACK |
Visible whitespace background color |
view.ELEMENT_FOLD_LINE |
Fold line color |
view.ELEMENT_HIDDEN_LINE |
The color of lines shown in place of hidden lines |
aLinux only
view.element_colorMap of UI element identifiers (view.ELEMENT_*) to their colors in “0xAABBGGRR” format.
If the alpha byte is omitted, it is assumed to be 0xFF (opaque).
view.element_is_setMap of UI element identifiers to whether or not their colors have been manually set.
view:reset_element_color(element)Resets the color of a UI element to its default color.
Parameters:
view.ELEMENT_* UI elements.view.element_base_colorMap of UI element identifiers to their default colors in “0xAABBGGRR” format. (Read-only)
view.element_allows_translucentMap of UI element identifiers to whether or not their elements support translucent colors.
view.selection_layerHow selections are drawn.
view.LAYER_BASE: Draw selections opaquely on the background.view.LAYER_UNDER_TEXT: Draw selections translucently under text.view.LAYER_OVER_TEXT: Draw selections translucently over text.The default value is view.LAYER_BASE.
view.caret_styleThe caret’s visual style.
view.CARETSTYLE_INVISIBLE: No caret.view.CARETSTYLE_LINE: A line caret.view.CARETSTYLE_BLOCK: A block caret.The default value is view.CARETSTYLE_LINE.
view.caret_widthThe line caret’s pixel width in insert mode, between 0 and 20.
The default value is 1.
view.caret_periodThe time between caret blinks in milliseconds.
A value of 0 stops blinking.
The default value is 500.
view.caret_line_frameThe caret line’s frame width in pixels.
When non-zero, the line that contains the caret is framed instead of colored in. The
view.ELEMENT_CARET_LINE_BACK color applies to the frame.
The default value is 0.
view.caret_line_highlight_sublineShow the caret line on sublines rather than entire wrapped lines.
The defalt value is false.
view.caret_line_visible_alwaysAlways show the caret line, even when the view is not in focus.
The default value is true, but only for the current view, and only while Textadept has focus.
view.caret_line_layerHow the caret line is drawn.
view.LAYER_BASE: Draw the caret line opaquely on the background.view.LAYER_UNDER_TEXT: Draw the caret line translucently under text.view.LAYER_OVER_TEXT: Draw the caret line translucently over text.The default value is view.LAYER_BASE.
view.additional_carets_visibleDisplay additional carets.
The default value is true.
view.additional_carets_blinkAllow additional carets to blink.
The default value is true.
buffer.virtual_space_optionsEnable virtual space, allowing the caret to move into the space past end of line characters.
This is either buffer.VS_NONE (disable virtual space) or a bit-mask of the following options:
buffer.VS_RECTANGULARSELECTION: Enable virtual space only for rectangular selections.buffer.VS_USERACCESSIBLE: Enable virtual space outside of rectangular selections.buffer.VS_NOWRAPLINESTART: Prevent the caret from wrapping to the previous line via
buffer:char_left() and buffer:char_left_extend().The default value is buffer.VS_NONE.
view.sel_eol_filledExtend the selection to the view’s right margin if it spans multiple lines.
The default value is false.
Normally, tab, space, and end of line characters are invisible.
view.view_wsShow whitespace characters.
view.WS_INVISIBLE: Whitespace is invisible.view.WS_VISIBLEALWAYS: Display all space characters as dots and tab characters as arrows.view.WS_VISIBLEAFTERINDENT: Display only non-indentation spaces and tabs as dots and arrows.view.WS_VISIBLEONLYININDENT: Display only indentation spaces and tabs as dots and arrows.The default value is view.WS_INVISIBLE.
view.whitespace_sizeThe pixel size of the dots that represent space characters when whitespace is visible.
The default value is 1.
view.tab_draw_modeHow visible tabs are drawn.
view.TD_LONGARROW: Draw tabs as arrows that stretch up to tabstops.view.TD_STRIKEOUT: Draw tabs as horizontal lines that stretch up to tabstops.The default value is view.TD_LONGARROW.
view.view_eolDisplay end of line characters.
The default value is false.
view.extra_ascentThe amount of pixel padding above lines.
The default value is 0.
view.extra_descentThe amount of pixel padding below lines.
The default is 0.
view.h_scroll_barDisplay the horizontal scroll bar.
The default value is true in the GUI version and false in the terminal version.
view.v_scroll_barDisplay the vertical scroll bar.
The default value is true.
view.scroll_widthThe horizontal scrolling pixel width.
If view.scroll_width_tracking is false, the view uses this static width for horizontal
scrolling instead of measuring the width of buffer lines.
The default value is 1 in conjunction with view.scroll_width_tracking being true. A
value of 2000 is reasonable if view.scroll_width_tracking is false.
view.scroll_width_trackingGrow (but never shrink) view.scroll_width as needed to match the maximum width of a
displayed line.
Enabling this may have performance implications for buffers with long lines.
The default value is true.
view.end_at_last_lineDisable scrolling past the last line.
The default value is true.
view:set_x_caret_policy(policy, x)Defines a scrolling policy for keeping the caret away from the horizontal margins.
Parameters:
view.CARET_SLOP
When the caret goes out of view, scroll the view so the caret is x pixels
away from the right margin.view.CARET_STRICT
Scroll the view to ensure the caret stays x pixels away from the right margin.view.CARET_EVEN
Consider both horizontal margins instead of just the right one.view.CARET_JUMPS
Scroll the view more than usual in order to scroll less often.view:set_y_caret_policy(policy, y)Defines a scrolling policy for keeping the caret away from the vertical margins.
Parameters:
view.CARET_SLOP
When the caret goes out of view, scroll the view so the caret is y lines
below from the top margin.view.CARET_STRICT
Scroll the view to ensure the caret stays y lines below from the top margin.view.CARET_EVEN
Consider both vertical margins instead of just the top one.view.CARET_JUMPS
Scroll the view more than usual in order to scroll less often.view:set_visible_policy(policy, y)Defines a scrolling policy for keeping the caret away from the vertical margins when
view:ensure_visible_enforce_policy() redisplays hidden or folded lines.
It is similar in operation to view:set_y_caret_policy().
Parameters:
view.VISIBLE_SLOP
When the caret is out of view, scroll the view so the caret is y lines away
from the vertical margins.view.VISIBLE_STRICT
Scroll the view to ensure the caret stays a y lines away from the vertical
margins.view.cursorThe mouse cursor to show.
view.CURSORNORMAL: The text insert cursor.view.CURSORARROW: The arrow cursor.view.CURSORWAIT: The wait cursor.view.CURSORREVERSEARROW: The reversed arrow cursor.The default value is view.CURSORNORMAL.
By default, lines that contain more characters than the view can show do not wrap into view and onto sub-lines.
view.wrap_modeWrap long lines.
view.WRAP_NONE: Do not wrap long lines.view.WRAP_WORD: Wrap long lines at word (and style) boundaries.view.WRAP_CHAR: Wrap long lines at character boundaries.view.WRAP_WHITESPACE: Wrap long lines at word boundaries (ignoring style boundaries).The default value is view.WRAP_NONE.
view.wrap_visual_flagsHow to mark wrapped lines.
view.WRAPVISUALFLAG_NONE: No visual flags.view.WRAPVISUALFLAG_END: Show a visual flag at the end of a wrapped line.view.WRAPVISUALFLAG_START: Show a visual flag at the beginning of a sub-line.view.WRAPVISUALFLAG_MARGIN: Show a visual flag in the sub-line’s line number margin.The default value is view.WRAPVISUALFLAG_NONE.
view.wrap_visual_flags_locationWhere to mark wrapped lines.
view.WRAPVISUALFLAGLOC_DEFAULT: Draw a visual flag near the view’s right margin.view.WRAPVISUALFLAGLOC_END_BY_TEXT: Draw a visual flag near text at the end of a
wrapped line.view.WRAPVISUALFLAGLOC_START_BY_TEXT: Draw a visual flag near text at the beginning of
a subline.The default value is view.WRAPVISUALFLAGLOC_DEFAULT.
view.wrap_indent_modeIndent wrapped lines.
view.WRAPINDENT_FIXED: Indent wrapped lines by view.wrap_start_indent number of spaces.view.WRAPINDENT_SAME: Indent wrapped lines the same amount as the first line.view.WRAPINDENT_INDENT: Indent wrapped lines one more level than the level of the
first line.view.WRAPINDENT_DEEPINDENT: Indent wrapped lines two more levels than the level of the
first line.The default value is view.WRAPINDENT_FIXED.
view.wrap_start_indentThe number of spaces of indentation to display wrapped lines with if
view.wrap_indent_mode is view.WRAPINDENT_FIXED.
The default value is 0.
view:zoom_in()Increases the size of all fonts by one point, up to a net increase of +60.
view:zoom_out()Decreases the size of all fonts by one point, up to a net decrease of -10.
view.zoomThe number of points to add to the size of all fonts.
Negative values are allowed, down to -10.
The default value is 0.
While the view does not enforce a maximum line length, it allows for visual identification of long lines.
view.edge_columnThe column number to mark long lines at.
view.edge_modeHow to mark long lines.
view.EDGE_NONE: Do not mark long lines.view.EDGE_LINE: Draw a single vertical line whose color is view.edge_color at column
view.edge_column.view.EDGE_BACKGROUND: Change the background color of text after column view.edge_column
to view.edge_color.view.EDGE_MULTILINE: Draw vertical lines whose colors and columns are defined by calls to
view:multi_edge_add_line().The default value is view.EDGE_NONE.
view:multi_edge_add_line(column, color)Adds a new vertical long line marker.
Parameters:
view:multi_edge_clear_all()Clears all vertical lines created by view:multi_edge_add_line().
view.multi_edge_columnMap of edge column numbers to their column positions.
(Read-only)
A position of -1 means no edge column was found.
view.edge_colorThe color, in “0xBBGGRR” format, of the single edge or background for long lines (depending on
view.edge_mode).
view.foldingEnable folding for the lexers that support it.
The default value is true.
view.fold_compactConsider any blank lines after an ending fold point as part of the fold.
The default value is false.
view.fold_on_zero_sum_linesMark as fold points lines that contain both an ending and starting fold point.
For example, mark } else { as a fold point.
The default value is false.
view.fold_by_indentationFold based on indentation level if a lexer does not have a folder.
Some lexers automatically enable this option.
The default value is false.
view.fold_flagsBit-mask of folding lines to draw in the buffer. (Read-only)
view.FOLDFLAG_NONE: Do not draw folding lines.view.FOLDFLAG_LINEBEFORE_EXPANDED: Draw lines above expanded folds.view.FOLDFLAG_LINEBEFORE_CONTRACTED: Draw lines above collapsed folds.view.FOLDFLAG_LINEAFTER_EXPANDED: Draw lines below expanded folds.view.FOLDFLAG_LINEAFTER_CONTRACTED: Draw lines below collapsed folds.view.FOLDFLAG_LEVELNUMBERS: Show hexadecimal fold levels in line margins.
This option cannot be combined with view.FOLDFLAG_LINESTATE.view.FOLDFLAG_LINESTATE: Show line state in line margins.
This option cannot be combined with view.FOLDFLAG_LEVELNUMBERS.The default value is view.FOLDFLAG_LINEAFTER_CONTRACTED in the GUI version, and
view.FOLDFLAG_NONE in the terminal version.
view.fold_display_text_styleHow to draw text shown next to folded lines.
view.FOLDDISPLAYTEXT_HIDDEN: Do not show fold display text.view.FOLDDISPLAYTEXT_STANDARD: Show fold display text with no decoration.view.FOLDDISPLAYTEXT_BOXED: Show fold display text outlined with a box.The default value is view.FOLDDISPLAYTEXT_BOXED.
view:brace_bad_light(pos)Highlights an unmatched brace character using the view.STYLE_BRACEBAD style.
Parameters:
-1 to remove the highlight.view:brace_bad_light_indicator(use_indicator, indicator)Indicates unmatched brace characters should highlight with an indicator instead of the
view.STYLE_BRACEBAD style.
Parameters:
view:brace_highlight(pos1, pos2)Highlights characters as matching braces using the view.STYLE_BRACELIGHT style.
If indent guides are enabled, this also uses buffer.column to locate the column of the
brace characters and sets view.highlight_guide in order to highlight the indent guide too.
Parameters:
view:brace_highlight_indicator(use_indicator, indicator)Indicates matching brace characters should highlight with an indicator instead of the
view.STYLE_BRACELIGHT style.
Parameters:
view.indentation_guidesDraw indentation guides.
Indentation guides are dotted vertical lines that appear within indentation whitespace at each level of indentation.
view.IV_NONE: Do not draw any guides.view.IV_REAL: Draw guides only within indentation whitespace.view.IV_LOOKFORWARD: Draw guides beyond the current line up to the next non-empty line’s
indentation level, but with an additional level if the previous non-empty line is a
fold point.view.IV_LOOKBOTH: Draw guides beyond the current line up to either the indentation level
of the previous or next non-empty line, whichever is greater.The default value is view.IV_LOOKBOTH in the GUI version, and view.IV_NONE in the
terminal version.
view.highlight_guideThe indentation guide column number to also highlight when highlighting matching braces, or
0 to stop indentation guide highlighting.
buffer:set_lexer([name])Sets the buffer’s lexer.
Parameters:
nil, Textadept tries to auto-detect the
buffer’s lexer.See also: lexer.detect_extensions, lexer.detect_patterns
buffer:get_lexer([current=false])Returns the buffer’s lexer name.
Parameters:
false, the parent lexer is always returned.buffer.lexer_languageThe buffer’s lexer name.
(Read-only)
If the lexer is a multi-language lexer, buffer:get_lexer() can obtain the lexer under
the caret.
Plain text can be manually styled after manually setting up styles.
buffer:colorize(start_pos, end_pos)Instructs the lexer to style and mark fold points in a range of text.
This is useful for reprocessing and refreshing a range of text if that range has incorrect highlighting or incorrect fold points.
Parameters:
-1 for the end of the buffer.buffer:clear_document_style()Clears all styling and folding information.
buffer:start_styling(position, unused)Begins styling at a given position.
This must be called before any calls to buffer:set_styling().
Parameters:
0 can be safely used.buffer:set_styling(length, style)Assigns a style to the next range of buffer text.
This will update the current styling position.
buffer:start_styling() must have already been called.
Parameters:
1 to 256.buffer.style_atMap of buffer positions to their style numbers. (Read-only)
buffer.named_stylesThe number of named lexer styles.
buffer:name_of_style(style)Returns the name of a style number.
Note: due to an implementation detail, the returned style contains ‘.’ instead of ‘_’. When setting styles, the ‘_’ form is preferred.
Parameters:
1 and 256 to get the name of.buffer:style_of_name(style_name)Returns the style number associated with a style name, or view.STYLE_DEFAULT if that name
is not in use.
Parameters:
buffer.end_styledThe current styling position or the last correctly styled character’s position. (Read-only)
buffer.tab_labelThe buffer’s tab label in the tab bar. (Write-only) Textadept sets this automatically based on the buffer’s filename or type, and its save status.
buffer.read_onlyWhether or not the buffer is read-only.
The default value is false.
buffer:cancel()Cancels the active selection mode, autocompletion or user list, call tip, etc.
buffer.overtypeEnable overtype mode, where typed characters overwrite existing ones.
The default value is false.
buffer:edit_toggle_overtype()Toggles buffer.overtype.
view.idle_stylingEnable background styling while the editor is idle.
This setting has no effect when view.wrap_mode is on.
view.IDLESTYLING_NONE: Require text to be styled before displaying it.view.IDLESTYLING_TOVISIBLE: Style some text before displaying it and then style the rest
incrementally in the background as an idle-time task.view.IDLESTYLING_AFTERVISIBLE: Style text after the currently visible portion in the
background.view.IDLESTYLING_ALL: Style text both before and after the visible text in the background.The default value is view.IDLESTYLING_ALL.
view.mouse_dwell_timeThe number of milliseconds the mouse must idle before generating an events.DWELL_START event.
A time of view.TIME_FOREVER will never generate one.
buffer:delete()Deletes the buffer.
Do not call this function. Call buffer:close() instead.
See also: events.BUFFER_DELETED
events moduleTextadept’s core event structure and handlers.
Textadept emits events when you do things like create a new buffer, press a key, click on
a menu, etc. You can even emit events yourself using Lua. Each event has a set of event
handlers, which are simply Lua functions called in the order they were connected to an
event. For example, if you created a module that needs to do something each time Textadept
creates a new buffer, connect a Lua function to the events.BUFFER_NEW event:
events.connect(events.BUFFER_NEW, function()
-- Do something here.
end)
Events themselves are nothing special. You do not have to declare one before using it. Events
are simply strings containing arbitrary event names. When either you or Textadept emits an
event, Textadept runs all event handlers connected to the event, passing any given arguments
to the event’s handler functions. If an event handler explicitly returns a value that is not
nil, Textadept will not call subsequent handlers. This is useful if you want to stop the
propagation of an event like a keypress if your event handler handled it, or if you want to
use the event framework to pass values.
events.APPLEEVENT_ODOCEmitted when macOS tells Textadept to open a file.
Arguments:
events.ARG_NONEEmitted when no filename or directory command line arguments are passed to Textadept on startup.
events.AUTO_C_CANCELEDEmitted when canceling an autocompletion or user list.
events.AUTO_C_CHAR_DELETEDEmitted after deleting a character while an autocompletion or user list is active.
events.AUTO_C_COMPLETEDEmitted after inserting an item from an autocompletion list into the buffer.
Arguments:
buffer.auto_c_fill_ups that made the selection,
or 0 if no character was used.events.AUTO_C_SELECTIONEmitted after selecting an item from an autocompletion list, but before inserting that item into the buffer.
Calling buffer:auto_c_cancel() from an event handler will prevent automatic insertion.
Arguments:
buffer.auto_c_fill_ups that made the selection,
or 0 if no character was used.events.AUTO_C_SELECTION_CHANGEEmitted as items are highlighted in an autocompletion or user list.
Arguments:
buffer:user_list_show() or 0 for an autocompletion list.events.BUFFER_AFTER_REPLACE_TEXTEmitted after replacing the contents of the current buffer.
Note that it is not guaranteed that events.BUFFER_BEFORE_REPLACE_TEXT was emitted previously.
The buffer must not be modified during this event.
events.BUFFER_AFTER_SWITCHEmitted after switching to another buffer.
The buffer being switched to is buffer.
See also: view.goto_buffer
events.BUFFER_BEFORE_REPLACE_TEXTEmitted before replacing the contents of the current buffer.
Note that it is not guaranteed that events.BUFFER_AFTER_REPLACE_TEXT will be emitted
shortly after this event.
The buffer must not be modified during this event.
events.BUFFER_BEFORE_SWITCHEmitted before switching to another buffer.
The buffer being switched from is buffer.
See also: view.goto_buffer, buffer.new
events.BUFFER_DELETEDEmitted after deleting a buffer.
Arguments:
buffer.filename can be read.See also: buffer.delete
events.BUFFER_NEWEmitted after creating a new buffer.
The new buffer is buffer.
See also: buffer.new
events.BUILD_OUTPUTEmitted when an executed build command has output.
The default behavior is to print output to the output buffer. In order to override this,
connect to this event with an index of 1 and return true.
Arguments:
events.CALL_TIP_CLICKEmitted when clicking on a calltip.
This event is not emitted by the Qt version.
Arguments:
1 if the up arrow was clicked, 2 if the down arrow was clicked, and 0
otherwise.events.CHAR_ADDEDEmitted after the user types a text character into the buffer.
Arguments:
events.COMMAND_TEXT_CHANGEDEmitted when the text in the command entry changes.
ui.command_entry:get_text() returns the current text.
events.COMPILE_OUTPUTEmitted when an executed compile command has output.
The default behavior is to print output to the output buffer. In order to override this,
connect to this event with an index of 1 and return true.
Arguments:
events.CSIEmitted when the terminal version receives an unrecognized CSI sequence.
Arguments:
events.DOUBLE_CLICKEmitted after double-clicking the mouse button.
Arguments:
view.MOD_CTRL,
view.MOD_SHIFT, view.MOD_ALT, and view.MOD_META. On macOS, the Command modifier
key is reported as view.MOD_CTRL and Ctrl is view.MOD_META. Note: If you set
view.rectangular_selection_modifier to view.MOD_CTRL, the “Control” modifier is
reported as both “Control” and “Alt” due to a Scintilla limitation in the GTK version.events.DWELL_ENDEmitted after events.DWELL_START when the user moves the mouse, presses a key, or scrolls
the view.
Arguments:
events.DWELL_STARTEmitted when the mouse is stationary for view.mouse_dwell_time milliseconds.
Arguments:
events.ERROREmitted when an error occurs.
Arguments:
events.FILE_AFTER_SAVEEmitted after saving a file to disk.
Arguments:
See also: buffer.save, buffer.save_as
events.FILE_BEFORE_SAVEEmitted before saving a file to disk.
Arguments:
See also: buffer.save
events.FILE_CHANGEDEmitted when Textadept detects that an open file was modified externally.
The default behavior is to prompt the user to reload the file. In order to override this,
connect to this event with an index of 1 and return true.
Arguments:
events.FILE_OPENEDEmitted after opening a file in a new buffer.
Arguments:
See also: io.open_file
events.FINDEmitted to find text.
ui.find contains active find options.
Arguments:
See also: ui.find.find_next, ui.find.find_prev
events.FIND_RESULT_FOUNDEmitted when finding a text search result.
It is selected and has been scrolled into view.
Arguments:
events.FIND_TEXT_CHANGEDEmitted when the text in the “Find” field of the find & replace pane changes.
ui.find.find_entry_text contains the current text.
events.FIND_WRAPPEDEmitted when a text search wraps, either from bottom to top (when searching for a next occurrence), or from top to bottom (when searching for a previous occurrence).
The default behavior is to print a statusbar notification. You can connect to this event to implement a more visual or audible notice.
events.FOCUSEmitted when Textadept receives focus.
This event is never emitted when Textadept is running in the terminal.
events.INDICATOR_CLICKEmitted when clicking the mouse on text within an indicator range.
Arguments:
view.MOD_CTRL,
view.MOD_SHIFT, view.MOD_ALT, and view.MOD_META. On macOS, the Command modifier
key is reported as view.MOD_CTRL and Ctrl is view.MOD_META. Note: If you set
view.rectangular_selection_modifier to view.MOD_CTRL, the “Control” modifier is
reported as both “Control” and “Alt” due to a Scintilla limitation in the GTK version.events.INDICATOR_RELEASEEmitted when releasing the mouse after clicking on text within an indicator range.
Arguments:
view.MOD_CTRL,
view.MOD_SHIFT, view.MOD_ALT, and view.MOD_META. On macOS, the Command modifier
key is reported as view.MOD_CTRL and Ctrl is view.MOD_META. Note: If you set
view.rectangular_selection_modifier to view.MOD_CTRL, the “Control” modifier is
reported as both “Control” and “Alt” due to a Scintilla limitation in the GTK version.events.INITIALIZEDEmitted after Textadept finishes initializing.
events.KEYPRESSEmitted when pressing a recognized key.
If any handler returns true, the key is not handled further (e.g. inserted into the buffer).
Arguments:
events.LEXER_LOADEDEmitted after loading a language lexer.
This is useful for automatically loading language modules as source files are opened, or setting up language-specific editing features for source files.
Arguments:
events.MARGIN_CLICKEmitted when clicking the mouse inside a sensitive margin.
Arguments:
view.MOD_CTRL,
view.MOD_SHIFT, view.MOD_ALT, and view.MOD_META. On macOS, the Command modifier
key is reported as view.MOD_CTRL and Ctrl is view.MOD_META. Note: If you set
view.rectangular_selection_modifier to view.MOD_CTRL, the “Control” modifier is
reported as both “Control” and “Alt” due to a Scintilla limitation in the GTK version.events.MENU_CLICKEDEmitted after selecting a menu item.
Arguments:
ui.menu().events.MODE_CHANGEDEmitted by the GUI version when switching between light mode and dark mode.
Arguments:
events.MOUSEEmitted by the terminal version for an unhandled mouse event.
A handler should return true if it handled the event. Otherwise Textadept will try again.
(This side effect for nil return is useful for sending the original mouse event to a
different view that a handler has switched to.)
Arguments:
view.MOUSE_PRESS, view.MOUSE_DRAG, or view.MOUSE_RELEASE.view.MOD_CTRL, view.MOD_SHIFT,
and view.MOD_ALT.events.QUITEmitted when quitting Textadept.
The default behavior is to close all buffers and, if that was successful, quit the application.
In order to do something before Textadept closes all open buffers, connect to this event with
an index of 1. 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.
See also: events.quit
events.REPLACEEmitted to replace selected (found) text.
ui.find contains active find options.
Arguments:
See also: ui.find.replace
events.REPLACE_ALLEmitted to replace all occurrences of found text.
ui.find contains active find options.
Arguments:
See also: ui.find.replace_all
events.RESET_AFTEREmitted after resetting Textadept’s Lua state.
Arguments:
events.RESET_BEFORE. All handlers will have access
to this same table.See also: events.reset
events.RESET_BEFOREEmitted before resetting Textadept’s Lua state.
Arguments:
events.RESET_AFTER. All handlers
will have access to this same table.See also: events.reset
events.RESUMEEmitted when resuming Textadept from a suspended state.
This event is only emitted by the terminal version.
events.RUN_OUTPUTEmitted when an executed run command has output.
The default behavior is to print output to the output buffer. In order to override this,
connect to this event with an index of 1 and return true.
Arguments:
events.SAVE_POINT_LEFTEmitted after leaving a save point.
events.SAVE_POINT_REACHEDEmitted after reaching a save point.
events.SESSION_LOADEmitted when loading a session.
Arguments:
events.SESSION_SAVEEmitted when saving a session.
Arguments:
events.SUSPENDEmitted prior to suspending Textadept.
This event is only emitted by the terminal version.
events.TAB_CLICKEDEmitted when the user clicks on a buffer tab.
The default behavior is to switch to the clicked tab’s buffer. In order to do something
before the switch, connect to this event with an index of 1.
Note that Textadept always displays a context menu for a right-click.
Arguments:
1 (left button), 2 (middle
button), 3 (right button), 4 (wheel up), or 5 (wheel down).view.MOD_CTRL,
view.MOD_SHIFT, view.MOD_ALT, and view.MOD_META. On macOS, the Command modifier
key is reported as view.MOD_CTRL and Ctrl is view.MOD_META. Note: If you set
view.rectangular_selection_modifier to view.MOD_CTRL, the “Control” modifier is
reported as both “Control” and “Alt” due to a Scintilla limitation in the GTK version.events.TAB_CLOSE_CLICKEDEmitted when the user clicks a buffer tab’s close button.
The default behavior is to close the tab’s buffer. If you need to do something before
Textadept closes the buffer, connect to this event with an index of 1.
This event is only emitted in the Qt version.
Arguments:
events.TEST_OUTPUTEmitted when an executed test command has output.
The default behavior is to print output to the output buffer. In order to override this,
connect to this event with an index of 1 and return true.
Arguments:
events.UNFOCUSEmitted when Textadept loses focus.
This event is never emitted when Textadept is running in the terminal.
events.UPDATE_UIEmitted after the view is visually updated.
Arguments:
updated: A bitmask of changes since the last update.
buffer.UPDATE_CONTENT
The buffer’s contents, styling, or markers have changed.buffer.UPDATE_SELECTION
The buffer’s selection has changed (including caret movement).view.UPDATE_V_SCROLL
The view has scrolled vertically.view.UPDATE_H_SCROLL
The view has scrolled horizontally.events.URI_DROPPEDEmitted after dragging and dropping a URI into a view.
Arguments:
events.USER_LIST_SELECTIONEmitted after selecting an item in a user list.
Arguments:
buffer:user_list_show().events.VIEW_AFTER_SWITCHEmitted after switching to another view.
The view being switched to is view.
See also: ui.goto_view
events.VIEW_BEFORE_SWITCHEmitted before switching to another view.
The view being switched from is view.
See also: ui.goto_view, view.split
events.VIEW_NEWEmitted after creating a new view.
The new view is view.
See also: view.split
events.ZOOMEmitted after changing view.zoom.
See also: view.zoom_in, view.zoom_out
events.connect(event, f[, index])Adds an event handler.
Parameters:
nil value, subsequent handlers for event
will not be invoked when that event is emitted.events.disconnect(event, f)Removes an event handler.
Parameters:
events.emit(event[, …])Sequentially invoke all of an event’s handler functions.
If any handler returns a non-nil value, subsequent handlers will not be called. This is
useful for stopping the propagation of an event like a keypress after it has been handled,
or for passing back values from handlers.
Parameters:
Returns: the first non-nil value returned by a handler, if any
io moduleExtends Lua’s io library with Textadept functions for working with files.
io.close_all_buffers()Closes all open buffers.
If there are any unsaved buffers, the user is prompted to confirm closing without saving for each one. If the user does not confirm, the remaining open buffers stay open.
Buffers are not saved automatically. They must be saved manually.
Returns: true if user did not cancel, and all buffers were closed; nil otherwise.
io.detect_indentationAttempt to detect indentation settings for opened files.
If any non-blank line starts with a tab, tabs are used. Otherwise, for the first non-blank line that starts with between two and eight spaces, that number of spaces is used.
The default value is true.
io.encodingsTable of encodings to attempt to decode files with.
The default list contains UTF-8, ASCII, CP1252, and UTF-16.
You should add to this list if you work with files encoded in something else. Valid encodings are GNU iconv’s encodings, and include:
Usage:
io.encodings[#io.encodings + 1] = 'UTF-32'
See also: string.iconv
io.ensure_final_newlineEnsure there is a final newline when saving text files.
This has no effect on binary files.
The default value is false on Windows, and true on macOS, Linux, and BSD.
io.get_project_root([path][, submodule=false])Returns a project’s root directory.
Textadept only recognizes projects under one of the following version control systems: Git, Mercurial, SVN, Bazaar, and Fossil.
Parameters:
Returns: string root, or nil if no project was found
io.open_file([filenames])Opens files for editing.
Parameters:
nil,
the user is prompted to open one or more.See also: _CHARSET, events.FILE_OPENED
io.open_recent_file()Prompts the user to select a recently opened file to reopen.
See also: io.recent_files
io.quick_open([paths[, filter]])Prompts the user to select a file to open from a list of files read from a directory.
The number of files shown in the list is capped at io.quick_open_max.
Parameters:
io.quick_open_filters[paths] if it exists, or
lfs.default_filter otherwise.Usage:
io.quick_open(buffer.filename:match('^(.+)[/\\]')) -- list files in the buffer's directory
io.quick_open(io.get_current_project(), {'.lua', '.c'}) -- list Lua and C project files
io.quick_open(io.get_current_project(), '!/build') -- list non-build project files
io.quick_open_filtersMap of directory paths to filters used by io.quick_open().
io.quick_open_maxThe maximum number of files listed in the quick open list.
The default value is 5000.
io.recent_filesTable of recently opened files, the most recent being towards the top.
io.save_all_files([untitled=false])Saves all unsaved buffers to their respective files.
Print and output buffers are ignored.
Parameters:
Returns: true if all savable files were saved; nil otherwise.
keys moduleManages key bindings in Textadept.
Define key bindings in the global keys table in key-value pairs. Each pair consists of either:
When searching for a command to run based on a key sequence, Textadept considers key bindings
in the current key mode to have priority. If no key mode is active, language-specific key
bindings have priority, followed by the ones in the global table. This means if there are
two commands with the same key sequence, Textadept runs the language-specific one. However,
if the command returns the boolean value false, Textadept also runs the lower-priority
command. (This is useful for overriding commands like autocompletion with language-specific
completion, but fall back to word autocompletion if the first command fails.)
Key sequences are strings built from an ordered combination of modifier keys and the key’s
inserted character. Modifier keys are “Control”, “Shift”, and “Alt” on Windows, Linux/BSD,
and in the terminal version. On macOS they are “Control” (^), “Alt/Option” (⌥), “Command”
(⌘), and “Shift” (⇧). These modifiers have the following string representations:
| Modifier | Windows / Linux / BSD | macOS | Terminal |
|---|---|---|---|
| Control | 'ctrl' |
'ctrl' |
'ctrl' |
| Alt | 'alt' |
'alt' |
'meta' |
| Command | N/A | 'cmd' |
N/A |
| Shift | 'shift' |
'shift' |
'shift' |
The string representation of key values less than 255 is the character that Textadept would
normally insert if the “Control”, “Alt”, and “Command” modifiers were not held down. Therefore,
a combination of Ctrl+Alt+Shift+A has the key sequence ctrl+alt+A on Windows and Linux/BSD,
but a combination of Ctrl+Shift+Tab has the key sequence ctrl+shift+\t. On a United States
English keyboard, since the combination of Ctrl+Shift+, has the key sequence ctrl+<
(Shift+, inserts a <), Textadept recognizes the key binding as Ctrl+<. This allows
key bindings to be language and layout agnostic. For key values greater than 255, Textadept
uses the keys.KEYSYMS lookup table. Therefore, Ctrl+Right Arrow has the key sequence
ctrl+right. Uncommenting the print() statements in core/keys.lua causes Textadept to
print key sequences to standard out (stdout) for inspection.
A command bound to a key sequence is simply a Lua function. For example:
keys['ctrl+n'] = buffer.new
keys['ctrl+z'] = buffer.undo
keys.c['shift+\n'] = function() -- language-specific key
buffer:line_end()
buffer:add_text(';')
buffer:new_line()
end
Textadept handles buffer and view references properly in this context; it will use the
correct buffer and view when running the key command.
Modes are groups of key bindings such that when a key mode is active, Textadept ignores all key bindings defined outside the mode until the mode is unset. Here is a simple vi mode example:
keys.command_mode = {
['h'] = buffer.char_left,
['j'] = buffer.line_up,
['k'] = buffer.line_down,
['l'] = buffer.char_right,
['i'] = function()
keys.mode = nil
ui.statusbar_text = 'INSERT MODE'
end
}
keys['esc'] = function() keys.mode = 'command_mode' end
events.connect(events.UPDATE_UI, function()
if keys.mode == 'command_mode' then return end
ui.statusbar_text = 'INSERT MODE'
end)
keys.mode = 'command_mode' -- default mode
Warning: When creating a mode, be sure to define a way to exit the mode, otherwise you will probably have to restart Textadept.
Key chains are a powerful concept. They allow you to assign multiple key bindings to one
key sequence. By default, the Esc key cancels a key chain, but you can redefine it via
keys.CLEAR. An example key chain looks like:
keys['alt+a'] = {
a = function1,
b = function2,
c = {...}
}
Pressing Alt+A activates the chain, and pressing A after that invokes function1. Alt+A
followed by B invokes function2, and so on.
keys.CLEARThe 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.KEYSYMSLookup table for string representations of key codes higher than 255.
Key codes can be identified by temporarily uncommenting the print() statements in
core/keys.lua.
Recognized codes are: esc, \b, \t, \n, down, up, left, right, home, end, pgup, pgdn, del,
ins, and f1-f12.
The GUI version also recognizes: menu, kpenter, kphome, kpend, kpleft, kpup, kpright, kpdown,
kppgup, kppgdn, kpmul, kpadd, kpsub, kpdiv, kpdec, and kp0-kp9.
keys.keychainThe current chain of key sequences. (Read-only)
keys.modeThe current key mode.
When non-nil, all key bindings defined outside of keys[keys.mode] are ignored.
The default value is nil.
lexer moduleLexes Scintilla documents and source code with Lua and LPeg.
Lexers recognize and tag elements of source code for syntax highlighting. Scintilla (the editing component behind Textadept and SciTE) traditionally uses static, compiled C++ lexers which are difficult to create and/or extend. On the other hand, Lua makes it easy to to rapidly create new lexers, extend existing ones, and embed lexers within one another. Lua lexers tend to be more readable than C++ lexers too.
While lexers can be written in plain Lua, Scintillua prefers using Parsing Expression Grammars, or PEGs, composed with the Lua LPeg library. As a result, this document is devoted to writing LPeg lexers. The following table comes from the LPeg documentation and summarizes all you need to know about constructing basic LPeg patterns. This module provides convenience functions for creating and working with other more advanced patterns and concepts.
| Operator | Description |
|---|---|
lpeg.P(string) |
Matches string string literally. |
lpeg.P(n) |
Matches exactly n number of characters. |
lpeg.S(string) |
Matches any character in string set string. |
lpeg.R(“xy”) |
Matches any character between range x and y. |
patt^n |
Matches at least n repetitions of patt. |
patt^-n |
Matches at most n repetitions of patt. |
patt1 * patt2 |
Matches patt1 followed by patt2. |
patt1 + patt2 |
Matches patt1 or patt2 (ordered choice). |
patt1 - patt2 |
Matches patt1 if patt2 does not also match. |
-patt |
Matches if patt does not match, consuming no input. |
#patt |
Matches patt but consumes no input. |
The first part of this document deals with rapidly constructing a simple lexer. The next part deals with more advanced techniques, such as embedding lexers within one another. Following that is a discussion about code folding, or being able to tell Scintilla which code blocks are “foldable” (temporarily hideable from view). After that are instructions on how to use Lua lexers with the aforementioned Textadept and SciTE editors. Finally there are comments on lexer performance and limitations.
The lexers/ directory contains all of Scintillua’s Lua lexers, including any new ones you write. Before attempting to write one from scratch though, first determine if your programming language is similar to any of the 100+ languages supported. If so, you may be able to copy and modify, or inherit from that lexer, saving some time and effort. The filename of your lexer should be the name of your programming language in lower case followed by a .lua extension. For example, a new Lua lexer has the name lua.lua.
There is a lexers/template.txt file that contains a simple template for a new lexer. Feel free to use it, replacing the ‘?’ with the name of your lexer. Consider this snippet from the template:
-- ? LPeg lexer.
local lexer = lexer
local P, S = lpeg.P, lpeg.S
local lex = lexer.new(...)
--[[... lexer rules ...]]
-- Identifier.
local identifier = lex:tag(lexer.IDENTIFIER, lexer.word)
lex:add_rule('identifier', identifier)
--[[... more lexer rules ...]]
return lex
The first line of code is a Lua convention to store a global variable into a local variable
for quick access. The second line simply defines often used convenience variables. The third
and last lines define and return the lexer object Scintillua uses; they are
very important and must be part of every lexer. Note the ... passed to lexer.new() is
literal: the lexer will assume the name of its filename or an alternative name specified
by lexer.load() in embedded lexer applications. The fourth line uses something called a
“tag”, an essential component of lexers. You will learn about tags shortly. The fifth line
defines a lexer grammar rule, which you will learn about later. (Be aware that it is common
practice to combine these two lines for short rules.) Note, however, the local prefix in
front of variables, which is needed so-as not to affect Lua’s global environment. All in all,
this is a minimal, working lexer that you can build on.
Take a moment to think about your programming language’s structure. What kind of key elements does it have? Most languages have elements like keywords, strings, and comments. The lexer’s job is to break down source code into these elements and “tag” them for syntax highlighting. Therefore, tags are an essential component of lexers. It is up to you how specific your lexer is when it comes to tagging elements. Perhaps only distinguishing between keywords and identifiers is necessary, or maybe recognizing constants and built-in functions, methods, or libraries is desirable. The Lua lexer, for example, tags the following elements: keywords, functions, constants, identifiers, strings, comments, numbers, labels, attributes, and operators. Even though functions and constants are subsets of identifiers, Lua programmers find it helpful for the lexer to distinguish between them all. It is perfectly acceptable to just recognize keywords and identifiers.
In a lexer, LPeg patterns that match particular sequences of characters are tagged with a
tag name using the the lexer.tag() function. Let us examine the “identifier” tag used in
the template shown earlier:
local identifier = lex:tag(lexer.IDENTIFIER, lexer.word)
At first glance, the first argument does not appear to be a string name and the second argument does not appear to be an LPeg pattern. Perhaps you expected something like:
lex:tag('identifier', (lpeg.R('AZ', 'az') + '_') * (lpeg.R('AZ', 'az', '09') + '_')^0)
The lexer module actually provides a convenient list of common tag names and common LPeg
patterns for you to use. Tag names for programming languages include (but are not limited
to) lexer.DEFAULT, lexer.COMMENT, lexer.STRING, lexer.NUMBER, lexer.KEYWORD,
lexer.IDENTIFIER, lexer.OPERATOR, lexer.ERROR, lexer.PREPROCESSOR, lexer.CONSTANT,
lexer.CONSTANT_BUILTIN, lexer.VARIABLE, lexer.VARIABLE_BUILTIN, lexer.FUNCTION,
lexer.FUNCTION_BUILTIN, lexer.FUNCTION_METHOD, lexer.CLASS, lexer.TYPE, lexer.LABEL,
lexer.REGEX, lexer.EMBEDDED, and lexer.ANNOTATION. Tag names for markup languages include
(but are not limited to) lexer.TAG, lexer.ATTRIBUTE, lexer.HEADING, lexer.BOLD,
lexer.ITALIC, lexer.UNDERLINE, lexer.CODE, lexer.LINK, lexer.REFERENCE, and
lexer.LIST. Patterns include lexer.any, lexer.alpha, lexer.digit, lexer.alnum,
lexer.lower, lexer.upper, lexer.xdigit, lexer.graph, lexer.punct, lexer.space,
lexer.newline, lexer.nonnewline, lexer.dec_num, lexer.hex_num, lexer.oct_num,
lexer.bin_num, lexer.integer, lexer.float, lexer.number, and lexer.word. You may use
your own tag names if none of the above fit your language, but an advantage to using predefined
tag names is that the language elements your lexer recognizes will inherit any universal syntax
highlighting color theme that your editor uses. You can also “subclass” existing tag names by
appending a ‘.subclass’ string to them. For example, the HTML lexer tags unknown tags as
lexer.TAG .. '.unknown'. This gives editors the opportunity to highlight those subclassed
tags in a different way than normal tags, or fall back to highlighting them as normal tags.
So, how might you recognize and tag elements like keywords, comments, and strings? Here are some examples.
Keywords
Instead of matching n keywords with n P('keyword_n') ordered choices, use one
of of the following methods:
Use the convenience function lexer.word_match() optionally coupled with
lexer.set_word_list(). It is much easier and more efficient to write word matches like:
local keyword = lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD))
--[[...]]
lex:set_word_list(lexer.KEYWORD, {
'keyword_1', 'keyword_2', ..., 'keyword_n'
})
local case_insensitive_word = lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD, true))
--[[...]]
lex:set_word_list(lexer.KEYWORD, {
'KEYWORD_1', 'keyword_2', ..., 'KEYword_n'
})
local hyphenated_keyword = lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD))
--[[...]]
lex:set_word_list(lexer.KEYWORD, {
'keyword-1', 'keyword-2', ..., 'keyword-n'
})
The benefit of using this method is that other lexers that inherit from, embed, or embed themselves into your lexer can set, replace, or extend these word lists. For example, the TypeScript lexer inherits from JavaScript, but extends JavaScript’s keyword and type lists with more options.
This method also allows applications that use your lexer to extend or replace your word lists. For example, the Lua lexer includes keywords and functions for the latest version of Lua (5.4 at the time of writing). However, editors using that lexer might want to use keywords from Lua version 5.1, which is still quite popular.
Note that calling lex:set_word_list() is completely optional. Your lexer is allowed to
expect the editor using it to supply word lists. Scintilla-based editors can do so via
Scintilla’s ILexer5 interface.
Use the lexer-agnostic form of lexer.word_match():
local keyword = lex:tag(lexer.KEYWORD, lexer.word_match{
'keyword_1', 'keyword_2', ..., 'keyword_n'
})
local case_insensitive_keyword = lex:tag(lexer.KEYWORD, lexer.word_match({
'KEYWORD_1', 'keyword_2', ..., 'KEYword_n'
}, true))
local hyphened_keyword = lex:tag(lexer.KEYWORD, lexer.word_match{
'keyword-1', 'keyword-2', ..., 'keyword-n'
})
For short keyword lists, you can use a single string of words. For example:
local keyword = lex:tag(lexer.KEYWORD, lexer.word_match('key_1 key_2 ... key_n'))
You can use this method for static word lists that do not change, or where it does not make sense to allow applications or other lexers to extend or replace a word list.
Comments
Line-style comments with a prefix character(s) are easy to express:
local shell_comment = lex:tag(lexer.COMMENT, lexer.to_eol('#'))
local c_line_comment = lex:tag(lexer.COMMENT, lexer.to_eol('//', true))
The comments above start with a ‘#’ or “//” and go to the end of the line (EOL). The second comment recognizes the next line also as a comment if the current line ends with a ‘\’ escape character.
C-style “block” comments with a start and end delimiter are also easy to express:
local c_comment = lex:tag(lexer.COMMENT, lexer.range('/*', '*/'))
This comment starts with a “/*” sequence and contains anything up to and including an ending “*/” sequence. The ending “*/” is optional so the lexer can recognize unfinished comments as comments and highlight them properly.
Strings
Most programming languages allow escape sequences in strings such that a sequence like
“\"” in a double-quoted string indicates that the ‘"’ is not the end of the
string. lexer.range() handles escapes inherently.
local dq_str = lexer.range('"')
local sq_str = lexer.range("'")
local string = lex:tag(lexer.STRING, dq_str + sq_str)
In this case, the lexer treats ‘\’ as an escape character in a string sequence.
Numbers
Most programming languages have the same format for integers and floats, so it might be as simple as using a predefined LPeg pattern:
local number = lex:tag(lexer.NUMBER, lexer.number)
However, some languages allow postfix characters on integers:
local integer = P('-')^-1 * (lexer.dec_num * S('lL')^-1)
local number = lex:tag(lexer.NUMBER, lexer.float + lexer.hex_num + integer)
Other languages allow separaters within numbers for better readability:
local number = lex:tag(lexer.NUMBER, lexer.number_('_')) -- recognize 1_000_000
Your language may need other tweaks, but it is up to you how fine-grained you want your highlighting to be. After all, you are not writing a compiler or interpreter!
Programming languages have grammars, which specify valid syntactic structure. For example,
comments usually cannot appear within a string, and valid identifiers (like variable names)
cannot be keywords. In Lua lexers, grammars consist of LPeg pattern rules, many of which
are tagged. Recall from the lexer template the lexer.add_rule() call, which adds a rule
to the lexer’s grammar:
lex:add_rule('identifier', identifier)
Each rule has an associated name, but rule names are completely arbitrary and serve only to identify and distinguish between different rules. Rule order is important: if text does not match the first rule added to the grammar, the lexer tries to match the second rule added, and so on. Right now this lexer simply matches identifiers under a rule named “identifier”.
To illustrate the importance of rule order, here is an example of a simplified Lua lexer:
lex:add_rule('keyword', lex:tag(lexer.KEYWORD, ...))
lex:add_rule('identifier', lex:tag(lexer.IDENTIFIER, ...))
lex:add_rule('string', lex:tag(lexer.STRING, ...))
lex:add_rule('comment', lex:tag(lexer.COMMENT, ...))
lex:add_rule('number', lex:tag(lexer.NUMBER, ...))
lex:add_rule('label', lex:tag(lexer.LABEL, ...))
lex:add_rule('operator', lex:tag(lexer.OPERATOR, ...))
Notice how identifiers come after keywords. In Lua, as with most programming languages, the characters allowed in keywords and identifiers are in the same set (alphanumerics plus underscores). If the lexer added the “identifier” rule before the “keyword” rule, all keywords would match identifiers and thus would be incorrectly tagged (and likewise incorrectly highlighted) as identifiers instead of keywords. The same idea applies to function names, constants, etc. that you may want to distinguish between: their rules should come before identifiers.
So what about text that does not match any rules? For example in Lua, the ‘!’ character is meaningless outside a string or comment. Normally the lexer skips over such text. If instead you want to highlight these “syntax errors”, add a final rule:
lex:add_rule('keyword', keyword)
--[[...]]
lex:add_rule('error', lex:tag(lexer.ERROR, lexer.any))
This identifies and tags any character not matched by an existing rule as a lexer.ERROR.
Even though the rules defined in the examples above contain a single tagged pattern, rules may consist of multiple tagged patterns. For example, the rule for an HTML tag could consist of a tagged tag followed by an arbitrary number of tagged attributes, separated by whitespace. This allows the lexer to produce all tags separately, but in a single, convenient rule. That rule might look something like this:
local ws = lex:get_rule('whitespace') -- predefined rule for all lexers
lex:add_rule('tag', tag_start * (ws * attributes)^0 * tag_end^-1)
Note however that lexers with complex rules like these are more prone to lose track of their state, especially if they span multiple lines.
Lexers primarily consist of tagged patterns and grammar rules. These patterns match language elements like keywords, comments, and strings, and rules dictate the order in which patterns are matched. At your disposal are a number of convenience patterns and functions for rapidly creating a lexer. If you choose to use predefined tag names (or perhaps even subclassed names) for your patterns, you do not have to update your editor’s theme to specify how to syntax-highlight those patterns. Your language’s elements will inherit the default syntax highlighting color theme your editor uses.
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 highlight the entire line accordingly. To indicate that your lexer matches by line, create the lexer with an extra parameter:
local lex = lexer.new(..., {lex_by_line = true})
Now the input text for the lexer is a single line at a time. Keep in mind that line lexers do not have the ability to look ahead to subsequent lines.
Scintillua lexers embed within one another very easily, requiring minimal effort. In the following sections, the lexer being embedded is called the “child” lexer and the lexer a child is being embedded in is called the “parent”. For example, consider an HTML lexer and a CSS lexer. Either lexer stands alone for tagging their respective HTML and CSS files. However, CSS can be embedded inside HTML. In this specific case, the CSS lexer is the “child” lexer with the HTML lexer being the “parent”. Now consider an HTML lexer and a PHP lexer. This sounds a lot like the case with CSS, but there is a subtle difference: PHP embeds itself into HTML while CSS is embedded in HTML. This fundamental difference results in two types of embedded lexers: a parent lexer that embeds other child lexers in it (like HTML embedding CSS), and a child lexer that embeds itself into a parent lexer (like PHP embedding itself in HTML).
Before embedding a child lexer into a parent lexer, the parent lexer needs to load the child
lexer. This is done with the lexer.load() function. For example, loading the CSS lexer
within the HTML lexer looks like:
local css = lexer.load('css')
The next part of the embedding process is telling the parent lexer when to switch over to the child lexer and when to switch back. The lexer refers to these indications as the “start rule” and “end rule”, respectively, and are just LPeg patterns. Continuing with the HTML/CSS example, the transition from HTML to CSS is when the lexer encounters a “style” tag with a “type” attribute whose value is “text/css”:
local css_tag = P('<style') * P(function(input, index)
if input:find('^[^>]+type="text/css"', index) then return true end
end)
This pattern looks for the beginning of a “style” tag and searches its attribute list for
the text “type="text/css"”. (In this simplified example, the Lua pattern does not consider
whitespace between the ‘=’ nor does it consider that using single quotes is valid.) If there
is a match, the functional pattern returns true. However, we ultimately want to tag 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 tag that tag as an HTML tag:
local css_end_rule = #P('</style>') * tag
Once the parent loads the child lexer and defines the child’s start and end rules, it embeds
the child with the lexer.embed() function:
lex:embed(css, css_start_rule, css_end_rule)
The process for instructing a child lexer to embed itself into a parent is very similar to
embedding a child into a parent: first, load the parent lexer into the child lexer with the
lexer.load() function and then create start and end rules for the child lexer. However,
in this case, call lexer.embed() with switched arguments. For example, in the PHP lexer:
local html = lexer.load('html')
local php_start_rule = lex:tag('php_tag', '<?php' * lexer.space)
local php_end_rule = lex:tag('php_tag', '?>')
html:embed(lex, php_start_rule, php_end_rule)
Note that the use of a ‘php_tag’ tag will require the editor using the lexer to specify how
to highlight text with that tag. In order to avoid this, you could use the lexer.PREPROCESSOR
tag instead.
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.
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 markers in the editor margins appear next to code that can be folded at places called “fold points”. When the user clicks on one of those markers, the editor hides the code associated with the marker until the user clicks on the marker again. The lexer specifies these fold points and what code exactly to fold.
The fold points for most languages occur on keywords or character sequences. Examples of
fold keywords are “if” and “end” in Lua and examples of fold character sequences are ‘{‘,
‘}’, “/*”, and “*/” in C for code block and comment delimiters, respectively. However,
these fold points cannot occur just anywhere. For example, lexers should not recognize fold
keywords that appear within strings or comments. The lexer.add_fold_point() function allows
you to conveniently define fold points with such granularity. For example, consider C:
lex:add_fold_point(lexer.OPERATOR, '{', '}')
lex:add_fold_point(lexer.COMMENT, '/*', '*/')
The first assignment states that any ‘{‘ or ‘}’ that the lexer tagged as an lexer.OPERATOR
is a fold point. Likewise, the second assignment states that any “/*” or “*/” that the
lexer tagged as part of a lexer.COMMENT is a fold point. The lexer does not consider any
occurrences of these characters outside their tagged elements (such as in a string) as fold
points. How do you specify fold keywords? Here is an example for Lua:
lex:add_fold_point(lexer.KEYWORD, 'if', 'end')
lex:add_fold_point(lexer.KEYWORD, 'do', 'end')
lex:add_fold_point(lexer.KEYWORD, 'function', 'end')
lex:add_fold_point(lexer.KEYWORD, 'repeat', 'until')
If your lexer has case-insensitive keywords as fold points, simply add a
case_insensitive_fold_points = true option to lexer.new(), and specify keywords in
lower case.
If your lexer needs to do some additional processing in order to determine if a tagged element
is a fold point, pass a function to lex:add_fold_point() that returns an integer. A return
value of 1 indicates the element is a beginning fold point and a return value of -1
indicates the element is an ending fold point. A return value of 0 indicates the element
is not a fold point. For example:
local function fold_strange_element(text, pos, line, s, symbol)
if ... then
return 1 -- beginning fold point
elseif ... then
return -1 -- ending fold point
end
return 0
end
lex:add_fold_point('strange_element', '|', fold_strange_element)
Any time the lexer encounters a ‘|’ that is tagged as a “strange_element”, it calls the
fold_strange_element function to determine if ‘|’ is a fold point. The lexer calls these
functions with the following arguments: the text to identify fold points in, the beginning
position of the current line in the text to fold, the current line’s text, the position in
the current line the fold point text starts at, and the fold point text itself.
Some languages have significant whitespace and/or no delimiters that indicate fold points. If
your lexer falls into this category and you would like to mark fold points based on changes
in indentation, create the lexer with a fold_by_indentation = true option:
local lex = lexer.new(..., {fold_by_indentation = true})
Textadept
Place your lexer in your ~/.textadept/lexers/ directory so you do not overwrite it when upgrading Textadept. Also, lexers in this directory override default lexers. Thus, Textadept loads a user lua lexer instead of the default lua lexer. This is convenient for tweaking a default lexer to your liking. Then add a file extension for your lexer if necessary.
SciTE
Create a .properties file for your lexer and import it in either your SciTEUser.properties
or SciTEGlobal.properties. The contents of the .properties file should contain:
file.patterns.[lexer_name]=[file_patterns]
lexer.$(file.patterns.[lexer_name])=scintillua.[lexer_name]
keywords.$(file.patterns.[lexer_name])=scintillua
keywords2.$(file.patterns.[lexer_name])=scintillua
...
keywords9.$(file.patterns.[lexer_name])=scintillua
where [lexer_name] is the name of your lexer (minus the .lua extension) and
[file_patterns] is a set of file extensions to use your lexer for. The keyword settings are
only needed if another SciTE properties file has defined keyword sets for [file_patterns].
The scintillua keyword setting instructs Scintillua to use the keyword sets defined within
the lexer. You can override a lexer’s keyword set(s) by specifying your own in the same order
that the lexer calls lex:set_word_list(). For example, the Lua lexer’s first set of keywords
is for reserved words, the second is for built-in global functions, the third is for library
functions, the fourth is for built-in global constants, and the fifth is for library constants.
SciTE assigns styles to tag names in order to perform syntax highlighting. Since the set of tag names used for a given language changes, your .properties file should specify styles for tag names instead of style numbers. For example:
scintillua.styles.my_tag=$(scintillua.styles.keyword),bold
Legacy lexers are of the form:
local lexer = require('lexer')
local token, word_match = lexer.token, lexer.word_match
local P, S = lpeg.P, lpeg.S
local lex = lexer.new('?')
-- Whitespace.
lex:add_rule('whitespace', token(lexer.WHITESPACE, lexer.space^1))
-- Keywords.
lex:add_rule('keyword', token(lexer.KEYWORD, word_match{
--[[...]]
}))
--[[... other rule definitions ...]]
-- Custom.
lex:add_rule('custom_rule', token('custom_token', ...))
lex:add_style('custom_token', lexer.styles.keyword .. {bold = true})
-- Fold points.
lex:add_fold_point(lexer.OPERATOR, '{', '}')
return lex
While Scintillua will mostly handle such legacy lexers just fine without any changes, it is recommended that you migrate yours. The migration process is fairly straightforward:
lexer exists in the default lexer environment, so require('lexer') should be replaced
by simply lexer. (Keep in mind local lexer = lexer is a Lua idiom.)lexer.new() should no longer specify a lexer name by string,
but should instead use ... (three dots), which evaluates to the lexer’s filename or
alternative name in embedded lexer applications.lexer.new() now includes a rule to match whitespace. Unless
your lexer has significant whitespace, you can remove your legacy lexer’s whitespace
token and rule. Otherwise, your defined whitespace rule will replace the default one.token() function,
call lex:tag() instead.lexer.word_match() with
large word lists, call it as an instance method with an identifier string (typically
something like lexer.KEYWORD). Then at the end of the lexer (before return lex), call
lex:set_word_list() with the same identifier and the usual
list of words to match. This allows users of your lexer to call lex:set_word_list()
with their own set of words should they wish to.lex:add_style(). You
may need to add styling information for custom tags to your editor’s theme.lexer.last_char_includes() has been deprecated in favor of the new lexer.after_set().
Use the character set and pattern as arguments to that new function.As an example, consider the following sample legacy lexer:
local lexer = require('lexer')
local token, word_match = lexer.token, lexer.word_match
local P, S = lpeg.P, lpeg.S
local lex = lexer.new('legacy')
lex:add_rule('whitespace', token(lexer.WHITESPACE, lexer.space^1))
lex:add_rule('keyword', token(lexer.KEYWORD, word_match('foo bar baz')))
lex:add_rule('custom', token('custom', 'quux'))
lex:add_style('custom', lexer.styles.keyword .. {bold = true})
lex:add_rule('identifier', token(lexer.IDENTIFIER, lexer.word))
lex:add_rule('string', token(lexer.STRING, lexer.range('"')))
lex:add_rule('comment', token(lexer.COMMENT, lexer.to_eol('#')))
lex:add_rule('number', token(lexer.NUMBER, lexer.number))
lex:add_rule('operator', token(lexer.OPERATOR, S('+-*/%^=<>,.()[]{}')))
lex:add_fold_point(lexer.OPERATOR, '{', '}')
return lex
Following the migration steps would yield:
local lexer = lexer
local P, S = lpeg.P, lpeg.S
local lex = lexer.new(...)
lex:add_rule('keyword', lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD)))
lex:add_rule('custom', lex:tag('custom', 'quux'))
lex:add_rule('identifier', lex:tag(lexer.IDENTIFIER, lexer.word))
lex:add_rule('string', lex:tag(lexer.STRING, lexer.range('"')))
lex:add_rule('comment', lex:tag(lexer.COMMENT, lexer.to_eol('#')))
lex:add_rule('number', lex:tag(lexer.NUMBER, lexer.number))
lex:add_rule('operator', lex:tag(lexer.OPERATOR, S('+-*/%^=<>,.()[]{}')))
lex:add_fold_point(lexer.OPERATOR, '{', '}')
lex:set_word_list(lexer.KEYWORD, {'foo', 'bar', 'baz'})
return lex
Any editors using this lexer would have to add a style for the ‘custom’ tag.
There might be some slight overhead when initializing a lexer, but loading a file from disk
into Scintilla is usually more expensive. Actually painting the syntax highlighted text to
the screen is often more expensive than the lexing operation. On modern computer systems,
I see no difference in speed between Lua lexers and Scintilla’s C++ ones. Optimize lexers for
speed by re-arranging lexer.add_rule() calls so that the most common rules match first. Do
keep in mind that order matters for similar rules.
In some cases, folding may be far more expensive than lexing, particularly in lexers with a
lot of potential fold points. If your lexer is exhibiting signs of slowness, try disabling
folding in your text editor first. If that speeds things up, you can try reducing the number
of fold points you added, overriding lexer.fold() with your own implementation, or simply
eliminating folding support from your lexer.
Embedded preprocessor languages like PHP cannot completely embed themselves into their parent languages because the parent’s tagged patterns do not support start and end rules. This mostly goes unnoticed, but code like
<div id="<?php echo $id; ?>">
will not be tagged correctly. Also, these types of languages cannot currently embed themselves into their parent’s child languages either.
A language cannot embed itself into something like an interpolated string because it is possible that if lexing starts within the embedded entity, it will not be detected as such, so a child to parent transition cannot happen. For example, the following Ruby code will not be tagged correctly:
sum = "1 + 2 = #{1 + 2}"
Also, there is the potential for recursion for languages embedding themselves within themselves.
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.
Poorly written lexers have the ability to crash Scintilla (and thus its containing application), so unsaved data might be lost. However, I have only observed these crashes in early lexer development, when syntax errors or pattern errors are present. Once the lexer actually starts processing and tagging text (either correctly or incorrectly, it does not matter), I have not observed any crashes.
Thanks to Peter Odding for his lexer post on the Lua mailing list that provided inspiration, and thanks to Roberto Ierusalimschy for LPeg.
lexer.add_fold_point(lexer, tag_name, start_symbol, end_symbol)Adds a fold point to a lexer.
Parameters:
text: The text being processed for fold points.pos: The position in text of the beginning of the line currently being processed.line: The text of the line currently being processed.s: The position of start_symbol in line.symbol: start_symbol itself.Usage:
lex:add_fold_point(lexer.OPERATOR, '{', '}')
lex:add_fold_point(lexer.KEYWORD, 'if', 'end')
lex:add_fold_point('custom', function(text, pos, line, s, symbol) ... end)
lexer.add_rule(lexer, id, rule)Adds a rule to a lexer.
Parameters:
lex:tag().lexer.after_set(set, patt, skip)Returns a pattern that only matches when it comes after certain characters (or when there are no characters behind it).
Parameters:
lpeg.S().Usage:
local regex = lexer.after_set('+-*!%^&|=,([{', lexer.range('/'))
-- matches "var re = /foo/;", but not "var x = 1 / 2 / 3;"
lexer.alnumA pattern that matches any alphanumeric character (‘A’-‘Z’, ‘a’-‘z’, ‘0’-‘9’).
lexer.alphaA pattern that matches any alphabetic character (‘A’-‘Z’, ‘a’-‘z’).
lexer.anyA pattern that matches any single character.
lexer.bin_numA pattern that matches a binary number.
lexer.bin_num_(c)Returns a pattern that matches a binary number, whose digits may be separated by a particular character.
Parameters:
lexer.dec_numA pattern that matches a decimal number.
lexer.dec_num_(c)Returns a pattern that matches a decimal number, whose digits may be separated by a particular character.
Parameters:
lexer.detect([filename[, line]])Returns the name of the lexer often associated a particular filename and/or file content.
Parameters:
Returns: string lexer name to pass to lexer.load(), or nil if none was detected
lexer.detect_extensionsMap of file extensions, without the ‘.’ prefix, to their associated lexer names.
Usage:
lexer.detect_extensions.luadoc = 'lua'
lexer.detect_patternsMap of first-line patterns to their associated lexer names.
These are Lua string patterns, not LPeg patterns.
Usage:
lexer.detect_patterns['^#!.+/zsh'] = 'bash'
lexer.digitA pattern that matches any digit (‘0’-‘9’).
lexer.embed(lexer, child, start_rule, end_rule)Embeds a child lexer into a parent lexer.
Parameters:
Usage:
html:embed(css, css_start_rule, css_end_rule)
html:embed(lex, php_start_rule, php_end_rule) -- from php lexer
lexer.floatA pattern that matches a floating point number.
lexer.float_(c)Returns a pattern that matches a floating point number, whose digits may be separated by a particular character.
Parameters:
lexer.fold(lexer, text, start_line, start_level)Determines fold points in a chunk of text.
Parameters:
lexer.FOLD_BASE
(1024).Returns: table of line numbers mapped to fold levels
Usage:
lex:fold(...) --> {[1] = 1024, [2] = 9216, [3] = 1025, [4] = 1025, [5] = 1024}
lexer.fold_levelMap of line numbers (starting from 1) to their fold level bit-masks. (Read-only) Fold level masks are composed of an integer level combined with any of the following bits:
lexer.FOLD_BASE
The initial fold level (1024).lexer.FOLD_BLANK
The line is blank.lexer.FOLD_HEADER
The line is a header, or fold point.lexer.get_rule(lexer, id)Returns a lexer’s rule.
Parameters:
lexer.graphA pattern that matches any graphical character (‘!’ to ‘~’).
lexer.hex_numA pattern that matches a hexadecimal number.
lexer.hex_num_(c)Returns a pattern that matches a hexadecimal number, whose digits may be separated by a particular character.
Parameters:
lexer.indent_amountMap of line numbers (starting from 1) to their indentation amounts, measured in character columns. (Read-only)
lexer.integerA pattern that matches either a decimal, hexadecimal, octal, or binary number.
lexer.integer_(c)Returns a pattern that matches either a decimal, hexadecimal, octal, or binary number, whose digits may be separated by a particular character.
Parameters:
lexer.lex(lexer, text, init_style)Lexes a chunk of text.
Parameters:
Returns: table of tag names and positions.
Usage:
lex:lex(...) --> {'keyword', 2, 'whitespace.lua', 3, 'identifier', 7}
lexer.line_from_position(pos)Returns a position’s line number (starting from 1).
Parameters:
lexer.line_stateMap of line numbers (starting from 1) to their 32-bit integer line states.
Line states can be used by lexers for keeping track of persistent states (up to 32 states with 1 state per bit). For example, the output lexer uses this to mark lines that have warnings or errors.
lexer.load(name[, alt_name])Initializes or loads a lexer.
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:
Returns: lexer object
lexer.lowerA pattern that matches any lower case character (‘a’-‘z’).
lexer.modify_rule(lexer, id, rule)Replaces a lexer’s existing rule.
Parameters:
lexer.names([path])Returns a table of all known lexer names.
This function is not available to lexers and requires the LuaFileSystem (lfs) module to
be available.
Parameters:
lexer.new(name[, opts])Creates a new lexer.
Parameters:
... to inherit from the file’s name.lex_by_line: Only processes whole lines of text at a time (instead of arbitrary chunks
of text). Line lexers cannot look ahead to subsequent lines. The default value is false.fold_by_indentation: Calculate fold points based on changes in line indentation. The
default value is false.case_insensitive_fold_points: Fold points added via lexer.add_fold_point() should
ignore case. The default value is false.no_user_word_lists: Do not automatically allocate word lists that can be set by
users. This should really only be set by non-programming languages like markup languages.inherit: Lexer to inherit from. The default value is nil.Returns: lexer object
Usage:
lexer.new(..., {inherit = lexer.load('html')}) -- name is 'rhtml' in rhtml.lua file
lexer.newlineA pattern that matches an end of line, either CR+LF or LF.
lexer.nonnewlineA pattern that matches any single, non-newline character.
lexer.numberA pattern that matches a typical number, either a floating point, decimal, hexadecimal, octal, or binary number.
lexer.number_(c)Returns a pattern that matches a typical number, either a floating point, decimal, hexadecimal, octal, or binary number, and whose digits may be separated by a particular character.
Parameters:
Usage:
lexer.number_('_') -- matches 1_000_000
lexer.oct_numA pattern that matches an octal number.
lexer.oct_num_(c)Returns a pattern that matches an octal number, whose digits may be separated by a particular character.
Parameters:
lexer.propertyMap of key-value string pairs.
The contents of this map are application-dependant.
lexer.property_intAlias of lexer.property, but with values interpreted as numbers, or 0 if not
found.
(Read-only)
lexer.punctA pattern that matches any punctuation character (‘!’ to ‘/’, ‘:’ to ‘@’, ‘[’ to ‘’’, ‘{‘ to ‘~’).
lexer.range(s[, e=s[, single_line=false[, escapes[, balanced=false]]]])Returns a pattern that matches a bounded range of text.
This is a convenience function for matching more complicated ranges like strings with escape characters, balanced parentheses, and block comments (nested or not).
Parameters:
false unless s and e are identical, single-character strings. In that case,
the default value is true.Usage:
local dq_str_escapes = lexer.range('"')
local dq_str_noescapes = lexer.range('"', false, false)
local unbalanced_parens = lexer.range('(', ')')
local balanced_parens = lexer.range('(', ')', false, false, true)
lexer.set_word_list(lexer, name, word_list[, append=false])Sets the words in a lexer’s word list.
This only has an effect if the lexer uses lexer.word_match() to reference the given list.
Parameters:
lexer.word_match() reference to this list.lexer.spaceA pattern that matches any whitespace character (‘\t’, ‘\v’, ‘\f’, ‘\n’, ‘\r’, space).
lexer.starts_line(patt[, allow_indent=false])Returns a pattern that matches only at the beginning of a line.
Parameters:
Usage:
local preproc = lex:tag(lexer.PREPROCESSOR, lexer.starts_line(lexer.to_eol('#')))
lexer.style_atMap of buffer positions (starting from 1) to their string style names. (Read-only)
lexer.tag(lexer, name, patt)Returns a tagged pattern.
Parameters:
lexer.[A-Z_]+), its Scintilla style will likely need to be defined by the editor or
theme using this lexer.Usage:
local number = lex:tag(lexer.NUMBER, lexer.number)
local addition = lex:tag('addition', '+' * lexer.word)
lexer.to_eol([prefix[, escape=false]])Returns a pattern that matches a prefix until the end of its line.
Parameters:
Usage:
local line_comment = lexer.to_eol('//')
local line_comment = lexer.to_eol(S('#;'))
lexer.upperA pattern that matches any upper case character (‘A’-‘Z’).
lexer.wordA pattern that matches a typical word. Words begin with a letter or underscore and consist of alphanumeric and underscore characters.
lexer.word_match([lexer], word_list[, case_insensitive=false])Returns a pattern that matches a word in a word list.
This is a convenience function for simplifying a set of ordered choice word patterns and potentially allowing downstream users to configure word lists.
Parameters:
lex:set_word_list(),
no error will be raised, but the returned pattern will not match anything.Usage:
lex:add_rule('keyword', lex:tag(lexer.KEYWORD, lex:word_match(lexer.KEYWORD)))
local keyword = lex:tag(lexer.KEYWORD, lexer.word_match{'foo', 'bar', 'baz'})
local keyword = lex:tag(lexer.KEYWORD, lexer.word_match({'foo-bar', 'foo-baz',
'bar-foo', 'bar-baz', 'baz-foo', 'baz-bar'}, true))
local keyword = lex:tag(lexer.KEYWORD, lexer.word_match('foo bar baz'))
lexer.xdigitA pattern that matches any hexadecimal digit (‘0’-‘9’, ‘A’-‘F’, ‘a’-‘f’).
lfs moduleExtends the lfs library to find files in directories and determine absolute file paths.
lfs.abspath(filename[, prefix])Returns the absolute path to a filename.
The returned path is not guaranteed to exist.
Parameters:
lfs.default_filterThe default filter table used when iterating over files and directories using lfs.walk().
lfs.walk(dir[, filter=lfs.default_filter[, n[, include_dirs=false]]])Returns an iterator that iterates over all files in a directory and its sub-directories.
Parameters:
Usage:
for filename in lfs.walk(buffer.filename:match('^.+[/\\]')) do ... end
os moduleExtends Lua’s os library to provide process spawning capabilities.
proc:close()Closes the process’s standard input, effectively sending it an EOF (end of file).
proc:kill([signal=9])Kills the running process.
Parameters:
SIGKILL.proc:read([arg=’l’])Returns stdout read from the running process, or nil plus an error code and an error
message if an error occurred.
This may block until stdout is available for reading.
If the process has a stdout callback function, you must manually read all stdout available before Textadept can call that callback again.
Parameters:
io.read(). In summary:
nil at end-of-file (EOF).nil at EOF.nil at EOF.proc:status()Returns the status of the process, either “running” or “terminated”.
proc:wait()Blocks until the process finishes (if it has not already done so).
Returns: status code of the finished process
proc:write(…)Writes to the process’s stdin.
Linux note: When using the GTK or terminal version, if more than 65536 bytes (64K) are to be written, it is possible those bytes need to be written in 65536-byte (64K) chunks, or the process may not receive all input. However, it is also possible that there is a limit on how many bytes can be written in a short period of time, perhaps 196608 bytes (192K). The Qt version does not appear to have this limitation.
Parameters:
os.spawn(cmd[, cwd][, env][, stdout_cb[, stderr_cb[, exit_cb]]])Spawns an interactive child process in a separate thread.
Parameters:
$PATH or %PATH% is searched for program names. On Windows, this entire
string is passed to cmd.exe: %COMSPEC% /c [cmd].env on macOS and Linux/BSD, or set
on Windows; iterate over output matches of “key=value” pairs (one per line); assign
them to the new environment table; add your own entries; and finally use that table here.Returns: proc or nil plus an error message on failure
Usage:
os.spawn('lua ' .. buffer.filename, print) -- non-interactive
local proc = os.spawn('lua -e "print(io.read())"', print) -- interactive
proc:write('foo\n')
proc:close() -- close stdin, not the process
string moduleExtends Lua’s string library to provide encoding conversion.
string.iconv(text, new, old)Returns text converted from one encoding to another, or raises an error if the conversion failed.
Valid encodings are GNU libiconv’s encodings, and include:
Parameters:
Usage:
local utf8_filename = string.iconv(buffer.filename, 'UTF-8', _CHARSET)
local filename = string.iconv(utf8_filename, _CHARSET, 'UTF-8')
textadept moduleThe textadept module.
It provides utilities for editing text in Textadept.
textadept.bookmarks moduleBookmarks for Textadept.
textadept.bookmarks.MARK_BOOKMARKThe bookmark mark number.
textadept.bookmarks.clear()Clears all bookmarks in the current buffer.
textadept.bookmarks.goto_mark([next])Jumps to a the beginning of a bookmarked line.
Parameters:
nil, the user is prompted to select bookmarked line to jump to,
which includes bookmarks from all open buffers.Usage:
textadept.bookmarks.goto_mark(true) -- jump to the next bookmark
textadept.bookmarks.goto_mark(false) -- jump to the previous bookmark
textadept.bookmarks.toggle()Toggles a bookmark on the current line.
textadept.editing moduleEditing features for Textadept.
textadept.editing.INDIC_HIGHLIGHTThe word highlight indicator number.
textadept.editing.XPM_IMAGESMap of image names to registered image numbers.
Fields:
CLASS: The image number for classes.NAMESPACE: The image number for namespaces.METHOD: The image number for methods.SIGNAL: The image number for signals.SLOT: The image number for slots.VARIABLE: The image number for variables.STRUCT: The image number for structures.TYPEDEF: The image number for type definitions.Usage:
local item = string.format('%s%s%s', name, string.char(buffer.auto_c_type_separator),
textadept.editing.XPM_IMAGES.CLASS) -- autocompletion or user list item with image
textadept.editing.auto_encloseAuto-enclose selected text when typing a punctuation character, taking
textadept.editing.auto_pairs into account.
While a snippet is active, only auto-paired punctuation characters can auto-enclose placeholders.
The default value is false.
textadept.editing.auto_indentMatch the previous line’s indentation level after inserting a new line.
The default value is true.
textadept.editing.auto_pairsMap of auto-paired characters like parentheses, brackets, braces, and quotes.
The default auto-paired characters are “()”, “[]”, “{}”, “''”, “""”, and “``”. For certain XML-like lexers, “<>” is also auto-paired.
Usage:
textadept.editing.auto_pairs['*'] = '*'
textadept.editing.auto_pairs = nil -- disable completely
textadept.editing.autocomplete(name)Displays an autocompletion list.
Parameters:
textadept.editing.autocompleters
table to use for providing autocompletions.Returns: true if autocompletions were found; nil otherwise
textadept.editing.autocomplete_all_wordsAutocomplete 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.autocompletersMap of autocompleter names to autocompletion functions.
Names are typically lexer names and autocompletion functions typically autocomplete symbols.
Autocompletion functions must return two values:
If any completion contains a space character, the function should change
buffer.auto_c_separator. Also, autocompletion lists are sorted automatically by default,
but the function may change buffer.auto_c_order if it wants to control sort order.
Fields:
word: Autocompletion function for words from the current buffer, or all open buffers if
textadept.editing.autocomplete_all_words is true.
buffer.word_chars contains the set of characters that constitute words.
If buffer.auto_c_ignore_case is true, completions are not case-sensitive.snippet: Autocompletion function for snippet trigger words.textadept.editing.comment_stringMap of lexer names to line comment strings for programming languages.
Line comment strings are either prefixes or block comment delimiters separated by a ‘|’ character. If no comment string exists for a given language, the lexer-supplied string is used, if available.
Usage:
textadept.editing.comment_string.c = '/*|*/' -- instead of the default '//'
textadept.editing.convert_indentation()Converts the buffer’s indentation between tabs and spaces according to buffer.use_tabs.
If buffer.use_tabs is true, this will convert buffer.tab_width number of indenting spaces
to tabs. Otherwise, this will convert all indenting tabs to buffer.tab_width number of spaces.
textadept.editing.enclose(left, right[, select=false])Encloses the selected text within delimiters, or encloses the current word if no text is selected.
If there are multiple selections, each one will be enclosed.
Parameters:
textadept.editing.filter_through(command)Filters text through a shell command, replacing it (stdin) with that command’s output (stdout).
The standard input sent is as follows:
Note: commands that emit stdout while reading stdin (as opposed to emitting stdout only after
stdin is closed) may hang the GTK and terminal versions of Textadept if input generates more
output than stdout can buffer. On Linux, this may be 64K. See proc:write().
Parameters:
Usage:
textadept.editing.filter_through('sort | uniq') -- sort lines and remove duplicates
textadept.editing.goto_line([line])Moves the caret to the beginning of a line, ensuring that line is visible.
Parameters:
nil, the user is prompted for one.textadept.editing.highlight_wordsAutomatically highlight words.
textadept.editing.HIGHLIGHT_CURRENT: Automatically highlight all instances of the
current word.textadept.editing.HIGHLIGHT_SELECTED: Automatically highlight all instances of the
selected word.textadept.editing.HIGHLIGHT_NONE: Do not automatically highlight words.The default value is textadept.editing.HIGHLIGHT_NONE.
See also: buffer.word_chars
textadept.editing.join_lines()Joins the currently selected lines, or joins the current line with the line below it if no lines are selected.
As long as any part of a line is selected, the entire line is eligible for joining.
textadept.editing.paste_reindent()Pastes the text from the clipboard, taking into account the buffer’s indentation settings and the indentation of the current and preceding lines.
textadept.editing.select_enclosed([left[, right]])Selects the range of text between delimiters surrounding the caret.
If that range is already selected, this will toggle between selecting those delimiters as well.
Parameters:
nil, it is assumed to be one of the pairs in
textadept.editing.auto_pairs and inferred from the current position or selection.nil, it is inferred like left is.textadept.editing.select_line()Selects the current line.
If text is selected and spans multiple lines, that selection will be expanded to include whole lines.
textadept.editing.select_paragraph()Selects the current paragraph.
Paragraphs are surrounded by one or more blank lines.
textadept.editing.select_word([all=false])Selects the current word.
If that word is already selected, its next occurrence will be selected as a multiple selection.
Parameters:
See also: buffer.word_chars
textadept.editing.strip_trailing_spacesStrip trailing whitespace before saving non-binary files.
The default value is false.
textadept.editing.toggle_comment()Comments or uncomments source lines based on textadept.editing.comment_string.
If no lines are selected, the current line is toggled. Otherwise, the selected lines are toggled. As long as any part of a line is selected, that entire line is eligible for toggling.
textadept.editing.typeover_auto_pairedType over an auto-paired complement character from textadept.editing.auto_pairs.
The default value is true.
textadept.history moduleRecords buffer positions within Textadept views over time and allows for navigating through that history.
This module listens for text edit events and buffer switch events. Each time an insertion or deletion occurs, its location is recorded in the current view’s location history. If the edit is close enough to the previous record, the previous record is amended. Each time a buffer switch occurs, the before and after locations are also recorded.
textadept.history.back()Navigates backwards through the current view’s history.
textadept.history.clear()Clears all view history.
textadept.history.forward()Navigates forwards through the current view’s history.
textadept.history.maximum_history_sizeThe maximum number of history records to keep per view.
The default value is 100.
textadept.history.minimum_line_distanceThe minimum number of lines between distinct history records.
The default value is 3.
textadept.history.record([filename=buffer.filename[, line[, column[, soft=false]]]])Records a buffer location in the current view’s history.
Parameters:
nil, the current line is used.nil, the current column
is used.textadept.keys moduleDefines key bindings for Textadept.
This set of key bindings is pretty standard among other text editors, at least for basic editing commands and movements.
These bindings are designed to be as consistent as possible between operating systems and platforms so that users familiar with one set of bindings can intuit a given binding on another OS or platform, minimizing the need for memorization.
In general, bindings for macOS are the same as for Windows/Linux/BSD except the “Control” modifier key on Windows/Linux/BSD is replaced by “Command” (⌘) and the “Alt” modifier key is replaced by “Control” (^). The only exception is for word- and paragraph-based movement keys, which use “Alt” (⌥) instead of “Command” (⌘), as is customary on macOS.
In general, bindings for the terminal version are the same as for Windows/Linux/BSD except:
Windows Note: on international keyboard layouts, the “AltGr” key is equivalent to pressing
“Ctrl” and “Alt”, so “AltGr+key” combinations may unexpectedly trigger one of Textadept’s
“Ctrl+Alt+key” bindings. In order to avoid this, you will likely have to disable the
“Ctrl+Alt+key” binding in your ~/.textadept/init.lua by setting it to nil.
| Windows, Linux, and BSD | macOS | Terminal | Command |
|---|---|---|---|
| File | |||
| Ctrl+N | ⌘N | ^N | New file |
| Ctrl+O | ⌘O | ^O | Open file |
| None | None | None | Open recent file… |
| None | None | None | Reload file |
| Ctrl+S | ⌘S | ^S M-Sa |
Save file |
| Ctrl+Shift+S | ⌘⇧S | M-^S | Save file as.. |
| None | None | None | Save all files |
| Ctrl+W | ⌘W | ^W | Close file |
| Ctrl+Shift+W | ⌘⇧W | M-^W | Close all files |
| None | None | None | Load session… |
| None | None | None | Save session… |
| Ctrl+Q | ⌘Q | ^Q M-Qa |
Quit |
| Edit | |||
| Ctrl+Z Alt+Bksp |
⌘Z | ^Zb M-Bksp |
Undo |
| Ctrl+Y Ctrl+Shift+Z |
⌘⇧Z ⌘Y |
^Y M-^Z |
Redo |
| Ctrl+X Shift+Del |
⌘X ⇧⌦ |
^X S-Del |
Cut |
| Ctrl+C Ctrl+Ins |
⌘C | ^C | Copy |
| Ctrl+V Shift+Ins |
⌘V | ^V S-Ins |
Paste |
| Ctrl+Shift+V | ⌘⇧V | M-^V | Paste Reindent |
| Ctrl+Shift+D | ⌘⇧D | M-^D | Duplicate line/selection |
| Del | ⌦ ^D |
Del | Delete |
| Alt+Del | ^⌦ | M-Del | Delete word |
| Ctrl+A | ⌘A | ^A | Select all |
| Ctrl+Shift+A | ⌘⇧A | M-^A | Deselect |
| Ctrl+M | ⌘M | M-M | Match brace |
| Ctrl+Enter | ⌘↩ | ^Enter | Complete word |
| Ctrl+/ | ⌘/ | ^/ M-/ |
Toggle block comment |
| Ctrl+J | ⌘J | M-J | Join lines |
| Ctrl+| | ⌘| | ^| ^\ |
Filter text through |
| Ctrl+Shift+M | ⌘⇧M | M-^M | Select between delimiters |
| Ctrl+D | ⌘D | ^D | Select word |
| Ctrl+Alt+D | ^⌘D | M-D | Deselect word |
| Ctrl+L | ⌘L | ^L | Select line |
| Ctrl+Shift+P | ⌘⇧P | M-^P | Select paragraph |
| Ctrl+Shift+Uc Ctrl+Alt+Shift+U |
⌘⇧U | M-^U | Upper case selection |
| Ctrl+U | ⌘U | ^U | Lower case selection |
| Alt+< | ^< | M-< | Enclose selection as XML tags |
| Alt+> | ^> | M-> | Enclose selection as single XML tag |
| Alt+” | ^” | M-“ | Enclose selection in double quotes |
| Alt+’ | ^’ | M-‘ | Enclose selection in single quotes |
| Alt+( | ^( | M-( | Enclose selection in parentheses |
| Alt+[ | ^[ | None | Enclose selection in brackets |
| Alt+{ | ^{ | M-{ | Enclose selection in braces |
| Ctrl+Alt+Shift+Up | ^⌘⇧⇡ | None | Move selected lines up |
| Ctrl+Alt+Shift+Down | ^⌘⇧⇣ | None | Move selected lines down |
| Ctrl+[ Alt+Left |
⌘[ | M-[ M-Left |
Navigate backward |
| Ctrl+] Alt+Right |
⌘] | M-] M-Right |
Navigate forward |
| None | None | None | Record location |
| None | None | None | Clear navigation history |
| None | ⌘, | None | Preferences |
| Search | |||
| Ctrl+F | ⌘F | ^F | Find |
| None | None | None | Find next |
| None | None | None | Find previous |
| None | None | None | Replace |
| None | None | None | Replace all |
| Ctrl+Alt+F | ^⌘F | M-F | Find incremental |
| Ctrl+Shift+F | ⌘⇧F | M-^F | Find in files |
| Ctrl+Alt+G | ^⌘G | M-G | Go to next file found |
| Ctrl+Alt+Shift+G | ^⌘⇧G | M-S-G | Go to previous file found |
| Ctrl+G | ⌘G | ^G | Go to line |
| Tools | |||
| Ctrl+E | ⌘E | ^E | Command entry |
| Ctrl+P | ⌘P | ^P | Select command |
| Ctrl+R | ⌘R | ^R | Run |
| Ctrl+Shift+C | ⌘⇧C | M-^C | Compile |
| Ctrl+Shift+B | ⌘⇧B | M-^B | Build |
| Ctrl+Shift+T | ⌘⇧T | M-^T | Run tests |
| Ctrl+Shift+R | ⌘⇧R | M-^R | Run project |
| Ctrl+Shift+X | ⌘⇧X | M-^X | Stop |
| Ctrl+Alt+E | ^⌘E | M-E | Next Error |
| Ctrl+Alt+Shift+E | ^⌘⇧E | M-S-E | Previous Error |
| Ctrl+K | ⌘K | ^K | Toggle bookmark |
| None | None | None | Clear bookmarks |
| Ctrl+Alt+K | ^⌘K | M-K | Next bookmark |
| Ctrl+Alt+Shift+K | ^⌘⇧K | M-S-K | Previous bookmark |
| Ctrl+Shift+K | ⌘⇧K | M-^K | Go to bookmark… |
| Alt+, | ^, | M-, | Start/stop recording macro |
| Alt+. | ^. | M-. | Play recorded macro |
| None | None | None | Save recorded macro |
| None | None | None | Load saved macro |
| Ctrl+Alt+U | ⌘⇧U | M-U | Quickly open _USERHOME |
| Ctrl+Alt+H | ⌘⇧H | M-H | Quickly open _HOME |
| None | None | None | Quickly open current directory |
| Ctrl+Shift+O | ⌘⇧O | M-^O | Quickly open current project |
| None | None | None | Insert snippet… |
| Tab | ⇥ | Tab | Expand snippet or next placeholder |
| Shift+Tab | ⇧⇥ | S-Tab | Previous snippet placeholder |
| Esc | Esc | Esc | Cancel snippet |
| None | None | None | Complete trigger word |
| None | None | None | Show style |
| Buffer | |||
| Ctrl+Tab Ctrl+PgDn |
^⇥ ⌘⇟ |
M-PgDn ^Tabd |
Next buffer |
| Ctrl+Shift+Tab Ctrl+PgUp |
^⇧⇥ ⌘⇞ |
M-PgUp S-^Tabd |
Previous buffer |
| Ctrl+B | ⌘B | ^B | Switch to buffer… |
| None | None | None | Tab width: 2 |
| None | None | None | Tab width: 3 |
| None | None | None | Tab width: 4 |
| None | None | None | Tab width: 8 |
| Ctrl+Alt+T | ^⌘T | M-T | Toggle use tabs |
| None | None | None | Convert indentation |
| None | None | None | CR+LF EOL mode |
| None | None | None | LF EOL mode |
| None | None | None | UTF-8 encoding |
| None | None | None | ASCII encoding |
| None | None | None | CP-1252 encoding |
| None | None | None | UTF-16 encoding |
| Ctrl+Shift+L | ⌘⇧L | M-^L | Select lexer… |
| View | |||
| Ctrl+Alt+PgDn | ^⌘⇟ | M-^PgDn M-PgUpd |
Next view |
| Ctrl+Alt+PgUp | ^⌘⇞ | M-^PgUp M-PgDnd |
Previous view |
| Ctrl+Alt+_ | ^⌘_ | M-_ | Split view horizontal |
| Ctrl+Alt+| | ^⌘| | M-| | Split view vertical |
| Ctrl+Alt+W | ^⌘W | M-W | Unsplit view |
| Ctrl+Alt+Shift+W | ^⌘⇧W | M-S-W | Unsplit all views |
| Ctrl+Alt++ Ctrl+Alt+= |
^⌘+ ^⌘= |
M-+ M-= |
Grow view |
| Ctrl+Alt+- | ^⌘- | M– | Shrink view |
| Ctrl+} | ⌘} | M-} | Toggle current fold |
| Ctrl+\ | ⌘\ | M-\ | Toggle wrap mode |
| None | None | N/A | Toggle indent guides |
| None | None | None | Toggle view whitespace |
| None | None | None | Toggle virtual space |
| Ctrl+= | ⌘= | N/A | Zoom in |
| Ctrl+- | ⌘- | N/A | Zoom out |
| Ctrl+0 | ⌘0 | N/A | Reset zoom |
| Help | |||
| F1 | F1 | None | Open manual |
| Shift+F1 | ⇧F1 | None | Open LuaDoc |
| None | None | None | About |
| Other | |||
| Shift+Enter | ⇧↩ | None | Start a new line below the current one |
| Ctrl+Shift+Enter | ⌘⇧↩ | None | Start a new line above the current one |
| Ctrl+Alt+Down | ^⌘⇣ | M-Down | Scroll line down |
| Ctrl+Alt+Up | ^⌘⇡ | M-Up | Scroll line up |
| Alt+PgUp | ^⇞ | N/A | Scroll page up |
| Alt+PgDn | ^⇟ | N/A | Scroll page down |
| Menu Shift+F10d |
N/A | N/A | Show context menu |
| Ctrl+Alt+Shift+R c | ^⌘⇧R c | M-S-R c | Save macro to alphanumeric register c |
| Ctrl+Alt+R c | ^⌘R c | M-R c | Load and play macro from alphanumeric register c |
| Movement | |||
| Down | ⇣ ^N |
Down | Line down |
| Shift+Down | ⇧⇣ ^⇧N |
S-Down | Line down extend selection |
| Alt+Shift+Down | ^⇧⇣ | M-S-Down | Line down extend rect. selection |
| Ctrl+Down | ⌥⇣ | ^Down | Paragraph down |
| Ctrl+Shift+Down | ⌥⇧⇣ | S-^Down | Paragraph down extend selection |
| Up | ⇡ ^P |
Up | Line up |
| Shift+Up | ⇧⇡ ^⇧P |
S-Up | Line up extend selection |
| Alt+Shift+Up | ^⇧⇡ | M-S-Up | Line up extend rect. selection |
| Ctrl+Up | ⌥⇡ | ^Up | Paragraph up |
| Ctrl+Shift+Up | ⌥⇧⇡ | S-^Up | Paragraph up extend selection |
| Left | ⇠ ^B |
Left | Char left |
| Shift+Left | ⇧⇠ ^⇧B |
S-Left | Char left extend selection |
| Alt+Shift+Left | ^⇧⇠ | M-S-Left | Char left extend rect. selection |
| Ctrl+Left | ⌥⇠ | ^Left | Word left |
| Ctrl+Shift+Left | ⌥⇧⇠ | S-^Left | Word left extend selection |
| Ctrl+Alt+Left | ^⌥⇠ | None | Word part left |
| Ctrl+Alt+Shift+Left | ^⌥⇧⇠ | None | Word part left extend selection |
| Right | ⇢ ^F |
Right | Char right |
| Shift+Right | ⇧⇢ ^⇧F |
S-Right | Char right extend selection |
| Alt+Shift+Right | ^⇧⇢ | M-S-Right | Char right extend rect. selection |
| Ctrl+Right | ⌥⇢ | ^Right | Word right |
| Ctrl+Shift+Right | ⌥⇧⇢ | S-^Right | Word right extend selection |
| Ctrl+Alt+Right | ^⌥⇢ | None | Word part right |
| Ctrl+Alt+Shift+Right | ^⌥⇧⇢ | None | Word part right extend selection |
| Home | ↖ ⌘⇠ ^A |
Home | Line start |
| Shift+Home | ⇧↖ ⌘⇧⇠ ^⇧A |
None | Line start extend selection |
| Alt+Shift+Home | ^⇧↖ | None | Line start extend rect. selection |
| Ctrl+Home | ⌘↖ | None | Document start |
| Ctrl+Shift+Home | ⌘⇧↖ | None | Document start extend selection |
| End | ↘ ⌘⇢ ^E |
End | Line end |
| Shift+End | ⇧↘ ⌘⇧⇢ ^⇧E |
None | Line end extend selection |
| Alt+Shift+End | ^⇧↘ | None | Line end extend rect. selection |
| Ctrl+End | ⌘↘ | None | Document end |
| Ctrl+Shift+End | ⌘⇧↘ | None | Document end extend selection |
| PgUp | ⇞ | PgUp | Page up |
| Shift+PgUp | ⇧⇞ | None | Page up extend selection |
| Alt+Shift+PgUp | ^⇧⇞ | None | Page up extend rect. selection |
| PgDn | ⇟ | PgDn | Page down |
| Shift+PgDn | ⇧⇟ | None | Page down extend selection |
| Alt+Shift+PgDn | ^⇧⇟ | None | Page down extend rect. selection |
| Ctrl+Del | ⌘⌦ | ^Del | Delete word right |
| Ctrl+Shift+Del | ⌘⇧⌦ | S-^Del | Delete line right |
| Ins | Ins | Ins | Toggle overtype |
| Bksp | ⌫ ^H |
Bksp ^H |
Delete back |
| Ctrl+Bksp | ⌘⌫ | None | Delete word left |
| Ctrl+Shift+Bksp | ⌘⇧⌫ | None | Delete line left |
| Tab | ⇥ | Tab ^I |
Insert tab or indent |
| Shift+Tab | ⇧⇥ | S-Tab | Dedent |
| None | ^K | None | Cut to line end |
| None | ^L | None | Center line vertically |
| N/A | N/A | ^^ | Mark text at the caret position |
| N/A | N/A | ^] | Swap caret and mark anchor |
| Find Fields | |||
| Left | ⇠ ^B |
Left ^B |
Cursor left |
| Right | ⇢ ^F |
Right ^F |
Cursor right |
| Del | ⌦ | Del | Delete forward |
| Bksp | ⌫ | Bksp ^H |
Delete back |
| Ctrl+V | ⌘V | ^V | Paste |
| N/A | N/A | ^X | Cut all |
| N/A | N/A | ^Y | Copy all |
| N/A | N/A | ^U | Erase all |
| Home | ↖ ⌘⇠ ^A |
Home ^A |
Home |
| End | ↘ ⌘⇢ ^E |
End ^E |
End |
| N/A | N/A | ^T | Transpose characters |
| N/A | N/A | Tab | Toggle find/replace buttons |
| Tab | ⇥ | Down | Focus replace field |
| Shift+Tab | ⇧⇥ | Up | Focus find field |
| Up | ⇡ | ^P | Cycle back through history |
| Down | ⇣ | ^N | Cycle forward through history |
| N/A | N/A | F1 | Toggle “Match Case” |
| N/A | N/A | F2 | Toggle “Whole Word” |
| N/A | N/A | F3 | Toggle “Regex” |
| N/A | N/A | F4 | Toggle “Find in Files” |
a For use when the -p or --preserve command line option is given to the
non-Windows terminal version, since ^S and ^Q are flow control sequences.
b If you prefer ^Z to suspend, you can bind it to ui.suspend().
c Some versions of Linux intercept this for Unicode input.
d Only on Windows or the GTK version on Linux.
textadept.macros moduleA module for recording, playing, saving, and loading keyboard macros.
Menu commands are also recorded. At this time, typing into multiple cursors during macro playback is not supported.
textadept.macros.load([filename])Loads a macro.
Parameters:
nil, the user is prompted for one. If
the filename is a relative path, it will be relative to ~/.textadept/macros/.textadept.macros.play([filename])Plays a recorded or previously loaded macro.
Parameters:
textadept.macros.record()Toggles between starting and stopping macro recording.
textadept.macros.save([filename])Saves a recorded macro.
Parameters:
nil, the user
is prompted for one. If the filename is a relative path, it will be relative to
~/.textadept/macros/.textadept.menu moduleDefines the menus used by Textadept.
Menus are simply tables of menu items and submenus. A menu item itself is a two-element table: a
menu label and a menu command to run. Submenus have title keys assigned to string label text.
Menus may be edited in place using normal Lua table operations. You can index a menu with either an index, a string label name, or a string path with submenus separated by ‘/’. When indexing with strings, labels are localized as needed, so you can use either English labels or their localized equivalent.
-- Append to the right-click context menu.
table.insert(textadept.menu.context_menu, {'Label', function() ... end})
-- Append an encoding in the "Buffer > Encoding" menu.
table.insert(textadept.menu.menubar['Buffer/Encoding'],
{'UTF-32', function() buffer:set_encoding('UTF-32') end})
-- Change the "Search > Find" command.
textadept.menu.menubar['Search/Find'][2] = function() ... end
textadept.menu.context_menuThe default right-click context menu.
Usage:
table.insert(textadept.menu.context_menu, {'Label', function() ... end})
textadept.menu.menubarThe default main menubar.
Usage:
table.insert(textadept.menu.menubar['Tools'], {...}) -- Append to the Tools menu
textadept.menu.menubar['File/New'] --> table for "File > New"
textadept.menu.menubar['File/New'][2] = function() ... end -- change "File > New" command
textadept.menu.select_command()Prompts the user to select a menu command to run.
textadept.menu.tab_context_menuThe default tabbar context menu.
textadept.run moduleExecute compile, run, build, test, and project shell commands with Textadept.
The editor prompts you with/for shell commands to run, prints output in real-time, and marks any warning and error messages it recognizes. Textadept remembers commands on a per-filename and per-directory basis where applicable.
textadept.run.INDIC_ERRORThe run or compile error indicator number.
textadept.run.INDIC_WARNINGThe run or compile warning indicator number.
textadept.run.MARK_ERRORThe run or compile error marker number.
textadept.run.MARK_WARNINGThe run or compile warning marker number.
textadept.run.build([dir])Prompts the user with the command entry to build a project using its shell command from the
textadept.run.build_commands table.
Parameters:
See also: events.BUILD_OUTPUT
textadept.run.build_commandsMap of project root paths and “makefiles” to their associated “build” shell command line strings or functions that return such strings.
Functions may also return a working directory and process environment table to operate in. By default, the working directory is the project’s root directory and the environment is Textadept’s environment.
Usage:
textadept.run.build_commands['CMakeLists.txt'] = 'cmake --build build'
textadept.run.build_commands['/path/to/project'] = 'make -C src'
textadept.run.compile([filename=buffer.filename])Prompts the user with the command entry to compile a file using an appropriate shell command
from the textadept.run.compile_commands table.
The shell command is determined from the file’s filename, extension, or language, in that order.
Parameters:
See also: events.COMPILE_OUTPUT
textadept.run.compile_commandsMap 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:
%f: The file’s name, including its extension.%e: The file’s name, excluding its extension.%d: The file’s directory path.%p: The file’s full path.Functions may also return a working directory and process environment table to operate in. By default, the working directory is the current file’s parent directory and the environment is Textadept’s environment.
Usage:
textadept.run.compile_commands.c = 'clang -o "%e" "%f"'
textadept.run.goto_error(location)Jumps to the source of a recognized compile/run/build/test warning or error in the output buffer, displaying an annotation with the warning or error message if possible.
Parameters:
true, jumps to the next recognized warning/error. When false,
jumps to the previous one. When a line number, jumps to it’s source.textadept.run.run([filename=buffer.filename])Prompts the user with the command entry to run a file using an appropriate shell command
from the textadept.run.run_commands table.
The shell command is determined from the file’s filename, extension, or language, in that order.
Parameters:
See also: events.RUN_OUTPUT
textadept.run.run_commandsMap 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:
%f: The file’s name, including its extension.%e: The file’s name, excluding its extension.%d: The file’s directory path.%p: The file’s full path.Functions may also return a working directory and process environment table to operate in. By default, the working directory is the current file’s parent directory and the environment is Textadept’s environment.
Usage:
textadept.run.run_commands.lua = 'lua5.1 "%f"'
textadept.run.run_in_backgroundRun shell commands silently in the background.
The default value is false.
textadept.run.run_project([dir[, cmd]])Prompts the user with the command entry to run a shell command for a project.
Parameters:
textadept.run.run_project_commands and dir.See also: events.RUN_OUTPUT
textadept.run.run_project_commandsMap of project root paths to their associated “run” shell command line strings or functions that return such strings.
Functions may also return a working directory and process environment table to operate in. By default, the working directory is the project’s root directory and the environment is Textadept’s environment.
Usage:
textadept.run.run_project_commands[_HOME] = function()
local env = {TEXTADEPT_HOME = _HOME}
for setting in os.spawn('env'):read('a'):gmatch('[^\n]+') do env[#env + 1] = setting end
return _HOME .. '/build/textadept -f -n', '/tmp', env -- run test instance of Textadept
end
textadept.run.run_without_promptRun shell commands without prompting.
The default value is false.
textadept.run.stop()Stops the currently running process, if any.
If there is more than one running process, the user is prompted to select the process to stop. Processes in the list are sorted from longest lived at the top to shortest lived on the bottom.
textadept.run.test([dir])Prompts the user with the command entry to run tests for a project using its shell command
from the textadept.run.test_commands table.
Parameters:
See also: events.TEST_OUTPUT
textadept.run.test_commandsMap of project root paths to their associated “test” shell command line strings or functions that return such strings.
Functions may also return a working directory and process environment table to operate in. By default, the working directory is the project’s root directory and the environment is Textadept’s environment.
Usage:
textadept.run.test_commands['/path/to/project'] = 'pytest'
textadept.session moduleSession support for Textadept.
textadept.session.load([filename])Loads a session file.
Textadept restores split views, opened buffers, cursor information, recent files, and bookmarks.
Parameters:
nil, the user
is prompted for one.See also: events.SESSION_LOAD
textadept.session.save(filename)Saves the session to a file.
Textadept saves split views, opened buffers, cursor information, recent files, and bookmarks.
The editor will save the current session to that file again before quitting unless
textadept.session.save_on_quit is false.
Parameters:
nil, the user
is prompted for one.See also: events.SESSION_SAVE
textadept.session.save_on_quitSave the session when quitting.
The default value is true unless the user passed the command line switch -n or --nosession
to Textadept.
textadept.snippets moduleSnippets for Textadept.
Define snippets in the global snippets table in key-value pairs. Each pair consists of
either:
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.
Snippets may contain any combination of plain-text sequences, variables, interpolated code, and placeholders.
Plain text consists of any character except ‘$’ and ‘`’. Those two characters are reserved for variables, interpolated code, and placeholders. In order to use either of those two characters literally, prefix them with ‘\’ (e.g. “\$” inserts a literal ‘$’).
Variables are defined in the textadept.snippets.variables table. Textadept expands
them in place using the ‘$’ prefix (e.g. $TM_SELECTED_TEXT references the currently
selected text). You can provide default values for empty or undefined variables using the
“${variable:default}” syntax (e.g. ${TM_SELECTED_TEXT:no text selected}). The values of
variables may be transformed in-place using the “${variable/regex/format/options}”
syntax (e.g. ${TM_SELECTED_TEXT/.+/"$0"/} quotes the selected text). The section on
placeholder transforms below describes this syntax in more detail.
Snippets can execute shell code enclosed within ‘`’ characters, and insert any standard output (stdout) emitted by that code. Textadept omits a trailing newline if it exists. For example, the following snippet evaluates (on macOS and Linux) the currently selected arithmetic expression and replaces it with the result:
snippets.eval = '`echo $(( $TM_SELECTED_TEXT ))`'
Snippets can also execute Lua code enclosed within “```” sequences, and insert any string results returned by that code. For example, the following snippet inserts the current date and time:
snippets.date = '```os.date()```'
Lua code is executed within Textadept’s Lua environment, with the addition of snippet
variables available as global variables (e.g. TM_SELECTED_TEXT exists as a global).
The true power of snippets lies with placeholders. Using placeholders, you can insert a text template and tab through placeholders one at a time, filling them in. Placeholders may be linked to one another, either mirroring text or transforming it in-place.
The simplest kind of placeholder is called a tab stop, and its syntax is either “$n” or
“${n}”, where n is an integer. When a snippet is inserted, the caret is moved to the
“$1” placeholder. Pressing the Tab key jumps to the next placeholder, “$2”, and so on. When
there are no more placeholders to jump to, the caret moves to either the “$0” placeholder if
it exists, or it moves to the end of the snippet. For example, the following snippet inserts
a 3-element vector, with tab stops at each element:
snippets.vec = '[$1, $2, $3]'
Placeholders may have default values using the “${n:default}” syntax. For example, the following snippet creates a numeric “for” loop in Lua:
snippets.lua.fori = [[
for ${1:i} = ${2:1}, $3 do
$0
end]]
Multiline snippets should be indented with tabs. Textadept will apply the buffer’s current indentation settings to the snippet upon insertion.
Placeholders may be nested inside one another. For example, the following snippet inserts a function call with a mandatory first argument, but an optional second one:
snippets.call = '${1:func}($2${3:, $4})'
Upon arriving at the third placeholder, backspacing and pressing Tab completes the snippet
with a single argument. On the other hand, pressing Tab again at the third placeholder
jumps to the second argument for input.
Note that plain text inside default values may not contain a ‘}’ character either, as it is reserved to indicate the end of the placeholder. Use “\}” to represent a literal ‘}’.
Multiple placeholders can share the same numeric index. When this happens, Textadept visits the one with a default value if it exists. Otherwise, the editor visits the first one it finds. As you type text into a placeholder, any other placeholders with the same index mirror the typed text. For example, the following snippet inserts beginning and ending HTML/XML tags with the same name:
snippets.tag = '<${1:div}>$0</$1>'
The end tag mirrors whatever name you type into the start tag.
Sometimes mirrors are not quite good enough. For example, perhaps the mirror’s content needs to deviate slightly from its linked placeholder, like capitalizing the first letter. Or perhaps the mirror’s contents should depend on the presence (or absence) of text in its linked placeholder. This is where placeholder transforms come in handy.
Transforms use the “${n/regex/format/options}” syntax, where regex is a regular expression (regex) to match against the content of placeholder n, format is a formatted replacement for matched content, and options are regex options to use when matching. format may contain any of the following:
textadept.snippets.transform_methods.options may include any of the following letters:
For example, the following snippet defines an attribute along with its getter and setter functions:
snippets.attr = [[
${1:int} ${2:name};
${1} get${2/./${0:/upcase}/}() { return $2; }
void set${2/./${0:/upcase}/}(${1} ${3:value}) { $2 = $3; }
]]
Note that the ‘/’ and ‘}’ characters are reserved in certain places within a placeholder transform. Use “\/” and “\}”, respectively, to represent literal versions of those characters where necessary.
Placeholders may define a list of options for the user to choose from using the
“${n|items|}” syntax, where items is a comma-separated list of options
(e.g. ${1|foo,bar,baz|}).
Items may not contain a ‘|’ character, as it is reserved to indicate the end of the choice list. Use “\|” to represent a literal ‘|’.
Legacy snippets used the following syntax:
You can migrate your snippets using the following steps:
%(\d+)\(([^)]+)\) and
${\1:\2}.textadept.snippets.transform_methods if you
need to.textadept.snippets.INDIC_PLACEHOLDERThe snippet placeholder indicator number.
textadept.snippets.activeWhether or not a snippet is active.
textadept.snippets.cancel()Cancels the active snippet, removing all inserted text.
Returns: false if no snippet is active; nil otherwise.
textadept.snippets.insert([text])Inserts a snippet or, if a snippet is already active, goes to that snippet’s next placeholder.
Parameters:
nil, attempts to insert a new snippet
based on the trigger (the word behind caret) and the current lexer.Returns: false if no action was taken; nil otherwise.
See also: buffer.word_chars
textadept.snippets.pathsTable of directory paths to look for snippet files in.
Filenames are of the form lexer.trigger.ext or trigger.ext (.ext is an optional,
arbitrary file extension). If the global snippets table does not contain a snippet for
a given trigger, this table is consulted for a matching filename, and the contents of that
file is inserted as a snippet.
Note: If a directory has multiple snippets with the same trigger, the snippet chosen for insertion is not defined and may not be constant.
textadept.snippets.previous()Jumps back to the previous snippet placeholder, reverting any changes from the current one.
Returns: false if no snippet is active; nil otherwise.
textadept.snippets.select()Prompts the user to select a snippet to insert from a list of global and language-specific snippets.
textadept.snippets.transform_methodsMap of format method names to their functions for text captured in placeholder transforms.
Fields:
upcase: Uppercases the captured text.downcase: Lowercases the captured text.capitalize: Capitalizes the captured text.textadept.snippets.variablesMap of snippet variable names to string values or functions that return string values.
Each time a snippet is inserted, this map is used to set its variables.
Fields:
TM_SELECTED_TEXT: The currently selected text, if any.TM_CURRENT_LINE: The contents of the current line.TM_CURRENT_WORD: The word under the caret, if any.TM_LINE_NUMBER: The current line number.TM_LINE_INDEX: The current line number, counting from 0.TM_FILENAME: The buffer’s filename, excluding path, if any.TM_FILENAME_BASE: The buffer’s bare filename, without extension.TM_DIRECTORY: The buffer’s parent directory path.TM_FILEPATH: The buffer’s filename, including path.ui moduleUtilities for interacting with Textadept’s user interface.
ui.SHOW_ALL_TABSOption for ui.tabs that always shows the tab bar, even if only one buffer is open.
ui.buffer_list_zorderList buffers by their z-order (most recently viewed to least recently viewed) in the switcher dialog, instead of listing buffers in their left-to-right tab order.
The default value is true.
ui.buffer_statusbar_textThe text displayed in the buffer statusbar. (Write-only)
ui.clipboard_textThe text on the clipboard.
ui.context_menuThe 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.get_split_table()Returns a split table that contains Textadept’s current split view structure.
This is primarily used in session saving.
Returns: table of split views. Each split view entry is a table with 4 fields: 1, 2,
vertical, and size. 1 and 2 have values of either nested split view entries or
the views themselves; vertical is a flag that indicates if the split is vertical or
not; and size is the integer position of the split resizer.
ui.goto_file(filename[, split=false[, preferred_view[, sloppy=false]]])Go to a particular file, opening it if necessary.
Parameters:
buffer.filename
This is useful for compile/run/test/build commands, which output relative filenames
and paths instead of full ones, and it is likely that the file in question is already open.ui.goto_view(view)Switches focus to another view.
Parameters:
Usage:
ui.goto_view(_VIEWS[1]) -- switch to first view
ui.goto_view(-1) -- switch to the view before the current one
See also: events.VIEW_BEFORE_SWITCH, events.VIEW_AFTER_SWITCH
ui.maximizedWhether or not Textadept’s window is maximized.
This field is always false in the terminal version.
ui.menu(menu_table)Low-level function for creating a menu.
You probably want to use the higher-level textadept.menu.menubar,
textadept.menu.context_menu, or textadept.menu.tab_context_menu tables.
Parameters:
title key.Returns: menu userdata
Usage:
ui.menu{ {'_New', 1}, {'_Open', 2}, {''}, {'&Quit', 4} }
ui.menu{ {'_New', 1, string.byte('n'), view.MOD_CTRL} } -- 'Ctrl+N'
ui.menubarA table of menus defining a menubar.
(Write-only).
This is a low-level field. You probably want to use the higher-level textadept.menu.menubar.
ui.output(…)Prints to the output buffer, creating it if necessary.
The output buffer attempts to understand the error messages and warnings produced by various tools.
If the output buffer is already open in a view, output is printed to that view. Otherwise
the view is split (unless ui.tabs is true) and the output buffer is displayed before
being printed to.
Parameters:
Returns: the output buffer
ui.output_silent(…)Prints to the output buffer (creating it if necessary) without switching to it.
Parameters:
Returns: the output buffer
ui.popup_menu(menu)Displays a popup menu, typically the right-click context menu.
Parameters:
Usage:
ui.popup_menu(ui.context_menu)
See also: ui.context_menu, ui.menu
ui.print(…)Prints to the output buffer (creating it if necessary), along with a trailing newline.
This function is primarily for use in the Lua command entry in place of Lua’s print()
function.
Parameters:
tostring() function is called for each value. They will
be printed as tab-separated values.ui.print_silent_to(type, message)Prints a message to a typed buffer (creating it if necessary) without switching to it.
Parameters:
Returns: the typed buffer printed to
ui.print_to(type, message)Prints a message along with a trailing newline to a typed buffer, creating it if necessary.
If the print buffer is already open in a view, the message is printed to that view. Otherwise
the view is split (unless ui.tabs is true) and the print buffer is displayed before
being printed to.
Parameters:
Returns: the typed buffer printed to
Usage:
ui.print_to('[Typed Buffer]', message)
ui.sizeA table that contains the width and height pixel values of Textadept’s window.
Usage:
ui.size = {1000, 625} -- resize window
ui.statusbar_textThe text displayed in the statusbar. (Write-only)
ui.suspend()Suspends Textadept.
This only works in the terminal version. By default, Textadept ignores ^Z suspend signals from the terminal.
Usage:
keys['ctrl+z'] = ui.suspend
See also: events.SUSPEND, events.RESUME
ui.switch_buffer()Prompts the user to select a buffer to switch to.
Buffers are listed in their left-to-right tab order unless ui.buffer_list_zorder is true, in
which case buffers are listed by their z-order (most recently viewed to least recently viewed).
Buffers in the same project as the current buffer are shown with relative paths.
ui.tab_context_menuThe 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.tabsDisplay the tab bar when multiple buffers are open.
The default value is true in the GUI version, and false in the terminal version.
A third option, ui.SHOW_ALL_TABS may be used to always show the tab bar, even if only one
buffer is open.
ui.titleThe title text of Textadept’s window. (Write-only)
ui.update()Processes pending UI events, including reading from spawned processes.
This function is primarily used in Textadept’s own unit tests.
ui.command_entry moduleTextadept’s Command Entry.
It supports multiple modes that each have their own functionality (such as running Lua code
and filtering text through shell commands) and history.
In addition to the API listed below, the command entry also shares the same API as buffer
and view.
ui.command_entry.activeWhether or not the command entry is active.
ui.command_entry.editing_keysA Lua metatable that contains a set of typical key bindings for text entries.
It is automatically added to keys passed to ui.command_entry.run() unless those keys
already have their own metatable.
ui.command_entry.focus()Opens the command entry.
This is a low-level function. You probably want to use the higher-level
ui.command_entry.run().
ui.command_entry.heightThe height in pixels of the command entry.
ui.command_entry.labelThe text of the command entry label. (Write-only)
ui.command_entry.run(label, f[, keys][, lang=’text’[, initial_text[, …]]])Opens the command entry.
This function may be called with no arguments to open the Lua command entry.
Parameters:
Enter. It should accept at a minimum the command
entry text as an argument.ui.command_entry.editing_keys. Esc and Enter
are automatically defined to cancel and finish the command entry, respectively. The
command entry does not respond to Textadept’s default key bindings.Usage:
ui.command_entry.run('echo:', ui.print)
ui.command_entry.run('$', os.spawn, 'bash', 'env', ui.print) -- spawn a process
ui.dialogs moduleProvides a set of interactive dialog prompts for user input.
ui.dialogs.input(options)Prompts the user for string input.
Parameters:
options: Table of key-value option pairs for the dialog.
title: String title.text: String initial input.button1: String label for the primary (accept) button. The default value is _L['OK'].button2: String label for the secondary (reject) button. The default value is
_L['Cancel'].button3: String label for the tertiary button. This option requires button2
to be set. It is not available in the Qt version.return_button: Also return the index of the selected button.Returns: string input text[, selected button index]; or nil if the user canceled the dialog
Usage:
ui.dialogs.input{title = 'Go to line number:', text = '1'}
ui.dialogs.list(options)Prompts the user to select an item from a list.
Text typed into the dialog filters the list items. Spaces are treated as wildcards.
Parameters:
options: Table of key-value option pairs for the dialog.
title: String title.text: String initial input text.columns: Table of string column names for list row headers. If this field is omitted,
a single column is used.items: Table of string items to show in the list. Each item is placed in the next
available column of the current row. If there is only one column, each item is
on its own row.button1: String label of the primary (accept) button. The default value is _L['OK'].button2: String label of the secondary (reject) button. The default value is
_L['Cancel'].button3: String label of the tertiary button. This option requires button2 to be set.multiple: Allow the user to select multiple items. The terminal version does not
support this option.search_column: Column number to filter the input text against. The default value is 1.select: Row number to initially select. The default value is 1.return_button: Also return the index of the selected button.Returns: selected item or table of selected items[, selected button index]; or nil if the
user canceled the dialog
Usage:
ui.dialogs.list{title = 'Title', columns = {'Foo', 'Bar'}, items = {'a', 'b', 'c', 'd'}}
ui.dialogs.message(options)Shows a message box.
Parameters:
options: Table of key-value option pairs for the dialog.
title: String title.text: String main message.icon: String icon name, according to the Free Desktop Icon Naming
Specification. Examples are “dialog-error”, “dialog-information”,
“dialog-question”, and “dialog-warning”.button1: String label for the primary (accept) button. The default value is _L['OK'].button2: String label for the secondary (reject) button.button3: String label for the tertiary button. This option requires button2 to be set.Returns: the selected button’s index, or nil if the user canceled the dialog
Usage:
ui.dialogs.message{
title = 'EOL Mode', text = 'Which EOL?', icon = 'dialog-question',
button1 = 'CRLF', button2 = 'CR', button3 = 'LF'
}
ui.dialogs.open(options)Prompts the user to select a file from the filesystem.
Parameters:
options: Table of key-value option pairs for the dialog.
title: String title.dir: String directory to initially show.file: String file to initially select. This option requires dir to be set.multiple: Allow the user to select multiple files. The terminal version does not
support this option.only_dirs: Only allow the user to select directories.Returns: string filename or table of filenames; or nil if the user canceled the dialog
Usage:
ui.dialogs.open{title = 'Open File', dir = _HOME, multiple = true}
ui.dialogs.progress(options)Displays a progress dialog while doing work.
Parameters:
options: Table of key-value option pairs for the dialog.
title: String title.text: String initial progressbar display text (GUI version only).work: Function repeatedly called to do work and provide progress updates. This function
is called without arguments and must return either nil, which indicates work
is complete, or a progress percentage number in the range 0-100 and optionally
a string to display (GUI version only). If progress is indeterminate, the
percentage can be less than zero.Returns: nil if all work completed, or true if the user clicked “Stop”
Usage:
ui.dialogs.progress{work = function()
if not work() then return nil end
return percent, status
end}
ui.dialogs.save(options)Prompts the user to select a file to save to.
Parameters:
options: Table of key-value option pairs for the dialog.
title: String title.dir: String directory to initially show.file: String filename to initially select. This option requires dir to be set.Returns: string filename, or nil if the user canceled the dialog
ui.find moduleTextadept’s Find & Replace pane.
ui.find.INDIC_FINDThe find results highlight indicator number.
ui.find.activeWhether or not the Find & Replace pane is active.
ui.find.entry_fontThe font to use in the “Find” and “Replace” entries in “name size” format. (Write-only) The default value is system-dependent.
ui.find.find_entry_textThe text in the “Find” entry.
ui.find.find_in_files_filtersMap of directory paths to filters used when finding in files.
A filter consists of glob patterns that match file and directory paths to include or exclude. Exclusive patterns begin with a ‘!’. If no inclusive patterns are given, any path is initially considered. As a convenience, ‘/’ also matches the Windows directory separator.
This table is updated when the user manually specifies a filter in the “Filter” entry during an “In files” search.
ui.find.find_label_textThe text of the “Find” label. (Write-only) This is primarily used for localization.
ui.find.find_next()Mimics pressing the “Find Next” button.
See also: events.FIND
ui.find.find_next_button_textThe text of the “Find Next” button. (Write-only) This is primarily used for localization.
ui.find.find_prev()Mimics pressing the “Find Prev” button.
See also: events.FIND
ui.find.find_prev_button_textThe text of the “Find Prev” button. (Write-only) This is primarily used for localization.
ui.find.focus([options])Displays and focuses the Find & Replace Pane.
Parameters:
ui.find field options to initially set.Usage:
ui.find.focus{find_entry_text = buffer:get_sel_text(), match_case = true}
ui.find.goto_file_found(location)Jumps to the source of a find in files search result in the “Files Found” buffer.
Parameters:
true, jumps to the next search result. When false, jumps to the
previous one. When a line number, jumps to it’s source.ui.find.highlight_all_matchesHighlight all occurrences of found text in the current buffer.
The default value is false.
ui.find.in_filesFind search text in a directory of files.
The default value is false.
ui.find.in_files_label_textThe text of the “In files” label. (Write-only) This is primarily used for localization.
ui.find.incrementalFind search text incrementally as it is typed.
The default value is false.
ui.find.match_caseMatch search text case sensitively.
The default value is false.
ui.find.match_case_label_textThe text of the “Match case” label. (Write-only) This is primarily used for localization.
ui.find.regexInterpret search text as a Regular Expression.
The default value is false.
ui.find.regex_label_textThe text of the “Regex” label. (Write-only) This is primarily used for localization.
ui.find.replace()Mimics pressing the “Replace” button.
If any events.REPLACE handler returns true, events.FIND will not be emitted to mimic
pressing the “Find Next” button.
ui.find.replace_all()Mimics pressing the “Replace All” button.
See also: events.REPLACE_ALL
ui.find.replace_all_button_textThe text of the “Replace All” button. (Write-only) This is primarily used for localization.
ui.find.replace_button_textThe text of the “Replace” button. (Write-only) This is primarily used for localization.
ui.find.replace_entry_textThe text in the “Replace” entry.
When searching for text in a directory of files, this is the current file and directory filter.
ui.find.replace_label_textThe text of the “Replace” label. (Write-only) This is primarily used for localization.
ui.find.show_filenames_in_progressbarShow filenames in the find in files search progressbar.
This can be useful for determining whether or not custom filters are working as expected. Showing filenames can slow down searches on computers with really fast SSDs.
The default value is false.
ui.find.whole_wordMatch search text only when it is surrounded by non-word characters in searches.
The default value is false.
See also: buffer.word_chars
ui.find.whole_word_label_textThe text of the “Whole word” label. (Write-only) This is primarily used for localization.
view moduleSee buffer.