diff options
author | mitchell <70453897+orbitalquark@users.noreply.github.com> | 2021-04-11 09:34:17 -0400 |
---|---|---|
committer | mitchell <70453897+orbitalquark@users.noreply.github.com> | 2021-04-11 09:34:17 -0400 |
commit | de3a745e1af2e441de868c2aa4849102d376acb5 (patch) | |
tree | c2d7767600dc519b2613ddecaf7e53fb5e8867a2 /docs | |
parent | 03fab17277fee7387fd93a9c2774b1ebf3f80fe4 (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.md | 4967 | ||||
-rw-r--r-- | docs/book.md | 24 | ||||
-rw-r--r-- | docs/changelog.md | 1004 | ||||
-rw-r--r-- | docs/faq.md | 150 | ||||
-rw-r--r-- | docs/index.html | 220 | ||||
-rw-r--r-- | docs/manual.md | 2294 | ||||
-rw-r--r-- | docs/thanks.md | 21 |
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 "\\"" in a double-quoted string indicates that the -'"' 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 +"\\"" in a double-quoted string indicates that the '"' 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 "()", "[]", -"{}", "''", and """". +The ASCII values of opening characters are assigned to strings that contain complement +characters. The default auto-paired characters are "()", "[]", "{}", "''", and +"""". 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 ')', ']', '}', ''', and '"'. +The ASCII values of characters are keys and are assigned non-`nil` values. The default +characters are ')', ']', '}', ''', and '"'. 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+| |⌘| |^\ |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+| | ⌘| | ^\ | 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’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’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" /> @@ -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’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’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" /> <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" /> - <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’s binary packages are self-contained and need not be - installed. No administrator privilages are required either. + Textadept’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’s <em>docs/</em> directory. It - covers all of Textadept’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’s <em>docs/</em> directory. It covers all of Textadept’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’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’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’s rich API - into a series of tasks in a convenient and easy-to-use manner. It - serves as the perfect complement to Textadept’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’s rich API into a series of tasks + in a convenient and easy-to-use manner. It serves as the perfect complement to + Textadept’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’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’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’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’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. ![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) ![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 (''' and '"'). 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 (''' and '"'). 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) ![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) @@ -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) ![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 - |%b*xy* |Matches a balanced string bounded by *x* and *y* - |%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 + | %b*xy* | Matches a balanced string bounded by *x* and *y* + | %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. |