aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorGravatar mitchell <70453897+orbitalquark@users.noreply.github.com>2021-04-11 09:34:17 -0400
committerGravatar mitchell <70453897+orbitalquark@users.noreply.github.com>2021-04-11 09:34:17 -0400
commitde3a745e1af2e441de868c2aa4849102d376acb5 (patch)
treec2d7767600dc519b2613ddecaf7e53fb5e8867a2 /docs
parent03fab17277fee7387fd93a9c2774b1ebf3f80fe4 (diff)
Initial pass reformatting all code.
Use clang-format, LuaFormatter, and 100 character limit on lines.
Diffstat (limited to 'docs')
-rw-r--r--docs/api.md4967
-rw-r--r--docs/book.md24
-rw-r--r--docs/changelog.md1004
-rw-r--r--docs/faq.md150
-rw-r--r--docs/index.html220
-rw-r--r--docs/manual.md2294
-rw-r--r--docs/thanks.md21
7 files changed, 3848 insertions, 4832 deletions
diff --git a/docs/api.md b/docs/api.md
index 4da386dd..c9d0edb7 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -88,13 +88,12 @@ The Textadept release version string.
<a id="_USERHOME"></a>
#### `_USERHOME` (string)
-The path to the user's *~/.textadept/* directory, where all preferences and
- user-data is stored.
- On Windows machines *~/* is the value of the "USERHOME" environment
- variable (typically *C:\Users\username\\* or
- *C:\Documents and Settings\username\\*). On Linux, BSD, and macOS
- machines *~/* is the value of "$HOME" (typically */home/username/* and
- */Users/username/* respectively).
+The path to the user's *~/.textadept/* directory, where all preferences and user-data
+ is stored.
+ On Windows machines *~/* is the value of the "USERHOME" environment variable (typically
+ *C:\Users\username\\* or *C:\Documents and Settings\username\\*). On Linux, BSD, and macOS
+ machines *~/* is the value of "$HOME" (typically */home/username/* and */Users/username/*
+ respectively).
### Functions defined by `_G`
@@ -102,8 +101,7 @@ The path to the user's *~/.textadept/* directory, where all preferences and
<a id="quit"></a>
#### `quit`()
-Emits a `QUIT` event, and unless any handler returns `false`, quits
-Textadept.
+Emits a `QUIT` event, and unless any handler returns `false`, quits Textadept.
See also:
@@ -113,20 +111,19 @@ See also:
#### `reset`()
Resets the Lua State by reloading all initialization scripts.
-Language modules for opened files are NOT reloaded. Re-opening the files that
-use them will reload those modules instead.
-This function is useful for modifying user scripts (such as
-*~/.textadept/init.lua* and *~/.textadept/modules/textadept/keys.lua*) on
-the fly without having to restart Textadept. `arg` is set to `nil` when
-reinitializing the Lua State. Any scripts that need to differentiate between
-startup and reset can test `arg`.
+Language modules for opened files are NOT reloaded. Re-opening the files that use them will
+reload those modules instead.
+This function is useful for modifying user scripts (such as *~/.textadept/init.lua* and
+*~/.textadept/modules/textadept/keys.lua*) on the fly without having to restart Textadept. `arg`
+is set to `nil` when reinitializing the Lua State. Any scripts that need to differentiate
+between startup and reset can test `arg`.
<a id="timeout"></a>
#### `timeout`(*interval, f, ...*)
Calls function *f* with the given arguments after *interval* seconds.
-If *f* returns `true`, calls *f* repeatedly every *interval* seconds as long
-as *f* returns `true`. A `nil` or `false` return value stops repetition.
+If *f* returns `true`, calls *f* repeatedly every *interval* seconds as long as *f* returns
+`true`. A `nil` or `false` return value stops repetition.
Parameters:
@@ -141,8 +138,7 @@ Parameters:
#### `_BUFFERS`
Table of all open buffers in Textadept.
-Numeric keys have buffer values and buffer keys have their associated numeric
-keys.
+Numeric keys have buffer values and buffer keys have their associated numeric keys.
Usage:
@@ -157,8 +153,7 @@ See also:
#### `_VIEWS`
Table of all views in Textadept.
-Numeric keys have view values and view keys have their associated numeric
-keys.
+Numeric keys have view values and view keys have their associated numeric keys.
Usage:
@@ -194,10 +189,9 @@ The current [view](#view).
---
Map of all messages used by Textadept to their localized form.
-If the table does not contain the localized version of a given message, it
-returns a string that starts with "No Localization:" via a metamethod.
-Note: the terminal version ignores any "_" mnemonics the GUI version would
-use.
+If the table does not contain the localized version of a given message, it returns a string
+that starts with "No Localization:" via a metamethod.
+Note: the terminal version ignores any "_" mnemonics the GUI version would use.
---
<a id="_M"></a>
@@ -206,14 +200,13 @@ use.
A table of loaded Textadept language modules.
-Language modules are a special kind of module that Textadept automatically
-loads when editing source code in a particular programming language. The only
-thing "special" about them is they are named after a lexer. Otherwise they
-are plain Lua modules. The *~/.textadept/modules/* directory houses language
-modules (along with other modules).
+Language modules are a special kind of module that Textadept automatically loads when editing
+source code in a particular programming language. The only thing "special" about them is they
+are named after a lexer. Otherwise they are plain Lua modules. The *~/.textadept/modules/*
+directory houses language modules (along with other modules).
-A language module is designed to provide extra functionality for a single
-programming language. Some examples of what language modules can do:
+A language module is designed to provide extra functionality for a single programming
+language. Some examples of what language modules can do:
* Specify block comment syntax for lines of code
* Define compile and run commands for source files
@@ -227,31 +220,27 @@ Examples of these features are described in the sections below.
### Block Comment
-Many languages have different syntaxes for single line comments and
-multi-line comments in source code. Textadept's block comment feature only
-uses one of those syntaxes for a given language. If you prefer the other
-syntax, or if Textadept does not support block comments for a particular
-language, modify the [`textadept.editing.comment_string`](#textadept.editing.comment_string) table. For
-example:
+Many languages have different syntaxes for single line comments and multi-line comments in
+source code. Textadept's block comment feature only uses one of those syntaxes for a given
+language. If you prefer the other syntax, or if Textadept does not support block comments
+for a particular language, modify the [`textadept.editing.comment_string`](#textadept.editing.comment_string) table. For example:
textadept.editing.comment_string.ansi_c = '//' -- change from /* ... */
### Compile and Run
-Textadept knows most of the commands that compile and/or run code in source
-files. However, it does not know all of them, and the ones that it does know
-may not be completely accurate in all cases. Compile and run commands are
-read from the [`textadept.run.compile_commands`](#textadept.run.compile_commands) and
-[`textadept.run.run_commands`](#textadept.run.run_commands) tables using the appropriate lexer name key,
-and thus can be defined or modified. For Lua, it would look like:
+Textadept knows most of the commands that compile and/or run code in source files. However,
+it does not know all of them, and the ones that it does know may not be completely accurate
+in all cases. Compile and run commands are read from the [`textadept.run.compile_commands`](#textadept.run.compile_commands)
+and [`textadept.run.run_commands`](#textadept.run.run_commands) tables using the appropriate lexer name key, and thus
+can be defined or modified. For Lua, it would look like:
textadept.run.compile_commands.lua = 'luac "%f"'
textadept.run.run_commands.lua = 'lua "%f"'
-Double-clicking on compile or runtime errors jumps to the error's location.
-If Textadept does not recognize your language's errors properly, add an error
-pattern to [`textadept.run.error_patterns`](#textadept.run.error_patterns). The Lua error pattern looks
-like:
+Double-clicking on compile or runtime errors jumps to the error's location. If
+Textadept does not recognize your language's errors properly, add an error pattern to
+[`textadept.run.error_patterns`](#textadept.run.error_patterns). The Lua error pattern looks like:
local patterns = textadept.run.error_patterns
if not patterns.lua then patterns.lua = {} end
@@ -259,31 +248,30 @@ like:
### Buffer Properties
-By default, Textadept uses 2 spaces for indentation. Some languages have
-different indentation guidelines, however. As described in the manual, use
-`events.LEXER_LOADED` to change this and any other language-specific editor
-properties. For example:
+By default, Textadept uses 2 spaces for indentation. Some languages have different indentation
+guidelines, however. As described in the manual, use `events.LEXER_LOADED` to change this
+and any other language-specific editor properties. For example:
events.connect(events.LEXER_LOADED, function(name)
if name ~= 'python' then return end
buffer.tab_width = 4
buffer.use_tabs = false
view.view_ws = view.WS_VISIBLEALWAYS
- end
+ end)
### Autocompletion and Documentation
Textadept has the capability to autocomplete symbols for programming
languages and display API documentation. In order for these to work for a
-given language, an [autocompleter](#textadept.editing.autocompleters) and
-[API file(s)](#textadept.editing.api_files) must exist. All of Textadept's
-included language modules have examples of autocompleters and API
-documentation, as well as most of its officially supported language modules.
+given language, an [autocompleter](#textadept.editing.autocompleters) and [API
+file(s)](#textadept.editing.api_files) must exist. All of Textadept's included language
+modules have examples of autocompleters and API documentation, as well as most of its
+officially supported language modules.
### Snippets
-[Snippets](#textadept.snippets) for common language constructs are useful.
-Some snippets for common Lua control structures look like this:
+[Snippets](#textadept.snippets) for common language constructs are useful. Some snippets
+for common Lua control structures look like this:
snippets.lua = {
f = "function %1(name)(%2(args))\n\t%0\nend",
@@ -294,10 +282,10 @@ Some snippets for common Lua control structures look like this:
### Commands
-Additional editing features for the language can be useful. For example, a
-C++ module might have a feature to add a ';' to the end of the current line
-and insert a new line. This command could be bound to the `Shift+Enter` (`⇧↩`
-on macOS | `S-Enter` in the terminal version) key for easy access:
+Additional editing features for the language can be useful. For example, a C++ module might
+have a feature to add a ';' to the end of the current line and insert a new line. This command
+could be bound to the `Shift+Enter` (`⇧↩` on macOS | `S-Enter` in the terminal version)
+key for easy access:
keys.cpp['shift+\n'] = function()
buffer:line_end()
@@ -305,12 +293,11 @@ on macOS | `S-Enter` in the terminal version) key for easy access:
buffer:new_line()
end
-When defining key bindings for other commands, you may make use of a `Ctrl+L`
-(`⌘L` on macOS | `M-L` in the terminal version) keychain. Traditionally this
-prefix has been reserved for use by language modules (although neither
-Textadept nor its modules utilize it at the moment). Users may define this
-keychain for new or existing modules and it will not conflict with any
-default key bindings. For example:
+When defining key bindings for other commands, you may make use of a `Ctrl+L` (`⌘L` on
+macOS | `M-L` in the terminal version) keychain. Traditionally this prefix has been reserved
+for use by language modules (although neither Textadept nor its modules utilize it at the
+moment). Users may define this keychain for new or existing modules and it will not conflict
+with any default key bindings. For example:
keys.lua[CURSES and 'meta+l' or OSX and 'cmd+l' or 'ctrl+l'] = {
...
@@ -318,9 +305,8 @@ default key bindings. For example:
### Menus
-It may be useful to add language-specific menu options to the top-level menu
-and/or right-click context menu in order to access module features without
-using key bindings. For example:
+It may be useful to add language-specific menu options to the top-level menu and/or right-click
+context menu in order to access module features without using key bindings. For example:
local lua_menu = {
title = 'Lua',
@@ -353,8 +339,8 @@ Whether or not to include snippets in autocompletion lists.
<a id="_M.ansi_c.tags"></a>
#### `_M.ansi_c.tags`
-List of ctags files to use for autocompletion in addition to the current
-project's top-level *tags* file or the current directory's *tags* file.
+List of ctags files to use for autocompletion in addition to the current project's top-level
+*tags* file or the current directory's *tags* file.
---
<a id="_M.lua"></a>
@@ -379,8 +365,8 @@ Whether or not to include snippets in autocompletion lists.
#### `_M.lua.expr_types`
Map of expression patterns to their types.
-Used for type-hinting when showing autocompletions for variables.
-Expressions are expected to match after the '=' sign of a statement.
+Used for type-hinting when showing autocompletions for variables. Expressions are expected
+to match after the '=' sign of a statement.
Usage:
@@ -389,12 +375,11 @@ Usage:
<a id="_M.lua.tags"></a>
#### `_M.lua.tags`
-List of "fake" ctags files (or functions that return such files) to use for
-autocompletion.
-The kind 'm' is recognized as a module, 'f' as a function, 't' as a table and
-'F' as a module or table field.
-The *modules/lua/tadoc.lua* script can generate *tags* and
-[*api*](#textadept.editing.api_files) files for Lua modules via LuaDoc.
+List of "fake" ctags files (or functions that return such files) to use for autocompletion.
+The kind 'm' is recognized as a module, 'f' as a function, 't' as a table and 'F' as a module
+or table field.
+The *modules/lua/tadoc.lua* script can generate *tags* and [*api*](#textadept.editing.api_files)
+files for Lua modules via LuaDoc.
---
<a id="_SCINTILLA"></a>
@@ -402,18 +387,17 @@ The *modules/lua/tadoc.lua* script can generate *tags* and
---
Scintilla constants, functions, and properties.
-Do not modify anything in this module. Doing so will have unpredictable
-consequences.
+Do not modify anything in this module. Doing so will have unpredictable consequences.
### Functions defined by `_SCINTILLA`
<a id="_SCINTILLA.next_image_type"></a>
#### `_SCINTILLA.next_image_type`()
-Returns a unique image type identier number for use with
-`view.register_image()` and `view.register_rgba_image()`.
-Use this function for custom image types in order to prevent clashes with
-identifiers of other custom image types.
+Returns a unique image type identier number for use with `view.register_image()` and
+`view.register_rgba_image()`.
+Use this function for custom image types in order to prevent clashes with identifiers of
+other custom image types.
Usage:
@@ -428,8 +412,8 @@ See also:
#### `_SCINTILLA.next_indic_number`()
Returns a unique indicator number for use with custom indicators.
-Use this function for custom indicators in order to prevent clashes with
-identifiers of other custom indicators.
+Use this function for custom indicators in order to prevent clashes with identifiers of
+other custom indicators.
Usage:
@@ -443,8 +427,8 @@ See also:
#### `_SCINTILLA.next_marker_number`()
Returns a unique marker number for use with `view.marker_define()`.
-Use this function for custom markers in order to prevent clashes with
-identifiers of other custom markers.
+Use this function for custom markers in order to prevent clashes with identifiers of other
+custom markers.
Usage:
@@ -457,10 +441,9 @@ See also:
<a id="_SCINTILLA.next_user_list_type"></a>
#### `_SCINTILLA.next_user_list_type`()
-Returns a unique user list identier number for use with
-`buffer.user_list_show()`.
-Use this function for custom user lists in order to prevent clashes with
-list identifiers of other custom user lists.
+Returns a unique user list identier number for use with `buffer.user_list_show()`.
+Use this function for custom user lists in order to prevent clashes with list identifiers
+of other custom user lists.
Usage:
@@ -490,8 +473,8 @@ Map of Scintilla event IDs to tables of event names and event parameters.
<a id="_SCINTILLA.functions"></a>
#### `_SCINTILLA.functions`
-Map of Scintilla function names to tables containing their IDs, return types,
-wParam types, and lParam types. Types are as follows:
+Map of Scintilla function names to tables containing their IDs, return types, wParam types,
+and lParam types. Types are as follows:
+ `0`: Void.
+ `1`: Integer.
@@ -506,8 +489,8 @@ wParam types, and lParam types. Types are as follows:
<a id="_SCINTILLA.properties"></a>
#### `_SCINTILLA.properties`
-Map of Scintilla property names to table values containing their "get"
-function IDs, "set" function IDs, return types, and wParam types.
+Map of Scintilla property names to table values containing their "get" function IDs, "set"
+function IDs, return types, and wParam types.
The wParam type will be non-zero if the property is indexable.
Types are the same as in the `functions` table.
@@ -535,20 +518,17 @@ Emitted when no command line arguments are passed to Textadept on startup.
<a id="args.register"></a>
#### `args.register`(*short, long, narg, f, description*)
-Registers a command line option with short and long versions *short* and
-*long*, respectively. *narg* is the number of arguments the option accepts,
-*f* is the function called when the option is set, and *description* is
-the option's description when displaying help.
+Registers a command line option with short and long versions *short* and *long*, respectively.
+*narg* is the number of arguments the option accepts, *f* is the function called when the
+option is set, and *description* is the option's description when displaying help.
Parameters:
* *`short`*: The string short version of the option.
* *`long`*: The string long version of the option.
* *`narg`*: The number of expected parameters for the option.
-* *`f`*: The Lua function to run when the option is set. It is passed *narg*
- string arguments.
-* *`description`*: The string description of the option for command line
- help.
+* *`f`*: The Lua function to run when the option is set. It is passed *narg* string arguments.
+* *`description`*: The string description of the option for command line help.
---
@@ -563,35 +543,32 @@ Extends `_G` with formatted assertions and function argument type checks.
<a id="_G.assert"></a>
#### `_G.assert`(*v, message, ...*)
-Asserts that value *v* is not `false` or `nil` and returns *v*, or calls
-`error()` with *message* as the error message, defaulting to "assertion
-failed!". If *message* is a format string, the remaining arguments are passed
-to `string.format()` and the resulting string becomes the error message.
+Asserts that value *v* is not `false` or `nil` and returns *v*, or calls `error()` with
+*message* as the error message, defaulting to "assertion failed!".
+If *message* is a format string, the remaining arguments are passed to `string.format()`
+and the resulting string becomes the error message.
Parameters:
* *`v`*: Value to assert.
-* *`message`*: Optional error message to show on error. The default value is
- "assertion failed!".
-* *`...`*: If *message* is a format string, these arguments are passed to
- `string.format()`.
+* *`message`*: Optional error message to show on error. The default value is "assertion failed!".
+* *`...`*: If *message* is a format string, these arguments are passed to `string.format()`.
<a id="_G.assert_type"></a>
#### `_G.assert_type`(*v, expected\_type, narg*)
-Asserts that value *v* has type string *expected_type* and returns *v*, or
-calls `error()` with an error message that implicates function argument
-number *narg*.
-This is intended to be used with API function arguments so users receive more
-helpful error messages.
+Asserts that value *v* has type string *expected_type* and returns *v*, or calls `error()`
+with an error message that implicates function argument number *narg*.
+This is intended to be used with API function arguments so users receive more helpful error
+messages.
Parameters:
* *`v`*: Value to assert the type of.
-* *`expected_type`*: String type to assert. It may be a non-letter-delimited
- list of type options.
-* *`narg`*: The positional argument number *v* is associated with. This is
- not required to be a number.
+* *`expected_type`*: String type to assert. It may be a non-letter-delimited list of type
+ options.
+* *`narg`*: The positional argument number *v* is associated with. This is not required to
+ be a number.
Usage:
@@ -606,17 +583,15 @@ Usage:
A Textadept buffer object.
Constants are documented in the fields they apply to.
-While you can work with individual buffer instances, it is really only useful
-to work with the global one.
-Many of these functions and fields are derived from buffer-specific
-functionality of the Scintilla editing component, and additional information
-can be found on the
-[Scintilla website](https://scintilla.org/ScintillaDoc.html).
-Note that with regard to Scintilla-specific functionality, this API is a
-_suggestion_, not a hard requirement. All of that functionality also exists
-in [`view`](#view), even if undocumented.
-Any buffer fields set on startup (e.g. in *~/.textadept/init.lua*) will be
-the default, initial values for all buffers.
+While you can work with individual buffer instances, it is really only useful to work with
+the global one.
+Many of these functions and fields are derived from buffer-specific functionality of the
+Scintilla editing component, and additional information can be found on the [Scintilla
+website](https://scintilla.org/ScintillaDoc.html). Note that with regard to Scintilla-specific
+functionality, this API is a _suggestion_, not a hard requirement. All of that functionality
+also exists in [`view`](#view), even if undocumented.
+Any buffer fields set on startup (e.g. in *~/.textadept/init.lua*) will be the default,
+initial values for all buffers.
### Fields defined by `buffer`
@@ -892,8 +867,8 @@ Table of the number of annotation text lines per line number.
#### `buffer.annotation_style` (table)
Table of style numbers for annotation text per line number.
- Only some style attributes are active in annotations: font,
- size/size_fractional, bold/weight, italics, fore, back, and character_set.
+ Only some style attributes are active in annotations: font, size/size_fractional, bold/weight,
+ italics, fore, back, and character_set.
<a id="buffer.annotation_text"></a>
#### `buffer.annotation_text` (table)
@@ -903,15 +878,14 @@ Table of annotation text per line number.
<a id="buffer.auto_c_auto_hide"></a>
#### `buffer.auto_c_auto_hide` (bool)
-Automatically cancel an autocompletion or user list when no entries match
- typed text.
+Automatically cancel an autocompletion or user list when no entries match typed text.
The default value is `true`.
<a id="buffer.auto_c_cancel_at_start"></a>
#### `buffer.auto_c_cancel_at_start` (bool)
-Cancel an autocompletion list when backspacing to a position before where
- autocompletion started (instead of before the word being completed).
+Cancel an autocompletion list when backspacing to a position before where autocompletion
+ started (instead of before the word being completed).
This option has no effect for a user list.
The default value is `true`.
@@ -954,8 +928,8 @@ Delete any word characters immediately to the right of autocompleted text.
<a id="buffer.auto_c_fill_ups"></a>
#### `buffer.auto_c_fill_ups` (string, Write-only)
-The set of characters that choose the currently selected item in an
- autocompletion or user list when the user types one of them.
+The set of characters that choose the currently selected item in an autocompletion or user
+ list when the user types one of them.
The default value is `''`.
<a id="buffer.auto_c_ignore_case"></a>
@@ -982,8 +956,7 @@ The multiple selection autocomplete mode.
The order setting for autocompletion and user lists.
* `buffer.ORDER_PRESORTED`
- Lists passed to [`buffer.auto_c_show()`](#buffer.auto_c_show) are in sorted, alphabetical
- order.
+ Lists passed to [`buffer.auto_c_show()`](#buffer.auto_c_show) are in sorted, alphabetical order.
* `buffer.ORDER_PERFORMSORT`
Sort autocompletion lists passed to [`buffer.auto_c_show()`](#buffer.auto_c_show).
* `buffer.ORDER_CUSTOM`
@@ -994,19 +967,16 @@ The order setting for autocompletion and user lists.
<a id="buffer.auto_c_separator"></a>
#### `buffer.auto_c_separator` (number)
-The byte value of the character that separates autocompletion and user list
- list items.
+The byte value of the character that separates autocompletion and user list list items.
The default value is `32` (' ').
<a id="buffer.auto_c_type_separator"></a>
#### `buffer.auto_c_type_separator` (number)
-The character byte that separates autocompletion and user list items and
- their image types.
- Autocompletion and user list items can display both an image and text.
- Register images and their types using [`view.register_image()`](#view.register_image) or
- [`view.register_rgba_image()`](#view.register_rgba_image) before appending image types to list
- items after type separator characters.
+The character byte that separates autocompletion and user list items and their image types.
+ Autocompletion and user list items can display both an image and text. Register images
+ and their types using [`view.register_image()`](#view.register_image) or [`view.register_rgba_image()`](#view.register_rgba_image)
+ before appending image types to list items after type separator characters.
The default value is 63 ('?').
<a id="buffer.back_space_un_indents"></a>
@@ -1023,11 +993,10 @@ The 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.
+ 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.
+ Use the position the caret had on the previous line, but prior to any inserted indentation.
The default value is `buffer.CARETSTICKY_OFF`.
@@ -1056,15 +1025,14 @@ The string encoding of the file, or `nil` for binary files.
<a id="buffer.end_styled"></a>
#### `buffer.end_styled` (number, Read-only)
-The current styling position or the last correctly styled character's
- position.
+The current styling position or the last correctly styled character's position.
<a id="buffer.eol_annotation_style"></a>
#### `buffer.eol_annotation_style` (table)
Table of style numbers for EOL annotation text per line number.
- Only some style attributes are active in annotations: font,
- size/size_fractional, bold/weight, italics, fore, back, and character_set.
+ Only some style attributes are active in annotations: font, size/size_fractional, bold/weight,
+ italics, fore, back, and character_set.
<a id="buffer.eol_annotation_text"></a>
#### `buffer.eol_annotation_text` (table)
@@ -1074,9 +1042,9 @@ Table of EOL annotation text per line number.
<a id="buffer.eol_mode"></a>
#### `buffer.eol_mode` (number)
-The current end of line mode. Changing the current mode does not convert
- any of the buffer's existing end of line characters.
- Use [`buffer.convert_eols()`](#buffer.convert_eols) to do so.
+The current end of line mode.
+ Changing the current mode does not convert any of the buffer's existing end of line
+ characters. Use [`buffer.convert_eols()`](#buffer.convert_eols) to do so.
* `buffer.EOL_CRLF`
Carriage return with line feed ("\r\n").
@@ -1085,8 +1053,7 @@ The current end of line mode. Changing the current mode does not convert
* `buffer.EOL_LF`
Line feed ("\n").
- The default value is `buffer.EOL_CRLF` on Windows platforms,
- `buffer.EOL_LF` otherwise.
+ The default value is `buffer.EOL_CRLF` on Windows platforms, `buffer.EOL_LF` otherwise.
<a id="buffer.filename"></a>
#### `buffer.filename` (string)
@@ -1097,8 +1064,7 @@ The absolute file path associated with the buffer.
#### `buffer.fold_level` (table)
Table of fold level bit-masks per line number.
- Fold level masks comprise of an integer level combined with any of the
- following bit flags:
+ Fold level masks comprise of an integer level combined with any of the following bit flags:
* `buffer.FOLDLEVELBASE`
The initial fold level.
@@ -1122,9 +1088,8 @@ The number of spaces in one level of indentation.
<a id="buffer.indicator_current"></a>
#### `buffer.indicator_current` (number)
-The indicator number in the range of `1` to `32` used by
- [`buffer.indicator_fill_range()`](#buffer.indicator_fill_range) and
- [`buffer.indicator_clear_range()`](#buffer.indicator_clear_range).
+The indicator number in the range of `1` to `32` used by [`buffer.indicator_fill_range()`](#buffer.indicator_fill_range)
+ and [`buffer.indicator_clear_range()`](#buffer.indicator_clear_range).
<a id="buffer.length"></a>
#### `buffer.length` (number, Read-only)
@@ -1140,8 +1105,8 @@ The number of lines in the buffer.
<a id="buffer.line_end_position"></a>
#### `buffer.line_end_position` (table, Read-only)
-Table of positions at the ends of lines, but before any end of line
- characters, per line number.
+Table of positions at the ends of lines, but before any end of line characters, per
+ line number.
<a id="buffer.line_indent_position"></a>
#### `buffer.line_indent_position` (table, Read-only)
@@ -1163,8 +1128,8 @@ The number of the main or most recent selection.
#### `buffer.margin_style` (table)
Table of style numbers in the text margin per line number.
- Only some style attributes are active in text margins: font, size, bold,
- italics, fore, and back.
+ Only some style attributes are active in text margins: font, size, bold, italics, fore,
+ and back.
<a id="buffer.margin_text"></a>
#### `buffer.margin_text` (table)
@@ -1211,8 +1176,7 @@ Enable overtype mode, where typed characters overwrite existing ones.
The string set of characters recognized as punctuation characters.
Set this only after setting [`buffer.word_chars`](#buffer.word_chars).
- The default value is a string that contains all non-word and non-whitespace
- characters.
+ The default value is a string that contains all non-word and non-whitespace characters.
<a id="buffer.read_only"></a>
#### `buffer.read_only` (bool)
@@ -1250,8 +1214,7 @@ The bit-mask of search flags used by [`buffer.search_in_target()`](#buffer.searc
* `buffer.FIND_MATCHCASE`
Match search text case sensitively.
* `buffer.FIND_WORDSTART`
- Match search text only when the previous character is a non-word
- character.
+ Match search text only when the previous character is a non-word character.
* `buffer.FIND_REGEXP`
Interpret search text as a regular expression.
@@ -1285,60 +1248,57 @@ The selection mode.
* `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.
+ 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 this field is set
- again to the same value or until [`buffer.cancel()`](#buffer.cancel) is called.
+ When set, caret movement alters the selected text until this field is set again to the
+ same value or until [`buffer.cancel()`](#buffer.cancel) is called.
<a id="buffer.selection_n_anchor"></a>
#### `buffer.selection_n_anchor` (table)
-Table of positions at the beginning of existing selections numbered from
- `1`, the main selection.
+Table of positions at the beginning of existing selections numbered from `1`, the main
+ selection.
<a id="buffer.selection_n_anchor_virtual_space"></a>
#### `buffer.selection_n_anchor_virtual_space` (table)
-Table of positions at the beginning of virtual space selected in existing
- selections numbered from `1`, the main selection.
+Table of positions at the beginning of virtual space selected in existing selections
+ numbered from `1`, the main selection.
<a id="buffer.selection_n_caret"></a>
#### `buffer.selection_n_caret` (table)
-Table of positions at the end of existing selections numbered from `1`,
- the main selection.
+Table of positions at the end of existing selections numbered from `1`, the main selection.
<a id="buffer.selection_n_caret_virtual_space"></a>
#### `buffer.selection_n_caret_virtual_space` (table)
-Table of positions at the end of virtual space selected in existing
- selections numbered from `1`, the main selection.
+Table of positions at the end of virtual space selected in existing selections numbered from
+ `1`, the main selection.
<a id="buffer.selection_n_end"></a>
#### `buffer.selection_n_end` (table)
-Table of positions at the end of existing selections numbered from `1`,
- the main selection.
+Table of positions at the end of existing selections numbered from `1`, the main selection.
<a id="buffer.selection_n_end_virtual_space"></a>
#### `buffer.selection_n_end_virtual_space` (number, Read-only)
-Table of positions at the end of virtual space selected in existing
- selections numbered from `1`, the main selection.
+Table of positions at the end of virtual space selected in existing selections numbered from
+ `1`, the main selection.
<a id="buffer.selection_n_start"></a>
#### `buffer.selection_n_start` (table)
-Table of positions at the beginning of existing selections numbered from
- `1`, the main selection.
+Table of positions at the beginning of existing selections numbered from `1`, the main
+ selection.
<a id="buffer.selection_n_start_virtual_space"></a>
#### `buffer.selection_n_start_virtual_space` (number, Read-only)
-Table of positions at the beginning of virtual space selected in existing
- selections numbered from `1`, the main selection.
+Table of positions at the beginning of virtual space selected in existing selections
+ numbered from `1`, the main selection.
<a id="buffer.selection_start"></a>
#### `buffer.selection_start` (number)
@@ -1388,9 +1348,8 @@ The position of the end of the target range.
#### `buffer.target_end_virtual_space` (number)
The position of the end of virtual space in the target range.
- This is set to `1` when [`buffer.target_start`](#buffer.target_start) or
- [`buffer.target_end`](#buffer.target_end) is set, or when [`buffer.set_target_range()`](#buffer.set_target_range) is
- called.
+ This is set to `1` when [`buffer.target_start`](#buffer.target_start) or [`buffer.target_end`](#buffer.target_end) is set,
+ or when [`buffer.set_target_range()`](#buffer.set_target_range) is called.
<a id="buffer.target_start"></a>
#### `buffer.target_start` (number)
@@ -1402,9 +1361,8 @@ The position of the beginning of the target range.
#### `buffer.target_start_virtual_space` (number)
The position of the beginning of virtual space in the target range.
- This is set to `1` when [`buffer.target_start`](#buffer.target_start) or
- [`buffer.target_end`](#buffer.target_end) is set, or when [`buffer.set_target_range()`](#buffer.set_target_range) is
- called.
+ This is set to `1` when [`buffer.target_start`](#buffer.target_start) or [`buffer.target_end`](#buffer.target_end) is set,
+ or when [`buffer.set_target_range()`](#buffer.set_target_range) is called.
<a id="buffer.target_text"></a>
#### `buffer.target_text` (string, Read-only)
@@ -1419,8 +1377,8 @@ The number of bytes in the buffer.
<a id="buffer.use_tabs"></a>
#### `buffer.use_tabs` (bool)
-Use tabs instead of spaces in indentation. Changing the current setting
- does not convert any of the buffer's existing indentation. Use
+Use tabs instead of spaces in indentation.
+ Changing the current setting does not convert any of the buffer's existing indentation. Use
[`textadept.editing.convert_indentation()`](#textadept.editing.convert_indentation) to do so.
The default value is `true`.
@@ -1436,13 +1394,11 @@ The virtual space mode.
* `buffer.VS_USERACCESSIBLE`
Enable virtual space.
* `buffer.VS_NOWRAPLINESTART`
- Prevent the caret from wrapping to the previous line via
- `buffer:char_left()` and `buffer:char_left_extend()`. This option is not
- restricted to virtual space and should be added to any of the above
- options.
+ Prevent the caret from wrapping to the previous line via `buffer:char_left()` and
+ `buffer:char_left_extend()`. This option is not restricted to virtual space and should
+ be added to any of the above options.
- When virtual space is enabled, the caret may move into the space past end
- of line characters.
+ When virtual space is enabled, the caret may move into the space past end of line characters.
The default value is `buffer.VS_NONE`.
<a id="buffer.whitespace_chars"></a>
@@ -1450,15 +1406,15 @@ The virtual space mode.
The string set of characters recognized as whitespace characters.
Set this only after setting [`buffer.word_chars`](#buffer.word_chars).
- The default value is a string that contains all non-newline characters less
- than ASCII value 33.
+ The default value is a string that contains all non-newline characters less than ASCII
+ value 33.
<a id="buffer.word_chars"></a>
#### `buffer.word_chars` (string)
The string set of characters recognized as word characters.
- The default value is a string that contains alphanumeric characters, an
- underscore, and all characters greater than ASCII value 127.
+ The default value is a string that contains alphanumeric characters, an underscore, and
+ all characters greater than ASCII value 127.
### Functions defined by `buffer`
@@ -1466,18 +1422,16 @@ The string set of characters recognized as word characters.
<a id="buffer.add_selection"></a>
#### `buffer.add_selection`(*buffer, end\_pos, start\_pos*)
-Selects the range of text between positions *start_pos* to *end_pos* as the
-main selection, retaining all other selections as additional selections.
-Since an empty selection (i.e. the current position) still counts as a
-selection, use `buffer.set_selection()` first when setting a list of
-selections.
+Selects the range of text between positions *start_pos* to *end_pos* as the main selection,
+retaining all other selections as additional selections.
+Since an empty selection (i.e. the current position) still counts as a selection, use
+`buffer.set_selection()` first when setting a list of selections.
Parameters:
* *`buffer`*: A buffer.
* *`end_pos`*: The caret position of the range of text to select in *buffer*.
-* *`start_pos`*: The anchor position of the range of text to select in
- *buffer*.
+* *`start_pos`*: The anchor position of the range of text to select in *buffer*.
See also:
@@ -1486,8 +1440,8 @@ See also:
<a id="buffer.add_text"></a>
#### `buffer.add_text`(*buffer, text*)
-Adds string *text* to the buffer at the caret position and moves the caret to
-the end of the added text without scrolling it into view.
+Adds string *text* to the buffer at the caret position and moves the caret to the end of
+the added text without scrolling it into view.
Parameters:
@@ -1506,8 +1460,8 @@ Parameters:
<a id="buffer.append_text"></a>
#### `buffer.append_text`(*buffer, text*)
-Appends string *text* to the end of the buffer without modifying any existing
-selections or scrolling the text into view.
+Appends string *text* to the end of the buffer without modifying any existing selections or
+scrolling the text into view.
Parameters:
@@ -1548,8 +1502,7 @@ Parameters:
<a id="buffer.auto_c_pos_start"></a>
#### `buffer.auto_c_pos_start`(*buffer*)
-Returns the position where autocompletion started or where a user list was
-shown.
+Returns the position where autocompletion started or where a user list was shown.
Parameters:
@@ -1562,8 +1515,8 @@ Return:
<a id="buffer.auto_c_select"></a>
#### `buffer.auto_c_select`(*buffer, prefix*)
-Selects the first item that starts with string *prefix* in an autocompletion
-or user list, using the case sensitivity setting `buffer.auto_c_ignore_case`.
+Selects the first item that starts with string *prefix* in an autocompletion or user list,
+using the case sensitivity setting `buffer.auto_c_ignore_case`.
Parameters:
@@ -1573,20 +1526,17 @@ Parameters:
<a id="buffer.auto_c_show"></a>
#### `buffer.auto_c_show`(*buffer, len\_entered, items*)
-Displays an autocompletion list constructed from string *items* (whose items
-are delimited by `buffer.auto_c_separator` characters) using *len_entered*
-number of characters behind the caret as the prefix of the word to be
-autocompleted.
-The sorted order of *items* (`buffer.auto_c_order`) must have already been
-defined.
+Displays an autocompletion list constructed from string *items* (whose items are delimited by
+`buffer.auto_c_separator` characters) using *len_entered* number of characters behind the
+caret as the prefix of the word to be autocompleted.
+The sorted order of *items* (`buffer.auto_c_order`) must have already been defined.
Parameters:
* *`buffer`*: A buffer.
-* *`len_entered`*: The number of characters before the caret used to provide
- the context.
-* *`items`*: The sorted string of words to show, separated by
- `buffer.auto_c_separator` characters (initially spaces).
+* *`len_entered`*: The number of characters before the caret used to provide the context.
+* *`items`*: The sorted string of words to show, separated by `buffer.auto_c_separator`
+ characters (initially spaces).
See also:
@@ -1596,15 +1546,15 @@ See also:
<a id="buffer.auto_c_stops"></a>
#### `buffer.auto_c_stops`(*buffer, chars*)
-Allows the user to type any character in string set *chars* in order to
-cancel an autocompletion or user list.
+Allows the user to type any character in string set *chars* in order to cancel an autocompletion
+or user list.
The default set is empty.
Parameters:
* *`buffer`*: A buffer.
-* *`chars`*: The string of characters that cancel autocompletion. This string
- is empty by default.
+* *`chars`*: The string of characters that cancel autocompletion. This string is empty
+ by default.
<a id="buffer.back_tab"></a>
#### `buffer.back_tab`(*buffer*)
@@ -1628,10 +1578,10 @@ Parameters:
<a id="buffer.brace_match"></a>
#### `buffer.brace_match`(*buffer, pos, max\_re\_style*)
-Returns the position of the matching brace for the brace character at
-position *pos*, taking nested braces into account, or `-1`.
-The brace characters recognized are '(', ')', '[', ']', '{', '}', '<', and
-'>' and must have the same style.
+Returns the position of the matching brace for the brace character at position *pos*, taking
+nested braces into account, or `-1`.
+The brace characters recognized are '(', ')', '[', ']', '{', '}', '<', and '>' and must have
+the same style.
Parameters:
@@ -1672,8 +1622,7 @@ Return:
<a id="buffer.cancel"></a>
#### `buffer.cancel`(*buffer*)
-Cancels the active selection mode, autocompletion or user list, call tip,
-etc.
+Cancels the active selection mode, autocompletion or user list, call tip, etc.
Parameters:
@@ -1691,8 +1640,7 @@ Parameters:
<a id="buffer.char_left_extend"></a>
#### `buffer.char_left_extend`(*buffer*)
-Moves the caret left one character, extending the selected text to the new
-position.
+Moves the caret left one character, extending the selected text to the new position.
Parameters:
@@ -1701,8 +1649,7 @@ Parameters:
<a id="buffer.char_left_rect_extend"></a>
#### `buffer.char_left_rect_extend`(*buffer*)
-Moves the caret left one character, extending the rectangular selection to
-the new position.
+Moves the caret left one character, extending the rectangular selection to the new position.
Parameters:
@@ -1720,8 +1667,7 @@ Parameters:
<a id="buffer.char_right_extend"></a>
#### `buffer.char_right_extend`(*buffer*)
-Moves the caret right one character, extending the selected text to the new
-position.
+Moves the caret right one character, extending the selected text to the new position.
Parameters:
@@ -1730,8 +1676,7 @@ Parameters:
<a id="buffer.char_right_rect_extend"></a>
#### `buffer.char_right_rect_extend`(*buffer*)
-Moves the caret right one character, extending the rectangular selection to
-the new position.
+Moves the caret right one character, extending the rectangular selection to the new position.
Parameters:
@@ -1740,8 +1685,8 @@ Parameters:
<a id="buffer.choose_caret_x"></a>
#### `buffer.choose_caret_x`(*buffer*)
-Identifies the current horizontal caret position as the caret's preferred
-horizontal position when moving between lines.
+Identifies the current horizontal caret position as the caret's preferred horizontal position
+when moving between lines.
Parameters:
@@ -1781,15 +1726,14 @@ Parameters:
<a id="buffer.close"></a>
#### `buffer.close`(*buffer, force*)
-Closes the buffer, prompting the user to continue if there are unsaved
-changes (unless *force* is `true`), and returns `true` if the buffer was
-closed.
+Closes the buffer, prompting the user to continue if there are unsaved changes (unless *force*
+is `true`), and returns `true` if the buffer was closed.
Parameters:
* *`buffer`*: A buffer.
-* *`force`*: Optional flag that discards unsaved changes without prompting
- the user. The default value is `false`.
+* *`force`*: Optional flag that discards unsaved changes without prompting the user. The
+ default value is `false`.
Return:
@@ -1798,17 +1742,16 @@ Return:
<a id="buffer.colorize"></a>
#### `buffer.colorize`(*buffer, start\_pos, end\_pos*)
-Instructs the lexer to style and mark fold points in the range of text
-between *start_pos* and *end_pos*.
+Instructs the lexer to style and mark fold points in the range of text between *start_pos*
+and *end_pos*.
If *end_pos* is `-1`, styles and marks to the end of the buffer.
Parameters:
* *`buffer`*: A buffer.
-* *`start_pos`*: The start position of the range of text in *buffer* to
- process.
-* *`end_pos`*: The end position of the range of text in *buffer* to process,
- or `-1` to process from *start_pos* to the end of *buffer*.
+* *`start_pos`*: The start position of the range of text in *buffer* to process.
+* *`end_pos`*: The end position of the range of text in *buffer* to process, or `-1` to
+ process from *start_pos* to the end of *buffer*.
<a id="buffer.convert_eols"></a>
#### `buffer.convert_eols`(*buffer, mode*)
@@ -1827,9 +1770,8 @@ Parameters:
#### `buffer.copy`(*buffer*)
Copies the selected text to the clipboard.
-Multiple selections are copied in order with no delimiters. Rectangular
-selections are copied from top to bottom with end of line characters. Virtual
-space is not copied.
+Multiple selections are copied in order with no delimiters. Rectangular selections are copied
+from top to bottom with end of line characters. Virtual space is not copied.
Parameters:
@@ -1838,8 +1780,7 @@ Parameters:
<a id="buffer.copy_range"></a>
#### `buffer.copy_range`(*buffer, start\_pos, end\_pos*)
-Copies to the clipboard the range of text between positions *start_pos* and
-*end_pos*.
+Copies to the clipboard the range of text between positions *start_pos* and *end_pos*.
Parameters:
@@ -1860,16 +1801,14 @@ Parameters:
<a id="buffer.count_characters"></a>
#### `buffer.count_characters`(*buffer, start\_pos, end\_pos*)
-Returns the number of whole characters (taking multi-byte characters into
-account) between positions *start_pos* and *end_pos*.
+Returns the number of whole characters (taking multi-byte characters into account) between
+positions *start_pos* and *end_pos*.
Parameters:
* *`buffer`*: A buffer.
-* *`start_pos`*: The start position of the range of text in *buffer* to start
- counting at.
-* *`end_pos`*: The end position of the range of text in *buffer* to stop
- counting at.
+* *`start_pos`*: The start position of the range of text in *buffer* to start counting at.
+* *`end_pos`*: The end position of the range of text in *buffer* to stop counting at.
Return:
@@ -1879,9 +1818,8 @@ Return:
#### `buffer.cut`(*buffer*)
Cuts the selected text to the clipboard.
-Multiple selections are copied in order with no delimiters. Rectangular
-selections are copied from top to bottom with end of line characters. Virtual
-space is not copied.
+Multiple selections are copied in order with no delimiters. Rectangular selections are copied
+from top to bottom with end of line characters. Virtual space is not copied.
Parameters:
@@ -1890,8 +1828,7 @@ Parameters:
<a id="buffer.del_line_left"></a>
#### `buffer.del_line_left`(*buffer*)
-Deletes the range of text from the caret to the beginning of the current
-line.
+Deletes the range of text from the caret to the beginning of the current line.
Parameters:
@@ -1909,8 +1846,7 @@ Parameters:
<a id="buffer.del_word_left"></a>
#### `buffer.del_word_left`(*buffer*)
-Deletes the word to the left of the caret, including any leading non-word
-characters.
+Deletes the word to the left of the caret, including any leading non-word characters.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -1920,8 +1856,7 @@ Parameters:
<a id="buffer.del_word_right"></a>
#### `buffer.del_word_right`(*buffer*)
-Deletes the word to the right of the caret, including any trailing non-word
-characters.
+Deletes the word to the right of the caret, including any trailing non-word characters.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -1931,8 +1866,7 @@ Parameters:
<a id="buffer.del_word_right_end"></a>
#### `buffer.del_word_right_end`(*buffer*)
-Deletes the word to the right of the caret, excluding any trailing non-word
-characters.
+Deletes the word to the right of the caret, excluding any trailing non-word characters.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -1943,8 +1877,7 @@ Parameters:
#### `buffer.delete`(*buffer*)
Deletes the buffer.
-**Do not call this function.** Call `buffer:close()` instead. Emits a
-`BUFFER_DELETED` event.
+**Do not call this function.** Call `buffer:close()` instead. Emits a `BUFFER_DELETED` event.
Parameters:
@@ -1967,8 +1900,8 @@ Parameters:
<a id="buffer.delete_back_not_line"></a>
#### `buffer.delete_back_not_line`(*buffer*)
-Deletes the character behind the caret unless either the caret is at the
-beginning of a line or text is selected.
+Deletes the character behind the caret unless either the caret is at the beginning of a line
+or text is selected.
If text is selected, deletes it.
Parameters:
@@ -1998,8 +1931,7 @@ Parameters:
<a id="buffer.document_end_extend"></a>
#### `buffer.document_end_extend`(*buffer*)
-Moves the caret to the end of the buffer, extending the selected text to the
-new position.
+Moves the caret to the end of the buffer, extending the selected text to the new position.
Parameters:
@@ -2017,8 +1949,7 @@ Parameters:
<a id="buffer.document_start_extend"></a>
#### `buffer.document_start_extend`(*buffer*)
-Moves the caret to the beginning of the buffer, extending the selected text
-to the new position.
+Moves the caret to the beginning of the buffer, extending the selected text to the new position.
Parameters:
@@ -2073,9 +2004,8 @@ Parameters:
<a id="buffer.find_column"></a>
#### `buffer.find_column`(*buffer, line, column*)
-Returns the position of column number *column* on line number *line* (taking
-tab and multi-byte characters into account), or the position at the end of
-line *line*.
+Returns the position of column number *column* on line number *line* (taking tab and multi-byte
+characters into account), or the position at the end of line *line*.
Parameters:
@@ -2099,8 +2029,8 @@ Return:
<a id="buffer.get_last_child"></a>
#### `buffer.get_last_child`(*buffer, line, level*)
-Returns the line number of the last line after line number *line* whose fold
-level is greater than *level*.
+Returns the line number of the last line after line number *line* whose fold level is greater
+than *level*.
If *level* is `-1`, returns the level of *line*.
Parameters:
@@ -2113,15 +2043,14 @@ Parameters:
#### `buffer.get_lexer`(*buffer, current*)
Returns the buffer's lexer name.
-If *current* is `true`, returns the name of the lexer under the caret in
-a multiple-language lexer.
+If *current* is `true`, returns the name of the lexer under the caret in a multiple-language
+lexer.
Parameters:
* *`buffer`*: A buffer.
-* *`current`*: Whether or not to get the lexer at the current caret position
- in multi-language lexers. The default is `false` and returns the parent
- lexer.
+* *`current`*: Whether or not to get the lexer at the current caret position in multi-language
+ lexers. The default is `false` and returns the parent lexer.
<a id="buffer.get_line"></a>
#### `buffer.get_line`(*buffer, line*)
@@ -2141,9 +2070,8 @@ Return:
#### `buffer.get_sel_text`(*buffer*)
Returns the selected text.
-Multiple selections are included in order with no delimiters. Rectangular
-selections are included from top to bottom with end of line characters.
-Virtual space is not included.
+Multiple selections are included in order with no delimiters. Rectangular selections are
+included from top to bottom with end of line characters. Virtual space is not included.
Parameters:
@@ -2165,8 +2093,8 @@ Parameters:
<a id="buffer.goto_line"></a>
#### `buffer.goto_line`(*buffer, line*)
-Moves the caret to the beginning of line number *line* and scrolls it into
-view, event if *line* is hidden.
+Moves the caret to the beginning of line number *line* and scrolls it into view, event if
+*line* is hidden.
Parameters:
@@ -2204,8 +2132,8 @@ Parameters:
<a id="buffer.home_display_extend"></a>
#### `buffer.home_display_extend`(*buffer*)
-Moves the caret to the beginning of the current wrapped line, extending the
-selected text to the new position.
+Moves the caret to the beginning of the current wrapped line, extending the selected text
+to the new position.
Parameters:
@@ -2214,8 +2142,8 @@ Parameters:
<a id="buffer.home_extend"></a>
#### `buffer.home_extend`(*buffer*)
-Moves the caret to the beginning of the current line, extending the selected
-text to the new position.
+Moves the caret to the beginning of the current line, extending the selected text to the
+new position.
Parameters:
@@ -2224,8 +2152,8 @@ Parameters:
<a id="buffer.home_rect_extend"></a>
#### `buffer.home_rect_extend`(*buffer*)
-Moves the caret to the beginning of the current line, extending the
-rectangular selection to the new position.
+Moves the caret to the beginning of the current line, extending the rectangular selection
+to the new position.
Parameters:
@@ -2234,8 +2162,8 @@ Parameters:
<a id="buffer.home_wrap"></a>
#### `buffer.home_wrap`(*buffer*)
-Moves the caret to the beginning of the current wrapped line or, if already
-there, to the beginning of the actual line.
+Moves the caret to the beginning of the current wrapped line or, if already there, to the
+beginning of the actual line.
Parameters:
@@ -2254,8 +2182,7 @@ Parameters:
#### `buffer.indicator_all_on_for`(*buffer, pos*)
Returns a bit-mask that represents which indicators are on at position *pos*.
-The first bit is set if indicator 1 is on, the second bit for indicator 2,
-etc.
+The first bit is set if indicator 1 is on, the second bit for indicator 2, etc.
Parameters:
@@ -2269,22 +2196,20 @@ Return:
<a id="buffer.indicator_clear_range"></a>
#### `buffer.indicator_clear_range`(*buffer, pos, length*)
-Clears indicator number `buffer.indicator_current` over the range of text
-from position *pos* to *pos* + *length*.
+Clears indicator number `buffer.indicator_current` over the range of text from position *pos*
+to *pos* + *length*.
Parameters:
* *`buffer`*: A buffer.
-* *`pos`*: The start position of the range of text in *buffer* to clear
- indicators over.
-* *`length`*: The number of characters in the range of text to clear
- indicators over.
+* *`pos`*: The start position of the range of text in *buffer* to clear indicators over.
+* *`length`*: The number of characters in the range of text to clear indicators over.
<a id="buffer.indicator_end"></a>
#### `buffer.indicator_end`(*buffer, indicator, pos*)
-Returns the next boundary position, starting from position *pos*, of
-indicator number *indicator*, in the range of `1` to `32`.
+Returns the next boundary position, starting from position *pos*, of indicator number
+*indicator*, in the range of `1` to `32`.
Returns `1` if *indicator* was not found.
Parameters:
@@ -2296,22 +2221,20 @@ Parameters:
<a id="buffer.indicator_fill_range"></a>
#### `buffer.indicator_fill_range`(*buffer, pos, length*)
-Fills the range of text from position *pos* to *pos* + *length* with
-indicator number `buffer.indicator_current`.
+Fills the range of text from position *pos* to *pos* + *length* with indicator number
+`buffer.indicator_current`.
Parameters:
* *`buffer`*: A buffer.
-* *`pos`*: The start position of the range of text in *buffer* to set
- indicators over.
-* *`length`*: The number of characters in the range of text to set indicators
- over.
+* *`pos`*: The start position of the range of text in *buffer* to set indicators over.
+* *`length`*: The number of characters in the range of text to set indicators over.
<a id="buffer.indicator_start"></a>
#### `buffer.indicator_start`(*buffer, indicator, pos*)
-Returns the previous boundary position, starting from position *pos*, of
-indicator number *indicator*, in the range of `1` to `32`.
+Returns the previous boundary position, starting from position *pos*, of indicator number
+*indicator*, in the range of `1` to `32`.
Returns `1` if *indicator* was not found.
Parameters:
@@ -2325,29 +2248,26 @@ Parameters:
Inserts string *text* at position *pos*, removing any selections.
If *pos* is `-1`, inserts *text* at the caret position.
-If the caret is after the *pos*, it is moved appropriately, but not scrolled
-into view.
+If the caret is after the *pos*, it is moved appropriately, but not scrolled into view.
Parameters:
* *`buffer`*: A buffer.
-* *`pos`*: The position in *buffer* to insert text at, or `-1` for the
- current position.
+* *`pos`*: The position in *buffer* to insert text at, or `-1` for the current position.
* *`text`*: The text to insert.
<a id="buffer.is_range_word"></a>
#### `buffer.is_range_word`(*buffer, start\_pos, end\_pos*)
-Returns whether or not the the positions *start_pos* and *end_pos* are at
-word boundaries.
+Returns whether or not the the positions *start_pos* and *end_pos* are at word boundaries.
Parameters:
* *`buffer`*: A buffer.
-* *`start_pos`*: The start position of the range of text in *buffer* to
- check for a word boundary at.
-* *`end_pos`*: The end position of the range of text in *buffer* to check for
- a word boundary at.
+* *`start_pos`*: The start position of the range of text in *buffer* to check for a word
+ boundary at.
+* *`end_pos`*: The end position of the range of text in *buffer* to check for a word
+ boundary at.
<a id="buffer.line_copy"></a>
#### `buffer.line_copy`(*buffer*)
@@ -2388,8 +2308,7 @@ Parameters:
<a id="buffer.line_down_extend"></a>
#### `buffer.line_down_extend`(*buffer*)
-Moves the caret down one line, extending the selected text to the new
-position.
+Moves the caret down one line, extending the selected text to the new position.
Parameters:
@@ -2398,8 +2317,7 @@ Parameters:
<a id="buffer.line_down_rect_extend"></a>
#### `buffer.line_down_rect_extend`(*buffer*)
-Moves the caret down one line, extending the rectangular selection to the new
-position.
+Moves the caret down one line, extending the rectangular selection to the new position.
Parameters:
@@ -2435,8 +2353,8 @@ Parameters:
<a id="buffer.line_end_display_extend"></a>
#### `buffer.line_end_display_extend`(*buffer*)
-Moves the caret to the end of the current wrapped line, extending the
-selected text to the new position.
+Moves the caret to the end of the current wrapped line, extending the selected text to the
+new position.
Parameters:
@@ -2445,8 +2363,7 @@ Parameters:
<a id="buffer.line_end_extend"></a>
#### `buffer.line_end_extend`(*buffer*)
-Moves the caret to the end of the current line, extending the selected text
-to the new position.
+Moves the caret to the end of the current line, extending the selected text to the new position.
Parameters:
@@ -2455,8 +2372,8 @@ Parameters:
<a id="buffer.line_end_rect_extend"></a>
#### `buffer.line_end_rect_extend`(*buffer*)
-Moves the caret to the end of the current line, extending the rectangular
-selection to the new position.
+Moves the caret to the end of the current line, extending the rectangular selection to the
+new position.
Parameters:
@@ -2465,8 +2382,8 @@ Parameters:
<a id="buffer.line_end_wrap"></a>
#### `buffer.line_end_wrap`(*buffer*)
-Moves the caret to the end of the current wrapped line or, if already there,
-to the end of the actual line.
+Moves the caret to the end of the current wrapped line or, if already there, to the end of
+the actual line.
Parameters:
@@ -2475,8 +2392,7 @@ Parameters:
<a id="buffer.line_end_wrap_extend"></a>
#### `buffer.line_end_wrap_extend`(*buffer*)
-Like `buffer.line_end_wrap()`, but extends the selected text to the new
-position.
+Like `buffer.line_end_wrap()`, but extends the selected text to the new position.
Parameters:
@@ -2486,8 +2402,8 @@ Parameters:
#### `buffer.line_from_position`(*buffer, pos*)
Returns the line number of the line that contains position *pos*.
-Returns `1` if *pos* is less than 1 or `buffer.line_count` if *pos* is
-greater than `buffer.length + 1`.
+Returns `1` if *pos* is less than 1 or `buffer.line_count` if *pos* is greater than
+`buffer.length + 1`.
Parameters:
@@ -2501,10 +2417,9 @@ Return:
<a id="buffer.line_length"></a>
#### `buffer.line_length`(*buffer, line*)
-Returns the number of bytes on line number *line*, including end of line
-characters.
-To get line length excluding end of line characters, use
-`buffer.line_end_position[line] - buffer.position_from_line(line)`.
+Returns the number of bytes on line number *line*, including end of line characters.
+To get line length excluding end of line characters, use `buffer.line_end_position[line]
+- buffer.position_from_line(line)`.
Parameters:
@@ -2554,8 +2469,7 @@ Parameters:
<a id="buffer.line_up_rect_extend"></a>
#### `buffer.line_up_rect_extend`(*buffer*)
-Moves the caret up one line, extending the rectangular selection to the new
-position.
+Moves the caret up one line, extending the rectangular selection to the new position.
Parameters:
@@ -2564,8 +2478,8 @@ Parameters:
<a id="buffer.lines_join"></a>
#### `buffer.lines_join`(*buffer*)
-Joins the lines in the target range, inserting spaces between the words
-joined at line boundaries.
+Joins the lines in the target range, inserting spaces between the words joined at line
+boundaries.
Parameters:
@@ -2575,15 +2489,13 @@ Parameters:
#### `buffer.lines_split`(*buffer, pixel\_width, width*)
Splits the lines in the target range into lines *width* pixels wide.
-If *width* is `0`, splits the lines in the target range into lines as wide as
-the view.
+If *width* is `0`, splits the lines in the target range into lines as wide as the view.
Parameters:
* *`buffer`*: A buffer.
* *`pixel_width`*:
-* *`width`*: The pixel width to split lines at. When `0`, uses the width of
- the view.
+* *`width`*: The pixel width to split lines at. When `0`, uses the width of the view.
<a id="buffer.lower_case"></a>
#### `buffer.lower_case`(*buffer*)
@@ -2606,10 +2518,9 @@ Parameters:
<a id="buffer.marker_add"></a>
#### `buffer.marker_add`(*buffer, line, marker*)
-Adds marker number *marker*, in the range of `1` to `32`, to line number
-*line*, returning the added marker's handle which can be used in
-`buffer.marker_delete_handle()` and `buffer.marker_line_from_handle()`, or
-`-1` if *line* is invalid.
+Adds marker number *marker*, in the range of `1` to `32`, to line number *line*, returning
+the added marker's handle which can be used in `buffer.marker_delete_handle()` and
+`buffer.marker_line_from_handle()`, or `-1` if *line* is invalid.
Parameters:
@@ -2624,43 +2535,41 @@ Return:
<a id="buffer.marker_add_set"></a>
#### `buffer.marker_add_set`(*buffer, line, marker\_mask*)
-Adds the markers specified in marker bit-mask *marker_mask* to line number
-*line*.
-The first bit is set to add marker number 1, the second bit for marker number
-2, and so on up to marker number 32.
+Adds the markers specified in marker bit-mask *marker_mask* to line number *line*.
+The first bit is set to add marker number 1, the second bit for marker number 2, and so on
+up to marker number 32.
Parameters:
* *`buffer`*: A buffer.
* *`line`*: The line number to add the markers on.
-* *`marker_mask`*: The mask of markers to set. Set the first bit to set
- marker 1, the second bit for marker 2 and so on.
+* *`marker_mask`*: The mask of markers to set. Set the first bit to set marker 1, the second
+ bit for marker 2 and so on.
<a id="buffer.marker_delete"></a>
#### `buffer.marker_delete`(*buffer, line, marker*)
-Deletes marker number *marker*, in the range of `1` to `32`, from line number
-*line*. If *marker* is `-1`, deletes all markers from *line*.
+Deletes marker number *marker*, in the range of `1` to `32`, from line number *line*. If
+*marker* is `-1`, deletes all markers from *line*.
Parameters:
* *`buffer`*: A buffer.
* *`line`*: The line number to delete the marker on.
-* *`marker`*: The marker number in the range of `1` to `32` to delete from
- *line*, or `-1` to delete all markers from the line.
+* *`marker`*: The marker number in the range of `1` to `32` to delete from *line*, or `-1`
+ to delete all markers from the line.
<a id="buffer.marker_delete_all"></a>
#### `buffer.marker_delete_all`(*buffer, marker*)
-Deletes marker number *marker*, in the range of `1` to `32`, from any line
-that has it.
+Deletes marker number *marker*, in the range of `1` to `32`, from any line that has it.
If *marker* is `-1`, deletes all markers from all lines.
Parameters:
* *`buffer`*: A buffer.
-* *`marker`*: The marker number in the range of `1` to `32` to delete from
- all lines, or `-1` to delete all markers from all lines.
+* *`marker`*: The marker number in the range of `1` to `32` to delete from all lines, or
+ `-1` to delete all markers from all lines.
<a id="buffer.marker_delete_handle"></a>
#### `buffer.marker_delete_handle`(*buffer, handle*)
@@ -2676,8 +2585,8 @@ Parameters:
#### `buffer.marker_get`(*buffer, line*)
Returns a bit-mask that represents the markers on line number *line*.
-The first bit is set if marker number 1 is present, the second bit for marker
-number 2, and so on.
+The first bit is set if marker number 1 is present, the second bit for marker number 2,
+and so on.
Parameters:
@@ -2691,8 +2600,7 @@ Return:
<a id="buffer.marker_handle_from_line"></a>
#### `buffer.marker_handle_from_line`(*buffer, line, n*)
-Returns the handle of the *n*th marker on line number *line*, or `-1` if no
-such marker exists.
+Returns the handle of the *n*th marker on line number *line*, or `-1` if no such marker exists.
Parameters:
@@ -2703,8 +2611,8 @@ Parameters:
<a id="buffer.marker_line_from_handle"></a>
#### `buffer.marker_line_from_handle`(*buffer, handle*)
-Returns the line number of the line that contains the marker with handle
-*handle* (returned `buffer.marker_add()`), or `-1` if the line was not found.
+Returns the line number of the line that contains the marker with handle *handle* (returned
+`buffer.marker_add()`), or `-1` if the line was not found.
Parameters:
@@ -2718,18 +2626,17 @@ Return:
<a id="buffer.marker_next"></a>
#### `buffer.marker_next`(*buffer, line, marker\_mask*)
-Returns the first line number, starting at line number *line*, that contains
-all of the markers represented by marker bit-mask *marker_mask*.
+Returns the first line number, starting at line number *line*, that contains all of the
+markers represented by marker bit-mask *marker_mask*.
Returns `-1` if no line was found.
-The first bit is set if marker 1 is set, the second bit for marker 2, etc.,
-up to marker 32.
+The first bit is set if marker 1 is set, the second bit for marker 2, etc., up to marker 32.
Parameters:
* *`buffer`*: A buffer.
* *`line`*: The start line to search from.
-* *`marker_mask`*: The mask of markers to find. Set the first bit to find
- marker 1, the second bit for marker 2, and so on.
+* *`marker_mask`*: The mask of markers to find. Set the first bit to find marker 1, the
+ second bit for marker 2, and so on.
Return:
@@ -2738,8 +2645,7 @@ Return:
<a id="buffer.marker_number_from_line"></a>
#### `buffer.marker_number_from_line`(*buffer, line, n*)
-Returns the number of the *n*th marker on line number *line*, or `-1` if no
-such marker exists.
+Returns the number of the *n*th marker on line number *line*, or `-1` if no such marker exists.
Parameters:
@@ -2750,18 +2656,17 @@ Parameters:
<a id="buffer.marker_previous"></a>
#### `buffer.marker_previous`(*buffer, line, marker\_mask*)
-Returns the last line number, before or on line number *line*, that contains
-all of the markers represented by marker bit-mask *marker_mask*.
+Returns the last line number, before or on line number *line*, that contains all of the
+markers represented by marker bit-mask *marker_mask*.
Returns `-1` if no line was found.
-The first bit is set if marker 1 is set, the second bit for marker 2, etc.,
-up to marker 32.
+The first bit is set if marker 1 is set, the second bit for marker 2, etc., up to marker 32.
Parameters:
* *`buffer`*: A buffer.
* *`line`*: The start line to search from.
-* *`marker_mask`*: The mask of markers to find. Set the first bit to find
- marker 1, the second bit for marker 2, and so on.
+* *`marker_mask`*: The mask of markers to find. Set the first bit to find marker 1, the
+ second bit for marker 2, and so on.
Return:
@@ -2797,8 +2702,7 @@ Parameters:
<a id="buffer.multiple_select_add_each"></a>
#### `buffer.multiple_select_add_each`(*buffer*)
-Adds to the set of selections each occurrence of the main selection within
-the target range.
+Adds to the set of selections each occurrence of the main selection within the target range.
If there is no selected text, the current word is used.
Parameters:
@@ -2808,9 +2712,8 @@ Parameters:
<a id="buffer.multiple_select_add_next"></a>
#### `buffer.multiple_select_add_next`(*buffer*)
-Adds to the set of selections the next occurrence of the main selection
-within the target range, makes that occurrence the new main selection, and
-scrolls it into view.
+Adds to the set of selections the next occurrence of the main selection within the target
+range, makes that occurrence the new main selection, and scrolls it into view.
If there is no selected text, the current word is used.
Parameters:
@@ -2866,8 +2769,7 @@ Parameters:
<a id="buffer.page_down_extend"></a>
#### `buffer.page_down_extend`(*buffer*)
-Moves the caret down one page, extending the selected text to the new
-position.
+Moves the caret down one page, extending the selected text to the new position.
Parameters:
@@ -2876,8 +2778,7 @@ Parameters:
<a id="buffer.page_down_rect_extend"></a>
#### `buffer.page_down_rect_extend`(*buffer*)
-Moves the caret down one page, extending the rectangular selection to the new
-position.
+Moves the caret down one page, extending the rectangular selection to the new position.
Parameters:
@@ -2904,8 +2805,7 @@ Parameters:
<a id="buffer.page_up_rect_extend"></a>
#### `buffer.page_up_rect_extend`(*buffer*)
-Moves the caret up one page, extending the rectangular selection to the new
-position.
+Moves the caret up one page, extending the rectangular selection to the new position.
Parameters:
@@ -2924,8 +2824,7 @@ Parameters:
<a id="buffer.para_down_extend"></a>
#### `buffer.para_down_extend`(*buffer*)
-Moves the caret down one paragraph, extending the selected text to the new
-position.
+Moves the caret down one paragraph, extending the selected text to the new position.
Paragraphs are surrounded by one or more blank lines.
Parameters:
@@ -2945,8 +2844,7 @@ Parameters:
<a id="buffer.para_up_extend"></a>
#### `buffer.para_up_extend`(*buffer*)
-Moves the caret up one paragraph, extending the selected text to the new
-position.
+Moves the caret up one paragraph, extending the selected text to the new position.
Paragraphs are surrounded by one or more blank lines.
Parameters:
@@ -2956,8 +2854,8 @@ Parameters:
<a id="buffer.paste"></a>
#### `buffer.paste`(*buffer*)
-Pastes the clipboard's contents into the buffer, replacing any selected text
-according to `buffer.multi_paste`.
+Pastes the clipboard's contents into the buffer, replacing any selected text according to
+`buffer.multi_paste`.
Parameters:
@@ -2966,9 +2864,8 @@ Parameters:
<a id="buffer.position_after"></a>
#### `buffer.position_after`(*buffer, pos*)
-Returns the position of the character after position *pos* (taking multi-byte
-characters into account), or `buffer.length + 1` if there is no character
-after *pos*.
+Returns the position of the character after position *pos* (taking multi-byte characters
+into account), or `buffer.length + 1` if there is no character after *pos*.
Parameters:
@@ -2978,9 +2875,8 @@ Parameters:
<a id="buffer.position_before"></a>
#### `buffer.position_before`(*buffer, pos*)
-Returns the position of the character before position *pos* (taking
-multi-byte characters into account), or `1` if there is no character before
-*pos*.
+Returns the position of the character before position *pos* (taking multi-byte characters
+into account), or `1` if there is no character before *pos*.
Parameters:
@@ -3009,18 +2905,16 @@ Return:
<a id="buffer.position_relative"></a>
#### `buffer.position_relative`(*buffer, pos, n*)
-Returns the position *n* characters before or after position *pos* (taking
-multi-byte characters into account).
-Returns `1` if the position is less than 1 or greater than
-`buffer.length + 1`.
+Returns the position *n* characters before or after position *pos* (taking multi-byte
+characters into account).
+Returns `1` if the position is less than 1 or greater than `buffer.length + 1`.
Parameters:
* *`buffer`*: A buffer.
* *`pos`*: The position in *buffer* to get the relative position from.
-* *`n`*: The relative number of characters to get the position for. A
- negative number indicates a position before while a positive number
- indicates a position after.
+* *`n`*: The relative number of characters to get the position for. A negative number
+ indicates a position before while a positive number indicates a position after.
Return:
@@ -3039,8 +2933,7 @@ Parameters:
#### `buffer.reload`(*buffer*)
Reloads the buffer's file contents, discarding any changes.
-Emits `FILE_BEFORE_RELOAD` and `FILE_AFTER_RELOAD` events if the buffer is
-the current one.
+Emits `FILE_BEFORE_RELOAD` and `FILE_AFTER_RELOAD` events if the buffer is the current one.
Parameters:
@@ -3059,10 +2952,9 @@ Parameters:
<a id="buffer.replace_target"></a>
#### `buffer.replace_target`(*buffer, text*)
-Replaces the text in the target range with string *text* sans modifying any
-selections or scrolling the view.
-Setting the target and calling this function with an empty string is another
-way to delete text.
+Replaces the text in the target range with string *text* sans modifying any selections or
+scrolling the view.
+Setting the target and calling this function with an empty string is another way to delete text.
Parameters:
@@ -3076,10 +2968,9 @@ Return:
<a id="buffer.replace_target_re"></a>
#### `buffer.replace_target_re`(*buffer, text*)
-Replaces the text in the target range with string *text* but first replaces
-any "\d" sequences with the text of capture number *d* from the regular
-expression (or the entire match for *d* = 0), and then returns the
-replacement text's length.
+Replaces the text in the target range with string *text* but first replaces any "\d" sequences
+with the text of capture number *d* from the regular expression (or the entire match for *d*
+= 0), and then returns the replacement text's length.
Parameters:
@@ -3119,14 +3010,14 @@ Emits a `FILE_AFTER_SAVE` event.
Parameters:
* *`buffer`*: A buffer.
-* *`filename`*: Optional new filepath to save the buffer to. If `nil`, the
- user is prompted for one.
+* *`filename`*: Optional new filepath to save the buffer to. If `nil`, the user is prompted
+ for one.
<a id="buffer.search_anchor"></a>
#### `buffer.search_anchor`(*buffer*)
-Anchors the position that `buffer.search_next()` and `buffer.search_prev()`
-start at to the beginning of the current selection or caret position.
+Anchors the position that `buffer.search_next()` and `buffer.search_prev()` start at to the
+beginning of the current selection or caret position.
Parameters:
@@ -3135,10 +3026,10 @@ Parameters:
<a id="buffer.search_in_target"></a>
#### `buffer.search_in_target`(*buffer, text*)
-Searches for the first occurrence of string *text* in the target range
-bounded by `buffer.target_start` and `buffer.target_end` using search flags
-`buffer.search_flags` and, if found, sets the new target range to that
-occurrence, returning its position or `-1` if *text* was not found.
+Searches for the first occurrence of string *text* in the target range bounded by
+`buffer.target_start` and `buffer.target_end` using search flags `buffer.search_flags`
+and, if found, sets the new target range to that occurrence, returning its position or `-1`
+if *text* was not found.
Parameters:
@@ -3156,9 +3047,9 @@ See also:
<a id="buffer.search_next"></a>
#### `buffer.search_next`(*buffer, flags, text*)
-Searches for and selects the first occurrence of string *text* starting at
-the search anchor using search flags *flags*, returning that occurrence's
-position or `-1` if *text* was not found.
+Searches for and selects the first occurrence of string *text* starting at the search
+anchor using search flags *flags*, returning that occurrence's position or `-1` if *text*
+was not found.
Selected text is not scrolled into view.
Parameters:
@@ -3178,9 +3069,8 @@ See also:
<a id="buffer.search_prev"></a>
#### `buffer.search_prev`(*buffer, flags, text*)
-Searches for and selects the last occurrence of string *text* before the
-search anchor using search flags *flags*, returning that occurrence's
-position or `-1` if *text* was not found.
+Searches for and selects the last occurrence of string *text* before the search anchor using
+search flags *flags*, returning that occurrence's position or `-1` if *text* was not found.
Parameters:
@@ -3218,8 +3108,8 @@ Parameters:
<a id="buffer.set_chars_default"></a>
#### `buffer.set_chars_default`(*buffer*)
-Resets `buffer.word_chars`, `buffer.whitespace_chars`, and
-`buffer.punctuation_chars` to their respective defaults.
+Resets `buffer.word_chars`, `buffer.whitespace_chars`, and `buffer.punctuation_chars` to
+their respective defaults.
Parameters:
@@ -3234,8 +3124,7 @@ See also:
<a id="buffer.set_empty_selection"></a>
#### `buffer.set_empty_selection`(*buffer, pos*)
-Moves the caret to position *pos* without scrolling the view and removes any
-selections.
+Moves the caret to position *pos* without scrolling the view and removes any selections.
Parameters:
@@ -3250,8 +3139,8 @@ Converts the buffer's contents to encoding *encoding*.
Parameters:
* *`buffer`*: A buffer.
-* *`encoding`*: The string encoding to set. Valid encodings are ones that GNU
- iconv accepts. If `nil`, assumes a binary encoding.
+* *`encoding`*: The string encoding to set. Valid encodings are ones that GNU iconv accepts. If
+ `nil`, assumes a binary encoding.
Usage:
@@ -3260,14 +3149,14 @@ Usage:
<a id="buffer.set_lexer"></a>
#### `buffer.set_lexer`(*buffer, name*)
-Associates string lexer name *name* or the auto-detected lexer name with the
-buffer and then loads the appropriate language module if that module exists.
+Associates string lexer name *name* or the auto-detected lexer name with the buffer and then
+loads the appropriate language module if that module exists.
Parameters:
* *`buffer`*: A buffer.
-* *`name`*: Optional string lexer name to set. If `nil`, attempts to
- auto-detect the buffer's lexer.
+* *`name`*: Optional string lexer name to set. If `nil`, attempts to auto-detect the
+ buffer's lexer.
Usage:
@@ -3285,37 +3174,34 @@ Parameters:
<a id="buffer.set_sel"></a>
#### `buffer.set_sel`(*buffer, start\_pos, end\_pos*)
-Selects the range of text between positions *start_pos* and *end_pos*,
-scrolling the selected text into view.
+Selects the range of text between positions *start_pos* and *end_pos*, scrolling the selected
+text into view.
Parameters:
* *`buffer`*: A buffer.
-* *`start_pos`*: The start position of the range of text in *buffer* to
- select. If negative, it means the end of the buffer.
-* *`end_pos`*: The end position of the range of text in *buffer* to select.
- If negative, it means remove any selection (i.e. set the `anchor` to the
- same position as `current_pos`).
+* *`start_pos`*: The start position of the range of text in *buffer* to select. If negative,
+ it means the end of the buffer.
+* *`end_pos`*: The end position of the range of text in *buffer* to select. If negative,
+ it means remove any selection (i.e. set the `anchor` to the same position as `current_pos`).
<a id="buffer.set_selection"></a>
#### `buffer.set_selection`(*buffer, end\_pos, start\_pos*)
-Selects the range of text between positions *start_pos* to *end_pos*,
-removing all other selections.
+Selects the range of text between positions *start_pos* to *end_pos*, removing all other
+selections.
Parameters:
* *`buffer`*: A buffer.
* *`end_pos`*: The caret position of the range of text to select in *buffer*.
-* *`start_pos`*: The anchor position of the range of text to select in
- *buffer*.
+* *`start_pos`*: The anchor position of the range of text to select in *buffer*.
<a id="buffer.set_styling"></a>
#### `buffer.set_styling`(*buffer, length, style*)
-Assigns style number *style*, in the range from `1` to `256`, to the next
-*length* characters, starting from the current styling position, and
-increments the styling position by *length*.
+Assigns style number *style*, in the range from `1` to `256`, to the next *length* characters,
+starting from the current styling position, and increments the styling position by *length*.
[`buffer:start_styling`](#buffer.start_styling) should be called before `buffer:set_styling()`.
Parameters:
@@ -3327,8 +3213,8 @@ Parameters:
<a id="buffer.set_target_range"></a>
#### `buffer.set_target_range`(*buffer, start\_pos, end\_pos*)
-Defines the target range's beginning and end positions as *start_pos* and
-*end_pos*, respectively.
+Defines the target range's beginning and end positions as *start_pos* and *end_pos*,
+respectively.
Parameters:
@@ -3350,8 +3236,7 @@ Parameters:
#### `buffer.start_styling`(*buffer, position, unused*)
Begins styling at position *position* with styling bit-mask *style_mask*.
-*style_mask* specifies which style bits can be set with
-`buffer.set_styling()`.
+*style_mask* specifies which style bits can be set with `buffer.set_styling()`.
Parameters:
@@ -3370,8 +3255,7 @@ See also:
<a id="buffer.stuttered_page_down"></a>
#### `buffer.stuttered_page_down`(*buffer*)
-Moves the caret to the bottom of the page or, if already there, down one
-page.
+Moves the caret to the bottom of the page or, if already there, down one page.
Parameters:
@@ -3380,8 +3264,7 @@ Parameters:
<a id="buffer.stuttered_page_down_extend"></a>
#### `buffer.stuttered_page_down_extend`(*buffer*)
-Like `buffer.stuttered_page_down()`, but extends the selected text to the new
-position.
+Like `buffer.stuttered_page_down()`, but extends the selected text to the new position.
Parameters:
@@ -3399,8 +3282,7 @@ Parameters:
<a id="buffer.stuttered_page_up_extend"></a>
#### `buffer.stuttered_page_up_extend`(*buffer*)
-Like `buffer.stuttered_page_up()`, but extends the selected text to the new
-position.
+Like `buffer.stuttered_page_up()`, but extends the selected text to the new position.
Parameters:
@@ -3409,8 +3291,8 @@ Parameters:
<a id="buffer.style_of_name"></a>
#### `buffer.style_of_name`(*buffer, style\_name, string*)
-Returns the style number associated with string *style_name*, or
-`view.STYLE_DEFAULT` if *style_name* is not in use.
+Returns the style number associated with string *style_name*, or `view.STYLE_DEFAULT` if
+*style_name* is not in use.
Parameters:
@@ -3438,8 +3320,7 @@ Parameters:
<a id="buffer.tab"></a>
#### `buffer.tab`(*buffer*)
-Indents the text on the selected lines or types a Tab character ("\t") at
-the caret position.
+Indents the text on the selected lines or types a Tab character ("\t") at the caret position.
Parameters:
@@ -3448,8 +3329,8 @@ Parameters:
<a id="buffer.target_from_selection"></a>
#### `buffer.target_from_selection`(*buffer*)
-Defines the target range's beginning and end positions as the beginning and
-end positions of the main selection, respectively.
+Defines the target range's beginning and end positions as the beginning and end positions
+of the main selection, respectively.
Parameters:
@@ -3458,8 +3339,8 @@ Parameters:
<a id="buffer.target_whole_document"></a>
#### `buffer.target_whole_document`(*buffer*)
-Defines the target range's beginning and end positions as the beginning and
-end positions of the document, respectively.
+Defines the target range's beginning and end positions as the beginning and end positions
+of the document, respectively.
Parameters:
@@ -3479,8 +3360,8 @@ Parameters:
<a id="buffer.toggle_caret_sticky"></a>
#### `buffer.toggle_caret_sticky`(*buffer*)
-Cycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON`
-and `buffer.CARETSTICKY_OFF`.
+Cycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON` and
+`buffer.CARETSTICKY_OFF`.
Parameters:
@@ -3511,19 +3392,17 @@ Parameters:
<a id="buffer.user_list_show"></a>
#### `buffer.user_list_show`(*buffer, id, items*)
-Displays a user list identified by list identifier number *id* and
-constructed from string *items* (whose items are delimited by
-`buffer.auto_c_separator` characters).
-The sorted order of *items* (`buffer.auto_c_order`) must have already been
-defined. When the user selects an item, *id* is sent in a
-`USER_LIST_SELECTION` event along with the selection.
+Displays a user list identified by list identifier number *id* and constructed from string
+*items* (whose items are delimited by `buffer.auto_c_separator` characters).
+The sorted order of *items* (`buffer.auto_c_order`) must have already been defined. When the
+user selects an item, *id* is sent in a `USER_LIST_SELECTION` event along with the selection.
Parameters:
* *`buffer`*: A buffer.
* *`id`*: The list identifier number greater than zero to use.
-* *`items`*: The sorted string of words to show, separated by
- `buffer.auto_c_separator` characters (initially spaces).
+* *`items`*: The sorted string of words to show, separated by `buffer.auto_c_separator`
+ characters (initially spaces).
See also:
@@ -3533,8 +3412,8 @@ See also:
<a id="buffer.vc_home"></a>
#### `buffer.vc_home`(*buffer*)
-Moves the caret to the first visible character on the current line or, if
-already there, to the beginning of the current line.
+Moves the caret to the first visible character on the current line or, if already there,
+to the beginning of the current line.
Parameters:
@@ -3543,8 +3422,8 @@ Parameters:
<a id="buffer.vc_home_display"></a>
#### `buffer.vc_home_display`(*buffer*)
-Moves the caret to the first visible character on the current wrapped line
-or, if already there, to the beginning of the current wrapped line.
+Moves the caret to the first visible character on the current wrapped line or, if already
+there, to the beginning of the current wrapped line.
Parameters:
@@ -3553,8 +3432,7 @@ Parameters:
<a id="buffer.vc_home_display_extend"></a>
#### `buffer.vc_home_display_extend`(*buffer*)
-Like `buffer.vc_home_display()`, but extends the selected text to the new
-position.
+Like `buffer.vc_home_display()`, but extends the selected text to the new position.
Parameters:
@@ -3572,8 +3450,7 @@ Parameters:
<a id="buffer.vc_home_rect_extend"></a>
#### `buffer.vc_home_rect_extend`(*buffer*)
-Like `buffer.vc_home()`, but extends the rectangular selection to the new
-position.
+Like `buffer.vc_home()`, but extends the rectangular selection to the new position.
Parameters:
@@ -3582,8 +3459,8 @@ Parameters:
<a id="buffer.vc_home_wrap"></a>
#### `buffer.vc_home_wrap`(*buffer*)
-Moves the caret to the first visible character on the current wrapped line
-or, if already there, to the beginning of the actual line.
+Moves the caret to the first visible character on the current wrapped line or, if already
+there, to the beginning of the actual line.
Parameters:
@@ -3592,8 +3469,7 @@ Parameters:
<a id="buffer.vc_home_wrap_extend"></a>
#### `buffer.vc_home_wrap_extend`(*buffer*)
-Like `buffer.vc_home_wrap()`, but extends the selected text to the new
-position.
+Like `buffer.vc_home_wrap()`, but extends the selected text to the new position.
Parameters:
@@ -3603,19 +3479,18 @@ Parameters:
#### `buffer.word_end_position`(*buffer, pos, only\_word\_chars*)
Returns the position of the end of the word at position *pos*.
-`buffer.word_chars` contains the set of characters that constitute words. If
-*pos* has a non-word character to its right and *only_word_chars* is `false`,
-returns the first word character's position.
+`buffer.word_chars` contains the set of characters that constitute words. If *pos* has a
+non-word character to its right and *only_word_chars* is `false`, returns the first word
+character's position.
Parameters:
* *`buffer`*: A buffer.
* *`pos`*: The position in *buffer* of the word.
-* *`only_word_chars`*: If `true`, stops searching at the first non-word
- character in the search direction. Otherwise, the first character in the
- search direction sets the type of the search as word or non-word and the
- search stops at the first non-matching character. Searches are also
- terminated by the start or end of the buffer.
+* *`only_word_chars`*: If `true`, stops searching at the first non-word character in
+ the search direction. Otherwise, the first character in the search direction sets the
+ type of the search as word or non-word and the search stops at the first non-matching
+ character. Searches are also terminated by the start or end of the buffer.
<a id="buffer.word_left"></a>
#### `buffer.word_left`(*buffer*)
@@ -3630,8 +3505,7 @@ Parameters:
<a id="buffer.word_left_end"></a>
#### `buffer.word_left_end`(*buffer*)
-Moves the caret left one word, positioning it at the end of the previous
-word.
+Moves the caret left one word, positioning it at the end of the previous word.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3641,8 +3515,7 @@ Parameters:
<a id="buffer.word_left_end_extend"></a>
#### `buffer.word_left_end_extend`(*buffer*)
-Like `buffer.word_left_end()`, but extends the selected text to the new
-position.
+Like `buffer.word_left_end()`, but extends the selected text to the new position.
Parameters:
@@ -3651,8 +3524,7 @@ Parameters:
<a id="buffer.word_left_extend"></a>
#### `buffer.word_left_extend`(*buffer*)
-Moves the caret left one word, extending the selected text to the new
-position.
+Moves the caret left one word, extending the selected text to the new position.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3663,8 +3535,7 @@ Parameters:
#### `buffer.word_part_left`(*buffer*)
Moves the caret to the previous part of the current word.
-Word parts are delimited by underscore characters or changes in
-capitalization.
+Word parts are delimited by underscore characters or changes in capitalization.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3674,10 +3545,9 @@ Parameters:
<a id="buffer.word_part_left_extend"></a>
#### `buffer.word_part_left_extend`(*buffer*)
-Moves the caret to the previous part of the current word, extending the
-selected text to the new position.
-Word parts are delimited by underscore characters or changes in
-capitalization.
+Moves the caret to the previous part of the current word, extending the selected text to
+the new position.
+Word parts are delimited by underscore characters or changes in capitalization.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3688,8 +3558,7 @@ Parameters:
#### `buffer.word_part_right`(*buffer*)
Moves the caret to the next part of the current word.
-Word parts are delimited by underscore characters or changes in
-capitalization.
+Word parts are delimited by underscore characters or changes in capitalization.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3699,10 +3568,9 @@ Parameters:
<a id="buffer.word_part_right_extend"></a>
#### `buffer.word_part_right_extend`(*buffer*)
-Moves the caret to the next part of the current word, extending the selected
-text to the new position.
-Word parts are delimited by underscore characters or changes in
-capitalization.
+Moves the caret to the next part of the current word, extending the selected text to the
+new position.
+Word parts are delimited by underscore characters or changes in capitalization.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3722,8 +3590,7 @@ Parameters:
<a id="buffer.word_right_end"></a>
#### `buffer.word_right_end`(*buffer*)
-Moves the caret right one word, positioning it at the end of the current
-word.
+Moves the caret right one word, positioning it at the end of the current word.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3733,8 +3600,7 @@ Parameters:
<a id="buffer.word_right_end_extend"></a>
#### `buffer.word_right_end_extend`(*buffer*)
-Like `buffer.word_right_end()`, but extends the selected text to the new
-position.
+Like `buffer.word_right_end()`, but extends the selected text to the new position.
Parameters:
@@ -3743,8 +3609,7 @@ Parameters:
<a id="buffer.word_right_extend"></a>
#### `buffer.word_right_extend`(*buffer*)
-Moves the caret right one word, extending the selected text to the new
-position.
+Moves the caret right one word, extending the selected text to the new position.
`buffer.word_chars` contains the set of characters that constitute words.
Parameters:
@@ -3755,19 +3620,18 @@ Parameters:
#### `buffer.word_start_position`(*buffer, pos, only\_word\_chars*)
Returns the position of the beginning of the word at position *pos*.
-`buffer.word_chars` contains the set of characters that constitute words. If
-*pos* has a non-word character to its left and *only_word_chars* is `false`,
-returns the last word character's position.
+`buffer.word_chars` contains the set of characters that constitute words. If *pos* has
+a non-word character to its left and *only_word_chars* is `false`, returns the last word
+character's position.
Parameters:
* *`buffer`*: A buffer.
* *`pos`*: The position in *buffer* of the word.
-* *`only_word_chars`*: If `true`, stops searching at the first non-word
- character in the search direction. Otherwise, the first character in the
- search direction sets the type of the search as word or non-word and the
- search stops at the first non-matching character. Searches are also
- terminated by the start or end of the buffer.
+* *`only_word_chars`*: If `true`, stops searching at the first non-word character in
+ the search direction. Otherwise, the first character in the search direction sets the
+ type of the search as word or non-word and the search stops at the first non-matching
+ character. Searches are also terminated by the start or end of the buffer.
---
@@ -3777,25 +3641,23 @@ Parameters:
Textadept's core event structure and handlers.
-Textadept emits events when you do things like create a new buffer, press a
-key, click on a menu, etc. You can even emit events yourself using Lua. Each
-event has a set of event handlers, which are simply Lua functions called in
-the order they were connected to an event. For example, if you created a
-module that needs to do something each time Textadept creates a new buffer,
-connect a Lua function to the [`events.BUFFER_NEW`](#events.BUFFER_NEW) event:
+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`](#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 themselves are nothing special. You do not have to declare one before using it. Events
+are simply strings containing arbitrary event names. When either you or Textadept emits an
+event, Textadept runs all event handlers connected to the event, passing any given arguments
+to the event's handler functions. If an event handler explicitly returns a value that is not
+`nil`, Textadept will not call subsequent handlers. This is useful if you want to stop the
+propagation of an event like a keypress if your event handler handled it, or if you want to
+use the event framework to pass values.
### Fields defined by `events`
@@ -3816,14 +3678,12 @@ Emitted when canceling an autocompletion or user list.
<a id="events.AUTO_C_CHAR_DELETED"></a>
#### `events.AUTO_C_CHAR_DELETED` (string)
-Emitted after deleting a character while an autocompletion or user list is
- active.
+Emitted after deleting a character while an autocompletion or user list is active.
<a id="events.AUTO_C_COMPLETED"></a>
#### `events.AUTO_C_COMPLETED` (string)
-Emitted after inserting an item from an autocompletion list into the
- buffer.
+Emitted after inserting an item from an autocompletion list into the buffer.
Arguments:
* _`text`_: The selection's text.
@@ -3832,10 +3692,10 @@ Emitted after inserting an item from an autocompletion list into the
<a id="events.AUTO_C_SELECTION"></a>
#### `events.AUTO_C_SELECTION` (string)
-Emitted after selecting an item from an autocompletion list, but before
- inserting that item into the buffer.
- Automatic insertion can be canceled by calling
- [`buffer:auto_c_cancel()`](#buffer.auto_c_cancel) before returning from the event handler.
+Emitted after selecting an item from an autocompletion list, but before inserting that
+ item into the buffer.
+ Automatic insertion can be canceled by calling [`buffer:auto_c_cancel()`](#buffer.auto_c_cancel) before returning
+ from the event handler.
Arguments:
* _`text`_: The selection's text.
@@ -3847,8 +3707,7 @@ Emitted after selecting an item from an autocompletion list, but before
Emitted as items are highlighted in an autocompletion or user list.
Arguments:
- * _`id`_: Either the *id* from [`buffer.user_list_show()`](#buffer.user_list_show) or `0` for an
- autocompletion list.
+ * _`id`_: Either the *id* from [`buffer.user_list_show()`](#buffer.user_list_show) or `0` for an autocompletion list.
* _`text`_: The current selection's text.
* _`position`_: The position the list was displayed at.
@@ -3885,8 +3744,8 @@ Emitted after creating a new buffer.
Emitted when clicking on a calltip.
Arguments:
- * _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was
- clicked, and 0 otherwise.
+ * _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was clicked, and
+ 0 otherwise.
<a id="events.CHAR_ADDED"></a>
#### `events.CHAR_ADDED` (string)
@@ -3908,10 +3767,9 @@ Emitted when the text in the command entry changes.
Emitted when the terminal version receives an unrecognized CSI sequence.
Arguments:
- * _`cmd`_: The 24-bit CSI command value. The lowest byte contains the
- command byte. The second lowest byte contains the leading byte, if any
- (e.g. '?'). The third lowest byte contains the intermediate byte, if any
- (e.g. '$').
+ * _`cmd`_: The 24-bit CSI command value. The lowest byte contains the command byte. The
+ second lowest byte contains the leading byte, if any (e.g. '?'). The third lowest byte
+ contains the intermediate byte, if any (e.g. '$').
* _`args`_: Table of numeric arguments of the CSI sequence.
<a id="events.DOUBLE_CLICK"></a>
@@ -3922,19 +3780,16 @@ Emitted after double-clicking the mouse button.
* _`position`_: The position double-clicked.
* _`line`_: The line number of the position double-clicked.
- * _`modifiers`_: A bit-mask of any modifier keys held 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 with GTK.
+ * _`modifiers`_: A bit-mask of any modifier keys held 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 with GTK.
<a id="events.DWELL_END"></a>
#### `events.DWELL_END` (string)
-Emitted after `DWELL_START` when the user moves the mouse, presses a key,
- or scrolls the view.
+Emitted after `DWELL_START` when the user moves the mouse, presses a key, or scrolls the view.
Arguments:
* _`position`_: The position closest to *x* and *y*.
@@ -3944,8 +3799,7 @@ Emitted after `DWELL_START` when the user moves the mouse, presses a key,
<a id="events.DWELL_START"></a>
#### `events.DWELL_START` (string)
-Emitted when the mouse is stationary for [`view.mouse_dwell_time`](#view.mouse_dwell_time)
- milliseconds.
+Emitted when the mouse is stationary for [`view.mouse_dwell_time`](#view.mouse_dwell_time) milliseconds.
Arguments:
* _`position`_: The position closest to *x* and *y*.
@@ -3972,8 +3826,7 @@ Emitted to find text via the Find & Replace Pane.
<a id="events.FIND_TEXT_CHANGED"></a>
#### `events.FIND_TEXT_CHANGED` (string)
-Emitted when the text in the "Find" field of the Find & Replace Pane
- changes.
+Emitted when the text in the "Find" field of the Find & Replace Pane changes.
`ui.find.find_entry_text` contains the current text.
<a id="events.FOCUS"></a>
@@ -3989,19 +3842,16 @@ Emitted when clicking the mouse on text that has an indicator present.
Arguments:
* _`position`_: The clicked text's position.
- * _`modifiers`_: A bit-mask of any modifier keys held 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 with GTK.
+ * _`modifiers`_: A bit-mask of any modifier keys held 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 with GTK.
<a id="events.INDICATOR_RELEASE"></a>
#### `events.INDICATOR_RELEASE` (string)
-Emitted when releasing the mouse after clicking on text that has an
- indicator present.
+Emitted when releasing the mouse after clicking on text that has an indicator present.
Arguments:
* _`position`_: The clicked text's position.
@@ -4033,13 +3883,11 @@ Emitted when clicking the mouse inside a sensitive margin.
* _`margin`_: The margin number clicked.
* _`position`_: The beginning position of the clicked margin's line.
- * _`modifiers`_: A bit-mask of any modifier keys held 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 with GTK.
+ * _`modifiers`_: A bit-mask of any modifier keys held 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 with GTK.
<a id="events.MENU_CLICKED"></a>
#### `events.MENU_CLICKED` (string)
@@ -4047,21 +3895,18 @@ Emitted when clicking the mouse inside a sensitive margin.
Emitted after selecting a menu item.
Arguments:
- * _`menu_id`_: The numeric ID of the menu item, which was defined in
- [`ui.menu()`](#ui.menu).
+ * _`menu_id`_: The numeric ID of the menu item, which was defined in [`ui.menu()`](#ui.menu).
<a id="events.MOUSE"></a>
#### `events.MOUSE` (string)
Emitted by the terminal version for an unhandled mouse event.
- A handler should return `true` if it handled the event. Otherwise Textadept
- will try again. (This side effect for a `false` or `nil` return is useful
- for sending the original mouse event to a different view that a handler
- has switched to.)
+ A handler should return `true` if it handled the event. Otherwise Textadept will try again.
+ (This side effect for a `false` or `nil` return is useful for sending the original mouse
+ event to a different view that a handler has switched to.)
Arguments:
- * _`event`_: The mouse event: `view.MOUSE_PRESS`, `view.MOUSE_DRAG`, or
- `view.MOUSE_RELEASE`.
+ * _`event`_: The mouse event: `view.MOUSE_PRESS`, `view.MOUSE_DRAG`, or `view.MOUSE_RELEASE`.
* _`button`_: The mouse button number.
* _`y`_: The y-coordinate of the mouse event, starting from 1.
* _`x`_: The x-coordinate of the mouse event, starting from 1.
@@ -4073,11 +3918,10 @@ Emitted by the terminal version for an unhandled mouse event.
#### `events.QUIT` (string)
Emitted when quitting Textadept.
- When connecting to this event, connect with an index of 1 if the handler
- needs to run before Textadept closes all open buffers. If a handler returns
- `true`, Textadept does not quit. It is not recommended to return `false`
- from a quit handler, as that may interfere with Textadept's normal shutdown
- procedure.
+ When connecting to this event, connect with an index of 1 if the handler needs to run
+ before Textadept closes all open buffers. If a handler returns `true`, Textadept does not
+ quit. It is not recommended to return `false` from a quit handler, as that may interfere
+ with Textadept's normal shutdown procedure.
Emitted by [`quit()`](#quit).
<a id="events.REPLACE"></a>
@@ -4104,8 +3948,8 @@ Emitted after resetting Textadept's Lua state.
Emitted by [`reset()`](#reset).
Arguments:
- * _`persist`_: Table of data persisted by `events.RESET_BEFORE`. All
- handlers will have access to this same table.
+ * _`persist`_: Table of data persisted by `events.RESET_BEFORE`. All handlers will have
+ access to this same table.
<a id="events.RESET_BEFORE"></a>
#### `events.RESET_BEFORE` (string)
@@ -4114,8 +3958,8 @@ Emitted before resetting Textadept's Lua state.
Emitted by [`reset()`](#reset).
Arguments:
- * _`persist`_: Table to store persistent data in for use by
- `events.RESET_AFTER`. All handlers will have access to this same table.
+ * _`persist`_: Table to store persistent data in for use by `events.RESET_AFTER`. All
+ handlers will have access to this same table.
<a id="events.RESUME"></a>
#### `events.RESUME` (string)
@@ -4136,23 +3980,21 @@ Emitted after reaching a save point.
<a id="events.SUSPEND"></a>
#### `events.SUSPEND` (string)
-Emitted when suspending Textadept. If any handler returns `true`, Textadept
- does not suspend.
+Emitted when suspending Textadept. If any handler returns `true`, Textadept does not suspend.
This event is only emitted by the terminal version.
<a id="events.TAB_CLICKED"></a>
#### `events.TAB_CLICKED` (string)
Emitted when the user clicks on a buffer tab.
- When connecting to this event, connect with an index of 1 if the handler
- needs to run before Textadept switches between buffers.
+ When connecting to this event, connect with an index of 1 if the handler needs to run
+ before Textadept switches between buffers.
Note that Textadept always displays a context menu on right-click.
Arguments:
* _`index`_: The numeric index of the clicked tab.
- * _`button`_: The mouse button number that was clicked, either `1` (left
- button), `2` (middle button), `3` (right button), `4` (wheel up), or `5`
- (wheel down).
+ * _`button`_: The mouse button number that was clicked, either `1` (left button), `2`
+ (middle button), `3` (right button), `4` (wheel up), or `5` (wheel down).
* _`shift`_: The "Shift" modifier key is held down.
* _`ctrl`_: The "Control" modifier key is held down.
* _`alt`_: The "Alt"/"Option" modifier key is held down.
@@ -4232,10 +4074,9 @@ Emitted after changing [`view.zoom`](#view.zoom).
<a id="events.connect"></a>
#### `events.connect`(*event, f, index*)
-Adds function *f* to the set of event handlers for event *event* at position
-*index*.
-If *index* not given, appends *f* to the set of handlers. *event* may be any
-arbitrary string and does not need to have been previously defined.
+Adds function *f* to the set of event handlers for event *event* at position *index*.
+If *index* not given, appends *f* to the set of handlers. *event* may be any arbitrary string
+and does not need to have been previously defined.
Parameters:
@@ -4268,13 +4109,11 @@ See also:
<a id="events.emit"></a>
#### `events.emit`(*event, ...*)
-Sequentially calls all handler functions for event *event* with the given
-arguments.
-*event* may be any arbitrary string and does not need to have been previously
-defined. If any handler explicitly returns a value that is not `nil`,
-`emit()` returns that value and ceases to call subsequent handlers. This is
-useful for stopping the propagation of an event like a keypress after it has
-been handled, or for passing back values from handlers.
+Sequentially calls all handler functions for event *event* with the given arguments.
+*event* may be any arbitrary string and does not need to have been previously defined. If
+any handler explicitly returns a value that is not `nil`, `emit()` returns that value and
+ceases to call subsequent handlers. This is useful for stopping the propagation of an event
+like a keypress after it has been handled, or for passing back values from handlers.
Parameters:
@@ -4287,8 +4126,8 @@ Usage:
Return:
-* `nil` unless any any handler explicitly returned a non-`nil` value;
- otherwise returns that value
+* `nil` unless any any handler explicitly returned a non-`nil` value; otherwise returns
+ that value
---
@@ -4314,8 +4153,7 @@ Emitted right after saving a file to disk.
Arguments:
* _`filename`_: The filename of the file being saved.
- * _`saved_as`_: Whether or not the file was saved under a different
- filename.
+ * _`saved_as`_: Whether or not the file was saved under a different filename.
<a id="events.FILE_BEFORE_RELOAD"></a>
#### `events.FILE_BEFORE_RELOAD` (string)
@@ -4336,8 +4174,8 @@ Emitted right before saving a file to disk.
#### `events.FILE_CHANGED` (string)
Emitted when Textadept detects that an open file was modified externally.
- When connecting to this event, connect with an index of 1 in order to
- override the default prompt to reload the file.
+ When connecting to this event, connect with an index of 1 in order to override the default
+ prompt to reload the file.
Arguments:
* _`filename`_: The filename externally modified.
@@ -4363,8 +4201,8 @@ The maximum number of files listed in the quick open dialog.
<a id="io.close_all_buffers"></a>
#### `io.close_all_buffers`()
-Closes all open buffers, prompting the user to continue if there are unsaved
-buffers, and returns `true` if the user did not cancel.
+Closes all open buffers, prompting the user to continue if there are unsaved buffers, and
+returns `true` if the user did not cancel.
No buffers are saved automatically. They must be saved manually.
Return:
@@ -4378,19 +4216,17 @@ See also:
<a id="io.get_project_root"></a>
#### `io.get_project_root`(*path, submodule*)
-Returns the root directory of the project that contains filesystem path
-*path*.
-In order to be recognized, projects must be under version control. Recognized
-VCSes are Bazaar, Fossil, Git, Mercurial, and SVN.
+Returns the root directory of the project that contains filesystem path *path*.
+In order to be recognized, projects must be under version control. Recognized VCSes are
+Bazaar, Fossil, Git, Mercurial, and SVN.
Parameters:
-* *`path`*: Optional filesystem path to a project or a file contained within
- a project. The default value is the buffer's filename or the current
- working directory. This parameter may be omitted.
-* *`submodule`*: Optional flag that indicates whether or not to return the
- root of the current submodule (if applicable). The default value is
- `false`.
+* *`path`*: Optional filesystem path to a project or a file contained within a project. The
+ default value is the buffer's filename or the current working directory. This parameter
+ may be omitted.
+* *`submodule`*: Optional flag that indicates whether or not to return the root of the
+ current submodule (if applicable). The default value is `false`.
Return:
@@ -4399,17 +4235,15 @@ Return:
<a id="io.open_file"></a>
#### `io.open_file`(*filenames, encodings*)
-Opens *filenames*, a string filename or list of filenames, or the
-user-selected filename(s).
+Opens *filenames*, a string filename or list of filenames, or the user-selected filename(s).
Emits a `FILE_OPENED` event.
Parameters:
-* *`filenames`*: Optional string filename or table of filenames to open. If
- `nil`, the user is prompted with a fileselect dialog.
-* *`encodings`*: Optional string encoding or table of encodings file contents
- are in (one encoding per file). If `nil`, encoding auto-detection is
- attempted via `io.encodings`.
+* *`filenames`*: Optional string filename or table of filenames to open. If `nil`, the user
+ is prompted with a fileselect dialog.
+* *`encodings`*: Optional string encoding or table of encodings file contents are in (one
+ encoding per file). If `nil`, encoding auto-detection is attempted via `io.encodings`.
See also:
@@ -4427,44 +4261,40 @@ See also:
<a id="io.quick_open"></a>
#### `io.quick_open`(*paths, filter, opts*)
-Prompts the user to select files to be opened from *paths*, a string
-directory path or list of directory paths, using a filtered list dialog.
-If *paths* is `nil`, uses the current project's root directory, which is
-obtained from `io.get_project_root()`.
-String or list *filter* determines which files to show in the dialog, with
-the default filter being `io.quick_open_filters[path]` (if it exists) or
-`lfs.default_filter`. A filter consists of Lua patterns that match file and
-directory paths to include or exclude. Patterns are inclusive by default.
-Exclusive patterns begin with a '!'. If no inclusive patterns are given, any
-path is initially considered. As a convenience, file extensions can be
-specified literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'),
-and '/' also matches the Windows directory separator ('[/\\]' is not needed).
+Prompts the user to select files to be opened from *paths*, a string directory path or list
+of directory paths, using a filtered list dialog.
+If *paths* is `nil`, uses the current project's root directory, which is obtained from
+`io.get_project_root()`.
+String or list *filter* determines which files to show in the dialog, with the default
+filter being `io.quick_open_filters[path]` (if it exists) or `lfs.default_filter`. A filter
+consists of Lua patterns that match file and directory paths to include or exclude. Patterns
+are inclusive by default. Exclusive patterns begin with a '!'. If no inclusive patterns are
+given, any path is initially considered. As a convenience, file extensions can be specified
+literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the
+Windows directory separator ('[/\\]' is not needed).
The number of files in the list is capped at `quick_open_max`.
If *filter* is `nil` and *paths* is ultimately a string, the filter from the
-`io.quick_open_filters` table is used. If that filter does not exist,
-`lfs.default_filter` is used.
-*opts* is an optional table of additional options for
-`ui.dialogs.filteredlist()`.
+`io.quick_open_filters` table is used. If that filter does not exist, `lfs.default_filter`
+is used.
+*opts* is an optional table of additional options for `ui.dialogs.filteredlist()`.
Parameters:
-* *`paths`*: Optional string directory path or table of directory paths to
- search. The default value is the current project's root directory, if
- available.
-* *`filter`*: Optional filter for files and directories to include and/or
- exclude. The default value is `lfs.default_filter` unless a filter for
- *paths* is defined in `io.quick_open_filters`.
-* *`opts`*: Optional table of additional options for
- `ui.dialogs.filteredlist()`.
+* *`paths`*: Optional string directory path or table of directory paths to search. The
+ default value is the current project's root directory, if available.
+* *`filter`*: Optional filter for files and directories to include and/or exclude. The
+ default value is `lfs.default_filter` unless a filter for *paths* is defined in
+ `io.quick_open_filters`.
+* *`opts`*: Optional table of additional options for `ui.dialogs.filteredlist()`.
Usage:
-* `io.quick_open(buffer.filename:match('^(.+)[/\\]')) -- list all files
- in the current file's directory, subject to the default filter`
-* `io.quick_open(io.get_current_project(), '.lua') -- list all Lua files
- in the current project`
-* `io.quick_open(io.get_current_project(), '!/build') -- list all files
- in the current project except those in the build directory`
+* `io.quick_open(buffer.filename:match('^(.+)[/\\]')) -- list all files in the current
+ file's directory, subject to the default filter`
+* `io.quick_open(io.get_current_project(), '.lua') -- list all Lua files in the current
+ project`
+* `io.quick_open(io.get_current_project(), '!/build') -- list all files in the current
+ project except those in the build directory`
See also:
@@ -4489,16 +4319,15 @@ See also:
#### `io.encodings`
List of encodings to attempt to decode files as.
-You should add to this list if you get a "Conversion failed" error when
-trying to open a file whose encoding is not recognized. Valid encodings are
-[GNU iconv's encodings][] and include:
+You should add to this list if you get a "Conversion failed" error when trying to open a file
+whose encoding is not recognized. Valid encodings are [GNU iconv's encodings][] and include:
- * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
- KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
- Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
- Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.
- * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,
- UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
+ * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R,
+ KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
+ Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, Mac{Cyrillic,Ukraine,Greek,Turkish},
+ Macintosh.
+ * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16, UTF-16BE,
+ UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
[GNU iconv's encodings]: https://www.gnu.org/software/libiconv/
@@ -4529,50 +4358,43 @@ Manages key bindings in Textadept.
### Overview
-Define key bindings in the global `keys` table in key-value pairs. Each pair
-consists of either a string key sequence and its associated command, a string
-lexer name (from the *lexers/* directory) with a table of key sequences and
-commands, a string key mode with a table of key sequences and commands, or a
-key sequence with a table of more sequences and commands. The latter is part
-of what is called a "key chain", to be discussed below. When searching for a
-command to run based on a key sequence, Textadept considers key bindings in
-the current key mode to have priority. If no key mode is active,
-language-specific key bindings have priority, followed by the ones in the
-global table. This means if there are two commands with the same key
-sequence, Textadept runs the language-specific one. However, if the command
-returns the boolean value `false`, Textadept also runs the lower-priority
-command. (This is useful for language modules to override commands like
-autocompletion, but fall back to word autocompletion if the first command
-fails.)
+Define key bindings in the global `keys` table in key-value pairs. Each pair consists of
+either a string key sequence and its associated command, a string lexer name (from the
+*lexers/* directory) with a table of key sequences and commands, a string key mode with a
+table of key sequences and commands, or a key sequence with a table of more sequences and
+commands. The latter is part of what is called a "key chain", to be discussed below. When
+searching for a command to run based on a key sequence, Textadept considers key bindings
+in the current key mode to have priority. If no key mode is active, language-specific key
+bindings have priority, followed by the ones in the global table. This means if there are
+two commands with the same key sequence, Textadept runs the language-specific one. However,
+if the command returns the boolean value `false`, Textadept also runs the lower-priority
+command. (This is useful for language modules to override commands like autocompletion,
+but fall back to word autocompletion if the first command fails.)
### Key Sequences
-Key sequences are strings built from an ordered combination of modifier keys
-and the key's inserted character. Modifier keys are "Control", "Shift", and
-"Alt" on Windows, Linux, BSD, and in the terminal version. On macOS they are
-"Control" (`^`), "Alt/Option" (`⌥`), "Command" (`⌘`), and "Shift" (`⇧`).
-These modifiers have the following string representations:
-
-Modifier | Linux / Win32 | 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, 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`](#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.
+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 | Linux / Win32 | 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,
+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`](#keys.KEYSYMS) lookup table. Therefore, `Ctrl+Right Arrow` has the key sequence
+`ctrl+right`. Uncommenting the `print()` statements in *core/keys.lua* causes Textadept to
+print key sequences to standard out (stdout) for inspection.
### Commands
@@ -4586,9 +4408,9 @@ Textadept handles [`buffer`](#buffer) references properly in static contexts.
### Modes
-Modes are groups of key bindings such that when a key [mode](#keys.mode) is
-active, Textadept ignores all key bindings defined outside the mode until the
-mode is unset. Here is a simple vi mode example:
+Modes are groups of key bindings such that when a key [mode](#keys.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,
@@ -4607,15 +4429,14 @@ mode is unset. Here is a simple vi mode example:
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.
+**Warning**: When creating a mode, be sure to define a way to exit the mode, otherwise you
+will probably have to restart Textadept.
### Key Chains
-Key chains are a powerful concept. They allow you to assign multiple key
-bindings to one key sequence. By default, the `Esc` key cancels a key chain,
-but you can redefine it via [`keys.CLEAR`](#keys.CLEAR). An example key chain looks
-like:
+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`](#keys.CLEAR). An example key chain looks like:
keys['alt+a'] = {
a = function1,
@@ -4636,8 +4457,7 @@ The key that clears the current key chain.
#### `keys.mode` (string)
The current key mode.
- When non-`nil`, all key bindings defined outside of `keys[mode]` are
- ignored.
+ When non-`nil`, all key bindings defined outside of `keys[mode]` are ignored.
The default value is `nil`.
@@ -4647,19 +4467,17 @@ The current key mode.
#### `keys.KEYSYMS`
Lookup table for string representations of key codes higher than 255.
-Key codes can be identified by temporarily uncommenting the `print()`
-statements in *core/keys.lua*.
-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: kpenter, kphome, kpend, kpleft, kpup,
-kpright, kpdown, kppgup, kppgdn, kpmul, kpadd, kpsub, kpdiv, kpdec, and
-kp0-kp9.
+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: kpenter, kphome, kpend, kpleft, kpup, kpright, kpdown,
+kppgup, kppgdn, kpmul, kpadd, kpsub, kpdiv, kpdec, and kp0-kp9.
<a id="_G.keys"></a>
#### `_G.keys`
-Map of key bindings to commands, with language-specific key tables assigned
-to a lexer name key.
+Map of key bindings to commands, with language-specific key tables assigned to a lexer name key.
<a id="keys.keychain"></a>
#### `keys.keychain`
@@ -4675,41 +4493,37 @@ Lexes Scintilla documents and source code with Lua and LPeg.
### Writing Lua Lexers
-Lexers highlight the syntax of source code. Scintilla (the editing component
-behind [Textadept][] and [SciTE][]) traditionally uses static, compiled C++
-lexers which are notoriously difficult to create and/or extend. On the other
-hand, Lua makes it easy to to rapidly create new lexers, extend existing
-ones, and embed lexers within one another. Lua lexers tend to be more
-readable than C++ lexers too.
-
-Lexers are Parsing Expression Grammars, or PEGs, composed with the Lua
-[LPeg library][]. The following table comes from the LPeg documentation and
-summarizes all you need to know about constructing basic LPeg patterns. This
-module provides convenience functions for creating and working with other
-more advanced patterns and concepts.
-
-Operator | Description
----------------------|------------
-`lpeg.P(string)` | Matches `string` literally.
-`lpeg.P(`_`n`_`)` | Matches exactly _`n`_ number of characters.
-`lpeg.S(string)` | Matches any character in set `string`.
-`lpeg.R("`_`xy`_`")` | Matches any character between range `x` and `y`.
-`patt^`_`n`_ | Matches at least _`n`_ repetitions of `patt`.
-`patt^-`_`n`_ | Matches at most _`n`_ repetitions of `patt`.
-`patt1 * patt2` | Matches `patt1` followed by `patt2`.
-`patt1 + patt2` | Matches `patt1` or `patt2` (ordered choice).
-`patt1 - patt2` | Matches `patt1` if `patt2` does not also match.
-`-patt` | Equivalent to `("" - patt)`.
-`#patt` | Matches `patt` but consumes no input.
-
-The first part of this document deals with rapidly constructing a simple
-lexer. The next part deals with more advanced techniques, such as custom
-coloring and embedding lexers within one another. Following that is a
-discussion about code folding, or being able to tell Scintilla which code
-blocks are "foldable" (temporarily hideable from view). After that are
-instructions on how to use Lua lexers with the aforementioned Textadept and
-SciTE editors. Finally there are comments on lexer performance and
-limitations.
+Lexers highlight the syntax of source code. Scintilla (the editing component behind
+[Textadept][] and [SciTE][]) traditionally uses static, compiled C++ lexers which are
+notoriously difficult to create and/or extend. On the other hand, Lua makes it easy to to
+rapidly create new lexers, extend existing ones, and embed lexers within one another. Lua
+lexers tend to be more readable than C++ lexers too.
+
+Lexers are Parsing Expression Grammars, or PEGs, composed with the Lua [LPeg library][]. The
+following table comes from the LPeg documentation and summarizes all you need to know about
+constructing basic LPeg patterns. This module provides convenience functions for creating
+and working with other more advanced patterns and concepts.
+
+Operator | Description
+-|-
+`lpeg.P(string)` | Matches `string` literally.
+`lpeg.P(`_`n`_`)` | Matches exactly _`n`_ number of characters.
+`lpeg.S(string)` | Matches any character in set `string`.
+`lpeg.R("`_`xy`_`")`| Matches any character between range `x` and `y`.
+`patt^`_`n`_ | Matches at least _`n`_ repetitions of `patt`.
+`patt^-`_`n`_ | Matches at most _`n`_ repetitions of `patt`.
+`patt1 * patt2` | Matches `patt1` followed by `patt2`.
+`patt1 + patt2` | Matches `patt1` or `patt2` (ordered choice).
+`patt1 - patt2` | Matches `patt1` if `patt2` does not also match.
+`-patt` | Equivalent to `("" - patt)`.
+`#patt` | Matches `patt` but consumes no input.
+
+The first part of this document deals with rapidly constructing a simple lexer. The next part
+deals with more advanced techniques, such as custom coloring and embedding lexers within one
+another. Following that is a discussion about code folding, or being able to tell Scintilla
+which code blocks are "foldable" (temporarily hideable from view). After that are instructions
+on how to use Lua lexers with the aforementioned Textadept and SciTE editors. Finally there
+are comments on lexer performance and limitations.
[LPeg library]: http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html
[Textadept]: https://orbitalquark.github.io/textadept
@@ -4717,23 +4531,21 @@ limitations.
### Lexer Basics
-The *lexers/* directory contains all lexers, including your new one. Before
-attempting to write one from scratch though, first determine if your
-programming language is similar to any of the 100+ languages supported. If
-so, you may be able to copy and modify that lexer, saving some time and
-effort. The filename of your lexer should be the name of your programming
-language in lower case followed by a *.lua* extension. For example, a new Lua
-lexer has the name *lua.lua*.
+The *lexers/* directory contains all lexers, including your new one. Before attempting to
+write one from scratch though, first determine if your programming language is similar to
+any of the 100+ languages supported. If so, you may be able to copy and modify that lexer,
+saving some time and effort. The filename of your lexer should be the name of your programming
+language in lower case followed by a *.lua* extension. For example, a new Lua lexer has the
+name *lua.lua*.
-Note: Try to refrain from using one-character language names like "c", "d",
-or "r". For example, Scintillua uses "ansi_c", "dmd", and "rstats",
-respectively.
+Note: Try to refrain from using one-character language names like "c", "d", or "r". For
+example, Scintillua uses "ansi_c", "dmd", and "rstats", respectively.
#### New Lexer Template
-There is a *lexers/template.txt* file that contains a simple template for a
-new lexer. Feel free to use it, replacing the '?'s with the name of your
-lexer. Consider this snippet from the template:
+There is a *lexers/template.txt* file that contains a simple template for a new lexer. Feel
+free to use it, replacing the '?'s with the name of your lexer. Consider this snippet from
+the template:
-- ? LPeg lexer.
@@ -4751,103 +4563,83 @@ lexer. Consider this snippet from the template:
return lex
-The first 3 lines of code simply define often used convenience variables. The
-fourth and last lines [define](#lexer.new) and return the lexer object
-Scintilla uses; they are very important and must be part of every lexer. The
-fifth line defines something called a "token", an essential building block of
-lexers. You will learn about tokens shortly. The sixth line defines a lexer
-grammar rule, which you will learn about later, as well as token styles. (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.
+The first 3 lines of code simply define often used convenience variables. The fourth and
+last lines [define](#lexer.new) and return the lexer object Scintilla uses; they are very
+important and must be part of every lexer. The fifth line defines something called a "token",
+an essential building block of lexers. You will learn about tokens shortly. The sixth line
+defines a lexer grammar rule, which you will learn about later, as well as token styles. (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.
#### Tokens
-Take a moment to think about your programming language's structure. What kind
-of key elements does it have? In the template shown earlier, one predefined
-element all languages have is whitespace. Your language probably also has
-elements like comments, strings, and keywords. Lexers refer to these elements
-as "tokens". Tokens are the fundamental "building blocks" of lexers. Lexers
-break down source code into tokens for coloring, which results in the syntax
-highlighting familiar to you. It is up to you how specific your lexer is when
-it comes to tokens. Perhaps only distinguishing between keywords and
-identifiers is necessary, or maybe recognizing constants and built-in
-functions, methods, or libraries is desirable. The Lua lexer, for example,
-defines 11 tokens: whitespace, keywords, built-in functions, constants,
-built-in libraries, identifiers, strings, comments, numbers, labels, and
-operators. Even though constants, built-in functions, and built-in libraries
-are subsets of identifiers, Lua programmers find it helpful for the lexer to
-distinguish between them all. It is perfectly acceptable to just recognize
-keywords and identifiers.
-
-In a lexer, tokens consist of a token name and an LPeg pattern that matches a
-sequence of characters recognized as an instance of that token. Create tokens
-using the [`lexer.token()`](#lexer.token) function. Let us examine the "whitespace" token
-defined in the template shown earlier:
+Take a moment to think about your programming language's structure. What kind of key
+elements does it have? In the template shown earlier, one predefined element all languages
+have is whitespace. Your language probably also has elements like comments, strings, and
+keywords. Lexers refer to these elements as "tokens". Tokens are the fundamental "building
+blocks" of lexers. Lexers break down source code into tokens for coloring, which results
+in the syntax highlighting familiar to you. It is up to you how specific your lexer is
+when it comes to tokens. Perhaps only distinguishing between keywords and identifiers is
+necessary, or maybe recognizing constants and built-in functions, methods, or libraries is
+desirable. The Lua lexer, for example, defines 11 tokens: whitespace, keywords, built-in
+functions, constants, built-in libraries, identifiers, strings, comments, numbers, labels,
+and operators. Even though constants, built-in functions, and built-in libraries are subsets
+of identifiers, Lua programmers find it helpful for the lexer to distinguish between them
+all. It is perfectly acceptable to just recognize keywords and identifiers.
+
+In a lexer, tokens consist of a token name and an LPeg pattern that matches a sequence of
+characters recognized as an instance of that token. Create tokens using the [`lexer.token()`](#lexer.token)
+function. Let us examine the "whitespace" token defined in the template shown earlier:
local ws = token(lexer.WHITESPACE, lexer.space^1)
-At first glance, the first argument does not appear to be a string name and
-the second argument does not appear to be an LPeg pattern. Perhaps you
-expected something like:
+At first glance, the first argument does not appear to be a string name and the second
+argument does not appear to be an LPeg pattern. Perhaps you expected something like:
local ws = token('whitespace', S('\t\v\f\n\r ')^1)
-The `lexer` module actually provides a convenient list of common token names
-and common LPeg patterns for you to use. Token names include
-[`lexer.DEFAULT`](#lexer.DEFAULT), [`lexer.WHITESPACE`](#lexer.WHITESPACE), [`lexer.COMMENT`](#lexer.COMMENT),
-[`lexer.STRING`](#lexer.STRING), [`lexer.NUMBER`](#lexer.NUMBER), [`lexer.KEYWORD`](#lexer.KEYWORD),
-[`lexer.IDENTIFIER`](#lexer.IDENTIFIER), [`lexer.OPERATOR`](#lexer.OPERATOR), [`lexer.ERROR`](#lexer.ERROR),
-[`lexer.PREPROCESSOR`](#lexer.PREPROCESSOR), [`lexer.CONSTANT`](#lexer.CONSTANT), [`lexer.VARIABLE`](#lexer.VARIABLE),
-[`lexer.FUNCTION`](#lexer.FUNCTION), [`lexer.CLASS`](#lexer.CLASS), [`lexer.TYPE`](#lexer.TYPE), [`lexer.LABEL`](#lexer.LABEL),
-[`lexer.REGEX`](#lexer.REGEX), and [`lexer.EMBEDDED`](#lexer.EMBEDDED). Patterns include
-[`lexer.any`](#lexer.any), [`lexer.alpha`](#lexer.alpha), [`lexer.digit`](#lexer.digit), [`lexer.alnum`](#lexer.alnum),
-[`lexer.lower`](#lexer.lower), [`lexer.upper`](#lexer.upper), [`lexer.xdigit`](#lexer.xdigit), [`lexer.graph`](#lexer.graph),
-[`lexer.print`](#lexer.print), [`lexer.punct`](#lexer.punct), [`lexer.space`](#lexer.space), [`lexer.newline`](#lexer.newline),
-[`lexer.nonnewline`](#lexer.nonnewline), [`lexer.dec_num`](#lexer.dec_num), [`lexer.hex_num`](#lexer.hex_num),
-[`lexer.oct_num`](#lexer.oct_num), [`lexer.integer`](#lexer.integer), [`lexer.float`](#lexer.float),
-[`lexer.number`](#lexer.number), and [`lexer.word`](#lexer.word). You may use your own token names if
-none of the above fit your language, but an advantage to using predefined
-token names is that your lexer's tokens will inherit the universal syntax
-highlighting color theme used by your text editor.
+The `lexer` module actually provides a convenient list of common token names and common LPeg
+patterns for you to use. Token names include [`lexer.DEFAULT`](#lexer.DEFAULT), [`lexer.WHITESPACE`](#lexer.WHITESPACE),
+[`lexer.COMMENT`](#lexer.COMMENT), [`lexer.STRING`](#lexer.STRING), [`lexer.NUMBER`](#lexer.NUMBER), [`lexer.KEYWORD`](#lexer.KEYWORD),
+[`lexer.IDENTIFIER`](#lexer.IDENTIFIER), [`lexer.OPERATOR`](#lexer.OPERATOR), [`lexer.ERROR`](#lexer.ERROR), [`lexer.PREPROCESSOR`](#lexer.PREPROCESSOR),
+[`lexer.CONSTANT`](#lexer.CONSTANT), [`lexer.VARIABLE`](#lexer.VARIABLE), [`lexer.FUNCTION`](#lexer.FUNCTION), [`lexer.CLASS`](#lexer.CLASS),
+[`lexer.TYPE`](#lexer.TYPE), [`lexer.LABEL`](#lexer.LABEL), [`lexer.REGEX`](#lexer.REGEX), and [`lexer.EMBEDDED`](#lexer.EMBEDDED). Patterns
+include [`lexer.any`](#lexer.any), [`lexer.alpha`](#lexer.alpha), [`lexer.digit`](#lexer.digit), [`lexer.alnum`](#lexer.alnum),
+[`lexer.lower`](#lexer.lower), [`lexer.upper`](#lexer.upper), [`lexer.xdigit`](#lexer.xdigit), [`lexer.graph`](#lexer.graph), [`lexer.print`](#lexer.print),
+[`lexer.punct`](#lexer.punct), [`lexer.space`](#lexer.space), [`lexer.newline`](#lexer.newline), [`lexer.nonnewline`](#lexer.nonnewline),
+[`lexer.dec_num`](#lexer.dec_num), [`lexer.hex_num`](#lexer.hex_num), [`lexer.oct_num`](#lexer.oct_num), [`lexer.integer`](#lexer.integer),
+[`lexer.float`](#lexer.float), [`lexer.number`](#lexer.number), and [`lexer.word`](#lexer.word). You may use your own token names
+if none of the above fit your language, but an advantage to using predefined token names is
+that your lexer's tokens will inherit the universal syntax highlighting color theme used by
+your text editor.
##### Example Tokens
-So, how might you define other tokens like keywords, comments, and strings?
-Here are some examples.
+So, how might you define other tokens like keywords, comments, and strings? Here are some
+examples.
**Keywords**
-Instead of matching _n_ keywords with _n_ `P('keyword_`_`n`_`')` ordered
-choices, use another convenience function: [`lexer.word_match()`](#lexer.word_match). It is
-much easier and more efficient to write word matches like:
+Instead of matching _n_ keywords with _n_ `P('keyword_`_`n`_`')` ordered choices, use another
+convenience function: [`lexer.word_match()`](#lexer.word_match). It is much easier and more efficient to
+write word matches like:
- local keyword = token(lexer.KEYWORD, lexer.word_match[[
- keyword_1 keyword_2 ... keyword_n
- ]])
+ local keyword = token(lexer.KEYWORD, lexer.word_match{
+ 'keyword_1', 'keyword_2', ..., 'keyword_n'
+ })
- local case_insensitive_keyword = token(lexer.KEYWORD, lexer.word_match([[
- KEYWORD_1 keyword_2 ... KEYword_n
- ]], true))
+ local case_insensitive_keyword = token(lexer.KEYWORD, lexer.word_match({
+ 'KEYWORD_1', 'keyword_2', ..., 'KEYword_n'
+ }, true))
- local hyphened_keyword = token(lexer.KEYWORD, lexer.word_match[[
- keyword-1 keyword-2 ... keyword-n
- ]])
+ local hyphened_keyword = token(lexer.KEYWORD, lexer.word_match{
+ 'keyword-1', 'keyword-2', ..., 'keyword-n'
+ })
-In order to more easily separate or categorize keyword sets, you can use Lua
-line comments within keyword strings. Such comments will be ignored. For
-example:
+For short keyword lists, you can use a single string of words. For example:
- local keyword = token(lexer.KEYWORD, lexer.word_match[[
- -- Version 1 keywords.
- keyword_11, keyword_12 ... keyword_1n
- -- Version 2 keywords.
- keyword_21, keyword_22 ... keyword_2n
- ...
- -- Version N keywords.
- keyword_m1, keyword_m2 ... keyword_mn
- ]])
+ local keyword = token(lexer.KEYWORD, lexer.word_match('key_1 key_2 ... key_n'))
**Comments**
@@ -4856,37 +4648,33 @@ Line-style comments with a prefix character(s) are easy to express with LPeg:
local shell_comment = token(lexer.COMMENT, lexer.to_eol('#'))
local c_line_comment = token(lexer.COMMENT, lexer.to_eol('//', true))
-The comments above start with a '#' or "//" and go to the end of the line.
-The second comment recognizes the next line also as a comment if the current
-line ends with a '\' escape character.
+The comments above start with a '#' or "//" and go to the end of the line. The second comment
+recognizes the next line also as a comment if the current line ends with a '\' escape character.
-C-style "block" comments with a start and end delimiter are also easy to
-express:
+C-style "block" comments with a start and end delimiter are also easy to express:
local c_comment = token(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.
+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 "\\&quot;" in a double-quoted string indicates that the
-'&quot;' is not the end of the string. [`lexer.range()`](#lexer.range) handles escapes
-inherently.
+Most programming languages allow escape sequences in strings such that a sequence like
+"\\&quot;" in a double-quoted string indicates that the '&quot;' is not the end of the
+string. [`lexer.range()`](#lexer.range) handles escapes inherently.
local dq_str = lexer.range('"')
local sq_str = lexer.range("'")
local string = token(lexer.STRING, dq_str + sq_str)
-In this case, the lexer treats '\' as an escape character in a string
-sequence.
+In this case, the lexer treats '\' as an escape character in a string sequence.
**Numbers**
-Most programming languages have the same format for integer and float tokens,
-so it might be as simple as using a predefined LPeg pattern:
+Most programming languages have the same format for integer and float tokens, so it might
+be as simple as using a predefined LPeg pattern:
local number = token(lexer.NUMBER, lexer.number)
@@ -4895,28 +4683,24 @@ However, some languages allow postfix characters on integers.
local integer = P('-')^-1 * (lexer.dec_num * S('lL')^-1)
local number = token(lexer.NUMBER, lexer.float + lexer.hex_num + integer)
-Your language may need other tweaks, but it is up to you how fine-grained you
-want your highlighting to be. After all, you are not writing a compiler or
-interpreter!
+Your language may need other tweaks, but it is up to you how fine-grained you want your
+highlighting to be. After all, you are not writing a compiler or interpreter!
#### Rules
-Programming languages have grammars, which specify valid token structure. For
-example, comments usually cannot appear within a string. Grammars consist of
-rules, which are simply combinations of tokens. Recall from the lexer
-template the [`lexer.add_rule()`](#lexer.add_rule) call, which adds a rule to the lexer's
-grammar:
+Programming languages have grammars, which specify valid token structure. For example,
+comments usually cannot appear within a string. Grammars consist of rules, which are simply
+combinations of tokens. Recall from the lexer template the [`lexer.add_rule()`](#lexer.add_rule) call,
+which adds a rule to the lexer's grammar:
lex:add_rule('whitespace', ws)
-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 whitespace tokens under a rule named "whitespace".
+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 whitespace tokens under a rule named "whitespace".
-To illustrate the importance of rule order, here is an example of a
-simplified Lua lexer:
+To illustrate the importance of rule order, here is an example of a simplified Lua lexer:
lex:add_rule('whitespace', token(lexer.WHITESPACE, ...))
lex:add_rule('keyword', token(lexer.KEYWORD, ...))
@@ -4927,73 +4711,65 @@ simplified Lua lexer:
lex:add_rule('label', token(lexer.LABEL, ...))
lex:add_rule('operator', token(lexer.OPERATOR, ...))
-Note how identifiers come after keywords. In Lua, as with most programming
-languages, the characters allowed in keywords and identifiers are in the same
-set (alphanumerics plus underscores). If the lexer added the "identifier"
-rule before the "keyword" rule, all keywords would match identifiers and thus
-incorrectly highlight as identifiers instead of keywords. The same idea
-applies to function, constant, etc. tokens that you may want to distinguish
-between: their rules should come before identifiers.
+Note how identifiers come after keywords. In Lua, as with most programming languages,
+the characters allowed in keywords and identifiers are in the same set (alphanumerics
+plus underscores). If the lexer added the "identifier" rule before the "keyword" rule,
+all keywords would match identifiers and thus incorrectly highlight as identifiers instead
+of keywords. The same idea applies to function, constant, etc. tokens that you may want to
+distinguish between: their rules should come before identifiers.
-So what about text that does not match any rules? For example in Lua, the '!'
-character is meaningless outside a string or comment. Normally the lexer
-skips over such text. If instead you want to highlight these "syntax errors",
-add an additional end rule:
+So what about text that does not match any rules? For example in Lua, the '!' character is
+meaningless outside a string or comment. Normally the lexer skips over such text. If instead
+you want to highlight these "syntax errors", add an additional end rule:
lex:add_rule('whitespace', ws)
...
lex:add_rule('error', token(lexer.ERROR, lexer.any))
-This identifies and highlights any character not matched by an existing
-rule as a `lexer.ERROR` token.
+This identifies and highlights any character not matched by an existing rule as a `lexer.ERROR`
+token.
-Even though the rules defined in the examples above contain a single token,
-rules may consist of multiple tokens. For example, a rule for an HTML tag
-could consist of a tag token followed by an arbitrary number of attribute
-tokens, allowing the lexer to highlight all tokens separately. That rule
-might look something like this:
+Even though the rules defined in the examples above contain a single token, rules may
+consist of multiple tokens. For example, a rule for an HTML tag could consist of a tag token
+followed by an arbitrary number of attribute tokens, allowing the lexer to highlight all
+tokens separately. That rule might look something like this:
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.
+Note however that lexers with complex rules like these are more prone to lose track of their
+state, especially if they span multiple lines.
#### Summary
-Lexers primarily consist of tokens and grammar rules. At your disposal are a
-number of convenience patterns and functions for rapidly creating a lexer. If
-you choose to use predefined token names for your tokens, you do not have to
-define how the lexer highlights them. The tokens will inherit the default
-syntax highlighting color theme your editor uses.
+Lexers primarily consist of tokens and grammar rules. At your disposal are a number of
+convenience patterns and functions for rapidly creating a lexer. If you choose to use
+predefined token names for your tokens, you do not have to define how the lexer highlights
+them. The tokens will inherit the default syntax highlighting color theme your editor uses.
### Advanced Techniques
#### Styles and Styling
-The most basic form of syntax highlighting is assigning different colors to
-different tokens. Instead of highlighting with just colors, Scintilla allows
-for more rich highlighting, or "styling", with different fonts, font sizes,
-font attributes, and foreground and background colors, just to name a few.
-The unit of this rich highlighting is called a "style". Styles are simply Lua
-tables of properties. By default, lexers associate predefined token names
-like `lexer.WHITESPACE`, `lexer.COMMENT`, `lexer.STRING`, etc. with
-particular styles as part of a universal color theme. These predefined styles
-are contained in [`lexer.styles`](#lexer.styles), and you may define your own styles. See
-that table's documentation for more information. As with token names,
-LPeg patterns, and styles, there is a set of predefined color names, but they
-vary depending on the current color theme in use. Therefore, it is generally
-not a good idea to manually define colors within styles in your lexer since
-they might not fit into a user's chosen color theme. Try to refrain from even
-using predefined colors in a style because that color may be theme-specific.
-Instead, the best practice is to either use predefined styles or derive new
-color-agnostic styles from predefined ones. For example, Lua "longstring"
-tokens use the existing `lexer.styles.string` style instead of defining a new
-one.
+The most basic form of syntax highlighting is assigning different colors to different
+tokens. Instead of highlighting with just colors, Scintilla allows for more rich highlighting,
+or "styling", with different fonts, font sizes, font attributes, and foreground and background
+colors, just to name a few. The unit of this rich highlighting is called a "style". Styles
+are simply Lua tables of properties. By default, lexers associate predefined token names like
+`lexer.WHITESPACE`, `lexer.COMMENT`, `lexer.STRING`, etc. with particular styles as part
+of a universal color theme. These predefined styles are contained in [`lexer.styles`](#lexer.styles),
+and you may define your own styles. See that table's documentation for more information. As
+with token names, LPeg patterns, and styles, there is a set of predefined color names,
+but they vary depending on the current color theme in use. Therefore, it is generally not
+a good idea to manually define colors within styles in your lexer since they might not fit
+into a user's chosen color theme. Try to refrain from even using predefined colors in a
+style because that color may be theme-specific. Instead, the best practice is to either use
+predefined styles or derive new color-agnostic styles from predefined ones. For example, Lua
+"longstring" tokens use the existing `lexer.styles.string` style instead of defining a new one.
##### Example Styles
-Defining styles is pretty straightforward. An empty style that inherits the
-default theme settings is simply an empty table:
+Defining styles is pretty straightforward. An empty style that inherits the default theme
+settings is simply an empty table:
local style_nothing = {}
@@ -5001,28 +4777,26 @@ A similar style but with a bold font face looks like this:
local style_bold = {bold = true}
-You can derive new styles from predefined ones without having to rewrite
-them. This operation leaves the old style unchanged. For example, if you had
-a "static variable" token whose style you wanted to base off of
-`lexer.styles.variable`, it would probably look like:
+You can derive new styles from predefined ones without having to rewrite them. This operation
+leaves the old style unchanged. For example, if you had a "static variable" token whose
+style you wanted to base off of `lexer.styles.variable`, it would probably look like:
local style_static_var = lexer.styles.variable .. {italics = true}
-The color theme files in the *lexers/themes/* folder give more examples of
-style definitions.
+The color theme files in the *lexers/themes/* folder give more examples of style definitions.
#### Token Styles
-Lexers use the [`lexer.add_style()`](#lexer.add_style) function to assign styles to
-particular tokens. Recall the token definition and from the lexer template:
+Lexers use the [`lexer.add_style()`](#lexer.add_style) function to assign styles to particular tokens. Recall
+the token definition and from the lexer template:
local ws = token(lexer.WHITESPACE, lexer.space^1)
lex:add_rule('whitespace', ws)
-Why is a style not assigned to the `lexer.WHITESPACE` token? As mentioned
-earlier, lexers automatically associate tokens that use predefined token
-names with a particular style. Only tokens with custom token names need
-manual style associations. As an example, consider a custom whitespace token:
+Why is a style not assigned to the `lexer.WHITESPACE` token? As mentioned earlier, lexers
+automatically associate tokens that use predefined token names with a particular style. Only
+tokens with custom token names need manual style associations. As an example, consider a
+custom whitespace token:
local ws = token('custom_whitespace', lexer.space^1)
@@ -5030,98 +4804,87 @@ Assigning a style to this token looks like:
lex:add_style('custom_whitespace', lexer.styles.whitespace)
-Do not confuse token names with rule names. They are completely different
-entities. In the example above, the lexer associates the "custom_whitespace"
-token with the existing style for `lexer.WHITESPACE` tokens. If instead you
-prefer to color the background of whitespace a shade of grey, it might look
-like:
+Do not confuse token names with rule names. They are completely different entities. In the
+example above, the lexer associates the "custom_whitespace" token with the existing style
+for `lexer.WHITESPACE` tokens. If instead you prefer to color the background of whitespace
+a shade of grey, it might look like:
- lex:add_style('custom_whitespace',
- lexer.styles.whitespace .. {back = lexer.colors.grey})
+ lex:add_style('custom_whitespace', lexer.styles.whitespace .. {back = lexer.colors.grey})
-Remember to refrain from assigning specific colors in styles, but in this
-case, all user color themes probably define `colors.grey`.
+Remember to refrain from assigning specific colors in styles, but in this case, all user
+color themes probably define `colors.grey`.
#### Line Lexers
-By default, lexers match the arbitrary chunks of text passed to them by
-Scintilla. These chunks may be a full document, only the visible part of a
-document, or even just portions of lines. Some lexers need to match whole
-lines. For example, a lexer for the output of a file "diff" needs to know if
-the line started with a '+' or '-' and then style the entire line
-accordingly. To indicate that your lexer matches by line, create the lexer
-with an extra parameter:
+By default, lexers match the arbitrary chunks of text passed to them by Scintilla. These
+chunks may be a full document, only the visible part of a document, or even just portions
+of lines. Some lexers need to match whole lines. For example, a lexer for the output of a
+file "diff" needs to know if the line started with a '+' or '-' and then style the entire
+line accordingly. To indicate that your lexer matches by line, create the lexer with an
+extra parameter:
local lex = lexer.new('?', {lex_by_line = true})
-Now the input text for the lexer is a single line at a time. Keep in mind
-that line lexers do not have the ability to look ahead at subsequent lines.
+Now the input text for the lexer is a single line at a time. Keep in mind that line lexers
+do not have the ability to look ahead at subsequent lines.
#### Embedded Lexers
-Lexers embed within one another very easily, requiring minimal effort. In the
-following sections, the lexer being embedded is called the "child" lexer and
-the lexer a child is being embedded in is called the "parent". For example,
-consider an HTML lexer and a CSS lexer. Either lexer stands alone for styling
-their respective HTML and CSS files. However, CSS can be embedded inside
-HTML. In this specific case, the CSS lexer is the "child" lexer with the HTML
-lexer being the "parent". Now consider an HTML lexer and a PHP lexer. This
-sounds a lot like the case with CSS, but there is a subtle difference: PHP
-_embeds itself into_ HTML while CSS is _embedded in_ HTML. This fundamental
-difference results in two types of embedded lexers: a parent lexer that
-embeds other child lexers in it (like HTML embedding CSS), and a child lexer
-that embeds itself into a parent lexer (like PHP embedding itself in HTML).
+Lexers embed within one another very easily, requiring minimal effort. In the following
+sections, the lexer being embedded is called the "child" lexer and the lexer a child is
+being embedded in is called the "parent". For example, consider an HTML lexer and a CSS
+lexer. Either lexer stands alone for styling their respective HTML and CSS files. However, CSS
+can be embedded inside HTML. In this specific case, the CSS lexer is the "child" lexer with
+the HTML lexer being the "parent". Now consider an HTML lexer and a PHP lexer. This sounds
+a lot like the case with CSS, but there is a subtle difference: PHP _embeds itself into_
+HTML while CSS is _embedded in_ HTML. This fundamental difference results in two types of
+embedded lexers: a parent lexer that embeds other child lexers in it (like HTML embedding CSS),
+and a child lexer that embeds itself into a parent lexer (like PHP embedding itself in HTML).
##### Parent Lexer
-Before embedding a child lexer into a parent lexer, the parent lexer needs to
-load the child lexer. This is done with the [`lexer.load()`](#lexer.load) function. For
-example, loading the CSS lexer within the HTML lexer looks like:
+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()`](#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":
+The next part of the embedding process is telling the parent lexer when to switch over
+to the child lexer and when to switch back. The lexer refers to these indications as the
+"start rule" and "end rule", respectively, and are just LPeg patterns. Continuing with the
+HTML/CSS example, the transition from HTML to CSS is when the lexer encounters a "style"
+tag with a "type" attribute whose value is "text/css":
local css_tag = P('<style') * P(function(input, index)
- if input:find('^[^>]+type="text/css"', index) then
- return index
- end
+ if input:find('^[^>]+type="text/css"', index) then return index end
end)
-This pattern looks for the beginning of a "style" tag and searches its
-attribute list for the text "`type="text/css"`". (In this simplified example,
-the Lua pattern does not consider whitespace between the '=' nor does it
-consider that using single quotes is valid.) If there is a match, the
-functional pattern returns a value instead of `nil`. In this case, the value
-returned does not matter because we ultimately want to style the "style" tag
-as an HTML tag, so the actual start rule looks like this:
+This pattern looks for the beginning of a "style" tag and searches its attribute list for
+the text "`type="text/css"`". (In this simplified example, the Lua pattern does not consider
+whitespace between the '=' nor does it consider that using single quotes is valid.) If there
+is a match, the functional pattern returns a value instead of `nil`. In this case, the value
+returned does not matter because we ultimately want to style the "style" tag as an HTML tag,
+so the actual start rule looks like this:
local css_start_rule = #css_tag * tag
-Now that the parent knows when to switch to the child, it needs to know when
-to switch back. In the case of HTML/CSS, the switch back occurs when the
-lexer encounters an ending "style" tag, though the lexer should still style
-the tag as an HTML tag:
+Now that the parent knows when to switch to the child, it needs to know when to switch
+back. In the case of HTML/CSS, the switch back occurs when the lexer encounters an ending
+"style" tag, though the lexer should still style the tag as an HTML tag:
local css_end_rule = #P('</style>') * tag
-Once the parent loads the child lexer and defines the child's start and end
-rules, it embeds the child with the [`lexer.embed()`](#lexer.embed) function:
+Once the parent loads the child lexer and defines the child's start and end rules, it embeds
+the child with the [`lexer.embed()`](#lexer.embed) function:
lex:embed(css, css_start_rule, css_end_rule)
##### Child Lexer
-The process for instructing a child lexer to embed itself into a parent is
-very similar to embedding a child into a parent: first, load the parent lexer
-into the child lexer with the [`lexer.load()`](#lexer.load) function and then create
-start and end rules for the child lexer. However, in this case, call
-[`lexer.embed()`](#lexer.embed) with switched arguments. For example, in the PHP lexer:
+The process for instructing a child lexer to embed itself into a parent is very similar to
+embedding a child into a parent: first, load the parent lexer into the child lexer with the
+[`lexer.load()`](#lexer.load) function and then create start and end rules for the child lexer. However,
+in this case, call [`lexer.embed()`](#lexer.embed) with switched arguments. For example, in the PHP lexer:
local html = lexer.load('html')
local php_start_rule = token('php_tag', '<?php ')
@@ -5131,47 +4894,40 @@ start and end rules for the child lexer. However, in this case, call
#### Lexers with Complex State
-A vast majority of lexers are not stateful and can operate on any chunk of
-text in a document. However, there may be rare cases where a lexer does need
-to keep track of some sort of persistent state. Rather than using `lpeg.P`
-function patterns that set state variables, it is recommended to make use of
-Scintilla's built-in, per-line state integers via [`lexer.line_state`](#lexer.line_state). It
-was designed to accommodate up to 32 bit flags for tracking state.
-[`lexer.line_from_position()`](#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.)
+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`](#lexer.line_state). It was designed to accommodate up to 32 bit flags for tracking state.
+[`lexer.line_from_position()`](#lexer.line_from_position) will return the line for any position given to an `lpeg.P`
+function pattern. (Any positions derived from that position argument will also work.)
Writing stateful lexers is beyond the scope of this document.
### Code Folding
-When reading source code, it is occasionally helpful to temporarily hide
-blocks of code like functions, classes, comments, etc. This is the concept of
-"folding". In the Textadept and SciTE editors for example, little indicators
-in the editor margins appear next to code that can be folded at places called
-"fold points". When the user clicks an indicator, the editor hides the code
-associated with the indicator until the user clicks the indicator again. The
+When reading source code, it is occasionally helpful to temporarily hide blocks of code like
+functions, classes, comments, etc. This is the concept of "folding". In the Textadept and
+SciTE editors for example, little indicators in the editor margins appear next to code that
+can be folded at places called "fold points". When the user clicks an indicator, the editor
+hides the code associated with the indicator until the user clicks the indicator again. The
lexer specifies these fold points and what code exactly to fold.
-The fold points for most languages occur on keywords or character sequences.
-Examples of fold keywords are "if" and "end" in Lua and examples of fold
-character sequences are '{', '}', "/\*", and "\*/" in C for code block and
-comment delimiters, respectively. However, these fold points cannot occur
-just anywhere. For example, lexers should not recognize fold keywords that
-appear within strings or comments. The [`lexer.add_fold_point()`](#lexer.add_fold_point) function
-allows you to conveniently define fold points with such granularity. For
-example, consider C:
+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()`](#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 recognized as
-an `lexer.OPERATOR` token is a fold point. Likewise, the second assignment
-states that any "/\*" or "\*/" that the lexer recognizes as part of a
-`lexer.COMMENT` token is a fold point. The lexer does not consider any
-occurrences of these characters outside their defined tokens (such as in a
-string) as fold points. How do you specify fold keywords? Here is an example
-for Lua:
+The first assignment states that any '{' or '}' that the lexer recognized as an `lexer.OPERATOR`
+token is a fold point. Likewise, the second assignment states that any "/\*" or "\*/" that
+the lexer recognizes as part of a `lexer.COMMENT` token is a fold point. The lexer does
+not consider any occurrences of these characters outside their defined tokens (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')
@@ -5179,14 +4935,13 @@ for Lua:
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()`](#lexer.new), and
-specify keywords in lower case.
+`case_insensitive_fold_points = true` option to [`lexer.new()`](#lexer.new), and specify keywords in
+lower case.
-If your lexer needs to do some additional processing in order to determine if
-a token is a fold point, pass a function that returns an integer to
-`lex:add_fold_point()`. Returning `1` indicates the token is a beginning fold
-point and returning `-1` indicates the token is an ending fold point.
-Returning `0` indicates the token is not a fold point. For example:
+If your lexer needs to do some additional processing in order to determine if a token is
+a fold point, pass a function that returns an integer to `lex:add_fold_point()`. Returning
+`1` indicates the token is a beginning fold point and returning `-1` indicates the token is
+an ending fold point. Returning `0` indicates the token is not a fold point. For example:
local function fold_strange_token(text, pos, line, s, symbol)
if ... then
@@ -5199,19 +4954,17 @@ Returning `0` indicates the token is not a fold point. For example:
lex:add_fold_point('strange_token', '|', fold_strange_token)
-Any time the lexer encounters a '|' that is a "strange_token", it calls the
-`fold_strange_token` function to determine if '|' is a fold point. The lexer
-calls these functions with the following arguments: the text to identify fold
-points in, the beginning position of the current line in the text to fold,
-the current line's text, the position in the current line the fold point text
-starts at, and the fold point text itself.
+Any time the lexer encounters a '|' that is a "strange_token", it calls the `fold_strange_token`
+function to determine if '|' is a fold point. The lexer calls these functions with the
+following arguments: the text to identify fold points in, the beginning position of the
+current line in the text to fold, the current line's text, the position in the current line
+the fold point text starts at, and the fold point text itself.
#### Fold by Indentation
-Some languages have significant whitespace and/or no delimiters that indicate
-fold points. If your lexer falls into this category and you would like to
-mark fold points based on changes in indentation, create the lexer with a
-`fold_by_indentation = true` option:
+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})
@@ -5219,28 +4972,25 @@ mark fold points based on changes in indentation, create the lexer with a
**Textadept**
-Put your lexer in your *~/.textadept/lexers/* directory so you do not
-overwrite it when upgrading Textadept. Also, lexers in this directory
-override default lexers. Thus, Textadept loads a user *lua* lexer instead of
-the default *lua* lexer. This is convenient for tweaking a default lexer to
-your liking. Then add a [file type](#textadept.file_types) for your lexer if
-necessary.
+Put your lexer in your *~/.textadept/lexers/* directory so you do not overwrite it when
+upgrading Textadept. Also, lexers in this directory override default lexers. Thus, Textadept
+loads a user *lua* lexer instead of the default *lua* lexer. This is convenient for tweaking
+a default lexer to your liking. Then add a [file type](#textadept.file_types) 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:
+Create a *.properties* file for your lexer and `import` it in either your *SciTEUser.properties*
+or *SciTEGlobal.properties*. The contents of the *.properties* file should contain:
file.patterns.[lexer_name]=[file_patterns]
lexer.$(file.patterns.[lexer_name])=[lexer_name]
-where `[lexer_name]` is the name of your lexer (minus the *.lua* extension)
-and `[file_patterns]` is a set of file extensions to use your lexer for.
+where `[lexer_name]` is the name of your lexer (minus the *.lua* extension) and
+`[file_patterns]` is a set of file extensions to use your lexer for.
-Please note that Lua lexers ignore any styling information in *.properties*
-files. Your theme file in the *lexers/themes/* directory contains styling
-information.
+Please note that Lua lexers ignore any styling information in *.properties* files. Your
+theme file in the *lexers/themes/* directory contains styling information.
### Migrating Legacy Lexers
@@ -5272,34 +5022,27 @@ Legacy lexers are of the form:
return M
-While Scintillua will handle such legacy lexers just fine without any
-changes, it is recommended that you migrate yours. The migration process is
-fairly straightforward:
-
-1. Replace all instances of `l` with `lexer`, as it's better practice and
- results in less confusion.
-2. Replace `local M = {_NAME = '?'}` with `local lex = lexer.new('?')`, where
- `?` is the name of your legacy lexer. At the end of the lexer, change
- `return M` to `return lex`.
-3. Instead of defining rules towards the end of your lexer, define your rules
- as you define your tokens and patterns using
- [`lex:add_rule()`](#lexer.add_rule).
-4. Similarly, any custom token names should have their styles immediately
- defined using [`lex:add_style()`](#lexer.add_style).
-5. Convert any table arguments passed to [`lexer.word_match()`](#lexer.word_match) to a
+While Scintillua will handle such legacy lexers just fine without any changes, it is
+recommended that you migrate yours. The migration process is fairly straightforward:
+
+1. Replace all instances of `l` with `lexer`, as it's better practice and results in less
+ confusion.
+2. Replace `local M = {_NAME = '?'}` with `local lex = lexer.new('?')`, where `?` is the
+ name of your legacy lexer. At the end of the lexer, change `return M` to `return lex`.
+3. Instead of defining rules towards the end of your lexer, define your rules as you define
+ your tokens and patterns using [`lex:add_rule()`](#lexer.add_rule).
+4. Similarly, any custom token names should have their styles immediately defined using
+ [`lex:add_style()`](#lexer.add_style).
+5. Optionally convert any table arguments passed to [`lexer.word_match()`](#lexer.word_match) to a
space-separated string of words.
-6. Replace any calls to `lexer.embed(M, child, ...)` and
- `lexer.embed(parent, M, ...)` with
- [`lex:embed`](#lexer.embed)`(child, ...)` and `parent:embed(lex, ...)`,
- respectively.
-7. Define fold points with simple calls to
- [`lex:add_fold_point()`](#lexer.add_fold_point). No need to mess with Lua
- patterns anymore.
-8. Any legacy lexer options such as `M._FOLDBYINDENTATION`, `M._LEXBYLINE`,
- `M._lexer`, etc. should be added as table options to [`lexer.new()`](#lexer.new).
-9. Any external lexer rule fetching and/or modifications via `lexer._RULES`
- should be changed to use [`lexer.get_rule()`](#lexer.get_rule) and
- [`lexer.modify_rule()`](#lexer.modify_rule).
+6. Replace any calls to `lexer.embed(M, child, ...)` and `lexer.embed(parent, M, ...)` with
+ [`lex:embed`](#lexer.embed)`(child, ...)` and `parent:embed(lex, ...)`, respectively.
+7. Define fold points with simple calls to [`lex:add_fold_point()`](#lexer.add_fold_point). No
+ need to mess with Lua patterns anymore.
+8. Any legacy lexer options such as `M._FOLDBYINDENTATION`, `M._LEXBYLINE`, `M._lexer`,
+ etc. should be added as table options to [`lexer.new()`](#lexer.new).
+9. Any external lexer rule fetching and/or modifications via `lexer._RULES` should be changed
+ to use [`lexer.get_rule()`](#lexer.get_rule) and [`lexer.modify_rule()`](#lexer.modify_rule).
As an example, consider the following sample legacy lexer:
@@ -5349,8 +5092,8 @@ Following the migration steps would yield:
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', P('quux')))
+ 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('"')))
@@ -5366,25 +5109,23 @@ Following the migration steps would yield:
#### Performance
-There might be some slight overhead when initializing a lexer, but loading a
-file from disk into Scintilla is usually more expensive. On modern computer
-systems, I see no difference in speed between 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.
+There might be some slight overhead when initializing a lexer, but loading a file from disk
+into Scintilla is usually more expensive. On modern computer systems, I see no difference in
+speed between 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.
+In some cases, folding may be far more expensive than lexing, particularly in lexers with a
+lot of potential fold points. If your lexer is exhibiting signs of slowness, try disabling
+folding in your text editor first. If that speeds things up, you can try reducing the number
+of fold points you added, overriding `lexer.fold()` with your own implementation, or simply
+eliminating folding support from your lexer.
#### Limitations
-Embedded preprocessor languages like PHP cannot completely embed in their
-parent languages in that the parent's tokens do not support start and end
-rules. This mostly goes unnoticed, but code like
+Embedded preprocessor languages like PHP cannot completely embed in their parent languages
+in that the parent's tokens do not support start and end rules. This mostly goes unnoticed,
+but code like
<div id="<?php echo $id; ?>">
@@ -5392,23 +5133,22 @@ will not style correctly.
#### Troubleshooting
-Errors in lexers can be tricky to debug. Lexers print Lua errors to
-`io.stderr` and `_G.print()` statements to `io.stdout`. Running your editor
-from a terminal is the easiest way to see errors as they occur.
+Errors in lexers can be tricky to debug. Lexers print Lua errors to `io.stderr` and `_G.print()`
+statements to `io.stdout`. Running your editor from a terminal is the easiest way to see
+errors as they occur.
#### Risks
-Poorly written lexers have the ability to crash Scintilla (and thus its
-containing application), so unsaved data might be lost. However, I have only
-observed these crashes in early lexer development, when syntax errors or
-pattern errors are present. Once the lexer actually starts styling text
-(either correctly or incorrectly, it does not matter), I have not observed
+Poorly written lexers have the ability to crash Scintilla (and thus its containing application),
+so unsaved data might be lost. However, I have only observed these crashes in early lexer
+development, when syntax errors or pattern errors are present. Once the lexer actually starts
+styling text (either correctly or incorrectly, it does not matter), I have not observed
any crashes.
#### Acknowledgements
-Thanks to Peter Odding for his [lexer post][] on the Lua mailing list
-that provided inspiration, and thanks to Roberto Ierusalimschy for LPeg.
+Thanks to Peter Odding for his [lexer post][] on the Lua mailing list that provided inspiration,
+and thanks to Roberto Ierusalimschy for LPeg.
[lexer post]: http://lua-users.org/lists/lua-l/2007-04/msg00116.html
@@ -5517,8 +5257,7 @@ The token name for whitespace tokens.
<a id="lexer.alnum"></a>
#### `lexer.alnum` (pattern)
-A pattern that matches any alphanumeric character ('A'-'Z', 'a'-'z',
- '0'-'9').
+A pattern that matches any alphanumeric character ('A'-'Z', 'a'-'z', '0'-'9').
<a id="lexer.alpha"></a>
#### `lexer.alpha` (pattern)
@@ -5580,8 +5319,7 @@ Whether or not blank lines after an ending fold point are included in that
#### `lexer.fold_level` (table, Read-only)
Table of fold level bit-masks for line numbers starting from 1.
- Fold level masks are composed of an integer level combined with any of the
- following bits:
+ Fold level masks are composed of an integer level combined with any of the following bits:
* `lexer.FOLD_BASE`
The initial fold level.
@@ -5593,19 +5331,18 @@ Table of fold level bit-masks for line numbers starting from 1.
<a id="lexer.fold_line_groups"></a>
#### `lexer.fold_line_groups` (boolean)
-Whether or not to fold multiple, consecutive line groups (such as line
- comments and import statements) and only show the top line.
+Whether or not to fold multiple, consecutive line groups (such as line comments and import
+ statements) and only show the top line.
This option is disabled by default.
This is an alias for `lexer.property['fold.line.groups'] = '1|0'`.
<a id="lexer.fold_on_zero_sum_lines"></a>
#### `lexer.fold_on_zero_sum_lines` (boolean)
-Whether or not to mark as a fold point lines that contain both an ending
- and starting fold point. For example, `} else {` would be marked as a fold
- point.
- This option is disabled by default.
- This is an alias for `lexer.property['fold.on.zero.sum.lines'] = '1|0'`.
+Whether or not to mark as a fold point lines that contain both an ending and starting fold
+ point. For example, `} else {` would be marked as a fold point.
+ This option is disabled by default. This is an alias for
+ `lexer.property['fold.on.zero.sum.lines'] = '1|0'`.
<a id="lexer.folding"></a>
#### `lexer.folding` (boolean)
@@ -5627,8 +5364,7 @@ A pattern that matches a hexadecimal number.
<a id="lexer.indent_amount"></a>
#### `lexer.indent_amount` (table, Read-only)
-Table of indentation amounts in character columns, for line numbers
- starting from 1.
+Table of indentation amounts in character columns, for line numbers starting from 1.
<a id="lexer.integer"></a>
#### `lexer.integer` (pattern)
@@ -5659,8 +5395,8 @@ A pattern that matches any single, non-newline character.
<a id="lexer.number"></a>
#### `lexer.number` (pattern)
-A pattern that matches a typical number, either a floating point, decimal,
- hexadecimal, or octal number.
+A pattern that matches a typical number, either a floating point, decimal, hexadecimal,
+ or octal number.
<a id="lexer.oct_num"></a>
#### `lexer.oct_num` (pattern)
@@ -5680,26 +5416,23 @@ Map of key-value string pairs.
<a id="lexer.property_expanded"></a>
#### `lexer.property_expanded` (table, Read-only)
-Map of key-value string pairs with `$()` and `%()` variable replacement
- performed in values.
+Map of key-value string pairs with `$()` and `%()` variable replacement performed in values.
<a id="lexer.property_int"></a>
#### `lexer.property_int` (table, Read-only)
-Map of key-value pairs with values interpreted as numbers, or `0` if not
- found.
+Map of key-value pairs with values interpreted as numbers, or `0` if not found.
<a id="lexer.punct"></a>
#### `lexer.punct` (pattern)
-A pattern that matches any punctuation character ('!' to '/', ':' to '@',
- '[' to ''', '{' to '~').
+A pattern that matches any punctuation character ('!' to '/', ':' to '@', '[' to ''',
+ '{' to '~').
<a id="lexer.space"></a>
#### `lexer.space` (pattern)
-A pattern that matches any whitespace character ('\t', '\v', '\f', '\n',
- '\r', space).
+A pattern that matches any whitespace character ('\t', '\v', '\f', '\n', '\r', space).
<a id="lexer.style_at"></a>
#### `lexer.style_at` (table, Read-only)
@@ -5714,8 +5447,8 @@ A pattern that matches any upper case character ('A'-'Z').
<a id="lexer.word"></a>
#### `lexer.word` (pattern)
-A pattern that matches a typical word. Words begin with a letter or
- underscore and consist of alphanumeric and underscore characters.
+A pattern that matches a typical word. Words begin with a letter or underscore and consist
+ of alphanumeric and underscore characters.
<a id="lexer.xdigit"></a>
#### `lexer.xdigit` (pattern)
@@ -5728,18 +5461,15 @@ A pattern that matches any hexadecimal digit ('0'-'9', 'A'-'F', 'a'-'f').
<a id="lexer.add_fold_point"></a>
#### `lexer.add_fold_point`(*lexer, token\_name, start\_symbol, end\_symbol*)
-Adds to lexer *lexer* a fold point whose beginning and end tokens are string
-*token_name* tokens with string content *start_symbol* and *end_symbol*,
-respectively.
-In the event that *start_symbol* may or may not be a fold point depending on
-context, and that additional processing is required, *end_symbol* may be a
-function that ultimately returns `1` (indicating a beginning fold point),
-`-1` (indicating an ending fold point), or `0` (indicating no fold point).
-That function is passed the following arguments:
+Adds to lexer *lexer* a fold point whose beginning and end tokens are string *token_name*
+tokens with string content *start_symbol* and *end_symbol*, respectively.
+In the event that *start_symbol* may or may not be a fold point depending on context, and that
+additional processing is required, *end_symbol* may be a function that ultimately returns
+`1` (indicating a beginning fold point), `-1` (indicating an ending fold point), or `0`
+(indicating no fold point). That function is passed the following arguments:
* `text`: The text being processed for fold points.
- * `pos`: The position in *text* of the beginning of the line currently
- being processed.
+ * `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.
@@ -5749,29 +5479,27 @@ Parameters:
* *`lexer`*: The lexer to add a fold point to.
* *`token_name`*: The token name of text that indicates a fold point.
* *`start_symbol`*: The text that indicates the beginning of a fold point.
-* *`end_symbol`*: Either the text that indicates the end of a fold point, or
- a function that returns whether or not *start_symbol* is a beginning fold
- point (1), an ending fold point (-1), or not a fold point at all (0).
+* *`end_symbol`*: Either the text that indicates the end of a fold point, or a function that
+ returns whether or not *start_symbol* is a beginning fold point (1), an ending fold point
+ (-1), or not a fold point at all (0).
Usage:
* `lex:add_fold_point(lexer.OPERATOR, '{', '}')`
* `lex:add_fold_point(lexer.KEYWORD, 'if', 'end')`
* `lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('#'))`
-* `lex:add_fold_point('custom', function(text, pos, line, s, symbol)
- ... end)`
+* `lex:add_fold_point('custom', function(text, pos, line, s, symbol) ... end)`
<a id="lexer.add_rule"></a>
#### `lexer.add_rule`(*lexer, id, rule*)
-Adds pattern *rule* identified by string *id* to the ordered list of rules
-for lexer *lexer*.
+Adds pattern *rule* identified by string *id* to the ordered list of rules for lexer *lexer*.
Parameters:
* *`lexer`*: The lexer to add the given rule to.
-* *`id`*: The id associated with this rule. It does not have to be the same
- as the name passed to `token()`.
+* *`id`*: The id associated with this rule. It does not have to be the same as the name
+ passed to `token()`.
* *`rule`*: The LPeg pattern of the rule.
See also:
@@ -5788,22 +5516,20 @@ Associates string *token_name* in lexer *lexer* with style table *style*.
* `size`: Integer font size.
* `bold`: Whether or not the font face is bold. The default value is `false`.
* `weight`: Integer weight or boldness of a font, between 1 and 999.
-* `italics`: Whether or not the font face is italic. The default value is
- `false`.
-* `underlined`: Whether or not the font face is underlined. The default value
- is `false`.
+* `italics`: Whether or not the font face is italic. The default value is `false`.
+* `underlined`: Whether or not the font face is underlined. The default value is `false`.
* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.
* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.
-* `eolfilled`: Whether or not the background color extends to the end of the
- line. The default value is `false`.
-* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal,
- mixed case. The default value is `'m'`.
+* `eolfilled`: Whether or not the background color extends to the end of the line. The
+ default value is `false`.
+* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal, mixed case. The
+ default value is `'m'`.
* `visible`: Whether or not the text is visible. The default value is `true`.
-* `changeable`: Whether the text is changeable instead of read-only. The
- default value is `true`.
+* `changeable`: Whether the text is changeable instead of read-only. The default value is
+ `true`.
-Field values may also contain "$(property.name)" expansions for properties
-defined in Scintilla, theme files, etc.
+Field values may also contain "$(property.name)" expansions for properties defined in Scintilla,
+theme files, etc.
Parameters:
@@ -5814,24 +5540,20 @@ Parameters:
Usage:
* `lex:add_style('longstring', lexer.styles.string)`
-* `lex:add_style('deprecated_func', lexer.styles['function'] ..
- {italics = true}`
-* `lex:add_style('visible_ws', lexer.styles.whitespace ..
- {back = lexer.colors.grey}`
+* `lex:add_style('deprecated_func', lexer.styles['function'] .. {italics = true}`
+* `lex:add_style('visible_ws', lexer.styles.whitespace .. {back = lexer.colors.grey}`
<a id="lexer.embed"></a>
#### `lexer.embed`(*lexer, child, start\_rule, end\_rule*)
-Embeds child lexer *child* in parent lexer *lexer* using patterns
-*start_rule* and *end_rule*, which signal the beginning and end of the
-embedded lexer, respectively.
+Embeds child lexer *child* in parent lexer *lexer* using patterns *start_rule* and *end_rule*,
+which signal the beginning and end of the embedded lexer, respectively.
Parameters:
* *`lexer`*: The parent lexer.
* *`child`*: The child lexer.
-* *`start_rule`*: The pattern that signals the beginning of the embedded
- lexer.
+* *`start_rule`*: The pattern that signals the beginning of the embedded lexer.
* *`end_rule`*: The pattern that signals the end of the embedded lexer.
Usage:
@@ -5842,17 +5564,16 @@ Usage:
<a id="lexer.fold"></a>
#### `lexer.fold`(*lexer, text, start\_pos, start\_line, start\_level*)
-Determines fold points in a chunk of text *text* using lexer *lexer*,
-returning a table of fold levels associated with line numbers.
-*text* starts at position *start_pos* on line number *start_line* with a
-beginning fold level of *start_level* in the buffer.
+Determines fold points in a chunk of text *text* using lexer *lexer*, returning a table of
+fold levels associated with line numbers.
+*text* starts at position *start_pos* on line number *start_line* with a beginning fold
+level of *start_level* in the buffer.
Parameters:
* *`lexer`*: The lexer to fold text with.
* *`text`*: The text in the buffer to fold.
-* *`start_pos`*: The position in the buffer *text* starts at, counting from
- 1.
+* *`start_pos`*: The position in the buffer *text* starts at, counting from 1.
* *`start_line`*: The line number *text* starts on, counting from 1.
* *`start_level`*: The fold level *text* starts on.
@@ -5863,8 +5584,8 @@ Return:
<a id="lexer.fold_consecutive_lines"></a>
#### `lexer.fold_consecutive_lines`(*prefix*)
-Returns for `lexer.add_fold_point()` the parameters needed to fold
-consecutive lines that start with string *prefix*.
+Returns for `lexer.add_fold_point()` the parameters needed to fold consecutive lines that
+start with string *prefix*.
Parameters:
@@ -5874,8 +5595,7 @@ Usage:
* `lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('--'))`
* `lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('//'))`
-* `lex:add_fold_point(
- lexer.KEYWORD, lexer.fold_consecutive_lines('import'))`
+* `lex:add_fold_point(lexer.KEYWORD, lexer.fold_consecutive_lines('import'))`
<a id="lexer.get_rule"></a>
#### `lexer.get_rule`(*lexer, id*)
@@ -5894,8 +5614,8 @@ Return:
<a id="lexer.last_char_includes"></a>
#### `lexer.last_char_includes`(*s*)
-Creates and returns a pattern that verifies the first non-whitespace
-character behind the current match position is in string set *s*.
+Creates and returns a pattern that verifies the first non-whitespace character behind the
+current match position is in string set *s*.
Parameters:
@@ -5903,8 +5623,7 @@ Parameters:
Usage:
-* `local regex = lexer.last_char_includes('+-*!%^&|=,([{') *
- lexer.range('/')`
+* `local regex = lexer.last_char_includes('+-*!%^&|=,([{') * lexer.range('/')`
Return:
@@ -5913,16 +5632,15 @@ Return:
<a id="lexer.lex"></a>
#### `lexer.lex`(*lexer, text, init\_style*)
-Lexes a chunk of text *text* (that has an initial style number of
-*init_style*) using lexer *lexer*, returning a table of token names and
-positions.
+Lexes a chunk of text *text* (that has an initial style number of *init_style*) using lexer
+*lexer*, returning a table of token names and positions.
Parameters:
* *`lexer`*: The lexer to lex text with.
* *`text`*: The text in the buffer to lex.
-* *`init_style`*: The current style. Multiple-language lexers use this to
- determine which language to start lexing in.
+* *`init_style`*: The current style. Multiple-language lexers use this to determine which
+ language to start lexing in.
Return:
@@ -5931,8 +5649,8 @@ Return:
<a id="lexer.line_from_position"></a>
#### `lexer.line_from_position`(*pos*)
-Returns the line number (starting from 1) of the line that contains position
-*pos*, which starts from 1.
+Returns the line number (starting from 1) of the line that contains position *pos*, which
+starts from 1.
Parameters:
@@ -5946,20 +5664,18 @@ Return:
#### `lexer.load`(*name, alt\_name, cache*)
Initializes or loads and returns the lexer of string name *name*.
-Scintilla calls this function in order to load a lexer. Parent lexers also
-call this function in order to load child lexers and vice-versa. The user
-calls this function in order to load a lexer when using Scintillua as a Lua
-library.
+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:
* *`name`*: The name of the lexing language.
-* *`alt_name`*: The alternate name of the lexing language. This is useful for
- embedding the same child lexer with multiple sets of start and end tokens.
-* *`cache`*: Flag indicating whether or not to load lexers from the cache.
- This should only be `true` when initially loading a lexer (e.g. not from
- within another lexer for embedding purposes).
- The default value is `false`.
+* *`alt_name`*: The alternate name of the lexing language. This is useful for embedding the
+ same child lexer with multiple sets of start and end tokens.
+* *`cache`*: Flag indicating whether or not to load lexers from the cache. This should only
+ be `true` when initially loading a lexer (e.g. not from within another lexer for embedding
+ purposes). The default value is `false`.
Return:
@@ -5968,8 +5684,7 @@ Return:
<a id="lexer.modify_rule"></a>
#### `lexer.modify_rule`(*lexer, id, rule*)
-Replaces in lexer *lexer* the existing rule identified by string *id* with
-pattern *rule*.
+Replaces in lexer *lexer* the existing rule identified by string *id* with pattern *rule*.
Parameters:
@@ -5986,19 +5701,15 @@ Parameters:
* *`name`*: The lexer's name.
* *`opts`*: Table of lexer options. Options currently supported:
- * `lex_by_line`: Whether or not the lexer only processes whole lines of
- text (instead of arbitrary chunks of text) at a time.
- Line lexers cannot look ahead to subsequent lines.
- The default value is `false`.
- * `fold_by_indentation`: Whether or not the lexer does not define any fold
- points and that fold points should be calculated based on changes in line
- indentation.
+ * `lex_by_line`: Whether or not the lexer only processes whole lines of text (instead of
+ arbitrary chunks of text) at a time. Line lexers cannot look ahead to subsequent lines.
The default value is `false`.
+ * `fold_by_indentation`: Whether or not the lexer does not define any fold points and that
+ fold points should be calculated based on changes in line indentation. The default value
+ is `false`.
* `case_insensitive_fold_points`: Whether or not fold points added via
- `lexer.add_fold_point()` ignore case.
- The default value is `false`.
- * `inherit`: Lexer to inherit from.
- The default value is `nil`.
+ `lexer.add_fold_point()` ignore case. The default value is `false`.
+ * `inherit`: Lexer to inherit from. The default value is `nil`.
Usage:
@@ -6007,29 +5718,26 @@ Usage:
<a id="lexer.range"></a>
#### `lexer.range`(*s, e, single\_line, escapes, balanced*)
-Creates and returns a pattern that matches a range of text bounded by strings
-or patterns *s* and *e*.
-This is a convenience function for matching more complicated ranges like
-strings with escape characters, balanced parentheses, and block comments
-(nested or not). *e* is optional and defaults to *s*. *single_line* indicates
-whether or not the range must be on a single line; *escapes* indicates
-whether or not to allow '\' as an escape character; and *balanced* indicates
-whether or not to handle balanced ranges like parentheses, and requires *s*
-and *e* to be different.
+Creates and returns a pattern that matches a range of text bounded by strings or patterns *s*
+and *e*.
+This is a convenience function for matching more complicated ranges like strings with escape
+characters, balanced parentheses, and block comments (nested or not). *e* is optional and
+defaults to *s*. *single_line* indicates whether or not the range must be on a single line;
+*escapes* indicates whether or not to allow '\' as an escape character; and *balanced*
+indicates whether or not to handle balanced ranges like parentheses, and requires *s* and *e*
+to be different.
Parameters:
* *`s`*: String or pattern start of a range.
* *`e`*: Optional string or pattern end of a range. The default value is *s*.
-* *`single_line`*: Optional flag indicating whether or not the range must be
- on a single line. The default value is `false`.
-* *`escapes`*: Optional flag indicating whether or not the range end may
- be escaped by a '\' character.
- The default value is `false` unless *s* and *e* are identical,
- single-character strings. In that case, the default value is `true`.
-* *`balanced`*: Optional flag indicating whether or not to match a balanced
- range, like the "%b" Lua pattern. This flag only applies if *s* and *e* are
- different.
+* *`single_line`*: Optional flag indicating whether or not the range must be on a single
+ line. The default value is `false`.
+* *`escapes`*: Optional flag indicating whether or not the range end may be escaped by a '\'
+ character. The default value is `false` unless *s* and *e* are identical, single-character
+ strings. In that case, the default value is `true`.
+* *`balanced`*: Optional flag indicating whether or not to match a balanced range, like the
+ "%b" Lua pattern. This flag only applies if *s* and *e* are different.
Usage:
@@ -6045,8 +5753,7 @@ Return:
<a id="lexer.starts_line"></a>
#### `lexer.starts_line`(*patt*)
-Creates and returns a pattern that matches pattern *patt* only at the
-beginning of a line.
+Creates and returns a pattern that matches pattern *patt* only at the beginning of a line.
Parameters:
@@ -6054,8 +5761,7 @@ Parameters:
Usage:
-* `local preproc = token(lexer.PREPROCESSOR,
- lexer.starts_line(lexer.to_eol('#')))`
+* `local preproc = token(lexer.PREPROCESSOR, lexer.starts_line(lexer.to_eol('#')))`
Return:
@@ -6064,16 +5770,15 @@ Return:
<a id="lexer.to_eol"></a>
#### `lexer.to_eol`(*prefix, escape*)
-Creates and returns a pattern that matches from string or pattern *prefix*
-until the end of the line.
-*escape* indicates whether the end of the line can be escaped with a '\'
-character.
+Creates and returns a pattern that matches from string or pattern *prefix* until the end of
+the line.
+*escape* indicates whether the end of the line can be escaped with a '\' character.
Parameters:
* *`prefix`*: String or pattern prefix to start matching at.
-* *`escape`*: Optional flag indicating whether or not newlines can be escaped
- by a '\' character. The default value is `false`.
+* *`escape`*: Optional flag indicating whether or not newlines can be escaped by a '\'
+ character. The default value is `false`.
Usage:
@@ -6087,15 +5792,13 @@ Return:
<a id="lexer.token"></a>
#### `lexer.token`(*name, patt*)
-Creates and returns a token pattern with token name *name* and pattern
-*patt*.
-If *name* is not a predefined token name, its style must be defined via
-`lexer.add_style()`.
+Creates and returns a token pattern with token name *name* and pattern *patt*.
+If *name* is not a predefined token name, its style must be defined via `lexer.add_style()`.
Parameters:
-* *`name`*: The name of token. If this name is not a predefined token name,
- then a style needs to be assiciated with it via `lexer.add_style()`.
+* *`name`*: The name of token. If this name is not a predefined token name, then a style
+ needs to be assiciated with it via `lexer.add_style()`.
* *`patt`*: The LPeg pattern associated with the token.
Usage:
@@ -6108,28 +5811,25 @@ Return:
* pattern
<a id="lexer.word_match"></a>
-#### `lexer.word_match`(*words, case\_insensitive, word\_chars*)
+#### `lexer.word_match`(*word\_list, case\_insensitive, word\_chars*)
-Creates and returns a pattern that matches any single word in string *words*.
-*case_insensitive* indicates whether or not to ignore case when matching
-words.
-This is a convenience function for simplifying a set of ordered choice word
-patterns.
-If *words* is a multi-line string, it may contain Lua line comments (`--`)
-that will ultimately be ignored.
+Creates and returns a pattern that matches any single word in list or string *words*.
+*case_insensitive* indicates whether or not to ignore case when matching words.
+This is a convenience function for simplifying a set of ordered choice word patterns.
Parameters:
-* *`words`*: A string list of words separated by spaces.
-* *`case_insensitive`*: Optional boolean flag indicating whether or not the
- word match is case-insensitive. The default value is `false`.
+* *`word_list`*: A list of words or a string list of words separated by spaces.
+* *`case_insensitive`*: Optional boolean flag indicating whether or not the word match is
+ case-insensitive. The default value is `false`.
* *`word_chars`*: Unused legacy parameter.
Usage:
-* `local keyword = token(lexer.KEYWORD, word_match[[foo bar baz]])`
-* `local keyword = token(lexer.KEYWORD, word_match([[foo-bar foo-baz
- bar-foo bar-baz baz-foo baz-bar]], true))`
+* `local keyword = token(lexer.KEYWORD, word_match{'foo', 'bar', 'baz'})`
+* `local keyword = token(lexer.KEYWORD, word_match({'foo-bar', 'foo-baz', 'bar-foo',
+ 'bar-baz', 'baz-foo', 'baz-bar'}, true))`
+* `local keyword = token(lexer.KEYWORD, word_match('foo bar baz'))`
Return:
@@ -6141,44 +5841,37 @@ Return:
<a id="lexer.colors"></a>
#### `lexer.colors`
-Map of color name strings to color values in `0xBBGGRR` or `"#RRGGBB"`
-format.
-Note: for applications running within a terminal emulator, only 16 color
-values are recognized, regardless of how many colors a user's terminal
-actually supports. (A terminal emulator's settings determines how to actually
-display these recognized color values, which may end up being mapped to a
-completely different color set.) In order to use the light variant of a
-color, some terminals require a style's `bold` attribute must be set along
-with that normal color. Recognized color values are black (0x000000), red
-(0x000080), green (0x008000), yellow (0x008080), blue (0x800000), magenta
-(0x800080), cyan (0x808000), white (0xC0C0C0), light black (0x404040), light
-red (0x0000FF), light green (0x00FF00), light yellow (0x00FFFF), light blue
-(0xFF0000), light magenta (0xFF00FF), light cyan (0xFFFF00), and light white
-(0xFFFFFF).
+Map of color name strings to color values in `0xBBGGRR` or `"#RRGGBB"` format.
+Note: for applications running within a terminal emulator, only 16 color values are recognized,
+regardless of how many colors a user's terminal actually supports. (A terminal emulator's
+settings determines how to actually display these recognized color values, which may end up
+being mapped to a completely different color set.) In order to use the light variant of a
+color, some terminals require a style's `bold` attribute must be set along with that normal
+color. Recognized color values are black (0x000000), red (0x000080), green (0x008000), yellow
+(0x008080), blue (0x800000), magenta (0x800080), cyan (0x808000), white (0xC0C0C0), light black
+(0x404040), light red (0x0000FF), light green (0x00FF00), light yellow (0x00FFFF), light blue
+(0xFF0000), light magenta (0xFF00FF), light cyan (0xFFFF00), and light white (0xFFFFFF).
<a id="lexer.styles"></a>
#### `lexer.styles`
Map of style names to style definition tables.
-Style names consist of the following default names as well as the token names
-defined by lexers.
+Style names consist of the following default names as well as the token names defined by lexers.
* `default`: The default style all others are based on.
* `line_number`: The line number margin style.
* `control_char`: The style of control character blocks.
* `indent_guide`: The style of indentation guides.
-* `call_tip`: The style of call tip text. Only the `font`, `size`, `fore`,
- and `back` style definition fields are supported.
+* `call_tip`: The style of call tip text. Only the `font`, `size`, `fore`, and `back` style
+ definition fields are supported.
* `fold_display_text`: The style of text displayed next to folded lines.
-* `class`, `comment`, `constant`, `embedded`, `error`, `function`,
- `identifier`, `keyword`, `label`, `number`, `operator`, `preprocessor`,
- `regex`, `string`, `type`, `variable`, `whitespace`: Some token names used
- by lexers. Some lexers may define more token names, so this list is not
- exhaustive.
-* *`lang`*`_whitespace`: A special style for whitespace tokens in lexer name
- *lang*. It inherits from `whitespace`, and is used in place of it for all
- lexers.
+* `class`, `comment`, `constant`, `embedded`, `error`, `function`, `identifier`, `keyword`,
+ `label`, `number`, `operator`, `preprocessor`, `regex`, `string`, `type`, `variable`,
+ `whitespace`: Some token names used by lexers. Some lexers may define more token names,
+ so this list is not exhaustive.
+* *`lang`*`_whitespace`: A special style for whitespace tokens in lexer name *lang*. It
+ inherits from `whitespace`, and is used in place of it for all lexers.
Style definition tables may contain the following fields:
@@ -6186,27 +5879,24 @@ Style definition tables may contain the following fields:
* `size`: Integer font size.
* `bold`: Whether or not the font face is bold. The default value is `false`.
* `weight`: Integer weight or boldness of a font, between 1 and 999.
-* `italics`: Whether or not the font face is italic. The default value is
- `false`.
-* `underlined`: Whether or not the font face is underlined. The default value
- is `false`.
+* `italics`: Whether or not the font face is italic. The default value is `false`.
+* `underlined`: Whether or not the font face is underlined. The default value is `false`.
* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.
* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.
-* `eolfilled`: Whether or not the background color extends to the end of the
- line. The default value is `false`.
-* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal,
- mixed case. The default value is `'m'`.
+* `eolfilled`: Whether or not the background color extends to the end of the line. The
+ default value is `false`.
+* `case`: Font case: `'u'` for upper, `'l'` for lower, and `'m'` for normal, mixed case. The
+ default value is `'m'`.
* `visible`: Whether or not the text is visible. The default value is `true`.
-* `changeable`: Whether the text is changeable instead of read-only. The
- default value is `true`.
+* `changeable`: Whether the text is changeable instead of read-only. The default value is
+ `true`.
---
<a id="lfs"></a>
## The `lfs` Module
---
-Extends the `lfs` library to find files in directories and determine absolute
-file paths.
+Extends the `lfs` library to find files in directories and determine absolute file paths.
### Functions defined by `lfs`
@@ -6214,8 +5904,8 @@ file paths.
#### `lfs.abspath`(*filename, prefix*)
Returns the absolute path to string *filename*.
-*prefix* or `lfs.currentdir()` is prepended to a relative filename. The
-returned path is not guaranteed to exist.
+*prefix* or `lfs.currentdir()` is prepended to a relative filename. The returned path is
+not guaranteed to exist.
Parameters:
@@ -6229,26 +5919,24 @@ Return:
<a id="lfs.walk"></a>
#### `lfs.walk`(*dir, filter, n, include\_dirs*)
-Returns an iterator that iterates over all files and sub-directories (up to
-*n* levels deep) in directory *dir* and yields each file found.
-String or list *filter* determines which files to yield, with the default
-filter being `lfs.default_filter`. A filter consists of Lua 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, file extensions can be specified literally
-instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches
-the Windows directory separator ('[/\\]' is not needed).
+Returns an iterator that iterates over all files and sub-directories (up to *n* levels deep)
+in directory *dir* and yields each file found.
+String or list *filter* determines which files to yield, with the default filter being
+`lfs.default_filter`. A filter consists of Lua 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, file extensions can be specified
+literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the
+Windows directory separator ('[/\\]' is not needed).
Parameters:
* *`dir`*: The directory path to iterate over.
-* *`filter`*: Optional filter for files and directories to include and
- exclude. The default value is `lfs.default_filter`.
-* *`n`*: Optional maximum number of directory levels to descend into.
- The default value is `nil`, which indicates no limit.
-* *`include_dirs`*: Optional flag indicating whether or not to yield
- directory names too. Directory names are passed with a trailing '/' or '\',
- depending on the current platform.
+* *`filter`*: Optional filter for files and directories to include and exclude. The default
+ value is `lfs.default_filter`.
+* *`n`*: Optional maximum number of directory levels to descend into. The default value is
+ `nil`, which indicates no limit.
+* *`include_dirs`*: Optional flag indicating whether or not to yield directory names too.
+ Directory names are passed with a trailing '/' or '\', depending on the current platform.
The default value is `false`.
See also:
@@ -6261,11 +5949,10 @@ See also:
<a id="lfs.default_filter"></a>
#### `lfs.default_filter`
-The filter table containing common binary file extensions and version control
-directories to exclude when iterating over files and directories using
-`walk`.
-Extensions excluded: a, bmp, bz2, class, dll, exe, gif, gz, jar, jpeg, jpg,
-o, pdf, png, so, tar, tgz, tif, tiff, xz, and zip.
+The filter table containing common binary file extensions and version control directories
+to exclude when iterating over files and directories using `walk`.
+Extensions excluded: a, bmp, bz2, class, dll, exe, gif, gz, jar, jpeg, jpg, o, pdf, png,
+so, tar, tgz, tif, tiff, xz, and zip.
Directories excluded: .bzr, .git, .hg, .svn, _FOSSIL_, and node_modules.
See also:
@@ -6284,32 +5971,29 @@ Extends Lua's `os` library to provide process spawning capabilities.
<a id="os.spawn"></a>
#### `os.spawn`(*cmd, cwd, env, stdout\_cb, stderr\_cb, exit\_cb*)
-Spawns an interactive child process *cmd* in a separate thread, returning
-a handle to that process.
+Spawns an interactive child process *cmd* in a separate thread, returning a handle to that
+process.
On Windows, *cmd* is passed to `cmd.exe`: `%COMSPEC% /c [cmd]`.
-At the moment, only the Windows terminal version spawns processes in the same
-thread.
-
-Parameters:
-
-* *`cmd`*: A command line string that contains the program's name followed by
- arguments to pass to it. `PATH` is searched for program names.
-* *`cwd`*: Optional current working directory (cwd) for the child
- process. When omitted, the parent's cwd is used.
-* *`env`*: Optional map of environment variables for the child process.
- When omitted, Textadept's environment is used.
-* *`stdout_cb`*: Optional Lua function that accepts a string parameter for a
- block of standard output read from the child. Stdout is read asynchronously
- in 1KB or 0.5KB blocks (depending on the platform), or however much data is
- available at the time.
- At the moment, only the Win32 terminal version sends all output, whether it
- be stdout or stderr, to this callback after the process finishes.
-* *`stderr_cb`*: Optional Lua function that accepts a string parameter for a
- block of standard error read from the child. Stderr is read asynchronously
- in 1KB or 0.5kB blocks (depending on the platform), or however much data is
- available at the time.
-* *`exit_cb`*: Optional Lua function that is called when the child process
- finishes. The child's exit status is passed.
+At the moment, only the Windows terminal version spawns processes in the same thread.
+
+Parameters:
+
+* *`cmd`*: A command line string that contains the program's name followed by arguments to
+ pass to it. `PATH` is searched for program names.
+* *`cwd`*: Optional current working directory (cwd) for the child process. When omitted,
+ the parent's cwd is used.
+* *`env`*: Optional map of environment variables for the child process. When omitted,
+ Textadept's environment is used.
+* *`stdout_cb`*: Optional Lua function that accepts a string parameter for a block of standard
+ output read from the child. Stdout is read asynchronously in 1KB or 0.5KB blocks (depending
+ on the platform), or however much data is available at the time.
+ At the moment, only the Win32 terminal version sends all output, whether it be stdout or
+ stderr, to this callback after the process finishes.
+* *`stderr_cb`*: Optional Lua function that accepts a string parameter for a block of
+ standard error read from the child. Stderr is read asynchronously in 1KB or 0.5kB blocks
+ (depending on the platform), or however much data is available at the time.
+* *`exit_cb`*: Optional Lua function that is called when the child process finishes. The
+ child's exit status is passed.
Usage:
@@ -6324,8 +6008,7 @@ Return:
<a id="spawn_proc:close"></a>
#### `spawn_proc:close`()
-Closes standard input for process *spawn_proc*, effectively sending an EOF
-(end of file) to it.
+Closes standard input for process *spawn_proc*, effectively sending an EOF (end of file) to it.
<a id="spawn_proc:kill"></a>
#### `spawn_proc:kill`(*signal*)
@@ -6334,25 +6017,22 @@ Kills running process *spawn_proc*, or sends it Unix signal *signal*.
Parameters:
-* *`signal`*: Optional Unix signal to send to *spawn_proc*. The default value
- is 9 (`SIGKILL`), which kills the process.
+* *`signal`*: Optional Unix signal to send to *spawn_proc*. The default value is 9 (`SIGKILL`),
+ which kills the process.
<a id="spawn_proc:read"></a>
#### `spawn_proc:read`(*arg*)
-Reads and returns stdout from process *spawn_proc*, according to string
-format or number *arg*.
-Similar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be
-running. If an error occurs while reading, returns `nil`, an error code, and
-an error message.
-Ensure any read operations read all stdout available, as the stdout callback
-function passed to `os.spawn()` will not be called until the stdout buffer is
-clear.
+Reads and returns stdout from process *spawn_proc*, according to string format or number *arg*.
+Similar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be running. If
+an error occurs while reading, returns `nil`, an error code, and an error message.
+Ensure any read operations read all stdout available, as the stdout callback function passed
+to `os.spawn()` will not be called until the stdout buffer is clear.
Parameters:
-* *`arg`*: Optional argument similar to those in Lua's `io.read()`, but "n"
- is not supported. The default value is "l", which reads a line.
+* *`arg`*: Optional argument similar to those in Lua's `io.read()`, but "n" is not
+ supported. The default value is "l", which reads a line.
Return:
@@ -6361,8 +6041,7 @@ Return:
<a id="spawn_proc:status"></a>
#### `spawn_proc:status`()
-Returns the status of process *spawn_proc*, which is either "running" or
-"terminated".
+Returns the status of process *spawn_proc*, which is either "running" or "terminated".
Return:
@@ -6371,8 +6050,8 @@ Return:
<a id="spawn_proc:wait"></a>
#### `spawn_proc:wait`()
-Blocks until process *spawn_proc* finishes (if it has not already done so)
-and returns its status code.
+Blocks until process *spawn_proc* finishes (if it has not already done so) and returns its
+status code.
Return:
@@ -6382,11 +6061,10 @@ Return:
#### `spawn_proc:write`(*...*)
Writes string input to the stdin of process *spawn_proc*.
-Note: On Linux, if more than 65536 bytes (64K) are to be written, it is
-possible those bytes need to be written in 65536-byte (64K) chunks, or the
-process may not receive all input. However, it is also possible that there is
-a limit on how many bytes can be written in a short period of time, perhaps
-196608 bytes (192K).
+Note: On Linux, if more than 65536 bytes (64K) are to be written, it is possible those
+bytes need to be written in 65536-byte (64K) chunks, or the process may not receive all
+input. However, it is also possible that there is a limit on how many bytes can be written
+in a short period of time, perhaps 196608 bytes (192K).
Parameters:
@@ -6405,21 +6083,19 @@ Extends Lua's `string` library to provide character set conversions.
<a id="string.iconv"></a>
#### `string.iconv`(*text, new, old*)
-Converts string *text* from encoding *old* to encoding *new* using GNU
-libiconv, returning the string result.
+Converts string *text* from encoding *old* to encoding *new* using GNU libiconv, returning
+the string result.
Raises an error if the encoding conversion failed.
Valid encodings are [GNU libiconv's encodings][] and include:
- * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
- KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
- Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
- Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.
+ * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R,
+ KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
+ Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, Mac{Cyrillic,Ukraine,Greek,Turkish},
+ Macintosh.
* Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.
- * Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2,
- ISO-2022-JP-1.
- * Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950,
- BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999,
- ISO-2022-CN, ISO-2022-CN-EXT.
+ * Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1.
+ * Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS, BIG5-HKSCS:2004,
+ BIG5-HKSCS:2001, BIG5-HKSCS:1999, ISO-2022-CN, ISO-2022-CN-EXT.
* Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.
* Armenian: ARMSCII-8.
* Georgian: Georgian-Academy, Georgian-PS.
@@ -6428,8 +6104,8 @@ Valid encodings are [GNU libiconv's encodings][] and include:
* Thai: ISO-8859-11, TIS-620, CP874, MacThai.
* Laotian: MuleLao-1, CP1133.
* Vietnamese: VISCII, TCVN, CP1258.
- * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,
- UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
+ * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16, UTF-16BE,
+ UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
[GNU libiconv's encodings]: https://www.gnu.org/software/libiconv/
@@ -6473,16 +6149,16 @@ Clears all bookmarks in the current buffer.
<a id="textadept.bookmarks.goto_mark"></a>
#### `textadept.bookmarks.goto_mark`(*next*)
-Prompts the user to select a bookmarked line to move the caret to the
-beginning of unless *next* is given.
-If *next* is `true` or `false`, moves the caret to the beginning of the next
-or previously bookmarked line, respectively.
+Prompts the user to select a bookmarked line to move the caret to the beginning of unless
+*next* is given.
+If *next* is `true` or `false`, moves the caret to the beginning of the next or previously
+bookmarked line, respectively.
Parameters:
-* *`next`*: Optional flag indicating whether to go to the next or previous
- bookmarked line relative to the current line. The default value is `nil`,
- prompting the user for a bookmarked line to go to.
+* *`next`*: Optional flag indicating whether to go to the next or previous bookmarked
+ line relative to the current line. The default value is `nil`, prompting the user for a
+ bookmarked line to go to.
<a id="textadept.bookmarks.toggle"></a>
#### `textadept.bookmarks.toggle`()
@@ -6512,8 +6188,8 @@ The word highlight indicator number.
<a id="textadept.editing.auto_enclose"></a>
#### `textadept.editing.auto_enclose` (bool)
-Whether or not to auto-enclose selected text when typing a punctuation
- character, taking [`textadept.editing.auto_pairs`](#textadept.editing.auto_pairs) into account.
+Whether or not to auto-enclose selected text when typing a punctuation character, taking
+ [`textadept.editing.auto_pairs`](#textadept.editing.auto_pairs) into account.
The default value is `false`.
<a id="textadept.editing.auto_indent"></a>
@@ -6546,8 +6222,7 @@ The word highlight mode.
<a id="textadept.editing.strip_trailing_spaces"></a>
#### `textadept.editing.strip_trailing_spaces` (bool)
-Strip trailing whitespace before saving files. (Does not apply to binary
- files.)
+Strip trailing whitespace before saving files. (Does not apply to binary files.)
The default value is `false`.
@@ -6556,13 +6231,13 @@ Strip trailing whitespace before saving files. (Does not apply to binary
<a id="textadept.editing.autocomplete"></a>
#### `textadept.editing.autocomplete`(*name*)
-Displays an autocompletion list provided by the autocompleter function
-associated with string *name*, and returns `true` if completions were found.
+Displays an autocompletion list provided by the autocompleter function associated with string
+*name*, and returns `true` if completions were found.
Parameters:
-* *`name`*: The name of an autocompleter function in the `autocompleters`
- table to use for providing autocompletions.
+* *`name`*: The name of an autocompleter function in the `autocompleters` table to use for
+ providing autocompletions.
See also:
@@ -6572,9 +6247,8 @@ See also:
#### `textadept.editing.convert_indentation`()
Converts indentation between tabs and spaces according to `buffer.use_tabs`.
-If `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are
-converted to tabs. Otherwise, all indenting tabs are converted to
-`buffer.tab_width` spaces.
+If `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are converted to tabs.
+Otherwise, all indenting tabs are converted to `buffer.tab_width` spaces.
See also:
@@ -6583,8 +6257,8 @@ See also:
<a id="textadept.editing.enclose"></a>
#### `textadept.editing.enclose`(*left, right*)
-Encloses the selected text or the current word within strings *left* and
-*right*, taking multiple selections into account.
+Encloses the selected text or the current word within strings *left* and *right*, taking
+multiple selections into account.
Parameters:
@@ -6594,58 +6268,52 @@ Parameters:
<a id="textadept.editing.filter_through"></a>
#### `textadept.editing.filter_through`(*command*)
-Passes the selected text or all buffer text to string shell command *command*
-as standard input (stdin) and replaces the input text with the command's
-standard output (stdout). *command* may contain shell pipes ('|').
+Passes the selected text or all buffer text to string shell command *command* as standard input
+(stdin) and replaces the input text with the command's standard output (stdout). *command*
+may contain shell pipes ('|').
Standard input is as follows:
1. If no text is selected, the entire buffer is used.
-2. If text is selected and spans a single line, only the selected text is
-used.
-3. If text is selected and spans multiple lines, all text on the lines that
-have text selected is passed as stdin. However, if the end of the selection
-is at the beginning of a line, only the line ending delimiters from the
-previous line are included. The rest of the line is excluded.
+2. If text is selected and spans a single line, only the selected text is used.
+3. If text is selected and spans multiple lines, all text on the lines that have text selected
+ is passed as stdin. However, if the end of the selection is at the beginning of a line,
+ only the line ending delimiters from the previous line are included. The rest of the line
+ is excluded.
Parameters:
-* *`command`*: The Linux, BSD, macOS, or Windows shell command to filter text
- through. May contain pipes.
+* *`command`*: The Linux, BSD, macOS, or Windows shell command to filter text through. May
+ contain pipes.
<a id="textadept.editing.goto_line"></a>
#### `textadept.editing.goto_line`(*line*)
-Moves the caret to the beginning of line number *line* or the user-specified
-line, ensuring *line* is visible.
+Moves the caret to the beginning of line number *line* or the user-specified line, ensuring
+*line* is visible.
Parameters:
-* *`line`*: Optional line number to go to. If `nil`, the user is prompted for
- one.
+* *`line`*: Optional line number to go to. If `nil`, the user is prompted for one.
<a id="textadept.editing.join_lines"></a>
#### `textadept.editing.join_lines`()
-Joins the currently selected lines or the current line with the line below
-it.
-As long as any part of a line is selected, the entire line is eligible for
-joining.
+Joins the currently selected lines or the current line with the line below it.
+As long as any part of a line is selected, the entire line is eligible for joining.
<a id="textadept.editing.paste_reindent"></a>
#### `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.
+Pastes the text from the clipboard, taking into account the buffer's indentation settings
+and the indentation of the current and preceding lines.
<a id="textadept.editing.select_enclosed"></a>
#### `textadept.editing.select_enclosed`(*left, right*)
Selects the text between strings *left* and *right* that enclose the caret.
-If that range is already selected, toggles between selecting *left* and
-*right* as well.
-If *left* and *right* are not provided, they are assumed to be one of the
-delimiter pairs specified in `auto_pairs` and are inferred from the current
-position or selection.
+If that range is already selected, toggles between selecting *left* and *right* as well.
+If *left* and *right* are not provided, they are assumed to be one of the delimiter pairs
+specified in `auto_pairs` and are inferred from the current position or selection.
Parameters:
@@ -6670,15 +6338,13 @@ Paragraphs are surrounded by one or more blank lines.
<a id="textadept.editing.select_word"></a>
#### `textadept.editing.select_word`(*all*)
-Selects the current word or, if *all* is `true`, all occurrences of the
-current word.
-If a word is already selected, selects the next occurrence as a multiple
-selection.
+Selects the current word or, if *all* is `true`, all occurrences of the current word.
+If a word is already selected, selects the next occurrence as a multiple selection.
Parameters:
-* *`all`*: Whether or not to select all occurrences of the current word.
- The default value is `false`.
+* *`all`*: Whether or not to select all occurrences of the current word. The default value is
+ `false`.
See also:
@@ -6687,18 +6353,18 @@ See also:
<a id="textadept.editing.show_documentation"></a>
#### `textadept.editing.show_documentation`(*pos, ignore\_case*)
-Displays a call tip with documentation for the symbol under or directly
-behind position *pos* or the caret position.
+Displays a call tip with documentation for the symbol under or directly behind position *pos*
+or the caret position.
Documentation is read from API files in the `api_files` table.
If a call tip is already shown, cycles to the next one if it exists.
Symbols are determined by using `buffer.word_chars`.
Parameters:
-* *`pos`*: Optional position of the symbol to show documentation for. If
- omitted, the caret position is used.
-* *`ignore_case`*: Optional flag that indicates whether or not to search
- API files case-insensitively for symbols. The default value is `false`.
+* *`pos`*: Optional position of the symbol to show documentation for. If omitted, the caret
+ position is used.
+* *`ignore_case`*: Optional flag that indicates whether or not to search API files
+ case-insensitively for symbols. The default value is `false`.
See also:
@@ -6720,8 +6386,8 @@ See also:
#### `textadept.editing.transpose_chars`()
Transposes characters intelligently.
-If the caret is at the end of a line, transposes the two characters before
-the caret. Otherwise, the characters to the left and right are.
+If the caret is at the end of a line, transposes the two characters before the caret. Otherwise,
+the characters to the left and right are.
### Tables defined by `textadept.editing`
@@ -6746,10 +6412,9 @@ Fields:
#### `textadept.editing.api_files`
Map of lexer names to API documentation file tables.
-File tables contain API file paths or functions that return such paths.
-Each line in an API file consists of a symbol name (not a fully qualified
-symbol name), a space character, and that symbol's documentation. "\n"
-represents a newline character.
+File tables contain API file paths or functions that return such paths. Each line in an
+API file consists of a symbol name (not a fully qualified symbol name), a space character,
+and that symbol's documentation. "\n" represents a newline character.
See also:
@@ -6759,9 +6424,9 @@ See also:
#### `textadept.editing.auto_pairs`
Map of auto-paired characters like parentheses, brackets, braces, and quotes.
-The ASCII values of opening characters are assigned to strings that contain
-complement characters. The default auto-paired characters are "()", "[]",
-"{}", "&apos;&apos;", and "&quot;&quot;".
+The ASCII values of opening characters are assigned to strings that contain complement
+characters. The default auto-paired characters are "()", "[]", "{}", "&apos;&apos;", and
+"&quot;&quot;".
Usage:
@@ -6772,12 +6437,10 @@ Usage:
#### `textadept.editing.autocompleters`
Map of autocompleter names to autocompletion functions.
-Names are typically lexer names and autocompletion functions typically
-autocomplete symbols.
-Autocompletion functions must return two values: the number of characters
-behind the caret that are used as the prefix of the entity to be
-autocompleted, and a list of completions to be shown. Autocompletion lists
-are sorted automatically.
+Names are typically lexer names and autocompletion functions typically autocomplete symbols.
+Autocompletion functions must return two values: the number of characters behind the caret
+that are used as the prefix of the entity to be autocompleted, and a list of completions to
+be shown. Autocompletion lists are sorted automatically.
See also:
@@ -6787,8 +6450,8 @@ See also:
#### `textadept.editing.brace_matches`
Table of brace characters to highlight.
-The ASCII values of brace characters are keys and are assigned non-`nil`
-values. The default brace characters are '(', ')', '[', ']', '{', and '}'.
+The ASCII values of brace characters are keys and are assigned non-`nil` values. The default
+brace characters are '(', ')', '[', ']', '{', and '}'.
Usage:
@@ -6798,10 +6461,10 @@ Usage:
<a id="textadept.editing.comment_string"></a>
#### `textadept.editing.comment_string`
-Map of lexer names to line comment strings for programming languages, used by
-the `toggle_comment()` function.
-Keys are lexer names and values are either the language's line comment
-prefixes or block comment delimiters separated by a '|' character.
+Map of lexer names to line comment strings for programming languages, used by the
+`toggle_comment()` function.
+Keys are lexer names and values are either the language's line comment prefixes or block
+comment delimiters separated by a '|' character.
See also:
@@ -6811,8 +6474,8 @@ See also:
#### `textadept.editing.typeover_chars`
Table of characters to move over when typed.
-The ASCII values of characters are keys and are assigned non-`nil` values.
-The default characters are ')', ']', '}', '&apos;', and '&quot;'.
+The ASCII values of characters are keys and are assigned non-`nil` values. The default
+characters are ')', ']', '}', '&apos;', and '&quot;'.
Usage:
@@ -6831,8 +6494,8 @@ Handles file type detection for Textadept.
#### `events.LEXER_LOADED` (string)
Emitted after loading a language lexer.
- This is useful for overriding a language module's key bindings or other
- properties since the module is not loaded when Textadept starts.
+ This is useful for overriding a language module's key bindings or other properties since
+ the module is not loaded when Textadept starts.
Arguments:
* _`name`_: The language lexer's name.
@@ -6856,8 +6519,8 @@ See also:
#### `textadept.file_types.extensions`
Map of file extensions to their associated lexer names.
-If the file type is not recognized by its first-line, each file extension is
-matched against the file's extension.
+If the file type is not recognized by its first-line, each file extension is matched against
+the file's extension.
<a id="textadept.file_types.patterns"></a>
#### `textadept.file_types.patterns`
@@ -6870,14 +6533,13 @@ Each pattern is matched against the first line in the file.
## The `textadept.history` Module
---
-Records buffer positions within Textadept views over time and allows for
-navigating through that history.
+Records buffer positions within Textadept views over time and allows for navigating through
+that history.
-This module listens for text edit events and buffer switch events. Each time
-an insertion or deletion occurs, its location is recorded in the current
-view's location history. If the edit is close enough to the previous record,
-the previous record is amended. Each time a buffer switch occurs, the before
-and after locations are also recorded.
+This module listens for text edit events and buffer switch events. Each time an insertion
+or deletion occurs, its location is recorded in the current view's location history. If the
+edit is close enough to the previous record, the previous record is amended. Each time a
+buffer switch occurs, the before and after locations are also recorded.
### Fields defined by `textadept.history`
@@ -6918,15 +6580,14 @@ Records the given location in the current view's history.
Parameters:
-* *`filename`*: Optional string filename, buffer type, or identifier of the
- buffer to store. If `nil`, uses the current buffer.
-* *`line`*: Optional Integer line number to store. If `nil`, uses the current
- line.
-* *`column`*: Optional integer column number on line *line* to store. If
- `nil`, uses the current column.
-* *`soft`*: Optional flag that indicates whether or not this record should be
- skipped when navigating backward towards it, and updated when navigating
- away from it. The default value is `false`.
+* *`filename`*: Optional string filename, buffer type, or identifier of the buffer to store. If
+ `nil`, uses the current buffer.
+* *`line`*: Optional Integer line number to store. If `nil`, uses the current line.
+* *`column`*: Optional integer column number on line *line* to store. If `nil`, uses the
+ current column.
+* *`soft`*: Optional flag that indicates whether or not this record should be skipped when
+ navigating backward towards it, and updated when navigating away from it. The default
+ value is `false`.
---
@@ -6935,214 +6596,214 @@ Parameters:
---
Defines key bindings for Textadept.
-This set of key bindings is pretty standard among other text editors, at
-least for basic editing commands and movements.
+This set of key bindings is pretty standard among other text editors, at least for basic
+editing commands and movements.
### Key Bindings
-Win32, Linux, BSD|macOS|Terminal|Command
------------------|-----|--------|--------
-**File** | | |
-Ctrl+N |⌘N |M-^N |New file
-Ctrl+O |⌘O |^O |Open file
-Ctrl+Alt+O |^⌘O |M-^O |Open recent file...
-Ctrl+Shift+O |⌘⇧O |M-O |Reload file
-Ctrl+S |⌘S |^S |Save file
-Ctrl+Shift+S |⌘⇧S |M-^S |Save file as..
-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 |Quit
-**Edit** | | |
-Ctrl+Z<br/>Alt+Bksp |⌘Z |^Z^(†)<br/>M-Z|Undo
-Ctrl+Y<br/>Ctrl+Shift+Z|⌘⇧Z |^Y<br/>M-S-Z |Redo
-Ctrl+X<br/>Shift+Del |⌘X<br/>⇧⌦|^X |Cut
-Ctrl+C<br/>Ctrl+Ins |⌘C |^C |Copy
-Ctrl+V<br/>Shift+Ins |⌘V |^V |Paste
-Ctrl+Shift+V |⌘⇧V |M-V |Paste Reindent
-Ctrl+D |⌘D |None |Duplicate line
-Del |⌦<br/>^D |Del<br/>^D |Delete
-Alt+Del |^⌦ |M-Del<br/>M-D |Delete word
-Ctrl+A |⌘A |M-A |Select all
-Ctrl+M |^M |M-M |Match brace
-Ctrl+Enter |^Esc |M-Enter^(‡) |Complete word
-Ctrl+/ |^/ |M-/ |Toggle block comment
-Ctrl+T |^T |^T |Transpose characters
-Ctrl+Shift+J |^J |M-J |Join lines
-Ctrl+&#124; |⌘&#124; |^\ |Filter text through
-Ctrl+Shift+M |^⇧M |M-S-M |Select between delimiters
-Ctrl+< |⌘< |M-< |Select between XML tags
-Ctrl+> |⌘> |None |Select in XML tag
-Ctrl+Shift+D |⌘⇧D |M-S-W |Select word
-Ctrl+Shift+N |⌘⇧N |M-S-N |Select line
-Ctrl+Shift+P |⌘⇧P |M-S-P |Select paragraph
-Ctrl+Alt+U |^U |M-^U |Upper case selection
-Ctrl+Alt+Shift+U |^⇧U |M-^L |Lower case selection
-Alt+< |^< |M-> |Enclose as XML tags
-Alt+> |^> |None |Enclose as single XML tag
-Alt+" |^" |None |Enclose in double quotes
-Alt+' |^' |None |Enclose in single quotes
-Alt+( |^( |M-) |Enclose in parentheses
-Alt+[ |^[ |M-] |Enclose in brackets
-Alt+{ |^{ |M-} |Enclose in braces
-Ctrl+Shift+Up |^⇧⇡ |S-^Up |Move selected lines up
-Ctrl+Shift+Down |^⇧⇣ |S-^Down |Move selected lines down
-Alt+, |^, |M-, |Navigate backward
-Alt+. |^. |M-. |Navigate forward
-None |None |None |Record location
-None |None |None |Clear navigation history
-Ctrl+P |⌘, |M-~ |Preferences
-**Search** | | |
-Ctrl+F |⌘F |M-F<br/>M-S-F|Find
-Ctrl+G<br/>F3 |⌘G |M-G |Find next
-Ctrl+Shift+G<br/>Shift+F3|⌘⇧G |M-S-G |Find previous
-Ctrl+Alt+R |^R |M-R |Replace
-Ctrl+Alt+Shift+R |^⇧R |M-S-R |Replace all
-Ctrl+Alt+F |^⌘F |M-^F |Find incremental
-Ctrl+Shift+F |⌘⇧F |None |Find in files
-Ctrl+Alt+G |^⌘G |None |Goto next file found
-Ctrl+Alt+Shift+G |^⌘⇧G|None |Goto previous file found
-Ctrl+J |⌘J |^J |Jump to line
-**Tools** | | |
-Ctrl+E |⌘E |M-C |Command entry
-Ctrl+Shift+E |⌘⇧E |M-S-C |Select command
-Ctrl+R |⌘R |^R |Run
-Ctrl+Shift+R |⌘⇧R |M-^R |Compile
-Ctrl+Shift+A |⌘⇧A |None |Set Arguments...
-Ctrl+Shift+B |⌘⇧B |M-^B |Build
-Ctrl+Shift+T |⌘⇧T |M-^T |Run tests
-Ctrl+Shift+X |⌘⇧X |M-^X |Stop
-Ctrl+Alt+E |^⌘E |M-X |Next Error
-Ctrl+Alt+Shift+E|^⌘⇧E |M-S-X |Previous Error
-Ctrl+F2 |⌘F2 |F1 |Toggle bookmark
-Ctrl+Shift+F2 |⌘⇧F2 |F6 |Clear bookmarks
-F2 |F2 |F2 |Next bookmark
-Shift+F2 |⇧F2 |F3 |Previous bookmark
-Alt+F2 |⌥F2 |F4 |Goto bookmark...
-F9 |F9 |F9 |Start/stop recording macro
-Shift+F9 |⇧F9 |F10 |Play recorded macro
-Ctrl+U |⌘U |^U |Quickly open `_USERHOME`
-None |None |None |Quickly open `_HOME`
-Ctrl+Alt+Shift+O|^⌘⇧O |M-S-O |Quickly open current directory
-Ctrl+Alt+Shift+P|^⌘⇧P |M-^P |Quickly open current project
-Ctrl+Shift+K |⌥⇧⇥ |M-S-K |Insert snippet...
-Tab |⇥ |Tab |Expand snippet or next placeholder
-Shift+Tab |⇧⇥ |S-Tab |Previous snippet placeholder
-Esc |Esc |Esc |Cancel snippet
-Ctrl+K |⌥⇥ |M-K |Complete trigger word
-Ctrl+Space |⌥Esc |^Space |Complete symbol
-Ctrl+H |^H |M-H<br/>M-S-H|Show documentation
-Ctrl+I |⌘I |M-S-I |Show style
-**Buffer** | | |
-Ctrl+Tab |^⇥ |M-N |Next buffer
-Ctrl+Shift+Tab |^⇧⇥ |M-P |Previous buffer
-Ctrl+B |⌘B |M-B<br/>M-S-B|Switch to buffer...
-None |None |None |Tab width: 2
-None |None |None |Tab width: 3
-None |None |None |Tab width: 4
-None |None |None |Tab width: 8
-Ctrl+Alt+Shift+T|^⇧T |M-T<br/>M-S-T|Toggle use tabs
-Ctrl+Alt+I |^I |M-I |Convert indentation
-None |None |None |CR+LF EOL mode
-None |None |None |LF EOL mode
-None |None |None |UTF-8 encoding
-None |None |None |ASCII encoding
-None |None |None |CP-1252 encoding
-None |None |None |UTF-16 encoding
-Ctrl+Alt+\\ |^\\ |None |Toggle wrap mode
-Ctrl+Alt+Shift+S|^⇧S |None |Toggle view whitespace
-Ctrl+Shift+L |⌘⇧L |M-S-L |Select lexer...
-**View** | | |
-Ctrl+Alt+N |^⌥⇥ |M-^V N |Next view
-Ctrl+Alt+P |^⌥⇧⇥ |M-^V P |Previous view
-Ctrl+Alt+S<br/>Ctrl+Alt+H|^S |M-^V S<br/>M-^V H|Split view horizontal
-Ctrl+Alt+V |^V |M-^V V |Split view vertical
-Ctrl+Alt+W |^W |M-^V W |Unsplit view
-Ctrl+Alt+Shift+W |^⇧W |M-^V S-W |Unsplit all views
-Ctrl+Alt++<br/>Ctrl+Alt+=|^+<br/>^=|M-^V +<br/>M-^V =|Grow view
-Ctrl+Alt+- |^- |M-^V - |Shrink view
-Ctrl+* |⌘* |M-* |Toggle current fold
-Ctrl+Alt+Shift+I |^⇧I |N/A |Toggle indent guides
-Ctrl+Alt+Shift+V |^⇧V |None |Toggle virtual space
-Ctrl+= |⌘= |N/A |Zoom in
-Ctrl+- |⌘- |N/A |Zoom out
-Ctrl+0 |⌘0 |N/A |Reset zoom
-**Help**| | |
-F1 |F1 |None|Open manual
-Shift+F1|⇧F1 |None|Open LuaDoc
-None |None|None|About
-**Movement** | | |
-Down |⇣<br/>^N |^N<br/>Down |Line down
-Shift+Down |⇧⇣<br/>^⇧N |S-Down |Line down extend selection
-Ctrl+Down |^⇣ |^Down |Scroll line down
-Alt+Shift+Down |⌥⇧⇣ |M-S-Down |Line down extend rect. selection
-Up |⇡<br/>^P |^P<br/>Up |Line up
-Shift+Up |⇧⇡<br/>^⇧P |S-Up |Line up extend selection
-Ctrl+Up |^⇡ |^Up |Scroll line up
-Alt+Shift+Up |⌥⇧⇡ |M-S-Up |Line up extend rect. selection
-Left |⇠<br/>^B |^B<br/>Left |Char left
-Shift+Left |⇧⇠<br/>^⇧B |S-Left |Char left extend selection
-Ctrl+Left |⌥⇠<br/>^⌘B |^Left |Word left
-Ctrl+Shift+Left |^⇧⇠<br/>^⌘⇧B|S-^Left |Word left extend selection
-Alt+Shift+Left |⌥⇧⇠ |M-S-Left |Char left extend rect. selection
-Right |⇢<br/>^F |^F<br/>Right|Char right
-Shift+Right |⇧⇢<br/>^⇧F |S-Right |Char right extend selection
-Ctrl+Right |⌥⇢<br/>^⌘F |^Right |Word right
-Ctrl+Shift+Right|^⇧⇢<br/>^⌘⇧F|S-^Right |Word right extend selection
-Alt+Shift+Right |⌥⇧⇢ |M-S-Right |Char right extend rect. selection
-Home |⌘⇠<br/>^A |^A<br/>Home |Line start
-Shift+Home |⌘⇧⇠<br/>^⇧A |M-S-A |Line start extend selection
-Ctrl+Home |⌘⇡<br/>⌘↖ |M-^A |Document start
-Ctrl+Shift+Home |⌘⇧⇡<br/>⌘⇧↖ |None |Document start extend selection
-Alt+Shift+Home |⌥⇧↖ |None |Line start extend rect. selection
-End |⌘⇢<br/>^E |^E<br/>End |Line end
-Shift+End |⌘⇧⇢<br/>^⇧E |M-S-E |Line end extend selection
-Ctrl+End |⌘⇣<br/>⌘↘ |M-^E |Document end
-Ctrl+Shift+End |⌘⇧⇣<br/>⌘⇧↘ |None |Document end extend selection
-Alt+Shift+End |⌥⇧↘ |None |Line end extend rect. selection
-PgUp |⇞ |PgUp |Page up
-Shift+PgUp |⇧⇞ |M-S-U |Page up extend selection
-Alt+Shift+PgUp |⌥⇧⇞ |None |Page up extend rect. selection
-PgDn |⇟ |PgDn |Page down
-Shift+PgDn |⇧⇟ |M-S-D |Page down extend selection
-Alt+Shift+PgDn |⌥⇧⇟ |None |Page down extend rect. selection
-Ctrl+Del |⌘⌦ |^Del |Delete word right
-Ctrl+Shift+Del |⌘⇧⌦ |S-^Del |Delete line right
-Ins |Ins |Ins |Toggle overtype
-Bksp |⌫<br/>⇧⌫ |^H<br/>Bksp |Delete back
-Ctrl+Bksp |⌘⌫ |None |Delete word left
-Ctrl+Shift+Bksp |⌘⇧⌫ |None |Delete line left
-Tab |⇥ |Tab<br/>^I |Insert tab or indent
-Shift+Tab |⇧⇥ |S-Tab |Dedent
-None |^K |^K |Cut to line end
-None |^L |None |Center line vertically
-N/A |N/A |^^ |Mark text at the caret position
-N/A |N/A |^] |Swap caret and mark anchor
-**UTF-8 Input** | | |
-Ctrl+Shift+U *xxxx* Enter|⌘⇧U *xxxx* ↩|M-U *xxxx* Enter|Insert U-*xxxx* char.
-**Find Fields**| | |
-Left |⇠<br/>^B |^B<br/>Left |Cursor left
-Right |⇢<br/>^F |^F<br/>Right|Cursor right
-Del |⌦ |Del |Delete forward
-Bksp |⌫ |^H<br/>Bksp |Delete back
-Ctrl+V |⌘V |^V |Paste
-N/A |N/A |^X |Cut all
-N/A |N/A |^Y |Copy all
-N/A |N/A |^U |Erase all
-Home |↖<br/>⌘⇠<br/>^A|^A |Home
-End |↘<br/>⌘⇢<br/>^E|^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"
+Win32, Linux, BSD | macOS | Terminal | Command
+-|-|-|-
+**File**|||
+Ctrl+N | ⌘N | M-^N | New file
+Ctrl+O | ⌘O | ^O | Open file
+Ctrl+Alt+O | ^⌘O | M-^O | Open recent file...
+Ctrl+Shift+O | ⌘⇧O | M-O | Reload file
+Ctrl+S | ⌘S | ^S | Save file
+Ctrl+Shift+S | ⌘⇧S | M-^S | Save file as..
+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 | Quit
+**Edit**| | |
+Ctrl+Z<br/>Alt+Bksp | ⌘Z | ^Z^(†)<br/>M-Z | Undo
+Ctrl+Y<br/>Ctrl+Shift+Z | ⌘⇧Z | ^Y<br/>M-S-Z | Redo
+Ctrl+X<br/>Shift+Del | ⌘X<br/>⇧⌦ | ^X | Cut
+Ctrl+C<br/>Ctrl+Ins | ⌘C | ^C | Copy
+Ctrl+V<br/>Shift+Ins | ⌘V | ^V | Paste
+Ctrl+Shift+V | ⌘⇧V | M-V | Paste Reindent
+Ctrl+D | ⌘D | None | Duplicate line
+Del | ⌦<br/>^D | Del<br/>^D | Delete
+Alt+Del | ^⌦ | M-Del<br/>M-D | Delete word
+Ctrl+A | ⌘A | M-A | Select all
+Ctrl+M | ^M | M-M | Match brace
+Ctrl+Enter | ^Esc | M-Enter^(‡) | Complete word
+Ctrl+/ | ^/ | M-/ | Toggle block comment
+Ctrl+T | ^T | ^T | Transpose characters
+Ctrl+Shift+J | ^J | M-J | Join lines
+Ctrl+&#124; | ⌘&#124; | ^\ | Filter text through
+Ctrl+Shift+M | ^⇧M | M-S-M | Select between delimiters
+Ctrl+< | ⌘< | M-< | Select between XML tags
+Ctrl+> | ⌘> | None | Select in XML tag
+Ctrl+Shift+D | ⌘⇧D | M-S-W | Select word
+Ctrl+Shift+N | ⌘⇧N | M-S-N | Select line
+Ctrl+Shift+P | ⌘⇧P | M-S-P | Select paragraph
+Ctrl+Alt+U | ^U | M-^U | Upper case selection
+Ctrl+Alt+Shift+U | ^⇧U | M-^L | Lower case selection
+Alt+< | ^< | M-> | Enclose as XML tags
+Alt+> | ^> | None | Enclose as single XML tag
+Alt+" | ^" | None | Enclose in double quotes
+Alt+' | ^' | None | Enclose in single quotes
+Alt+( | ^( | M-) | Enclose in parentheses
+Alt+[ | ^[ | M-] | Enclose in brackets
+Alt+{ | ^{ | M-} | Enclose in braces
+Ctrl+Shift+Up | ^⇧⇡ | S-^Up | Move selected lines up
+Ctrl+Shift+Down | ^⇧⇣ | S-^Down | Move selected lines down
+Alt+, | ^, | M-, | Navigate backward
+Alt+. | ^. | M-. | Navigate forward
+None | None | None | Record location
+None | None | None | Clear navigation history
+Ctrl+P | ⌘, | M-~ | Preferences
+**Search**| | |
+Ctrl+F | ⌘F | M-F<br/>M-S-F | Find
+Ctrl+G<br/>F3 | ⌘G | M-G | Find next
+Ctrl+Shift+G<br/>Shift+F3 | ⌘⇧G | M-S-G | Find previous
+Ctrl+Alt+R | ^R | M-R | Replace
+Ctrl+Alt+Shift+R | ^⇧R | M-S-R | Replace all
+Ctrl+Alt+F | ^⌘F | M-^F | Find incremental
+Ctrl+Shift+F | ⌘⇧F | None | Find in files
+Ctrl+Alt+G | ^⌘G | None | Goto next file found
+Ctrl+Alt+Shift+G | ^⌘⇧G | None | Goto previous file found
+Ctrl+J | ⌘J | ^J | Jump to line
+**Tools**| | |
+Ctrl+E | ⌘E | M-C | Command entry
+Ctrl+Shift+E | ⌘⇧E | M-S-C | Select command
+Ctrl+R | ⌘R | ^R | Run
+Ctrl+Shift+R | ⌘⇧R | M-^R | Compile
+Ctrl+Shift+A | ⌘⇧A | None | Set Arguments...
+Ctrl+Shift+B | ⌘⇧B | M-^B | Build
+Ctrl+Shift+T | ⌘⇧T | M-^T | Run tests
+Ctrl+Shift+X | ⌘⇧X | M-^X | Stop
+Ctrl+Alt+E | ^⌘E | M-X | Next Error
+Ctrl+Alt+Shift+E | ^⌘⇧E | M-S-X | Previous Error
+Ctrl+F2 | ⌘F2 | F1 | Toggle bookmark
+Ctrl+Shift+F2 | ⌘⇧F2 | F6 | Clear bookmarks
+F2 | F2 | F2 | Next bookmark
+Shift+F2 | ⇧F2 | F3 | Previous bookmark
+Alt+F2 | ⌥F2 | F4 | Goto bookmark...
+F9 | F9 | F9 | Start/stop recording macro
+Shift+F9 | ⇧F9 | F10 | Play recorded macro
+Ctrl+U | ⌘U | ^U | Quickly open `_USERHOME`
+None | None | None | Quickly open `_HOME`
+Ctrl+Alt+Shift+O | ^⌘⇧O | M-S-O | Quickly open current directory
+Ctrl+Alt+Shift+P | ^⌘⇧P | M-^P | Quickly open current project
+Ctrl+Shift+K | ⌥⇧⇥ | M-S-K | Insert snippet...
+Tab | ⇥ | Tab | Expand snippet or next placeholder
+Shift+Tab | ⇧⇥ | S-Tab | Previous snippet placeholder
+Esc | Esc | Esc | Cancel snippet
+Ctrl+K | ⌥⇥ | M-K | Complete trigger word
+Ctrl+Space | ⌥Esc | ^Space | Complete symbol
+Ctrl+H | ^H | M-H<br/>M-S-H | Show documentation
+Ctrl+I | ⌘I | M-S-I | Show style
+**Buffer**| | |
+Ctrl+Tab | ^⇥ | M-N | Next buffer
+Ctrl+Shift+Tab | ^⇧⇥ | M-P | Previous buffer
+Ctrl+B | ⌘B | M-B<br/>M-S-B | Switch to buffer...
+None | None | None | Tab width: 2
+None | None | None | Tab width: 3
+None | None | None | Tab width: 4
+None | None | None | Tab width: 8
+Ctrl+Alt+Shift+T | ^⇧T | M-T<br/>M-S-T | Toggle use tabs
+Ctrl+Alt+I | ^I | M-I | Convert indentation
+None | None | None | CR+LF EOL mode
+None | None | None | LF EOL mode
+None | None | None | UTF-8 encoding
+None | None | None | ASCII encoding
+None | None | None | CP-1252 encoding
+None | None | None | UTF-16 encoding
+Ctrl+Alt+\\ | ^\\ | None | Toggle wrap mode
+Ctrl+Alt+Shift+S | ^⇧S | None | Toggle view whitespace
+Ctrl+Shift+L | ⌘⇧L | M-S-L | Select lexer...
+**View**| | |
+Ctrl+Alt+N | ^⌥⇥ | M-^V N | Next view
+Ctrl+Alt+P | ^⌥⇧⇥ | M-^V P | Previous view
+Ctrl+Alt+S<br/>Ctrl+Alt+H | ^S | M-^V S<br/>M-^V H | Split view horizontal
+Ctrl+Alt+V | ^V | M-^V V | Split view vertical
+Ctrl+Alt+W | ^W | M-^V W | Unsplit view
+Ctrl+Alt+Shift+W | ^⇧W | M-^V S-W | Unsplit all views
+Ctrl+Alt++<br/>Ctrl+Alt+= | ^+<br/>^= | M-^V +<br/>M-^V = | Grow view
+Ctrl+Alt+- | ^- | M-^V - | Shrink view
+Ctrl+* | ⌘* | M-* | Toggle current fold
+Ctrl+Alt+Shift+I | ^⇧I | N/A | Toggle indent guides
+Ctrl+Alt+Shift+V | ^⇧V | None | Toggle virtual space
+Ctrl+= | ⌘= | N/A | Zoom in
+Ctrl+- | ⌘- | N/A | Zoom out
+Ctrl+0 | ⌘0 | N/A | Reset zoom
+**Help**|| |
+F1 | F1 | None | Open manual
+Shift+F1 | ⇧F1 | None | Open LuaDoc
+None | None | None | About
+**Movement**| | |
+Down | ⇣<br/>^N | ^N<br/>Down | Line down
+Shift+Down | ⇧⇣<br/>^⇧N | S-Down | Line down extend selection
+Ctrl+Down | ^⇣ | ^Down | Scroll line down
+Alt+Shift+Down | ⌥⇧⇣ | M-S-Down | Line down extend rect. selection
+Up | ⇡<br/>^P | ^P<br/>Up | Line up
+Shift+Up | ⇧⇡<br/>^⇧P | S-Up | Line up extend selection
+Ctrl+Up | ^⇡ | ^Up | Scroll line up
+Alt+Shift+Up | ⌥⇧⇡ | M-S-Up | Line up extend rect. selection
+Left | ⇠<br/>^B | ^B<br/>Left | Char left
+Shift+Left | ⇧⇠<br/>^⇧B | S-Left | Char left extend selection
+Ctrl+Left | ⌥⇠<br/>^⌘B | ^Left | Word left
+Ctrl+Shift+Left | ^⇧⇠<br/>^⌘⇧B | S-^Left | Word left extend selection
+Alt+Shift+Left | ⌥⇧⇠ | M-S-Left | Char left extend rect. selection
+Right | ⇢<br/>^F | ^F<br/>Right | Char right
+Shift+Right | ⇧⇢<br/>^⇧F | S-Right | Char right extend selection
+Ctrl+Right | ⌥⇢<br/>^⌘F | ^Right | Word right
+Ctrl+Shift+Right | ^⇧⇢<br/>^⌘⇧F | S-^Right | Word right extend selection
+Alt+Shift+Right | ⌥⇧⇢ | M-S-Right | Char right extend rect. selection
+Home | ⌘⇠<br/>^A | ^A<br/>Home | Line start
+Shift+Home | ⌘⇧⇠<br/>^⇧A | M-S-A | Line start extend selection
+Ctrl+Home | ⌘⇡<br/>⌘↖ | M-^A | Document start
+Ctrl+Shift+Home | ⌘⇧⇡<br/>⌘⇧↖ | None | Document start extend selection
+Alt+Shift+Home | ⌥⇧↖ | None | Line start extend rect. selection
+End | ⌘⇢<br/>^E | ^E<br/>End | Line end
+Shift+End | ⌘⇧⇢<br/>^⇧E | M-S-E | Line end extend selection
+Ctrl+End | ⌘⇣<br/>⌘↘ | M-^E | Document end
+Ctrl+Shift+End | ⌘⇧⇣<br/>⌘⇧↘ | None | Document end extend selection
+Alt+Shift+End | ⌥⇧↘ | None | Line end extend rect. selection
+PgUp | ⇞ | PgUp | Page up
+Shift+PgUp | ⇧⇞ | M-S-U | Page up extend selection
+Alt+Shift+PgUp | ⌥⇧⇞ | None | Page up extend rect. selection
+PgDn | ⇟ | PgDn | Page down
+Shift+PgDn | ⇧⇟ | M-S-D | Page down extend selection
+Alt+Shift+PgDn | ⌥⇧⇟ | None | Page down extend rect. selection
+Ctrl+Del | ⌘⌦ | ^Del | Delete word right
+Ctrl+Shift+Del | ⌘⇧⌦ | S-^Del | Delete line right
+Ins | Ins | Ins | Toggle overtype
+Bksp | ⌫<br/>⇧⌫ | ^H<br/>Bksp | Delete back
+Ctrl+Bksp | ⌘⌫ | None | Delete word left
+Ctrl+Shift+Bksp | ⌘⇧⌫ | None | Delete line left
+Tab | ⇥ | Tab<br/>^I | Insert tab or indent
+Shift+Tab | ⇧⇥ | S-Tab | Dedent
+None | ^K | ^K | Cut to line end
+None | ^L | None | Center line vertically
+N/A | N/A | ^^ | Mark text at the caret position
+N/A | N/A | ^] | Swap caret and mark anchor
+**UTF-8 Input**|||
+Ctrl+Shift+U *xxxx* Enter | ⌘⇧U *xxxx* ↩ | M-U *xxxx* Enter | Insert U-*xxxx* char.
+**Find Fields**|||
+Left | ⇠<br/>^B | ^B<br/>Left | Cursor left
+Right | ⇢<br/>^F | ^F<br/>Right | Cursor right
+Del | ⌦ | Del | Delete forward
+Bksp | ⌫ | ^H<br/>Bksp | Delete back
+Ctrl+V | ⌘V | ^V | Paste
+N/A | N/A | ^X | Cut all
+N/A | N/A | ^Y | Copy all
+N/A | N/A | ^U | Erase all
+Home | ↖<br/>⌘⇠<br/>^A | ^A | Home
+End | ↘<br/>⌘⇢<br/>^E | ^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"
†: Some terminals interpret ^Z as suspend; see FAQ for workaround.
@@ -7155,8 +6816,7 @@ N/A |N/A |F4 |Toggle "Find in Files"
A module for recording, playing, saving, and loading keyboard macros.
Menu commands are also recorded.
-At this time, typing into multiple cursors during macro playback is not
-supported.
+At this time, typing into multiple cursors during macro playback is not supported.
### Functions defined by `textadept.macros`
@@ -7167,8 +6827,7 @@ Loads a macro from file *filename* or the user-selected file.
Parameters:
-* *`filename`*: Optional macro file to load. If `nil`, the user is prompted
- for one.
+* *`filename`*: Optional macro file to load. If `nil`, the user is prompted for one.
<a id="textadept.macros.play"></a>
#### `textadept.macros.play`()
@@ -7191,8 +6850,8 @@ Saves a recorded macro to file *filename* or the user-selected file.
Parameters:
-* *`filename`*: Optional filename to save the recorded macro to. If `nil`,
- the user is prompted for one.
+* *`filename`*: Optional filename to save the recorded macro to. If `nil`, the user is
+ prompted for one.
---
@@ -7201,10 +6860,9 @@ Parameters:
---
Defines the menus used by Textadept.
-Menus are simply tables of menu items and submenus and may be edited in
-place. A menu item itself is a table whose first element is a menu label and
-whose second element is a menu command to run. Submenus have `title` keys
-assigned to string text.
+Menus are simply tables of menu items and submenus and may be edited in place. A menu item
+itself is a table whose first element is a menu label and whose second element is a menu
+command to run. Submenus have `title` keys assigned to string text.
### Functions defined by `textadept.menu`
@@ -7220,8 +6878,7 @@ Prompts the user to select a menu command to run.
#### `textadept.menu.context_menu`
The default right-click context menu.
-Submenus, and menu items can be retrieved by name in addition to table index
-number.
+Submenus, and menu items can be retrieved by name in addition to table index number.
Usage:
@@ -7231,8 +6888,8 @@ Usage:
#### `textadept.menu.menubar`
The default main menubar.
-Individual menus, submenus, and menu items can be retrieved by name in
-addition to table index number.
+Individual menus, submenus, and menu items can be retrieved by name in addition to table
+index number.
Usage:
@@ -7243,8 +6900,7 @@ Usage:
#### `textadept.menu.tab_context_menu`
The default tabbar context menu.
-Submenus, and menu items can be retrieved by name in addition to table index
-number.
+Submenus, and menu items can be retrieved by name in addition to table index number.
---
<a id="textadept.run"></a>
@@ -7252,10 +6908,9 @@ number.
---
Compile and run source code files with Textadept.
-[Language modules](#compile-and-run) may tweak the `compile_commands`,
-`run_commands`, and `error_patterns` tables for particular languages.
-The user may tweak `build_commands` and `test_commands` for particular
-projects.
+[Language modules](#compile-and-run) may tweak the `compile_commands`, `run_commands`, and
+`error_patterns` tables for particular languages.
+The user may tweak `build_commands` and `test_commands` for particular projects.
### Fields defined by `textadept.run`
@@ -7273,8 +6928,8 @@ The run or compile warning marker number.
#### `events.BUILD_OUTPUT` (string)
Emitted when executing a project's build shell command.
- By default, output is printed to the message buffer. In order to override
- this behavior, connect to the event with an index of `1` and return `true`.
+ By default, output is printed to the message buffer. In order to override this behavior,
+ connect to the event with an index of `1` and return `true`.
Arguments:
* `output`: A line of string output from the command.
@@ -7283,33 +6938,31 @@ Emitted when executing a project's build shell command.
#### `events.COMPILE_OUTPUT` (string)
Emitted when executing a language's compile shell command.
- By default, compiler output is printed to the message buffer. In order to
- override this behavior, connect to the event with an index of `1` and
- return `true`.
+ By default, compiler output is printed to the message buffer. In order to override this
+ behavior, connect to the event with an index of `1` and return `true`.
Arguments:
* `output`: A line of string output from the command.
- * `ext_or_lexer`: The file extension or lexer name associated with the
- executed compile command.
+ * `ext_or_lexer`: The file extension or lexer name associated with the executed compile
+ command.
<a id="events.RUN_OUTPUT"></a>
#### `events.RUN_OUTPUT` (string)
Emitted when executing a language's run shell command.
- By default, output is printed to the message buffer. In order to override
- this behavior, connect to the event with an index of `1` and return `true`.
+ By default, output is printed to the message buffer. In order to override this behavior,
+ connect to the event with an index of `1` and return `true`.
Arguments:
* `output`: A line of string output from the command.
- * `ext_or_lexer`: The file extension or lexer name associated with the
- executed run command.
+ * `ext_or_lexer`: The file extension or lexer name associated with the executed run command.
<a id="events.TEST_OUTPUT"></a>
#### `events.TEST_OUTPUT` (string)
Emitted when executing a project's shell command for running tests.
- By default, output is printed to the message buffer. In order to override
- this behavior, connect to the event with an index of `1` and return `true`.
+ By default, output is printed to the message buffer. In order to override this behavior,
+ connect to the event with an index of `1` and return `true`.
Arguments:
* `output`: A line of string output from the command.
@@ -7318,8 +6971,7 @@ Emitted when executing a project's shell command for running tests.
#### `textadept.run.run_in_background` (bool)
Run shell commands silently in the background.
- This only applies when the message buffer is open, though it does not have
- to be visible.
+ This only applies when the message buffer is open, though it does not have to be visible.
The default value is `false`.
@@ -7328,18 +6980,15 @@ Run shell commands silently in the background.
<a id="textadept.run.build"></a>
#### `textadept.run.build`(*root\_directory*)
-Builds the project whose root path is *root_directory* or the current project
-using the shell command from the `build_commands` table.
-If a "makefile" type of build file is found, prompts the user for the full
-build command.
-The current project is determined by either the buffer's filename or the
-current working directory.
+Builds the project whose root path is *root_directory* or the current project using the
+shell command from the `build_commands` table.
+If a "makefile" type of build file is found, prompts the user for the full build command. The
+current project is determined by either the buffer's filename or the current working directory.
Emits `BUILD_OUTPUT` events.
Parameters:
-* *`root_directory`*: The path to the project to build. The default value is
- the current project.
+* *`root_directory`*: The path to the project to build. The default value is the current project.
See also:
@@ -7349,16 +6998,15 @@ See also:
<a id="textadept.run.compile"></a>
#### `textadept.run.compile`(*filename*)
-Compiles file *filename* or the current file using an appropriate shell
-command from the `compile_commands` table.
-The shell command is determined from the file's filename, extension, or
-language in that order.
+Compiles file *filename* or the current file using an appropriate shell command from the
+`compile_commands` table.
+The shell command is determined from the file's filename, extension, or language in that order.
Emits `COMPILE_OUTPUT` events.
Parameters:
-* *`filename`*: Optional path to the file to compile. The default value is
- the current file's filename.
+* *`filename`*: Optional path to the file to compile. The default value is the current
+ file's filename.
See also:
@@ -7368,20 +7016,17 @@ See also:
<a id="textadept.run.goto_error"></a>
#### `textadept.run.goto_error`(*line\_num, next*)
-Jumps to the source of the recognized compile/run warning or error on line
-number *line_num* in the message buffer.
-If *line_num* is `nil`, jumps to the next or previous warning or error,
-depending on boolean *next*. Displays an annotation with the warning or error
-message if possible.
+Jumps to the source of the recognized compile/run warning or error on line number *line_num*
+in the message buffer.
+If *line_num* is `nil`, jumps to the next or previous warning or error, depending on boolean
+*next*. Displays an annotation with the warning or error message if possible.
Parameters:
-* *`line_num`*: Optional line number in the message buffer that contains the
- compile/run warning or error to go to. This parameter may be omitted
- completely.
-* *`next`*: Optional flag indicating whether to go to the next recognized
- warning/error or the previous one. Only applicable when *line_num* is
- `nil`.
+* *`line_num`*: Optional line number in the message buffer that contains the compile/run
+ warning or error to go to. This parameter may be omitted completely.
+* *`next`*: Optional flag indicating whether to go to the next recognized warning/error or
+ the previous one. Only applicable when *line_num* is `nil`.
See also:
@@ -7390,16 +7035,15 @@ See also:
<a id="textadept.run.run"></a>
#### `textadept.run.run`(*filename*)
-Runs file *filename* or the current file using an appropriate shell command
-from the `run_commands` table.
-The shell command is determined from the file's filename, extension, or
-language in that order.
+Runs file *filename* or the current file using an appropriate shell command from the
+`run_commands` table.
+The shell command is determined from the file's filename, extension, or language in that order.
Emits `RUN_OUTPUT` events.
Parameters:
-* *`filename`*: Optional path to the file to run. The default value is the
- current file's filename.
+* *`filename`*: Optional path to the file to run. The default value is the current file's
+ filename.
See also:
@@ -7409,18 +7053,18 @@ See also:
<a id="textadept.run.set_arguments"></a>
#### `textadept.run.set_arguments`(*filename, run, compile*)
-Appends the command line argument strings *run* and *compile* to their
-respective run and compile commands for file *filename* or the current file.
-If either is `nil`, prompts the user for missing the arguments. Each filename
-has its own set of compile and run arguments.
+Appends the command line argument strings *run* and *compile* to their respective run and
+compile commands for file *filename* or the current file.
+If either is `nil`, prompts the user for missing the arguments. Each filename has its own
+set of compile and run arguments.
Parameters:
* *`filename`*: Optional path to the file to set run/compile arguments for.
-* *`run`*: Optional string run arguments to set. If `nil`, the user is
- prompted for them. Pass the empty string for no run arguments.
-* *`compile`*: Optional string compile arguments to set. If `nil`, the user
- is prompted for them. Pass the empty string for no compile arguments.
+* *`run`*: Optional string run arguments to set. If `nil`, the user is prompted for them. Pass
+ the empty string for no run arguments.
+* *`compile`*: Optional string compile arguments to set. If `nil`, the user is prompted
+ for them. Pass the empty string for no compile arguments.
See also:
@@ -7435,16 +7079,16 @@ Stops the currently running process, if any.
<a id="textadept.run.test"></a>
#### `textadept.run.test`(*root\_directory*)
-Runs tests for the project whose root path is *root_directory* or the current
-project using the shell command from the `test_commands` table.
-The current project is determined by either the buffer's filename or the
-current working directory.
+Runs tests for the project whose root path is *root_directory* or the current project using
+the shell command from the `test_commands` table.
+The current project is determined by either the buffer's filename or the current working
+directory.
Emits `TEST_OUTPUT` events.
Parameters:
-* *`root_directory`*: The path to the project to run tests for. The default
- value is the current project.
+* *`root_directory`*: The path to the project to run tests for. The default value is the
+ current project.
See also:
@@ -7457,17 +7101,17 @@ See also:
<a id="textadept.run.build_commands"></a>
#### `textadept.run.build_commands`
-Map of project root paths and "makefiles" to their associated "build" shell
-command line strings or functions that return such strings.
-Functions may also return a working directory 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.
+Map of project root paths and "makefiles" to their associated "build" shell command line
+strings or functions that return such strings.
+Functions may also return a working directory and process environment table to operate
+in. By default, the working directory is the project's root directory and the environment
+is Textadept's environment.
<a id="textadept.run.compile_commands"></a>
#### `textadept.run.compile_commands`
-Map of filenames, file extensions, and lexer names to their associated
-"compile" shell command line strings or functions that return such strings.
+Map of filenames, file extensions, and lexer names to their associated "compile" shell
+command line strings or functions that return such strings.
Command line strings may have the following macros:
+ `%f`: The file's name, including its extension.
@@ -7475,29 +7119,28 @@ Command line strings may have the following macros:
+ `%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.
+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.
<a id="textadept.run.error_patterns"></a>
#### `textadept.run.error_patterns`
-Map of file extensions and lexer names to their associated lists of string
-patterns that match warning and error messages emitted by compile and run
-commands for those file extensions and lexers.
-Patterns match single lines and contain captures for a filename, line number,
-column number (optional), and warning or error message (optional).
-Double-clicking a warning or error message takes the user to the source of
-that warning/error.
-Note: `(.-)` captures in patterns are interpreted as filenames; `(%d+)`
-captures are interpreted as line numbers first, and then column numbers; and
-any other capture is treated as warning/error message text.
+Map of file extensions and lexer names to their associated lists of string patterns that
+match warning and error messages emitted by compile and run commands for those file extensions
+and lexers.
+Patterns match single lines and contain captures for a filename, line number, column number
+(optional), and warning or error message (optional). Double-clicking a warning or error
+message takes the user to the source of that warning/error.
+Note: `(.-)` captures in patterns are interpreted as filenames; `(%d+)` captures are
+interpreted as line numbers first, and then column numbers; and any other capture is treated
+as warning/error message text.
<a id="textadept.run.run_commands"></a>
#### `textadept.run.run_commands`
-Map of filenames, file extensions, and lexer names to their associated "run"
-shell command line strings or functions that return strings.
+Map of filenames, file extensions, and lexer names to their associated "run" shell command
+line strings or functions that return strings.
Command line strings may have the following macros:
+ `%f`: The file's name, including its extension.
@@ -7505,18 +7148,18 @@ Command line strings may have the following macros:
+ `%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.
+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.
<a id="textadept.run.test_commands"></a>
#### `textadept.run.test_commands`
-Map of project root paths to their associated "test" shell command line
-strings or functions that return such strings.
-Functions may also return a working directory and process environment table
-to operate in. By default, the working directory is the project's root
-directory and the environment is Textadept's environment.
+Map of project root paths to their associated "test" shell command line strings or functions
+that return such strings.
+Functions may also return a working directory and process environment table to operate
+in. By default, the working directory is the project's root directory and the environment
+is Textadept's environment.
---
<a id="textadept.session"></a>
@@ -7533,8 +7176,7 @@ Session support for Textadept.
Emitted when loading a session.
Arguments:
- * `session`: Table of session data to load. All handlers will have access
- to this same table.
+ * `session`: Table of session data to load. All handlers will have access to this same table.
<a id="events.SESSION_SAVE"></a>
#### `events.SESSION_SAVE` (string)
@@ -7542,18 +7184,17 @@ Emitted when loading a session.
Emitted when saving a session.
Arguments:
- * `session`: Table of session data to save. All handlers will have access
- to this same table, and Textadept's default handler reserves the use of
- some keys.
- Note that functions, userdata, and circular table values cannot be saved.
- The latter case is not recognized at all, so beware.
+ * `session`: Table of session data to save. All handlers will have access to this same
+ table, and Textadept's default handler reserves the use of some keys.
+ Note that functions, userdata, and circular table values cannot be saved. The latter
+ case is not recognized at all, so beware.
<a id="textadept.session.save_on_quit"></a>
#### `textadept.session.save_on_quit` (bool)
Save the session when quitting.
- The default value is `true` unless the user passed the command line switch
- `-n` or `--nosession` to Textadept.
+ The default value is `true` unless the user passed the command line switch `-n` or
+ `--nosession` to Textadept.
### Functions defined by `textadept.session`
@@ -7561,15 +7202,14 @@ Save the session when quitting.
<a id="textadept.session.load"></a>
#### `textadept.session.load`(*filename*)
-Loads session file *filename* or the user-selected session, returning `true`
-if a session file was opened and read.
-Textadept restores split views, opened buffers, cursor information, recent
-files, and bookmarks.
+Loads session file *filename* or the user-selected session, returning `true` if a session
+file was opened and read.
+Textadept restores split views, opened buffers, cursor information, recent files, and bookmarks.
Parameters:
-* *`filename`*: Optional absolute path to the session file to load. If `nil`,
- the user is prompted for one.
+* *`filename`*: Optional absolute path to the session file to load. If `nil`, the user is
+ prompted for one.
Usage:
@@ -7583,15 +7223,14 @@ Return:
#### `textadept.session.save`(*filename*)
Saves the session to file *filename* or the user-selected file.
-Saves split views, opened buffers, cursor information, recent files, and
-bookmarks.
+Saves split views, opened buffers, cursor information, recent files, and bookmarks.
Upon quitting, the current session is saved to *filename* again, unless
`textadept.session.save_on_quit` is `false`.
Parameters:
-* *`filename`*: Optional absolute path to the session file to save. If `nil`,
- the user is prompted for one.
+* *`filename`*: Optional absolute path to the session file to save. If `nil`, the user is
+ prompted for one.
Usage:
@@ -7607,57 +7246,53 @@ Snippets for Textadept.
### Overview
-Define snippets in the global `snippets` table in key-value pairs. Each pair
-consists of either a string trigger word and its snippet text, or a string
-lexer name (from the *lexers/* directory) with a table of trigger words and
-snippet texts. When searching for a snippet to insert based on a trigger
-word, Textadept considers snippets in the current lexer to have priority,
-followed by the ones in the global table. This means if there are two
-snippets with the same trigger word, Textadept inserts the one specific to
-the current lexer, not the global one.
+Define snippets in the global `snippets` table in key-value pairs. Each pair consists of
+either a string trigger word and its snippet text, or a string lexer name (from the *lexers/*
+directory) with a table of trigger words and snippet texts. When searching for a snippet to
+insert based on a trigger word, Textadept considers snippets in the current lexer to have
+priority, followed by the ones in the global table. This means if there are two snippets
+with the same trigger word, Textadept inserts the one specific to the current lexer, not
+the global one.
### Special Sequences
#### `%`*n*`(`*text*`)`
-Represents a placeholder, where *n* is an integer and *text* is default
-placeholder text. Textadept moves the caret to placeholders in numeric order
-each time it calls [`textadept.snippets.insert()`](#textadept.snippets.insert), finishing at either
-the "%0" placeholder if it exists or at the end of the snippet. Examples are
+Represents a placeholder, where *n* is an integer and *text* is default placeholder
+text. Textadept moves the caret to placeholders in numeric order each time it calls
+[`textadept.snippets.insert()`](#textadept.snippets.insert), finishing at either the "%0" placeholder if it exists or
+at the end of the snippet. Examples are
snippets['foo'] = 'foobar%1(baz)'
snippets['bar'] = 'start\n\t%0\nend'
#### `%`*n*`{`*list*`}`
-Also represents a placeholder (where *n* is an integer), but presents a list
-of choices for placeholder text constructed from comma-separated *list*.
-Examples are
+Also represents a placeholder (where *n* is an integer), but presents a list of choices for
+placeholder text constructed from comma-separated *list*. Examples are
snippets['op'] = 'operator(%1(1), %2(1), "%3{add,sub,mul,div}")'
#### `%`*n*
-Represents a mirror, where *n* is an integer. Mirrors with the same *n* as a
-placeholder mirror any user input in the placeholder. If no placeholder
-exists for *n*, the first occurrence of that mirror in the snippet becomes
-the placeholder, but with no default text. Examples are
+Represents a mirror, where *n* is an integer. Mirrors with the same *n* as a placeholder mirror
+any user input in the placeholder. If no placeholder exists for *n*, the first occurrence
+of that mirror in the snippet becomes the placeholder, but with no default text. Examples are
snippets['foo'] = '%1(mirror), %1, on the wall'
snippets['q'] = '"%1"'
#### `%`*n*`<`*Lua code*`>`<br/>`%`*n*`[`*Shell code*`]`
-Represents a transform, where *n* is an integer that has an associated
-placeholder, *Lua code* is arbitrary Lua code, and *Shell code* is arbitrary
-Shell code. Textadept executes the code as text is typed into placeholder
-*n*. If the transform omits *n*, Textadept executes the transform's code the
-moment the editor inserts the snippet.
+Represents a transform, where *n* is an integer that has an associated placeholder, *Lua code*
+is arbitrary Lua code, and *Shell code* is arbitrary Shell code. Textadept executes the code
+as text is typed into placeholder *n*. If the transform omits *n*, Textadept executes the
+transform's code the moment the editor inserts the snippet.
-Textadept runs Lua code in its Lua State and replaces the transform with the
-code's return text. The code may use the temporary `text` and `selected_text`
-global variables which contain placeholder *n*'s text and the text originally
-selected when the snippet was inserted, respectively. An example is
+Textadept runs Lua code in its Lua State and replaces the transform with the code's return
+text. The code may use the temporary `text` and `selected_text` global variables which
+contain placeholder *n*'s text and the text originally selected when the snippet was inserted,
+respectively. An example is
snippets['attr'] = [[
%1(int) %2(foo) = %3;
@@ -7670,29 +7305,27 @@ selected when the snippet was inserted, respectively. An example is
}
]]
-Textadept executes shell code using Lua's [`io.popen()`][] and replaces the
-transform with the process' standard output (stdout). The code may use a `%`
-character to represent placeholder *n*'s text. An example is
+Textadept executes shell code using Lua's [`io.popen()`][] and replaces the transform with the
+process' standard output (stdout). The code may use a `%` character to represent placeholder
+*n*'s text. An example is
snippets['env'] = '$%1(HOME) = %1[echo $%]'
#### `%%`
-Stands for a single '%' since '%' by itself has a special meaning in
-snippets.
+Stands for a single '%' since '%' by itself has a special meaning in snippets.
#### `%(`<br/>`%{`
-Stands for a single '(' or '{', respectively, after a `%`*n* mirror.
-Otherwise, the mirror would be interpreted as a placeholder or transform.
-Note: it is currently not possible to escape a '<' or '[' immediately after
-a `%`*n* mirror due to `%<...>` and `%[...]` sequences being interpreted as
-code to execute.
+Stands for a single '(' or '{', respectively, after a `%`*n* mirror. Otherwise, the mirror
+would be interpreted as a placeholder or transform. Note: it is currently not possible to
+escape a '<' or '[' immediately after a `%`*n* mirror due to `%<...>` and `%[...]` sequences
+being interpreted as code to execute.
#### `\t`
-A single unit of indentation based on the buffer's indentation settings
-([`buffer.use_tabs`](#buffer.use_tabs) and [`buffer.tab_width`](#buffer.tab_width)).
+A single unit of indentation based on the buffer's indentation settings ([`buffer.use_tabs`](#buffer.use_tabs)
+and [`buffer.tab_width`](#buffer.tab_width)).
#### `\n`
@@ -7730,16 +7363,14 @@ Return:
<a id="textadept.snippets.insert"></a>
#### `textadept.snippets.insert`(*text*)
-Inserts snippet text *text* or the snippet assigned to the trigger word
-behind the caret.
-Otherwise, if a snippet is active, goes to the active snippet's next
-placeholder. Returns `false` if no action was taken.
+Inserts snippet text *text* or the snippet assigned to the trigger word behind the caret.
+Otherwise, if a snippet is active, goes to the active snippet's next placeholder. Returns
+`false` if no action was taken.
Parameters:
-* *`text`*: Optional snippet text to insert. If `nil`, attempts to insert a
- new snippet based on the trigger, the word behind caret, and the current
- lexer.
+* *`text`*: Optional snippet text to insert. If `nil`, attempts to insert a new snippet
+ based on the trigger, the word behind caret, and the current lexer.
Return:
@@ -7752,8 +7383,7 @@ See also:
<a id="textadept.snippets.previous"></a>
#### `textadept.snippets.previous`()
-Jumps back to the previous snippet placeholder, reverting any changes from
-the current one.
+Jumps back to the previous snippet placeholder, reverting any changes from the current one.
Returns `false` if no snippet is active.
Return:
@@ -7763,8 +7393,8 @@ Return:
<a id="textadept.snippets.select"></a>
#### `textadept.snippets.select`()
-Prompts the user to select a snippet to insert from a list of global and
-language-specific snippets.
+Prompts the user to select a snippet to insert from a list of global and language-specific
+snippets.
### Tables defined by `textadept.snippets`
@@ -7772,19 +7402,19 @@ language-specific snippets.
<a id="_G.snippets"></a>
#### `_G.snippets`
-Map of snippet triggers with their snippet text or functions that return such
-text, with language-specific snippets tables assigned to a lexer name key.
+Map of snippet triggers with their snippet text or functions that return such text, with
+language-specific snippets tables assigned to a lexer name key.
<a id="textadept.snippets.paths"></a>
#### `textadept.snippets.paths`
List of directory paths to look for snippet files in.
-Filenames are of the form *lexer.trigger.ext* or *trigger.ext* (*.ext* is an
-optional, arbitrary file extension). If the global `snippets` table does not
-contain a snippet for a given trigger, this table is consulted for a matching
-filename, and the contents of that file is inserted as a snippet.
-Note: If a directory has multiple snippets with the same trigger, the snippet
-chosen for insertion is not defined and may not be constant.
+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.
---
<a id="ui"></a>
@@ -7827,11 +7457,10 @@ Whether or not Textadept's window is maximized.
#### `ui.silent_print` (bool)
Whether or not to print messages to buffers silently.
- This is not guaranteed to be a constant value, as Textadept may change it
- for the editor's own purposes. This flag should be used only in conjunction
- with a group of [`ui.print()`](#ui.print) and [`ui._print()`](#ui._print) function calls.
- The default value is `false`, and focuses buffers when messages are printed
- to them.
+ This is not guaranteed to be a constant value, as Textadept may change it for the editor's
+ own purposes. This flag should be used only in conjunction with a group of [`ui.print()`](#ui.print)
+ and [`ui._print()`](#ui._print) function calls.
+ The default value is `false`, and focuses buffers when messages are printed to them.
<a id="ui.statusbar_text"></a>
#### `ui.statusbar_text` (string, Write-only)
@@ -7850,8 +7479,8 @@ The context menu for the buffer's tab, a [`ui.menu()`](#ui.menu).
Whether or not to display the tab bar when multiple buffers are open.
The default value is `true`.
- A third option, `ui.SHOW_ALL_TABS` may be used to always show the tab bar,
- even if only one buffer is open.
+ A third option, `ui.SHOW_ALL_TABS` may be used to always show the tab bar, even if only
+ one buffer is open.
<a id="ui.title"></a>
#### `ui.title` (string, Write-only)
@@ -7865,10 +7494,9 @@ The title text of Textadept's window.
#### `ui._print`(*buffer\_type, ...*)
Prints the given string messages to the buffer of string type *buffer_type*.
-Opens a new buffer for printing messages to if necessary. If the message
-buffer is already open in a view, the message is printed to that view.
-Otherwise the view is split (unless `ui.tabs` is `true`) and the message
-buffer is displayed before being printed to.
+Opens a new buffer for printing messages to if necessary. If the message buffer is already
+open in a view, the message is printed to that view. Otherwise the view is split (unless
+`ui.tabs` is `true`) and the message buffer is displayed before being printed to.
Parameters:
@@ -7882,13 +7510,11 @@ Usage:
<a id="ui.dialog"></a>
#### `ui.dialog`(*kind, ...*)
-Low-level function for prompting the user with a [gtdialog][] of kind *kind*
-with the given string and table arguments, returning a formatted string of
-the dialog's output.
-You probably want to use the higher-level functions in the [`ui.dialogs`](#ui.dialogs)
-module.
-Table arguments containing strings are allowed and expanded in place. This is
-useful for filtered list dialogs with many items.
+Low-level function for prompting the user with a [gtdialog][] of kind *kind* with the given
+string and table arguments, returning a formatted string of the dialog's output.
+You probably want to use the higher-level functions in the [`ui.dialogs`](#ui.dialogs) module.
+Table arguments containing strings are allowed and expanded in place. This is useful for
+filtered list dialogs with many items.
[gtdialog]: https://orbitalquark.github.io/gtdialog/manual.html
@@ -7909,42 +7535,38 @@ This is primarily used in session saving.
Return:
-* 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.
+* 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.
<a id="ui.goto_file"></a>
#### `ui.goto_file`(*filename, split, preferred\_view, sloppy*)
Switches to the existing view whose buffer's filename is *filename*.
-If no view was found and *split* is `true`, splits the current view in order
-to show the requested file. If *split* is `false`, shifts to the next or
-*preferred_view* view in order to show the requested file. If *sloppy* is
-`true`, requires only the basename of *filename* to match a buffer's
-`filename`. If the requested file was not found, it is opened in the desired
-view.
+If no view was found and *split* is `true`, splits the current view in order to show the
+requested file. If *split* is `false`, shifts to the next or *preferred_view* view in order
+to show the requested file. If *sloppy* is `true`, requires only the basename of *filename*
+to match a buffer's `filename`. If the requested file was not found, it is opened in the
+desired view.
Parameters:
* *`filename`*: The filename of the buffer to go to.
-* *`split`*: Optional flag that indicates whether or not to open the buffer
- in a split view if there is only one view. The default value is `false`.
-* *`preferred_view`*: Optional view to open the desired buffer in if the
- buffer is not visible in any other view.
-* *`sloppy`*: Optional flag that indicates whether or not to not match
- *filename* to `buffer.filename` exactly. When `true`, matches *filename* to
- only the last part of `buffer.filename` This is useful for run and compile
- commands which output relative filenames and paths instead of full ones and
- it is likely that the file in question is already open. The default value
- is `false`.
+* *`split`*: Optional flag that indicates whether or not to open the buffer in a split view
+ if there is only one view. The default value is `false`.
+* *`preferred_view`*: Optional view to open the desired buffer in if the buffer is not
+ visible in any other view.
+* *`sloppy`*: Optional flag that indicates whether or not to not match *filename* to
+ `buffer.filename` exactly. When `true`, matches *filename* to only the last part of
+ `buffer.filename` This is useful for run and compile commands which output relative filenames
+ and paths instead of full ones and it is likely that the file in question is already open.
+ The default value is `false`.
<a id="ui.goto_view"></a>
#### `ui.goto_view`(*view*)
-Shifts to view *view* or the view *view* number of views relative to the
-current one.
+Shifts to view *view* or the view *view* number of views relative to the current one.
Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.
Parameters:
@@ -7960,20 +7582,18 @@ See also:
<a id="ui.menu"></a>
#### `ui.menu`(*menu\_table*)
-Low-level function for creating a menu from table *menu_table* and returning
-the userdata.
+Low-level function for creating a menu from table *menu_table* and returning the userdata.
You probably want to use the higher-level `textadept.menu.menubar`,
`textadept.menu.context_menu`, or `textadept.menu.tab_context_menu` tables.
Emits a `MENU_CLICKED` event when a menu item is selected.
Parameters:
-* *`menu_table`*: A table defining the menu. It is an ordered list of tables
- with a string menu item, integer menu ID, and optional GDK keycode and
- modifier mask. The latter two are used to display key shortcuts in the
- menu. '_' characters are treated as a menu mnemonics. If the menu item is
- empty, a menu separator item is created. Submenus are just nested
- menu-structure tables. Their title text is defined with a `title` key.
+* *`menu_table`*: A table defining the menu. It is an ordered list of tables with a string
+ menu item, integer menu ID, and optional GDK keycode and modifier mask. The latter
+ two are used to display key shortcuts in the menu. '_' characters are treated as a menu
+ mnemonics. If the menu item is empty, a menu separator item is created. Submenus are just
+ nested menu-structure tables. Their title text is defined with a `title` key.
Usage:
@@ -8001,14 +7621,13 @@ Parameters:
#### `ui.switch_buffer`(*zorder*)
Prompts the user to select a buffer to switch to.
-Buffers are listed in the order they were opened unless `zorder` is `true`,
-in which case buffers are listed by their z-order (most recently viewed to
-least recently viewed).
+Buffers are listed in the order they were opened unless `zorder` is `true`, in which case
+buffers are listed by their z-order (most recently viewed to least recently viewed).
Parameters:
-* *`zorder`*: Flag that indicates whether or not to list buffers by their
- z-order. The default value is `false`.
+* *`zorder`*: Flag that indicates whether or not to list buffers by their z-order. The
+ default value is `false`.
<a id="ui.update"></a>
#### `ui.update`()
@@ -8023,8 +7642,7 @@ This function is primarily used in unit tests.
#### `ui.menubar`
A table of menus defining a menubar. (Write-only).
-This is a low-level field. You probably want to use the higher-level
-`textadept.menu.menubar`.
+This is a low-level field. You probably want to use the higher-level `textadept.menu.menubar`.
See also:
@@ -8041,8 +7659,8 @@ A table containing the width and height pixel values of Textadept's window.
---
Textadept's Command Entry.
-It supports multiple modes that each have their own functionality (such as
-running Lua code and filtering text through shell commands) and history.
+It supports multiple modes that each have their own functionality (such as running Lua code
+and filtering text through shell commands) and history.
### Fields defined by `ui.command_entry`
@@ -8062,17 +7680,15 @@ The height in pixels of the command entry.
<a id="ui.command_entry.append_history"></a>
#### `ui.command_entry.append_history`(*f, text*)
-Appends string *text* to the history for command entry mode *f* or the
-current or most recent mode.
-This should only be called if `ui.command_entry.run()` is called with a keys
-table that has a custom binding for the Enter key ('\n').
-Otherwise, history is automatically appended as needed.
+Appends string *text* to the history for command entry mode *f* or the current or most
+recent mode.
+This should only be called if `ui.command_entry.run()` is called with a keys table that has a
+custom binding for the Enter key ('\n'). Otherwise, history is automatically appended as needed.
Parameters:
-* *`f`*: Optional command entry mode to append history to. This is a function
- passed to `ui.command_entry_run()`. If omitted, uses the current or most
- recent mode.
+* *`f`*: Optional command entry mode to append history to. This is a function passed to
+ `ui.command_entry_run()`. If omitted, uses the current or most recent mode.
* *`text`*: String text to append to history.
<a id="ui.command_entry.focus"></a>
@@ -8083,31 +7699,25 @@ Opens the command entry.
<a id="ui.command_entry.run"></a>
#### `ui.command_entry.run`(*f, keys, lang, height*)
-Opens the command entry, subjecting it to any key bindings defined in table
-*keys*, highlighting text with lexer name *lang*, and displaying
-*height* number of lines at a time, and then when the `Enter` key is pressed,
-closes the command entry and calls function *f* (if non-`nil`) with the
-command entry's text as an argument.
+Opens the command entry, subjecting it to any key bindings defined in table *keys*,
+highlighting text with lexer name *lang*, and displaying *height* number of lines at a time,
+and then when the `Enter` key is pressed, closes the command entry and calls function *f*
+(if non-`nil`) with the command entry's text as an argument.
By default with no arguments given, opens a Lua command entry.
-The command entry does not respond to Textadept's default key bindings, but
-instead to the key bindings defined in *keys* and in
-`ui.command_entry.editing_keys`.
+The command entry does not respond to Textadept's default key bindings, but instead to the
+key bindings defined in *keys* and in `ui.command_entry.editing_keys`.
Parameters:
-* *`f`*: Optional function to call upon pressing `Enter` in the command
- entry, ending the mode. It should accept the command entry text as an
- argument.
-* *`keys`*: Optional table of key bindings to respond to. This is in
- addition to the basic editing and movement keys defined in
- `ui.command_entry.editing_keys`.
- `Esc` and `Enter` are automatically defined to cancel and finish the
- command entry, respectively.
+* *`f`*: Optional function to call upon pressing `Enter` in the command entry, ending the mode.
+ It should accept the command entry text as an argument.
+* *`keys`*: Optional table of key bindings to respond to. This is in addition to the
+ basic editing and movement keys defined in `ui.command_entry.editing_keys`. `Esc` and
+ `Enter` are automatically defined to cancel and finish the command entry, respectively.
This parameter may be omitted completely.
-* *`lang`*: Optional string lexer name to use for command entry text. The
- default value is `'text'`.
-* *`height`*: Optional number of lines to display in the command entry. The
- default value is `1`.
+* *`lang`*: Optional string lexer name to use for command entry text. The default value is
+ `'text'`.
+* *`height`*: Optional number of lines to display in the command entry. The default value is `1`.
Usage:
@@ -8124,9 +7734,8 @@ See also:
#### `ui.command_entry.editing_keys`
A metatable with typical platform-specific key bindings for text entries.
-This metatable may be used to add basic editing and movement keys to command
-entry modes. It is automatically added to command entry modes unless a
-metatable was previously set.
+This metatable may be used to add basic editing and movement keys to command entry modes. It
+is automatically added to command entry modes unless a metatable was previously set.
Usage:
@@ -8144,8 +7753,8 @@ Provides a set of interactive dialog prompts for user input.
<a id="ui.dialogs.colorselect"></a>
#### `ui.dialogs.colorselect`(*options*)
-Prompts the user with a color selection dialog defined by dialog options
-table *options*, returning the color selected.
+Prompts the user with a color selection dialog defined by dialog options table *options*,
+returning the color selected.
If the user canceled the dialog, returns `nil`.
Parameters:
@@ -8153,16 +7762,14 @@ Parameters:
* *`options`*: Table of key-value option pairs for the option select dialog.
* `title`: The dialog's title text.
- * `color`: The initially selected color as either a number in "0xBBGGRR"
- format, or as a string in "#RRGGBB" format.
- * `palette`: The list of colors to show in the dialog's color palette.
- Up to 20 colors can be specified as either numbers in "0xBBGGRR" format
- or as strings in "#RRGGBB" format. If `true` (no list was given), a
- default palette is shown.
- * `string_output`: Return the selected color in string "#RRGGBB" format
- instead of as a number. The default value is `false`.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
+ * `color`: The initially selected color as either a number in "0xBBGGRR" format, or as a
+ string in "#RRGGBB" format.
+ * `palette`: The list of colors to show in the dialog's color palette. Up to 20 colors can
+ be specified as either numbers in "0xBBGGRR" format or as strings in "#RRGGBB" format. If
+ `true` (no list was given), a default palette is shown.
+ * `string_output`: Return the selected color in string "#RRGGBB" format instead of as a
+ number. The default value is `false`.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
Usage:
@@ -8176,15 +7783,12 @@ Return:
<a id="ui.dialogs.dropdown"></a>
#### `ui.dialogs.dropdown`(*options*)
-Prompts the user with a drop-down item selection dialog defined by dialog
-options table *options*, returning the selected button's index along with the
-index of the selected item.
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the selected item's text.
-If the dialog closed due to *options*.`exit_onchange`, returns `4` along with
-either the selected item's index or its text. If the dialog timed out,
-returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or
-`"delete"`.
+Prompts the user with a drop-down item selection dialog defined by dialog options table
+*options*, returning the selected button's index along with the index of the selected item.
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+selected item's text. If the dialog closed due to *options*.`exit_onchange`, returns `4`
+along with either the selected item's index or its text. If the dialog timed out, returns
+`0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.
Parameters:
@@ -8193,30 +7797,24 @@ Parameters:
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `items`: The list of string items to show in the drop-down.
- * `button1`: The right-most button's label. The default value is
- `_L['OK']`.
+ * `button1`: The right-most button's label. The default value is `_L['OK']`.
* `button2`: The middle button's label.
- * `button3`: The left-most button's label. This option requires `button2`
- to be set.
- * `exit_onchange`: Close the dialog after selecting a new item. The default
- value is `false`.
- * `select`: The index of the initially selected list item. The default
- value is `1`.
- * `string_output`: Return the selected button's label (instead of its
- index) and the selected item's text (instead of its index). If no item
- was selected, returns the dialog's exit status (instead of its exit
- code). The default value is `false`.
+ * `button3`: The left-most button's label. This option requires `button2` to be set.
+ * `exit_onchange`: Close the dialog after selecting a new item. The default value is `false`.
+ * `select`: The index of the initially selected list item. The default value is `1`.
+ * `string_output`: Return the selected button's label (instead of its index) and the selected
+ item's text (instead of its index). If no item was selected, returns the dialog's exit
+ status (instead of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Usage:
-* `ui.dialogs.dropdown{title = 'Select Encoding', width = 200,
- items = io.encodings, string_output = true}`
+* `ui.dialogs.dropdown{title = 'Select Encoding', width = 200, items = io.encodings,
+ string_output = true}`
Return:
@@ -8225,8 +7823,8 @@ Return:
<a id="ui.dialogs.filesave"></a>
#### `ui.dialogs.filesave`(*options*)
-Prompts the user with a file save dialog defined by dialog options table
-*options*, returning the string file chosen.
+Prompts the user with a file save dialog defined by dialog options table *options*, returning
+the string file chosen.
If the user canceled the dialog, returns `nil`.
Parameters:
@@ -8235,11 +7833,10 @@ Parameters:
* `title`: The dialog's title text.
* `with_directory`: The initial filesystem directory to show.
- * `with_file`: The initially chosen filename. This option requires
- `with_directory` to be set.
+ * `with_file`: The initially chosen filename. This option requires `with_directory` to be set.
* `with_extension`: The list of extensions selectable files must have.
- * `no_create_directories`: Prevent the user from creating new directories.
- The default value is `false`.
+ * `no_create_directories`: Prevent the user from creating new directories. The default
+ value is `false`.
Return:
@@ -8248,10 +7845,10 @@ Return:
<a id="ui.dialogs.fileselect"></a>
#### `ui.dialogs.fileselect`(*options*)
-Prompts the user with a file selection dialog defined by dialog options
-table *options*, returning the string file selected.
-If *options*.`select_multiple` is `true`, returns the list of files selected.
-If the user canceled the dialog, returns `nil`.
+Prompts the user with a file selection dialog defined by dialog options table *options*,
+returning the string file selected.
+If *options*.`select_multiple` is `true`, returns the list of files selected. If the user
+canceled the dialog, returns `nil`.
Parameters:
@@ -8259,13 +7856,12 @@ Parameters:
* `title`: The dialog's title text.
* `with_directory`: The initial filesystem directory to show.
- * `with_file`: The initially selected filename. This option requires
- `with_directory` to be set.
+ * `with_file`: The initially selected filename. This option requires `with_directory`
+ to be set.
* `with_extension`: The list of extensions selectable files must have.
- * `select_multiple`: Allow the user to select multiple files. The default
- value is `false`.
- * `select_only_directories`: Only allow the user to select directories. The
- default value is `false`.
+ * `select_multiple`: Allow the user to select multiple files. The default value is `false`.
+ * `select_only_directories`: Only allow the user to select directories. The default value is
+ `false`.
Usage:
@@ -8279,14 +7875,12 @@ Return:
<a id="ui.dialogs.filteredlist"></a>
#### `ui.dialogs.filteredlist`(*options*)
-Prompts the user with a filtered list item selection dialog defined by dialog
-options table *options*, returning the selected button's index along with the
-index or indices of the selected item or items (depending on whether or not
-*options*.`select_multiple` is `true`).
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the text of the selected item or items.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with a filtered list item selection dialog defined by dialog options table
+*options*, returning the selected button's index along with the index or indices of the
+selected item or items (depending on whether or not *options*.`select_multiple` is `true`).
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+text of the selected item or items. If the dialog timed out, returns `0` or `"timeout"`. If
+the user canceled the dialog, returns `-1` or `"delete"`.
Spaces in the filter text are treated as wildcards.
Parameters:
@@ -8298,30 +7892,23 @@ Parameters:
* `text`: The dialog's initial input text.
* `columns`: The list of string column names for list rows.
* `items`: The list of string items to show in the filtered list.
- * `button1`: The right-most button's label. The default value is
- `_L['OK']`.
+ * `button1`: The right-most button's label. The default value is `_L['OK']`.
* `button2`: The middle button's label.
- * `button3`: The left-most button's label. This option requires `button2`
- to be set.
- * `select_multiple`: Allow the user to select multiple items. The default
- value is `false`.
- * `search_column`: The column number to filter the input text against. The
- default value is `1`. This option requires `columns` to be set and
- contain at least *n* column names.
- * `output_column`: The column number to use for `string_output`. The
- default value is `1`. This option requires `columns` to be set and
- contain at least *n* column names.
- * `string_output`: Return the selected button's label (instead of its
- index) and the selected item's text (instead of its index). If no item
- was selected, returns the dialog's exit status (instead of its exit
- code). The default value is `false`.
- * `width`: The dialog's pixel width. The default width stretches nearly the
- width of Textadept's window.
+ * `button3`: The left-most button's label. This option requires `button2` to be set.
+ * `select_multiple`: Allow the user to select multiple items. The default value is `false`.
+ * `search_column`: The column number to filter the input text against. The default value is
+ `1`. This option requires `columns` to be set and contain at least *n* column names.
+ * `output_column`: The column number to use for `string_output`. The default value is
+ `1`. This option requires `columns` to be set and contain at least *n* column names.
+ * `string_output`: Return the selected button's label (instead of its index) and the selected
+ item's text (instead of its index). If no item was selected, returns the dialog's exit
+ status (instead of its exit code). The default value is `false`.
+ * `width`: The dialog's pixel width. The default width stretches nearly the width of
+ Textadept's window.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Usage:
@@ -8335,8 +7922,8 @@ Return:
<a id="ui.dialogs.fontselect"></a>
#### `ui.dialogs.fontselect`(*options*)
-Prompts the user with a font selection dialog defined by dialog options
-table *options*, returning the font selected (including style and size).
+Prompts the user with a font selection dialog defined by dialog options table *options*,
+returning the font selected (including style and size).
If the user canceled the dialog, returns `nil`.
Parameters:
@@ -8347,16 +7934,13 @@ Parameters:
* `text`: The font preview text.
* `font_name`: The initially selected font name.
* `font_size`: The initially selected font size. The default value is `12`.
- * `font_style`: The initially selected font style. The available options
- are `"regular"`, `"bold"`, `"italic"`, and `"bold italic"`. The default
- value is `"regular"`.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
+ * `font_style`: The initially selected font style. The available options are `"regular"`,
+ `"bold"`, `"italic"`, and `"bold italic"`. The default value is `"regular"`.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
Usage:
-* `ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace',
- font_size = 10}`
+* `ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace', font_size = 10}`
Return:
@@ -8365,41 +7949,34 @@ Return:
<a id="ui.dialogs.inputbox"></a>
#### `ui.dialogs.inputbox`(*options*)
-Prompts the user with an inputbox dialog defined by dialog options table
-*options*, returning the selected button's index along with the user's
-input text (the latter as a string or table, depending on the type of
-*options*.`informative_text`).
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the user's input text.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with an inputbox dialog defined by dialog options table *options*, returning
+the selected button's index along with the user's input text (the latter as a string or table,
+depending on the type of *options*.`informative_text`).
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+user's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled
+the dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
- * `informative_text`: The dialog's main message text. If the value is a
- table, the first table value is the main message text and any subsequent
- values are used as the labels for multiple entry boxes. Providing a
- single label has no effect.
- * `text`: The dialog's initial input text. If the value is a table, the
- table values are used to populate the multiple entry boxes defined by
- `informative_text`.
- * `button1`: The right-most button's label. The default value is
- `_L['OK']`.
+ * `informative_text`: The dialog's main message text. If the value is a table, the first
+ table value is the main message text and any subsequent values are used as the labels
+ for multiple entry boxes. Providing a single label has no effect.
+ * `text`: The dialog's initial input text. If the value is a table, the table values are
+ used to populate the multiple entry boxes defined by `informative_text`.
+ * `button1`: The right-most button's label. The default value is `_L['OK']`.
* `button2`: The middle button's label.
- * `button3`: The left-most button's label. This option requires `button2`
- to be set.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
+ * `button3`: The left-most button's label. This option requires `button2` to be set.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
+ `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Usage:
@@ -8413,11 +7990,10 @@ Return:
<a id="ui.dialogs.msgbox"></a>
#### `ui.dialogs.msgbox`(*options*)
-Prompts the user with a generic message box dialog defined by dialog options
-table *options*, returning the selected button's index.
-If *options*.`string_output` is `true`, returns the selected button's label.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with a generic message box dialog defined by dialog options table *options*,
+returning the selected button's index.
+If *options*.`string_output` is `true`, returns the selected button's label. If the dialog timed
+out, returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.
Parameters:
@@ -8426,25 +8002,21 @@ Parameters:
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `informative_text`: The dialog's extra informative text.
- * `icon`: The dialog's GTK stock icon name. Examples are
- "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
- "gtk-dialog-warning". The dialog does not display an icon by default.
- * `icon_file`: The dialog's icon file path. This option has no effect when
- `icon` is set.
- * `button1`: The right-most button's label. The default value is
- `_L['OK']`.
+ * `icon`: The dialog's GTK stock icon name. Examples are "gtk-dialog-error",
+ "gtk-dialog-info", "gtk-dialog-question", and "gtk-dialog-warning". The dialog does not
+ display an icon by default.
+ * `icon_file`: The dialog's icon file path. This option has no effect when `icon` is set.
+ * `button1`: The right-most button's label. The default value is `_L['OK']`.
* `button2`: The middle button's label.
- * `button3`: The left-most button's label. This option requires `button2`
- to be set.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
+ * `button3`: The left-most button's label. This option requires `button2` to be set.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
+ `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Usage:
@@ -8459,12 +8031,10 @@ Return:
<a id="ui.dialogs.ok_msgbox"></a>
#### `ui.dialogs.ok_msgbox`(*options*)
-Prompts the user with a generic message box dialog defined by dialog options
-table *options* and with localized "Ok" and "Cancel" buttons, returning the
-selected button's index.
-If *options*.`string_output` is `true`, returns the selected button's label.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with a generic message box dialog defined by dialog options table *options*
+and with localized "Ok" and "Cancel" buttons, returning the selected button's index.
+If *options*.`string_output` is `true`, returns the selected button's label. If the dialog timed
+out, returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.
Parameters:
@@ -8473,22 +8043,19 @@ Parameters:
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `informative_text`: The dialog's extra informative text.
- * `icon`: The dialog's GTK stock icon name. Examples are
- "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
- "gtk-dialog-warning". The dialog does not display an icon by default.
- * `icon_file`: The dialog's icon file path. This option has no effect when
- `icon` is set.
- * `no_cancel`: Do not display the "Cancel" button. The default value is
+ * `icon`: The dialog's GTK stock icon name. Examples are "gtk-dialog-error",
+ "gtk-dialog-info", "gtk-dialog-question", and "gtk-dialog-warning". The dialog does not
+ display an icon by default.
+ * `icon_file`: The dialog's icon file path. This option has no effect when `icon` is set.
+ * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
`false`.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Return:
@@ -8497,13 +8064,11 @@ Return:
<a id="ui.dialogs.optionselect"></a>
#### `ui.dialogs.optionselect`(*options*)
-Prompts the user with an option selection dialog defined by dialog options
-table *options*, returning the selected button's index along with the indices
-of the selected options.
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the text of the selected options.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with an option selection dialog defined by dialog options table *options*,
+returning the selected button's index along with the indices of the selected options.
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+text of the selected options. If the dialog timed out, returns `0` or `"timeout"`. If the
+user canceled the dialog, returns `-1` or `"delete"`.
Parameters:
@@ -8512,22 +8077,18 @@ Parameters:
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `items`: The list of string options to show in the option group.
- * `button1`: The right-most button's label. The default value is
- `_L['OK']`.
+ * `button1`: The right-most button's label. The default value is `_L['OK']`.
* `button2`: The middle button's label.
- * `button3`: The left-most button's label. This option requires `button2`
- to be set.
+ * `button3`: The left-most button's label. This option requires `button2` to be set.
* `select`: The indices of initially selected options.
- * `string_output`: Return the selected button's label or the dialog's exit
- status along with the selected options' text instead of the button's
- index or the dialog's exit code along with the options' indices. The
- default value is `false`.
+ * `string_output`: Return the selected button's label or the dialog's exit status along
+ with the selected options' text instead of the button's index or the dialog's exit code
+ along with the options' indices. The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Usage:
@@ -8542,10 +8103,10 @@ Return:
<a id="ui.dialogs.progressbar"></a>
#### `ui.dialogs.progressbar`(*options, f*)
-Displays a progressbar dialog, defined by dialog options table *options*,
-that receives updates from function *f*.
-Returns "stopped" if *options*.`stoppable` is `true` and the user clicked the
-"Stop" button. Otherwise, returns `nil`.
+Displays a progressbar dialog, defined by dialog options table *options*, that receives
+updates from function *f*.
+Returns "stopped" if *options*.`stoppable` is `true` and the user clicked the "Stop"
+button. Otherwise, returns `nil`.
Parameters:
@@ -8554,17 +8115,15 @@ Parameters:
* `title`: The dialog's title text.
* `percent`: The initial progressbar percentage between 0 and 100.
* `text`: The initial progressbar display text (GTK only).
- * `indeterminate`: Show the progress bar as "busy", with no percentage
- updates.
+ * `indeterminate`: Show the progress bar as "busy", with no percentage updates.
* `stoppable`: Show the "Stop" button.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
-* *`f`*: Function repeatedly called to do work and provide progress updates.
- The 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 an optional string to display (GTK only). If the text is
- either "stop disable" or "stop enable" and *options*.`stoppable` is `true`,
- the "Stop" button is disabled or enabled, respectively.
+* *`f`*: Function repeatedly called to do work and provide progress updates. The 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 an optional string to display (GTK
+ only). If the text is either "stop disable" or "stop enable" and *options*.`stoppable` is
+ `true`, the "Stop" button is disabled or enabled, respectively.
Usage:
@@ -8578,41 +8137,34 @@ Return:
<a id="ui.dialogs.secure_inputbox"></a>
#### `ui.dialogs.secure_inputbox`(*options*)
-Prompts the user with a masked inputbox dialog defined by dialog options
-table *options*, returning the selected button's index along with the user's
-input text (the latter as a string or table, depending on the type of
-*options*.`informative_text`).
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the user's input text.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with a masked inputbox dialog defined by dialog options table *options*,
+returning the selected button's index along with the user's input text (the latter as a
+string or table, depending on the type of *options*.`informative_text`).
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+user's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled
+the dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
- * `informative_text`: The dialog's main message text. If the value is a
- table, the first table value is the main message text and any subsequent
- values are used as the labels for multiple entry boxes. Providing a
- single label has no effect.
- * `text`: The dialog's initial input text. If the value is a table, the
- table values are used to populate the multiple entry boxes defined by
- `informative_text`.
- * `button1`: The right-most button's label. The default value is
- `_L['OK']`.
+ * `informative_text`: The dialog's main message text. If the value is a table, the first
+ table value is the main message text and any subsequent values are used as the labels
+ for multiple entry boxes. Providing a single label has no effect.
+ * `text`: The dialog's initial input text. If the value is a table, the table values are
+ used to populate the multiple entry boxes defined by `informative_text`.
+ * `button1`: The right-most button's label. The default value is `_L['OK']`.
* `button2`: The middle button's label.
- * `button3`: The left-most button's label. This option requires `button2`
- to be set.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
+ * `button3`: The left-most button's label. This option requires `button2` to be set.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
+ `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Return:
@@ -8621,38 +8173,33 @@ Return:
<a id="ui.dialogs.secure_standard_inputbox"></a>
#### `ui.dialogs.secure_standard_inputbox`(*options*)
-Prompts the user with a masked inputbox dialog defined by dialog options
-table *options* and with localized "Ok" and "Cancel" buttons, returning the
-selected button's index along with the user's input text (the latter as a
-string or table, depending on the type of *options*.`informative_text`).
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the user's input text.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with a masked inputbox dialog defined by dialog options table *options*
+and with localized "Ok" and "Cancel" buttons, returning the selected button's index along
+with the user's input text (the latter as a string or table, depending on the type of
+*options*.`informative_text`).
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+user's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled
+the dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
- * `informative_text`: The dialog's main message text. If the value is a
- table, the first table value is the main message text and any subsequent
- values are used as the labels for multiple entry boxes. Providing a
- single label has no effect.
- * `text`: The dialog's initial input text. If the value is a table, the
- table values are used to populate the multiple entry boxes defined by
- `informative_text`.
- * `no_cancel`: Do not display the "Cancel" button. The default value is
+ * `informative_text`: The dialog's main message text. If the value is a table, the first
+ table value is the main message text and any subsequent values are used as the labels
+ for multiple entry boxes. Providing a single label has no effect.
+ * `text`: The dialog's initial input text. If the value is a table, the table values are
+ used to populate the multiple entry boxes defined by `informative_text`.
+ * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
`false`.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Return:
@@ -8661,15 +8208,13 @@ Return:
<a id="ui.dialogs.standard_dropdown"></a>
#### `ui.dialogs.standard_dropdown`(*options*)
-Prompts the user with a drop-down item selection dialog defined by dialog
-options table *options* and with localized "Ok" and "Cancel" buttons,
-returning the selected button's index along with the selected item's index.
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the selected item's text.
-If the dialog closed due to *options*.`exit_onchange`, returns `4` along with
-either the selected item's index or its text. If the dialog timed out,
-returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or
-`"delete"`.
+Prompts the user with a drop-down item selection dialog defined by dialog options table
+*options* and with localized "Ok" and "Cancel" buttons, returning the selected button's
+index along with the selected item's index.
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+selected item's text. If the dialog closed due to *options*.`exit_onchange`, returns `4`
+along with either the selected item's index or its text. If the dialog timed out, returns
+`0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.
Parameters:
@@ -8678,22 +8223,17 @@ Parameters:
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `items`: The list of string items to show in the drop-down.
- * `no_cancel`: Do not display the "Cancel" button. The default value is
- `false`.
- * `exit_onchange`: Close the dialog after selecting a new item. The default
- value is `false`.
- * `select`: The index of the initially selected list item. The default
- value is `1`.
- * `string_output`: Return the selected button's label (instead of its
- index) and the selected item's text (instead of its index). If no item
- was selected, returns the dialog's exit status (instead of its exit
- code). The default value is `false`.
+ * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.
+ * `exit_onchange`: Close the dialog after selecting a new item. The default value is `false`.
+ * `select`: The index of the initially selected list item. The default value is `1`.
+ * `string_output`: Return the selected button's label (instead of its index) and the selected
+ item's text (instead of its index). If no item was selected, returns the dialog's exit
+ status (instead of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Return:
@@ -8702,38 +8242,33 @@ Return:
<a id="ui.dialogs.standard_inputbox"></a>
#### `ui.dialogs.standard_inputbox`(*options*)
-Prompts the user with an inputbox dialog defined by dialog options table
-*options* and with localized "Ok" and "Cancel" buttons, returning the
-selected button's index along with the user's input text (the latter as a
-string or table, depending on the type of *options*.`informative_text`).
-If *options*.`string_output` is `true`, returns the selected button's label
-along with the user's input text.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with an inputbox dialog defined by dialog options table *options* and
+with localized "Ok" and "Cancel" buttons, returning the selected button's index along
+with the user's input text (the latter as a string or table, depending on the type of
+*options*.`informative_text`).
+If *options*.`string_output` is `true`, returns the selected button's label along with the
+user's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled
+the dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
- * `informative_text`: The dialog's main message text. If the value is a
- table, the first table value is the main message text and any subsequent
- values are used as the labels for multiple entry boxes. Providing a
- single label has no effect.
- * `text`: The dialog's initial input text. If the value is a table, the
- table values are used to populate the multiple entry boxes defined by
- `informative_text`.
- * `no_cancel`: Do not display the "Cancel" button. The default value is
+ * `informative_text`: The dialog's main message text. If the value is a table, the first
+ table value is the main message text and any subsequent values are used as the labels
+ for multiple entry boxes. Providing a single label has no effect.
+ * `text`: The dialog's initial input text. If the value is a table, the table values are
+ used to populate the multiple entry boxes defined by `informative_text`.
+ * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
`false`.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Return:
@@ -8742,12 +8277,11 @@ Return:
<a id="ui.dialogs.textbox"></a>
#### `ui.dialogs.textbox`(*options*)
-Prompts the user with a multiple-line textbox dialog defined by dialog
-options table *options*, returning the selected button's index.
-If *options*.`string_output` is `true`, returns the selected button's label.
-If *options*.`editable` is `true`, also returns the textbox's text. If the
-dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with a multiple-line textbox dialog defined by dialog options table *options*,
+returning the selected button's index.
+If *options*.`string_output` is `true`, returns the selected button's label. If
+*options*.`editable` is `true`, also returns the textbox's text. If the dialog timed out,
+returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.
Parameters:
@@ -8756,38 +8290,31 @@ Parameters:
* `title`: The dialog's title text.
* `informative_text`: The dialog's main message text.
* `text`: The dialog's initial textbox text.
- * `text_from_file`: The filename whose contents are loaded into the
- textbox. This option has no effect when `text` is given.
- * `button1`: The right-most button's label. The default value is
- `_L['OK']`.
+ * `text_from_file`: The filename whose contents are loaded into the textbox. This option
+ has no effect when `text` is given.
+ * `button1`: The right-most button's label. The default value is `_L['OK']`.
* `button2`: The middle button's label.
- * `button3`: The left-most button's label. This option requires `button2`
- to be set.
- * `editable`: Allows the user to edit the textbox's text. The default value
- is `false`.
- * `focus_textbox`: Focus the textbox instead of the buttons. The default
- value is `false`.
- * `scroll_to`: Where to scroll the textbox's text.
- The available values are `"top"` and `"bottom"`. The default value is
- `"top"`.
- * `selected`: Select all of the textbox's text. The default value is
+ * `button3`: The left-most button's label. This option requires `button2` to be set.
+ * `editable`: Allows the user to edit the textbox's text. The default value is `false`.
+ * `focus_textbox`: Focus the textbox instead of the buttons. The default value is `false`.
+ * `scroll_to`: Where to scroll the textbox's text. The available values are `"top"` and
+ `"bottom"`. The default value is `"top"`.
+ * `selected`: Select all of the textbox's text. The default value is `false`.
+ * `monospaced_font`: Use a monospaced font in the textbox instead of a proportional one. The
+ default value is `false`.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
`false`.
- * `monospaced_font`: Use a monospaced font in the textbox instead of a
- proportional one. The default value is `false`.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Usage:
-* `ui.dialogs.textbox{title = 'License Agreement',
- informative_text = 'You agree to:', text_from_file = _HOME..'/LICENSE'}`
+* `ui.dialogs.textbox{title = 'License Agreement', informative_text = 'You agree to:',
+ text_from_file = _HOME..'/LICENSE'}`
Return:
@@ -8796,12 +8323,10 @@ Return:
<a id="ui.dialogs.yesno_msgbox"></a>
#### `ui.dialogs.yesno_msgbox`(*options*)
-Prompts the user with a generic message box dialog defined by dialog options
-table *options* and with localized "Yes", "No", and "Cancel" buttons,
-returning the selected button's index.
-If *options*.`string_output` is `true`, returns the selected button's label.
-If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
-dialog, returns `-1` or `"delete"`.
+Prompts the user with a generic message box dialog defined by dialog options table *options*
+and with localized "Yes", "No", and "Cancel" buttons, returning the selected button's index.
+If *options*.`string_output` is `true`, returns the selected button's label. If the dialog timed
+out, returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.
Parameters:
@@ -8810,22 +8335,19 @@ Parameters:
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `informative_text`: The dialog's extra informative text.
- * `icon`: The dialog's GTK stock icon name. Examples are
- "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
- "gtk-dialog-warning". The dialog does not display an icon by default.
- * `icon_file`: The dialog's icon file path. This option has no effect when
- `icon` is set.
- * `no_cancel`: Do not display the "Cancel" button. The default value is
+ * `icon`: The dialog's GTK stock icon name. Examples are "gtk-dialog-error",
+ "gtk-dialog-info", "gtk-dialog-question", and "gtk-dialog-warning". The dialog does not
+ display an icon by default.
+ * `icon_file`: The dialog's icon file path. This option has no effect when `icon` is set.
+ * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.
+ * `string_output`: Return the selected button's label (instead of its index) or the dialog's
+ exit status instead of the button's index (instead of its exit code). The default value is
`false`.
- * `string_output`: Return the selected button's label (instead of its
- index) or the dialog's exit status instead of the button's index (instead
- of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
- * `float`: Show the dialog on top of all desktop windows. The default value
- is `false`.
- * `timeout`: The integer number of seconds the dialog waits for the user to
- select a button before timing out. Dialogs do not time out by default.
+ * `float`: Show the dialog on top of all desktop windows. The default value is `false`.
+ * `timeout`: The integer number of seconds the dialog waits for the user to select a button
+ before timing out. Dialogs do not time out by default.
Return:
@@ -8849,8 +8371,7 @@ The find results highlight indicator number.
<a id="events.FIND_RESULT_FOUND"></a>
#### `events.FIND_RESULT_FOUND` (string)
-Emitted when a result is found. It is selected and has been scrolled into
- view.
+Emitted when a result is found. It is selected and has been scrolled into view.
Arguments:
* _`find_text`_: The text originally searched for.
@@ -8858,11 +8379,11 @@ Emitted when a result is found. It is selected and has been scrolled into
<a id="events.FIND_WRAPPED"></a>
#### `events.FIND_WRAPPED` (string)
-Emitted when a text search wraps (passes through the beginning of the
- buffer), either from bottom to top (when searching for a next occurrence),
- or from top to bottom (when searching for a previous occurrence).
- This is useful for implementing a more visual or audible notice when a
- search wraps in addition to the statusbar message.
+Emitted when a text search wraps (passes through the beginning of the buffer), either
+ from bottom to top (when searching for a next occurrence), or from top to bottom (when
+ searching for a previous occurrence).
+ This is useful for implementing a more visual or audible notice when a search wraps in
+ addition to the statusbar message.
<a id="ui.find.active"></a>
#### `ui.find.active` (boolean)
@@ -8895,8 +8416,7 @@ The text of the "Find Prev" button.
<a id="ui.find.highlight_all_matches"></a>
#### `ui.find.highlight_all_matches` (boolean)
-Whether or not to highlight all occurrences of found text in the current
- buffer.
+Whether or not to highlight all occurrences of found text in the current buffer.
The default value is `false`.
<a id="ui.find.in_files"></a>
@@ -8957,8 +8477,7 @@ The text of the "Replace" button.
#### `ui.find.replace_entry_text` (string)
The text in the "Replace" entry.
- When searching for text in a directory of files, this is the current file
- and directory filter.
+ When searching for text in a directory of files, this is the current file and directory filter.
<a id="ui.find.replace_label_text"></a>
#### `ui.find.replace_label_text` (string, Write-only)
@@ -8969,8 +8488,7 @@ The text of the "Replace" label.
<a id="ui.find.whole_word"></a>
#### `ui.find.whole_word` (bool)
-Match search text only when it is surrounded by non-word characters in
- searches.
+Match search text only when it is surrounded by non-word characters in searches.
The default value is `false`.
<a id="ui.find.whole_word_label_text"></a>
@@ -8985,30 +8503,26 @@ The text of the "Whole word" label.
<a id="ui.find.find_in_files"></a>
#### `ui.find.find_in_files`(*dir, filter*)
-Searches directory *dir* or the user-specified directory for files that match
-search text and search options (subject to optional filter *filter*), and
-prints the results to a buffer titled "Files Found", highlighting found text.
-Use the `find_entry_text`, `match_case`, `whole_word`, and `regex` fields to
-set the search text and option flags, respectively.
+Searches directory *dir* or the user-specified directory for files that match search text
+and search options (subject to optional filter *filter*), and prints the results to a buffer
+titled "Files Found", highlighting found text.
+Use the `find_entry_text`, `match_case`, `whole_word`, and `regex` fields to set the search
+text and option flags, respectively.
A filter determines which files to search in, with the default filter being
-`ui.find.find_in_files_filters[dir]` (if it exists) or `lfs.default_filter`.
-A filter consists of Lua patterns that match file and directory paths to
-include or exclude. Patterns are inclusive by default. Exclusive patterns
-begin with a '!'. If no inclusive patterns are given, any filename is
-initially considered. As a convenience, file extensions can be specified
-literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/'
-also matches the Windows directory separator ('[/\\]' is not needed).
-If *filter* is `nil`, the filter from the `ui.find.find_in_files_filters`
-table for *dir* is used. If that filter does not exist, `lfs.default_filter`
-is used.
+`ui.find.find_in_files_filters[dir]` (if it exists) or `lfs.default_filter`. A filter consists
+of Lua patterns that match file and directory paths to include or exclude. Patterns are
+inclusive by default. Exclusive patterns begin with a '!'. If no inclusive patterns are given,
+any filename is initially considered. As a convenience, file extensions can be specified
+literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the
+Windows directory separator ('[/\\]' is not needed). If *filter* is `nil`, the filter from
+the `ui.find.find_in_files_filters` table for *dir* is used. If that filter does not exist,
+`lfs.default_filter` is used.
Parameters:
-* *`dir`*: Optional directory path to search. If `nil`, the user is prompted
- for one.
-* *`filter`*: Optional filter for files and directories to exclude. The
- default value is `lfs.default_filter` unless a filter for *dir* is defined
- in `ui.find.find_in_files_filters`.
+* *`dir`*: Optional directory path to search. If `nil`, the user is prompted for one.
+* *`filter`*: Optional filter for files and directories to exclude. The default value is
+ `lfs.default_filter` unless a filter for *dir* is defined in `ui.find.find_in_files_filters`.
See also:
@@ -9036,16 +8550,16 @@ Parameters:
<a id="ui.find.goto_file_found"></a>
#### `ui.find.goto_file_found`(*line\_num, next*)
-Jumps to the source of the find in files search result on line number
-*line_num* in the buffer titled "Files Found" or, if *line_num* is `nil`,
-jumps to the next or previous search result, depending on boolean *next*.
+Jumps to the source of the find in files search result on line number *line_num* in the buffer
+titled "Files Found" or, if *line_num* is `nil`, jumps to the next or previous search result,
+depending on boolean *next*.
Parameters:
-* *`line_num`*: Optional line number in the files found buffer that contains
- the search result to go to. This parameter may be omitted completely.
-* *`next`*: Optional flag indicating whether to go to the next search result
- or the previous one. Only applicable when *line_num* is `nil`.
+* *`line_num`*: Optional line number in the files found buffer that contains the search
+ result to go to. This parameter may be omitted completely.
+* *`next`*: Optional flag indicating whether to go to the next search result or the previous
+ one. Only applicable when *line_num* is `nil`.
<a id="ui.find.replace"></a>
#### `ui.find.replace`()
@@ -9064,8 +8578,8 @@ Mimics pressing the "Replace All" button.
#### `ui.find.find_in_files_filters`
Map of directory paths to filters used in `ui.find.find_in_files()`.
-This table is updated when the user manually specifies a filter in the
-"Filter" entry during an "In files" search.
+This table is updated when the user manually specifies a filter in the "Filter" entry during
+an "In files" search.
See also:
@@ -9078,17 +8592,15 @@ See also:
A Textadept view object.
Constants are documented in the fields they apply to.
-While you can work with individual view instances, it is often useful to work
-with just the global one.
-Many of these functions and fields are derived from view-specific
-functionality of the Scintilla editing component, and additional information
-can be found on the
-[Scintilla website](https://scintilla.org/ScintillaDoc.html).
-Note that with regard to Scintilla-specific functionality, this API is a
-_suggestion_, not a hard requirement. All of that functionality also exists
-in [`buffer`](#buffer), even if undocumented.
-Any view fields set on startup (e.g. in *~/.textadept/init.lua*) will be the
-default, initial values for all views.
+While you can work with individual view instances, it is often useful to work with just the
+global one.
+Many of these functions and fields are derived from view-specific functionality of the
+Scintilla editing component, and additional information can be found on the [Scintilla
+website](https://scintilla.org/ScintillaDoc.html). Note that with regard to Scintilla-specific
+functionality, this API is a _suggestion_, not a hard requirement. All of that functionality
+also exists in [`buffer`](#buffer), even if undocumented.
+Any view fields set on startup (e.g. in *~/.textadept/init.lua*) will be the default,
+initial values for all views.
### Fields defined by `view`
@@ -10012,8 +9524,7 @@ Display additional carets.
<a id="view.additional_sel_alpha"></a>
#### `view.additional_sel_alpha` (number)
-The alpha value, ranging from `0` (transparent) to `255` (opaque), of
- additional selections.
+The alpha value, ranging from `0` (transparent) to `255` (opaque), of additional selections.
The default value is `view.ALPHA_NOALPHA`, for no alpha.
<a id="view.additional_sel_back"></a>
@@ -10043,8 +9554,7 @@ The annotation visibility mode.
* `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.
+ 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.
@@ -10053,16 +9563,14 @@ The annotation visibility mode.
<a id="view.auto_c_max_height"></a>
#### `view.auto_c_max_height` (number)
-The maximum number of items per page to show in autocompletion and user
- lists. The default value is `5`.
+The maximum number of items per page to show in autocompletion and user lists.
+ The default value is `5`.
<a id="view.auto_c_max_width"></a>
#### `view.auto_c_max_width` (number)
-The maximum number of characters per item to show in autocompletion and
- user lists.
- The default value is `0`, which automatically sizes the width to fit the
- longest item.
+The maximum number of characters per item to show in autocompletion and user lists.
+ The default value is `0`, which automatically sizes the width to fit the longest item.
<a id="view.call_tip_fore_hlt"></a>
#### `view.call_tip_fore_hlt` (number, Write-only)
@@ -10084,8 +9592,8 @@ Display a call tip above the current line instead of below it.
#### `view.call_tip_use_style` (number)
The pixel width of tab characters in call tips.
- When non-zero, also enables the use of style number `view.STYLE_CALLTIP`
- instead of `view.STYLE_DEFAULT` for call tip styles.
+ 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 `0`.
<a id="view.caret_fore"></a>
@@ -10096,23 +9604,20 @@ The caret's foreground color, in "0xBBGGRR" format.
<a id="view.caret_line_back"></a>
#### `view.caret_line_back` (number)
-The background color, in "0xBBGGRR" format, of the line that contains the
- caret.
+The background color, in "0xBBGGRR" format, of the line that contains the caret.
<a id="view.caret_line_back_alpha"></a>
#### `view.caret_line_back_alpha` (number)
-The caret line's background alpha value, ranging from `0` (transparent) to
- `255` (opaque).
+The caret line's background alpha value, ranging from `0` (transparent) to `255` (opaque).
The default value is `view.ALPHA_NOALPHA`, for no alpha.
<a id="view.caret_line_frame"></a>
#### `view.caret_line_frame` (number)
The caret line's frame width in pixels.
- When non-zero, the line that contains the caret is framed instead of
- colored in. The `view.caret_line_back` and `view.caret_line_back_alpha`
- properties apply to the frame.
+ When non-zero, the line that contains the caret is framed instead of colored in. The
+ `view.caret_line_back` and `view.caret_line_back_alpha` properties apply to the frame.
The default value is `0`.
<a id="view.caret_line_visible"></a>
@@ -10125,8 +9630,7 @@ Color the background of the line that contains the caret a different color.
#### `view.caret_line_visible_always` (bool)
Always show the caret line, even when the view is not in focus.
- The default value is `false`, showing the line only when the view is in
- focus.
+ The default value is `false`, showing the line only when the view is in focus.
<a id="view.caret_period"></a>
#### `view.caret_period` (number)
@@ -10147,9 +9651,8 @@ The caret's visual style.
* `view.CARETSTYLE_BLOCK`
A block caret.
- Any block setting may be combined with `view.CARETSTYLE_BLOCK_AFTER` via
- bitwise OR (`|`) in order to draw the caret after the end of a selection,
- as opposed to just inside it.
+ Any block setting may be combined with `view.CARETSTYLE_BLOCK_AFTER` via bitwise OR (`|`)
+ in order to draw the caret after the end of a selection, as opposed to just inside it.
The default value is `view.CARETSTYLE_LINE`.
@@ -10178,8 +9681,8 @@ The display cursor type.
<a id="view.edge_color"></a>
#### `view.edge_color` (number)
-The color, in "0xBBGGRR" format, of the single edge or background for long
- lines according to `view.edge_mode`.
+The color, in "0xBBGGRR" format, of the single edge or background for long lines according
+ to `view.edge_mode`.
<a id="view.edge_column"></a>
#### `view.edge_column` (number)
@@ -10194,11 +9697,11 @@ The long line mark mode.
* `view.EDGE_NONE`
Long lines are not marked.
* `view.EDGE_LINE`
- Draw a single vertical line whose color is [`view.edge_color`](#view.edge_color) at
- column [`view.edge_column`](#view.edge_column).
+ Draw a single vertical line whose color is [`view.edge_color`](#view.edge_color) at column
+ [`view.edge_column`](#view.edge_column).
* `view.EDGE_BACKGROUND`
- Change the background color of text after column [`view.edge_column`](#view.edge_column)
- to [`view.edge_color`](#view.edge_color).
+ Change the background color of text after column [`view.edge_column`](#view.edge_column) to
+ [`view.edge_color`](#view.edge_color).
* `view.EDGE_MULTILINE`
Draw vertical lines whose colors and columns are defined by calls to
[`view:multi_edge_add_line()`](#view.multi_edge_add_line).
@@ -10257,10 +9760,10 @@ The fold display text mode.
<a id="view.fold_expanded"></a>
#### `view.fold_expanded` (table)
-Table of flags per line number that indicate whether or not fold points are
- expanded for those line numbers.
- Setting expanded fold states does not toggle folds; it only updates fold
- margin markers. Use [`view.toggle_fold()`](#view.toggle_fold) instead.
+Table of flags per line number that indicate whether or not fold points are expanded for
+ those line numbers.
+ Setting expanded fold states does not toggle folds; it only updates fold margin markers. Use
+ [`view.toggle_fold()`](#view.toggle_fold) instead.
<a id="view.fold_flags"></a>
#### `view.fold_flags` (number, Read-only)
@@ -10293,8 +9796,8 @@ Display the horizontal scroll bar.
<a id="view.highlight_guide"></a>
#### `view.highlight_guide` (number)
-The indentation guide column number to also highlight when highlighting
- matching braces, or `0` to stop indentation guide highlighting.
+The indentation guide column number to also highlight when highlighting matching braces,
+ or `0` to stop indentation guide highlighting.
<a id="view.idle_styling"></a>
#### `view.idle_styling` (number)
@@ -10305,8 +9808,8 @@ The idle styling mode.
* `view.IDLESTYLING_NONE`
Style all the currently visible text 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.
+ 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`
@@ -10318,60 +9821,57 @@ The idle styling mode.
#### `view.indentation_guides` (number)
The indentation guide drawing mode.
- Indentation guides are dotted vertical lines that appear within indentation
- whitespace at each level of indentation.
+ Indentation guides are dotted vertical lines that appear within indentation whitespace at
+ each level of indentation.
* `view.IV_NONE`
Does 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.
+ 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.
+ 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_NONE`.
<a id="view.indic_alpha"></a>
#### `view.indic_alpha` (table)
-Table of fill color alpha values, ranging from `0` (transparent) to `255`
- (opaque), for indicator numbers from `1` to `32` whose styles are either
- `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
+Table of fill color alpha values, ranging from `0` (transparent) to `255` (opaque),
+ for indicator numbers from `1` to `32` whose styles are either `INDIC_ROUNDBOX`,
+ `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
The default values are `view.ALPHA_NOALPHA`, for no alpha.
<a id="view.indic_fore"></a>
#### `view.indic_fore` (table)
-Table of foreground colors, in "0xBBGGRR" format, for indicator numbers
- from `1` to `32`.
- Changing an indicator's foreground color resets that indicator's hover
- foreground color.
+Table of foreground colors, in "0xBBGGRR" format, for indicator numbers from `1` to `32`.
+ Changing an indicator's foreground color resets that indicator's hover foreground color.
<a id="view.indic_hover_fore"></a>
#### `view.indic_hover_fore` (table)
-Table of hover foreground colors, in "0xBBGGRR" format, for indicator
- numbers from `1` to `32`.
+Table of hover foreground colors, in "0xBBGGRR" format, for indicator numbers from `1` to
+ `32`.
The default values are the respective indicator foreground colors.
<a id="view.indic_hover_style"></a>
#### `view.indic_hover_style` (table)
-Table of hover styles for indicators numbers from `1` to `32`. An
- indicator's hover style drawn when either the cursor hovers over that
- indicator or the caret is within that indicator.
+Table of hover styles for indicators numbers from `1` to `32`.
+ An indicator's hover style drawn when either the cursor hovers over that indicator or the
+ caret is within that indicator.
The default values are the respective indicator styles.
<a id="view.indic_outline_alpha"></a>
#### `view.indic_outline_alpha` (table)
-Table of outline color alpha values, ranging from `0` (transparent) to
- `255` (opaque), for indicator numbers from `1` to `32` whose styles are
- either `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
+Table of outline color alpha values, ranging from `0` (transparent) to `255` (opaque),
+ for indicator numbers from `1` to `32` whose styles are either `INDIC_ROUNDBOX`,
+ `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
The default values are `view.ALPHA_NOALPHA`, for no alpha.
<a id="view.indic_style"></a>
@@ -10394,10 +9894,9 @@ Table of styles for indicator numbers from `1` to `32`.
* `view.INDIC_BOX`
A bounding box.
* `view.INDIC_ROUNDBOX`
- A translucent box with rounded corners around the text. Use
- [`view.indic_alpha`](#view.indic_alpha) and [`view.indic_outline_alpha`](#view.indic_outline_alpha) to set the
- fill and outline transparency, respectively. Their default values are
- `30` and `50`.
+ A translucent box with rounded corners around the text. Use [`view.indic_alpha`](#view.indic_alpha) and
+ [`view.indic_outline_alpha`](#view.indic_outline_alpha) to set the fill and outline transparency, respectively.
+ Their default values are `30` and `50`.
* `view.INDIC_STRAIGHTBOX`
Similar to `INDIC_ROUNDBOX` but with sharp corners.
* `view.INDIC_DASH`
@@ -10408,22 +9907,20 @@ Table of styles for indicator numbers from `1` to `32`.
A squiggly underline 2 pixels in height.
* `view.INDIC_DOTBOX`
Similar to `INDIC_STRAIGHTBOX` but with a dotted outline.
- Translucency alternates between [`view.indic_alpha`](#view.indic_alpha) and
- [`view.indic_outline_alpha`](#view.indic_outline_alpha) starting with the top-left pixel.
+ Translucency alternates between [`view.indic_alpha`](#view.indic_alpha) and [`view.indic_outline_alpha`](#view.indic_outline_alpha)
+ starting with the top-left pixel.
* `view.INDIC_SQUIGGLEPIXMAP`
- Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead
- of multiple line segments.
+ Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead of multiple
+ line segments.
* `view.INDIC_COMPOSITIONTHICK`
- A 2-pixel thick underline at the bottom of the line inset by 1 pixel on
- on either side. Similar in appearance to the target in Asian language
- input composition.
+ A 2-pixel thick underline at the bottom of the line inset by 1 pixel on on either
+ side. Similar in appearance to the target in Asian language input composition.
* `view.INDIC_COMPOSITIONTHIN`
- A 1-pixel thick underline just before the bottom of the line inset by 1
- pixel on either side. Similar in appearance to the non-target ranges in
- Asian language input composition.
+ A 1-pixel thick underline just before the bottom of the line inset by 1 pixel on either
+ side. Similar in appearance to the non-target ranges in Asian language input composition.
* `view.INDIC_FULLBOX`
- Similar to `INDIC_STRAIGHTBOX` but extends to the top of its line,
- potentially touching any similar indicators on the line above.
+ Similar to `INDIC_STRAIGHTBOX` but extends to the top of its line, potentially touching
+ any similar indicators on the line above.
* `view.INDIC_TEXTFORE`
Changes the color of text to an indicator's foreground color.
* `view.INDIC_POINT`
@@ -10432,11 +9929,10 @@ Table of styles for indicator numbers from `1` to `32`.
A triangle below the center of the first character of the indicator
range.
* `view.INDIC_GRADIENT`
- A box with a vertical gradient from solid on top to transparent on
- bottom.
+ A box with a vertical gradient from solid on top to transparent on bottom.
* `view.INDIC_GRADIENTCENTER`
- A box with a centered gradient from solid in the middle to transparent on
- the top and bottom.
+ A box with a centered gradient from solid in the middle to transparent on the top
+ and bottom.
Use [`_SCINTILLA.next_indic_number()`](#_SCINTILLA.next_indic_number) for custom indicators.
Changing an indicator's style resets that indicator's hover style.
@@ -10444,15 +9940,15 @@ Table of styles for indicator numbers from `1` to `32`.
<a id="view.indic_under"></a>
#### `view.indic_under` (table)
-Table of flags that indicate whether or not to draw indicators behind text
- instead of over the top of it for indicator numbers from `1` to `32`.
+Table of flags that indicate whether or not to draw indicators behind text instead of over
+ the top of it for indicator numbers from `1` to `32`.
The default values are `false`.
<a id="view.line_visible"></a>
#### `view.line_visible` (table, Read-only)
-Table of flags per line number that indicate whether or not lines are
- visible for those line numbers.
+Table of flags per line number that indicate whether or not lines are visible for those
+ line numbers.
<a id="view.lines_on_screen"></a>
#### `view.lines_on_screen` (number, Read-only)
@@ -10463,15 +9959,14 @@ The number of completely visible lines in the view.
<a id="view.margin_back_n"></a>
#### `view.margin_back_n` (table)
-Table of background colors, in "0xBBGGRR" format, of margin numbers from
- `1` to `view.margins` (`5` by default).
+Table of background colors, in "0xBBGGRR" format, of margin numbers from `1` to `view.margins`
+ (`5` by default).
Only affects margins of type `view.MARGIN_COLOR`.
<a id="view.margin_cursor_n"></a>
#### `view.margin_cursor_n` (table)
-Table of cursor types shown over margin numbers from `1` to
- `view.margins` (`5` by default).
+Table of cursor types shown over margin numbers from `1` to `view.margins` (`5` by default).
* `view.CURSORARROW`
Normal arrow cursor.
@@ -10489,12 +9984,11 @@ The pixel size of the left margin of the buffer text.
<a id="view.margin_mask_n"></a>
#### `view.margin_mask_n` (table)
-Table of bit-masks of markers whose symbols marker symbol margins can
- display for margin numbers from `1` to `view.margins` (`5` by default).
- Bit-masks are 32-bit values whose bits correspond to the 32 available
- markers.
- The default values are `0`, `view.MASK_FOLDERS`, `0`, `0`, and `0`, for
- a line margin and logical marker margin.
+Table of bit-masks of markers whose symbols marker symbol margins can display for margin
+ numbers from `1` to `view.margins` (`5` by default).
+ Bit-masks are 32-bit values whose bits correspond to the 32 available markers.
+ The default values are `0`, `view.MASK_FOLDERS`, `0`, `0`, and `0`, for a line margin and
+ logical marker margin.
<a id="view.margin_options"></a>
#### `view.margin_options` (number)
@@ -10504,8 +9998,8 @@ A 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
- the line number margin is clicked.
+ Select only a wrapped line's sub-line (rather than the entire line) when the line number
+ margin is clicked.
The default value is `view.MARGINOPTION_NONE`.
@@ -10518,27 +10012,23 @@ The pixel size of the right margin of the buffer text.
<a id="view.margin_sensitive_n"></a>
#### `view.margin_sensitive_n` (table)
-Table of flags that indicate whether or not mouse clicks in margins emit
- `MARGIN_CLICK` events for margin numbers from `1` to `view.margins` (`5`
- by default).
+Table of flags that indicate whether or not mouse clicks in margins emit `MARGIN_CLICK`
+ events for margin numbers from `1` to `view.margins` (`5` by default).
The default values are `false`.
<a id="view.margin_type_n"></a>
#### `view.margin_type_n` (table)
-Table of margin types for margin numbers from `1` to `view.margins` (`5`
- by default).
+Table of margin types for margin numbers from `1` to `view.margins` (`5` by default).
* `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.
+ 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.
+ A marker symbol margin whose background color matches the default text foreground color.
* `view.MARGIN_TEXT`
A text margin.
* `view.MARGIN_RTEXT`
@@ -10546,14 +10036,13 @@ Table of margin types for margin numbers from `1` to `view.margins` (`5`
* `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.
+ The default value for the first margin is `view.MARGIN_NUMBER`, followed by
+ `view.MARGIN_SYMBOL` for the rest.
<a id="view.margin_width_n"></a>
#### `view.margin_width_n` (table)
-Table of pixel margin widths for margin numbers from `1` to
- `view.margins` (`5` by default).
+Table of pixel margin widths for margin numbers from `1` to `view.margins` (`5` by default).
<a id="view.margins"></a>
#### `view.margins` (number)
@@ -10564,41 +10053,37 @@ The number of margins.
<a id="view.marker_alpha"></a>
#### `view.marker_alpha` (table, Write-only)
-Table of alpha values, ranging from `0` (transparent) to `255` (opaque),
- of markers drawn in the text area (not the margin) for markers numbers from
- `1` to `32`.
+Table of alpha values, ranging from `0` (transparent) to `255` (opaque), of markers drawn
+ in the text area (not the margin) for markers numbers from `1` to `32`.
The default values are `view.ALPHA_NOALPHA`, for no alpha.
<a id="view.marker_back"></a>
#### `view.marker_back` (table, Write-only)
-Table of background colors, in "0xBBGGRR" format, of marker numbers from
- `1` to `32`.
+Table of background colors, in "0xBBGGRR" format, of marker numbers from `1` to `32`.
<a id="view.marker_back_selected"></a>
#### `view.marker_back_selected` (table, Write-only)
-Table of background colors, in "0xBBGGRR" format, of markers whose folding
- blocks are selected for marker numbers from `1` to `32`.
+Table of background colors, in "0xBBGGRR" format, of markers whose folding blocks are
+ selected for marker numbers from `1` to `32`.
<a id="view.marker_fore"></a>
#### `view.marker_fore` (table, Write-only)
-Table of foreground colors, in "0xBBGGRR" format, of marker numbers from
- `1` to `32`.
+Table of foreground colors, in "0xBBGGRR" format, of marker numbers from `1` to `32`.
<a id="view.mouse_dwell_time"></a>
#### `view.mouse_dwell_time` (number)
-The number of milliseconds the mouse must idle before generating a
- `DWELL_START` event. A time of `view.TIME_FOREVER` will never generate
- one.
+The number of milliseconds the mouse must idle before generating a `DWELL_START` event. A
+ time of `view.TIME_FOREVER` will never generate one.
<a id="view.mouse_selection_rectangular_switch"></a>
#### `view.mouse_selection_rectangular_switch` (bool)
-Whether or not pressing [`view.rectangular_selection_modifier`](#view.rectangular_selection_modifier) when
- selecting text normally with the mouse turns on rectangular selection.
+Whether or not pressing [`view.rectangular_selection_modifier`](#view.rectangular_selection_modifier) when selecting text
+ normally with the mouse turns on rectangular selection.
The default value is `false`.
<a id="view.multi_edge_column"></a>
@@ -10615,20 +10100,19 @@ Map of key-value string pairs used by lexers.
<a id="view.property_expanded"></a>
#### `view.property_expanded` (table, Read-only)
-Map of key-value string pairs used by lexers with `$()` and `%()` variable
- replacement performed in values.
+Map of key-value string pairs used by lexers with `$()` and `%()` variable replacement
+ performed in values.
<a id="view.property_int"></a>
#### `view.property_int` (table, Read-only)
-Map of key-value pairs used by lexers with values interpreted as numbers,
- or `0` if not found.
+Map of key-value pairs used by lexers with values interpreted as numbers, or `0` if not found.
<a id="view.rectangular_selection_modifier"></a>
#### `view.rectangular_selection_modifier` (number)
-The modifier key used in combination with a mouse drag in order to create a
- rectangular selection.
+The modifier key used in combination with a mouse drag in order to create a rectangular
+ selection.
* `view.MOD_CTRL`
The "Control" modifier key.
@@ -10644,57 +10128,52 @@ The modifier key used in combination with a mouse drag in order to create a
#### `view.representation` (table)
The alternative string representations of characters.
- Representations are displayed in the same way control characters are. Use
- the empty string for the '\0' character when assigning its representation.
- Characters are strings, not numeric codes, and can be multi-byte
- characters.
+ Representations are displayed in the same way control characters are. Use the empty
+ string for the '\0' character when assigning its representation. Characters are strings,
+ not numeric codes, and can be multi-byte characters.
Call [`view.clear_representation()`](#view.clear_representation) to remove a representation.
<a id="view.rgba_image_height"></a>
#### `view.rgba_image_height` (number)
-The height of the RGBA image to be defined using
- [`view.marker_define_rgba_image()`](#view.marker_define_rgba_image).
+The height of the RGBA image to be defined using [`view.marker_define_rgba_image()`](#view.marker_define_rgba_image).
<a id="view.rgba_image_scale"></a>
#### `view.rgba_image_scale` (number)
The scale factor in percent of the RGBA image to be defined using
[`view.marker_define_rgba_image()`](#view.marker_define_rgba_image).
- This is useful on macOS with a retina display where each display unit is 2
- pixels: use a factor of `200` so that each image pixel is displayed using a
- screen pixel. The default scale, `100`, will stretch each image pixel to
- cover 4 screen pixels on a retina display.
+ 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.
<a id="view.rgba_image_width"></a>
#### `view.rgba_image_width` (number)
-The width of the RGBA image to be defined using
- [`view.marker_define_rgba_image()`](#view.marker_define_rgba_image) and
+The width of the RGBA image to be defined using [`view.marker_define_rgba_image()`](#view.marker_define_rgba_image) and
[`view.register_rgba_image()`](#view.register_rgba_image).
<a id="view.scroll_width"></a>
#### `view.scroll_width` (number)
The horizontal scrolling pixel width.
- For performance, the view does not measure the display width of the buffer
- to determine the properties of the horizontal scroll bar, but uses an
- assumed width instead. To ensure the width of the currently visible lines
- can be scrolled use [`view.scroll_width_tracking`](#view.scroll_width_tracking).
+ For performance, the view does not measure the display width of the buffer to determine
+ the properties of the horizontal scroll bar, but uses an assumed width instead. To ensure
+ the width of the currently visible lines can be scrolled use [`view.scroll_width_tracking`](#view.scroll_width_tracking).
The default value is `2000`.
<a id="view.scroll_width_tracking"></a>
#### `view.scroll_width_tracking` (bool)
-Continuously update the horizontal scrolling width to match the maximum
- width of a displayed line beyond [`view.scroll_width`](#view.scroll_width).
+Continuously update the horizontal scrolling width to match the maximum width of a displayed
+ line beyond [`view.scroll_width`](#view.scroll_width).
The default value is `false`.
<a id="view.sel_alpha"></a>
#### `view.sel_alpha` (number)
-The selection's alpha value, ranging from `0` (transparent) to `255`
- (opaque).
+The selection's alpha value, ranging from `0` (transparent) to `255` (opaque).
The default value is `view.ALPHA_NOALPHA`, for no alpha.
<a id="view.sel_eol_filled"></a>
@@ -10711,14 +10190,12 @@ The split resizer's pixel position if the view is a split one.
<a id="view.style_back"></a>
#### `view.style_back` (table)
-Table of background colors, in "0xBBGGRR" format, of text for style numbers
- from `1` to `256`.
+Table of background colors, in "0xBBGGRR" format, of text for style numbers from `1` to `256`.
<a id="view.style_bold"></a>
#### `view.style_bold` (table)
-Table of flags that indicate whether or not text is bold for style numbers
- from `1` to `256`.
+Table of flags that indicate whether or not text is bold for style numbers from `1` to `256`.
The default values are `false`.
<a id="view.style_case"></a>
@@ -10740,17 +10217,17 @@ Table of letter case modes of text for style numbers from `1` to `256`.
<a id="view.style_changeable"></a>
#### `view.style_changeable` (table)
-Table of flags that indicate whether or not text is changeable for style
- numbers from `1` to `256`.
+Table of flags that indicate whether or not text is changeable for style numbers from `1`
+ to `256`.
The default values are `true`.
Read-only styles do not allow the caret into the range of text.
<a id="view.style_eol_filled"></a>
#### `view.style_eol_filled` (table)
-Table of flags that indicate whether or not the background colors of styles
- whose characters occur last on lines extend all the way to the view's right
- margin for style numbers from `1` to `256`.
+Table of flags that indicate whether or not the background colors of styles whose characters
+ occur last on lines extend all the way to the view's right margin for style numbers from
+ `1` to `256`.
The default values are `false`.
<a id="view.style_font"></a>
@@ -10761,14 +10238,13 @@ Table of string font names of text for style numbers from `1` to `256`.
<a id="view.style_fore"></a>
#### `view.style_fore` (table)
-Table of foreground colors, in "0xBBGGRR" format, of text for style numbers
- from `1` to `256`.
+Table of foreground colors, in "0xBBGGRR" format, of text for style numbers from `1` to `256`.
<a id="view.style_italic"></a>
#### `view.style_italic` (table)
-Table of flags that indicate whether or not text is italic for style
- numbers from `1` to `256`.
+Table of flags that indicate whether or not text is italic for style numbers from `1` to
+ `256`.
The default values are `false`.
<a id="view.style_size"></a>
@@ -10779,15 +10255,15 @@ Table of font sizes of text for style numbers from `1` to `256`.
<a id="view.style_underline"></a>
#### `view.style_underline` (table)
-Table of flags that indicate whether or not text is underlined for style
- numbers from `1` to `256`.
+Table of flags that indicate whether or not text is underlined for style numbers from `1`
+ to `256`.
The default values are `false`.
<a id="view.style_visible"></a>
#### `view.style_visible` (table)
-Table of flags that indicate whether or not text is visible for style
- numbers from `1` to `256`.
+Table of flags that indicate whether or not text is visible for style numbers from `1` to
+ `256`.
The default values are `true`.
<a id="view.tab_draw_mode"></a>
@@ -10833,8 +10309,7 @@ The whitespace visibility mode.
<a id="view.whitespace_size"></a>
#### `view.whitespace_size` (number)
-The pixel size of the dots that represent space characters when whitespace
- is visible.
+The pixel size of the dots that represent space characters when whitespace is visible.
The default value is `1`.
<a id="view.wrap_indent_mode"></a>
@@ -10910,8 +10385,8 @@ The wrapped line visual flag location.
#### `view.x_offset` (number)
The horizontal scroll pixel position.
- A value of `0` is the normal position with the first text column visible at
- the left of the view.
+ A value of `0` is the normal position with the first text column visible at the left of
+ the view.
<a id="view.zoom"></a>
#### `view.zoom` (number)
@@ -10926,22 +10401,20 @@ The number of points to add to the size of all fonts.
<a id="view.brace_bad_light"></a>
#### `view.brace_bad_light`(*view, pos*)
-Highlights the character at position *pos* as an unmatched brace character
-using the `'style.bracebad'` style.
+Highlights the character at position *pos* as an unmatched brace character using the
+`'style.bracebad'` style.
Removes highlighting when *pos* is `-1`.
Parameters:
* *`view`*: A view.
-* *`pos`*: The position in *view*'s buffer to highlight, or `-1` to remove
- the highlight.
+* *`pos`*: The position in *view*'s buffer to highlight, or `-1` to remove the highlight.
<a id="view.brace_bad_light_indicator"></a>
#### `view.brace_bad_light_indicator`(*view, use\_indicator, indicator*)
-Highlights unmatched brace characters with indicator number *indicator*, in
-the range of `1` to `32`, instead of the
-`view.STYLE_BRACEBAD` style if *use_indicator* is `true`.
+Highlights unmatched brace characters with indicator number *indicator*, in the range of
+`1` to `32`, instead of the `view.STYLE_BRACEBAD` style if *use_indicator* is `true`.
Parameters:
@@ -10952,10 +10425,10 @@ Parameters:
<a id="view.brace_highlight"></a>
#### `view.brace_highlight`(*view, pos1, pos2*)
-Highlights the characters at positions *pos1* and *pos2* as matching braces
-using the `'style.bracelight'` style.
-If indent guides are enabled, locates the column with `buffer.column` and
-sets `view.highlight_guide` in order to highlight the indent guide.
+Highlights the characters at positions *pos1* and *pos2* as matching braces using the
+`'style.bracelight'` style.
+If indent guides are enabled, locates the column with `buffer.column` and sets
+`view.highlight_guide` in order to highlight the indent guide.
Parameters:
@@ -10966,9 +10439,8 @@ Parameters:
<a id="view.brace_highlight_indicator"></a>
#### `view.brace_highlight_indicator`(*view, use\_indicator, indicator*)
-Highlights matching brace characters with indicator number *indicator*, in
-the range of `1` to `32`, instead of the
-`view.STYLE_BRACELIGHT` style if *use_indicator* is `true`.
+Highlights matching brace characters with indicator number *indicator*, in the range of `1`
+to `32`, instead of the `view.STYLE_BRACELIGHT` style if *use_indicator* is `true`.
Parameters:
@@ -11014,8 +10486,8 @@ Return:
<a id="view.call_tip_set_hlt"></a>
#### `view.call_tip_set_hlt`(*view, start\_pos, end\_pos*)
-Highlights a call tip's text between positions *start_pos* to *end_pos* with
-the color `view.call_tip_fore_hlt`.
+Highlights a call tip's text between positions *start_pos* to *end_pos* with the color
+`view.call_tip_fore_hlt`.
Parameters:
@@ -11026,11 +10498,10 @@ Parameters:
<a id="view.call_tip_show"></a>
#### `view.call_tip_show`(*view, pos, text*)
-Displays a call tip at position *pos* with string *text* as the call tip's
-contents.
-Any "\001" or "\002" bytes in *text* are replaced by clickable up or down
-arrow visuals, respectively. These may be used to indicate that a symbol has
-more than one call tip, for example.
+Displays a call tip at position *pos* with string *text* as the call tip's contents.
+Any "\001" or "\002" bytes in *text* are replaced by clickable up or down arrow visuals,
+respectively. These may be used to indicate that a symbol has more than one call tip,
+for example.
Parameters:
@@ -11041,8 +10512,7 @@ Parameters:
<a id="view.clear_registered_images"></a>
#### `view.clear_registered_images`(*view*)
-Clears all images registered using `view.register_image()` and
-`view.register_rgba_image()`.
+Clears all images registered using `view.register_image()` and `view.register_rgba_image()`.
Parameters:
@@ -11051,20 +10521,20 @@ Parameters:
<a id="view.clear_representation"></a>
#### `view.clear_representation`(*view, char*)
-Removes the alternate string representation for character *char* (which may
- be a multi-byte character).
+Removes the alternate string representation for character *char* (which may be a multi-byte
+ character).
Parameters:
* *`view`*: A view.
-* *`char`*: The string character in `buffer.representations` to remove the
- alternate string representation for.
+* *`char`*: The string character in `buffer.representations` to remove the alternate string
+ representation for.
<a id="view.contracted_fold_next"></a>
#### `view.contracted_fold_next`(*view, line*)
-Returns the line number of the next contracted fold point starting from line
-number *line*, or `-1` if none exists.
+Returns the line number of the next contracted fold point starting from line number *line*,
+or `-1` if none exists.
Parameters:
@@ -11078,11 +10548,10 @@ Return:
<a id="view.doc_line_from_visible"></a>
#### `view.doc_line_from_visible`(*view, display\_line*)
-Returns the actual line number of displayed line number *display_line*,
-taking wrapped, annotated, and hidden lines into account.
-If *display_line* is less than or equal to `1`, returns `1`. If
-*display_line* is greater than the number of displayed lines, returns
-`buffer.line_count`.
+Returns the actual line number of displayed line number *display_line*, taking wrapped,
+annotated, and hidden lines into account.
+If *display_line* is less than or equal to `1`, returns `1`. If *display_line* is greater
+than the number of displayed lines, returns `buffer.line_count`.
Parameters:
@@ -11106,9 +10575,8 @@ Parameters:
<a id="view.ensure_visible_enforce_policy"></a>
#### `view.ensure_visible_enforce_policy`(*view, line*)
-Ensures line number *line* is visible by expanding any fold points hiding it
-based on the vertical caret policy previously defined in
-`view.set_visible_policy()`.
+Ensures line number *line* is visible by expanding any fold points hiding it based on the
+vertical caret policy previously defined in `view.set_visible_policy()`.
Parameters:
@@ -11119,8 +10587,7 @@ Parameters:
#### `view.fold_all`(*view, action*)
Contracts, expands, or toggles all fold points, depending on *action*.
-When toggling, the state of the first fold point determines whether to
-expand or contract.
+When toggling, the state of the first fold point determines whether to expand or contract.
Parameters:
@@ -11133,8 +10600,8 @@ Parameters:
<a id="view.fold_children"></a>
#### `view.fold_children`(*view, line, action*)
-Contracts, expands, or toggles the fold point on line number *line*, as well
-as all of its children, depending on *action*.
+Contracts, expands, or toggles the fold point on line number *line*, as well as all of its
+children, depending on *action*.
Parameters:
@@ -11148,8 +10615,7 @@ Parameters:
<a id="view.fold_line"></a>
#### `view.fold_line`(*view, line, action*)
-Contracts, expands, or toggles the fold point on line number *line*,
-depending on *action*.
+Contracts, expands, or toggles the fold point on line number *line*, depending on *action*.
Parameters:
@@ -11172,8 +10638,8 @@ Parameters:
<a id="view.goto_buffer"></a>
#### `view.goto_buffer`(*view, buffer*)
-Switches to buffer *buffer* or the buffer *buffer* number of buffers relative
-to the current one.
+Switches to buffer *buffer* or the buffer *buffer* number of buffers relative to the
+current one.
Emits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events.
Parameters:
@@ -11191,8 +10657,7 @@ See also:
#### `view.hide_lines`(*view, start\_line, end\_line*)
Hides the range of lines between line numbers *start_line* to *end_line*.
-This has no effect on fold levels or fold flags and the first line cannot be
-hidden.
+This has no effect on fold levels or fold flags and the first line cannot be hidden.
Parameters:
@@ -11233,16 +10698,13 @@ Parameters:
<a id="view.marker_define"></a>
#### `view.marker_define`(*view, marker, symbol*)
-Assigns marker symbol *symbol* to marker number *marker*, in the range of `1`
-to `32`.
-*symbol* is shown in marker symbol margins next to lines marked with
-*marker*.
+Assigns marker symbol *symbol* to marker number *marker*, in the range of `1` to `32`.
+*symbol* is shown in marker symbol margins next to lines marked with *marker*.
Parameters:
* *`view`*: A view.
-* *`marker`*: The marker number in the range of `1` to `32` to set *symbol*
- for.
+* *`marker`*: The marker number in the range of `1` to `32` to set *symbol* for.
* *`symbol`*: The marker symbol: `buffer.MARK_*`.
See also:
@@ -11252,49 +10714,41 @@ See also:
<a id="view.marker_define_pixmap"></a>
#### `view.marker_define_pixmap`(*view, marker, pixmap*)
-Associates marker number *marker*, in the range of `1` to `32`, with XPM
-image *pixmap*.
-The `view.MARK_PIXMAP` marker symbol must be assigned to *marker*.
-*pixmap* is shown in marker symbol margins next to lines marked with
-*marker*.
+Associates marker number *marker*, in the range of `1` to `32`, with XPM image *pixmap*.
+The `view.MARK_PIXMAP` marker symbol must be assigned to *marker*. *pixmap* is shown in
+marker symbol margins next to lines marked with *marker*.
Parameters:
* *`view`*: A view.
-* *`marker`*: The marker number in the range of `1` to `32` to define
- pixmap *pixmap* for.
+* *`marker`*: The marker number in the range of `1` to `32` to define pixmap *pixmap* for.
* *`pixmap`*: The string pixmap data.
<a id="view.marker_define_rgba_image"></a>
#### `view.marker_define_rgba_image`(*view, marker, pixels*)
-Associates marker number *marker*, in the range of `1` to `32`, with RGBA
-image *pixels*.
-The dimensions for *pixels* (`view.rgba_image_width` and
-`view.rgba_image_height`) must have already been defined. *pixels* is a
-sequence of 4 byte pixel values (red, blue, green, and alpha) defining the
-image line by line starting at the top-left pixel.
-The `view.MARK_RGBAIMAGE` marker symbol must be assigned to *marker*.
-*pixels* is shown in symbol margins next to lines marked with *marker*.
+Associates marker number *marker*, in the range of `1` to `32`, with RGBA image *pixels*.
+The dimensions for *pixels* (`view.rgba_image_width` and `view.rgba_image_height`) must
+have already been defined. *pixels* is a sequence of 4 byte pixel values (red, blue, green,
+and alpha) defining the image line by line starting at the top-left pixel.
+The `view.MARK_RGBAIMAGE` marker symbol must be assigned to *marker*. *pixels* is shown in
+symbol margins next to lines marked with *marker*.
Parameters:
* *`view`*: A view.
-* *`marker`*: The marker number in the range of `1` to `32` to define RGBA
- data *pixels* for.
-* *`pixels`*: The string sequence of 4 byte pixel values starting with the
- pixels for the top line, with the leftmost pixel first, then continuing
- with the pixels for subsequent lines. There is no gap between lines for
- alignment reasons. Each pixel consists of, in order, a red byte, a green
- byte, a blue byte and an alpha byte. The color bytes are not premultiplied
- by the alpha value. That is, a fully red pixel that is 25% opaque will be
+* *`marker`*: The marker number in the range of `1` to `32` to define RGBA data *pixels* for.
+* *`pixels`*: The string sequence of 4 byte pixel values starting with the pixels for the
+ top line, with the leftmost pixel first, then continuing with the pixels for subsequent
+ lines. There is no gap between lines for alignment reasons. Each pixel consists of, in
+ order, a red byte, a green byte, a blue byte and an alpha byte. The color bytes are not
+ premultiplied by the alpha value. That is, a fully red pixel that is 25% opaque will be
`[FF, 00, 00, 3F]`.
<a id="view.marker_enable_highlight"></a>
#### `view.marker_enable_highlight`(*view, enabled*)
-Highlights the margin fold markers for the current fold block if *enabled* is
-`true`.
+Highlights the margin fold markers for the current fold block if *enabled* is `true`.
Parameters:
@@ -11304,15 +10758,14 @@ Parameters:
<a id="view.marker_symbol_defined"></a>
#### `view.marker_symbol_defined`(*view, marker*)
-Returns the symbol assigned to marker number *marker*, in the range of `1` to
-`32`, used in `view.marker_define()`,
+Returns the symbol assigned to marker number *marker*, in the range of `1` to `32`, used in
+`view.marker_define()`,
`view.marker_define_pixmap()`, or `view.marker_define_rgba_image()`.
Parameters:
* *`view`*: A view.
-* *`marker`*: The marker number in the range of `1` to `32` to get the symbol
- of.
+* *`marker`*: The marker number in the range of `1` to `32` to get the symbol of.
Return:
@@ -11321,8 +10774,7 @@ Return:
<a id="view.multi_edge_add_line"></a>
#### `view.multi_edge_add_line`(*view, column, color*)
-Adds a new vertical line at column number *column* with color *color*, in
-"0xBBGGRR" format.
+Adds a new vertical line at column number *column* with color *color*, in "0xBBGGRR" format.
Parameters:
@@ -11342,8 +10794,7 @@ Parameters:
<a id="view.register_image"></a>
#### `view.register_image`(*view, type, xpm\_data*)
-Registers XPM image *xpm_data* to type number *type* for use in
-autocompletion and user lists.
+Registers XPM image *xpm_data* to type number *type* for use in autocompletion and user lists.
Parameters:
@@ -11354,19 +10805,16 @@ Parameters:
<a id="view.register_rgba_image"></a>
#### `view.register_rgba_image`(*view, type, pixels*)
-Registers RGBA image *pixels* to type number *type* for use in autocompletion
-and user lists.
-The dimensions for *pixels* (`view.rgba_image_width` and
-`view.rgba_image_height`) must have already been defined. *pixels* is a
-sequence of 4 byte pixel values (red, blue, green, and alpha) defining the
-image line by line starting at the top-left pixel.
+Registers RGBA image *pixels* to type number *type* for use in autocompletion and user lists.
+The dimensions for *pixels* (`view.rgba_image_width` and `view.rgba_image_height`) must
+have already been defined. *pixels* is a sequence of 4 byte pixel values (red, blue, green,
+and alpha) defining the image line by line starting at the top-left pixel.
Parameters:
* *`view`*: A view.
* *`type`*: Integer type to register the image with.
-* *`pixels`*: The RGBA data as described in
- `view.marker_define_rgba_image()`.
+* *`pixels`*: The RGBA data as described in `view.marker_define_rgba_image()`.
<a id="view.scroll_caret"></a>
#### `view.scroll_caret`(*view*)
@@ -11386,10 +10834,9 @@ See also:
<a id="view.scroll_range"></a>
#### `view.scroll_range`(*view, secondary\_pos, primary\_pos*)
-Scrolls into view the range of text between positions *primary_pos* and
-*secondary_pos*, with priority given to *primary_pos*.
-Similar to `view.scroll_caret()`, but with *primary_pos* instead of
-`buffer.current_pos`.
+Scrolls into view the range of text between positions *primary_pos* and *secondary_pos*,
+with priority given to *primary_pos*.
+Similar to `view.scroll_caret()`, but with *primary_pos* instead of `buffer.current_pos`.
This is useful for scrolling search results into view.
Parameters:
@@ -11433,9 +10880,8 @@ See also:
<a id="view.set_fold_margin_color"></a>
#### `view.set_fold_margin_color`(*view, use\_setting, color*)
-Overrides the fold margin's default color with color *color*, in "0xBBGGRR"
-format,
-if *use_setting* is `true`.
+Overrides the fold margin's default color with color *color*, in "0xBBGGRR" format, if
+*use_setting* is `true`.
Parameters:
@@ -11446,8 +10892,8 @@ Parameters:
<a id="view.set_fold_margin_hi_color"></a>
#### `view.set_fold_margin_hi_color`(*view, use\_setting, color*)
-Overrides the fold margin's default highlight color with color *color*, in
-"0xBBGGRR" format, if *use_setting* is `true`.
+Overrides the fold margin's default highlight color with color *color*, in "0xBBGGRR" format,
+if *use_setting* is `true`.
Parameters:
@@ -11458,8 +10904,8 @@ Parameters:
<a id="view.set_sel_back"></a>
#### `view.set_sel_back`(*view, use\_setting, color*)
-Overrides the selection's default background color with color *color*, in
-"0xBBGGRR" format, if *use_setting* is `true`.
+Overrides the selection's default background color with color *color*, in "0xBBGGRR" format,
+if *use_setting* is `true`.
Overwrites any existing `view.additional_sel_back` color.
Parameters:
@@ -11471,8 +10917,8 @@ Parameters:
<a id="view.set_sel_fore"></a>
#### `view.set_sel_fore`(*view, use\_setting, color*)
-Overrides the selection's default foreground color with color *color*, in
-"0xBBGGRR" format, if *use_setting* is `true`.
+Overrides the selection's default foreground color with color *color*, in "0xBBGGRR" format,
+if *use_setting* is `true`.
Overwrites any existing `view.additional_sel_fore` color.
Parameters:
@@ -11484,18 +10930,17 @@ Parameters:
<a id="view.set_theme"></a>
#### `view.set_theme`(*view, name, env*)
-Sets the view's color theme to be string *name*, with the contents of table
-*env* available as global variables.
-User themes override Textadept's default themes when they have the same name.
-If *name* contains slashes, it is assumed to be an absolute path to a theme
-instead of a theme name.
+Sets the view's color theme to be string *name*, with the contents of table *env* available
+as global variables.
+User themes override Textadept's default themes when they have the same name. If *name*
+contains slashes, it is assumed to be an absolute path to a theme instead of a theme name.
Parameters:
* *`view`*: A view.
* *`name`*: The name or absolute path of a theme to set.
-* *`env`*: Optional table of global variables themes can utilize to override
- default settings such as font and size.
+* *`env`*: Optional table of global variables themes can utilize to override default settings
+ such as font and size.
Usage:
@@ -11509,23 +10954,23 @@ See also:
<a id="view.set_visible_policy"></a>
#### `view.set_visible_policy`(*view, policy, y*)
-Defines scrolling policy bit-mask *policy* as the policy for keeping the
-caret *y* number of lines away from the vertical margins as
-`view.ensure_visible_enforce_policy()` redisplays hidden or folded lines.
+Defines scrolling policy bit-mask *policy* as the policy for keeping the caret *y* number
+of lines away from the vertical margins as `view.ensure_visible_enforce_policy()` redisplays
+hidden or folded lines.
It is similar in operation to `view.set_y_caret_policy()`.
Parameters:
* *`view`*: A view.
-* *`policy`*: The combination of `view.VISIBLE_SLOP` and
- `view.VISIBLE_STRICT` policy flags to set.
+* *`policy`*: The combination of `view.VISIBLE_SLOP` and `view.VISIBLE_STRICT` policy flags
+ to set.
* *`y`*: The number of lines from the vertical margins to keep the caret.
<a id="view.set_whitespace_back"></a>
#### `view.set_whitespace_back`(*view, use\_setting, color*)
-Overrides the background color of whitespace with color *color*, in
-"0xBBGGRR" format, if *use_setting* is `true`.
+Overrides the background color of whitespace with color *color*, in "0xBBGGRR" format,
+if *use_setting* is `true`.
Parameters:
@@ -11536,8 +10981,8 @@ Parameters:
<a id="view.set_whitespace_fore"></a>
#### `view.set_whitespace_fore`(*view, use\_setting, color*)
-Overrides the foreground color of whitespace with color *color*, in
-"0xBBGGRR" format, if *use_setting* is `true`.
+Overrides the foreground color of whitespace with color *color*, in "0xBBGGRR" format,
+if *use_setting* is `true`.
Parameters:
@@ -11548,35 +10993,34 @@ Parameters:
<a id="view.set_x_caret_policy"></a>
#### `view.set_x_caret_policy`(*view, policy, x*)
-Defines scrolling policy bit-mask *policy* as the policy for keeping the
-caret *x* number of pixels away from the horizontal margins.
+Defines scrolling policy bit-mask *policy* as the policy for keeping the caret *x* number
+of pixels away from the horizontal margins.
Parameters:
* *`view`*: A view.
-* *`policy`*: The combination of `view.CARET_SLOP`, `view.CARET_STRICT`,
- `view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set.
+* *`policy`*: The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, `view.CARET_EVEN`,
+ and `view.CARET_JUMPS` policy flags to set.
* *`x`*: The number of pixels from the horizontal margins to keep the caret.
<a id="view.set_y_caret_policy"></a>
#### `view.set_y_caret_policy`(*view, policy, y*)
-Defines scrolling policy bit-mask *policy* as the policy for keeping the
-caret *y* number of lines away from the vertical margins.
+Defines scrolling policy bit-mask *policy* as the policy for keeping the caret *y* number
+of lines away from the vertical margins.
Parameters:
* *`view`*: A view.
-* *`policy`*: The combination of `view.CARET_SLOP`, `view.CARET_STRICT`,
- `view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set.
+* *`policy`*: The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, `view.CARET_EVEN`,
+ and `view.CARET_JUMPS` policy flags to set.
* *`y`*: The number of lines from the vertical margins to keep the caret.
<a id="view.show_lines"></a>
#### `view.show_lines`(*view, start\_line, end\_line*)
Shows the range of lines between line numbers *start_line* to *end_line*.
-This has no effect on fold levels or fold flags and the first line cannot be
-hidden.
+This has no effect on fold levels or fold flags and the first line cannot be hidden.
Parameters:
@@ -11587,17 +11031,16 @@ Parameters:
<a id="view.split"></a>
#### `view.split`(*view, vertical*)
-Splits the view into top and bottom views (unless *vertical* is `true`),
-focuses the new view, and returns both the old and new views.
-If *vertical* is `false`, splits the view vertically into left and
-right views.
+Splits the view into top and bottom views (unless *vertical* is `true`), focuses the new view,
+and returns both the old and new views.
+If *vertical* is `false`, splits the view vertically into left and right views.
Emits a `VIEW_NEW` event.
Parameters:
* *`view`*: The view to split.
-* *`vertical`*: Optional flag indicating whether or not to split the view
- vertically. The default value is `false`, for horizontal.
+* *`vertical`*: Optional flag indicating whether or not to split the view vertically. The
+ default value is `false`, for horizontal.
Return:
@@ -11642,8 +11085,8 @@ Return:
<a id="view.text_width"></a>
#### `view.text_width`(*view, style\_num, text*)
-Returns the pixel width string *text* would have when styled with style
-number *style_num*, in the range of `1` to `256`.
+Returns the pixel width string *text* would have when styled with style number *style_num*,
+in the range of `1` to `256`.
Parameters:
@@ -11658,9 +11101,8 @@ Return:
<a id="view.toggle_fold"></a>
#### `view.toggle_fold`(*view, line*)
-Toggles the fold point on line number *line* between expanded (where all of
-its child lines are displayed) and contracted (where all of its child lines
-are hidden).
+Toggles the fold point on line number *line* between expanded (where all of its child lines
+are displayed) and contracted (where all of its child lines are hidden).
Parameters:
@@ -11674,16 +11116,15 @@ See also:
<a id="view.toggle_fold_show_text"></a>
#### `view.toggle_fold_show_text`(*view, line, text*)
-Toggles a fold point on line number *line* between expanded (where all of
-its child lines are displayed) and contracted (where all of its child lines
-are hidden), and shows string *text* next to that line.
+Toggles a fold point on line number *line* between expanded (where all of its child lines are
+displayed) and contracted (where all of its child lines are hidden), and shows string *text*
+next to that line.
*text* is drawn with style number `view.STYLE_FOLDDISPLAYTEXT`.
Parameters:
* *`view`*: A view.
-* *`line`*: The line number in *view* to toggle the fold on and display
- *text* after.
+* *`line`*: The line number in *view* to toggle the fold on and display *text* after.
* *`text`*: The text to display after the line.
<a id="view.unsplit"></a>
@@ -11711,9 +11152,8 @@ Parameters:
<a id="view.visible_from_doc_line"></a>
#### `view.visible_from_doc_line`(*view, line*)
-Returns the displayed line number of actual line number *line*, taking
-wrapped, annotated, and hidden lines into account, or `-1` if *line* is
-outside the range of lines in the buffer.
+Returns the displayed line number of actual line number *line*, taking wrapped, annotated,
+and hidden lines into account, or `-1` if *line* is outside the range of lines in the buffer.
Lines can occupy more than one display line if they wrap.
Parameters:
@@ -11728,8 +11168,7 @@ Return:
<a id="view.wrap_count"></a>
#### `view.wrap_count`(*view, line*)
-Returns the number of wrapped lines needed to fully display line number
-*line*.
+Returns the number of wrapped lines needed to fully display line number *line*.
Parameters:
diff --git a/docs/book.md b/docs/book.md
index 943429c5..0411efbe 100644
--- a/docs/book.md
+++ b/docs/book.md
@@ -9,12 +9,11 @@
*Textadept Quick Reference*<br/>
Fifth Edition
-Order the <a href="https://gum.co/textadept_ebook" target="_blank">e-book</a> --
-$15 USD<br/>
-Order the <a href="https://gum.co/qr_bundle" target="_blank">e-book bundle</a>
-with [Lua Quick Reference][] -- $27 USD<br/>
-Order the print book via Amazon [US][], [CA][], [UK][], [DE][], [FR][], [IT][],
-[ES][], [JP][] -- ~$25 USD
+Order the <a href="https://gum.co/textadept_ebook" target="_blank">e-book</a> -- $15 USD<br/>
+Order the <a href="https://gum.co/qr_bundle" target="_blank">e-book bundle</a> with
+[Lua Quick Reference][] -- $27 USD<br/>
+Order the print book via Amazon [US][], [CA][], [UK][], [DE][], [FR][], [IT][], [ES][], [JP][] --
+~$25 USD
Published: Dec 2020<br/>
ISBN: 978-0-9912379-6-8<br/>
@@ -22,11 +21,10 @@ Pages: 179
[Excerpt][]
-Textadept is a fast, minimalist, and remarkably extensible cross-platform text
-editor for programmers. This quick reference contains a wealth of knowledge on
-how to script and configure Textadept using the Lua programming language. It
-groups the editor's rich API into a series of tasks in a convenient and
-easy-to-use manner.
+Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor for
+programmers. This quick reference contains a wealth of knowledge on how to script and configure
+Textadept using the Lua programming language. It groups the editor's rich API into a series of
+tasks in a convenient and easy-to-use manner.
This book covers how to:
@@ -40,8 +38,8 @@ This book covers how to:
* Define lexers for highlighting source code
* And much more
-It serves as the perfect complement to Textadept's comprehensive Manual and
-exhaustive API documentation.
+It serves as the perfect complement to Textadept's comprehensive Manual and exhaustive API
+documentation.
[Lua Quick Reference]: https://orbitalquark.github.io/lua-quick-reference
[US]: https://www.amazon.com/dp/099123796X/
diff --git a/docs/changelog.md b/docs/changelog.md
index cf75afe0..b533f394 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -2,8 +2,7 @@
[Atom Feed](https://github.com/orbitalquark/textadept/releases.atom)
-**Please [donate][] or purchase the [book][] to help fund continuous
-development.**
+**Please [donate][] or purchase the [book][] to help fund continuous development.**
[donate]: https://gum.co/textadept
[book]: book.html
@@ -23,8 +22,7 @@ Bugfixes:
* Fixed custom theme's overriding of default theme's colors.
* Do not mark GCC-style "note:" output as compile/run/build/test errors.
* Modules: Fixed inability to handle large LSP notifications.
-* Modules: Prefer asynchronous LSP response reading on Windows in order to
- prevent hanging.
+* Modules: Prefer asynchronous LSP response reading on Windows in order to prevent hanging.
* Modules: Fixed bug where LSP is not notified of files opened during a session.
* Modules: Fixed LSP startup errors if the LSP command is ultimately nil.
* Modules: Fixed debugger status when paused.
@@ -33,12 +31,10 @@ Changes:
* Added `ui.SHOW_ALL_TABS` option for `ui.tabs`.
* Added support for TypeScript.
-* The terminal version now uses a native terminal cursor instead of an
- artificially drawn one.
+* The terminal version now uses a native terminal cursor instead of an artificially drawn one.
* Modules: Keep current line's scroll position when displaying LSP diagnostics.
* Modules: Added option to turn off LSP diagnostic display completely.
-* Modules: Added `debugger.project_commands` for making project-specific
- debugging easier.
+* Modules: Added `debugger.project_commands` for making project-specific debugging easier.
* Updated to [Lua][] 5.4.2.
* Updated to [Scintilla][] 5.0.0.
@@ -67,20 +63,19 @@ Bugfixes:
* Fixed bug restoring view state in an intermediate buffer after closing one.
* Fixed navigating back through history from a print buffer.
* Modules: Fixed incorrect LSP mouse hover query position.
-* Modules: Only notify LSP servers about opened files after startup in order to
- avoid overwhelming the connection.
+* Modules: Only notify LSP servers about opened files after startup in order to avoid overwhelming
+ the connection.
Changes:
* Save the current session prior to loading another one.
* Do not show deleted files in recent file list.
* Updated various lexers and fixed various small lexer issues.
-* Added support for Clojure, Elm, Fantom, fstab, Julia, Meson, Pony, Reason,
- RouterOS, Spin, systemd, systemd-networkd, Xs, and Zig.
+* Added support for Clojure, Elm, Fantom, fstab, Julia, Meson, Pony, Reason, RouterOS, Spin,
+ systemd, systemd-networkd, Xs, and Zig.
* Compile, run, and build command functions can also return environment tables.
* Added [`textadept.run.test()`][] and [`textadept.run.test_commands`][].
-* `io.get_project_root()` accepts an optional flag for returning a submodule
- root.
+* `io.get_project_root()` accepts an optional flag for returning a submodule root.
[Textadept 11.1 -- Win32]: https://github.com/orbitalquark/textadept/releases/download/textadept_11.1/textadept_11.1.win32.zip
[Textadept 11.1 -- Mac OSX 10.7+]: https://github.com/orbitalquark/textadept/releases/download/textadept_11.1/textadept_11.1.macOS.zip
@@ -91,8 +86,7 @@ Changes:
### 11.0 (01 Dec 2020)
-Please see the [10 to 11 migration guide][] for upgrading from Textadept 10 to
-Textadept 11.
+Please see the [10 to 11 migration guide][] for upgrading from Textadept 10 to Textadept 11.
Download:
@@ -135,13 +129,13 @@ Bugfixes:
* Fixed the listing of bookmarks for all open buffers.
* Fixed "Enclose as XML Tags" with multiple selections.
* Fixed clearing of "Replace" entry in Find & Replace pane on reset in the GUI.
-* Fixed lack of statusbar updating when setting options like buffer EOL mode,
- indentation, and encoding from the menu.
+* Fixed lack of statusbar updating when setting options like buffer EOL mode, indentation,
+ and encoding from the menu.
* Do not clear highlighting when searching inside the "Find in Files" buffer.
* `textadept.editing.strip_trailing_spaces` should not apply to binary files.
* Handle recursive symlinks in `lfs.walk()`.
-* Modules: Fixed Lua debugger crash when inspecting variables with very large
- string representations.
+* Modules: Fixed Lua debugger crash when inspecting variables with very large string
+ representations.
* Modules: Support non-UTF-8 spelling dictionaries.
* Modules: Fixed YAML syntax checking notification.
* Modules: Fixed various small issues with the C debugger.
@@ -150,13 +144,12 @@ Changes:
* New [`textadept.history`][] module.
* Updated German and Russian translations.
-* Added [`ui.command_entry.append_history()`][] for special command entry modes
- that need to manually append history.
-* Implement `\U`, `\L`, `\u`, and `\l` case transformations in regex
- replacements.
+* Added [`ui.command_entry.append_history()`][] for special command entry modes that need to
+ manually append history.
+* Implement `\U`, `\L`, `\u`, and `\l` case transformations in regex replacements.
* Added [`textadept.run.set_arguments()`][].
-* Modules: Each module in the separate modules download has its own repository
- now, but all are still bundled into a single archive for release.
+* Modules: Each module in the separate modules download has its own repository now, but all
+ are still bundled into a single archive for release.
* Modules: Greatly improved the speed of file comparison.
* Modules: Added ability to switch spelling dictionaries on the fly.
* Updated to [CDK][] 5.0-20200923.
@@ -186,59 +179,52 @@ Bugfixes:
* Fixed word left/right key bindings on macOS.
* Fixed regression with showing "No results found" in searches.
* Fixed regression in showing images in Lua command entry completions.
-* Fixed restoration of Replace entry text in various instances, such as after
- "Find in Files" and "Replace All".
+* Fixed restoration of Replace entry text in various instances, such as after "Find in Files"
+ and "Replace All".
* Prevent infinite loops when highlighting found text.
* Fixed bugs in `events.KEYPRESS` handlers when command entry is active.
-* Fixed bug in "Find in Files" results highlighting when jumping to a result of
- length 1.
+* Fixed bug in "Find in Files" results highlighting when jumping to a result of length 1.
* Fixed emission of `events.UPDATE_UI` when resuming from terminal suspend.
-* Fixed initial query of `ui.find.find_text` and `ui.find.repl_text` in the
- terminal version.
+* Fixed initial query of `ui.find.find_text` and `ui.find.repl_text` in the terminal version.
* Fixed incorrect CSS key prefix incompatibility notice.
* Fixed error reporting the number of zero-length find results.
* Fixed call tip display in the terminal version.
* Always refresh during incremental find in the terminal version.
* Fixed `io.quick_open()` doing nothing when file limit was exceeded.
* gtDialog: Fixed potential crash when canceling a running progressbar dialog.
-* Scintilla: Fixed position of marker symbols for `view.MARGIN_RTEXT` which were
- being moved based on width of text.
+* Scintilla: Fixed position of marker symbols for `view.MARGIN_RTEXT` which were being moved
+ based on width of text.
* Scintilla: Fixed hover indicator appearance when moving out of view.
-* Scintilla: Fixed display of `buffer.INDIC_TEXTFORE` and gradient indicators on
- hover.
+* Scintilla: Fixed display of `buffer.INDIC_TEXTFORE` and gradient indicators on hover.
Changes:
-* Rewrote manual and updated lots of other documentation and the documentation
- generation pipeline.
+* Rewrote manual and updated lots of other documentation and the documentation generation pipeline.
* Prefer passing an environment table to `os.spawn()`.
* Updated find & replace key bindings.
* Use comma-separated patterns in find & replace pane's "Filter" field.
* Removed "View EOL" menu item, key binding, and buffer setting.
* Accept a directory as a command line argument.
* Save the current working directory to session files.
-* "View > Toggle Fold" toggles folding for the current block, regardless of
- line.
+* "View > Toggle Fold" toggles folding for the current block, regardless of line.
* Recognize Fossil projects.
* Added [`textadept.editing.auto_enclose()`][] for auto-enclosing selected text.
* Show "Match X/Y" in statusbar when searching for text.
* Added [`ui.command_entry.active`][].
* Improved handling of print buffers and splits.
-* Added "Edit > Preferences" menu item and key binding for opening
- *~/.textadept/init.lua*.
+* Added "Edit > Preferences" menu item and key binding for opening *~/.textadept/init.lua*.
* Disable `ui.find.highlight_all_matches` by default.
-* GCC 7.1+ is now required for building, added support for
- [building with Docker][], and dropped automated Linux i386 builds.
+* GCC 7.1+ is now required for building, added support for [building with Docker][], and dropped
+ automated Linux i386 builds.
* Added [`events.FIND_RESULT_FOUND`][].
* Added [`ui.find.active`][] and prevent word highlighting when searching.
* Added support for jq language.
* Record directory in "Find in Files" searches.
* Added `ui.update()`, mainly for unit tests.
-* Added [`events.FILE_BEFORE_RELOAD`][] and [`events.FILE_AFTER_RELOAD`][]
- events, and save/restore bookmarks.
+* Added [`events.FILE_BEFORE_RELOAD`][] and [`events.FILE_AFTER_RELOAD`][] events, and
+ save/restore bookmarks.
* Added [`events.COMMAND_TEXT_CHANGED`][] for when command entry text changes.
-* Added `_NOCOMPAT` option to disable temporary key shortcut compatibility
- checking.
+* Added `_NOCOMPAT` option to disable temporary key shortcut compatibility checking.
* Updated Spanish translation.
* gtDialog: Improved responsiveness for huge lists (greater than 10,000 items).
* Scintilla: Added [`view.multi_edge_column`][].
@@ -293,40 +279,37 @@ Changes:
* Renamed `buffer:set_theme()` to [`view:set_theme()`][].
* Replaced `lfs.dir_foreach()` with [`lfs.walk()`][] generator.
-* Renamed some buffer/view fields to use American English instead of Australian
- English (e.g. "colour" to "color").
-* Changed key binding modifier keys from `c` (Ctrl), `m` (Meta/Command), `a`
- (Alt), and `s` (Shift) to `ctrl`, `meta`/`cmd`, `alt`, and `shift`,
- respectively.
+* Renamed some buffer/view fields to use American English instead of Australian English
+ (e.g. "colour" to "color").
+* Changed key binding modifier keys from `c` (Ctrl), `m` (Meta/Command), `a` (Alt), and `s`
+ (Shift) to `ctrl`, `meta`/`cmd`, `alt`, and `shift`, respectively.
* Renamed `ui.bufstatusbar_text` to `ui.buffer_statusbar_text`.
* Only save before compile/run if the buffer has been modified.
* Added support for Fennel.
* Added [`buffer:style_of_name()`][] as an analogue to `buffer:name_of_style()`.
-* When requiring modules, read from `LUA_PATH` and `LUA_CPATH` environment
- variables instead of `TA_LUA_PATH` and `TA_LUA_CPATH`.
-* `ui.goto_file_found()` and `textadept.run.goto_error()` arguments are now
- optional.
-* Moved Find Incremental into the Find & Replace pane (via
- [`ui.find.incremental`][]), eliminated `ui.find.find_incremental()` and
- `ui.find.find_incremental_keys`, and added [`events.FIND_TEXT_CHANGED`][].
-* Replaced `textadept.editing.highlight_word()` with
- [`textadept.editing.highlight_words`][] auto-highlighting option.
+* When requiring modules, read from `LUA_PATH` and `LUA_CPATH` environment variables instead of
+ `TA_LUA_PATH` and `TA_LUA_CPATH`.
+* `ui.goto_file_found()` and `textadept.run.goto_error()` arguments are now optional.
+* Moved Find Incremental into the Find & Replace pane (via [`ui.find.incremental`][]),
+ eliminated `ui.find.find_incremental()` and `ui.find.find_incremental_keys`, and added
+ [`events.FIND_TEXT_CHANGED`][].
+* Replaced `textadept.editing.highlight_word()` with [`textadept.editing.highlight_words`][]
+ auto-highlighting option.
* Find & Replace Pane now allows file filters to be specified for Find in Files.
* Use monospaced font in Find & Replace Pane text entries.
* Removed legacy "refresh syntax highlighting" feature.
* Modules: Added documentation for generating ctags and API files.
* Modules: Improved in-place editing of files during comparison.
-* Scintilla: added [`lexer.colors`][] and [`lexer.styles`][] tables for use in
- themes. Also added new way to [define and reference styles][].
+* Scintilla: added [`lexer.colors`][] and [`lexer.styles`][] tables for use in themes. Also
+ added new way to [define and reference styles][].
* Scintilla: Added [`lexer.fold*`][] options instead of setting view properties.
* Scintilla: Optimized performance when opening huge files.
-* Scintilla: Added [`buffer.eol_annotation_text`][] analogue to
- `buffer.annotation_text`, but for EOL annotations.
+* Scintilla: Added [`buffer.eol_annotation_text`][] analogue to `buffer.annotation_text`,
+ but for EOL annotations.
* Scintilla: Display DEL control characters like other control characters.
* Scintilla: Allow caret width to be up to 20 pixel.
* Scintilla: Updated markdown and C lexers.
-* Scintilla: Fixed bug with GTK on recent Linux distributions where underscores
- were invisible.
+* Scintilla: Fixed bug with GTK on recent Linux distributions where underscores were invisible.
* Scintilla: Fixed GTK on Linux bug when pasting from closed application.
* Updated to [Scintilla][] 3.21.0.
@@ -360,24 +343,21 @@ Download:
Bugfixes:
-* Fixed some drive letter case issues on Windows resulting in duplicate open
- files.
+* Fixed some drive letter case issues on Windows resulting in duplicate open files.
* Fixed `os.spawn` exit callback and `spawn_proc:wait()` inconsistencies.
* Restore prior key mode after running the command entry.
-* Fixed regression with word completion not respecting
- `buffer.auto_c_ignore_case`.
+* Fixed regression with word completion not respecting `buffer.auto_c_ignore_case`.
* Scintilla: Fixed display of windowed IME on Wayland.
Changes:
-* Views can be used as buffers in most places, resulting in new
- [API suggestions][] for `buffer` and `view`.
+* Views can be used as buffers in most places, resulting in new [API suggestions][] for `buffer`
+ and `view`.
* Scintilla: Added [`buffer:marker_handle_from_line()`][] and
- [`buffer:marker_number_from_line()`][] for iterating through the marker
- handles and marker numbers on a line.
-* Scintilla: Deprecated `lexer.delimited_range()` and `lexer.nested_pair()` in
- favor of [`lexer.range()`][], and added [`lexer.to_eol()`][] and
- [`lexer.number`][].
+ [`buffer:marker_number_from_line()`][] for iterating through the marker handles and marker
+ numbers on a line.
+* Scintilla: Deprecated `lexer.delimited_range()` and `lexer.nested_pair()` in favor of
+ [`lexer.range()`][], and added [`lexer.to_eol()`][] and [`lexer.number`][].
* Scintilla: Automatically scroll text while dragging.
* Scintilla: Improved behavior of IME.
* Updated to [Scintilla][] 3.20.0.
@@ -410,21 +390,17 @@ Bugfixes:
* Fixed `--help` command line option.
* Fixed Textadept API autocompletion and documentation on Windows.
* Fixed bug that regards lexer-specific snippet files as global.
-* Fixed hangs on Win32 terminal version with
- `textadept.editing.filter_through()`.
+* Fixed hangs on Win32 terminal version with `textadept.editing.filter_through()`.
* Fixed issues with buffer z-order when switching between views.
-* Fixed accidental clipping of first character in a snippet under certain
- circumstances.
+* Fixed accidental clipping of first character in a snippet under certain circumstances.
* Fixed C autocompletion error with typerefs.
-* Fixed skipping of event handlers that come directly after one that was just
- run, but disconnected.
-* Fixed bugs in the return values of `ui.dialogs.standard_dropdown` and `msgbox`
- dialogs.
+* Fixed skipping of event handlers that come directly after one that was just run, but
+ disconnected.
+* Fixed bugs in the return values of `ui.dialogs.standard_dropdown` and `msgbox` dialogs.
* Fixed `events.FILE_CHANGED` not emitting a filename.
* Fixed bug with pipes in `textadept.editing.filter_through()`.
* Fixed tab label display on Windows.
-* Fixed bug in syntax highlighting with PHP, Django, and other lexers that embed
- themselves.
+* Fixed bug in syntax highlighting with PHP, Django, and other lexers that embed themselves.
Changes:
@@ -432,46 +408,42 @@ Changes:
* Support more Alt and Shift+Alt keys in the Win32 terminal version.
* `textadept.editing.api_files` acts as if it already has lexer tables defined.
* `textadept.run.goto_error()` wraps searches now.
-* Added snippet trigger autocompletion via
- `textadept.editing.autocomplete('snippet')`.
+* Added snippet trigger autocompletion via `textadept.editing.autocomplete('snippet')`.
* Improved Lua API documentation generator.
* Localization keys in `_L` no longer contain GUI mnemonics ('\_').
* `textadept.snippets` functions no longer have a '\_' prefix.
* `--help` command line options are alphabetized.
* The Lua command entry can now run any `view` functions by name (e.g. split).
-* Auto-pair, type-over, and auto-deletion of matching braces now works with
- multiple selections.
-* Removed `textadept.file_types.lexers` table in favor of asking the LPeg lexer
- for known lexer names.
+* Auto-pair, type-over, and auto-deletion of matching braces now works with multiple selections.
+* Removed `textadept.file_types.lexers` table in favor of asking the LPeg lexer for known
+ lexer names.
* Updated German translation.
-* Changed `textadept.bookmarks.toggle()` to only toggle bookmarks on the current
- line.
-* Removed '=' prefix in command entry that would print results; printing results
- has been the default behavior for quite some time.
+* Changed `textadept.bookmarks.toggle()` to only toggle bookmarks on the current line.
+* Removed '=' prefix in command entry that would print results; printing results has been the
+ default behavior for quite some time.
* Replaced `buffer.style_name[]` with [`buffer:name_of_style()`][].
* Session files are now Lua data files; old formats will no longer work.
-* Added [`events.SESSION_SAVE`][] and [`events.SESSION_LOAD`][] events for
- saving and loading custom user data to sessions.
-* Removed *~/.textadept/?.lua* and *~/.textadept/?.{so,dll}* from `package.path`
- and `package.cpath`, respectively.
+* Added [`events.SESSION_SAVE`][] and [`events.SESSION_LOAD`][] events for saving and loading
+ custom user data to sessions.
+* Removed *~/.textadept/?.lua* and *~/.textadept/?.{so,dll}* from `package.path` and
+ `package.cpath`, respectively.
* Lua errors in Textadept can now be jumped to via double-click or Enter.
* `ui.dialogs.filteredlist()` dialogs have a reasonable default width.
* Renamed `keys.MODE` to [`keys.mode`][].
* Moved individual buffer functions in `io` into `buffer`.
-* Event handlers can now return any non-`nil` value instead of a boolean value
- and have that value passed back to `events.emit()`.
+* Event handlers can now return any non-`nil` value instead of a boolean value and have that
+ value passed back to `events.emit()`.
* Lua command entry completions show images just like in Lua autocompletion.
* Align block comments by column if possible, not indent.
-* Added per-mode command entry history which can be cycled through using the
- `Up` and `Down` keys.
-* Added [`ui.dialogs.progressbar()`][], utilize it with Find in Files, and
- removed `ui.find.find_in_files_timeout`.
-* GUI find/replace history Up/Down history key bindings swapped, mimicking
- traditional command line history navigation.
+* Added per-mode command entry history which can be cycled through using the `Up` and `Down` keys.
+* Added [`ui.dialogs.progressbar()`][], utilize it with Find in Files, and removed
+ `ui.find.find_in_files_timeout`.
+* GUI find/replace history Up/Down history key bindings swapped, mimicking traditional command
+ line history navigation.
* The statusbar now indicates an active snippet.
* Updated to [PDCurses][] 3.9.
-* Experimental set of "standard" modules is provided in the modules archive
- instead of just language modules.
+* Experimental set of "standard" modules is provided in the modules archive instead of just
+ language modules.
[Textadept 11.0 alpha -- Win32]: https://github.com/orbitalquark/textadept/releases/download/textadept_11.0_alpha/textadept_11.0_alpha.win32.zip
[Textadept 11.0 alpha -- Mac OSX 10.6+]: https://github.com/orbitalquark/textadept/releases/download/textadept_11.0_alpha/textadept_11.0_alpha.osx.zip
@@ -502,15 +474,12 @@ Bugfixes:
Changes:
-* Changed [`events.TAB_CLICKED`][] to emit button clicked as well as modifier
- keys.
-* Autocompletion and documentation for Textadept's Lua API only happens in
- Textadept files now (i.e. files in `_HOME` and `_USERHOME`).
-* `textadept.editing.api_files` and `_M.lua.tags` can contain functions that
- return file paths.
+* Changed [`events.TAB_CLICKED`][] to emit button clicked as well as modifier keys.
+* Autocompletion and documentation for Textadept's Lua API only happens in Textadept files now
+ (i.e. files in `_HOME` and `_USERHOME`).
+* `textadept.editing.api_files` and `_M.lua.tags` can contain functions that return file paths.
* Added support for txt2tags.
-* Scintilla: Added access to virtual space at the start and end of multiple
- selections.
+* Scintilla: Added access to virtual space at the start and end of multiple selections.
* Scintilla: The target can have virtual space.
* Updated to [Scintilla][] 3.11.2.
@@ -526,8 +495,8 @@ Changes:
Bugfixes:
* Fixed scroll issues when toggling line wrap.
-* Properly handle absolute paths in run/compile/build output and also
- case-insensitivity on Windows.
+* Properly handle absolute paths in run/compile/build output and also case-insensitivity
+ on Windows.
* Restore virtual space state when switching between buffers.
* Restore rectangular selection state when switching between buffers.
* Fixed opening of non-UTF-8-encoded filenames dropped into a view.
@@ -538,16 +507,14 @@ Bugfixes:
Changes:
* Refactored "Replace All" to be more performant.
-* Added back [`textadept.editing.paste_reindent()`][] as a separate
- menu/key/command from `buffer.paste()`.
-* Enabled all theme colors by default, and changed line number color in the
- terminal version.
-* Replaced `ui.command_entry.enter_mode()` and `ui.command_entry.finish_mode()`
- with simplified [`ui.command_entry.run()`][].
-* Added `ui.find.find_incremental_keys` table of key bindings during "Find
- Incremental" searches.
-* Replaced `textadept.macros.start_recording()` and
- `textadept.macros.stop_recording()` with [`textadept.macros.record()`][].
+* Added back [`textadept.editing.paste_reindent()`][] as a separate menu/key/command from
+ `buffer.paste()`.
+* Enabled all theme colors by default, and changed line number color in the terminal version.
+* Replaced `ui.command_entry.enter_mode()` and `ui.command_entry.finish_mode()` with simplified
+ [`ui.command_entry.run()`][].
+* Added `ui.find.find_incremental_keys` table of key bindings during "Find Incremental" searches.
+* Replaced `textadept.macros.start_recording()` and `textadept.macros.stop_recording()` with
+ [`textadept.macros.record()`][].
* Updated C, Rust, Prolog, and Logtalk lexers.
* Added MediaWiki lexer.
* Scintilla: Updated case conversion and character categories to Unicode 12.1.
@@ -589,10 +556,9 @@ Changes:
* Updated the default window size and some default dialog sizes.
* Updated Markdown lexer.
* Improved C++ lexer to support single quotes in C++14 integer literals.
-* Scintilla: Improved performance opening and closing large files with fold
- points.
-* Scintilla: Tweaked behavior of `buffer.style_case`'s `buffer.CASE_CAMEL`
- option to treat only letters as word characters.
+* Scintilla: Improved performance opening and closing large files with fold points.
+* Scintilla: Tweaked behavior of `buffer.style_case`'s `buffer.CASE_CAMEL` option to treat only
+ letters as word characters.
* Updated to [Scintilla][] 3.10.6.
[`textadept.editing.show_documentation()`]: api.html#textadept.editing.show_documentation
@@ -642,19 +608,14 @@ Bugfixes:
* Fixed behavior of `Home` and `Shift+Home` keys on non-OSX platforms.
* Fixed some instances of snippet next/prev not working correctly.
* Fixed Alt+Gr key handling in the Windows terminal version.
-* Only pass command entry text to function passed to
- `ui.command_entry.finish_mode()`.
-* Fixed handling of escaped double-quotes in `os.spawn()` in the terminal
- version.
-* Ensure long filenames are visible in the reload dialog prompt in the terminal
- version.
+* Only pass command entry text to function passed to `ui.command_entry.finish_mode()`.
+* Fixed handling of escaped double-quotes in `os.spawn()` in the terminal version.
+* Ensure long filenames are visible in the reload dialog prompt in the terminal version.
Changes:
-* Added optional position argument to
- [`textadept.editing.show_documentation()`][].
-* `textadept.editing.highlight_word()` does not select the word by default
- anymore.
+* Added optional position argument to [`textadept.editing.show_documentation()`][].
+* `textadept.editing.highlight_word()` does not select the word by default anymore.
* Changed [file filter][] format to be more flat and intuitive.
* Added `-l` and `--line` command line options to jump to a buffer line.
* Updated to [PDCurses][] 3.6 for the Windows terminal version.
@@ -672,20 +633,19 @@ Bugfixes:
* Fixed key handling on some international keyboards.
* Fixed tab labels not updating when loading message buffers from a session.
* Fixed potential crashes in `string.iconv()` with tiny strings.
-* Fixed inability to resize one split view configuration with the mouse in the
- terminal version.
+* Fixed inability to resize one split view configuration with the mouse in the terminal version.
Changes:
* Renamed `spawn()` to [`os.spawn()`][].
* `os.spawn()` now allows omission of `cwd` and `env` parameters.
* `spawn_proc:wait()` returns the process' exit code.
-* `textadept.editing.filter_through()` halts on non-zero status instead of
- clobbering the buffer or selected text.
-* Removed `textadept.editing.paste()` and `textadept.editing.paste_reindents`
- option; Textadept no longer reindents pasted text by default.
-* Experimentally added [`textadept.macros`][] module for recording, playing,
- saving, and loading keyboard macros.
+* `textadept.editing.filter_through()` halts on non-zero status instead of clobbering the buffer
+ or selected text.
+* Removed `textadept.editing.paste()` and `textadept.editing.paste_reindents` option; Textadept
+ no longer reindents pasted text by default.
+* Experimentally added [`textadept.macros`][] module for recording, playing, saving, and loading
+ keyboard macros.
* Scintilla: Improve efficiency of idle wrapping.
* Scintilla: Updated case conversion and character categories to Unicode 11.
* Scintilla: Updated ConTeXt, HTML, and Markdown lexers.
@@ -705,13 +665,12 @@ Bugfixes:
Changes:
-* Added ability to save/restore persistent data during a reset event via
- [`events.RESET_BEFORE`][] and [`events.RESET_AFTER`][].
-* Replaced `ui.find.find_in_files_filter` with
- [`ui.find.find_in_files_filters`][] table for project-specific filters.
+* Added ability to save/restore persistent data during a reset event via [`events.RESET_BEFORE`][]
+ and [`events.RESET_AFTER`][].
+* Replaced `ui.find.find_in_files_filter` with [`ui.find.find_in_files_filters`][] table for
+ project-specific filters.
* Added Chinese localization.
-* Updated to GTK 2.24.32 on Windows, which fixes a number of various GTK-related
- issues.
+* Updated to GTK 2.24.32 on Windows, which fixes a number of various GTK-related issues.
[`events.RESET_BEFORE`]: api.html#events.RESET_BEFORE
[`events.RESET_AFTER`]: api.html#events.RESET_AFTER
@@ -719,8 +678,7 @@ Changes:
### 10.0 (01 Aug 2018)
-Please see the [9 to 10 migration guide][] for upgrading from Textadept 9 to
-Textadept 10.
+Please see the [9 to 10 migration guide][] for upgrading from Textadept 9 to Textadept 10.
Bugfixes:
@@ -734,8 +692,7 @@ Bugfixes:
Changes:
* Updated German localization.
-* Scintilla: Added new `buffer.INDIC_GRADIENT` and `buffer.INDIC_GRADIENTCENTRE`
- indicators.
+* Scintilla: Added new `buffer.INDIC_GRADIENT` and `buffer.INDIC_GRADIENTCENTRE` indicators.
* Scintilla: Added `buffer.WRAPINDENT_DEEPINDENT` line wrapping option.
* Updated to [Scintilla][] 3.10.0.
* Updated to [Lua][] 5.3.5.
@@ -752,8 +709,7 @@ Bugfixes:
* Fixed a potential infinite loop with "replace in selection".
* Fixed crash on Mac OSX with regex searches.
* Fixed selection of "find in files" result if it's at the start of the line.
-* Properly handle abbreviated setting of write-only buffer properties via
- command entry.
+* Properly handle abbreviated setting of write-only buffer properties via command entry.
Changes:
@@ -788,12 +744,11 @@ Changes:
* Textadept requires GCC 4.9 (circa early-2014) or later to _compile_ (not run).
* C++11 regex replaces old TRE library.
-* Scintillua and Scinterm were merged into Scintilla and are no longer
- dependencies.
+* Scintillua and Scinterm were merged into Scintilla and are no longer dependencies.
* Emacs-style `^K` for OSX and the terminal version joins lines at EOL.
* Pasted text reindents an extra level after a fold header.
-* `buffer.set_theme()` now takes an initial buffer argument like all other
- buffer functions and does not have any call restrictions.
+* `buffer.set_theme()` now takes an initial buffer argument like all other buffer functions
+ and does not have any call restrictions.
* Scintilla: Added [`events.AUTO_C_SELECTION_CHANGE`][] event.
* Updated to [Scintilla][] 3.8.0.
@@ -806,8 +761,7 @@ Bugfixes:
* Fixed clang build warnings/errors regarding LuaJIT.
* Fixed busy wait in second instance of Textadept on Windows.
-* Fixed bug in remote-controlled Textadept when no arguments were initially
- given.
+* Fixed bug in remote-controlled Textadept when no arguments were initially given.
* Fixed session loading when only it is provided as a command line argument.
* Fixed copy-paste between views in the terminal version.
* Fixed crash when attempting to show a badly-encoded filename in the titlebar.
@@ -817,15 +771,13 @@ Bugfixes:
Changes:
* Added `fold.compact` buffer property.
-* Added [`buffer.move_extends_selection`][] for enhanced modal keyboard
- movement.
+* Added [`buffer.move_extends_selection`][] for enhanced modal keyboard movement.
* Auto-detect UTF-16-encoded files automatically.
-* Save to the loaded session on quit and removed the
- `textadept.session.default_session` option.
+* Save to the loaded session on quit and removed the `textadept.session.default_session` option.
* Various Makefile improvements.
* The terminal version can immediately focus on a clicked split view.
-* Textadept only minimally supports GTK3 now -- it still compiles, but
- deprecated function calls have not been, and will not be migrated.
+* Textadept only minimally supports GTK3 now -- it still compiles, but deprecated function
+ calls have not been, and will not be migrated.
* The terminal key sequence for `Ctrl+Space` is now `'c '` instead of `'c@'`.
* The terminal version can now remap `^H` (which was previously locked to
`Backspace`).
@@ -844,16 +796,14 @@ Bugfixes:
Changes:
* Textadept requires GTK 2.24 (circa early-2011) or greater.
-* Pasted text is reindented by default via `textadept.editing.paste()`, and is
- configured with `textadept.editing.paste_reindents`.
+* Pasted text is reindented by default via `textadept.editing.paste()`, and is configured with
+ `textadept.editing.paste_reindents`.
* Replaced `textadept.editing.match_brace()` with a menu function, enhanced
- `textadept.editing.select_enclosed()` behavior, and removed redundant
- "Select in ..." menu items.
-* Removed the need for *~/.textadept/properties.lua*. All `buffer` settings set
- in *~/.textadept/init.lua* will apply to the first and subsequent buffers.
+ `textadept.editing.select_enclosed()` behavior, and removed redundant "Select in ..." menu items.
+* Removed the need for *~/.textadept/properties.lua*. All `buffer` settings set in
+ *~/.textadept/init.lua* will apply to the first and subsequent buffers.
* Renamed `ui.set_theme()` to `buffer.set_theme()`.
-* Enforce extra argument to [`buffer.brace_match()`][] added back in Scintilla
- 3.7.0.
+* Enforce extra argument to [`buffer.brace_match()`][] added back in Scintilla 3.7.0.
* Added [`events.ZOOM`][].
* New, object-oriented way to [create lexers][].
@@ -870,8 +820,8 @@ Bugfixes:
Changes:
-* Scintilla: Block caret appears after selection end instead of on it. (Reverts
- change from Textadept 9.3)
+* Scintilla: Block caret appears after selection end instead of on it. (Reverts change from
+ Textadept 9.3)
### 9.5 (01 Sep 2017)
@@ -890,8 +840,7 @@ Changes:
* Added optional encoding parameter to [`io.open_file()`][].
* Improved file associations on Mac OSX.
* Added support for Myrddin.
-* The terminal version updates its cursor position for display in tools like
- tmux.
+* The terminal version updates its cursor position for display in tools like tmux.
[`ui.switch_buffer()`]: api.html#ui.switch_buffer
[`io.open_file()`]: api.html#io.open_file
@@ -903,22 +852,20 @@ Bugfixes:
* Fixed bug that deleted characters outside of mangled snippets.
* Fixed start-anchored "Find Prev" regex searches.
* Correctly handle multiple '!'-prefixed patterns in file filters.
-* Scintilla: Pressing `Esc` while rectangular selection is active does not
- collapse it.
+* Scintilla: Pressing `Esc` while rectangular selection is active does not collapse it.
Changes:
-* Changed "Cancel Snippet" key binding from `Ctrl+Shift+K` (`⌥⇧⇥` on Mac OSX |
- `M-S-K` in curses) to `Esc`.
+* Changed "Cancel Snippet" key binding from `Ctrl+Shift+K` (`⌥⇧⇥` on Mac OSX | `M-S-K`
+ in curses) to `Esc`.
* Added [`buffer.caret_line_frame`][] option for outlining the current line.
* Added [`buffer:line_reverse()`][] for reversing selected lines.
-* Added [`ui.dialogs.colorselect()`][] and [`ui.dialogs.fontselect()`][]
- dialogs.
+* Added [`ui.dialogs.colorselect()`][] and [`ui.dialogs.fontselect()`][] dialogs.
* Handle pipes in shell commands for [filter-through][].
-* The [Lua command entry][] prints results like Lua 5.3's interactive prompt
- (e.g. no need for explicit '=' prefix).
-* The Lua command entry now invokes bare functions as commands (e.g. `copy`
- invokes `buffer:copy()`, `split` invokes `view:split()`, etc.).
+* The [Lua command entry][] prints results like Lua 5.3's interactive prompt (e.g. no need for
+ explicit '=' prefix).
+* The Lua command entry now invokes bare functions as commands (e.g. `copy` invokes
+ `buffer:copy()`, `split` invokes `view:split()`, etc.).
* Scintilla: Updated case conversion and character categories to Unicode 9.
* Scintilla: Update scroll bar when annotations are added, removed, or changed.
* Effectively updated to [Scintilla][] 3.7.5.
@@ -965,13 +912,11 @@ Bugfixes:
* Fixed folding in multiple-language lexers.
* Fixed accidental editing of cached lexers.
* Scintilla: Minimize redrawing for `buffer.selection_n_*` settings.
-* Scintilla: Fixed individual line selection in files with more than 16.7
- million lines.
+* Scintilla: Fixed individual line selection in files with more than 16.7 million lines.
* Scintilla: Various accessibility fixes for GTK on Linux.
* Scintilla: Fixed a couple of folding regressions.
* Scintilla: Fixed various issues on GTK 3.22.
-* Scintilla: Fixed inability to extend selection up or down in stream selection
- mode.
+* Scintilla: Fixed inability to extend selection up or down in stream selection mode.
Changes:
@@ -1003,33 +948,27 @@ Bugfixes:
* Fixed bug in find/replace with consecutive matches.
* Fixed encoding detection for encodings with NUL bytes (e.g. UTF-16).
* Fixed duplicate entries in `io.recent_files` when loading sessions.
-* Scintilla: Fixed caret placement after left or right movement with rectangular
- selection.
+* Scintilla: Fixed caret placement after left or right movement with rectangular selection.
* Scintilla: Fixed GTK 3 incorrect font size in autocompletion list.
* Scintilla: Fixed various minor GTK bugs.
Changes:
* Added support for Protobuf and Crystal.
-* On Linux systems that support it, `make install` installs `.desktop` files
- too.
+* On Linux systems that support it, `make install` installs `.desktop` files too.
* Removed MacRoman encoding detection and options.
* Scintilla: Character-based word selection, navigation, and manipulation.
-* Scintilla: Added [`view.EDGE_MULTILINE`][],
- [`view:multi_edge_add_line()`][], and [`view:multi_edge_clear_all()`][]
- for multiple edge lines.
-* Scintilla: Added `buffer.MARGIN_COLOUR` and [`buffer.margin_back_n`][] for
- setting arbitrary margin background colors.
+* Scintilla: Added [`view.EDGE_MULTILINE`][], [`view:multi_edge_add_line()`][], and
+ [`view:multi_edge_clear_all()`][] for multiple edge lines.
+* Scintilla: Added `buffer.MARGIN_COLOUR` and [`buffer.margin_back_n`][] for setting arbitrary
+ margin background colors.
* Scintilla: Added [`buffer.margins`][] for more margins.
* Scintilla: Added accessibility support for GTK on Linux.
-* Scintilla: Added [`buffer:toggle_fold_display_text()`][] and
- [`buffer.fold_display_text_style`][] for showing text next to folded lines.
-* Scintilla: Added new `buffer.INDIC_POINT` and `buffer.INDIC_POINTCHARACTER`
- indicators.
-* Scintilla: Added [`buffer.tab_draw_mode`][] for changing the appearance of
- visible tabs.
-* Scintilla: Margin click line selection clears rectangular and multiple
- selection.
+* Scintilla: Added [`buffer:toggle_fold_display_text()`][] and [`buffer.fold_display_text_style`][]
+ for showing text next to folded lines.
+* Scintilla: Added new `buffer.INDIC_POINT` and `buffer.INDIC_POINTCHARACTER` indicators.
+* Scintilla: Added [`buffer.tab_draw_mode`][] for changing the appearance of visible tabs.
+* Scintilla: Margin click line selection clears rectangular and multiple selection.
* Updated to [Scintilla][] 3.7.1.
[`view.EDGE_MULTILINE`]: api.html#view.EDGE_MULTILINE
@@ -1044,24 +983,21 @@ Changes:
### 9.0 (01 Oct 2016)
-Please see the [8 to 9 migration guide][] for upgrading from Textadept 8 to
-Textadept 9.
+Please see the [8 to 9 migration guide][] for upgrading from Textadept 8 to Textadept 9.
Bugfixes:
* Better error handling with "filter-through".
* Fixed error in building projects.
* Better handling of key bindings on international keyboards.
-* Scintilla: Respect indentation settings when inserting indentation within
- virtual space.
+* Scintilla: Respect indentation settings when inserting indentation within virtual space.
* Scintilla: Fixed bug with expanding folds.
* Scintilla: Fix GTK 3 runtime warning.
Changes:
* Added TaskPaper lexer.
-* Scintilla: Added `buffer.VS_NOWRAPLINESTART` option to
- `buffer.virtual_space_options`.
+* Scintilla: Added `buffer.VS_NOWRAPLINESTART` option to `buffer.virtual_space_options`.
* Updated to [Scintilla][] 3.6.7.
[8 to 9 migration guide]: manual.html#textadept-8-to-9
@@ -1076,8 +1012,7 @@ Bugfixes:
* Fixed passing of quoted arguments to OSX `ta` script.
* Fixed CapsLock key handling.
* Fixed button order in the terminal version's dialogs.
-* Fixed potential crash on Windows with `textadept.editing.filter_through()` and
- some locales.
+* Fixed potential crash on Windows with `textadept.editing.filter_through()` and some locales.
* Fixed infinite loop in "Replace All" with zero-length regex matches.
Changes:
@@ -1113,40 +1048,32 @@ Bugfixes:
Changes:
-* Renamed `io.snapopen()` to [`io.quick_open()`][] and tweaked its arguments,
- renamed `io.SNAPOPEN_MAX` to [`io.quick_open_max`][], and renamed
- `io.snapopen_filters` to [`io.quick_open_filters`][].
-* Removed BOM (byte order mark) encoding detection. (BOM use is legacy and
- discouraged.)
+* Renamed `io.snapopen()` to [`io.quick_open()`][] and tweaked its arguments, renamed
+ `io.SNAPOPEN_MAX` to [`io.quick_open_max`][], and renamed `io.snapopen_filters` to
+ [`io.quick_open_filters`][].
+* Removed BOM (byte order mark) encoding detection. (BOM use is legacy and discouraged.)
* Removed detection and use of extinct `\r` (CR) line endings.
* Removed project support for CVS and assume Subversion v1.8+.
-* Key and menu commands [must be Lua functions][]; the table syntax is no longer
- recognized.
-* Renamed `lfs.FILTER` to [`lfs.default_filter`][] and tweaked arguments to
- `lfs.dir_foreach()`.
+* Key and menu commands [must be Lua functions][]; the table syntax is no longer recognized.
+* Renamed `lfs.FILTER` to [`lfs.default_filter`][] and tweaked arguments to `lfs.dir_foreach()`.
* Locale files can optionally use `#` for comments instead of `%`.
* Renamed `ui.SILENT_PRINT` to [`ui.silent_print`][].
-* Renamed all [`textadept.editing`][]`.[A-Z]+` options to their lower-case
- equivalents and renamed `textadept.editing.braces` to
- [`textadept.editing.brace_matches`][].
+* Renamed all [`textadept.editing`][]`.[A-Z]+` options to their lower-case equivalents and
+ renamed `textadept.editing.braces` to [`textadept.editing.brace_matches`][].
* *post_init.lua* files for language modules are [no longer auto-loaded][]; use
[`events.LEXER_LOADED`][] to load additional bits instead.
-* Renamed `ui.find.FILTER` to [`ui.find.find_in_files_filter`][] and added an
- optional argument to [`ui.find.find_in_files()`][].
-* Renamed all [`textadept.session`][]`.[A-Z]+` options to their lower-case
- equivalents.
+* Renamed `ui.find.FILTER` to [`ui.find.find_in_files_filter`][] and added an optional argument
+ to [`ui.find.find_in_files()`][].
+* Renamed all [`textadept.session`][]`.[A-Z]+` options to their lower-case equivalents.
* Removed syntax checking support, renamed `textadept.run.RUN_IN_BACKGROUND` to
- [`textadept.run.run_in_background`][], removed `textadept.run.cwd` and
- `textadept.run.proc`, added optional arguments to
- [`textadept.run.compile()`][], [`textadept.run.run()`][], and
- [`textadept.run.build()`][], and changed the format of
- [`textadept.run.error_patterns`][].
-* Rewrote sections 7-9 in the [manual][] and added a new part to section 11.
- Understanding how to configure and script Textadept should be easier now.
-* `textadept.editing.goto_line()` takes a 0-based line number like all
- Scintilla functions.
-* `ui.goto_view()` and `view:goto_buffer()` now take actual `view` and `buffer`
- arguments, respectively, or a relative number.
+ [`textadept.run.run_in_background`][], removed `textadept.run.cwd` and `textadept.run.proc`,
+ added optional arguments to [`textadept.run.compile()`][], [`textadept.run.run()`][], and
+ [`textadept.run.build()`][], and changed the format of [`textadept.run.error_patterns`][].
+* Rewrote sections 7-9 in the [manual][] and added a new part to section 11. Understanding how
+ to configure and script Textadept should be easier now.
+* `textadept.editing.goto_line()` takes a 0-based line number like all Scintilla functions.
+* `ui.goto_view()` and `view:goto_buffer()` now take actual `view` and `buffer` arguments,
+ respectively, or a relative number.
* Added [file-based snippet][] capabilities.
* Updated to [Scintilla][] 3.6.6.
* Updated to [Lua][] 5.3.3
@@ -1184,11 +1111,9 @@ Bugfixes:
* Added some block comment strings for languages lacking them.
* Fixed a number of small encoding issues in various corner cases.
* Fixed bug in `textadept.editing.convert_indentation()` with mixed indentation.
-* Fixed an obscure side-effect that reset buffer properties when working with
- non-focused buffers.
+* Fixed an obscure side-effect that reset buffer properties when working with non-focused buffers.
* Fixed incremental find with UTF-8 characters.
-* Fixed bug in session restoration of scroll and caret positions in multiple
- views.
+* Fixed bug in session restoration of scroll and caret positions in multiple views.
* Fixed bug where existing files were not closed when a session is loaded.
* Fixed corner case in "replace within selection".
* Fixed regression for `%<...>` and `%[...]` in snippets.
@@ -1200,19 +1125,18 @@ Bugfixes:
Changes:
-* Support UTF-8 pattern matching in "Lua Pattern" searches by incorporating bits
- of [luautf8][].
+* Support UTF-8 pattern matching in "Lua Pattern" searches by incorporating bits of [luautf8][].
* Improved efficiency of autocompleting words from all open buffers.
* "Find in Files" defaults to the current project's root directory.
-* Submenus and menu items can be accessed by name. (See
- [`textadept.menu.menubar`][] for an example.)
+* Submenus and menu items can be accessed by name. (See [`textadept.menu.menubar`][] for an
+ example.)
* Only show snippet trigger and text when selecting from a dialog.
* More efficient screen refreshes in the terminal version.
* Save and restore horizontal scroll position when switching buffers.
-* The undocumented `keys.utils` was removed. This will break custom key bindings
- that depend on it. See [this mailing list post][] for more information.
-* The menubar is loaded on `events.INITIALIZED` now. See the above mailing
- list post for more information.
+* The undocumented `keys.utils` was removed. This will break custom key bindings that depend
+ on it. See [this mailing list post][] for more information.
+* The menubar is loaded on `events.INITIALIZED` now. See the above mailing list post for more
+ information.
* Allow file-specific [compile commands][] and [run commands][].
* Added new dialog for specifying compile/run command arguments to "Tools" menu.
* `textadept.editing.enclose()` works with multiple selections.
@@ -1232,8 +1156,8 @@ Changes:
Bugfixes:
-* Prevent silent crash reports from being generated on Mac OSX when child
- processes fail to be spawned.
+* Prevent silent crash reports from being generated on Mac OSX when child processes fail to
+ be spawned.
* Do not "busy wait" for spawned process stdout or stderr on Mac OSX.
* Fixed bug in escaping `([{<` after mirrors in snippets.
* Only change spawned process environment if one was specified on Mac OSX.
@@ -1241,23 +1165,20 @@ Bugfixes:
* Fixed building the terminal version in debug mode.
* Fixed potential crash with malformed style properties.
* Fixed unlikely buffer overflow in messages coming from Scintilla.
-* Fixed potential memory access error when closing Textadept while a spawned
- process is still alive.
-* Fixed bug in setting view properties when restoring sessions with nested
- splits.
+* Fixed potential memory access error when closing Textadept while a spawned process is still
+ alive.
+* Fixed bug in setting view properties when restoring sessions with nested splits.
Changes:
-* Added support for APL, Docker, Faust, Ledger, MoonScript, man/roff, PICO-8,
- and Pure.
+* Added support for APL, Docker, Faust, Ledger, MoonScript, man/roff, PICO-8, and Pure.
* Enabled idle-styling of buffers in the background in the GUI version.
* Undocumented `buffer:clear_cmd_key()` only takes one argument now.
* Added `-v` and `--version` command line parameters.
* Added single-instance functionality on Win32.
* Require GLib 2.28+.
* Recognize the `weight` [style property][].
-* Added [`lexer.line_state`][] and [`lexer.line_from_position()`][] for
- [stateful lexers][].
+* Added [`lexer.line_state`][] and [`lexer.line_from_position()`][] for [stateful lexers][].
* Updated to lspawn 1.4.
* Updated to [Scintilla][] 3.6.3.
* Updated to Scinterm 1.7.
@@ -1281,8 +1202,7 @@ Bugfixes:
Changes:
-* Allow [compile, run, and build commands][] functions to specify a working
- directory.
+* Allow [compile, run, and build commands][] functions to specify a working directory.
* Added support for SNOBOL4.
* Added support for Icon.
* Added support for AutoIt.
@@ -1355,12 +1275,10 @@ Changes:
* Highlight found text in "Find in Files" searches.
* Added Italian translation and updated French translation.
* Added automatic syntax checking as source files are saved, along with
- `textadept.run.CHECK_SYNTAX` and `textadept.run.GOTO_SYNTAX_ERRORS`
- configuration fields.
-* Scintilla: multiple selection works over more key commands like caret
- movement, selections, and word and line deletions.
-* Scintilla: new [`events.AUTO_C_COMPLETED`][] event for when autocompleted text
- has been inserted.
+ `textadept.run.CHECK_SYNTAX` and `textadept.run.GOTO_SYNTAX_ERRORS` configuration fields.
+* Scintilla: multiple selection works over more key commands like caret movement, selections,
+ and word and line deletions.
+* Scintilla: new [`events.AUTO_C_COMPLETED`][] event for when autocompleted text has been inserted.
* Updated to [Scintilla][] 3.6.0.
[`events.AUTO_C_COMPLETED`]: api.html#events.AUTO_C_COMPLETED
@@ -1381,13 +1299,11 @@ Bugfixes:
Changes:
* Added support for Elixir and Windows Script Files (WSF).
-* Added parameter to [`textadept.editing.select_word()`][] for selecting all
- occurrences.
+* Added parameter to [`textadept.editing.select_word()`][] for selecting all occurrences.
* Scintilla: added [`buffer:multiple_select_add_next()`][] and
- [`buffer:multiple_select_add_each()`][] for creating multiple selections from
- selected text.
-* Scintilla: added [`buffer:is_range_word()`][] and
- [`buffer:target_whole_document()`][] helper functions for search and replace.
+ [`buffer:multiple_select_add_each()`][] for creating multiple selections from selected text.
+* Scintilla: added [`buffer:is_range_word()`][] and [`buffer:target_whole_document()`][] helper
+ functions for search and replace.
* Updated to [Scintilla][] 3.5.7.
* Updated to [Lua][] 5.3.1.
@@ -1401,8 +1317,7 @@ Changes:
### 8.0 (01 May 2015)
-Please see the [7 to 8 migration guide][] for upgrading from Textadept 7 to
-Textadept 8.
+Please see the [7 to 8 migration guide][] for upgrading from Textadept 7 to Textadept 8.
Bugfixes:
@@ -1425,8 +1340,8 @@ Bugfixes:
Changes:
-* Added `symlink` filter option for ignoring symlinked files and folders to
- [`io.snapopen()`][], `lfs.dir_foreach()`, and [`ui.find.FILTER`][].
+* Added `symlink` filter option for ignoring symlinked files and folders to [`io.snapopen()`][],
+ `lfs.dir_foreach()`, and [`ui.find.FILTER`][].
* Added [`_FOLDBYINDENTATION`][] field for lexers that fold by indentation.
* Updated to [Scintilla][] 3.5.5.
@@ -1445,16 +1360,14 @@ Bugfixes:
Changes:
* Upgraded to Lua 5.3, LPeg 0.12.2, lfs 1.6.3, and lspawn 1.2.
-* Removed `keys.LANGUAGE_MODULE_PREFIX`, but left that prefix unused on all
- platforms.
+* Removed `keys.LANGUAGE_MODULE_PREFIX`, but left that prefix unused on all platforms.
* `textadept.editing.filter_through()` now uses `os.spawn()`.
* Removed long-hand [compile and run macros][] in favor of shorter ones.
* [`textadept.bookmarks.toggle()`][] accepts an optional line to bookmark.
* Added support for Rust and TOML.
* "Goto Bookmark" now lists bookmarks in all open buffers.
* [`spawn_proc:kill()`][] can send signals to processes.
-* New [`lexer._FOLDBYINDENTATION`][] field for lexers that fold based on
- indentation.
+* New [`lexer._FOLDBYINDENTATION`][] field for lexers that fold based on indentation.
[compile and run macros]: api.html#textadept.run.compile\_commands
[`textadept.bookmarks.toggle()`]: api.html#textadept.bookmarks.toggle
@@ -1465,8 +1378,7 @@ Changes:
Bugfixes:
-* Fixed command entry's abbreviated environment to allow functions to return
- values.
+* Fixed command entry's abbreviated environment to allow functions to return values.
* Fixed accidental firing of "Escape" key on window focus lost.
* Fixed tab stop calculation in the terminal version.
* Improved performance of lexers that fold by indentation.
@@ -1474,21 +1386,18 @@ Bugfixes:
Changes:
-* The following view-specific properties are now considered buffer-specific:
- "view EOL", "view whitespace", "wrap mode", "margin type", and "margin width";
- updated the "Buffer" and "View" menus appropriately.
+* The following view-specific properties are now considered buffer-specific: "view EOL", "view
+ whitespace", "wrap mode", "margin type", and "margin width"; updated the "Buffer" and "View"
+ menus appropriately.
* Officially supported language modules moved to a [new repository][].
* Added Fish lexer and updated PHP and Python lexers.
-* Merged `events.FILE_SAVED_AS` into [`events.FILE_AFTER_SAVE`][] as a new
- parameter.
-* Merged `textadept.file_types.shebangs` into
- [`textadept.file_types.patterns`][].
+* Merged `events.FILE_SAVED_AS` into [`events.FILE_AFTER_SAVE`][] as a new parameter.
+* Merged `textadept.file_types.shebangs` into [`textadept.file_types.patterns`][].
* Removed `io.boms`.
-* Scintilla: added [`buffer.indic_hover_fore`][] and
- [`buffer.indic_hover_style`][] for styling indicators differently when the
- mouse is over them.
-* Added new `buffer.INDIC_COMPOSITIONTHIN`, `buffer.INDIC_FULLBOX`, and
- `buffer.INDIC_TEXTFORE` indicators.
+* Scintilla: added [`buffer.indic_hover_fore`][] and [`buffer.indic_hover_style`][] for styling
+ indicators differently when the mouse is over them.
+* Added new `buffer.INDIC_COMPOSITIONTHIN`, `buffer.INDIC_FULLBOX`, and `buffer.INDIC_TEXTFORE`
+ indicators.
* Updated to [Scintilla][] 3.5.4.
[new repository]: https://github.com/orbitalquark/textadept-modules
@@ -1506,8 +1415,8 @@ Bugfixes:
Changes:
-* Removed language-specific context menus; manipulate
- `textadept.menu.context_menu` directly from language modules.
+* Removed language-specific context menus; manipulate `textadept.menu.context_menu` directly
+ from language modules.
### 7.8 beta 3 (21 Jan 2015)
@@ -1525,8 +1434,7 @@ Bugfixes:
Changes:
* Restore `^Z` key binding as "undo" if terminal suspend is disabled.
-* Added [`events.SUSPEND`][] and [`events.RESUME`][] events for terminal suspend
- and resume.
+* Added [`events.SUSPEND`][] and [`events.RESUME`][] events for terminal suspend and resume.
* Updated to [Scintilla][] 3.5.3.
[`events.SUSPEND`]: api.html#events.SUSPEND
@@ -1538,8 +1446,7 @@ Changes:
Bugfixes:
* Improved C module's ctags lookups and autocompletion.
-* Do not select a line when clicking on its first character in the terminal
- version.
+* Do not select a line when clicking on its first character in the terminal version.
* Fixed some cases of toggling find options via API in the terminal version.
* Improved folding by indentation.
* Scintilla: fixed caret blinking when holding down `Del`.
@@ -1547,14 +1454,12 @@ Bugfixes:
Changes:
-* The terminal version can suspend via `^Z` (changed "undo" key binding to
- `M-Z` and added additional `M-S-Z` "redo" binding).
+* The terminal version can suspend via `^Z` (changed "undo" key binding to `M-Z` and added
+ additional `M-S-Z` "redo" binding).
* Added [`spawn_proc:close()`][] for sending EOF to spawned processes.
* Updated Tcl lexer.
-* Scintilla: Added `buffer.ANNOTATION_INDENTED` for indented, non-bordered
- annotations.
-* Scintilla: tab arrows, wrap markers, and line markers are now drawn in the
- terminal version.
+* Scintilla: Added `buffer.ANNOTATION_INDENTED` for indented, non-bordered annotations.
+* Scintilla: tab arrows, wrap markers, and line markers are now drawn in the terminal version.
* Updated to [Scintilla][] 3.5.2.
[`spawn_proc:close()`]: api.html#spawn_proc:close
@@ -1571,30 +1476,24 @@ Bugfixes:
* Fixed return values from `ui.dialogs.optionselect()`.
* The command entry does not hide when the window loses focus.
* Fixed '//' bug when iterating over root directory with `lfs.dir_foreach()`.
-* Fixed bug in jumping to compile/run errors and clear annotations before
- building projects.
+* Fixed bug in jumping to compile/run errors and clear annotations before building projects.
* Fixed memory leaks in `ui.dialog()`.
Changes:
* Replaced the command entry text field with a Scintilla buffer and added
- [`ui.command_entry.editing_keys`][] for changing the editing keys in all
- modes.
+ [`ui.command_entry.editing_keys`][] for changing the editing keys in all modes.
* Added lexer and height parameters to `ui.command_entry.enter_mode()`.
* Support bracketed paste in the terminal version.
* Allow handling of unknown [CSI events][].
-* Added mouse support for buffers and eliminated many
- [terminal version incompatibilities][].
-* Added [`_G.LINUX`][] and [`_G.BSD`][] platform flags for the sake of
- completeness.
-* [Rectangular selections][] with the mouse on Linux use the `Alt` modifier key
- instead of `Super`.
+* Added mouse support for buffers and eliminated many [terminal version incompatibilities][].
+* Added [`_G.LINUX`][] and [`_G.BSD`][] platform flags for the sake of completeness.
+* [Rectangular selections][] with the mouse on Linux use the `Alt` modifier key instead of `Super`.
* Display the current working directory in fileselect dialogs.
* Added [`_SCINTILLA.next_image_type()`][] for registering images.
* Added Arabic translation.
* File dialogs in the terminal span the whole view.
-* Added basic UTF-8 support for terminal widgets -- locales such as Russian now
- display properly.
+* Added basic UTF-8 support for terminal widgets -- locales such as Russian now display properly.
* Added UTF-8 input mode for Mac OSX (`⌘⇧U`) and the terminal version (`M-U`).
* Show character information in "Show Style" popup.
@@ -1656,8 +1555,7 @@ Changes:
* New [`events.FOCUS`][] event for when Textadept's window receives focus.
* Condensed manual and API documentation into single files.
* Added Polish translation.
-* Scintilla: added [`buffer.auto_c_multi`][] for autocompleting into multiple
- selections.
+* Scintilla: added [`buffer.auto_c_multi`][] for autocompleting into multiple selections.
* Updated to [Scintilla][] 3.4.4.
[`events.FOCUS`]: api.html#events.FOCUS
@@ -1675,8 +1573,7 @@ Bugfixes:
Changes:
-* Pressing the Enter key in the message buffer and find in files buffer
- simulates a double-click.
+* Pressing the Enter key in the message buffer and find in files buffer simulates a double-click.
### 7.3 (01 Jun 2014)
@@ -1694,23 +1591,20 @@ Changes:
* Added reST and YAML lexers and official language modules for each.
* Use `os.spawn()` for launching help.
* Renamed `io.set_buffer_encoding()` to [`buffer:set_encoding()`][].
-* Removed Adeptsense in favor of [autocompleter functions][], but kept existing
- [api file format][].
+* Removed Adeptsense in favor of [autocompleter functions][], but kept existing [api file
+ format][].
* Renamed `textadept.editing.autocomplete_word()` to
[`textadept.editing.autocomplete`][]`('word')`.
-* New [`textadept.editing.AUTOCOMPLETE_ALL`][] field for autocompleting words
- from all open buffers.
-* Dropped support for official java, php, rails, and rhtml modules; they are
- on the wiki now.
-* Removed `textadept.editing.HIGHLIGHT_BRACES` option, as indicator style can be
- changed to hide highlighting.
+* New [`textadept.editing.AUTOCOMPLETE_ALL`][] field for autocompleting words from all open
+ buffers.
+* Dropped support for official java, php, rails, and rhtml modules; they are on the wiki now.
+* Removed `textadept.editing.HIGHLIGHT_BRACES` option, as indicator style can be changed to
+ hide highlighting.
* Removed `textadept.editing.select_indented_block()`.
-* In-place menu editing via [`textadept.menu.menubar`][],
- [`textadept.menu.context_menu`][], and [`textadept.menu.tab_context_menu`][]
- tables.
-* Removed `textadept.command_entry.complete_lua()` and
- `textadept.command_entry.execute_lua()` and moved their key bindings into
- their module.
+* In-place menu editing via [`textadept.menu.menubar`][], [`textadept.menu.context_menu`][],
+ and [`textadept.menu.tab_context_menu`][] tables.
+* Removed `textadept.command_entry.complete_lua()` and `textadept.command_entry.execute_lua()`
+ and moved their key bindings into their module.
* Updated D lexer.
* Scintilla: added `buffer.FOLDFLAG_LINESTATE` for lexer debugging aid.
* Updated to [Scintilla][] 3.4.2.
@@ -1763,13 +1657,12 @@ Changes:
* New [optionselect][] dialog.
* Added [`ui.SILENT_PRINT`][] option for printing messages.
* The GUI version can [spawn processes][] in separate threads.
-* Removed experimental Windows `io.popen()` and `os.execute()` replacements due
- to spawning support.
+* Removed experimental Windows `io.popen()` and `os.execute()` replacements due to spawning
+ support.
* [Snapopen][] now supports projects; added new menu entry and key command.
* Added support for [building projects][].
* Scintilla: draw unicode line ends as blobs.
-* Scintilla: added `buffer.WRAP_WHITESPACE` for wrapping on whitespace, not
- style changes.
+* Scintilla: added `buffer.WRAP_WHITESPACE` for wrapping on whitespace, not style changes.
* Updated to [LuaJIT][] 2.0.3.
* Updated to [Scintilla][] 3.4.1.
@@ -1804,10 +1697,8 @@ Changes:
* Added Swedish translation.
* Added support for multiple entry boxes in [inputdialogs][].
* Updated LaTeX and Go lexers.
-* Scintilla: added [`buffer:drop_selection_n()`][] for dropping a multiple
- selection.
-* Scintilla: added `buffer.call_tip_pos_start` for altering call tip
- backspace behavior.
+* Scintilla: added [`buffer:drop_selection_n()`][] for dropping a multiple selection.
+* Scintilla: added `buffer.call_tip_pos_start` for altering call tip backspace behavior.
* Scintilla: added `buffer.MARK_BOOKMARK` marker symbol.
* Scintilla: better marker drawing.
* Updated to [Scintilla][] 3.3.9.
@@ -1824,8 +1715,7 @@ Bugfixes:
* Do not halt opening files if one of them is already open.
* Better key input handling in the terminal version.
* Fixed Makefile bug in grabbing dependencies with older versions of wget.
-* Recognize lower-case drive letter names for files passed from external
- programs in Windows.
+* Recognize lower-case drive letter names for files passed from external programs in Windows.
* Scintilla: fixed some instances of adjacent indicator drawing.
* Scintilla: fixed scroll width tracking for annotated lines.
* Scintilla: fixed horizontal scroll bar range.
@@ -1836,23 +1726,21 @@ Changes:
* Added Dart lexer.
* Do not split the view when printing messages if tabs are enabled.
-* Look for *~/.textadept/osx_env.sh* for [OSX environment variables][] due to
- changes in Mac OSX 10.9.
-* [Experimental] Replaced Lua's `io.popen()` and `os.execute()` with versions
- that do not flash the "black box" on Windows.
+* Look for *~/.textadept/osx_env.sh* for [OSX environment variables][] due to changes in Mac
+ OSX 10.9.
+* [Experimental] Replaced Lua's `io.popen()` and `os.execute()` with versions that do not flash
+ the "black box" on Windows.
* Added read-only access to the current key chain via `keys.keychain`.
* Renamed "hypertext" lexer and its corresponding module to "html".
* Added configurable tab context menus via `textadept.menu.set_contextmenus()`.
* New GUI theme for Mac OSX.
* [Experimental] Merged separate lexer states into Textadept's Lua state.
* Updated HTML lexer.
-* Scintilla: the `Ctrl` modifier in Mac OSX mouse clicks is recognized as
- `buffer.MOD_META`.
-* Scintilla: added [`buffer.representation`][] for changing the representation
- of characters.
+* Scintilla: the `Ctrl` modifier in Mac OSX mouse clicks is recognized as `buffer.MOD_META`.
+* Scintilla: added [`buffer.representation`][] for changing the representation of characters.
* Scintilla: added [`buffer:position_relative()`][] for character navigation.
-* Scintilla: added [`buffer.mouse_selection_rectangular_switch`][] for aiding in
- rectangular selection creation.
+* Scintilla: added [`buffer.mouse_selection_rectangular_switch`][] for aiding in rectangular
+ selection creation.
* Updated to [Lua][] 5.2.3.
* Updated to [Scintilla][] 3.3.7.
@@ -1876,8 +1764,7 @@ Bugfixes:
Changes:
* Tabs for multiple buffers along with [`ui.tabs`][] API.
-* Split C/C++ lexer into separate lexers and replaced default "cpp" module with
- "ansi\_c".
+* Split C/C++ lexer into separate lexers and replaced default "cpp" module with "ansi\_c".
* Find and replace text may utilize "%0" capture containing the entire match.
* Disable `textadept.editing.STRIP_TRAILING_SPACES` by default.
* `ui.clipboard_text` is no longer read-only.
@@ -1888,8 +1775,7 @@ Changes:
### 7.0 (01 Nov 2013)
-Please see the [6 to 7 migration guide][] for upgrading from Textadept 6 to
-Textadept 7.
+Please see the [6 to 7 migration guide][] for upgrading from Textadept 6 to Textadept 7.
Bugfixes:
@@ -1920,16 +1806,15 @@ Changes:
* Changed `ui.set_theme()` API to accept a table of property assignments.
* Added Nimrod lexer and compile and run commands.
-* Use [`textadept.editing.INDIC_BRACEMATCH`][] indicator for brace highlighting
- instead of styles.
+* Use [`textadept.editing.INDIC_BRACEMATCH`][] indicator for brace highlighting instead of styles.
* The `buffer` API applies to all buffers now, not just the global one.
* Added "Save All" to the menu.
* Updated D lexer.
-* Added additional parameter to [`lexer.load()`][] to allow child lexers to be
- embedded multiple times with different start/end tokens.
+* Added additional parameter to [`lexer.load()`][] to allow child lexers to be embedded multiple
+ times with different start/end tokens.
* Lexers do not need an "any\_char" [rule][] anymore; it is included by default.
-* [Child lexers][] do not need an explicit `M._lexer = parent` declaration
- anymore; it is done automatically.
+* [Child lexers][] do not need an explicit `M._lexer = parent` declaration anymore; it is done
+ automatically.
[`textadept.editing.INDIC_BRACEMATCH`]: api.html#textadept.editing.INDIC_BRACEMATCH
[`lexer.load()`]: api.html#lexer.load
@@ -1947,34 +1832,28 @@ Bugfixes:
Changes:
* [`events.disconnect()`][] now accepts function argument instead of ID.
-* `buffer.filename` and all internal filenames are no longer encoded in
- UTF-8, but in [`_CHARSET`][].
-* Removed many unused Scintilla constants and stripped many constants of `SC`
- and `SC_` prefixes.
+* `buffer.filename` and all internal filenames are no longer encoded in UTF-8, but in
+ [`_CHARSET`][].
+* Removed many unused Scintilla constants and stripped many constants of `SC` and `SC_` prefixes.
* Changed marker margin symbols via *properties.lua*.
-* Calling `textadept.editing.select_word()` repeatedly makes multiple
- selections.
+* Calling `textadept.editing.select_word()` repeatedly makes multiple selections.
* Renamed `buffer:convert_eo_ls()` to [`convert_eols()`][].
* Added [`textadept.run.MARK_WARNING`][] marker.
-* Renamed `textadept.run.compile_command` and `textadept.run.run_command` to
- [`compile_commands`][] and [`run_commands`][], respectively.
-* Renamed `textadept.run.error_detail` to [`error_patterns`][] and changed its
- internal structure.
-* Compile and run commands for languages that support them are now built-in
- along with their respective warning and error messages. The supplemental ones
- on the wiki are no longer needed.
-* New [`ui.dialogs`][] module for more user-friendly dialog support. Removed
- `ui.filteredlist()` as a result.
-* Changed [`io.open_file()`][] and [`io.snapopen()`][] to accept tables of files
- and paths instead of "\n" delimited strings.
-* Changed `lexer.get_fold_level()`, `lexer.get_indent_amount()`,
- `lexer.get_property()`, and `lexer.get_style_at()` functions to be
- [`lexer.fold_level`][], [`lexer.indent_amount`][], [`lexer.property`][], and
- [`lexer.style_at`][] tables, respectively.
+* Renamed `textadept.run.compile_command` and `textadept.run.run_command` to [`compile_commands`][]
+ and [`run_commands`][], respectively.
+* Renamed `textadept.run.error_detail` to [`error_patterns`][] and changed its internal structure.
+* Compile and run commands for languages that support them are now built-in along with their
+ respective warning and error messages. The supplemental ones on the wiki are no longer needed.
+* New [`ui.dialogs`][] module for more user-friendly dialog support. Removed `ui.filteredlist()`
+ as a result.
+* Changed [`io.open_file()`][] and [`io.snapopen()`][] to accept tables of files and paths
+ instead of "\n" delimited strings.
+* Changed `lexer.get_fold_level()`, `lexer.get_indent_amount()`, `lexer.get_property()`, and
+ `lexer.get_style_at()` functions to be [`lexer.fold_level`][], [`lexer.indent_amount`][],
+ [`lexer.property`][], and [`lexer.style_at`][] tables, respectively.
* Added [`lexer.property_int`][] and [`lexer.property_expanded`][] tables.
* Changed API for [`lexer.delimited_range()`][] and [`lexer.nested_pair()`][].
-* Only enable `fold.by.indentation` property by default in
- whitespace-significant languages.
+* Only enable `fold.by.indentation` property by default in whitespace-significant languages.
[`events.disconnect()`]: api.html#events.disconnect
[`_CHARSET`]: api.html#_CHARSET
@@ -1999,8 +1878,7 @@ Changes:
Bugfixes:
-* User functions that connect to `events.BUFFER_NEW` and `events.VIEW_NEW` are
- run on startup.
+* User functions that connect to `events.BUFFER_NEW` and `events.VIEW_NEW` are run on startup.
* Fixed potential crash caused by split views.
Changes:
@@ -2012,9 +1890,9 @@ Changes:
* New [`events.INITIALIZED`][] event.
* Renamed `buffer:get_style_name()` to `buffer.style_name`.
* Renamed `ui.docstatusbar_text` to `ui.bufstatusbar_text`.
-* Removed `textadept.bookmarks.BOOKMARK_COLOR`,
- `textadept.editing.HIGHLIGHT_COLOR`, and `textadept.run.ERROR_COLOR` while
- exposing their respective marker and indicator numbers for customization.
+* Removed `textadept.bookmarks.BOOKMARK_COLOR`, `textadept.editing.HIGHLIGHT_COLOR`, and
+ `textadept.run.ERROR_COLOR` while exposing their respective marker and indicator numbers
+ for customization.
* Moved buffer IO functions into [`io` module][].
* Updated to [CDK][] 5.0-20130901.
@@ -2056,8 +1934,7 @@ Bugfixes:
Changes:
* Renamed `_M.textadept.mime_types` to [`_M.textadept.file_types`][].
-* Eliminated *mime_types.conf* files. Add or modify file type tables
- [directly][].
+* Eliminated *mime_types.conf* files. Add or modify file type tables [directly][].
* Changed scrollbar look and feel on Mac OSX.
[`_M.textadept.file_types`]: api.html#textadept.file_types
@@ -2074,17 +1951,15 @@ Bugfixes:
Changes:
-* Makefile improvements. See [compiling][] for more information. The source
- release is no longer necessary.
+* Makefile improvements. See [compiling][] for more information. The source release is no
+ longer necessary.
* Removed `_G._LEXERPATH` and `_L._EXISTS()`.
* Renamed Adeptsense image fields.
-* Renamed `_M.textadept.editing.STRIP_WHITESPACE_ON_SAVE` to
- `STRIP_TRAILING_SPACES`.
+* Renamed `_M.textadept.editing.STRIP_WHITESPACE_ON_SAVE` to `STRIP_TRAILING_SPACES`.
* `_M.textadept.editing.block_comment()` supports block comment delimiters.
-* Block comments for languages is now built-in. The supplemental ones on the
- wiki are no longer needed.
-* `gui.set_theme()` accepts key-value argument pairs for overriding theme
- properties.
+* Block comments for languages is now built-in. The supplemental ones on the wiki are no
+ longer needed.
+* `gui.set_theme()` accepts key-value argument pairs for overriding theme properties.
* Removed `gui.select_theme()` since selected themes do not persist.
* Removed `_G.RESETTING` flag.
* Consolidated `_M.textadept.bookmarks.goto_*()` functionality into
@@ -2151,8 +2026,8 @@ Bugfixes:
Changes:
-* Textadept supports multiple curses platforms, not just ncurses. Make targets
- now use "curses" instead of "ncurses".
+* Textadept supports multiple curses platforms, not just ncurses. Make targets now use "curses"
+ instead of "ncurses".
* Better 16-color terminal support in lexer theme.
* Reduced the delay when pressing `Esc` in the terminal version.
* [Messagebox][] dialogs can show icons via `--icon` and `--icon-file`.
@@ -2164,12 +2039,12 @@ Changes:
* Changed the display of highlighted words, including removing
`_M.textadept.editing.INDIC_HIGHLIGHT_ALPHA`.
* Changed `_M.textadept.editing.autocomplete_word()` API.
-* Removed `_M.textadept.menu.menubar`, `_M.textadept.menu.contextmenu`, and
- `events.handlers` tables from the API.
+* Removed `_M.textadept.menu.menubar`, `_M.textadept.menu.contextmenu`, and `events.handlers`
+ tables from the API.
* Moved `_M.textadept.filter_through` module functionality into
[`_M.textadept.editing.filter_through()`][].
-* Mark errors in compile/run commands and added
- [`_M.textadept.run.goto_error()`][] menu options and key shortcuts.
+* Mark errors in compile/run commands and added [`_M.textadept.run.goto_error()`][] menu options
+ and key shortcuts.
* Renamed `gui.find.goto_file_in_list()` to [`gui.find.goto_file_found()`][].
* Consolidated `_M.textadept.editing.grow_selection()` functionality into
[`_M.textadept.editing.select_enclosed()`][].
@@ -2193,15 +2068,15 @@ Bugfixes:
* Only consider visible directories in *_USERHOME/themes/* as themes.
* Indicator for highlighted words works in ncurses.
-* Improved message double-clicking behavior for compile and run commands by
- adding `_M.textadept.run.cwd`.
+* Improved message double-clicking behavior for compile and run commands by adding
+ `_M.textadept.run.cwd`.
* Fixed disorienting scrolling when wrapping only one search result.
* Fixed crash when attempting to load a non-existant lexer.
* Fixed CSS preprocessor styling.
* Fixed labels for inputbox dialogs.
* Scintilla: fixed some instances of incorrect folded text display.
-* Scintilla: fixed `buffer:visible_from_doc_line()` to never return a line
- beyond the end of the buffer.
+* Scintilla: fixed `buffer:visible_from_doc_line()` to never return a line beyond the end of
+ the buffer.
* Scintilla: fixed `buffer:line_scroll()` for negative columns.
* Scintilla: fixed tab marker display when indentation lines are visible.
@@ -2254,14 +2129,13 @@ Bugfixes:
* Scintilla: fixed pasting with NULL bytes.
* Scintilla: autocompletion should only have one undo step.
* Scintilla: fixed crash when drawing very long lines.
-* Scintilla: fixed unexpected collapse of selections when extending by
- character.
+* Scintilla: fixed unexpected collapse of selections when extending by character.
Changes:
* Use Scintilla API for ncurses mark mode.
-* Scintilla: added [`buffer.caret_line_visible_always`][] for showing the caret
- line despite not having focus.
+* Scintilla: added [`buffer.caret_line_visible_always`][] for showing the caret line despite
+ not having focus.
* Updated to [Scintilla][] 3.2.4.
* Added [typeover characters][].
@@ -2309,8 +2183,7 @@ Changes:
### 6.0 (01 Nov 2012)
-Please see the [5 to 6 migration guide][] for upgrading from Textadept 5 to
-Textadept 6.
+Please see the [5 to 6 migration guide][] for upgrading from Textadept 5 to Textadept 6.
Bugfixes:
@@ -2322,11 +2195,9 @@ Bugfixes:
* Pass `Esc` to Scintilla correctly in ncurses.
* Fix errors when specifying directories and files for file dialogs.
* Fixed some operators in Bash lexer.
-* Scintilla: fixed hang when removing all characters from an indicator at the
- the end of a buffer.
+* Scintilla: fixed hang when removing all characters from an indicator at the the end of a buffer.
* Scintilla: fixed crash when drawing margins in GTK 3.
-* Scintilla: do not draw spaces after an italic style at the end of a line in
- the terminal version.
+* Scintilla: do not draw spaces after an italic style at the end of a line in the terminal version.
Changes:
@@ -2369,8 +2240,7 @@ Changes:
* Key Bindings reference moved from Appendix to [`_M.textadept.keys`][] LuaDoc.
* Plain text lexer name changed from `container` to `text`.
* New application icon.
-* Removed `./?.lua` and `./?.so` from `package.path` and `package.cpath`,
- respectively.
+* Removed `./?.lua` and `./?.so` from `package.path` and `package.cpath`, respectively.
* Added marks for making selections in ncurses.
[`_M.textadept.keys`]: api.html#textadept.keys
@@ -2391,18 +2261,16 @@ Changes:
* Added `make install` and `make uninstall` rules for optional installation.
* Updated manual with ncurses key bindings.
-* Consolidated `_M.textadept.bookmarks.add()` and
- `_M.textadept.bookmarks.remove()` into [`_M.textadept.bookmarks.toggle()`][].
+* Consolidated `_M.textadept.bookmarks.add()` and `_M.textadept.bookmarks.remove()` into
+ [`_M.textadept.bookmarks.toggle()`][].
* Updated manual images.
-* `_M.textadept.snapopen.DEFAULT_DEPTH` is now `99` since `MAX` is the limiting
- factor.
+* `_M.textadept.snapopen.DEFAULT_DEPTH` is now `99` since `MAX` is the limiting factor.
* Use constant names in theme options instead of nondescript integers.
-* Added new [`lexer.last_char_includes()`][] function for better regex
- detection.
+* Added new [`lexer.last_char_includes()`][] function for better regex detection.
* Updated AWK lexer.
* Scintilla: added [`buffer.selection_empty`][].
-* Scintilla: added [`buffer:vc_home_display()`][] and
- [`buffer:vc_home_display_extend()`][] for navigating wrapped lines.
+* Scintilla: added [`buffer:vc_home_display()`][] and [`buffer:vc_home_display_extend()`][]
+ for navigating wrapped lines.
* Updated to [Scintilla][] 3.2.2.
[`_M.textadept.bookmarks.toggle()`]: api.html#textadept.bookmarks.toggle
@@ -2418,14 +2286,13 @@ Bugfixes:
* Lots of bugfixes to the experimental ncurses version.
* Fixed bug with `$$` variables in Perl lexer.
-* Scintilla: do not show empty autocompletion list if
- `buffer.auto_c_choose_single` is set.
+* Scintilla: do not show empty autocompletion list if `buffer.auto_c_choose_single` is set.
* Scintilla: fixed `buffer:marker_delete()` to only delete one marker per call.
* Scintilla: fixed caret positioning after undoing multiple deletions.
* Scintilla: fixed margin drawing after `buffer.margin_style` is altered.
* Scintilla: fixed margin click handling.
-* Scintilla: fixed hang when drawing block carets on a zero-width space at the
- beginning of a buffer.
+* Scintilla: fixed hang when drawing block carets on a zero-width space at the beginning of
+ a buffer.
* Scintilla: fixed crash deleting negative ranges.
* Scintilla: fixed drawing of overlapping characters.
@@ -2433,12 +2300,12 @@ Changes:
* Removed Lua, Ruby, and PHP modules' `goto_required()` functions.
* Moved `_M.textadept.editing.prepare_for_save()` directly into event handler.
-* Moved `_M.textadept.session.prompt_load()` and `prompt_save()` functionality
- into [`_M.textadept.session.load()`][] and [`_M.textadept.session.save()`][].
+* Moved `_M.textadept.session.prompt_load()` and `prompt_save()` functionality into
+ [`_M.textadept.session.load()`][] and [`_M.textadept.session.save()`][].
* Removed `_G.user_dofile()`.
* Converted some `buffer` "get" and "set" functions into properties.
-* Moved `_M.textadept.adeptsense.complete_symbol()` and `show_documentation()`
- functionality into `_M.textadept.adeptsense.complete()` and `show_apidoc()`.
+* Moved `_M.textadept.adeptsense.complete_symbol()` and `show_documentation()` functionality into
+ `_M.textadept.adeptsense.complete()` and `show_apidoc()`.
* New 64-bit Windows version (note: without LuaJIT).
* Updated Perl lexer.
* Scintilla: added [`buffer.punctuation_chars`][], [`buffer.word_chars`][], and
@@ -2485,8 +2352,7 @@ Bugfixes:
* Scintilla: fixed boxed annotation drawing.
* Scintilla: fixed virtual space selection bug in rectangular selections.
-* Scintilla: replacing multiple selections with newlines is a single undo
- action.
+* Scintilla: replacing multiple selections with newlines is a single undo action.
* Scintilla: fixed autocompletion list height in GTK 3.
* Scintilla: fixed mouse scrolling due to recent GTK changes.
@@ -2494,11 +2360,10 @@ Changes:
* Identify more file extensions.
* Updated Batch lexer.
-* Scintilla: `Ctrl+Double Click` and `Ctrl+Triple Click` adds words and lines,
- respectively, to selections.
+* Scintilla: `Ctrl+Double Click` and `Ctrl+Triple Click` adds words and lines, respectively,
+ to selections.
* Scintilla: added [`buffer:delete_range()`][] for deleting ranges of text.
-* Scintilla: added `buffer.WRAPVISUALFLAG_MARGIN` for drawing wrap markers in
- margins.
+* Scintilla: added `buffer.WRAPVISUALFLAG_MARGIN` for drawing wrap markers in margins.
* Scintilla: improved UTF-8 validity checks.
* Updated to [Scintilla][] 3.2.0.
@@ -2525,8 +2390,8 @@ Changes:
* Textadept is [single-instance][] by default on Linux and Mac OSX.
* Textadept requires [GTK][] 2.18 or higher now instead of 2.16.
* The provided Textadept binaries [require][] [GLib][] 2.28 or higher.
-* Scintilla: added `buffer.auto_c_case_insensitive_behaviour` for
- controlling case sensitivity in autocompletion lists.
+* Scintilla: added `buffer.auto_c_case_insensitive_behaviour` for controlling case sensitivity
+ in autocompletion lists.
* Scintilla: `\0` in regex replacements represents the full found text.
* Updated to [Scintilla][] 3.1.0.
@@ -2603,8 +2468,7 @@ Bugfixes:
Changes:
-* Added default extension and folder filters in
- `modules/textadept/snapopen.lua`.
+* Added default extension and folder filters in `modules/textadept/snapopen.lua`.
* Added ChucK lexer.
* Updated Lua lexer.
* Updated to [Scintilla][] 3.0.3.
@@ -2622,8 +2486,7 @@ Bugfixes:
Changes:
-* Changed `locale.localize()` to global [`_L`][] table and removed `locale`
- module.
+* Changed `locale.localize()` to global [`_L`][] table and removed `locale` module.
* Renamed `_m` to [`_M`][].
* Do not clear registered images when autocompleting with Adeptsense.
* Renamed editing module's `current_word()` to [`select_word()`][].
@@ -2718,8 +2581,7 @@ Changes:
* Added language-specific [context menu][] support.
* Use [LuaCoco][] patch for Lua 5.1.4.
* Use lexer at the caret for key bindings and snippets.
-* Added `selected` and `monospaced-font` options for dropdown and textbox
- dialogs, respectively.
+* Added `selected` and `monospaced-font` options for dropdown and textbox dialogs, respectively.
* Updated to [Scintilla][] 2.29.
[dwell events]: api.html#events
@@ -2734,8 +2596,7 @@ Changes:
### 4.0 (01 Sep 2011)
-Please see the [3 to 4 migration guide][] for upgrading from Textadept 3 to
-Textadept 4.
+Please see the [3 to 4 migration guide][] for upgrading from Textadept 3 to Textadept 4.
Bugfixes:
@@ -2781,8 +2642,7 @@ Bugfixes:
* Fixed bug when setting both dialog with and height.
* Scintilla: fixed incorrect mouse cursor changes.
* Scintilla: fixed bug with annotations beyond the document end.
-* Scintilla: fixed incorrect drawing of background colors and translucent
- selection.
+* Scintilla: fixed incorrect drawing of background colors and translucent selection.
* Scintilla: fixed lexer initialization.
* Scintilla: fixed some instances of fold highlight drawing.
* Scintilla: fixed some cases of case insensitive searching.
@@ -2792,16 +2652,14 @@ Changes:
* Mac OSX uses GTK 2.24.
* Added [`io.open_recent_file()`][].
* Changes to localization file again.
-* [`buffer`][] functions may omit the first `buffer` argument (e.g.
- `buffer.line_down()` is allowed).
+* [`buffer`][] functions may omit the first `buffer` argument (e.g.n `buffer.line_down()`
+ is allowed).
* Complete overhaul of menus and added accelerators to [menu][] items.
* Renamed `_m.textadept.editing.SAVE_STRIPS_WS` to
[`_m.textadept.editing.STRIP_WHITESPACE_ON_SAVE`][].
-* Renamed `_m.textadept.editing.select_scope()` to
- `_m.textadept.editing.select_style()`.
+* Renamed `_m.textadept.editing.select_scope()` to `_m.textadept.editing.select_style()`.
* *Completely new set of key bindings.*
-* Scintilla: translucent RGBA images can be used in margins and autocompletion
- and user lists.
+* Scintilla: translucent RGBA images can be used in margins and autocompletion and user lists.
* Scintilla: added new `buffer.INDIC_DOTBOX` indicator.
* Scintilla: IME input now works.
* Scintilla: `Ctrl+Shift+U` used for Unicode input.
@@ -2832,10 +2690,10 @@ Changes:
* Added support for [GTK][] 3.0.
* Use ID generator [functions][] for marker, indicator, and user list IDs.
-* Scintilla: added [`buffer:set_empty_selection()`][] for setting selections
- without scrolling or redrawing.
-* Scintilla: added new `buffer.INDIC_DASH`, `buffer.INDIC_DOTS`, and
- `buffer.INDIC_SQUIGGLELOW` indicators.
+* Scintilla: added [`buffer:set_empty_selection()`][] for setting selections without scrolling
+ or redrawing.
+* Scintilla: added new `buffer.INDIC_DASH`, `buffer.INDIC_DOTS`, and `buffer.INDIC_SQUIGGLELOW`
+ indicators.
* Scintilla: added option to allow margin clicks to select wrapped lines.
* Updated to [Scintilla][] 2.27.
* Use string constants for event names.
@@ -2845,8 +2703,7 @@ Changes:
* Use [GTK][] 2.22 on Windows.
* Can localize the labels and buttons in the GUI [find][] frame.
* Added ConTeXt lexer and updated Coffeescript, HTML, LaTeX, and TeX lexers.
-* Multiple single-line comments can be folded with the `fold.line.comments`
- property set to `1`.
+* Multiple single-line comments can be folded with the `fold.line.comments` property set to `1`.
[GTK]: https://gtk.org
[functions]: api.html#_SCINTILLA
@@ -2882,8 +2739,8 @@ Changes:
* Scintilla: improved text drawing and measuring.
* Updated to [Scintilla][] 2.26.
* Writing custom folding for lexers is much [easier][] now.
-* Added native folding for more than 60% of existing lexers. The rest still use
- folding by indentation by default.
+* Added native folding for more than 60% of existing lexers. The rest still use folding by
+ indentation by default.
* Added regex support for Coffeescript lexer.
* Embed Coffeescript lexer in HTML lexer.
@@ -2921,25 +2778,23 @@ Changes:
* Language modules load a user `post_init.lua` script if it exists.
* Added Ruby on Rails lexer and module.
* Added RHTML module.
-* Updated mime-types and prioritize by shebang, pattern, and then file
- extension.
+* Updated mime-types and prioritize by shebang, pattern, and then file extension.
* `buffer:get_lexer(true)` returns the lexer at the caret position.
* Adeptsense can be triggered in embedded lexers now.
* Added C standard library and Lua C API to C/C++ Adeptsense.
* Lua module fields are now in Lua Adeptsense.
* Updated to [Scintilla][] 2.25.
* Rewrote [`_m.textadept.snippets`][] with syntax changes.
-* `Alt+I` (`Ctrl+I` on Mac OSX) is now "Select Snippet" instead of "Show Style".
- "Show Style" is now `Ctrl+Alt+Shift+I` (`Ctrl+Apple+Shift+I`).
-* Adeptsense can exclude types matched by `sense.syntax.type_declarations`
- patterns.
-* `Ctrl+T, V` (`Apple+T, V` on Mac OSX) keychain for toggling whitespace, wrap,
- etc. is now `Ctrl+Shift+B` (`Apple+Shift+B`).
+* `Alt+I` (`Ctrl+I` on Mac OSX) is now "Select Snippet" instead of "Show Style". "Show Style"
+ is now `Ctrl+Alt+Shift+I` (`Ctrl+Apple+Shift+I`).
+* Adeptsense can exclude types matched by `sense.syntax.type_declarations` patterns.
+* `Ctrl+T, V` (`Apple+T, V` on Mac OSX) keychain for toggling whitespace, wrap, etc. is now
+ `Ctrl+Shift+B` (`Apple+Shift+B`).
* Key bindings and menu definition syntax changed.
* Snapopen allows for multiple-selection.
* `gui.print()` handles `nil` and non-string arguments properly.
-* Officially supported modules have their own [repository][] and are available
- as a separate download.
+* Officially supported modules have their own [repository][] and are available as a separate
+ download.
* Added cancel button to standard dialogs.
[Scintilla]: https://scintilla.org
@@ -2976,12 +2831,11 @@ Changes:
* Added class context completion to Adeptsense.
* Added class type-inference through variable assignment to Adeptsense.
* Added Adeptsense tutorial.
-* Added `_m.textadept.adeptsense.always_show_globals` setting for showing
- globals in completion lists.
+* Added `_m.textadept.adeptsense.always_show_globals` setting for showing globals in completion
+ lists.
* `Ctrl+H` (highlight word) is now `Ctrl+Shift+H`.
* `Ctrl+H` now shows Adeptsense documentation.
-* Added Adeptsense `complete()` and `show_documentation()` functions to the
- menu.
+* Added Adeptsense `complete()` and `show_documentation()` functions to the menu.
* Language modules condensed into single `init.lua` file.
* Added `sense.syntax.word_chars` to Adeptsense.
* Included libpng12 build for 64-bit Debian-based Linux distros (Ubuntu).
@@ -3029,8 +2883,7 @@ Changes:
* `buffer.rectangular_selection_modifier` on Linux is the Super/Windows key.
* Improved HTML lexer.
-* Added Markdown, BibTeX, CMake, CUDA, Desktop Entry, F#, GLSL, and Nemerle
- lexers.
+* Added Markdown, BibTeX, CMake, CUDA, Desktop Entry, F#, GLSL, and Nemerle lexers.
* Added [`_m.textadept.filter_through`][] module for [shell commands][].
* Moved GUI events from `core/events.lua` to `core/gui.lua`.
* Separated key command manager from key command definitions.
@@ -3050,8 +2903,7 @@ Changes:
* Lua files are syntax-checked for errors on save.
* [Menus][] are easier to create.
* Changed `_m.textadept.editing.enclose()` behavior.
-* Win32 and Mac OSX packages are all-in-one bundles; GTK is no longer an
- external dependency.
+* Win32 and Mac OSX packages are all-in-one bundles; GTK is no longer an external dependency.
* New [manual][].
* Added [`file_after_save`][] event.
@@ -3064,45 +2916,38 @@ Changes:
Bugfixes:
* Fixed menu item conflicts.
-* Pressing `Cancel` in the [Switch Buffers][] dialog does not jump to the
- selected buffer anymore.
+* Pressing `Cancel` in the [Switch Buffers][] dialog does not jump to the selected buffer anymore.
* Autocomplete lists sort properly for machines with a different locale.
* Statusbar is not cleared when set from a key command.
* Unreadable files are handled appropriately.
* Scintilla: fixed scrolling bug where caret was not kept visible.
* Scintilla: fixed caret position caching after autocompletion.
* Scintilla: fixed paging up/down in virtual space.
-* Scintilla: fixed crash with negative arguments passed to
- `buffer:marker_add()` and `buffer:marker_add_set()`.
-* Scintilla: dwell notifications are not emitted when the mouse is outside the
- view.
+* Scintilla: fixed crash with negative arguments passed to `buffer:marker_add()` and
+ `buffer:marker_add_set()`.
+* Scintilla: dwell notifications are not emitted when the mouse is outside the view.
Changes:
-* Multi-language lexers (HTML, PHP, RHTML, etc.) are processed as fast as single
- language ones, resulting in a huge speed improvement.
+* Multi-language lexers (HTML, PHP, RHTML, etc.) are processed as fast as single language ones,
+ resulting in a huge speed improvement.
* An `update_ui` event is triggered after a Lua command is entered.
* `gui.dialog()` can take tables of strings as arguments now.
-* [`_m.textadept.snapopen.open()`][] takes a recursion depth as a parameter and
- falls back on a `DEFAULT_DEPTH` if necessary.
-* Removed `_m.textadept.editing.smart_cutcopy()` and
- `_m.textadept.editing.squeeze()` functions.
-* Added `_m.textadept.editing.SAVE_STRIPS_WS` option to disable strip whitespace
- on save.
+* [`_m.textadept.snapopen.open()`][] takes a recursion depth as a parameter and falls back on a
+ `DEFAULT_DEPTH` if necessary.
+* Removed `_m.textadept.editing.smart_cutcopy()` and `_m.textadept.editing.squeeze()` functions.
+* Added `_m.textadept.editing.SAVE_STRIPS_WS` option to disable strip whitespace on save.
* Changed locale implementation. Locale files are much easier to create now.
* `gui.statusbar_text` is now readable instead of being write-only.
* Can [highlight][] all occurances of a word.
* Added jsp lexer.
* More consistant handling of `\` directory separator for Win32.
-* Consolidated `textadept.h` and `lua_interface.c` into single `textadept.c`
- file.
-* Added [`_G.timeout()`][] function for calling functions and/or events after a
- period of time.
+* Consolidated `textadept.h` and `lua_interface.c` into single `textadept.c` file.
+* Added [`_G.timeout()`][] function for calling functions and/or events after a period of time.
* Find in files is accessible through [find API][].
* Updated XML lexer.
* Added `search-column` and `output-column` options for filteredlist dialogs.
-* Scintilla: added [`buffer:contracted_fold_next()`][] for retrieving fold
- states.
+* Scintilla: added [`buffer:contracted_fold_next()`][] for retrieving fold states.
* Scintilla: added `buffer:vertical_centre_caret()`.
* Updated to [Scintilla][] 2.22.
* Renamed `_G.MAC` to [`_G.OSX`][].
@@ -3125,8 +2970,7 @@ Bugfixes:
Changes:
-* Added [`_m.textadept.snapopen`][] module with menu options for rapidly opening
- files.
+* Added [`_m.textadept.snapopen`][] module with menu options for rapidly opening files.
* Added coffeescript lexer.
* Updated D and Java lexers.
@@ -3154,8 +2998,7 @@ Bugfixes:
* Fixed memory leak in Mac OSX.
* Scintilla: fixed crash when searching for empty strings.
-* Scintilla: fixed lexing and folding bugs when pressing enter at the beginning
- of a line.
+* Scintilla: fixed lexing and folding bugs when pressing enter at the beginning of a line.
* Scintilla: fixed bug in line selection mode.
* Scintilla: fixed alpha indicator value ranges.
* Scintilla: fixed compiler errors for some compilers.
@@ -3175,8 +3018,7 @@ Changes:
### 3.0 (01 Jul 2010)
-Please see the [2 to 3 migration guide][] for upgrading from Textadept 2 to
-Textadept 3.
+Please see the [2 to 3 migration guide][] for upgrading from Textadept 2 to Textadept 3.
Bugfixes:
@@ -3202,8 +3044,7 @@ Bugfixes:
* Scintilla: fixed selection bounds returned for rectangular selections.
* Scintilla: fixed case-insensitive searching for non-ASCII characters.
* Scintilla: fixed bad-UTF-8 byte handling.
-* Scintilla: fixed bug when rectangular selections were extended into multiple
- selections.
+* Scintilla: fixed bug when rectangular selections were extended into multiple selections.
* Scintilla: fixed incorrect caret placement after scrolling.
* Scintilla: fixed text disappearing after wrapping bug.
* Scintilla: fixed various regex search bugs.
@@ -3216,11 +3057,9 @@ Changes:
* Moved core extension modules into [`textadept`][] module.
* New [API][].
* `~/.textadept/init.lua` is created for you if one does not exist.
-* No more autoload of `~/.textadept/key_commands.lua` and
- `~/.textadept/snippets.lua`
+* No more autoload of `~/.textadept/key_commands.lua` and `~/.textadept/snippets.lua`
* Updated Java and D lexers.
-* Scintilla: added [`buffer.multi_paste`][] for pasting into multiple
- selections.
+* Scintilla: added [`buffer.multi_paste`][] for pasting into multiple selections.
* Updated to [Scintilla][] 2.12.
* [Abbreviated][] Lua commands in the command entry.
* Dynamic command line [arguments][].
@@ -3244,8 +3083,7 @@ Bugfixes:
Changes:
-* `_USERHOME` comes before `_HOME` in `package.path` so `require` searches
- `~/.textadept/` first.
+* `_USERHOME` comes before `_HOME` in `package.path` so `require` searches `~/.textadept/` first.
### 2.2 beta 2 (01 May 2010)
@@ -3286,14 +3124,13 @@ Bugfixes:
Changes:
-* Removed `_m.textadept.mlines` module since Scintilla's multiple selections
- supercedes it.
+* Removed `_m.textadept.mlines` module since Scintilla's multiple selections supercedes it.
* Removed side pane.
* New [`gui.dialog('filteredlist', ...)][] from [gtdialog][].
* Can select buffer from filteredlist dialog (replacing side pane buffer list).
* Can select lexer from filteredlist dialog.
-* Can have user `key_commands.lua`, `snippets.lua`, `mime_types.conf`,
- `locale.conf` that are loaded by their respective modules.
+* Can have user `key_commands.lua`, `snippets.lua`, `mime_types.conf`, `locale.conf` that are
+ loaded by their respective modules.
* Added Matlab/Octave lexer and updated Haskell lexer.
* Backspace deletes auto-inserted character pairs.
* Added notification for session files not found.
@@ -3313,14 +3150,11 @@ Bugfixes:
* Fixed key command for word autocomplete on Win32.
* Changed conflicting menu shortcut for Lexers menu.
* Fixed typos in templates generated by modules PM browser.
-* Scintilla: fixed crash after adding an annotation and then adding a new line
- below it.
+* Scintilla: fixed crash after adding an annotation and then adding a new line below it.
* Scintilla: fixed `buffer:get_sel_text()`.
* Scintilla: fixed some instances of text positioning.
-* Scintilla: fixed various problems with rectangular selections and rectangular
- pastes.
-* Scintilla: fixed some instances of navigation through and display of wrapped
- lines.
+* Scintilla: fixed various problems with rectangular selections and rectangular pastes.
+* Scintilla: fixed some instances of navigation through and display of wrapped lines.
* Scintilla: fixed drag and drop.
* Scintilla: fixed extra background styling at the end of the buffer.
* Scintilla: fixed crash when adding markers to non-existant lines.
@@ -3332,16 +3166,14 @@ Changes:
* Search `_USERHOME` in addition to `_HOME` for themes.
* Added command line option for not loading/saving session.
* Modified key bindings to be more key-layout agnostic.
-* Added `reset_before` and `reset_after` events while `textadept.reset()` is
- being run.
+* Added `reset_before` and `reset_after` events while `textadept.reset()` is being run.
* Reload current lexer module after `textadept.reset()`.
* Added `~/.textadept/modules/` to `package.path`.
* Scintilla: added support for multiple selections and virtual space.
* Scintilla: `buffer.first_visible_line` is no longer read-only.
-* Scintilla: added [`buffer.whitespace_size`][] for changing the size of visible
- whitespace.
-* Scintilla: added [`buffer.auto_c_current_text`][] for retrieving the currently
- selected autocompletion text.
+* Scintilla: added [`buffer.whitespace_size`][] for changing the size of visible whitespace.
+* Scintilla: added [`buffer.auto_c_current_text`][] for retrieving the currently selected
+ autocompletion text.
* Updated to [Scintilla][] 2.03.
* Modified quit and close dialogs to be more readable.
@@ -3379,27 +3211,23 @@ Bugfixes:
* Alphabetize lexer list.
* Fixed some locale issues.
* Fixed some small memory leaks.
-* Try a [list of encodings][] rather than just UTF-8 so "conversion failed" does
- not happen so often.
+* Try a [list of encodings][] rather than just UTF-8 so "conversion failed" does not happen
+ so often.
* Restore a manually set lexer.
Changes:
-* Removed `_m.textadept.macros` module and respective PM browser (use Lua
- instead).
-* Linux version can be installed and run from anywhere; no need to recompile
- anymore.
+* Removed `_m.textadept.macros` module and respective PM browser (use Lua instead).
+* Linux version can be installed and run from anywhere; no need to recompile anymore.
* Added many more [events][] to hook into lots of core functionality.
* Updated to [Scintilla][] 1.79.
* Run module allows more flexible [compile commands][] and [run commands][].
* Save project manager cursor over sessions.
-* Allow mime-types and compile and run commands to be user-redefinable in user
- scripts.
+* Allow mime-types and compile and run commands to be user-redefinable in user scripts.
* Use `~/.textadept/` for holding user lexers, themes, sessions, etc.
* Added "Help" menu linking to Manual and LuaDoc.
* Textadept compiles as C99 code. (Drops Microsoft Visual Studio support.)
-* Sessions functionality moved to `modules/textadept/session.lua` from
- `core/file_io.lua`.
+* Sessions functionality moved to `modules/textadept/session.lua` from `core/file_io.lua`.
* The `char_added` event now passes an int, not a string, to handler functions.
* Replaced [cocoaDialog][] and [lua_dialog][] with my C-based [gtdialog][].
* [Incremental find][] via the Lua command entry.
@@ -3428,8 +3256,7 @@ Changes:
Bugfixes:
-* Fixed `NULL` byte bug associated with Lua interface due to multi-encoding
- support.
+* Fixed `NULL` byte bug associated with Lua interface due to multi-encoding support.
* Find marker is colored consistently.
* Fixed issue with buffer browser cursor saving.
* Fixed block character insertion issue on GTK-OSX.
@@ -3474,8 +3301,7 @@ Bugfixes:
Updates:
-* Consolidated *core/ext/key_commands_{std,mac}.lua* into single
- *core/ext/key_commands.lua*.
+* Consolidated *core/ext/key_commands_{std,mac}.lua* into single *core/ext/key_commands.lua*.
* Can use the `Tab` and `Shift+Tab` keys for snippets now.
* Removed support for Textmate-style snippets in favor of Lua-style snippets.
* Load drag-and-dropped directories into file browser.
@@ -3513,8 +3339,7 @@ Updates:
Bugfixes:
* Binary files are opened and handled properly.
-* Drag-and-dropped files are now opened in the correct split view they were
- dropped in.
+* Drag-and-dropped files are now opened in the correct split view they were dropped in.
* Fixed some various GTK-OSX UI issues.
* Fixed a special case of "Replace All".
* Clicking "Ok" closes any error dialogs on init.
@@ -3546,9 +3371,8 @@ Bugfixes:
Updates:
* Windows command line support ("Open With Textadept" works too).
-* New [`_m.textadept.run`][] module for compiling and running programs. Output
- is displayed in a message buffer and you can double-click errors and warnings
- to go to them in the source file.
+* New [`_m.textadept.run`][] module for compiling and running programs. Output is displayed in
+ a message buffer and you can double-click errors and warnings to go to them in the source file.
[`_m.textadept.run`]: api.html#textadept.run
@@ -3563,8 +3387,7 @@ Updates:
* Dramatic speed increase in lexing for large, single-language files.
* Added [localization][] support.
* Added [bookmarks][] support.
-* All `require` statements have been moved to *init.lua* for easy module
- configuration.
+* All `require` statements have been moved to *init.lua* for easy module configuration.
* Various improvements to efficiency, speed, and readability of source code.
* Manually parse *~/.gtkrc-2.0* on Mac since GTK-OSX does not do it.
@@ -3611,8 +3434,8 @@ Updates:
* Some C++ API-simplifying changes.
* Drag-and-drop files into Textadept works as expected.
* Revised [manual][].
-* Buffer and View properties are no longer set in C++, but in Lua through
- "buffer_new" and "view_new" event handlers respectively.
+* Buffer and View properties are no longer set in C++, but in Lua through "buffer_new" and
+ "view_new" event handlers respectively.
* File types can be recognized by [pattern matching][] the first line.
[Theming]: manual.html#themes
@@ -3629,8 +3452,7 @@ Updates:
* Added user-friendly key bindings and menus.
* Added 43 more lexers.
-* Moved block-comment commands from language modules to `textadept.editing`
- module.
+* Moved block-comment commands from language modules to `textadept.editing` module.
* Updated some Luadoc.
### 0.4 (25 Jun 2008)
@@ -3643,12 +3465,10 @@ Bugfixes:
Updates:
-* Added [bookmark][] support through *modules/textadept/bookmarks.lua* (not
- loaded by default).
+* Added [bookmark][] support through *modules/textadept/bookmarks.lua* (not loaded by default).
* Added icons to Textadept.
* Added a modules browser for adding, deleting, and editing modules easily.
-* Consolidated source files into *textadept.c*, *textadept.h*, and
- *lua_interface.c*.
+* Consolidated source files into *textadept.c*, *textadept.h*, and *lua_interface.c*.
* Always load project manager settings from session file if available.
* Include *liblua5.1.a* for compiling Lua into Textadept.
* Added true [tab-completion][] to Lua command entry.
diff --git a/docs/faq.md b/docs/faq.md
index 789e3bec..445fc413 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,61 +1,55 @@
## FAQ
**Q:**
-If Textadept is so minimalist, why are the downloads around 10MB in size and the
-unzipped folders 10s of MBs in size? Why is the Git repository more than 50MB in
-size?
+If Textadept is so minimalist, why are the downloads around 10MB in size and the unzipped
+folders 10s of MBs in size? Why is the Git repository more than 50MB in size?
**A:**
-Each download contains 2 executables: a GUI version and a terminal version.
-Furthermore, the Windows and macOS packages bundle in GTK runtimes, accounting
-for some 3/4 of the total application size. (GTK is the cross-platform GUI
-toolkit Textadept uses.) Then, starting in version 10, in order to be able to
-run on older Linux systems whose libstdc++ does not support newer C++ symbols,
-the Linux executables statically link in a newer version of libstdc++. Finally,
-nightly builds are compiled with debug symbols enabled in order to aid debugging
-of various issues.
-
-The Git repository is an export of an underlying Mercurial repository and is not
-compressed or optimized for size. After the initial clone, you can run
-`git gc --aggressive` to reduce its footprint to about a third of the original
-size.
+Each download contains 2 executables: a GUI version and a terminal version. Furthermore,
+the Windows and macOS packages bundle in GTK runtimes, accounting for some 3/4 of the total
+application size. (GTK is the cross-platform GUI toolkit Textadept uses.) Then, starting in
+version 10, in order to be able to run on older Linux systems whose libstdc++ does not support
+newer C++ symbols, the Linux executables statically link in a newer version of libstdc++. Finally,
+nightly builds are compiled with debug symbols enabled in order to aid debugging of various issues.
+
+The Git repository is an export of an underlying Mercurial repository and is not compressed or
+optimized for size. After the initial clone, you can run `git gc --aggressive` to reduce its
+footprint to about a third of the original size.
- - -
**Q:**
-On Linux I either get one of the following error messages when trying to run
-Textadept, or I get odd behavior in the terminal version, even crashes.
+On Linux I either get one of the following error messages when trying to run Textadept, or I
+get odd behavior in the terminal version, even crashes.
-* `error while loading shared libraries: <lib>: cannot open shared object
- file: No such file or directory`
+* `error while loading shared libraries: <lib>: cannot open shared object file: No such file
+ or directory`
* `/<path>/libc.so.6: version 'GLIBC_<version>' not found`
How do I fix this?
**A:**
-Short answer: you will need to [compile][] Textadept manually for your system,
-which is a very straightforward and easy process.
+Short answer: you will need to [compile][] Textadept manually for your system, which is a very
+straightforward and easy process.
-Long answer: it is difficult to provide a binary that runs on all Linux
-platforms since the library versions installed vary widely from distribution to
-distribution. For example, "libpng14" was available for many distributions
-starting in late 2009 while Ubuntu 12.04 (circa 2012) used "libpng12". More
-recently, some distributions have started using "libncurses6" while many
-distributions are still on "libncurses5". The only way to avoid problems that
-stem from these cases is to compile Textadept for the target system.
+Long answer: it is difficult to provide a binary that runs on all Linux platforms since the
+library versions installed vary widely from distribution to distribution. For example, "libpng14"
+was available for many distributions starting in late 2009 while Ubuntu 12.04 (circa 2012)
+used "libpng12". More recently, some distributions have started using "libncurses6" while many
+distributions are still on "libncurses5". The only way to avoid problems that stem from these
+cases is to compile Textadept for the target system.
[compile]: manual.html#compiling
- - -
**Q:**
-On Windows my anti-virus software says Textadept contains a virus. Does it? Or
-is this a false-positive?
+On Windows my anti-virus software says Textadept contains a virus. Does it? Or is this a
+false-positive?
**A:**
-Textadept does not contain any viruses and it certainly is a false positive.
-The likely culprit is the `textadept-curses.exe` executable, which runs in the
-Windows command prompt.
+Textadept does not contain any viruses and it certainly is a false positive. The likely culprit
+is the `textadept-curses.exe` executable, which runs in the Windows command prompt.
- - -
@@ -63,8 +57,8 @@ Windows command prompt.
Why can't Textadept handle HUGE files very well?
**A:**
-Textadept is an editor for programmers. It is unlikely a programmer would be
-editing a gigantic log file. There are other tools for that case.
+Textadept is an editor for programmers. It is unlikely a programmer would be editing a gigantic
+log file. There are other tools for that case.
- - -
@@ -72,21 +66,19 @@ editing a gigantic log file. There are other tools for that case.
When I open a file in a non-English language, I see a lot of strange characters.
**A:**
-Textadept was not able to detect the file's encoding correctly. You'll need to
-[help it][].
+Textadept was not able to detect the file's encoding correctly. You'll need to [help it][].
[help it]: manual.html#encoding
- - -
**Q:**
-When I click the "Compile" or "Run" menu item (or execute the key command),
-either nothing happens or the wrong command is executed. How can I tell
-Textadept which command to run?
+When I click the "Compile" or "Run" menu item (or execute the key command), either nothing
+happens or the wrong command is executed. How can I tell Textadept which command to run?
**A:**
-The LuaDoc describes [compile and run commands][] and you can configure them in
-your [preferences][].
+The LuaDoc describes [compile and run commands][] and you can configure them in your
+[preferences][].
[compile and run commands]: api.html#_M.Compile.and.Run
[preferences]: manual.html#textadept
@@ -94,9 +86,8 @@ your [preferences][].
- - -
**Q:**
-In the terminal version on Linux, pressing `^Z` suspends Textadept instead of
-performing an "Undo" action. How can I disable suspend and perform "Undo"
-instead?
+In the terminal version on Linux, pressing `^Z` suspends Textadept instead of performing an
+"Undo" action. How can I disable suspend and perform "Undo" instead?
**A:**
Place the following in your `~/.textadept/init.lua` file:
@@ -109,31 +100,28 @@ Place the following in your `~/.textadept/init.lua` file:
- - -
**Q:**
-In Linux, middle-clicking in the terminal version does not paste the primary
-selection and selecting text does copy to the primary selection. All other
-terminal apps support this functionality, why not Textadept?
+In Linux, middle-clicking in the terminal version does not paste the primary selection and
+selecting text does copy to the primary selection. All other terminal apps support this
+functionality, why not Textadept?
**A:**
-It does; use the `Shift` modifier key with your middle-clicking and text
-selecting. Textadept interprets non-`Shift`ed mouse events like a GUI
-application.
+It does; use the `Shift` modifier key with your middle-clicking and text selecting. Textadept
+interprets non-`Shift`ed mouse events like a GUI application.
- - -
**Q:**
-The terminal version does not support feature _x_ the GUI version does. Is this
-a bug?
+The terminal version does not support feature _x_ the GUI version does. Is this a bug?
**A:**
-Maybe. Some terminals do not recognize certain key sequences like `Shift+Arrow`
-for making selections. Linux's virtual terminals (the ones accessible with
-`Ctrl+Alt+FunctionKey`) are an example. GNOME Terminal, LXTerminal and XTerm
-seem to work fine. rxvt and rxvt-unicode do not work out of the box, but may be
-configurable.
+Maybe. Some terminals do not recognize certain key sequences like `Shift+Arrow` for making
+selections. Linux's virtual terminals (the ones accessible with `Ctrl+Alt+FunctionKey`) are an
+example. GNOME Terminal, LXTerminal and XTerm seem to work fine. rxvt and rxvt-unicode do not
+work out of the box, but may be configurable.
-Please see the [terminal version compatibility][] section of the appendix. If
-the feature in question is not listed there, it may be a bug. Please contact me
-(see README.md) with any bug reports.
+Please see the [terminal version compatibility][] section of the appendix. If the feature
+in question is not listed there, it may be a bug. Please contact me (see README.md) with any
+bug reports.
[terminal version compatibility]: manual.html#terminal-version-compatibility
@@ -143,9 +131,9 @@ the feature in question is not listed there, it may be a bug. Please contact me
Pressing `^O` in the terminal version on macOS does not do anything. Why?
**A:**
-For whatever reason, `^O` is discarded by the terminal driver. To enable it, run
-`stty discard undef` first. You can put the command in your *~/.bashrc* or
-*~/.bash_profile* to make it permanent.
+For whatever reason, `^O` is discarded by the terminal driver. To enable it, run `stty discard
+undef` first. You can put the command in your *~/.bashrc* or *~/.bash_profile* to make it
+permanent.
- - -
@@ -153,8 +141,7 @@ For whatever reason, `^O` is discarded by the terminal driver. To enable it, run
How can I get the terminal version on macOS to show more than 8 colors?
**A:**
-Enable the "Use bright colors for bold text" setting in your Terminal.app
-preferences.
+Enable the "Use bright colors for bold text" setting in your Terminal.app preferences.
- - -
@@ -162,30 +149,29 @@ preferences.
Why does Textadept remember its window size but not its window position?
**A:**
-Your window manager is to blame. Textadept is not responsible for, and should
-never attempt to set its window position.
+Your window manager is to blame. Textadept is not responsible for, and should never attempt to
+set its window position.
- - -
**Q:**
-I am not able to use the "Consolas" or [insert other Windows font package here]
-on Windows. Textadept just uses a default font. How can I get it to use my font?
+I am not able to use the "Consolas" or [insert other Windows font package here] on
+Windows. Textadept just uses a default font. How can I get it to use my font?
**A:**
-You'll have to provide the full name of the font, such as "Consolas Regular",
-rather than just the name of the "ttf" file in your Fonts directory.
+You'll have to provide the full name of the font, such as "Consolas Regular", rather than just
+the name of the "ttf" file in your Fonts directory.
- - -
**Q:**
-On my Windows HiDPI display, Textadept's fonts look fuzzy or blurred. How can I
-make them crisp like other HiDPI-aware applications?
+On my Windows HiDPI display, Textadept's fonts look fuzzy or blurred. How can I make them crisp
+like other HiDPI-aware applications?
**A:**
-GTK 2.0, the cross-platform GUI toolkit Textadept uses, is not HiDPI aware, so
-you need to instruct Windows to take over font rendering. Right-click on the
-Textadept executable and select "Properties". Click on the "Compatibility" tab
-and then the "Change high DPI settings" button. Check the "Override high DPI
-scaling" checkbox towards the bottom of the pop-up dialog. The next time you
-run Textadept, the fonts should look much better. You may have to tweak other
-settings in the dialog, but the above worked for me.
+GTK 2.0, the cross-platform GUI toolkit Textadept uses, is not HiDPI aware, so you need to
+instruct Windows to take over font rendering. Right-click on the Textadept executable and
+select "Properties". Click on the "Compatibility" tab and then the "Change high DPI settings"
+button. Check the "Override high DPI scaling" checkbox towards the bottom of the pop-up
+dialog. The next time you run Textadept, the fonts should look much better. You may have to
+tweak other settings in the dialog, but the above worked for me.
diff --git a/docs/index.html b/docs/index.html
index 678ba8f7..6f07d5f2 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -36,9 +36,7 @@
#main div.right-col { float: right; }
#main div.clear-col { clear: both; }
#main div.left-col h3, #main div.right-col h3 { text-align: center; }
- #main div.left-col .center, #main div.right-col .center {
- text-align: center;
- }
+ #main div.left-col .center, #main div.right-col .center { text-align: center; }
@media screen and (max-width: 1000px) {
#main div.left-col, #main div.right-col { width: 100%; }
@@ -48,22 +46,17 @@
<body>
<div id="content">
<div id="header" style="text-align: center;">
- <h1 style="background-image:url('images/header.png');
- background-position: bottom; font-size: 2em;">
+ <h1 style="background-image:url('images/header.png'); background-position: bottom; font-size: 2em;">
Textadept
</h1>
- <p>
- A fast, minimalist, and remarkably extensible cross-platform text
- editor
- </p>
+ <p>A fast, minimalist, and remarkably extensible cross-platform text editor</p>
</div>
<div id="left">
<a id="download"></a>
<h2>Download (v11.1)</h2>
<a href="https://github.com/orbitalquark/textadept/releases.atom">
- <img src="images/feed.png" style="float: right; margin: 0.25em;"
- alt="Atom" />
+ <img src="images/feed.png" style="float: right; margin: 0.25em;" alt="Atom" />
</a>
<ul>
<li><a href="https://github.com/orbitalquark/textadept/releases/download/textadept_11.1/textadept_11.1.win32.zip">Win32</a></li>
@@ -73,9 +66,7 @@
</ul>
<hr style="margin: 0.25em 0.5em 0.25em 0.5em;" />
<ul>
- <li>
- <a href="https://github.com/orbitalquark/textadept">Source</a>
- </li>
+ <li><a href="https://github.com/orbitalquark/textadept">Source</a></li>
<li><a href="changelog.html">Other versions</a></li>
</ul>
@@ -100,8 +91,7 @@
<h2>Quick Reference</h2>
<p style="margin: 0.25em 0 0.25em 0.5em;">
<a href="book.html">
- <img src="images/quickref_small.png" alt="Cover"
- style="border-width: 1px; margin-top: 0.25em;" />
+ <img src="images/quickref_small.png" alt="Cover" style="border-width: 1px; margin-top: 0.25em;" />
</a>
</p>
</div>
@@ -111,10 +101,8 @@
<img src="images/textadept.gif" alt="Textadept Platforms" />
</p>
<p style="font-size: smaller; font-weight: bold;">
- Please
- <a href="https://gum.co/textadept?wanted=true">donate</a> or purchase
- the <a href="book.html">quick reference</a> to help fund continuous
- development.
+ Please <a href="https://gum.co/textadept?wanted=true">donate</a> or purchase the <a
+ href="book.html">quick reference</a> to help fund continuous development.
</p>
<div class="head-col">
@@ -122,28 +110,24 @@
<h2>Features</h2>
<hr />
<p style="text-align: center">
- Textadept is a fast, minimalist, and remarkably extensible
- cross-platform text editor.
+ Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor.
</p>
</div>
<div class="left-col">
<h3>Fast and Minimalist</h3>
<p>
- Textadept&rsquo;s user interface is sleek and simple. Relentlessly
- optimized for speed and minimalism over the years, the editor
- consists of less than 2000 lines of C code and less than 4000 lines
- of <a href="https://lua.org">Lua</a> code.
- </p>
- <p class="center">
- <img src="images/textadept.png" alt="Textadept" />
+ Textadept&rsquo;s user interface is sleek and simple. Relentlessly optimized for
+ speed and minimalism over the years, the editor consists of less than 2000 lines
+ of C code and less than 4000 lines of <a href="https://lua.org">Lua</a> code.
</p>
+ <p class="center"><img src="images/textadept.png" alt="Textadept" /></p>
</div>
<div class="right-col">
<h3>Cross Platform</h3>
<p>
- Textadept runs on Windows, macOS, Linux, and BSD. It also has a
- terminal version, which is ideal for work on remote machines.
+ Textadept runs on Windows, macOS, Linux, and BSD. It also has a terminal version,
+ which is ideal for work on remote machines.
</p>
<p class="center">
<img src="images/linux.png" alt="Linux" />&nbsp;&nbsp;
@@ -158,77 +142,66 @@
<div class="left-col">
<h3>Remarkably Extensible</h3>
<p>
- Textadept is an ideal editor for programmers who want endless
- extensibility without sacrificing speed or succumbing to code bloat
- and featuritis. The editor gives you complete control over the
- entire application using the Lua programming language. Everything
- from moving the caret to changing menus and key bindings on-the-fly
- to handling core events is possible. Its potential is vast.
+ Textadept is an ideal editor for programmers who want endless extensibility
+ without sacrificing speed or succumbing to code bloat and featuritis. The editor
+ gives you complete control over the entire application using the Lua programming
+ language. Everything from moving the caret to changing menus and key bindings
+ on-the-fly to handling core events is possible. Its potential is vast.
</p>
</div>
<div class="right-col">
<h3>Multiple Language Support</h3>
<p>
- Being a programmer&rsquo;s editor, Textadept excels at editing
- source code. It understands the syntax and structure of more than
- 100 different programming languages and recognizes hundreds of file
- types. Textadept uses this knowledge to make viewing and editing
- code faster and easier. It can also compile and run simple source
- files.
+ Being a programmer&rsquo;s editor, Textadept excels at editing source code. It
+ understands the syntax and structure of more than 100 different programming languages
+ and recognizes hundreds of file types. Textadept uses this knowledge to make viewing
+ and editing code faster and easier. It can also compile and run simple source files.
</p>
</div>
<div class="clear-col"></div>
<div class="left-col">
<h3>Unlimited Split Views</h3>
<p>
- Both the graphical version and the terminal version of Textadept
- support unlimited vertical and horizontal view splitting, even of
- the same file.
- </p>
- <p class="center">
- <img src="images/splitviews.png" alt="Split Views" />
+ Both the graphical version and the terminal version of Textadept support unlimited
+ vertical and horizontal view splitting, even of the same file.
</p>
+ <p class="center"><img src="images/splitviews.png" alt="Split Views" /></p>
</div>
<div class="right-col">
<h3>Customizable Themes</h3>
<p>
- Textadept uses themes to customize its look and feel. It comes with
- built-in light, dark, and terminal themes.
+ Textadept uses themes to customize its look and feel. It comes with built-in light,
+ dark, and terminal themes.
</p>
<p class="center">
<img src="images/lighttheme.png" alt="Light Theme" />&nbsp;&nbsp;
<img src="images/darktheme.png" alt="Dark Theme" />
</p>
- <p class="center">
- <img src="images/termtheme.png" alt="Term Theme" />
- </p>
+ <p class="center"><img src="images/termtheme.png" alt="Term Theme" /></p>
</div>
<div class="clear-col"></div>
<div class="left-col">
<h3>Code Autocompletion</h3>
<p>
- Not only can Textadept autocomplete words in files, but it can also
- autocomplete symbols for programming languages and display API
- documentation.
+ Not only can Textadept autocomplete words in files, but it can also autocomplete
+ symbols for programming languages and display API documentation.
</p>
<p class="center">
<img src="images/adeptsense_lua.png" alt="Adeptsense Lua" />&nbsp;
- <img src="images/adeptsense_string.png"
- alt="Adeptsense Lua String" />
+ <img src="images/adeptsense_string.png" alt="Adeptsense Lua String" />
</p>
</div>
<div class="right-col">
<h3>Keyboard Driven</h3>
<p>
- Textadept can be entirely keyboard driven. The editor defines key
- bindings for nearly every action. You can easily reassign existing
- bindings or create new ones. Keys may be chained together or grouped
- into language-specific keys or key modes.
+ Textadept can be entirely keyboard driven. The editor defines key bindings for nearly
+ every action. You can easily reassign existing bindings or create new ones. Keys
+ may be chained together or grouped into language-specific keys or key modes.
</p>
<h3>Self Contained</h3>
<p>
- Textadept&rsquo;s binary packages are self-contained and need not be
- installed. No administrator privilages are required either.
+ Textadept&rsquo;s binary packages are self-contained and need not be installed. No
+ administrator privilages are required either.
</p>
</div>
@@ -237,21 +210,19 @@
<div class="left-col">
<h3>Comprehensive Manual</h3>
<p>
- Textadept comes with a comprehensive <a href="manual.html">user
- manual</a> in the application&rsquo;s <em>docs/</em> directory. It
- covers all of Textadept&rsquo;s main features, including
- installation, usage, configuration, theming, scripting, and
- compilation.
+ Textadept comes with a comprehensive <a href="manual.html">user manual</a> in the
+ application&rsquo;s <em>docs/</em> directory. It covers all of Textadept&rsquo;s
+ main features, including installation, usage, configuration, theming, scripting,
+ and compilation.
</p>
</div>
<div class="right-col">
<h3>Exhaustive API Documentation</h3>
<p>
- Since Textadept is entirely scriptable with Lua, its API is heavily
- <a href="api.html">documented</a>. This documentation is also
- located in <em>docs/</em> and is the ultimate resource on scripting
- Textadept. (The editor&rsquo;s Lua internals also provide abundant
- scripting examples.)
+ Since Textadept is entirely scriptable with Lua, its API is heavily <a
+ href="api.html">documented</a>. This documentation is also located in <em>docs/</em>
+ and is the ultimate resource on scripting Textadept. (The editor&rsquo;s Lua
+ internals also provide abundant scripting examples.)
</p>
</div>
<div class="clear-col"></div>
@@ -259,34 +230,29 @@
<h3>Quick Reference</h3>
<p style="float: left; margin-top: 0;">
<a href="book.html">
- <img src="images/quickref_small.png" alt="Cover2"
- style="border-width: 1px;" />
+ <img src="images/quickref_small.png" alt="Cover2" style="border-width: 1px;" />
</a>
</p>
<p>
- This reference contains a wealth of knowledge on how to script and
- configure Textadept using Lua. It groups the editor&rsquo;s rich API
- into a series of tasks in a convenient and easy-to-use manner. It
- serves as the perfect complement to Textadept&rsquo;s Manual and API
- documentation.
+ This reference contains a wealth of knowledge on how to script and configure
+ Textadept using Lua. It groups the editor&rsquo;s rich API into a series of tasks
+ in a convenient and easy-to-use manner. It serves as the perfect complement to
+ Textadept&rsquo;s Manual and API documentation.
</p>
</div>
<div class="right-col">
<h3>Try It Yourself</h3>
<p>
- Learn even more about Textadept by downloading and trying it out
- yourself. If you&rsquo;re not completely satisfied, <a
- href="https://github.com/orbitalquark/textadept/discussions">contact
- us</a> or e-mail me personally (orbitalquark.att.triplequasar.com).
- You may also fork the project, submit patches, or
- <a href="thanks.html#sponsors">sponsor a feature</a>. Textadept is
- 100% open source.
+ Learn even more about Textadept by downloading and trying
+ it out yourself. If you&rsquo;re not completely satisfied, <a
+ href="https://github.com/orbitalquark/textadept/discussions">contact us</a> or e-mail
+ me personally (orbitalquark.att.triplequasar.com). You may also fork the project,
+ submit patches, or <a href="thanks.html#sponsors">sponsor a feature</a>. Textadept
+ is 100% open source.
</p>
<p style="background-color: #80cc80; color: #4d4d4d; font-size: 1.5em;
- margin: 0 auto 0 auto; padding: 0.25em; text-align: center;
- width: 6em;">
- <a href="#download" style="color: inherit; display: block;
- text-decoration: none;">
+ margin: 0 auto 0 auto; padding: 0.25em; text-align: center; width: 6em;">
+ <a href="#download" style="color: inherit; display: block; text-decoration: none;">
Download
</a>
</p>
@@ -296,56 +262,50 @@
<ul style="margin: 1em 1em 1em 2em;">
<li>
- Textadept has a <a href="changelog.html">proven track record</a>,
- with at least one release every 2 months for 8+ years and no signs
- of inactivity. Also, as an open-source project, the editor will
- never fade away.
+ Textadept has a <a href="changelog.html">proven track record</a>, with at least
+ one release every 2 months for 8+ years and no signs of inactivity. Also, as an
+ open-source project, the editor will never fade away.
</li>
<li>
- Textadept is a real cross-platform desktop application, backed by a
- world-class editing engine that
- <a href="https://www.scintilla.org/ScintillaRelated.html">dozens</a>
- of editors and IDEs have depended on for
- <a href="https://www.scintilla.org/ScintillaHistory.html">over 19
- years</a>.
+ Textadept is a real cross-platform desktop application, backed by a world-class editing
+ engine that <a href="https://www.scintilla.org/ScintillaRelated.html">dozens</a>
+ of editors and IDEs have depended on for <a
+ href="https://www.scintilla.org/ScintillaHistory.html">over 19 years</a>.
</li>
<li>
- Textadept is scriptable in a language that was
- <em><a href="https://www.lua.org/history.html">carefully
- designed</a></em> to run on any platform at high speed and with a
- minimal memory footprint. Lua is used <a
- href="https://sites.google.com/site/marbux/home/where-lua-is-used"
- >everywhere</a> from video games to embedded devices. It is easy to
- <a href="https://www.lua.org/start.html">learn</a> too!
+ Textadept is scriptable in a language that was <em><a
+ href="https://www.lua.org/history.html">carefully designed</a></em> to run
+ on any platform at high speed and with a minimal memory footprint. Lua is
+ used <a href="https://sites.google.com/site/marbux/home/where-lua-is-used"
+ >everywhere</a> from video games to embedded devices. It is easy to <a
+ href="https://www.lua.org/start.html">learn</a> too!
</li>
<li>
- Textadept is very resource efficient, consuming merely 15MB of RAM
- at startup and hardly any CPU while under load. Even with over 20 of
- its own source files open at once, Textadept does not exceed 20MB of
- RAM usage and has no input lag at all.
+ Textadept is very resource efficient, consuming merely 15MB of RAM at startup and
+ hardly any CPU while under load. Even with over 20 of its own source files open at
+ once, Textadept does not exceed 20MB of RAM usage and has no input lag at all.
</li>
<li>
- Textadept does not rely on external packages to provide its
- functionality and does not depend on a package ecosystem to thrive.
- The editor gives you plenty of the tools you need out of the box.
+ Textadept does not rely on external packages to provide its functionality and does
+ not depend on a package ecosystem to thrive. The editor gives you plenty of the
+ tools you need out of the box.
</li>
<li>
- Textadept has sensible defaults and does not expect you to spend
- hours customizing it before you can start being productive.
+ Textadept has sensible defaults and does not expect you to spend hours customizing
+ it before you can start being productive.
</li>
<li>
- With fewer than 30 main source files comprising roughly 6000 lines
- of heavily documented code, Textadept&rsquo;s internals are
- remarkably easy to read, understand, keep track of, and extend to
- your liking.
+ With fewer than 30 main source files comprising roughly 6000 lines of heavily
+ documented code, Textadept&rsquo;s internals are remarkably easy to read, understand,
+ keep track of, and extend to your liking.
</li>
<li>
- Did you see that there is a terminal version in case you need to do
- work on a remote server?
+ Did you see that there is a terminal version in case you need to do work on a
+ remote server?
</li>
<li>
- Textadept does not track you. It does not attempt to connect to the
- internet. <em>It is just a text editor</em>.
+ Textadept does not track you. It does not attempt to connect to the internet. <em>It
+ is just a text editor</em>.
</li>
</ul>
@@ -364,9 +324,9 @@
<div class="clear-col"></div>
<p style="color: #994d4d;">
<a id="nightly"></a>
- *<em>Warning</em>: nightly builds are untested, may have bugs, and are
- the absolute cutting-edge versions of Textadept. Do not use them in
- production, but for testing purposes only.
+ *<em>Warning</em>: nightly builds are untested, may have bugs, and are the absolute
+ cutting-edge versions of Textadept. Do not use them in production, but for testing
+ purposes only.
</p>
</div>
diff --git a/docs/manual.md b/docs/manual.md
index 11bb53ed..aa67283c 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -14,45 +14,40 @@
10. [Compiling](#compiling)
11. [Appendix](#appendix)
---------------------------------------------------------------------------------
+---
### Introduction
---------------------------------------------------------------------------------
+---
#### Overview
![Textadept](images/textadept.png)
-Textadept is a fast, minimalist, and remarkably extensible cross-platform text
-editor for programmers. Written in a combination of C and [Lua][] and
-relentlessly optimized for speed and minimalism over the last 12+ years,
-Textadept is an ideal editor for programmers who want endless extensibility
-without sacrificing speed and disk space, and without succumbing to code bloat
-and a superabundance of features. The application has both a graphical user
-interface (GUI) version that runs in a desktop environment, and a terminal
-version that runs within a terminal emulator.
+Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor for
+programmers. Written in a combination of C and [Lua][] and relentlessly optimized for speed and
+minimalism over the last 12+ years, Textadept is an ideal editor for programmers who want endless
+extensibility without sacrificing speed and disk space, and without succumbing to code bloat and
+a superabundance of features. The application has both a graphical user interface (GUI) version
+that runs in a desktop environment, and a terminal version that runs within a terminal emulator.
[Lua]: https://www.lua.org
-Textadept is _fast_. It starts up instantly and has a very responsive user
-interface. C code is about as fast as you can get, and Lua is widely regarded as
-being one of the fastest scripting languages available.
+Textadept is _fast_. It starts up instantly and has a very responsive user interface. C code is
+about as fast as you can get, and Lua is widely regarded as being one of the fastest scripting
+languages available.
-Textadept is minimalist. Not only is this evident in the editor's appearance,
-but its C core is limited to around 2000 lines of code and its Lua extension
-code tries to avoid going beyond 4000 lines. After more than 12 years of
-development, Textadept contains [roughly the same amount of code][] since its
-inception while significantly improving year after year.
+Textadept is minimalist. Not only is this evident in the editor's appearance, but its C core
+is limited to around 2000 lines of code and its Lua extension code tries to avoid going beyond
+4000 lines. After more than 12 years of development, Textadept contains [roughly the same amount
+of code][] since its inception while significantly improving year after year.
[roughly the same amount of code]: index.html#plots
-Textadept is remarkably extensible. It was designed to be that way from the
-beginning; the editor's features came later. Most of Textadept's internals are
-written in Lua: syntax highlighting, opening and saving files, and search and
-replace, to name a few. Textadept gives you nearly complete control over the
-entire application using Lua. Capabilities like navigating within the editor,
-changing menus and key bindings on the fly, handling core events, and
-highlighting the syntax of new programming languages are possible. The editor's
-potential is seemingly limitless.
+Textadept is remarkably extensible. It was designed to be that way from the beginning; the editor's
+features came later. Most of Textadept's internals are written in Lua: syntax highlighting,
+opening and saving files, and search and replace, to name a few. Textadept gives you nearly
+complete control over the entire application using Lua. Capabilities like navigating within the
+editor, changing menus and key bindings on the fly, handling core events, and highlighting the
+syntax of new programming languages are possible. The editor's potential is seemingly limitless.
![Split Views](images/splitviews.png)
@@ -61,62 +56,55 @@ potential is seemingly limitless.
This manual uses the following typographical conventions:
* *Italic*: Used for filenames.
-* `Constant width`: Used for environment variables, command line arguments,
- shell code, key bindings, and Lua code, including functions, tables, and
- variables.
+* `Constant width`: Used for environment variables, command line arguments, shell code, key
+ bindings, and Lua code, including functions, tables, and variables.
Key bindings use the following modifier key representations:
-Modifier|Windows, Linux, BSD|macOS|Terminal|
---------|-------------------|-----|--------|
-Control |`Ctrl` |`^` |`^` |
-Alt |`Alt` |`⌥` |`M-` |
-Command |N/A |`⌘` |N/A |
-Shift |`Shift` |`⇧` |`S-` |
+Modifier | Windows, Linux, BSD | macOS | Terminal
+-|-|-|-
+Control | `Ctrl` | `^` | `^`
+Alt | `Alt` | `⌥` | `M-`
+Command | N/A | `⌘` | N/A
+Shift | `Shift` | `⇧` | `S-`
This manual uses the following terminology:
-* *buffer*: An object that contains editable text. Some other applications call
- this object a document or file.
-* *view*: An object that displays a single buffer. Some other applications call
- this object a window.
-* *caret*: The visual that represents the text insertion point. It is usually a
- blinking line.
+* *buffer*: An object that contains editable text. Some other applications call this object a
+ document or file.
+* *view*: An object that displays a single buffer. Some other applications call this object
+ a window.
+* *caret*: The visual that represents the text insertion point. It is usually a blinking line.
* *module*: A package of Lua code that provides functionality for Textadept.
-* *lexer*: A Lua module that highlights the syntax of source code written in a
- particular programming language. Textadept refers to a programming language by
- its lexer's name.
+* *lexer*: A Lua module that highlights the syntax of source code written in a particular
+ programming language. Textadept refers to a programming language by its lexer's name.
-Finally, this manual assumes you are familiar enough with the [Lua][]
-programming language that you can understand the simple code samples spread
-throughout the manual's contents. If you would like to quickly get up to speed,
-or need a refresher, the excerpt from [Lua Quick Reference][] may be of help.
+Finally, this manual assumes you are familiar enough with the [Lua][] programming language that
+you can understand the simple code samples spread throughout the manual's contents. If you would
+like to quickly get up to speed, or need a refresher, the excerpt from [Lua Quick Reference][]
+may be of help.
[Lua Quick Reference]: https://orbitalquark.github.io/lua-quick-reference
#### ~/.textadept
-Textadept stores all settings and user data in a local user directory that
-varies, depending on the platform. This directory can also be configured using
-command line arguments. On Windows systems, the default user directory is
-*C:\Users\username\.textadept\\* or
-*C:\Documents and Settings\username\.textadept\\*; on macOS, the default user
-directory is */Users/username/.textadept/*; and on Linux and BSD, it is
-*/home/username/.textadept/*. (Substitute *username* for your actual user name.)
-From this point forward, the manual will use *~/.textadept/* in place of any
-platform-specific user data directory.
-
-There is a special file, *~/.textadept/init.lua*, that Textadept will create for
-you if it does not already exist. This file is what you use to configure
-Textadept, specify your preferences, and customize what the application does
-when it starts. For example, you can use this file to set a color theme, specify
-default buffer and view settings, change the settings of existing modules, load
-custom modules, configure key bindings, extend menus, enhance support for file
-types and programming languages, and run arbitrary Lua code. These topics will
-be covered throughout the manual. Textadept's comprehensive [Lua API][] lists,
-among other things, all configurable settings for buffers, views, and modules.
-You can open your *~/.textadept/init.lua* file via `Ctrl+P` on Windows, Linux,
-and BSD, `⌘,` on macOS, and `M-~` in the terminal version.
+Textadept stores all settings and user data in a local user directory that varies, depending
+on the platform. This directory can also be configured using command line arguments. On
+Windows systems, the default user directory is *C:\Users\username\.textadept\\*
+or *C:\Documents and Settings\username\.textadept\\*; on macOS, the default
+user directory is */Users/username/.textadept/*; and on Linux and BSD, it is
+*/home/username/.textadept/*. (Substitute *username* for your actual user name.) From this point
+forward, the manual will use *~/.textadept/* in place of any platform-specific user data directory.
+
+There is a special file, *~/.textadept/init.lua*, that Textadept will create for you if it does
+not already exist. This file is what you use to configure Textadept, specify your preferences,
+and customize what the application does when it starts. For example, you can use this file to set
+a color theme, specify default buffer and view settings, change the settings of existing modules,
+load custom modules, configure key bindings, extend menus, enhance support for file types and
+programming languages, and run arbitrary Lua code. These topics will be covered throughout
+the manual. Textadept's comprehensive [Lua API][] lists, among other things, all configurable
+settings for buffers, views, and modules. You can open your *~/.textadept/init.lua* file via
+`Ctrl+P` on Windows, Linux, and BSD, `⌘,` on macOS, and `M-~` in the terminal version.
Here is a simple *~/.textadept/init.lua* for illustration:
@@ -153,78 +141,72 @@ Here is a simple *~/.textadept/init.lua* for illustration:
buffer.tab_width = 4
end)
-**Note:** *~/.textadept/init.lua* must not call any functions that create
-buffers and views (e.g. `ui.print()`, `io.open_file()`, and `buffer.new()`) at
-file-level scope. Buffers and views can only be created within functions
-assigned to keys, associated with menu items, or connected to events.
+**Note:** *~/.textadept/init.lua* must not call any functions that create buffers and views
+(e.g. `ui.print()`, `io.open_file()`, and `buffer.new()`) at file-level scope. Buffers and
+views can only be created within functions assigned to keys, associated with menu items, or
+connected to events.
[Lua API]: api.html
---------------------------------------------------------------------------------
+---
### Getting Started
---------------------------------------------------------------------------------
+---
#### Requirements
-In its bid for minimalism, Textadept depends on very little to run. On Windows
-and macOS, it has no external dependencies. On Linux and BSD, the GUI version
-depends only on [GTK][] (a cross-platform GUI toolkit) version 2.24 or later
-(circa early 2011), and the terminal version depends only on a wide-character
-implementation of curses like [ncurses][](w). Most Linux and BSD systems either
-already have these dependencies installed, or they are readily available from a
-package manager.
+In its bid for minimalism, Textadept depends on very little to run. On Windows and macOS,
+it has no external dependencies. On Linux and BSD, the GUI version depends only on [GTK][]
+(a cross-platform GUI toolkit) version 2.24 or later (circa early 2011), and the terminal
+version depends only on a wide-character implementation of curses like [ncurses][](w). Most
+Linux and BSD systems either already have these dependencies installed, or they are readily
+available from a package manager.
-Windows XP and Mac OSX 10.7 (Lion) are the minimum required operating systems.
-Linux and BSD have no defined minimum.
+Windows XP and Mac OSX 10.7 (Lion) are the minimum required operating systems. Linux and BSD
+have no defined minimum.
[GTK]: https://gtk.org
[ncurses]: https://invisible-island.net/ncurses/ncurses.html
#### Download
-Textadept releases can be found [here][1]. Select the appropriate package for
-your platform. A comprehensive list of changes between releases can be found
-[here][2]. You can also download a separate set of modules that provide extra
-features and functionality to the core application.
+Textadept releases can be found [here][1]. Select the appropriate package for your platform. A
+comprehensive list of changes between releases can be found [here][2]. You can also download
+a separate set of modules that provide extra features and functionality to the core application.
-**Windows Note:** antivirus software may flag the Windows package as containing
-a virus or malware. This is a false-positive, likely due to Textadept's terminal
-version executable, which is a console application.
+**Windows Note:** antivirus software may flag the Windows package as containing a virus or
+malware. This is a false-positive, likely due to Textadept's terminal version executable,
+which is a console application.
-The following table lists Textadept's approximate download and installation size
-for each platform.
+The following table lists Textadept's approximate download and installation size for each platform.
-Platform|Download Size|Installed Size
---------|-------------|--------------
-Linux |4 MB |11 MB
-macOS |11 MB |35 MB (12 MB without bundled GTK Runtime)
-Windows |16 MB |41 MB (23 MB without bundled GTK Runtime)
+Platform | Download Size | Installed Size
+-|-|-
+Linux | 4 MB | 11 MB
+macOS | 11 MB | 35 MB (12 MB without bundled GTK Runtime)
+Windows | 16 MB |41 MB (23 MB without bundled GTK Runtime)
-**Note:** each platform package contains two executables, one for the GUI
-version of Textadept, and one for the terminal version.
+**Note:** each platform package contains two executables, one for the GUI version of Textadept,
+and one for the terminal version.
[1]: https://github.com/orbitalquark/textadept/releases
[2]: changelog.html
#### Installation
-Installing Textadept is simple and easy. You do not need administrator
-privileges. On Windows, Linux, and BSD, simply unpack the archive anywhere. On
-macOS, unpack the archive and move *Textadept.app* to your user or system
-*Applications/* directory like any other macOS application. The macOS archive
-also contains a *ta* script for launching Textadept from the command line. You
-can put this script somewhere in your `$PATH` (e.g. */usr/local/bin/*), but this
-is completely optional.
+Installing Textadept is simple and easy. You do not need administrator privileges. On Windows,
+Linux, and BSD, simply unpack the archive anywhere. On macOS, unpack the archive and move
+*Textadept.app* to your user or system *Applications/* directory like any other macOS
+application. The macOS archive also contains a *ta* script for launching Textadept from the
+command line. You can put this script somewhere in your `$PATH` (e.g. */usr/local/bin/*),
+but this is completely optional.
-If you downloaded Textadept's extra set of modules, you can unpack its contents
-into Textadept's directory (thus merging the *modules/* directories) on Windows,
-Linux, and BSD. On macOS, it is recommended to create a *~/.textadept/*
-directory (if it does not already exist) and unpack the modules there (thus
-creating or merging the *modules/* directory).
+If you downloaded Textadept's extra set of modules, you can unpack its contents into Textadept's
+directory (thus merging the *modules/* directories) on Windows, Linux, and BSD. On macOS, it
+is recommended to create a *~/.textadept/* directory (if it does not already exist) and unpack
+the modules there (thus creating or merging the *modules/* directory).
-**Note:** Textadept generally does not auto-load [modules](#modules), so you
-will need to load at least some of those extra modules manually. For example, in
-your *~/.textadept/init.lua*:
+**Note:** Textadept generally does not auto-load [modules](#modules), so you will need to load
+at least some of those extra modules manually. For example, in your *~/.textadept/init.lua*:
require('ctags')
require('file_diff')
@@ -232,11 +214,10 @@ your *~/.textadept/init.lua*:
#### Updating
-Textadept releases typically occur on the first day of the month every 1-2
-months. There is no auto-update process. (Textadept does not connect to the
-internet; it's just a text editor.) Simply download the new version and copy its
-contents into your current installation, overwriting any existing files and
-directories.
+Textadept releases typically occur on the first day of the month every 1-2 months. There is no
+auto-update process. (Textadept does not connect to the internet; it's just a text editor.) Simply
+download the new version and copy its contents into your current installation, overwriting any
+existing files and directories.
#### Running
@@ -248,36 +229,33 @@ directories.
&nbsp;&nbsp;
![curses](images/ncurses.png)
-Run Textadept on Windows by double-clicking *textadept.exe* or
-*textadept-curses.exe*. On macOS, double-click *Textadept.app* or invoke the
-*ta* script from the command line. On Linux and BSD, invoke *textadept* or
-*textadept-curses* from a file browser, run dialog, terminal, etc.
-
-For convenience, you can create shortcuts to the executables on the Windows
-Desktop, Start Menu, Quick Launch toolbar, etc. On macOS, you can pin the app to
-your dock. On Linux and BSD, you can create a symbolic link to the executables
-from somewhere in your `$PATH` (e.g. */usr/local/bin/*) or make a GNOME, KDE,
-XFCE, etc. button or menu launcher. Textadept's *src/textadept.desktop* and
-*src/textadept-curses.desktop* files may be of help.
-
-Textadept accepts a variety of command line arguments, which are listed in the
-table below.
-
-Option |Arguments|Description
--------------------|:-------:|-----------
-`-e`, `--execute` | 1 |Run the given Lua code
-`-f`, `--force` | 0 |Forces unique instance
-`-h`, `--help` | 0 |Shows this<sup>a</sup>
-`-l`, `--line` | 1 |Jumps to a line in the previously opened file
-`-n`, `--nosession`| 0 |No state saving/restoring functionality
-`-s`, `--session` | 1 |Loads the given session on startup
-`-u`, `--userhome` | 1 |Sets alternate user data directory
-`-v`, `--version` | 0 |Prints version and copyright info<sup>a</sup>
+Run Textadept on Windows by double-clicking *textadept.exe* or *textadept-curses.exe*. On macOS,
+double-click *Textadept.app* or invoke the *ta* script from the command line. On Linux and BSD,
+invoke *textadept* or *textadept-curses* from a file browser, run dialog, terminal, etc.
+
+For convenience, you can create shortcuts to the executables on the Windows Desktop, Start Menu,
+Quick Launch toolbar, etc. On macOS, you can pin the app to your dock. On Linux and BSD, you can
+create a symbolic link to the executables from somewhere in your `$PATH` (e.g. */usr/local/bin/*)
+or make a GNOME, KDE, XFCE, etc. button or menu launcher. Textadept's *src/textadept.desktop*
+and *src/textadept-curses.desktop* files may be of help.
+
+Textadept accepts a variety of command line arguments, which are listed in the table below.
+
+Option | Arguments | Description
+-|:-:|-
+`-e`, `--execute` | 1 | Run the given Lua code
+`-f`, `--force` | 0 | Forces unique instance
+`-h`, `--help` | 0 | Shows this<sup>a</sup>
+`-l`, `--line` | 1 | Jumps to a line in the previously opened file
+`-n`, `--nosession` | 0 | No state saving/restoring functionality
+`-s`, `--session` | 1 | Loads the given session on startup
+`-u`, `--userhome` | 1 | Sets alternate user data directory
+`-v`, `--version` | 0 | Prints version and copyright info<sup>a</sup>
<sup>a</sup>The terminal version does not support these.
-You can add your own command line arguments using [`args.register()`][]. For
-example, in your *~/.textadept/init.lua*:
+You can add your own command line arguments using [`args.register()`][]. For example, in your
+*~/.textadept/init.lua*:
args.register('-r', '--read-only', 0, function()
events.connect(events.FILE_OPENED, function()
@@ -293,119 +271,106 @@ Textadept can also open files and projects using the command line. For example:
textadept /path/to/file1 ../relative/path/to/file2
textadept /path/to/project/ relative/path/to/file1 relative/file2
-Unless a filename is specified as an absolute path, Textadept assumes it is
-relative to the application's current working directory (cwd). Textadept's cwd
-is initially the command line's cwd. (If Textadept is not being run from the
-command line, its cwd is unspecified.) If a project directory is specified, it
-becomes Textadept's cwd. (Textadept does not open all files in that directory.)
-If multiple project directories are specified, the last one becomes the cwd.
-
-By default, Textadept saves its state when it exits. (This state consists of
-buffers and split views that are open, the list of recently opened files,
-the application window's size and maximized state, etc.) If Textadept is not
-given any files or projects to open, it will try to restore its state at last
-exit.
-
-**Tip:** you can explicitly tell Textadept to load a session by name using the
-`-s` or `--session` command line argument. You can disable session functionality
-using `-n` or `--nosession`. Session files are stored in *~/.textadept/*, and
-the default session name is "session".
-
-The GUI version of Textadept is a single-instance application. This means that
-after you start Textadept, any time you invoke it again (e.g. opening a file
-from a file browser or command line), the action happens in the original
-instance. If you want to run separate instances of Textadept, pass the `-f` or
-`--force` command line flag. On Windows, you can create a shortcut to
-*textadept.exe* that passes this flag and use that shortcut to run Textadept. On
-Linux and BSD, you can set up your button or menu launchers to pass the flag to
-the *textadept* executable.
-
-Textadept can be run as a portable application. This is useful if, for example,
-you want to install Textadept onto a flash drive and take it with you for use on
-multiple machines. Normally, all settings and user data is stored in
-*~/.textadept/* (a local user directory that varies, depending on the platform).
-However, this user directory can be controlled using the `-u` or `--userhome`
-command line argument. For example, invoking *textadept.exe* with the command
-line arguments `-u userdata` will read from and store settings and user data to
-a *userdata/* directory located inside an installation of Textadept. You can
-create a Windows shortcut that passes these command line arguments to the
-Textadept executable and use that shortcut to run Textadept portably.
-
-Textadept's user interface has been translated into a few different languages.
-When the application starts, it attempts to auto-detect your language settings
-by reading from the `$LANG` environment variable. If Textadept cannot determine
-what language to use, or if it does not support your language, it falls back on
-English. You can manually set your locale by copying one of the locale
-configuration files from Textadept's *core/locales/* to your *~/.textadept/*
-directory and renaming it *locale.conf*. If you would like to translate
-Textadept into your language, please translate the English messages in
-*core/locale.conf* and send me (see README.md) the modified file for inclusion
-in a future release.
-
-**macOS Tip:** by default, macOS does not allow GUI applications like
-*Textadept.app* to see shell environment variables like `$PATH`. (The terminal
-version is unaffected.) Consequently, any features that utilize programs
-contained in `$PATH` (e.g. the programs in */usr/bin/* or */usr/local/bin/*)
-will not find those programs. In order to work around this, Textadept
-automatically invokes a user-created *~/.textadept/osx_env.sh* file when the
-application starts. This script should export all of the environment variables
-you need Textadept to see. For example:
+Unless a filename is specified as an absolute path, Textadept assumes it is relative to
+the application's current working directory (cwd). Textadept's cwd is initially the command
+line's cwd. (If Textadept is not being run from the command line, its cwd is unspecified.) If a
+project directory is specified, it becomes Textadept's cwd. (Textadept does not open all files
+in that directory.) If multiple project directories are specified, the last one becomes the cwd.
+
+By default, Textadept saves its state when it exits. (This state consists of buffers and split
+views that are open, the list of recently opened files, the application window's size and
+maximized state, etc.) If Textadept is not given any files or projects to open, it will try to
+restore its state at last exit.
+
+**Tip:** you can explicitly tell Textadept to load a session by name using the `-s` or `--session`
+command line argument. You can disable session functionality using `-n` or `--nosession`. Session
+files are stored in *~/.textadept/*, and the default session name is "session".
+
+The GUI version of Textadept is a single-instance application. This means that after you start
+Textadept, any time you invoke it again (e.g. opening a file from a file browser or command
+line), the action happens in the original instance. If you want to run separate instances of
+Textadept, pass the `-f` or `--force` command line flag. On Windows, you can create a shortcut
+to *textadept.exe* that passes this flag and use that shortcut to run Textadept. On Linux and
+BSD, you can set up your button or menu launchers to pass the flag to the *textadept* executable.
+
+Textadept can be run as a portable application. This is useful if, for example, you want to
+install Textadept onto a flash drive and take it with you for use on multiple machines. Normally,
+all settings and user data is stored in *~/.textadept/* (a local user directory that varies,
+depending on the platform). However, this user directory can be controlled using the `-u` or
+`--userhome` command line argument. For example, invoking *textadept.exe* with the command line
+arguments `-u userdata` will read from and store settings and user data to a *userdata/* directory
+located inside an installation of Textadept. You can create a Windows shortcut that passes these
+command line arguments to the Textadept executable and use that shortcut to run Textadept portably.
+
+Textadept's user interface has been translated into a few different languages. When the
+application starts, it attempts to auto-detect your language settings by reading from the `$LANG`
+environment variable. If Textadept cannot determine what language to use, or if it does not
+support your language, it falls back on English. You can manually set your locale by copying
+one of the locale configuration files from Textadept's *core/locales/* to your *~/.textadept/*
+directory and renaming it *locale.conf*. If you would like to translate Textadept into your
+language, please translate the English messages in *core/locale.conf* and send me (see README.md)
+the modified file for inclusion in a future release.
+
+**macOS Tip:** by default, macOS does not allow GUI applications like *Textadept.app* to see
+shell environment variables like `$PATH`. (The terminal version is unaffected.) Consequently,
+any features that utilize programs contained in `$PATH` (e.g. the programs in */usr/bin/*
+or */usr/local/bin/*) will not find those programs. In order to work around this, Textadept
+automatically invokes a user-created *~/.textadept/osx_env.sh* file when the application
+starts. This script should export all of the environment variables you need Textadept to
+see. For example:
export PATH=$PATH
-**Linux Note:** providing a single binary that runs on all Linux systems proves
-challenging, since the versions of software installed vary widely from
-distribution to distribution. If you get errors like:
+**Linux Note:** providing a single binary that runs on all Linux systems proves challenging,
+since the versions of software installed vary widely from distribution to distribution. If you
+get errors like:
- * `error while loading shared libraries: <lib>: cannot open shared object
- file: No such file or directory`
+ * `error while loading shared libraries: <lib>: cannot open shared object file: No such file
+ or directory`
* `/<path>/libc.so.6: version 'GLIBC_<version>' not found`
-you will need to [compile](#compiling) Textadept manually for your system, which
-is a very straightforward and easy process.
+you will need to [compile](#compiling) Textadept manually for your system, which is a very
+straightforward and easy process.
---------------------------------------------------------------------------------
+---
### User Interface
---------------------------------------------------------------------------------
+---
![UI](images/ui.png)
-Textadept's user interface is sleek and simple. It consists of a menu bar, tab
-bar, editor view, and statusbar. There is also a find & replace pane and a
-command entry, though Textadept initially hides them both.
+Textadept's user interface is sleek and simple. It consists of a menu bar, tab bar, editor
+view, and statusbar. There is also a find & replace pane and a command entry, though Textadept
+initially hides them both.
-Textadept's titlebar shows the name and path of the current, active buffer. A
-'\*' character, if present, indicates there are unsaved changes in that buffer.
+Textadept's titlebar shows the name and path of the current, active buffer. A '\*' character,
+if present, indicates there are unsaved changes in that buffer.
#### Menu
-The GUI version of Textadept has a completely customizable menu that provides
-access to nearly all of the application's editing features.
-
-**Tip:** Textadept is largely a keyboard-driven application, so nearly every
-menu item has a key binding. For at least the GUI version in the English locale
-on Windows, Linux, and BSD, each menu and menu item also has a unique mnemonic
-that can be used to activate it. For example, `Alt+E` accesses the "Edit" menu,
-`S` opens the "Select" sub-menu, and `L` invokes the menu item that selects the
-current line.
-
-Textadept's menu is also accessible in the form of a searchable dialog via
-`Ctrl+Shift+E` on Windows, Linux, and BSD, `⌘⇧E` on macOS, and `M-S-C` in the
-terminal version. (Despite the fact that the terminal version does not have a
-menu, it does have this dialog.) Typing part of the name of any command in the
-dialog filters the list, with spaces being wildcards. The arrow keys move the
-selection up and down. Pressing `Enter`, selecting `OK`, or double-clicking on a
-command invokes it. (The terminal requires pressing `Enter`.) This feature is an
-alternative to navigating the menus or remembering key bindings. It can also be
-used to quickly look up key bindings for particular commands.
-
-**Note:** for commands that have more than one key binding, only one of those
-bindings is shown in the menu and dialog, and that binding is randomly chosen.
-
-You can extend Textadept's menu with your own menus, sub-menus, and menu items
-by modifying the [`textadept.menu.menubar`][] table. Any modifications will show
-up in the selection dialog mentioned previously, even in the terminal version.
-For example, in your *~/.textadept/init.lua*:
+The GUI version of Textadept has a completely customizable menu that provides access to nearly
+all of the application's editing features.
+
+**Tip:** Textadept is largely a keyboard-driven application, so nearly every menu item has a key
+binding. For at least the GUI version in the English locale on Windows, Linux, and BSD, each
+menu and menu item also has a unique mnemonic that can be used to activate it. For example,
+`Alt+E` accesses the "Edit" menu, `S` opens the "Select" sub-menu, and `L` invokes the menu
+item that selects the current line.
+
+Textadept's menu is also accessible in the form of a searchable dialog via `Ctrl+Shift+E` on
+Windows, Linux, and BSD, `⌘⇧E` on macOS, and `M-S-C` in the terminal version. (Despite the
+fact that the terminal version does not have a menu, it does have this dialog.) Typing part of
+the name of any command in the dialog filters the list, with spaces being wildcards. The arrow
+keys move the selection up and down. Pressing `Enter`, selecting `OK`, or double-clicking on a
+command invokes it. (The terminal requires pressing `Enter`.) This feature is an alternative
+to navigating the menus or remembering key bindings. It can also be used to quickly look up
+key bindings for particular commands.
+
+**Note:** for commands that have more than one key binding, only one of those bindings is shown
+in the menu and dialog, and that binding is randomly chosen.
+
+You can extend Textadept's menu with your own menus, sub-menus, and menu items by modifying
+the [`textadept.menu.menubar`][] table. Any modifications will show up in the selection dialog
+mentioned previously, even in the terminal version. For example, in your *~/.textadept/init.lua*:
local tools = textadept.menu.menubar[_L['Tools']]
tools[#tools + 1] = {''} -- separator
@@ -415,88 +380,75 @@ For example, in your *~/.textadept/init.lua*:
#### Tab Bar
-The GUI version of Textadept has a tab bar that displays all of Textadept's open
-buffers by name, though it is only visible when two or more buffers are open. A
-'\*' character, if present, indicates there are unsaved changes in the marked
-buffer. There is only one tab bar for the entire application, even if there are
-multiple split views. When two or more views are open, the state of the tab bar
-applies only to the active view, and using the tab bar to switch between files
-also applies only to that view. Right-clicking on the tab bar brings up a
-configurable context menu that is defined by
-[`textadept.menu.tab_context_menu`][]. You can turn off the tab bar by setting
-[`ui.tabs`][]. For example, in your *~/.textadept/init.lua*:
+The GUI version of Textadept has a tab bar that displays all of Textadept's open buffers by name,
+though it is only visible when two or more buffers are open. A '\*' character, if present,
+indicates there are unsaved changes in the marked buffer. There is only one tab bar for the
+entire application, even if there are multiple split views. When two or more views are open, the
+state of the tab bar applies only to the active view, and using the tab bar to switch between
+files also applies only to that view. Right-clicking on the tab bar brings up a configurable
+context menu that is defined by [`textadept.menu.tab_context_menu`][]. You can turn off the
+tab bar by setting [`ui.tabs`][]. For example, in your *~/.textadept/init.lua*:
ui.tabs = false
[`textadept.menu.tab_context_menu`]: api.html#textadept.menu.tab_context_menu
[`ui.tabs`]: api.html#ui.tabs
-Cycle to the next buffer via `Ctrl+Tab` on Windows, Linux, and BSD, `^⇥` on
-macOS, and `M-N` in the terminal version. Cycle to the previous buffer via
-`Ctrl+Shift+Tab`, `^⇧⇥`, and `M-P`.
+Cycle to the next buffer via `Ctrl+Tab` on Windows, Linux, and BSD, `^⇥` on macOS, and `M-N`
+in the terminal version. Cycle to the previous buffer via `Ctrl+Shift+Tab`, `^⇧⇥`, and `M-P`.
-**Note:** Textadept does not currently support rearranging tabs (e.g. via drag
-and drop).
+**Note:** Textadept does not currently support rearranging tabs (e.g. via drag and drop).
-The tab bar is also accessible in the form of a searchable dialog via `Ctrl+B`
-on Windows, Linux, and BSD, `⌘B` on macOS, and `M-B` or `M-S-B` in the terminal
-version. (Despite the fact that the terminal version does not have a tab bar, it
-does have this dialog.) The dialog displays a list of currently open buffers.
-Typing part of any filename filters the list, with spaces being wildcards. The
-arrow keys move the selection up and down. Pressing `Enter`, selecting `OK`, or
-double-clicking on a buffer switches to it. (The terminal requires pressing
-`Enter`.) This feature is particularly useful when many files are open, and
-navigating through the tab bar is tedious.
+The tab bar is also accessible in the form of a searchable dialog via `Ctrl+B` on Windows,
+Linux, and BSD, `⌘B` on macOS, and `M-B` or `M-S-B` in the terminal version. (Despite the
+fact that the terminal version does not have a tab bar, it does have this dialog.) The dialog
+displays a list of currently open buffers. Typing part of any filename filters the list,
+with spaces being wildcards. The arrow keys move the selection up and down. Pressing `Enter`,
+selecting `OK`, or double-clicking on a buffer switches to it. (The terminal requires pressing
+`Enter`.) This feature is particularly useful when many files are open, and navigating through
+the tab bar is tedious.
![Buffer Browser](images/bufferbrowser.png)
&nbsp;&nbsp;
![Buffer Browser Filtered](images/bufferbrowserfiltered.png)
-By default, the list shows buffers in the same order as the tab bar (the most
-recently opened buffers are shown towards the bottom). You can configure the
-list to show the most recently viewed buffers first by changing the key binding.
-For example, in your *~/.textadept/init.lua*:
+By default, the list shows buffers in the same order as the tab bar (the most recently opened
+buffers are shown towards the bottom). You can configure the list to show the most recently
+viewed buffers first by changing the key binding. For example, in your *~/.textadept/init.lua*:
keys['ctrl+b'] = function() ui.switch_buffer(true) end
#### Editor View
-The editor view is where you will spend most of your time in Textadept. You can
-split it vertically and horizontally as many times as you like, and you can view
-the same buffer in two or more separate views. Lua also has near complete
-control over all views. The [`buffer`][] and [`view`][] documentation lists
-everything you can do with buffers and views directly. Right-clicking inside a
-view brings up a configurable context menu that is defined by
-[`textadept.menu.context_menu`][].
-
-Split views can be dynamically resized by clicking and dragging on the splitter
-bar that separates them. The following key bindings apply for split views:
-
-* Split a view horizontally into top and bottom views via `Ctrl+Alt+S` or
- `Ctrl+Alt+H` on Windows, Linux, and BSD, `^S` on macOS, and `M-^V S` in the
- terminal version.
-* Split a view vertically into side-by-side views via `Ctrl+Alt+V` on Windows,
- Linux, and BSD, `^V` on macOS, and `M-^V V` in the terminal version.
-* Cycle to the next split view via `Ctrl+Alt+N` on Windows, Linux, and BSD,
- `^⌥⇥` on macOS, and `M-^V N` in the terminal version.
-* Cycle to the previous split view via `Ctrl+Alt+P` on Windows, Linux, and BSD,
- `^⌥⇧⇥` on macOS, and `M-^V P` in the terminal version.
-* Grow or shrink a view via `Ctrl+Alt++` or `Ctrl+Alt+-`, respectively, on
- Windows, Linux, and BSD; `^+` or `^-`, respectively, on macOS; and `M-^V +` or
- `M-^V -` in the terminal version.
-* Unsplit the current view by removing its complement view(s) via `Ctrl+Alt+W`
- on Windows, Linux, and BSD, `^W` on macOS, and `M-^V W` in the terminal
- version.
-* Unsplit the current view by removing all other views via `Ctrl+Alt+Shift+W` on
- Windows, Linux, and BSD, `^⇧W` on macOS, and `M-^V S-W` in the terminal
- version.
-
-**Note:** depending on the split sequence, the order when cycling between views
-may not be linear.
-
-**Terminal version note:** `M-^V` is the key chain prefix for split views. Press
-and release the prefix, and then type the next key in the chain by itself in
-order to perform the split view action.
+The editor view is where you will spend most of your time in Textadept. You can split it vertically
+and horizontally as many times as you like, and you can view the same buffer in two or more
+separate views. Lua also has near complete control over all views. The [`buffer`][] and [`view`][]
+documentation lists everything you can do with buffers and views directly. Right-clicking inside
+a view brings up a configurable context menu that is defined by [`textadept.menu.context_menu`][].
+
+Split views can be dynamically resized by clicking and dragging on the splitter bar that
+separates them. The following key bindings apply for split views:
+
+* Split a view horizontally into top and bottom views via `Ctrl+Alt+S` or `Ctrl+Alt+H` on Windows,
+ Linux, and BSD, `^S` on macOS, and `M-^V S` in the terminal version.
+* Split a view vertically into side-by-side views via `Ctrl+Alt+V` on Windows, Linux, and BSD,
+ `^V` on macOS, and `M-^V V` in the terminal version.
+* Cycle to the next split view via `Ctrl+Alt+N` on Windows, Linux, and BSD, `^⌥⇥` on macOS,
+ and `M-^V N` in the terminal version.
+* Cycle to the previous split view via `Ctrl+Alt+P` on Windows, Linux, and BSD, `^⌥⇧⇥`
+ on macOS, and `M-^V P` in the terminal version.
+* Grow or shrink a view via `Ctrl+Alt++` or `Ctrl+Alt+-`, respectively, on Windows, Linux,
+ and BSD; `^+` or `^-`, respectively, on macOS; and `M-^V +` or `M-^V -` in the terminal version.
+* Unsplit the current view by removing its complement view(s) via `Ctrl+Alt+W` on Windows,
+ Linux, and BSD, `^W` on macOS, and `M-^V W` in the terminal version.
+* Unsplit the current view by removing all other views via `Ctrl+Alt+Shift+W` on Windows, Linux,
+ and BSD, `^⇧W` on macOS, and `M-^V S-W` in the terminal version.
+
+**Note:** depending on the split sequence, the order when cycling between views may not be linear.
+
+**Terminal version note:** `M-^V` is the key chain prefix for split views. Press and release
+the prefix, and then type the next key in the chain by itself in order to perform the split
+view action.
[`buffer`]: api.html#buffer
[`view`]: api.html#view
@@ -504,19 +456,16 @@ order to perform the split view action.
#### Find & Replace Pane
-The find & replace pane is a compact, full-featured pane that allows you to
-quickly search through files and directories. The pane is available only when
-you need it and quickly gets out of your way when you do not, minimizing
-distractions.
+The find & replace pane is a compact, full-featured pane that allows you to quickly search
+through files and directories. The pane is available only when you need it and quickly gets
+out of your way when you do not, minimizing distractions.
-You can summon the find & replace pane via `Ctrl+F` on Windows, Linux and BSD,
-`⌘F` on macOS, and `M-F` or `M-S-F` in the terminal version. It has the usual
-find and replace functionality you would expect, along with "Match Case",
-"Whole Word", "[Regex](#regex-and-lua-pattern-syntax)", and "In Files" options.
-The pane also stores find and replace history, up to 10 entries for each. As you
-search, Textadept can automatically highlight all instances of found text in the
-current buffer by setting [`ui.find.highlight_all_matches`][]. For example, in
-your *~/.textadept/init.lua*:
+You can summon the find & replace pane via `Ctrl+F` on Windows, Linux and BSD, `⌘F` on macOS,
+and `M-F` or `M-S-F` in the terminal version. It has the usual find and replace functionality you
+would expect, along with "Match Case", "Whole Word", "[Regex](#regex-and-lua-pattern-syntax)", and
+"In Files" options. The pane also stores find and replace history, up to 10 entries for each. As
+you search, Textadept can automatically highlight all instances of found text in the current buffer
+by setting [`ui.find.highlight_all_matches`][]. For example, in your *~/.textadept/init.lua*:
ui.find.highlight_all_matches = true
@@ -524,27 +473,26 @@ your *~/.textadept/init.lua*:
While the pane is open in the GUI, the following key bindings apply:
-* Perform "Find Next" and "Find Prev" in the "Find" entry via `Enter` and
- `Shift+Enter`, respectively.
-* Perform "Replace" and "Replace All" in the "Replace" entry via `Enter` and
- `Shift+Enter`, respectively. When the "Regex" find option is enabled,
-
- + `\`*`n`* in the "Replace" entry represents the *n*th captured matching
- region's text, and `\0` represents all matched text.
- + `\U` and `\L` converts everything up to the next `\L`, `\U`, or `\E` to
- uppercase and lowercase, respectively. (`\E` turns off conversion.)
- + `\u` and `\l` converts the next character to uppercase and lowercase,
- respectively. These may appear within `\U` and `\L` constructs.
-
-* For at least the English locale, toggle the find options using their button
- mnemonics: `Alt+M`, `Alt+W`, `Alt+X`, `Alt+I` on Windows, Linux, and BSD, and
- `⌘M`, `⌘W`, `⌘X`, and `⌘I`, respectively, on macOS.
-* Cycle through find/replace history via `Up` and `Down` on Windows, Linux, BSD,
- and the terminal version, and `⇡` and `⇣` on macOS.
+* Perform "Find Next" and "Find Prev" in the "Find" entry via `Enter` and `Shift+Enter`,
+ respectively.
+* Perform "Replace" and "Replace All" in the "Replace" entry via `Enter` and `Shift+Enter`,
+ respectively. When the "Regex" find option is enabled,
+
+ + `\`*`n`* in the "Replace" entry represents the *n*th captured matching region's text, and
+ `\0` represents all matched text.
+ + `\U` and `\L` converts everything up to the next `\L`, `\U`, or `\E` to uppercase and
+ lowercase, respectively. (`\E` turns off conversion.)
+ + `\u` and `\l` converts the next character to uppercase and lowercase, respectively. These
+ may appear within `\U` and `\L` constructs.
+
+* For at least the English locale, toggle the find options using their button mnemonics: `Alt+M`,
+ `Alt+W`, `Alt+X`, `Alt+I` on Windows, Linux, and BSD, and `⌘M`, `⌘W`, `⌘X`, and `⌘I`,
+ respectively, on macOS.
+* Cycle through find/replace history via `Up` and `Down` on Windows, Linux, BSD, and the terminal
+ version, and `⇡` and `⇣` on macOS.
* Hide the pane via `Esc`.
-While the pane is open in the terminal version, the following key bindings
-apply:
+While the pane is open in the terminal version, the following key bindings apply:
* Switch between "Find" and "Replace" entries via `Down` and `Up`.
* Toggle between "Find Next" and "Find Prev" in the "Find" entry via `Tab`.
@@ -555,51 +503,44 @@ apply:
* Erase the contents of the focused entry via `^U`.
* Hide the pane via `Esc`.
-When the pane is closed, you can quickly perform "Find Next", "Find Prev",
-"Replace", and "Replace All" via `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, and
-`Ctrl+Alt+Shift+R`, respectively, on Windows, Linux, and BSD; `⌘G`, `⌘⇧G`, `^R`,
-and `^⇧R`, respectively, on macOS; and `M-G`, `M-S-G`, `M-R`, and `M-S-R` in the
-terminal version.
+When the pane is closed, you can quickly perform "Find Next", "Find Prev", "Replace", and
+"Replace All" via `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, and `Ctrl+Alt+Shift+R`, respectively,
+on Windows, Linux, and BSD; `⌘G`, `⌘⇧G`, `^R`, and `^⇧R`, respectively, on macOS; and
+`M-G`, `M-S-G`, `M-R`, and `M-S-R` in the terminal version.
-**Tip:** by default, "Replace All" replaces all text in the buffer. Selecting a
-contiguous block of text and then performing "Replace All" replaces all text
-in that selection only. Textadept does not currently support "Replace All"
-within non-contiguous selections (e.g. multiple selections).
+**Tip:** by default, "Replace All" replaces all text in the buffer. Selecting a contiguous block
+of text and then performing "Replace All" replaces all text in that selection only. Textadept does
+not currently support "Replace All" within non-contiguous selections (e.g. multiple selections).
[`ui.find.highlight_all_matches`]: api.html#ui.find.highlight_all_matches
##### Find in Files
-Textadept can search for text within multiple files and directories via
-`Ctrl+Shift+F` on Windows, Linux, and BSD, and `⌘⇧F` on macOS. (The terminal
-version does not have a default key binding for finding in files.) Invoking
-"Find Next" prompts you for a directory to search in. The "Replace" entry has
-been substituted for a "Filter" entry that contains files and directories to
-include or exclude from the search.
-
-A filter consists of a comma-separated list of
-[Lua patterns](#regex-and-lua-pattern-syntax) that match filenames and
-directories to include or exclude. Patterns are inclusive by default. Exclusive
-patterns begin with a '!'. If no inclusive patterns are given, any filename is
-initially considered. As a convenience, file extensions can be specified
-literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also
-matches the Windows directory separator ('[/\\]' is not needed). The default
-filter excludes many common binary files and version control directories from
-searches.
-
-**Tip:** Textadept keeps track of filters set per-directory. You can also set
-per-directory filters in Lua by modifying [`ui.find_in_files_filters`][]. For
-example, in your *~/.textadept/init.lua*:
+Textadept can search for text within multiple files and directories via `Ctrl+Shift+F` on
+Windows, Linux, and BSD, and `⌘⇧F` on macOS. (The terminal version does not have a default
+key binding for finding in files.) Invoking "Find Next" prompts you for a directory to search
+in. The "Replace" entry has been substituted for a "Filter" entry that contains files and
+directories to include or exclude from the search.
+
+A filter consists of a comma-separated list of [Lua patterns](#regex-and-lua-pattern-syntax)
+that match filenames and directories to include or exclude. Patterns are inclusive by
+default. Exclusive patterns begin with a '!'. If no inclusive patterns are given, any filename
+is initially considered. As a convenience, file extensions can be specified literally instead
+of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the Windows directory
+separator ('[/\\]' is not needed). The default filter excludes many common binary files and
+version control directories from searches.
+
+**Tip:** Textadept keeps track of filters set per-directory. You can also set per-directory filters
+in Lua by modifying [`ui.find_in_files_filters`][]. For example, in your *~/.textadept/init.lua*:
-- Only search in certain source directories.
ui.find.find_in_files_filters['/path/to/project'] = {'/include', '/src'}
-After performing a "Find in Files" search, a temporary buffer lists the search
-results. You can use the arrow keys to navigate within the list and press
-`Enter` to jump to a result's location in its respective file. You can also
-double-click on results or jump to the next or previous result via `Ctrl+Alt+G`
-or `Ctrl+Alt+Shift+G`, respectively, on Windows, Linux, and BSD; and `^⌘G` or
-`^⌘⇧G`, respectively, on macOS. (The terminal version does not have default key
+After performing a "Find in Files" search, a temporary buffer lists the search results. You can
+use the arrow keys to navigate within the list and press `Enter` to jump to a result's location
+in its respective file. You can also double-click on results or jump to the next or previous
+result via `Ctrl+Alt+G` or `Ctrl+Alt+Shift+G`, respectively, on Windows, Linux, and BSD; and
+`^⌘G` or `^⌘⇧G`, respectively, on macOS. (The terminal version does not have default key
bindings for these actions.)
![Find in Files](images/findinfiles.png)
@@ -608,20 +549,18 @@ bindings for these actions.)
##### Incremental Find
-Textadept searches for text incrementally as you type when you summon the find &
-replace pane via `Ctrl+Alt+F` on Windows, Linux, and BSD, `^⌘F` on macOS, and
-`M-^F` in the terminal version. All of the find options apply except for
-"In Files".
+Textadept searches for text incrementally as you type when you summon the find & replace pane
+via `Ctrl+Alt+F` on Windows, Linux, and BSD, `^⌘F` on macOS, and `M-^F` in the terminal
+version. All of the find options apply except for "In Files".
#### Command Entry
-The versatile command entry has many different roles. Its primary role is to
-execute Lua commands and interact with Textadept's internal Lua state. In
-another context it filters text through shell commands. [Lua extensions][] allow
-it to do even more. Like the find & replace pane, the command entry pops in and
-out as you wish. Each role has its own history that can be cycled through via
-the `Up` and `Down` key bindings on Windows, Linux, BSD, and the terminal
-version, and `⇡` and `⇣` on macOS.
+The versatile command entry has many different roles. Its primary role is to execute Lua commands
+and interact with Textadept's internal Lua state. In another context it filters text through
+shell commands. [Lua extensions][] allow it to do even more. Like the find & replace pane,
+the command entry pops in and out as you wish. Each role has its own history that can be cycled
+through via the `Up` and `Down` key bindings on Windows, Linux, BSD, and the terminal version,
+and `⇡` and `⇣` on macOS.
[Lua extensions]: api.html#ui.command_entry
@@ -629,46 +568,41 @@ version, and `⇡` and `⇣` on macOS.
![Command Entry](images/commandentry.png)
-You can open the Lua command entry via `Ctrl+E` on Windows, Linux, and BSD,
-`⌘E` on macOS, and `M-C` in the terminal version. It acts very similarly to
-Lua's interactive prompt. Type in the Lua command or code to run and press
-`Enter` to invoke or run it. Textadept's [Lua API][] contains all of the
-application's built-in commands. For convenience, the contents of the
-[`buffer`][], [`view`][], [`ui`][], and [`textadept`][] tables are considered to
-be global variables, the first parameter to `buffer` and `view` functions may be
-omitted, and function call parentheses can also be omitted. For example, instead
-of entering `buffer:append_text('foo')`, you can enter `append_text('foo')`.
-Instead of `view:split()`, you can simply use `split`. These convenience
-facilities are not available in normally executed Lua code, such as code in
+You can open the Lua command entry via `Ctrl+E` on Windows, Linux, and BSD, `⌘E` on macOS, and
+`M-C` in the terminal version. It acts very similarly to Lua's interactive prompt. Type in the Lua
+command or code to run and press `Enter` to invoke or run it. Textadept's [Lua API][] contains
+all of the application's built-in commands. For convenience, the contents of the [`buffer`][],
+[`view`][], [`ui`][], and [`textadept`][] tables are considered to be global variables, the
+first parameter to `buffer` and `view` functions may be omitted, and function call parentheses
+can also be omitted. For example, instead of entering `buffer:append_text('foo')`, you can
+enter `append_text('foo')`. Instead of `view:split()`, you can simply use `split`. These
+convenience facilities are not available in normally executed Lua code, such as code in
*~/.textadept/init.lua*.
-**Warning:** if you try to cause instability of Textadept's Lua state, you will
-probably succeed, so be careful.
+**Warning:** if you try to cause instability of Textadept's Lua state, you will probably succeed,
+so be careful.
The following key bindings apply in the Lua command entry:
-* Show a documentation popup for the command under or behind the caret via
- `Ctrl+H` on Windows, Linux, and BSD, `^H` on macOS, and `M-H` or `M-S-H` in
- the terminal version.
-* Show completion candidates for Lua variables, tables, functions, and fields
- via `Tab` on Windows, Linux, BSD, and the terminal version, and `⇥` on macOS.
- Use the arrow keys to make a selection and press `Enter` to insert it.
+* Show a documentation popup for the command under or behind the caret via `Ctrl+H` on Windows,
+ Linux, and BSD, `^H` on macOS, and `M-H` or `M-S-H` in the terminal version.
+* Show completion candidates for Lua variables, tables, functions, and fields via `Tab` on
+ Windows, Linux, BSD, and the terminal version, and `⇥` on macOS. Use the arrow keys to
+ make a selection and press `Enter` to insert it.
![Command Completion](images/commandentrycompletion.png)
-You can specify on the command line Lua commands and code to run on startup
-using the `-e` and `--execute` command line argument. This is useful when you
-want to run dynamic commands that do not belong in *~/.textadept/init.lua*.
+You can specify on the command line Lua commands and code to run on startup using the `-e` and
+`--execute` command line argument. This is useful when you want to run dynamic commands that
+do not belong in *~/.textadept/init.lua*.
-**Tip:** a side-effect of single-instance functionality in the GUI version of
-Textadept is that you can remotely control the original instance of Textadept.
-For example:
+**Tip:** a side-effect of single-instance functionality in the GUI version of Textadept is that
+you can remotely control the original instance of Textadept. For example:
ta ~/.textadept/init.lua &
ta -e "events.emit(events.FIND, 'require')"
-This will search for the first instance of the word "require" in the current
-file.
+This will search for the first instance of the word "require" in the current file.
[Lua API]: api.html
[`buffer`]: api.html#buffer
@@ -678,161 +612,141 @@ file.
##### Shell Command Entry and Filtering Text
-You can filter text through shell commands via `Ctrl+|` on Windows, Linux, and
-BSD, `⌘|` on macOS, and `^\` in the terminal version. An example would be
-running the shell command `sort`, which accepts lines in a buffer as standard
-input (stdin), sorts those lines, and then emits them to standard output
-(stdout), which Textadept replaces the original input text with.
-[`textadept.editing.filter_through()`][] describes how this feature determines
-stdin.
+You can filter text through shell commands via `Ctrl+|` on Windows, Linux, and BSD, `⌘|`
+on macOS, and `^\` in the terminal version. An example would be running the shell command
+`sort`, which accepts lines in a buffer as standard input (stdin), sorts those lines, and then
+emits them to standard output (stdout), which Textadept replaces the original input text with.
+[`textadept.editing.filter_through()`][] describes how this feature determines stdin.
[`textadept.editing.filter_through()`]: api.html#textadept.editing.filter_through
#### Statusbar
-The statusbar consists of two sections. The left section displays temporary
-status messages, while the right section shows buffer status information. Buffer
-status information includes:
+The statusbar consists of two sections. The left section displays temporary status messages,
+while the right section shows buffer status information. Buffer status information includes:
* The current line and column number.
* The lexer language name.
-* The line ending mode, or EOL mode, which is either CRLF ("\r\n") or LF ('\n').
- Line endings are the characters that separate lines.
-* The indentation settings, which are a combination of an indentation character
- (either a tab or a space) and an indentation size (a measure of how many space
- characters are in one level of indentation). If tabs are used for indentation,
- then the indentation size is the number of space characters to draw for each
- tab character.
-* The buffer's encoding. File and buffer encoding specifies how to interpret
- text bytes for display.
+* The line ending mode, or EOL mode, which is either CRLF ("\r\n") or LF ('\n'). Line endings
+ are the characters that separate lines.
+* The indentation settings, which are a combination of an indentation character (either a tab
+ or a space) and an indentation size (a measure of how many space characters are in one level
+ of indentation). If tabs are used for indentation, then the indentation size is the number
+ of space characters to draw for each tab character.
+* The buffer's encoding. File and buffer encoding specifies how to interpret text bytes for
+ display.
![Document Statusbar](images/docstatusbar.png)
---------------------------------------------------------------------------------
+---
### Working with Files and Projects
---------------------------------------------------------------------------------
+---
Textadept allows you to open files using a variety of methods:
-* Open, using a standard file chooser dialog, one or more files in a single
- directory via `Ctrl+O` on Windows, Linux, and BSD, `⌘O` on macOS, and `^O` in
- the terminal version.
-* Open, using a quick open dialog, one or more files in the current project or
- Textadept's current working directory via `Ctrl+Alt+Shift+P` on Windows,
- Linux, and BSD, `^⌘⇧P` on macOS, and `M-^P` in the terminal version. Typing
- part of any filename filters the list, with spaces being wildcards. The arrow
- keys move the selection up and down. Holding down `Shift` while pressing the
- arrow keys selects multiple files, as does holding down `Ctrl` while clicking.
- Pressing `Enter` or selecting `OK` opens all selected files. Double-clicking
+* Open, using a standard file chooser dialog, one or more files in a single directory via
+ `Ctrl+O` on Windows, Linux, and BSD, `⌘O` on macOS, and `^O` in the terminal version.
+* Open, using a quick open dialog, one or more files in the current project or Textadept's
+ current working directory via `Ctrl+Alt+Shift+P` on Windows, Linux, and BSD, `^⌘⇧P` on
+ macOS, and `M-^P` in the terminal version. Typing part of any filename filters the list,
+ with spaces being wildcards. The arrow keys move the selection up and down. Holding down
+ `Shift` while pressing the arrow keys selects multiple files, as does holding down `Ctrl`
+ while clicking. Pressing `Enter` or selecting `OK` opens all selected files. Double-clicking
on a single file opens it. (The terminal requires pressing `Enter`.)
-* Open, using a quick open dialog, one or more files in the directory of the
- currently opened file via `Ctrl+Alt+Shift+O` on Windows, Linux, and BSD,
- `^⌘⇧O` on macOS, and `M-S-O` in the terminal version.
-* Open a file by dragging it from a file manager and dropping it into one of
- Textadept's views.
-* Open a recently opened file from a list of recent files via `Ctrl+Alt+O` on
- Windows, Linux, and BSD, `^⌘O` on macOS, and `M-^O` in the terminal version.
-* Open, using a quick open dialog, one or more files in *~/.textadept/* via
- `Ctrl+U` on Windows, Linux, and BSD, `⌘U` on macOS, and `^U` in the terminal
- version.
-* Reopen the currently opened file, discarding any unsaved changes, via
- `Ctrl+Shift+O` on Windows, Linux, and BSD, `⌘⇧O` on macOS, and `M-O` in the
- terminal version. Textadept will prompt you to reload a file if the editor
- detects it has been modified externally.
+* Open, using a quick open dialog, one or more files in the directory of the currently opened
+ file via `Ctrl+Alt+Shift+O` on Windows, Linux, and BSD, `^⌘⇧O` on macOS, and `M-S-O`
+ in the terminal version.
+* Open a file by dragging it from a file manager and dropping it into one of Textadept's views.
+* Open a recently opened file from a list of recent files via `Ctrl+Alt+O` on Windows, Linux,
+ and BSD, `^⌘O` on macOS, and `M-^O` in the terminal version.
+* Open, using a quick open dialog, one or more files in *~/.textadept/* via `Ctrl+U` on Windows,
+ Linux, and BSD, `⌘U` on macOS, and `^U` in the terminal version.
+* Reopen the currently opened file, discarding any unsaved changes, via `Ctrl+Shift+O` on Windows,
+ Linux, and BSD, `⌘⇧O` on macOS, and `M-O` in the terminal version. Textadept will prompt
+ you to reload a file if the editor detects it has been modified externally.
![Quick Open](images/snapopen.png)
-When it comes to projects, Textadept's only concept of a project is a parent
-directory under a recognized form of version control (Git, Mercurial, SVN,
-Bazaar, and Fossil). There is no "Open Project" action. Textadept can work with
-multiple projects at once, since the current project depends largely on context.
-The current project is determined as follows:
-
-1. If the current buffer is a file, its parent directory is searched for a
- version control directory. If none is found, that directory's parent
- directory is searched next, and so on. If a version control directory is
- found, its parent directory is the current project.
-2. If Textadept's current working directory (cwd) contains a version control
- directory, that cwd is the current project. Otherwise, the cwd's parent
- directory is searched, just like in step 1.
+When it comes to projects, Textadept's only concept of a project is a parent directory under
+a recognized form of version control (Git, Mercurial, SVN, Bazaar, and Fossil). There is no
+"Open Project" action. Textadept can work with multiple projects at once, since the current
+project depends largely on context. The current project is determined as follows:
+
+1. If the current buffer is a file, its parent directory is searched for a version control
+ directory. If none is found, that directory's parent directory is searched next, and so
+ on. If a version control directory is found, its parent directory is the current project.
+2. If Textadept's current working directory (cwd) contains a version control directory, that cwd
+ is the current project. Otherwise, the cwd's parent directory is searched, just like in step 1.
3. If no version control directory is found, there is no current project.
-**Tip:** you can specify Textadept's current working directory by passing it on
-the command line when running the application. This effectively starts Textadept
-with a "default project".
+**Tip:** you can specify Textadept's current working directory by passing it on the command
+line when running the application. This effectively starts Textadept with a "default project".
-By default, Textadept's quick open dialog displays nearly all types of files,
-and only the first 1000 files it finds. You can assign a project or
-directory-specific filter that indicates which files to display for that project
-or directory by modifying [`io.quick_open_filters`][], and you can specify a
-different maximum file list size that applies to all projects and directories by
-setting [`io.quick_open_max`][]. For example, in your *~/.textadept/init.lua*:
+By default, Textadept's quick open dialog displays nearly all types of files, and only the first
+1000 files it finds. You can assign a project or directory-specific filter that indicates which
+files to display for that project or directory by modifying [`io.quick_open_filters`][], and
+you can specify a different maximum file list size that applies to all projects and directories
+by setting [`io.quick_open_max`][]. For example, in your *~/.textadept/init.lua*:
io.quick_open_filters['/path/to/project'] = {'/include', '/src'}
io.quick_open_max = 10000 -- support huge projects
-A filter consists of a comma-separated list of
-[Lua patterns](#regex-and-lua-pattern-syntax) that match filenames and
-directories to include or exclude. Patterns are inclusive by default. Exclusive
-patterns begin with a '!'. If no inclusive patterns are given, any filename is
-initially considered. As a convenience, file extensions can be specified
-literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also
-matches the Windows directory separator ('[/\\]' is not needed). The default
-filter excludes many common binary files and version control directories from
-searches.
-
-You can mimic a more traditional approach to projects by saving and loading
-project-specific sessions via the "File > Save Session..." and
-"File > Load Session..." menu items, respectively. A session can be loaded on
-startup using the `-s` or `--session` command line argument.
+A filter consists of a comma-separated list of [Lua patterns](#regex-and-lua-pattern-syntax)
+that match filenames and directories to include or exclude. Patterns are inclusive by
+default. Exclusive patterns begin with a '!'. If no inclusive patterns are given, any filename
+is initially considered. As a convenience, file extensions can be specified literally instead
+of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the Windows directory
+separator ('[/\\]' is not needed). The default filter excludes many common binary files and
+version control directories from searches.
+
+You can mimic a more traditional approach to projects by saving and loading project-specific
+sessions via the "File > Save Session..." and "File > Load Session..." menu items, respectively. A
+session can be loaded on startup using the `-s` or `--session` command line argument.
[`io.quick_open_filters`]: api.html#io.quick_open_filters
[`io.quick_open_max`]: api.html#io.quick_open_max
##### Language
-When Textadept opens a file, it automatically attempts to identify the
-programming language associated with that file and assigns a lexer to perform
-syntax highlighting of the file's contents. The identification process is as
-follows:
+When Textadept opens a file, it automatically attempts to identify the programming language
+associated with that file and assigns a lexer to perform syntax highlighting of the file's
+contents. The identification process is as follows:
1. The first line of the file is checked against any Lua patterns in
- [`textadept.file_types.patterns`][]. If there is a match, the lexer
- associated with that matching pattern is used.
+ [`textadept.file_types.patterns`][]. If there is a match, the lexer associated with that
+ matching pattern is used.
2. The file's extension is checked against any of the extensions in
- [`textadept.file_types.extensions`][]. If there is a match, the lexer
- associated with that matching extension is used. If the file does not have
- an extension, the entire file name is used in the check.
+ [`textadept.file_types.extensions`][]. If there is a match, the lexer associated with that
+ matching extension is used. If the file does not have an extension, the entire file name is
+ used in the check.
-You can associate first line patterns, file extensions, and file names with
-lexers by modifying [`textadept.file_types.patterns`][] and
-[`textadept.file_types.extensions`][]. For example, in your
-*~/.textadept/init.lua*:
+You can associate first line patterns, file extensions, and file names with lexers by modifying
+[`textadept.file_types.patterns`][] and [`textadept.file_types.extensions`][]. For example,
+in your *~/.textadept/init.lua*:
textadept.file_types.patterns['^#!.+/zsh'] = 'bash'
textadept.file_types.extensions.luadoc = 'lua'
-Textadept has lexers for more than 100 different programming languages and
-recognizes hundreds of file types. In the event that your programming language
-is not understood, you can write a [lexer][] for it, place that lexer in your
-*~/.textadept/lexers/* directory, and add an extension and/or pattern for it.
+Textadept has lexers for more than 100 different programming languages and recognizes hundreds
+of file types. In the event that your programming language is not understood, you can write a
+[lexer][] for it, place that lexer in your *~/.textadept/lexers/* directory, and add an extension
+and/or pattern for it.
-For a given lexer name, Textadept attempts to find, in order, that lexer from
-the following locations:
+For a given lexer name, Textadept attempts to find, in order, that lexer from the following
+locations:
1. Your *~/.textadept/lexers/* directory.
2. Textadept's *lexers/* directory.
-**Tip:** placing lexers in your user data directory avoids the possibility of
-you overwriting them when you update Textadept. These lexers also take
-precedence over the ones installed with Textadept.
+**Tip:** placing lexers in your user data directory avoids the possibility of you overwriting
+them when you update Textadept. These lexers also take precedence over the ones installed
+with Textadept.
-You can manually change a buffer's lexer via `Ctrl+Shift+L` on Windows, Linux,
-and BSD, `⌘⇧L` on macOS, and `M-S-L` in the terminal version. Typing part of a
-lexer name in the dialog filters the list, with spaces being wildcards. The
-arrow keys move the selection up and down. Pressing `Enter`, selecting `OK`, or
-double-clicking on a lexer assigns it to the current buffer. (The terminal
-requires pressing `Enter`.)
+You can manually change a buffer's lexer via `Ctrl+Shift+L` on Windows, Linux, and BSD, `⌘⇧L`
+on macOS, and `M-S-L` in the terminal version. Typing part of a lexer name in the dialog filters
+the list, with spaces being wildcards. The arrow keys move the selection up and down. Pressing
+`Enter`, selecting `OK`, or double-clicking on a lexer assigns it to the current buffer. (The
+terminal requires pressing `Enter`.)
[`textadept.file_types.patterns`]: api.html#textadept.file_types.patterns
[`textadept.file_types.extensions`]: api.html#textadept.file_types.extensions
@@ -840,41 +754,37 @@ requires pressing `Enter`.)
##### Encoding
-Textadept has the ability to work with files encoded in one of many different
-encodings, but by default it only attempts to read UTF-8, ASCII, CP1252, and
-UTF-16 files, in that order. If you work with files that have other encodings,
-you will need to add them to [`io.encodings`][], Textadept's known encoding
-list, before attempting to open one. For example, in your
-*~/.textadept/init.lua*:
+Textadept has the ability to work with files encoded in one of many different encodings, but by
+default it only attempts to read UTF-8, ASCII, CP1252, and UTF-16 files, in that order. If you work
+with files that have other encodings, you will need to add them to [`io.encodings`][], Textadept's
+known encoding list, before attempting to open one. For example, in your *~/.textadept/init.lua*:
io.encodings[#io.encodings + 1] = 'UTF-32'
table.insert(io.encodings, 3, 'Macintosh') -- before CP1252
You can convert a buffer's encoding using the "Buffer > Encoding" menu or
-[`buffer.set_encoding()`][]. You can extend the menu to include more encodings.
-For example, in your *~/.textadept/init.lua*:
+[`buffer.set_encoding()`][]. You can extend the menu to include more encodings. For example,
+in your *~/.textadept/init.lua*:
local menu = textadept.menu.menubar[_L['Buffer']][_L['Encoding']]
local encoding = 'UTF-32'
menu[#menu + 1] = {encoding, function() buffer:set_encoding(encoding) end}
-The default encoding for new buffers is UTF-8, due to its wide support in other
-text editors and all modern operating systems.
+The default encoding for new buffers is UTF-8, due to its wide support in other text editors
+and all modern operating systems.
[`io.encodings`]: api.html#io.encodings
[`buffer.set_encoding()`]: api.html#buffer.set_encoding
##### Buffer Settings
-Textadept attempts to auto-detect a file's line end mode (EOL mode), falling
-back on CRLF ("\r\n") by default on Windows, and LF ('\n') on all other
-platforms. You can manually change the line ending mode using the
-"Buffer > EOL Mode" menu.
+Textadept attempts to auto-detect a file's line end mode (EOL mode), falling back on CRLF
+("\r\n") by default on Windows, and LF ('\n') on all other platforms. You can manually change
+the line ending mode using the "Buffer > EOL Mode" menu.
-Textadept does not attempt to auto-detect a file's indentation. The default
-indentation setting is two spaces, but you can specify your preferred
-indentation settings globally, and on a language-specific basis. For example,
-in your *~/.textadept/init.lua*:
+Textadept does not attempt to auto-detect a file's indentation. The default indentation setting
+is two spaces, but you can specify your preferred indentation settings globally, and on a
+language-specific basis. For example, in your *~/.textadept/init.lua*:
-- Default indentation settings for all buffers.
buffer.use_tabs = true
@@ -893,75 +803,65 @@ in your *~/.textadept/init.lua*:
You can manually change a buffer's indentation using the following process:
-1. Toggle between using tabs and spaces via `Ctrl+Alt+Shift+T` on Windows,
- Linux, and BSD, `^⇧T` on macOS, and `M-T` or `M-S-T` in the terminal version.
+1. Toggle between using tabs and spaces via `Ctrl+Alt+Shift+T` on Windows, Linux, and BSD,
+ `^⇧T` on macOS, and `M-T` or `M-S-T` in the terminal version.
2. Set the indentation size via the "Buffer > Indentation" menu.
-3. Optionally convert existing indentation to the new indentation settings via
- `Ctrl+Alt+I` on Windows, Linux, and BSD, `^I` on macOS, and `M-I` in the
- terminal version.
+3. Optionally convert existing indentation to the new indentation settings via `Ctrl+Alt+I`
+ on Windows, Linux, and BSD, `^I` on macOS, and `M-I` in the terminal version.
##### View Settings
-Textadept normally does not wrap long lines into view, nor does it show
-whitespace characters. You can toggle line wrapping for the current buffer via
-`Ctrl+Alt+\` on Windows, Linux, and BSD, and `^\` on macOS. You can toggle
-whitespace visibility for the current buffer via `Ctrl+Alt+Shift+S` on Windows,
-Linux, and BSD, and `^⇧S` on macOS. Visible spaces are represented by dots, and
-visible tabs are represented by arrows. (The terminal version does not have
-default key bindings for either of these actions.)
-
-The GUI version of Textadept can show small guiding lines based on indentation
-level, and does so by default. You can toggle the visibility of these guides for
-the current view via `Ctrl+Alt+Shift+I` on Windows, Linux, and BSD, and `^⇧I` on
-macOS.
-
-The GUI version of Textadept also allows you to temporarily increase or decrease
-the font size in the current view. The following key bindings apply for this
-feature:
-
-* Increase the view's font size via `Ctrl+=` on Windows, Linux, and BSD, and
- `⌘=` on macOS.
-* Decrease the view's font size via `Ctrl+-` on Windows, Linux, and BSD, and
- `⌘-` on macOS.
-* Reset the view's font size to its normal value via `Ctrl+0` on Windows, Linux,
- and BSD, and `⌘0` on macOS.
-
---------------------------------------------------------------------------------
+Textadept normally does not wrap long lines into view, nor does it show whitespace characters. You
+can toggle line wrapping for the current buffer via `Ctrl+Alt+\` on Windows, Linux, and BSD, and
+`^\` on macOS. You can toggle whitespace visibility for the current buffer via `Ctrl+Alt+Shift+S`
+on Windows, Linux, and BSD, and `^⇧S` on macOS. Visible spaces are represented by dots,
+and visible tabs are represented by arrows. (The terminal version does not have default key
+bindings for either of these actions.)
+
+The GUI version of Textadept can show small guiding lines based on indentation level, and
+does so by default. You can toggle the visibility of these guides for the current view via
+`Ctrl+Alt+Shift+I` on Windows, Linux, and BSD, and `^⇧I` on macOS.
+
+The GUI version of Textadept also allows you to temporarily increase or decrease the font size
+in the current view. The following key bindings apply for this feature:
+
+* Increase the view's font size via `Ctrl+=` on Windows, Linux, and BSD, and `⌘=` on macOS.
+* Decrease the view's font size via `Ctrl+-` on Windows, Linux, and BSD, and `⌘-` on macOS.
+* Reset the view's font size to its normal value via `Ctrl+0` on Windows, Linux, and BSD, and
+ `⌘0` on macOS.
+
+---
### Adept Editing
---------------------------------------------------------------------------------
+---
-Textadept implements most of the customary key bindings for navigating text
-fields on each platform, including Bash-style bindings on macOS and in the
-terminal version. The editor also implements most of the usual basic editing
-key bindings (e.g. undo, redo, cut, copy, paste, etc.). All of Textadept's
-navigation-related key bindings are listed in the "Movement" section of the
-[key bindings list][]. Textadept's basic editing key bindings are listed in the
-"Edit" section of that list. (They are also shown in the "Edit" menu.)
+Textadept implements most of the customary key bindings for navigating text fields on each
+platform, including Bash-style bindings on macOS and in the terminal version. The editor also
+implements most of the usual basic editing key bindings (e.g. undo, redo, cut, copy, paste,
+etc.). All of Textadept's navigation-related key bindings are listed in the "Movement" section
+of the [key bindings list][]. Textadept's basic editing key bindings are listed in the "Edit"
+section of that list. (They are also shown in the "Edit" menu.)
[key bindings list]: api.html#textadept.keys
#### Brace Matching, Auto-pair, and Typeover
-Textadept automatically highlights matching brace characters when the caret is
-over one of them: '(', ')', '[', ']', '{', or '}'. You can jump to the current
-character's complement via `Ctrl+M` on Windows, Linux, and BSD, `^M` on macOS,
-and `M-M` in the terminal version. You can add highlighting for '<' and '>' by
-modifying [`textadept.editing.brace_matches`][]. For example, in your
-*~/.textadept/init.lua*:
+Textadept automatically highlights matching brace characters when the caret is over one of them:
+'(', ')', '[', ']', '{', or '}'. You can jump to the current character's complement via `Ctrl+M`
+on Windows, Linux, and BSD, `^M` on macOS, and `M-M` in the terminal version. You can add
+highlighting for '<' and '>' by modifying [`textadept.editing.brace_matches`][]. For example,
+in your *~/.textadept/init.lua*:
textadept.editing.brace_matches[string.byte('<')] = true
textadept.editing.brace_matches[string.byte('>')] = true
![Matching Braces](images/matchingbrace.png)
-Since braces often go together in pairs, Textadept automatically inserts the
-complement of opening brace characters you type, deletes that complement if you
-press `Backspace`, and moves over the complement if you type it (as opposed to
-inserting it again). Textadept also exhibits this behavior for single and double
-quote characters ('&apos;' and '&quot;'). You can configure or disable this
-behavior by modifying [`textadept.editing.auto_pairs`][] and
-[`textadept.editing.typeover_chars`][]. For example, in your
-*~/.textadept/init.lua*:
+Since braces often go together in pairs, Textadept automatically inserts the complement of
+opening brace characters you type, deletes that complement if you press `Backspace`, and
+moves over the complement if you type it (as opposed to inserting it again). Textadept also
+exhibits this behavior for single and double quote characters ('&apos;' and '&quot;'). You
+can configure or disable this behavior by modifying [`textadept.editing.auto_pairs`][] and
+[`textadept.editing.typeover_chars`][]. For example, in your *~/.textadept/init.lua*:
-- Auto-pair and typeover '<' and '>'.
textadept.editing.auto_pairs[string.byte('<')] = '>'
@@ -977,18 +877,17 @@ behavior by modifying [`textadept.editing.auto_pairs`][] and
#### Word Highlight
-Textadept can be configured to automatically highlight all occurrences of the
-word under the caret, or all occurrences of the selected word (e.g. a variable
-name), by setting [`textadept.editing.highlight_words`][]. For example, in your
-*~/.textadept/init.lua*:
+Textadept can be configured to automatically highlight all occurrences of the word under
+the caret, or all occurrences of the selected word (e.g. a variable name), by setting
+[`textadept.editing.highlight_words`][]. For example, in your *~/.textadept/init.lua*:
-- Highlight all occurrences of the current word.
textadept.editing.highlight_words = textadept.editing.HIGHLIGHT_CURRENT
-- Highlight all occurrences of the selected word.
textadept.editing.highlight_words = textadept.editing.HIGHLIGHT_SELECTED
-Pressing `Esc` clears highlighting. By default, Textadept does not perform any
-automatic highlighting.
+Pressing `Esc` clears highlighting. By default, Textadept does not perform any automatic
+highlighting.
![Word Highlight](images/wordhighlight.png)
@@ -996,42 +895,38 @@ automatic highlighting.
#### Autocompletion and Documentation
-Textadept provides buffer-based word completion. It can also autocomplete
-symbols for programming languages and display documentation for functions and
-other symbols.
-
-You can show word completion candidates for partially-typed words via
-`Ctrl+Enter` on Windows, Linux, and BSD, `^Esc` on macOS, and `M-Enter` in the
-terminal version. Continuing to type changes the suggested completion. Use the
-arrow keys to navigate within the list and press `Enter` to insert the rest of
-the selected word. By default, the list of completions comes from the current
-buffer. You can configure Textadept to look in all open buffers by setting
-[`textadept.editing.autocomplete_all_words`][]. For example, in
-*~/.textadept/init.lua*:
+Textadept provides buffer-based word completion. It can also autocomplete symbols for programming
+languages and display documentation for functions and other symbols.
+
+You can show word completion candidates for partially-typed words via `Ctrl+Enter` on Windows,
+Linux, and BSD, `^Esc` on macOS, and `M-Enter` in the terminal version. Continuing to type
+changes the suggested completion. Use the arrow keys to navigate within the list and press
+`Enter` to insert the rest of the selected word. By default, the list of completions comes
+from the current buffer. You can configure Textadept to look in all open buffers by setting
+[`textadept.editing.autocomplete_all_words`][]. For example, in *~/.textadept/init.lua*:
textadept.editing.autocomplete_all_words = true
![Word Completion](images/wordcompletion.png)
-For languages that support it, you can show symbol completion candidates at the
-current position via `Ctrl+Space` on Windows, Linux, and BSD, `⌥Esc` on macOS,
-and `^Space` in the terminal version.
+For languages that support it, you can show symbol completion candidates at the current position
+via `Ctrl+Space` on Windows, Linux, and BSD, `⌥Esc` on macOS, and `^Space` in the terminal
+version.
![Autocomplete Lua](images/adeptsense_lua.png)
&nbsp;&nbsp;&nbsp;&nbsp;
![Autocomplete Lua String](images/adeptsense_string.png)
-Also for languages that support it, you can show any known documentation for the
-current symbol via `Ctrl+H` on Windows, Linux, and BSD, `^H` on macOS, and `M-H`
-or `M-S-H` in the terminal version. Textadept has built-in autocompletion and
-documentation support for Lua and C, including for its own Lua API.
+Also for languages that support it, you can show any known documentation for the current symbol
+via `Ctrl+H` on Windows, Linux, and BSD, `^H` on macOS, and `M-H` or `M-S-H` in the terminal
+version. Textadept has built-in autocompletion and documentation support for Lua and C, including
+for its own Lua API.
![Documentation](images/adeptsense_doc.png)
-Textadept's framework for providing symbol autocompletion and documentation
-relies on [autocompleter][] functions and [API files][], which are often
-supplied by [language][] [modules](#modules). You can use this framework to
-write your own autocompletion routines.
+Textadept's framework for providing symbol autocompletion and documentation relies on
+[autocompleter][] functions and [API files][], which are often supplied by [language][]
+[modules](#modules). You can use this framework to write your own autocompletion routines.
[`textadept.editing.autocomplete_all_words`]: api.html#textadept.editing.autocomplete_all_words
[autocompleter]: api.html#textadept.editing.autocompleters
@@ -1040,69 +935,58 @@ write your own autocompletion routines.
#### Text Selections
-Textadept has three kinds of text selections: contiguous, multiple, and
-rectangular.
+Textadept has three kinds of text selections: contiguous, multiple, and rectangular.
You can create contiguous selections as follows:
-* Make an arbitrary selection anchored at the caret by pressing the arrow keys,
- home/end, page up/down, etc. while holding down the `Shift` key, or by simply
- clicking and dragging the mouse.
-* The terminal version can also make an arbitrary selection by entering
- selection mode via `^^` and using normal movement keys. This feature is
- available since some terminals do not recognize `Shift` with movement keys.
- While in selection mode, swap the start and end positions via `^]` in order to
- alter the selection from its opposite side. Exit selection mode by typing
- text, deleting text, performing an action that changes text, or by
- pressing `^^` again.
-* Select the current word via `Ctrl+Shift+D` on Windows, Linux, and BSD, `⌘⇧D`
- on macOS, and `M-S-W` in the terminal version. Repeated use of this action
- selects subsequent occurrences of that word as additional (multiple)
- selections.
-* Select the current line via `Ctrl+Shift+N` on Windows, Linux, and BSD, `⌘⇧N`
- on macOS, and `M-S-N` in the terminal version.
+* Make an arbitrary selection anchored at the caret by pressing the arrow keys, home/end, page
+ up/down, etc. while holding down the `Shift` key, or by simply clicking and dragging the mouse.
+* The terminal version can also make an arbitrary selection by entering selection mode via `^^`
+ and using normal movement keys. This feature is available since some terminals do not recognize
+ `Shift` with movement keys. While in selection mode, swap the start and end positions via
+ `^]` in order to alter the selection from its opposite side. Exit selection mode by typing
+ text, deleting text, performing an action that changes text, or by pressing `^^` again.
+* Select the current word via `Ctrl+Shift+D` on Windows, Linux, and BSD, `⌘⇧D` on macOS, and
+ `M-S-W` in the terminal version. Repeated use of this action selects subsequent occurrences
+ of that word as additional (multiple) selections.
+* Select the current line via `Ctrl+Shift+N` on Windows, Linux, and BSD, `⌘⇧N` on macOS,
+ and `M-S-N` in the terminal version.
* Double click to select a word, and triple-click to select a line.
* Click and optionally drag within the line number margin to select whole lines.
-* Select the current paragraph via `Ctrl+Shift+P` on Windows, Linux, and BSD,
- `⌘⇧P` on macOS, and `M-S-P` in the terminal version. Paragraphs are surrounded
- by one or more blank lines.
-* Select all buffer text via `Ctrl+A` on Windows, Linux, and BSD, `⌘A` on macOS,
- and `M-A` in the terminal version.
-* Select text between matching delimiters (parentheses, brackets, braces, single
- quotes, double-quotes, and back quotes) via `Ctrl+Shift+M` on Windows, Linux,
- and BSD, `^⇧M` on macOS, and `M-S-M` in the terminal version. Repeated use of
- this action toggles the selection of the delimiters themselves.
-* Select between HTML/XML tags via `Ctrl+<` on Windows, Linux, and BSD, `⌘<` on
- macOS, and `M-<` in the terminal version.
-* Select an HTML/XML tag via `Ctrl+>` on Windows, Linux, and BSD, and `⌘>` on
- macOS.
+* Select the current paragraph via `Ctrl+Shift+P` on Windows, Linux, and BSD, `⌘⇧P` on macOS,
+ and `M-S-P` in the terminal version. Paragraphs are surrounded by one or more blank lines.
+* Select all buffer text via `Ctrl+A` on Windows, Linux, and BSD, `⌘A` on macOS, and `M-A`
+ in the terminal version.
+* Select text between matching delimiters (parentheses, brackets, braces, single quotes,
+ double-quotes, and back quotes) via `Ctrl+Shift+M` on Windows, Linux, and BSD, `^⇧M` on
+ macOS, and `M-S-M` in the terminal version. Repeated use of this action toggles the selection
+ of the delimiters themselves.
+* Select between HTML/XML tags via `Ctrl+<` on Windows, Linux, and BSD, `⌘<` on macOS, and
+ `M-<` in the terminal version.
+* Select an HTML/XML tag via `Ctrl+>` on Windows, Linux, and BSD, and `⌘>` on macOS.
You can create multiple selections as follows:
-* Add another selection by holding down `Ctrl`, clicking, and optionally
- dragging the mouse over a range of text.
-* Select as an additional selection the next occurrence of the current word via
- `Ctrl+Shift+D` on Windows, Linux, and BSD, `⌘⇧D` on macOS, and `M-S-W` in the
- terminal version.
+* Add another selection by holding down `Ctrl`, clicking, and optionally dragging the mouse
+ over a range of text.
+* Select as an additional selection the next occurrence of the current word via `Ctrl+Shift+D`
+ on Windows, Linux, and BSD, `⌘⇧D` on macOS, and `M-S-W` in the terminal version.
Textadept mirrors any typed text at each selection.
You can create a rectangular selection as follows:
-* Press the arrow keys, home/end, or page up/down, while holding down
- `Alt+Shift` on Windows, Linux, and BSD, `⌥⇧` on macOS, and `M-S-` in the
- terminal version.
-* Click and drag the mouse while holding down the `Alt` key on Windows, Linux,
- and BSD, and `⌥` on macOS.
-* Click and drag the mouse without holding down any modifiers (thus making a
- normal, multi-line selection), press and hold down the `Alt` key on Windows,
- Linux, and BSD, `⌥` on macOS, and `M-` in the terminal version, and then
- continue dragging the mouse. This feature is available because some window
- managers in Linux consume `Alt+Shift` + arrow keys and `Alt` + mouse drag.
-
-You are permitted to create a zero-width rectangular selection that spans
-multiple lines, and for this kind of selection, Textadept mirrors any typed text
-on all of those lines.
+* Press the arrow keys, home/end, or page up/down, while holding down `Alt+Shift` on Windows,
+ Linux, and BSD, `⌥⇧` on macOS, and `M-S-` in the terminal version.
+* Click and drag the mouse while holding down the `Alt` key on Windows, Linux, and BSD, and
+ `⌥` on macOS.
+* Click and drag the mouse without holding down any modifiers (thus making a normal, multi-line
+ selection), press and hold down the `Alt` key on Windows, Linux, and BSD, `⌥` on macOS, and
+ `M-` in the terminal version, and then continue dragging the mouse. This feature is available
+ because some window managers in Linux consume `Alt+Shift` + arrow keys and `Alt` + mouse drag.
+
+You are permitted to create a zero-width rectangular selection that spans multiple lines,
+and for this kind of selection, Textadept mirrors any typed text on all of those lines.
![Rectangular Selection](images/rectangularselection.png)
&nbsp;&nbsp;&nbsp;&nbsp;
@@ -1110,31 +994,29 @@ on all of those lines.
#### Text Transformations
-Textadept can apply many different transformations to the current word, line,
-and selected text.
-
-* Enclose the current word or selected text within delimiters like parentheses,
- braces, brackets, single quotes, double quotes, or HTML/XML tags using the key
- bindings listed in the "Edit > Selection" submenu.
-* Convert the selected text to upper or lower case via `Ctrl+Alt+U` or
- `Ctrl+Alt+Shift+U`, respectively, on Windows, Linux, and BSD; `^U` or `^⇧U`,
- respectively, on macOS; and `M-^U` or `M-^L` in the terminal version.
-* Increase or decrease the indentation of the selected lines via `Tab` or
- `Shift+Tab`, respectively, on Windows, Linux, and BSD; `⇥` or `⇧⇥`,
- respectively on macOS; and `Tab` or `S-Tab` in the terminal version. You do
- not have to select whole lines; selecting any part of a line is sufficient.
-* Move the current or selected line(s) up or down via `Ctrl+Shift+Up` or
- `Ctrl+Shift+Down`, respectively, on Windows, Linux, and BSD; `^⇧⇡` or `^⇧⇣`,
- respectively, on macOS; and `S-^Up` or `S-^Down` in the terminal version. You
- do not have to select whole lines; selecting any part of a line is sufficient.
-* Comment out code on the current or selected line(s) via `Ctrl+/` on Windows,
- Linux, and BSD, `⌘/` on macOS, and `M-/` in the terminal version. You do not
- have to select whole lines; selecting any part of a line is sufficient.
-
-You can auto-enclose selected text between any typed punctuation character
-(taking into account [`textadept.editing.auto_pairs`][]) by setting
-[`textadept.editing.auto_enclose`][]. For example, in your
-*~/.textadept/init.lua*:
+Textadept can apply many different transformations to the current word, line, and selected text.
+
+* Enclose the current word or selected text within delimiters like parentheses, braces, brackets,
+ single quotes, double quotes, or HTML/XML tags using the key bindings listed in the "Edit >
+ Selection" submenu.
+* Convert the selected text to upper or lower case via `Ctrl+Alt+U` or `Ctrl+Alt+Shift+U`,
+ respectively, on Windows, Linux, and BSD; `^U` or `^⇧U`, respectively, on macOS; and `M-^U`
+ or `M-^L` in the terminal version.
+* Increase or decrease the indentation of the selected lines via `Tab` or `Shift+Tab`,
+ respectively, on Windows, Linux, and BSD; `⇥` or `⇧⇥`, respectively on macOS; and `Tab`
+ or `S-Tab` in the terminal version. You do not have to select whole lines; selecting any part
+ of a line is sufficient.
+* Move the current or selected line(s) up or down via `Ctrl+Shift+Up` or `Ctrl+Shift+Down`,
+ respectively, on Windows, Linux, and BSD; `^⇧⇡` or `^⇧⇣`, respectively, on macOS;
+ and `S-^Up` or `S-^Down` in the terminal version. You do not have to select whole lines;
+ selecting any part of a line is sufficient.
+* Comment out code on the current or selected line(s) via `Ctrl+/` on Windows, Linux, and BSD,
+ `⌘/` on macOS, and `M-/` in the terminal version. You do not have to select whole lines;
+ selecting any part of a line is sufficient.
+
+You can auto-enclose selected text between any typed punctuation character (taking into account
+[`textadept.editing.auto_pairs`][]) by setting [`textadept.editing.auto_enclose`][]. For example,
+in your *~/.textadept/init.lua*:
textadept.editing.auto_enclose = true
@@ -1143,92 +1025,86 @@ You can auto-enclose selected text between any typed punctuation character
#### Navigate Through History
-Textadept records buffer positions within views over time and allows for
-navigating through that history. Navigate backward or forward via `Alt+,` or
-`Alt+.`, respectively, on Windows, Linux, and BSD; `^,` or `^.`, respectively,
-on macOS; and `M-,` or `M-.`, respectively, in the terminal version.
+Textadept records buffer positions within views over time and allows for navigating through
+that history. Navigate backward or forward via `Alt+,` or `Alt+.`, respectively, on Windows,
+Linux, and BSD; `^,` or `^.`, respectively, on macOS; and `M-,` or `M-.`, respectively, in the
+terminal version.
#### Goto Line
-You can jump to a specific line in the current buffer via `Ctrl+J` on Windows,
-Linux, and BSD, `⌘J` on macOS, and `^J` in the terminal version. Enter the line
-number to jump to in the prompt, and press `Enter` or click `OK`.
+You can jump to a specific line in the current buffer via `Ctrl+J` on Windows, Linux, and BSD,
+`⌘J` on macOS, and `^J` in the terminal version. Enter the line number to jump to in the
+prompt, and press `Enter` or click `OK`.
#### Bookmarks
-Bookmarks are markers attached to lines of interest. They move in sync with the
-lines they were added to as buffer text is inserted and deleted. Bookmarks show
-up in the left-hand margin after line numbers. Textadept allows you to bookmark
-lines and jump back to them later. The following key bindings apply for
-bookmarks:
+Bookmarks are markers attached to lines of interest. They move in sync with the lines they were
+added to as buffer text is inserted and deleted. Bookmarks show up in the left-hand margin
+after line numbers. Textadept allows you to bookmark lines and jump back to them later. The
+following key bindings apply for bookmarks:
-* Toggle a bookmark on the current line via `Ctrl+F2` on Windows, Linux, and
- BSD, `⌘F2` on macOS, and `F1` in the terminal version.
+* Toggle a bookmark on the current line via `Ctrl+F2` on Windows, Linux, and BSD, `⌘F2`
+ on macOS, and `F1` in the terminal version.
* Jump to the next bookmarked line via `F2`.
-* Jump to the previously bookmarked line via `Shift+F2` on Windows, Linux, and
- BSD, `⇧F2` on macOS, and `F3` in the terminal version.
-* Jump to the bookmarked line selected from a list via `Alt+F2` on Windows,
- Linux, and BSD, `⌥F2` on macOS, and `F4` in the terminal version.
-* Clear all bookmarks in the current buffer via `Ctrl+Shift+F2` on Windows,
- Linux, and BSD, `⌘⇧F2` on macOS, and `F6` in the terminal version.
+* Jump to the previously bookmarked line via `Shift+F2` on Windows, Linux, and BSD, `⇧F2`
+ on macOS, and `F3` in the terminal version.
+* Jump to the bookmarked line selected from a list via `Alt+F2` on Windows, Linux, and BSD,
+ `⌥F2` on macOS, and `F4` in the terminal version.
+* Clear all bookmarks in the current buffer via `Ctrl+Shift+F2` on Windows, Linux, and BSD,
+ `⌘⇧F2` on macOS, and `F6` in the terminal version.
#### Macros
-Macros allow you to quickly record a series of edits and play them back without
-having to write a custom Lua script. The following key bindings apply for
-macros:
+Macros allow you to quickly record a series of edits and play them back without having to write
+a custom Lua script. The following key bindings apply for macros:
* Start recording a macro via `F9`.
-* Stop recording a macro via `Shift+F9` on Windows, Linux, and BSD, `⇧F9` on
- macOS, and `F10` in the terminal version.
-* Play back the most recently recorded macro via `Alt+F9` on Windows, Linux, and
- BSD, `⌥F9` on macOS, and `F12` in the terminal version.
+* Stop recording a macro via `Shift+F9` on Windows, Linux, and BSD, `⇧F9` on macOS, and `F10`
+ in the terminal version.
+* Play back the most recently recorded macro via `Alt+F9` on Windows, Linux, and BSD, `⌥F9`
+ on macOS, and `F12` in the terminal version.
-You can use the "Tools > Macros" menu to save the most recently recorded macro
-to a file, and to load one for playback on demand.
+You can use the "Tools > Macros" menu to save the most recently recorded macro to a file,
+and to load one for playback on demand.
#### Snippets
-Snippets are dynamic text templates that can be inserted into the buffer on
-demand. They are composed of any combination of plain text, placeholders for
-interactive input, mirrors and transforms for interactive input, and arbitrary
-Lua and Shell code. Snippets eliminate the need for typing repetitive code
-constructs like class definitions, getters and setters, control structures, API
-calls, and more.
+Snippets are dynamic text templates that can be inserted into the buffer on demand. They
+are composed of any combination of plain text, placeholders for interactive input, mirrors
+and transforms for interactive input, and arbitrary Lua and Shell code. Snippets eliminate
+the need for typing repetitive code constructs like class definitions, getters and setters,
+control structures, API calls, and more.
![Snippet](images/snippet.png)
&nbsp;&nbsp;&nbsp;&nbsp;
![Snippet Expanded](images/snippet2.png)
A snippet has a trigger word associated with snippet text in the [`snippets`][]
-table. Language-specific snippets are in a subtable assigned to their language's
-lexer name, and are often supplied by [language][] [modules](#modules). Snippets
-may also be the contents of files in a snippet directory, with file names being
-the trigger word. The [snippets documentation][] describes snippets and their
-contents in more detail.
+table. Language-specific snippets are in a subtable assigned to their language's lexer name, and
+are often supplied by [language][] [modules](#modules). Snippets may also be the contents of files
+in a snippet directory, with file names being the trigger word. The [snippets documentation][]
+describes snippets and their contents in more detail.
The following key bindings apply for snippets:
-* Insert a snippet from a list of available snippets via `Ctrl+Shift+K` on
- Windows, Linux, and BSD, `⌥⇧⇥` on macOS, and `M-S-K` in the terminal version.
- Typing part of a snippet trigger in the dialog filters the list, with spaces
- being wildcards. The arrow keys move the selection up and down. Pressing
- `Enter`, selecting `OK`, or double-clicking on a snippet inserts it into the
- current buffer. (The terminal requires pressing `Enter`.)
-* Show completion candidates for a partially-typed snippet trigger word via
- `Ctrl+K` on Windows, Linux, and BSD, `⌥⇥` on macOS, and `M-K` in the terminal
- version. Continuing to type changes the suggested completion. Use the arrow
- keys to navigate within the list and press `Enter` to insert the rest of the
- trigger word.
-* Insert a snippet based on the trigger word behind the caret via `Tab` on
- Windows, Linux, BSD, and in the terminal version, and `⇥` on macOS. You can
- insert another snippet within an active snippet. A previously active snippet
- will pick up where it left off after a nested snippet finishes.
-* Navigate to the next placeholder in the current snippet via `Tab` on Windows,
- Linux, BSD, and in the terminal version, and `⇥` on macOS.
-* Navigate to the previous placeholder in the current snippet via `Shift+Tab` on
- Windows, Linux, and BSD, `⇧⇥` on macOS, and `S-Tab` in the terminal version.
- If there is no previous placeholder, the current snippet is canceled.
+* Insert a snippet from a list of available snippets via `Ctrl+Shift+K` on Windows, Linux, and
+ BSD, `⌥⇧⇥` on macOS, and `M-S-K` in the terminal version. Typing part of a snippet
+ trigger in the dialog filters the list, with spaces being wildcards. The arrow keys move
+ the selection up and down. Pressing `Enter`, selecting `OK`, or double-clicking on a snippet
+ inserts it into the current buffer. (The terminal requires pressing `Enter`.)
+* Show completion candidates for a partially-typed snippet trigger word via `Ctrl+K` on Windows,
+ Linux, and BSD, `⌥⇥` on macOS, and `M-K` in the terminal version. Continuing to type
+ changes the suggested completion. Use the arrow keys to navigate within the list and press
+ `Enter` to insert the rest of the trigger word.
+* Insert a snippet based on the trigger word behind the caret via `Tab` on Windows, Linux,
+ BSD, and in the terminal version, and `⇥` on macOS. You can insert another snippet within
+ an active snippet. A previously active snippet will pick up where it left off after a nested
+ snippet finishes.
+* Navigate to the next placeholder in the current snippet via `Tab` on Windows, Linux, BSD,
+ and in the terminal version, and `⇥` on macOS.
+* Navigate to the previous placeholder in the current snippet via `Shift+Tab` on Windows, Linux,
+ and BSD, `⇧⇥` on macOS, and `S-Tab` in the terminal version. If there is no previous
+ placeholder, the current snippet is canceled.
* Cancel the current snippet via `Esc`.
[`snippets`]: api.html#_G.snippets
@@ -1237,93 +1113,83 @@ The following key bindings apply for snippets:
#### Code Folding
-Textadept can temporarily hide blocks of code in supported languages. Markers in
-the margin to the left of code denote fold points. Clicking on those markers
-toggles folding. You can toggle folding for the current block via `Ctrl+*` on
-Windows, Linux, and BSD, `⌘*` on macOS, and `M-*` in the terminal version.
+Textadept can temporarily hide blocks of code in supported languages. Markers in the margin to
+the left of code denote fold points. Clicking on those markers toggles folding. You can toggle
+folding for the current block via `Ctrl+*` on Windows, Linux, and BSD, `⌘*` on macOS, and
+`M-*` in the terminal version.
![Folding](images/folding.png)
#### Virtual Space
-Textadept normally constrains the caret to remain within text lines. Enabling
-virtual space allows you to move the caret into the space beyond the ends of
-lines. Toggle virtual space via `Ctrl+Alt+Shift+V` on Windows, Linux, and BSD,
-and `^⇧V` in macOS. (The terminal version does not have a default key binding
-for toggling virtual space.)
+Textadept normally constrains the caret to remain within text lines. Enabling virtual space
+allows you to move the caret into the space beyond the ends of lines. Toggle virtual space via
+`Ctrl+Alt+Shift+V` on Windows, Linux, and BSD, and `^⇧V` in macOS. (The terminal version does
+not have a default key binding for toggling virtual space.)
#### Key Bindings
-Key bindings are simply commands (Lua functions) assigned to key sequences in
-the [`keys`][] table. Key sequences are composed of an ordered combination of
-modifier keys followed by either the key's inserted character or, if no such
-character exists, the string representation of the key according to
-[`keys.KEYSYMS`][]. Language-specific keys are in a subtable assigned to their
-language's lexer name, and are often supplied by [language][]
-[modules](#modules). Key sequences can also be assigned tables of key bindings
-to create key chains (e.g. Emacs `C-x` prefix). Key bindings can be grouped into
-modes such that while a mode is active, Textadept ignores all key bindings
-outside that mode until the mode is unset (e.g. Vim-style modal editing). The
-[keys documentation][] describes all of this in more detail.
+Key bindings are simply commands (Lua functions) assigned to key sequences in the [`keys`][]
+table. Key sequences are composed of an ordered combination of modifier keys followed by either
+the key's inserted character or, if no such character exists, the string representation of
+the key according to [`keys.KEYSYMS`][]. Language-specific keys are in a subtable assigned to
+their language's lexer name, and are often supplied by [language][] [modules](#modules). Key
+sequences can also be assigned tables of key bindings to create key chains (e.g. Emacs `C-x`
+prefix). Key bindings can be grouped into modes such that while a mode is active, Textadept
+ignores all key bindings outside that mode until the mode is unset (e.g. Vim-style modal
+editing). The [keys documentation][] describes all of this in more detail.
[`keys`]: api.html#keys
[`keys.KEYSYMS`]: api.html#keys.KEYSYMS
[language]: api.html#_M
[keys documentation]: api.html#keys
---------------------------------------------------------------------------------
+---
### Compile, Run, Build, and Test
---------------------------------------------------------------------------------
-
-Textadept knows most of the commands that compile and/or run code in source
-files. It also knows some of the commands that build projects, and you can tell
-the editor how to run your project's test suite. Textadept recognizes many of
-the warning and error messages emitted by those commands and marks them as they
-occur in compile/run/build/test output. Double-clicking on a line with a warning
-or error jumps to its source.
-
-The following key bindings apply for compiling and running source files, and
-for building projects and running tests:
-
-* Compile the current file via `Ctrl+Shift+R` on Windows, Linux, and BSD, `⌘⇧R`
- on macOS, and `M-^R` in the terminal version.
-* Run the current file via `Ctrl+R` on Windows, Linux, and BSD, `⌘R` on macOS,
- and `^R` in the terminal version.
-* Set, using an interactive dialog, the command line arguments for the current
- file's compile and run commands via `Ctrl+Shift+A` on Windows, Linux, and BSD,
- and `⌘⇧A` on macOS. (The terminal version does not have a default key binding
- for setting command line arguments.) Enter the command line arguments for each
- command and press `Enter` or click `OK`.
-* Build the current project via `Ctrl+Shift+B` on Windows, Linux, and BSD, `⌘⇧B`
- on macOS, and `M-^B` in the terminal version.
-* Run tests for the current project via `Ctrl+Shift+T` on Windows, Linux, and
- BSD, `⌘⇧T` on macOS, and `M-^T` in the terminal version.
-* Stop the currently running compile, run, build, or test process via
- `Ctrl+Shift+X` on Windows, Linux, and BSD, `⌘⇧X` on macOS, and `M-^X` in the
- terminal version.
-* Jump to the source of the next recognized warning or error via `Ctrl+Alt+E` on
- Windows, Linux, and BSD, `^⌘E` on macOS, and `M-X` in the terminal version.
-* Jump to the source of the previously recognized warning or error via
- `Ctrl+Alt+Shift+E` on Windows, Linux, and BSD, `^⌘⇧E` on macOS, and `M-S-X` in
- the terminal version.
-* Jump to the source of the recognized warning or error on the current line via
- `Enter`.
+---
+
+Textadept knows most of the commands that compile and/or run code in source files. It also
+knows some of the commands that build projects, and you can tell the editor how to run your
+project's test suite. Textadept recognizes many of the warning and error messages emitted by
+those commands and marks them as they occur in compile/run/build/test output. Double-clicking
+on a line with a warning or error jumps to its source.
+
+The following key bindings apply for compiling and running source files, and for building
+projects and running tests:
+
+* Compile the current file via `Ctrl+Shift+R` on Windows, Linux, and BSD, `⌘⇧R` on macOS,
+ and `M-^R` in the terminal version.
+* Run the current file via `Ctrl+R` on Windows, Linux, and BSD, `⌘R` on macOS, and `^R`
+ in the terminal version.
+* Set, using an interactive dialog, the command line arguments for the current file's compile
+ and run commands via `Ctrl+Shift+A` on Windows, Linux, and BSD, and `⌘⇧A` on macOS. (The
+ terminal version does not have a default key binding for setting command line arguments.) Enter
+ the command line arguments for each command and press `Enter` or click `OK`.
+* Build the current project via `Ctrl+Shift+B` on Windows, Linux, and BSD, `⌘⇧B` on macOS,
+ and `M-^B` in the terminal version.
+* Run tests for the current project via `Ctrl+Shift+T` on Windows, Linux, and BSD, `⌘⇧T`
+ on macOS, and `M-^T` in the terminal version.
+* Stop the currently running compile, run, build, or test process via `Ctrl+Shift+X` on Windows,
+ Linux, and BSD, `⌘⇧X` on macOS, and `M-^X` in the terminal version.
+* Jump to the source of the next recognized warning or error via `Ctrl+Alt+E` on Windows, Linux,
+ and BSD, `^⌘E` on macOS, and `M-X` in the terminal version.
+* Jump to the source of the previously recognized warning or error via `Ctrl+Alt+Shift+E`
+ on Windows, Linux, and BSD, `^⌘⇧E` on macOS, and `M-S-X` in the terminal version.
+* Jump to the source of the recognized warning or error on the current line via `Enter`.
![Runtime Error](images/runerror.png)
-When you execute a compile, run, build, or test command, that command's output
-is printed to a temporary buffer in real-time. You can configure Textadept to
-print output in the background by setting [`textadept.run.run_in_background`][].
-For example, in your *~/.textadept/init.lua*:
+When you execute a compile, run, build, or test command, that command's output is printed to
+a temporary buffer in real-time. You can configure Textadept to print output in the background
+by setting [`textadept.run.run_in_background`][]. For example, in your *~/.textadept/init.lua*:
textadept.run.run_in_background = true
-You can change or add compile, run, build, and test commands by modifying the
-[`textadept.run.compile_commands`][], [`textadept.run.run_commands`][],
-[`textadept.run.build_commands`][], and [`textadept.run.test_commands`][]
-tables, respectively. You can add Lua patterns that recognize warning and error
-output by modifying the [`textadept.run.error_patterns`][] table. For example,
-in your *~/.textadept/init.lua*:
+You can change or add compile, run, build, and test commands by modifying
+the [`textadept.run.compile_commands`][], [`textadept.run.run_commands`][],
+[`textadept.run.build_commands`][], and [`textadept.run.test_commands`][] tables,
+respectively. You can add Lua patterns that recognize warning and error output by modifying the
+[`textadept.run.error_patterns`][] table. For example, in your *~/.textadept/init.lua*:
textadept.run.compile_commands.foo = 'foo "%f"'
textadept.run.run_commands.foo = './"%e"'
@@ -1332,9 +1198,8 @@ in your *~/.textadept/init.lua*:
textadept.run.build_commands['/path/to/project'] = 'make -C src -j4'
textadept.run.test_commands['/path/to/project'] = 'lua tests.lua'
-**Tip:** you can set compile and run commands on a per-filename basis, and these
-commands can contain arguments so that you do not have to invoke
-"Tools > Set Arguments..."
+**Tip:** you can set compile and run commands on a per-filename basis, and these commands can
+contain arguments so that you do not have to invoke "Tools > Set Arguments..."
[`textadept.run.run_in_background`]: api.html#textadept.run.run_in_background
[`textadept.run.compile_commands`]: api.html#textadept.run.compile_commands
@@ -1343,23 +1208,22 @@ commands can contain arguments so that you do not have to invoke
[`textadept.run.test_commands`]: api.html#textadept.run.test_commands
[`textadept.run.error_patterns`]: api.html#textadept.run.error_patterns
---------------------------------------------------------------------------------
+---
### Modules
---------------------------------------------------------------------------------
+---
-Modules are packages of Lua code that provide functionality for Textadept. Most
-of the editor's features come from individual modules (see Textadept's *core/*
-and *modules/* directories). Textadept can load modules when the application
-starts up, or it can load modules on-demand in response to events. Once a module
-is loaded, it persists in memory and is never unloaded. Textadept attempts to
-load, in order, a given module from the following locations:
+Modules are packages of Lua code that provide functionality for Textadept. Most of the
+editor's features come from individual modules (see Textadept's *core/* and *modules/*
+directories). Textadept can load modules when the application starts up, or it can load modules
+on-demand in response to events. Once a module is loaded, it persists in memory and is never
+unloaded. Textadept attempts to load, in order, a given module from the following locations:
1. Your *~/.textadept/modules/* directory.
2. Textadept's *modules/* directory.
-**Tip:** placing modules in your user data directory avoids the possibility of
-you overwriting them when you update Textadept. These modules also take
-precedence over the ones installed with Textadept.
+**Tip:** placing modules in your user data directory avoids the possibility of you overwriting
+them when you update Textadept. These modules also take precedence over the ones installed
+with Textadept.
Textadept will only load modules it is explicitly told to load (e.g. from your
*~/.textadept/init.lua*). For example, in your *~/.textadept/init.lua*:
@@ -1371,39 +1235,34 @@ Textadept will only load modules it is explicitly told to load (e.g. from your
if name == 'lua' then require('lua.extras') end
end)
-The only exception to this auto-loading prohibition is modules that have the
-same name as a lexer language. These so-called "[language modules][]" will be
-automatically loaded when an appropriate source file is opened, or when the
-module's associated lexer is loaded for a buffer.
+The only exception to this auto-loading prohibition is modules that have the same name as a
+lexer language. These so-called "[language modules][]" will be automatically loaded when an
+appropriate source file is opened, or when the module's associated lexer is loaded for a buffer.
**Note:** lexer language names are typically the names of lexer files in your
*~/.textadept/lexers/* directory and Textadept's *lexers/* directory.
#### Developing Modules
-Modules follow the Lua package model: a module is either a single Lua file or
-a group of Lua files in a directory that contains an *init.lua* file (which is
-the module's entry point). The name of the module is its file name or directory
-name, respectively. Here are some basic guidelines for developing modules and
-some things to keep in mind:
-
-* Modules should return a table of functions and fields that are defined
- locally, rather than globally. (This is standard Lua practice.) That way, the
- construct `local foo = require('foo')` behaves as expected.
-* Modules should not define global variables, as all modules share the same Lua
- state.
+Modules follow the Lua package model: a module is either a single Lua file or a group of Lua files
+in a directory that contains an *init.lua* file (which is the module's entry point). The name
+of the module is its file name or directory name, respectively. Here are some basic guidelines
+for developing modules and some things to keep in mind:
+
+* Modules should return a table of functions and fields that are defined locally, rather than
+ globally. (This is standard Lua practice.) That way, the construct `local foo = require('foo')`
+ behaves as expected.
+* Modules should not define global variables, as all modules share the same Lua state.
* Only [language modules][] should be named after lexer languages.
-* Modules must not call any functions that create buffers and views (e.g.
- `ui.print()`, `io.open_file()`, and `buffer.new()`) at file-level scope.
- Buffers and views can only be created within functions assigned to keys,
- associated with menu items, or connected to events.
-* Additional documentation on creating language modules can be found in the
- the [language modules][] documentation.
-
-**Tip:** you do not need to have a language module in order to have
-language-specific editing features. You can simply put language-specific
-features inside an [`events.LEXER_LOADED`][] event handler. For example, in your
-*~/.textadept/init.lua*:
+* Modules must not call any functions that create buffers and views (e.g. `ui.print()`,
+ `io.open_file()`, and `buffer.new()`) at file-level scope. Buffers and views can only be
+ created within functions assigned to keys, associated with menu items, or connected to events.
+* Additional documentation on creating language modules can be found in the the [language
+ modules][] documentation.
+
+**Tip:** you do not need to have a language module in order to have language-specific editing
+features. You can simply put language-specific features inside an [`events.LEXER_LOADED`][]
+event handler. For example, in your *~/.textadept/init.lua*:
-- Auto-pair and brace-match '<' and '>' only in HTML and XML files.
events.connect(events.LEXER_LOADED, function(name)
@@ -1416,13 +1275,13 @@ features inside an [`events.LEXER_LOADED`][] event handler. For example, in your
[language modules]: api.html#_M
[`events.LEXER_LOADED`]: api.html#events.LEXER_LOADED
---------------------------------------------------------------------------------
+---
### Themes
---------------------------------------------------------------------------------
+---
-Themes customize Textadept's look and feel. The editor comes with three built-in
-themes: "light", "dark", and "term". The default theme for the GUI and terminal
-versions is "light" and "term", respectively.
+Themes customize Textadept's look and feel. The editor comes with three built-in themes:
+"light", "dark", and "term". The default theme for the GUI and terminal versions is "light"
+and "term", respectively.
<span style="display: block; clear: right;"></span>
@@ -1434,29 +1293,26 @@ versions is "light" and "term", respectively.
A theme consists of a single Lua file, and is typically responsible for:
-* Defining the [colors][] and [text display settings][] (styles) used in syntax
- highlighting.
-* Assigning colors to various UI elements such as the caret, text selections,
- margin markers, and documentation popups.
-* Specifying what symbols to use for margin markers and how to display visual
- elements like the brace match indicator and snippet placeholders.
+* Defining the [colors][] and [text display settings][] (styles) used in syntax highlighting.
+* Assigning colors to various UI elements such as the caret, text selections, margin markers,
+ and documentation popups.
+* Specifying what symbols to use for margin markers and how to display visual elements like
+ the brace match indicator and snippet placeholders.
[colors]: api.html#lexer.colors
[text display settings]: api.html#lexer.styles
-Textadept attempts to load, in order, a given theme from the following
-locations:
+Textadept attempts to load, in order, a given theme from the following locations:
1. Your *~/.textadept/themes/* directory.
2. Textadept's *themes/* directory.
-**Tip:** placing themes in your user data directory avoids the possibility of
-you overwriting them when you update Textadept. These themes also take
-precedence over the ones installed with Textadept.
+**Tip:** placing themes in your user data directory avoids the possibility of you overwriting
+them when you update Textadept. These themes also take precedence over the ones installed
+with Textadept.
-You can set Textadept's theme using [`view.set_theme()`][]. You can also tweak a
-theme's styles on a per-language basis. For example, in your
-*~/.textadept/init.lua*:
+You can set Textadept's theme using [`view.set_theme()`][]. You can also tweak a theme's styles
+on a per-language basis. For example, in your *~/.textadept/init.lua*:
if not CURSES then
view:set_theme('light', {font = 'DejaVu Sans Mono', size = 12})
@@ -1469,84 +1325,73 @@ theme's styles on a per-language basis. For example, in your
view.style_fore[buffer:style_of_name('function')] = default_fore
end)
-**Tip:** you can experiment with themes without having to restart Textadept by
-using the [`reset()`][] command in the [Lua Command Entry](#lua-command-entry).
-Once you make changes to either your *~/.textadept/init.lua* or theme file,
-issuing the `reset` command will reload your changes.
+**Tip:** you can experiment with themes without having to restart Textadept by using the
+[`reset()`][] command in the [Lua Command Entry](#lua-command-entry). Once you make changes
+to either your *~/.textadept/init.lua* or theme file, issuing the `reset` command will reload
+your changes.
[`view.set_theme()`]: api.html#view.set_theme
[`reset()`]: api.html#reset
-The widgets in the GUI version of Textadept cannot be themed using Lua theme
-files. Instead, you must use [GTK Resource Files][], which are part of the GUI
-toolkit Textadept uses.
+The widgets in the GUI version of Textadept cannot be themed using Lua theme files. Instead,
+you must use [GTK Resource Files][], which are part of the GUI toolkit Textadept uses.
**Note:** Textadept's pre-built binaries are built for and linked against GTK 2,
not GTK 3.
[GTK Resource Files]: https://developer.gnome.org/gtk3/stable/gtk3-Resource-Files.html
---------------------------------------------------------------------------------
+---
### Scripting
---------------------------------------------------------------------------------
-
-Nearly every aspect of Textadept can be scripted, or controlled, using Lua.
-Textadept contains its own internal copy of [Lua 5.3][], which is largely
-unmodified compared to the official Lua release. The main difference is that
-Textadept's Lua does not have any compatibility options turned on for previous
-versions of Lua.
-
-Being an event-driven application, Textadept simply responds to input like key
-presses, mouse clicks, and state changes by running Lua code (more specifically,
-executing Lua functions). For example, when you press a key, Textadept emits an
-`events.KEYPRESS` event, which its *core/keys.lua* is listening for. When a
-sequence like `Ctrl+O` on Windows, Linux, and BSD is recognized, *core/keys.lua*
-looks up which Lua function is assigned to the `keys['ctrl+o']` key. By default,
-it is `io.open_file()`, so that function is executed and the user is prompted
-for a file to open. You could bind a different function to that key and
-Textadept will duly execute it. Similarly, when the editor opens a file via
-`io.open_file()`, that function emits a `events.FILE_OPENED` event, which
-*modules/textadept/file_types.lua* is listening for. When a Lua file is opened,
-*modules/textadept/file_types.lua* designates the "lua" lexer to perform syntax
-highlighting on that file and also loads the Lua language module if it has not
-already been loaded. You could also listen for `events.FILE_OPENED` in your
-*~/.textadept/init.lua* and perform your own action, such as loading some
-project-specific tools for editing that file.
-
-Your *~/.textadept/init.lua* is the entry point to scripting Textadept. In this
-file you can set up custom key bindings, menu items, and event handlers that
-will perform custom actions. Here are some ideas:
-
-* Define custom key bindings and menu items that manipulate buffer contents via
- the extensive [`buffer`][] API.
-* Extend Textadept's File menu with a menu item that prompts for a commit
- message using an [interactive dialog][], and then invokes a shell command that
- commits the current file to version control using the provided message.
-* Listen for the `events.FILE_SAVED` [event][] and [spawn][] an asynchronous
- process that runs a syntax checker, linter, or formatter on a source file when
- it is saved.
-* Start searches with the word under the caret by substituting the
- "Search > Find" menu item and key binding functions with a custom function
- that pre-populates `ui.find.find_entry_text` before calling `ui.find.focus()`
- to show the find & replace pane.
-* Auto-save files as you switch between buffers by listening for the
- `events.BUFFER_BEFORE_SWITCH` event and calling `buffer:save()` for buffers
- that have a `buffer.filename`. In the GUI version, you can even auto-save on
- a timer via `timeout()`.
-* Overload Textadept's find & replace capabilities to use Lua patterns instead
- of regex by reacting to `events.FIND` and `events.REPLACE` before Textadept
- can, and then determining whether or not the editor's default routines should
- handle those events.
-
-Textadept's [Lua API][] is extensively documented and serves as the ultimate
-resource when it comes to scripting the editor. The claim "Textadept gives you
-complete control over nearly the entire application using Lua" is not an
-exaggeration!
-
-If you are looking for a more structured scripting resource,
-[Textadept Quick Reference][] contains a wealth of knowledge on how to script
-and configure Textadept. It groups the editor's rich API into a series of tasks
-in a convenient and easy-to-use manner.
+---
+
+Nearly every aspect of Textadept can be scripted, or controlled, using Lua. Textadept contains
+its own internal copy of [Lua 5.3][], which is largely unmodified compared to the official Lua
+release. The main difference is that Textadept's Lua does not have any compatibility options
+turned on for previous versions of Lua.
+
+Being an event-driven application, Textadept simply responds to input like key presses,
+mouse clicks, and state changes by running Lua code (more specifically, executing Lua
+functions). For example, when you press a key, Textadept emits an `events.KEYPRESS` event, which
+its *core/keys.lua* is listening for. When a sequence like `Ctrl+O` on Windows, Linux, and BSD
+is recognized, *core/keys.lua* looks up which Lua function is assigned to the `keys['ctrl+o']`
+key. By default, it is `io.open_file()`, so that function is executed and the user is prompted
+for a file to open. You could bind a different function to that key and Textadept will duly
+execute it. Similarly, when the editor opens a file via `io.open_file()`, that function emits a
+`events.FILE_OPENED` event, which *modules/textadept/file_types.lua* is listening for. When a
+Lua file is opened, *modules/textadept/file_types.lua* designates the "lua" lexer to perform
+syntax highlighting on that file and also loads the Lua language module if it has not already
+been loaded. You could also listen for `events.FILE_OPENED` in your *~/.textadept/init.lua*
+and perform your own action, such as loading some project-specific tools for editing that file.
+
+Your *~/.textadept/init.lua* is the entry point to scripting Textadept. In this file you can set
+up custom key bindings, menu items, and event handlers that will perform custom actions. Here
+are some ideas:
+
+* Define custom key bindings and menu items that manipulate buffer contents via the extensive
+ [`buffer`][] API.
+* Extend Textadept's File menu with a menu item that prompts for a commit message using an
+ [interactive dialog][], and then invokes a shell command that commits the current file to
+ version control using the provided message.
+* Listen for the `events.FILE_SAVED` [event][] and [spawn][] an asynchronous process that runs
+ a syntax checker, linter, or formatter on a source file when it is saved.
+* Start searches with the word under the caret by substituting the "Search > Find" menu item
+ and key binding functions with a custom function that pre-populates `ui.find.find_entry_text`
+ before calling `ui.find.focus()` to show the find & replace pane.
+* Auto-save files as you switch between buffers by listening for the `events.BUFFER_BEFORE_SWITCH`
+ event and calling `buffer:save()` for buffers that have a `buffer.filename`. In the GUI version,
+ you can even auto-save on a timer via `timeout()`.
+* Overload Textadept's find & replace capabilities to use Lua patterns instead of regex by
+ reacting to `events.FIND` and `events.REPLACE` before Textadept can, and then determining
+ whether or not the editor's default routines should handle those events.
+
+Textadept's [Lua API][] is extensively documented and serves as the ultimate resource when it
+comes to scripting the editor. The claim "Textadept gives you complete control over nearly the
+entire application using Lua" is not an exaggeration!
+
+If you are looking for a more structured scripting resource, [Textadept Quick Reference][]
+contains a wealth of knowledge on how to script and configure Textadept. It groups the editor's
+rich API into a series of tasks in a convenient and easy-to-use manner.
[Lua 5.3]: https://www.lua.org/manual/5.3
[`buffer`]: api.html#buffer
@@ -1558,21 +1403,20 @@ in a convenient and easy-to-use manner.
#### Generate Autocompletion and Documentation Files
-You can generate for use with Textadept
-[autocompletion and documentation](#autocompletion-and-documentation) files for
-your Lua modules. Simply run [LuaDoc][] with Textadept's *modules/lua/tadoc.lua*
-doclet. For example:
+You can generate for use with Textadept [autocompletion and
+documentation](#autocompletion-and-documentation) files for your Lua modules. Simply run
+[LuaDoc][] with Textadept's *modules/lua/tadoc.lua* doclet. For example:
luadoc -d [output_path] --doclet _HOME/modules/lua/tadoc.lua [module(s)]
-where `_HOME` is the path where you installed Textadept and `output_path` is an
-arbitrary path to write the generated *tags* and *api* files to. You can then
-have Textadept load and use those autocompletion and documentation files when
-editing Lua code. For example, in your *~/.textadept/init.lua*:
+where `_HOME` is the path where you installed Textadept and `output_path` is an arbitrary
+path to write the generated *tags* and *api* files to. You can then have Textadept load and
+use those autocompletion and documentation files when editing Lua code. For example, in your
+*~/.textadept/init.lua*:
local loaded_tags = false
events.connect(events.LEXER_LOADED, function(name)
- if name ~= 'lua' or loaded_tags then return
+ if name ~= 'lua' or loaded_tags then return end
_M.lua.tags[#_M.lua.tags + 1] = '/path/to/tags'
loaded_tags = true
end)
@@ -1580,35 +1424,32 @@ editing Lua code. For example, in your *~/.textadept/init.lua*:
[LuaDoc]: https://keplerproject.github.com/luadoc
---------------------------------------------------------------------------------
+---
### Compiling
---------------------------------------------------------------------------------
+---
-Textadept is a bit unusual in that building it is only supported on Linux and
-BSD, or within a [Docker][] [image][]. The application is cross-compiled for
-Windows and macOS from Linux. While it is certainly possible to compile
-Textadept natively on those platforms, it is simply not supported in any
-official capacity.
+Textadept is a bit unusual in that building it is only supported on Linux and BSD, or within a
+[Docker][] [image][]. The application is cross-compiled for Windows and macOS from Linux. While
+it is certainly possible to compile Textadept natively on those platforms, it is simply not
+supported in any official capacity.
#### Requirements
-The requirements for compiling Textadept on Linux or BSD should be readily
-available from a package manager. The requirements for cross-compiling Textadept
-for Windows from Linux should also be easily obtainable.
+The requirements for compiling Textadept on Linux or BSD should be readily available from a
+package manager. The requirements for cross-compiling Textadept for Windows from Linux should
+also be easily obtainable.
Linux requirements:
* [GNU C compiler][] (*gcc*) 7.1+ (circa mid-2017)
* [GNU Make][] (*make*)
* [GTK][] 2.24+ development libraries for the GUI version
-* [ncurses][](w) development libraries (wide character support) for the terminal
- version
+* [ncurses][](w) development libraries (wide character support) for the terminal version
* _**OR**_
* [Docker][]
-**Note:** on Ubuntu for example, these dependencies would be provided by the
-`build-essential`, `libgtk2.0-dev`, `libncurses5-dev`, `libncursesw5-dev`, and
-`docker.io` packages.
+**Note:** on Ubuntu for example, these dependencies would be provided by the `build-essential`,
+`libgtk2.0-dev`, `libncurses5-dev`, `libncursesw5-dev`, and `docker.io` packages.
BSD requirements:
@@ -1617,8 +1458,7 @@ BSD requirements:
* [pkg-config][]
* [libiconv][]
* [GTK][] 2.24+ development libraries for the GUI version
-* [ncurses][](w) development libraries (wide character support) for the terminal
- version
+* [ncurses][](w) development libraries (wide character support) for the terminal version
Windows cross-compiling requirements:
@@ -1626,8 +1466,8 @@ Windows cross-compiling requirements:
* _**OR**_
* [Docker][]
-**Note:** on Ubuntu for example, the compiler dependency would be provided by
-the `gcc-mingw-w64` and `g++-mingw-w64` packages.
+**Note:** on Ubuntu for example, the compiler dependency would be provided by the `gcc-mingw-w64`
+and `g++-mingw-w64` packages.
macOS cross-compiling requirements:
@@ -1635,8 +1475,7 @@ macOS cross-compiling requirements:
* _**OR**_
* [Docker][]
-**Note:** Textadept's *src/Dockerfile* contains an example of how to build an
-OSX cross toolchain.
+**Note:** Textadept's *src/Dockerfile* contains an example of how to build an OSX cross toolchain.
[Docker]: https://www.docker.com
[image]: https://hub.docker.com/repository/docker/textadept/build
@@ -1652,46 +1491,44 @@ OSX cross toolchain.
#### Compiling
-Textadept is built from its *src/* directory and binaries are placed in the
-application's root directory. The general procedure is to have Textadept build
-its dependencies first, and then its binaries. Textadept is self-contained,
-meaning you do not have to install it; it can run from its current location.
-
-The following table provides a brief summary of `make` rules for building
-Textadept on Linux and BSD. (On BSD, substitute `make` with `gmake`.)
-
-Command |Description
----------------------|-----------
-`make deps` |Downloads and builds all of Textadept's core dependencies
-`make deps NIGHTLY=1`|Optionally downloads and builds bleeding-edge dependencies
-`make` |Builds Textadept, provided all dependencies are in place
-`make GTK3=1` |Builds Textadept using GTK 3.x
-`make DEBUG=1` |Optionally builds Textadept with debug symbols
-`make install` |Optionally installs Textadept (to */usr/local* by default)
-`make curses` |Builds the terminal version of Textadept
-`make curses install`|Optionally installs the terminal version of Textadept
-`make uninstall` |Uninstalls Textadept (from */usr/local* by default)
-`make clean` |Deletes all compiled files, leaving only source files
-`make clean-deps` |Deletes all unpacked dependencies, leaving only downloads
-`make win32-deps` |Downloads and builds Textadept's Windows dependencies
-`make win32` |Cross-compiles Textadept for Windows
-`make win32-curses` |Cross-compiles the terminal version for Windows
-`make osx-deps` |Downloads and builds Textadept's macOS dependencies
-`make osx` |Cross-compiles Textadept for macOS
-`make osx-curses` |Cross-compiles the terminal version for macOS
-`make osx-app` |Builds *Textadept.app*
-
-If you want to install Textadept into a non-standard location, you can specify
-that location using the `DESTDIR` variable. For example:
+Textadept is built from its *src/* directory and binaries are placed in the application's root
+directory. The general procedure is to have Textadept build its dependencies first, and then
+its binaries. Textadept is self-contained, meaning you do not have to install it; it can run
+from its current location.
+
+The following table provides a brief summary of `make` rules for building Textadept on Linux
+and BSD. (On BSD, substitute `make` with `gmake`.)
+
+Command | Description
+-|-
+`make deps` | Downloads and builds all of Textadept's core dependencies
+`make deps NIGHTLY=1` | Optionally downloads and builds bleeding-edge dependencies
+`make` | Builds Textadept, provided all dependencies are in place
+`make GTK3=1` | Builds Textadept using GTK 3.x
+`make DEBUG=1` | Optionally builds Textadept with debug symbols
+`make install` | Optionally installs Textadept (to */usr/local* by default)
+`make curses` | Builds the terminal version of Textadept
+`make curses install`| Optionally installs the terminal version of Textadept
+`make uninstall` | Uninstalls Textadept (from */usr/local* by default)
+`make clean` | Deletes all compiled files, leaving only source files
+`make clean-deps` | Deletes all unpacked dependencies, leaving only downloads
+`make win32-deps` | Downloads and builds Textadept's Windows dependencies
+`make win32` | Cross-compiles Textadept for Windows
+`make win32-curses` | Cross-compiles the terminal version for Windows
+`make osx-deps` | Downloads and builds Textadept's macOS dependencies
+`make osx` | Cross-compiles Textadept for macOS
+`make osx-curses` | Cross-compiles the terminal version for macOS
+`make osx-app` | Builds *Textadept.app*
+
+If you want to install Textadept into a non-standard location, you can specify that location
+using the `DESTDIR` variable. For example:
make install DESTDIR=/prefix/to/install/to
-**Linux and BSD note:** if any of Textadept's dependencies are installed under a
-prefix that your compiler flags do not include by default (e.g. */usr/local/*),
-you will have to run something like:
+**Linux and BSD note:** if any of Textadept's dependencies are installed under a prefix that your
+compiler flags do not include by default (e.g. */usr/local/*), you will have to run something like:
- make CFLAGS="-I/usr/local/include" \
- CXXFLAGS="-I/usr/local/include -L/usr/local/lib"
+ make CFLAGS="-I/usr/local/include" CXXFLAGS="-I/usr/local/include -L/usr/local/lib"
Also, if you want to compile with Clang, you will have to run something like:
@@ -1699,8 +1536,8 @@ Also, if you want to compile with Clang, you will have to run something like:
##### Compiling using Docker
-You can use [Docker][] to build Textadept for Windows, macOS, or Linux. The
-[image][] required to do so is about 2.5GB in size. For example:
+You can use [Docker][] to build Textadept for Windows, macOS, or Linux. The [image][] required
+to do so is about 2.5GB in size. For example:
localhost$ docker pull ghcr.io/orbitalquark/textadept-build:v1.0
localhost$ docker run -t -i -v /path/to/textadept:/ta -w /ta/src \
@@ -1709,91 +1546,87 @@ You can use [Docker][] to build Textadept for Windows, macOS, or Linux. The
container# make
container# exit
-If you prefer to build your own Docker image instead of pulling one, you can
-run `docker build .` from Textadept's *src/* directory, which contains the
-relevant *Dockerfile*.
+If you prefer to build your own Docker image instead of pulling one, you can run `docker build .`
+from Textadept's *src/* directory, which contains the relevant *Dockerfile*.
-You can issue within the container any of the build commands given in
-the previous table, though the install commands are meaningless.
+You can issue within the container any of the build commands given in the previous table,
+though the install commands are meaningless.
-**Linux note:** if, when running one of the Linux binaries produced, you get an
-error like `/<path>/libstdc++.so.6: version 'GLIBCXX_<version>' not found`, then
-try compiling with the following flags:
+**Linux note:** if, when running one of the Linux binaries produced, you get an error like
+`/<path>/libstdc++.so.6: version 'GLIBCXX_<version>' not found`, then try compiling with the
+following flags:
container# make CXXFLAGS="-0s -std=c++17 -static-libstdc++"
-If you still get an error, this time like
-`/<path>/libc.so.6: version 'GLIBC_<version>' not found`, then you will have to
-compile Textadept manually without Docker.
+If you still get an error, this time like `/<path>/libc.so.6: version 'GLIBC_<version>' not
+found`, then you will have to compile Textadept manually without Docker.
[Docker]: https://www.docker.com
[image]: https://github.com/users/orbitalquark/packages/container/textadept-build
---------------------------------------------------------------------------------
+---
### Appendix
---------------------------------------------------------------------------------
+---
#### Regex and Lua Pattern Syntax
The following table outlines Regex and Lua Pattern syntax:
-Regex |Lua |Meaning
-------------|---------|-------
-. |. |Matches any character
-[[:alpha:]] |%a |Matches any letter
-\d |%d |Matches any digit
-[[:lower:]] |%l |Matches any lower case character
-[[:punct:]] |%p |Matches any punctuation character
-\s |%s |Matches any space character
-[[:upper:]] |%u |Matches any upper case character
-\w |%w |Matches any alphanumeric character (Regex includes '_')
-[[:xdigit:]]|%x |Matches any hexadecimal digit
-[*set*] |[*set*] |Matches any character in *set*, including ranges like A-Z
-[^*set*] |[^*set*] |Matches the complement of *set*
-\* |\* |Matches the previous item (Regex) or class (Lua) 0+ times
-\+ |+ |Matches the previous item or class 1+ times
-\*? |- |Matches the previous item or class 0+ times, non-greedily
-\+? | |Matches the previous item 1+ times, non-greedily
-? |? |Matches the previous item or class once or not at all
-{*m*,*n*} | |Matches the previous item between *m* and *n* times
-{*m*,} | |Matches the previous item at least *m* times
-{*m*} | |Matches the previous item exactly *m* times
-\| | |Matches either the previous item or the next item
-&nbsp; |%b*xy* |Matches a balanced string bounded by *x* and *y*
-&nbsp; |%f[*set*]|Matches a position between characters not in and in *set*
-\\< | |Matches the beginning of a word
-\\> | |Matches the end of a word
-\b | |Matches a word boundary
-^ |^ |Matches the beginning of a line unless inside a set
-$ |$ |Matches the end of a line unless inside a set
-( |( |The beginning of a captured matching region
-) |) |The end of a captured matching region
-(?:*...*) | |Consider matched "*...*" as a single, uncaptured item
-\\*n* |%*n* |The *n*th captured matching region's text<sup>a</sup>
-\\*x* |%*x* |Non-alphanumeric character *x*, ignoring special meaning
-
-<sup>a</sup>In replacement text, "\0" (Regex) or "%0" (Lua) represents all
-matched text.
-
-Textadept's regular expressions are based on the C++11 standard for ECMAScript.
-There are a number of references for this syntax on the internet, including:
+Regex | Lua | Meaning
+-|-|-
+. | . | Matches any character
+[[:alpha:]] |%a | Matches any letter
+\d | %d | Matches any digit
+[[:lower:]] | %l | Matches any lower case character
+[[:punct:]] | %p | Matches any punctuation character
+\s | %s | Matches any space character
+[[:upper:]] | %u | Matches any upper case character
+\w | %w | Matches any alphanumeric character (Regex includes '_')
+[[:xdigit:]] | %x | Matches any hexadecimal digit
+[*set*] | [*set*] | Matches any character in *set*, including ranges like A-Z
+[^*set*] | [^*set*] | Matches the complement of *set*
+\* | \* | Matches the previous item (Regex) or class (Lua) 0+ times
+\+ | + | Matches the previous item or class 1+ times
+\*? | - | Matches the previous item or class 0+ times, non-greedily
+\+? | | Matches the previous item 1+ times, non-greedily
+? | ? | Matches the previous item or class once or not at all
+{*m*,*n*} | | Matches the previous item between *m* and *n* times
+{*m*,} | | Matches the previous item at least *m* times
+{*m*} | | Matches the previous item exactly *m* times
+\| | | Matches either the previous item or the next item
+&nbsp; | %b*xy* | Matches a balanced string bounded by *x* and *y*
+&nbsp; | %f[*set*] | Matches a position between characters not in and in *set*
+\\< | | Matches the beginning of a word
+\\> | | Matches the end of a word
+\b | | Matches a word boundary
+^ | ^ | Matches the beginning of a line unless inside a set
+$ | $ | Matches the end of a line unless inside a set
+( | ( | The beginning of a captured matching region
+) | ) | The end of a captured matching region
+(?:*...*) | | Consider matched "*...*" as a single, uncaptured item
+\\*n* | %*n* | The *n*th captured matching region's text<sup>a</sup>
+\\*x* | %*x* | Non-alphanumeric character *x*, ignoring special meaning
+
+<sup>a</sup>In replacement text, "\0" (Regex) or "%0" (Lua) represents all matched text.
+
+Textadept's regular expressions are based on the C++11 standard for ECMAScript. There are a
+number of references for this syntax on the internet, including:
* [ECMAScript syntax C++ reference](https://www.cplusplus.com/reference/regex/ECMAScript/)
* [Modified ECMAScript regular expression grammar](https://en.cppreference.com/w/cpp/regex/ecmascript)
* [Regular Expressions (C++)](https://docs.microsoft.com/en-us/cpp/standard-library/regular-expressions-cpp)
-More information on Lua patterns can be found in the
-[Lua 5.3 Reference Manual](https://www.lua.org/manual/5.3/manual.html#6.4.1).
+More information on Lua patterns can be found in the [Lua 5.3 Reference
+Manual](https://www.lua.org/manual/5.3/manual.html#6.4.1).
#### Terminal Version Compatibility
-Textadept's terminal version requires a font with good glyph support (like
-DejaVu Sans Mono or Liberation Mono), and lacks some GUI features due to the
-terminal's constraints:
+Textadept's terminal version requires a font with good glyph support (like DejaVu Sans Mono or
+Liberation Mono), and lacks some GUI features due to the terminal's constraints:
* No alpha values or transparency.
-* No images in autocompletion lists. Instead, autocompletion lists show the
- first character in the string passed to [`buffer.register_image()`][].
+* No images in autocompletion lists. Instead, autocompletion lists show the first character in
+ the string passed to [`buffer.register_image()`][].
* No buffered or two-phase drawing.
* Carets cannot have a period, line style, or width.
* No drag and drop.
@@ -1801,9 +1634,8 @@ terminal's constraints:
* No extra line ascent or descent.
* No fold lines above and below lines.
* No hotspot underlines on mouse hover.
-* No indicators other than `INDIC_ROUNDBOX` and `INDIC_STRAIGHTBOX`, although
- neither has translucent drawing and `INDIC_ROUNDBOX` does not have rounded
- corners.
+* No indicators other than `INDIC_ROUNDBOX` and `INDIC_STRAIGHTBOX`, although neither has
+ translucent drawing and `INDIC_ROUNDBOX` does not have rounded corners.
* Some complex marker symbols are not drawn properly or at all.
* No mouse cursor types.
* Only up to 16 colors recognized, regardless of how many colors the terminal
@@ -1812,8 +1644,8 @@ terminal's constraints:
* No style settings like font name, font size, or italics.
* No X selection, primary or secondary, integration with the clipboard.
* No zoom.
-* When using the mouse in the Windows console, Shift+Double-click extends
- selections and quadruple-clicking inside a selection collapses it.
+* When using the mouse in the Windows console, Shift+Double-click extends selections and
+ quadruple-clicking inside a selection collapses it.
[`buffer.register_image()`]: api.html#buffer.register_image
@@ -1821,17 +1653,14 @@ terminal's constraints:
Textadept's directory structure is organized as follows:
-* *core/*: Contains Textadept's core Lua modules. These modules are essential
- for the application to run. They provide Textadept's Lua to C interface, event
- framework, file interactions, and localization.
-* *lexers/*: Houses the lexer modules that analyze source code for syntax
- highlighting.
-* *modules/*: Contains modules for editing text and source code, as well as
- language modules.
-* *themes/*: Contains built-in themes that customize the look and feel of
- Textadept.
-* *etc/*, *lib/*, and *share/*: GTK support directories and only appear in the
- Windows and macOS packages.
+* *core/*: Contains Textadept's core Lua modules. These modules are essential for the application
+ to run. They provide Textadept's Lua to C interface, event framework, file interactions,
+ and localization.
+* *lexers/*: Houses the lexer modules that analyze source code for syntax highlighting.
+* *modules/*: Contains modules for editing text and source code, as well as language modules.
+* *themes/*: Contains built-in themes that customize the look and feel of Textadept.
+* *etc/*, *lib/*, and *share/*: GTK support directories and only appear in the Windows and
+ macOS packages.
#### Technologies
@@ -1869,85 +1698,84 @@ Textadept is composed of the following technologies:
##### API Changes
-Old API |Change |New API
----------------------------|:------:|-------
-**buffer** | |
-set_theme() |Renamed |[view:set_theme()][]
-style_name[n] |Replaced|[name_of_style][](n)
-CASEINSENSITIVEBEHAVIOUR\_*|Renamed |CASEINSENSITIVEBEHAVIOR\_*
-INDIC\_GRADIENTCENTRE |Renamed |INDIC\_GRADIENTCENTER
-MARGIN\_COLOUR |Renamed |MARGIN\_COLOR
-auto\_c\_case_insensitive\_behaviour|Renamed|auto\_c\_case\_insensitive\_behavior
-colourise |Renamed |colorize
-edge\_colour |Renamed |edge\_color
-set\_fold\_margin\_\*colour|Renamed |set\_fold\_margin\_\*color
-vertical\_centre\_caret |Renamed |vertical\_center\_caret
-**events** | |
-AUTO\_C\_CANCELLED |Renamed |AUTO\_C\_CANCELED
-N/A |Added |[COMMAND_TEXT_CHANGED][]
-N/A |Added |[FILE_BEFORE_RELOAD][]
-N/A |Added |[FILE_AFTER_RELOAD][]
-N/A |Added |[FIND_RESULT_FOUND][]
-N/A |Added |[FIND_TEXT_CHANGED][]
-N/A |Added |[SESSION_SAVE][]
-N/A |Added |[SESSION_LOAD][]
-N/A |Added |[UNFOCUS][]
-**io** | |
-reload_file() |Renamed |[buffer:reload()][]
-save_file() |Renamed |[buffer:save()][]
-save_file_as() |Renamed |[buffer:save_as()][]
-close_buffer() |Renamed |[buffer:close()][]
-**keys** | |
-MODE |Renamed |[mode][]
-**lexer** | |
-N/A |Added |[to_eol()][]
-delimited\_range() |Replaced|[range()][]
-nested\_pair() |Replaced|[range()][]
-fold\_line\_comments() |Replaced|[fold_consecutive_lines()][]<sup>a</sup>
-N/A |Added |[number][]
-N/A |Added |[colors][]
-N/A |Added |[styles][]
-N/A |Added |[folding][] and other fold\* properties
-**lfs** | |
-dir\_foreach() |Replaced|for filename in [lfs.walk()][] do ... end
-**textadept.bookmarks** | |
-toggle(line, on) |Changed |[toggle()][]
-**textadept.editing** | |
-block\_comment() |Renamed |[toggle_comment()][]
-highlight_word() |Replaced|[highlight_words][]
-**textadept.file_types** | |
-lexers |Removed |N/A<sup>b</sup>
-**textadept.find** | |
-find\_incremental() |Replaced|[incremental][]<sup>c</sup>
-find\_incremental\_keys |Removed |
-N/A |Added |[highlight_all_matches][]
-**textadept.history** |Added |[textadept.history][]
-**textadept.run** | |
-N/A |Added |[set_arguments][]
-**textadept.snippets** | |
-\_insert() |Renamed |[insert()][]
-\_previous() |Renamed |[previous()][]
-\_cancel_current() |Renamed |[cancel_current()][]
-\_select() |Renamed |[select()][]
-\_paths |Renamed |[paths][]
-**ui** | |
-bufstatusbar\_text |Renamed |[buffer_statusbar_text][]
-**ui.command_entry** | |
-N/A |Added |[active][]
-N/A |Added |[append_history][]
-**ui.dialogs** | |
-N/A |Added |[progressbar()][]
-**ui.find** | |
-find\_in\_files\_timeout |Removed |N/A
-N/A |Added |[active][]
-**view** | |
-N/A |Added |_buffer functions and fields_<sup>d</sup>
+Old API | Change | New API
+-|:-:|-
+**buffer**||
+set_theme() | Renamed | [view:set_theme()][]
+style_name[n] | Replaced | [name_of_style][](n)
+CASEINSENSITIVEBEHAVIOUR\_* | Renamed | CASEINSENSITIVEBEHAVIOR\_*
+INDIC\_GRADIENTCENTRE | Renamed | INDIC\_GRADIENTCENTER
+MARGIN\_COLOUR | Renamed | MARGIN\_COLOR
+auto\_c\_case_insensitive\_behaviour | Renamed | auto\_c\_case\_insensitive\_behavior
+colourise | Renamed | colorize
+edge\_colour | Renamed | edge\_color
+set\_fold\_margin\_\*colour | Renamed | set\_fold\_margin\_\*color
+vertical\_centre\_caret | Renamed | vertical\_center\_caret
+**events**||
+AUTO\_C\_CANCELLED | Renamed | AUTO\_C\_CANCELED
+N/A | Added | [COMMAND_TEXT_CHANGED][]
+N/A | Added | [FILE_BEFORE_RELOAD][]
+N/A | Added | [FILE_AFTER_RELOAD][]
+N/A | Added | [FIND_RESULT_FOUND][]
+N/A | Added | [FIND_TEXT_CHANGED][]
+N/A | Added | [SESSION_SAVE][]
+N/A | Added | [SESSION_LOAD][]
+N/A | Added | [UNFOCUS][]
+**io**||
+reload_file() | Renamed | [buffer:reload()][]
+save_file() | Renamed | [buffer:save()][]
+save_file_as() | Renamed | [buffer:save_as()][]
+close_buffer() | Renamed | [buffer:close()][]
+**keys**||
+MODE | Renamed | [mode][]
+**lexer**||
+N/A | Added | [to_eol()][]
+delimited\_range() | Replaced | [range()][]
+nested\_pair() | Replaced | [range()][]
+fold\_line\_comments() | Replaced | [fold_consecutive_lines()][]<sup>a</sup>
+N/A | Added | [number][]
+N/A | Added | [colors][]
+N/A | Added | [styles][]
+N/A | Added | [folding][] and other fold\* properties
+**lfs**||
+dir\_foreach() | Replaced | for filename in [lfs.walk()][] do ... end
+**textadept.bookmarks**||
+toggle(line, on) | Changed | [toggle()][]
+**textadept.editing**||
+block\_comment() | Renamed | [toggle_comment()][]
+highlight_word() | Replaced | [highlight_words][]
+**textadept.file_types**||
+lexers | Removed | N/A<sup>b</sup>
+**textadept.find**||
+find\_incremental() | Replaced | [incremental][]<sup>c</sup>
+find\_incremental\_keys | Removed |
+N/A | Added | [highlight_all_matches][]
+**textadept.history** | Added | [textadept.history][]
+**textadept.run**||
+N/A | Added | [set_arguments][]
+**textadept.snippets** ||
+\_insert() | Renamed | [insert()][]
+\_previous() | Renamed | [previous()][]
+\_cancel_current() | Renamed | [cancel_current()][]
+\_select() | Renamed | [select()][]
+\_paths | Renamed | [paths][]
+**ui**||
+bufstatusbar\_text | Renamed | [buffer_statusbar_text][]
+**ui.command_entry**||
+N/A | Added | [active][]
+N/A | Added | [append_history][]
+**ui.dialogs**||
+N/A | Added | [progressbar()][]
+**ui.find**||
+find\_in\_files\_timeout | Removed | N/A
+N/A | Added | [active][]
+**view**||
+N/A | Added | _buffer functions and fields_<sup>d</sup>
<sup>a</sup>Returns prefix and function, instead of just function.<br/>
<sup>b</sup>Use `for name in buffer:private_lexer_call(_SCINTILLA.functions.property_names[1]):gmatch('[^\n]+') do ... end`.<br/>
<sup>c</sup>Use `textadept.menu.menubar[_L['Search']][_L['Find Incremental']][2]`.<br/>
-<sup>d</sup>Most buffer functions and fields are available in views now. See
-section below.
+<sup>d</sup>Most buffer functions and fields are available in views now. See section below.
[view:set_theme()]: api.html#view.set_theme
[name_of_style]: api.html#buffer.name_of_style
@@ -1992,58 +1820,51 @@ section below.
##### Buffer Indexing Changes
-All buffer positions, lines, and countable entities now start from `1` instead
-of `0`. For example, `buffer:get_line(1)` now returns the contents of the first
-line instead of `buffer:get_line(0)`, and marker and indicator numbers now count
-from 1 instead of 0.
+All buffer positions, lines, and countable entities now start from `1` instead of `0`. For example,
+`buffer:get_line(1)` now returns the contents of the first line instead of `buffer:get_line(0)`,
+and marker and indicator numbers now count from 1 instead of 0.
-While this change may seem daunting for migrating user scripts, in practice it
-is not, since most usage is internal, and an offset of 1 or 0 does not matter.
-In migrating Textadept's internals, the following changes were made:
+While this change may seem daunting for migrating user scripts, in practice it is not, since most
+usage is internal, and an offset of 1 or 0 does not matter. In migrating Textadept's internals,
+the following changes were made:
-* Themes that loop through marker numbers will need to be updated from something
- like `for i = 25, 31 do ... end` to either `for i = 26, 32 do ... end` or
+* Themes that loop through marker numbers will need to be updated from something like
+ `for i = 25, 31 do ... end` to either `for i = 26, 32 do ... end` or
`for i = buffer.MARKNUM_FOLDEREND, buffer.MARKNUM_FOLDEROPEN do ... end`.
-* Most references of `buffer.length` will need to be changed to
- `buffer.length + 1`. For example, something like
- `buffer:goto_pos(buffer.length)` needs to be
- `buffer:goto_pos(buffer.length + 1)`. The exceptions are when `buffer.length`
- is not used as a position, as in
+* Most references of `buffer.length` will need to be changed to `buffer.length + 1`. For example,
+ something like `buffer:goto_pos(buffer.length)` needs to be `buffer:goto_pos(buffer.length + 1)`.
+ The exceptions are when `buffer.length` is not used as a position, as in
`buffer:indicator_clear_range(1, buffer.length)`, which is still valid.
-* Any `buffer` function calls and property indexing with bare numbers should be
- changed to calls or indexes with those numbers plus 1. For example,
- `buffer:contracted_fold_next(0)` changes to `buffer:contracted_fold_next(1)`,
- and `buffer.margin_n_width[1] = ...` changes to
+* Any `buffer` function calls and property indexing with bare numbers should be changed to
+ calls or indexes with those numbers plus 1. For example, `buffer:contracted_fold_next(0)`
+ changes to `buffer:contracted_fold_next(1)`, and `buffer.margin_n_width[1] = ...` changes to
`buffer.margin_n_width[2] = ...`.
* Any looping through lines, margins, and selections via
`for i = 0, buffer.{line_count,margins,selections} - 1 do ... end` needs to be
`for i = 1, buffer.{line_count,margins,selections} do ... end`.
-* Similarly, any language modules that loop back through lines (e.g. to
- determine types for autocompletion) via
- `for i = current_line, 0, -1 do ... end` needs to be
+* Similarly, any language modules that loop back through lines (e.g. to determine types for
+ autocompletion) via `for i = current_line, 0, -1 do ... end` needs to be
`for i = current_line, 1, -1 do ... end`.
-* Marker or indicator masks are produced by subtracting 1 from marker or
- indicator numbers. For example, `1 << textadept.bookmarks.MARK_BOOKMARK`
- changes to `1 << textadept.bookmarks.MARK_BOOKMARK - 1`.
-* Logic that depends on the return value of `buffer:get_cur_line()` may need to
- be changed. For example, any subsequent references to `pos` after
- `local line, pos = buffer:get_cur_line()` like `if line:sub(1, pos) ... end`
- need to be changed to `if line:sub(1, pos - 1) ... end`.
-
-I found it helpful to quickly scan source files for syntax-highlighted numbers
-and then seeing if those numbers needed to be changed. Searching for "- 1",
-"+ 1", "buffer.length", etc. was also helpful.
+* Marker or indicator masks are produced by subtracting 1 from marker or indicator
+ numbers. For example, `1 << textadept.bookmarks.MARK_BOOKMARK` changes to
+ `1 << textadept.bookmarks.MARK_BOOKMARK - 1`.
+* Logic that depends on the return value of `buffer:get_cur_line()` may need to be changed. For
+ example, any subsequent references to `pos` after `local line, pos = buffer:get_cur_line()`
+ like `if line:sub(1, pos) ... end` need to be changed to `if line:sub(1, pos - 1) ... end`.
+
+I found it helpful to quickly scan source files for syntax-highlighted numbers and then seeing
+if those numbers needed to be changed. Searching for "- 1", "+ 1", "buffer.length", etc. was
+also helpful.
##### View API Additions and Buffer API Changes
-Textadept's [buffer][] API is largely based on the [Scintilla API][], which does
-not distinguish between buffer- and view-specific functionality. Textadept 11
-now attempts to separate this functionality, but only superficially. Buffers and
-views may be used interchangeably for the most part, but the [buffer][] and
-[view][] API provides _guidance_ (not hard requirements) on which functions and
-fields are more appropriate for their respective objects. _User scripts do not
-need to be updated and will continue to function normally_. The following "Find"
-regex can be used to help convert `buffer.*` functionality to `view.*`:
+Textadept's [buffer][] API is largely based on the [Scintilla API][], which does not distinguish
+between buffer- and view-specific functionality. Textadept 11 now attempts to separate this
+functionality, but only superficially. Buffers and views may be used interchangeably for the
+most part, but the [buffer][] and [view][] API provides _guidance_ (not hard requirements)
+on which functions and fields are more appropriate for their respective objects. _User scripts
+do not need to be updated and will continue to function normally_. The following "Find" regex
+can be used to help convert `buffer.*` functionality to `view.*`:
<pre style="word-wrap: break-word;">
<code>(\w+)([.:])\b(additional_caret_fore|additional_carets_blink|additional_carets_visible|additional_sel_alpha|additional_sel_back|additional_sel_fore|all_lines_visible|annotation_visible|auto_c_max_height|auto_c_max_width|call_tip_fore_hlt|call_tip_pos_start|call_tip_position|call_tip_use_style|caret_fore|caret_line_back|caret_line_back_alpha|caret_line_frame|caret_line_visible|caret_line_visible_always|caret_period|caret_style|caret_width|cursor|edge_colour|edge_column|edge_mode|end_at_last_line|extra_ascent|extra_descent|first_visible_line|fold_display_text_style|fold_expanded|fold_flags|h_scroll_bar|highlight_guide|idle_styling|indentation_guides|indic_alpha|indic_fore|indic_hover_fore|indic_hover_style|indic_outline_alpha|indic_style|indic_under|line_visible|lines_on_screen|margins|margin_back_n|margin_cursor_n|margin_left|margin_mask_n|margin_options|margin_right|margin_sensitive_n|margin_type_n|margin_width_n|marker_alpha|marker_back|marker_back_selected|marker_fore|mouse_dwell_time|mouse_selection_rectangular_switch|property|property_expanded|property_int|rectangular_selection_modifier|representation|rgba_image_height|rgba_image_scale|rgba_image_width|scroll_width|scroll_width_tracking|sel_alpha|sel_eol_filled|size|style_back|style_bold|style_case|style_changeable|style_eol_filled|style_font|style_fore|style_italic|style_size|style_underline|style_visible|tab_draw_mode|v_scroll_bar|view_eol|view_ws|whitespace_size|wrap_indent_mode|wrap_mode|wrap_start_indent|wrap_visual_flags|wrap_visual_flags_location|x_offset|zoom|ANNOTATION_BOXED|ANNOTATION_HIDDEN|ANNOTATION_STANDARD|ANNOTATION_INDENTED|CARETSTYLE_BLOCK|CARETSTYLE_INVISIBLE|CARETSTYLE_LINE|CARET_EVEN|CARET_JUMPS|CARET_SLOP|CARET_STRICT|EDGE_BACKGROUND|EDGE_LINE|EDGE_MULTILINE|EDGE_NONE|FOLDACTION_CONTRACT|FOLDACTION_EXPAND|FOLDACTION_TOGGLE|FOLDDISPLAYTEXT_HIDDEN|FOLDDISPLAYTEXT_STANDARD|FOLDDISPLAYTEXT_BOXED|INDIC_BOX|INDIC_COMPOSITIONTHICK|INDIC_COMPOSITIONTHIN|INDIC_DASH|INDIC_DIAGONAL|INDIC_DOTBOX|INDIC_DOTS|INDIC_FULLBOX|INDIC_GRADIENT|INDIC_GRADIENTCENTRE|INDIC_HIDDEN|INDIC_PLAIN|INDIC_POINT|INDIC_POINTCHARACTER|INDIC_ROUNDBOX|INDIC_SQUIGGLE|INDIC_SQUIGGLELOW|INDIC_SQUIGGLEPIXMAP|INDIC_STRAIGHTBOX|INDIC_STRIKE|INDIC_TEXTFORE|INDIC_TT|MOD_ALT|MOD_CTRL|MOD_META|MOD_SHIFT|MOD_SUPER|MOUSE_DRAG|MOUSE_PRESS|MOUSE_RELEASE|WS_INVISIBLE|WS_VISIBLEAFTERINDENT|WS_VISIBLEALWAYS|WS_VISIBLEONLYININDENT|ALPHA_NOALPHA|ALPHA_OPAQUE|ALPHA_TRANSPARENT|CASE_CAMEL|CASE_LOWER|CASE_MIXED|CASE_UPPER|CURSORARROW|CURSORNORMAL|CURSORREVERSEARROW|CURSORWAIT|FOLDFLAG_LEVELNUMBERS|FOLDFLAG_LINEAFTER_CONTRACTED|FOLDFLAG_LINEAFTER_EXPANDED|FOLDFLAG_LINEBEFORE_CONTRACTED|FOLDFLAG_LINEBEFORE_EXPANDED|FOLDFLAG_LINESTATE|IV_LOOKBOTH|IV_LOOKFORWARD|IV_NONE|IV_REAL|MARGINOPTION_NONE|MARGINOPTION_SUBLINESELECT|MARGIN_BACK|MARGIN_COLOUR|MARGIN_FORE|MARGIN_NUMBER|MARGIN_RTEXT|MARGIN_SYMBOL|MARGIN_TEXT|MARK_ARROW|MARK_ARROWDOWN|MARK_ARROWS|MARK_BACKGROUND|MARK_BOOKMARK|MARK_BOXMINUS|MARK_BOXMINUSCONNECTED|MARK_BOXPLUS|MARK_BOXPLUSCONNECTED|MARK_CHARACTER|MARK_CIRCLE|MARK_CIRCLEMINUS|MARK_CIRCLEMINUSCONNECTED|MARK_CIRCLEPLUS|MARK_CIRCLEPLUSCONNECTED|MARK_DOTDOTDOT|MARK_EMPTY|MARK_FULLRECT|MARK_LCORNER|MARK_LCORNERCURVE|MARK_LEFTRECT|MARK_MINUS|MARK_PIXMAP|MARK_PLUS|MARK_RGBAIMAGE|MARK_ROUNDRECT|MARK_SHORTARROW|MARK_SMALLRECT|MARK_TCORNER|MARK_TCORNERCURVE|MARK_UNDERLINE|MARK_VERTICALBOOKMARK|MARK_VLINE|MASK_FOLDERS|TD_LONGARROW|TD_STRIKEOUT|TIME_FOREVER|WRAPINDENT_DEEPINDENT|WRAPINDENT_FIXED|WRAPINDENT_INDENT|WRAPINDENT_SAME|WRAPVISUALFLAGLOC_DEFAULT|WRAPVISUALFLAGLOC_END_BY_TEXT|WRAPVISUALFLAGLOC_START_BY_TEXT|WRAPVISUALFLAG_END|WRAPVISUALFLAG_MARGIN|WRAPVISUALFLAG_NONE|WRAPVISUALFLAG_START|WRAP_CHAR|WRAP_NONE|WRAP_WHITESPACE|WRAP_WORD|STYLE_BRACEBAD|STYLE_BRACELIGHT|STYLE_CALLTIP|STYLE_CONTROLCHAR|STYLE_DEFAULT|STYLE_FOLDDISPLAYTEXT|STYLE_INDENTGUIDE|STYLE_LINENUMBER|STYLE_MAX|UPDATE_H_SCROLL|UPDATE_V_SCROLL|VISIBLE_SLOP|VISIBLE_STRICT|brace_bad_light|brace_bad_light_indicator|brace_highlight|brace_highlight_indicator|call_tip_active|call_tip_cancel|call_tip_pos_start|call_tip_set_hlt|call_tip_show|clear_registered_images|clear_representation|contracted_fold_next|doc_line_from_visible|ensure_visible|ensure_visible_enforce_policy|fold_all|fold_children|fold_line|get_default_fold_display_text|hide_lines|line_scroll|line_scroll_down|line_scroll_up|marker_define|marker_define_pixmap|marker_define_rgba_image|marker_enable_highlight|marker_symbol_defined|multi_edge_add_line|multi_edge_clear_all|register_image|register_rgba_image|scroll_caret|scroll_to_end|scroll_to_start|scroll_range|set_default_fold_display_text|set_fold_margin_colour|set_fold_margin_hi_colour|set_sel_back|set_sel_fore|set_visible_policy|set_whitespace_back|set_whitespace_fore|set_x_caret_policy|set_y_caret_policy|show_lines|style_clear_all|style_reset_default|text_height|text_width|toggle_fold|toggle_fold_show_text|vertical_centre_caret|visible_from_doc_line|wrap_count|zoom_in|zoom_out|split|unsplit|goto_buffer)\b</code>
@@ -2053,8 +1874,7 @@ regex can be used to help convert `buffer.*` functionality to `view.*`:
view\2\3
-It is not recommended to blindly "Replace All". Each change should be manually
-confirmed.
+It is not recommended to blindly "Replace All". Each change should be manually confirmed.
[buffer]: api.html#buffer
[Scintilla API]: https://scintilla.org/ScintillaDoc.html
@@ -2063,10 +1883,10 @@ confirmed.
##### Theme and Lexer Changes
-Themes and lexers have a new, optional API for defining and using colors and
-styles. Previously, all definitions and access to colors and styles was
-accomplished through `buffer.property` and `buffer.property_int`. Now it can be
-done via the `lexer.colors` and `lexer.styles` variables. For example:
+Themes and lexers have a new, optional API for defining and using colors and styles. Previously,
+all definitions and access to colors and styles was accomplished through `buffer.property`
+and `buffer.property_int`. Now it can be done via the `lexer.colors` and `lexer.styles`
+variables. For example:
-- Textadept 10
local property, property_int = buffer.property, buffer.property_int
@@ -2080,10 +1900,9 @@ done via the `lexer.colors` and `lexer.styles` variables. For example:
styles.keyword = {fore = colors.blue, bold = true}
view.edge_color = colors.grey
-Any additional settings passed `view:set_theme()` are available as global
-variables in the theme. Textadept's themes make use of `font` and `size` (the
-latter of which used to be `fontsize`) for easily configuring font and size
-per-user.
+Any additional settings passed `view:set_theme()` are available as global variables in the
+theme. Textadept's themes make use of `font` and `size` (the latter of which used to be
+`fontsize`) for easily configuring font and size per-user.
Lexers can also utilize these new features. For example:
@@ -2095,38 +1914,35 @@ Lexers can also utilize these new features. For example:
lex:add_rule('custom_rule', token('custom', P('word')))
lex:add_style('custom', lexer.styles.keyword .. {italic = true})
-Note that these features are optional. Themes and lexers setting property
-strings is still supported.
+Note that these features are optional. Themes and lexers setting property strings is still
+supported.
##### Localization Changes
-GUI mnemonics in localization keys have been removed. For example, `_L['_New']`
-should be changed to `_L['New']`. Mnemonics can still be used in localization
-values; it's just the keys that have changed. See Textadept's *core/locale.conf*
-for examples.
+GUI mnemonics in localization keys have been removed. For example, `_L['_New']` should be
+changed to `_L['New']`. Mnemonics can still be used in localization values; it's just the keys
+that have changed. See Textadept's *core/locale.conf* for examples.
##### Key Bindings Changes
-Key sequence modifiers have changed from their shortened form to a longer form
-that is more intuitive. `'c'` is now `'ctrl'`, `'a'` is now `'alt'`, `'m'` is
-now `'cmd'` on macOS and `'meta'` in the terminal version, and `'s'` is now
-`'shift'`. For example, `keys.cn = ...` is now `keys['ctrl+n'] = ...` and
-`keys['m<'] = ...` is now `keys['cmd+<'] = ...` or `keys['meta+<'] = ...`.
+Key sequence modifiers have changed from their shortened form to a longer form that is more
+intuitive. `'c'` is now `'ctrl'`, `'a'` is now `'alt'`, `'m'` is now `'cmd'` on macOS and
+`'meta'` in the terminal version, and `'s'` is now `'shift'`. For example, `keys.cn = ...` is now
+`keys['ctrl+n'] = ...` and `keys['m<'] = ...` is now `keys['cmd+<'] = ...` or `keys['meta+<']
+= ...`.
-The key binding for inserting a user-specified snippet from a dialog has changed
-from `Ctrl+K` (`⌥⇥` on macOS | `M-K` on the terminal) to `Ctrl+Shift+K`
-(`⌥⇧⇥` | `M-S-K`). `Ctrl+K` (`⌥⇥` | `M-K`) now autocompletes snippet names.
+The key binding for inserting a user-specified snippet from a dialog has changed from `Ctrl+K`
+(`⌥⇥` on macOS | `M-K` on the terminal) to `Ctrl+Shift+K` (`⌥⇧⇥` | `M-S-K`). `Ctrl+K`
+(`⌥⇥` | `M-K`) now autocompletes snippet names.
##### Session Changes
-Textadept saves and loads session from Lua data files instead of structured text
-files. As a result, Textadept 11 cannot load session files from 10.x or before.
+Textadept saves and loads session from Lua data files instead of structured text files. As a
+result, Textadept 11 cannot load session files from 10.x or before.
##### Miscellaneous Changes
-* *~/.textadept/?.lua* and *~/.textadept/?.{so,dll}* has been removed from
- `package.path` and `package.cpath`, respectively. All modules should be placed
- in *~/.textadept/modules/*.
-* The command entry no longer recognizes a Lua 5.1-style '`=`' prefix for
- printing return values. Printing return values has been the default for quite
- some time.
+* *~/.textadept/?.lua* and *~/.textadept/?.{so,dll}* has been removed from `package.path` and
+ `package.cpath`, respectively. All modules should be placed in *~/.textadept/modules/*.
+* The command entry no longer recognizes a Lua 5.1-style '`=`' prefix for printing return
+ values. Printing return values has been the default for quite some time.
diff --git a/docs/thanks.md b/docs/thanks.md
index e15bddc6..660030ba 100644
--- a/docs/thanks.md
+++ b/docs/thanks.md
@@ -1,7 +1,7 @@
## Thanks
-Thank you everyone for your contributions and feedback. They have helped make
-Textadept the amazing editor that it is today.
+Thank you everyone for your contributions and feedback. They have helped make Textadept the
+amazing editor that it is today.
### Sponsors
@@ -11,15 +11,13 @@ Textadept the amazing editor that it is today.
#### Become a Sponsor
-You, your company, or your organization may sponsor a feature in Textadept. The
-feature will be included in subsequent releases of Textadept and will also be
-available under Textadept's open source license. You will be credited on this
-page with an optional link to your website, and will receive a proper receipt or
-invoice for recording and/or tax-related purposes.
+You, your company, or your organization may sponsor a feature in Textadept. The feature will
+be included in subsequent releases of Textadept and will also be available under Textadept's
+open source license. You will be credited on this page with an optional link to your website,
+and will receive a proper receipt or invoice for recording and/or tax-related purposes.
-Please send any inquiries by e-mail (see README.md). All correspondence is kept
-strictly confidential. You may also contact me for private contract work related
-to Textadept.
+Please send any inquiries by e-mail (see README.md). All correspondence is kept strictly
+confidential. You may also contact me for private contract work related to Textadept.
### Code and Documentation Contributors
@@ -65,5 +63,4 @@ to Textadept.
* Vais Salikhov
* Vladimir Lomov
-If I have left off your name, please contact me (see README.md). I am very sorry
-about that.
+If I have left off your name, please contact me (see README.md). I am very sorry about that.