diff options
65 files changed, 9515 insertions, 11386 deletions
diff --git a/.clang-format b/.clang-format new file mode 100644 index 00000000..0f587890 --- /dev/null +++ b/.clang-format @@ -0,0 +1,13 @@ +BasedOnStyle: LLVM +AlignAfterOpenBracket: DontAlign +AlignEscapedNewlines: DontAlign +AlignOperands: DontAlign +AlignTrailingComments: false +AllowShortBlocksOnASingleLine: Always +AllowShortCaseLabelsOnASingleLine: true +AllowShortIfStatementsOnASingleLine: true +AllowShortLoopsOnASingleLine: true +BreakBeforeTernaryOperators: false +ColumnLimit: 100 +ContinuationIndentWidth: 2 +SortIncludes: false diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ee181d42..98866771 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -22,9 +22,9 @@ jobs: - name: Git init if necessary shell: bash run: | - # If git version is less than 2.18, a git clone will not be made in - # this container. In that case, make a temporary repository so - # "make release" can archive the repo's contents for release. + # If git version is less than 2.18, a git clone will not be made in this container. In + # that case, make a temporary repository so "make release" can archive the repo's + # contents for release. if [[ -d .git ]]; then exit 0; fi git init git add . @@ -59,24 +59,22 @@ jobs: # Output version information for use in later steps. version="${{ github.event.inputs.tag }}" if [[ -z $version ]]; then - version=`ls -1 src/textadept_*.zip | head -1 | - sed 's/[^_]\+_\(.\+\)\.[^.]\+\.zip/\1/;'` + version=`ls -1 src/textadept_*.zip | head -1 | sed 's/[^_]\+_\(.\+\)\.[^.]\+\.zip/\1/;'` fi echo "::set-output name=version::$version" - name: Package modules shell: bash run: | mkdir textadept-modules - modules="css ctags debugger export file_diff html lsp lua_repl \ - open_file_mode python rest ruby spellcheck yaml" + modules="css ctags debugger export file_diff html lsp lua_repl open_file_mode python \ + rest ruby spellcheck yaml" for module in $modules; do gh_name="`echo -n $module | sed -e 's/_/-/g;'`" gh_prefix="https://github.com/orbitalquark/textadept-$gh_name" wget $gh_prefix/releases/download/latest/$module.zip unzip -d textadept-modules $module.zip done - zip -r src/textadept_${{ steps.build.outputs.version }}.modules.zip \ - textadept-modules + zip -r src/textadept_${{ steps.build.outputs.version }}.modules.zip textadept-modules - name: Upload artifacts uses: actions/upload-artifact@v2 with: diff --git a/.lua-format b/.lua-format new file mode 100644 index 00000000..fed2dc47 --- /dev/null +++ b/.lua-format @@ -0,0 +1,8 @@ +column_limit: 100 +indent_width: 2 +continuation_indent_width: 2 +align_args: false +align_parameter: false +align_table_field: false +chop_down_kv_table: false +spaces_before_call: 0 @@ -1,6 +1,6 @@ The MIT License -Copyright (c) 2007-2020 Mitchell +Copyright (c) 2007-2021 Mitchell Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -1,13 +1,11 @@ # Textadept -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 for more than 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 for more than 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://lua.org @@ -21,47 +19,42 @@ version that runs within a terminal emulator. * Can be entirely keyboard driven. * Powerful snippets and key commands. * Code autocompletion and documentation lookup. -* Remarkably extensible, with a heavily documented Application Programming - Interface (API). +* Remarkably extensible, with a heavily documented Application Programming Interface (API). ## 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). Lua and any other third-party -dependencies are compiled into the application itself. +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). Lua and +any other third-party dependencies are compiled into the application itself. [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. [1]: https://github.com/orbitalquark/textadept/releases [2]: https://orbitalquark.github.io/textadept/changelog.html ## Installation and Usage -Textadept comes with a comprehensive [user manual][] in its *docs/* directory. -It covers all of Textadept's main features, including installation, usage, -configuration, theming, scripting, and compilation. +Textadept comes with a comprehensive [user manual][] in its *docs/* directory. It covers all +of Textadept's main features, including installation, usage, configuration, theming, scripting, +and compilation. -Since nearly every aspect of Textadept can be scripted using Lua, the editor's -API is heavily documented. This [API documentation][] is also located in -*docs/*. It serves as the ultimate resource when it comes to scripting the -application. +Since nearly every aspect of Textadept can be scripted using Lua, the editor's API is heavily +documented. This [API documentation][] is also located in *docs/*. It serves as the ultimate +resource when it comes to scripting the application. -A more structured scripting resource is [Textadept Quick Reference][], which -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. This book serves as the perfect complement to Textadept's -Manual and exhaustive API documentation. +A more structured scripting resource is [Textadept Quick Reference][], which 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. This book serves as the perfect +complement to Textadept's Manual and exhaustive API documentation. [user manual]: https://orbitalquark.github.io/textadept/manual.html [API documentation]: https://orbitalquark.github.io/textadept/api.html @@ -69,46 +62,44 @@ Manual and exhaustive API documentation. ## Compile -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. -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. +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. General 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 * [mingw-w64][] 5.0+ with GCC 7.1+ when cross-compiling for Windows. * [OSX cross toolchain][] with [Clang][] 4.0+ when cross-compiling for macOS. * _**OR**_ * [Docker][] -The following table provides a brief list 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 curses` |Builds the terminal version of Textadept -`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 +The following table provides a brief list 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 curses` | Builds the terminal version of Textadept +`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 When building within Docker, the relevant container [image][] is `ghcr.io/orbitalquark/textadept-build:v1.0`. @@ -128,12 +119,10 @@ For more information on compiling Textadept, please see the [manual][]. ## Contribute -Your [donation][] or purchase of the [book][] helps fund Textadept's continuous -development. +Your [donation][] or purchase of the [book][] helps fund Textadept's continuous development. -Textadept is [open source][]. Feel free to discuss features, report bugs, and -submit patches. You can also contact me personally -(orbitalquark.att.triplequasar.com). +Textadept is [open source][]. Feel free to discuss features, report bugs, and submit patches. You +can also contact me personally (orbitalquark.att.triplequasar.com). [donation]: https://gum.co/textadept [book]: https://orbitalquark.github.io/textadept/book.html diff --git a/core/._M.luadoc b/core/._M.luadoc index 8f94a93d..b720d336 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -1,19 +1,16 @@ -- Copyright 2007-2020 Mitchell. See LICENSE. --- This is a DUMMY FILE used for making LuaDoc for built-in functions in the --- global _M table. +-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the global _M table. ---[[ This comment is for LuaDoc. --- -- 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 @@ -27,31 +24,27 @@ -- -- ### Block Comment -- --- Many languages have different syntaxes for single line comments and --- multi-line comments in source code. Textadept's block comment feature only --- uses one of those syntaxes for a given language. If you prefer the other --- syntax, or if Textadept does not support block comments for a particular --- language, modify the [`textadept.editing.comment_string`]() table. For --- example: +-- Many languages have different syntaxes for single line comments and multi-line comments in +-- source code. Textadept's block comment feature only uses one of those syntaxes for a given +-- language. If you prefer the other syntax, or if Textadept does not support block comments +-- for a particular language, modify the [`textadept.editing.comment_string`]() table. For example: -- -- textadept.editing.comment_string.ansi_c = '//' -- change from /* ... */ -- -- ### Compile and Run -- --- Textadept knows most of the commands that compile and/or run code in source --- files. However, it does not know all of them, and the ones that it does know --- may not be completely accurate in all cases. Compile and run commands are --- read from the [`textadept.run.compile_commands`]() and --- [`textadept.run.run_commands`]() tables using the appropriate lexer 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`]() +-- and [`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`](). 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`](). The Lua error pattern looks like: -- -- local patterns = textadept.run.error_patterns -- if not patterns.lua then patterns.lua = {} end @@ -59,31 +52,30 @@ -- -- ### 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", @@ -94,10 +86,10 @@ -- -- ### 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() @@ -105,12 +97,11 @@ -- 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'] = { -- ... @@ -118,9 +109,8 @@ -- -- ### 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', @@ -130,4 +120,4 @@ -- local tools = textadept.menu.menubar[_L['Tools']] -- tools[#tools + 1] = lua_menu -- textadept.menu.context_menu[#textadept.menu.context_menu + 1] = lua_menu -module('_M')]] +module('_M') diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index e2d45e71..8a136a3a 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -4,17 +4,15 @@ --- -- 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`](), 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`](), even if undocumented. +-- Any buffer fields set on startup (e.g. in *~/.textadept/init.lua*) will be the default, +-- initial values for all buffers. -- @field additional_selection_typing (bool) -- Type into multiple selections. -- The default value is `false`. @@ -24,17 +22,16 @@ -- Table of the number of annotation text lines per line number. -- @field 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. -- @field annotation_text (table) -- Table of annotation text per line number. -- @field 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`. -- @field 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`. -- @field auto_c_case_insensitive_behavior (number) @@ -59,8 +56,8 @@ -- Delete any word characters immediately to the right of autocompleted text. -- The default value is `false`. -- @field 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 `''`. -- @field auto_c_ignore_case (bool) -- Ignore case when searching an autocompletion or user list for matches. @@ -78,8 +75,7 @@ -- The order setting for autocompletion and user lists. -- -- * `buffer.ORDER_PRESORTED` --- Lists passed to [`buffer.auto_c_show()`]() are in sorted, alphabetical --- order. +-- Lists passed to [`buffer.auto_c_show()`]() are in sorted, alphabetical order. -- * `buffer.ORDER_PERFORMSORT` -- Sort autocompletion lists passed to [`buffer.auto_c_show()`](). -- * `buffer.ORDER_CUSTOM` @@ -87,16 +83,13 @@ -- -- The default value is `buffer.ORDER_PRESORTED`. -- @field 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` (' '). -- @field 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()`]() or --- [`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()`]() or [`view.register_rgba_image()`]() +-- before appending image types to list items after type separator characters. -- The default value is 63 ('?'). -- @field back_space_un_indents (bool) -- Un-indent text when backspacing within indentation. @@ -107,11 +100,10 @@ -- * `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`. -- @field char_at (table, Read-only) @@ -125,18 +117,17 @@ -- @field encoding (string or nil) -- The string encoding of the file, or `nil` for binary files. -- @field 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. -- @field 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. -- @field eol_annotation_text (table) -- Table of EOL annotation text per line number. -- @field eol_mode (number) --- The current end of line mode. Changing the current mode does not convert --- any of the buffer's existing end of line characters. --- Use [`buffer.convert_eols()`]() to do so. +-- The current end of line mode. +-- Changing the current mode does not convert any of the buffer's existing end of line +-- characters. Use [`buffer.convert_eols()`]() to do so. -- -- * `buffer.EOL_CRLF` -- Carriage return with line feed ("\r\n"). @@ -145,14 +136,12 @@ -- * `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. -- @field filename (string) -- The absolute file path associated with the buffer. -- @field 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. @@ -167,17 +156,16 @@ -- The number of spaces in one level of indentation. -- The default value is `0`, which uses the value of [`buffer.tab_width`](). -- @field indicator_current (number) --- The indicator number in the range of `1` to `32` used by --- [`buffer.indicator_fill_range()`]() and --- [`buffer.indicator_clear_range()`](). +-- The indicator number in the range of `1` to `32` used by [`buffer.indicator_fill_range()`]() +-- and [`buffer.indicator_clear_range()`](). -- @field length (number, Read-only) -- The number of bytes in the buffer. -- @field line_count (number, Read-only) -- The number of lines in the buffer. -- There is always at least one. -- @field 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. -- @field line_indent_position (table, Read-only) -- Table of positions at the ends of indentation per line number. -- @field line_indentation (table) @@ -189,8 +177,8 @@ -- Table of text displayed in text margins per line number. -- @field 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. -- @field modify (bool, Read-only) -- Whether or not the buffer has unsaved changes. -- @field move_extends_selection (bool, Read-only) @@ -214,8 +202,7 @@ -- @field punctuation_chars (string) -- The string set of characters recognized as punctuation characters. -- Set this only after setting [`buffer.word_chars`](). --- The default value is a string that contains all non-word and non-whitespace --- characters. +-- The default value is a string that contains all non-word and non-whitespace characters. -- @field read_only (bool) -- Whether or not the buffer is read-only. -- The default value is `false`. @@ -235,8 +222,7 @@ -- * `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. -- @@ -258,36 +244,33 @@ -- * `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()`]() is called. +-- When set, caret movement alters the selected text until this field is set again to the +-- same value or until [`buffer.cancel()`]() is called. -- @field 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. -- @field 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. -- @field 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. -- @field 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. -- @field 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. -- @field 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. -- @field 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. -- @field 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. -- @field selection_start (number) -- The position of the beginning of the selected text. -- When set, becomes the anchor, but is not scrolled into view. @@ -310,24 +293,22 @@ -- This is also set by a successful [`buffer.search_in_target()`](). -- @field 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`]() or --- [`buffer.target_end`]() is set, or when [`buffer.set_target_range()`]() is --- called. +-- This is set to `1` when [`buffer.target_start`]() or [`buffer.target_end`]() is set, +-- or when [`buffer.set_target_range()`]() is called. -- @field target_start (number) -- The position of the beginning of the target range. -- This is also set by a successful [`buffer.search_in_target()`](). -- @field 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`]() or --- [`buffer.target_end`]() is set, or when [`buffer.set_target_range()`]() is --- called. +-- This is set to `1` when [`buffer.target_start`]() or [`buffer.target_end`]() is set, +-- or when [`buffer.set_target_range()`]() is called. -- @field target_text (string, Read-only) -- The text in the target range. -- @field text_length (number, Read-only) -- The number of bytes in the buffer. -- @field 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()`]() to do so. -- The default value is `true`. -- @field virtual_space_options (number) @@ -340,23 +321,21 @@ -- * `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`. -- @field whitespace_chars (string) -- The string set of characters recognized as whitespace characters. -- Set this only after setting [`buffer.word_chars`](). --- The default value is a string that contains all non-newline characters less --- than ASCII value 33. +-- The default value is a string that contains all non-newline characters less than ASCII +-- value 33. -- @field 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. -- @field FIND_MATCHCASE (number, Read-only) -- -- @field FIND_REGEXP (number, Read-only) @@ -444,21 +423,19 @@ module('buffer') --- --- 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. -- @param buffer A buffer. -- @param end_pos The caret position of the range of text to select in *buffer*. --- @param start_pos The anchor position of the range of text to select in --- *buffer*. +-- @param start_pos The anchor position of the range of text to select in *buffer*. -- @see set_selection function add_selection(buffer, end_pos, start_pos) end --- --- 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. -- @param buffer A buffer. -- @param text The text to add. function add_text(buffer, text) end @@ -469,8 +446,8 @@ function add_text(buffer, text) end function annotation_clear_all(buffer) end --- --- 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. -- @param buffer A buffer. -- @param text The text to append. function append_text(buffer, text) end @@ -492,42 +469,38 @@ function auto_c_cancel(buffer) end function auto_c_complete(buffer) end --- --- 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. -- @param buffer A buffer. -- @return number function auto_c_pos_start(buffer) end --- --- 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`. -- @param buffer A buffer. -- @param prefix The item in the list to select. function auto_c_select(buffer, prefix) end --- --- 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. -- @param buffer A buffer. --- @param len_entered The number of characters before the caret used to provide --- the context. --- @param items The sorted string of words to show, separated by --- `buffer.auto_c_separator` characters (initially spaces). +-- @param len_entered The number of characters before the caret used to provide the context. +-- @param items The sorted string of words to show, separated by `buffer.auto_c_separator` +-- characters (initially spaces). -- @see auto_c_separator -- @see auto_c_order function auto_c_show(buffer, len_entered, items) end --- --- 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. -- @param buffer A buffer. --- @param chars The string of characters that cancel autocompletion. This string --- is empty by default. +-- @param chars The string of characters that cancel autocompletion. This string is empty +-- by default. function auto_c_stops(buffer, chars) end --- @@ -542,10 +515,10 @@ function back_tab(buffer) end function begin_undo_action(buffer) end --- --- 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. -- @param buffer A buffer. -- @param pos The position of the brace in *buffer* to match. -- @param max_re_style Must be `0`. Reserved for expansion. @@ -565,8 +538,7 @@ function can_redo(buffer) end function can_undo(buffer) end --- --- Cancels the active selection mode, autocompletion or user list, call tip, --- etc. +-- Cancels the active selection mode, autocompletion or user list, call tip, etc. -- @param buffer A buffer. function cancel(buffer) end @@ -576,14 +548,12 @@ function cancel(buffer) end function char_left(buffer) end --- --- 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. -- @param buffer A buffer. function char_left_extend(buffer) end --- --- 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. -- @param buffer A buffer. function char_left_rect_extend(buffer) end @@ -593,20 +563,18 @@ function char_left_rect_extend(buffer) end function char_right(buffer) end --- --- 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. -- @param buffer A buffer. function char_right_extend(buffer) end --- --- 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. -- @param buffer A buffer. function char_right_rect_extend(buffer) end --- --- 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. -- @param buffer A buffer. -- @see caret_sticky function choose_caret_x(buffer) end @@ -627,14 +595,13 @@ function clear_all(buffer) end function clear_document_style(buffer) end --- --- 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. -- @param buffer A buffer. --- @param start_pos The start position of the range of text in *buffer* to --- process. --- @param 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*. +-- @param start_pos The start position of the range of text in *buffer* to process. +-- @param 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*. function colorize(buffer, start_pos, end_pos) end --- @@ -648,15 +615,13 @@ function convert_eols(buffer, mode) end --- -- 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. -- @param buffer A buffer. function copy(buffer) end --- --- 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*. -- @param buffer A buffer. -- @param start_pos The start position of the range of text in *buffer* to copy. -- @param end_pos The end position of the range of text in *buffer* to copy. @@ -669,27 +634,23 @@ function copy_range(buffer, start_pos, end_pos) end function copy_text(buffer, text) end --- --- 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*. -- @param buffer A buffer. --- @param start_pos The start position of the range of text in *buffer* to start --- counting at. --- @param end_pos The end position of the range of text in *buffer* to stop --- counting at. +-- @param start_pos The start position of the range of text in *buffer* to start counting at. +-- @param end_pos The end position of the range of text in *buffer* to stop counting at. -- @return number function count_characters(buffer, start_pos, end_pos) end --- -- 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. -- @param buffer A buffer. function cut(buffer) end --- --- 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. -- @param buffer A buffer. function del_line_left(buffer) end @@ -699,22 +660,19 @@ function del_line_left(buffer) end function del_line_right(buffer) end --- --- 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. -- @param buffer A buffer. function del_word_left(buffer) end --- --- 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. -- @param buffer A buffer. function del_word_right(buffer) end --- --- 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. -- @param buffer A buffer. function del_word_right_end(buffer) end @@ -726,8 +684,8 @@ function del_word_right_end(buffer) end function delete_back(buffer) end --- --- 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. -- @param buffer A buffer. function delete_back_not_line(buffer) end @@ -745,8 +703,7 @@ function delete_range(buffer, pos, length) end function document_end(buffer) end --- --- 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. -- @param buffer A buffer. function document_end_extend(buffer) end @@ -756,8 +713,7 @@ function document_end_extend(buffer) end function document_start(buffer) end --- --- 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. -- @param buffer A buffer. function document_start_extend(buffer) end @@ -788,9 +744,8 @@ function end_undo_action(buffer) end function eol_annotation_clear_all(buffer) end --- --- 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*. -- @param buffer A buffer. -- @param line The line number in *buffer* to use. -- @param column The column number to use. @@ -803,8 +758,8 @@ function find_column(buffer, line, column) end function get_cur_line(buffer) end --- --- 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*. -- @param buffer A buffer. -- @param line The line number in *buffer* of a header line. @@ -820,9 +775,8 @@ function get_line(buffer, line) end --- -- 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. -- @param buffer A buffer. -- @return string, number function get_sel_text(buffer) end @@ -833,8 +787,8 @@ function get_sel_text(buffer) end function get_text(buffer) end --- --- 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. -- @param buffer A buffer. -- @param line The line number in *buffer* to go to. function goto_line(buffer, line) end @@ -856,26 +810,26 @@ function home(buffer) end function home_display(buffer) end --- --- 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. -- @param buffer A buffer. function home_display_extend(buffer) end --- --- 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. -- @param buffer A buffer. function home_extend(buffer) end --- --- 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. -- @param buffer A buffer. function home_rect_extend(buffer) end --- --- 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. -- @param buffer A buffer. function home_wrap(buffer) end @@ -886,26 +840,23 @@ function home_wrap_extend(buffer) end --- -- 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. -- @param buffer A buffer. -- @param pos The position in *buffer* to get indicators at. -- @return number function indicator_all_on_for(buffer, pos) end --- --- 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*. -- @param buffer A buffer. --- @param pos The start position of the range of text in *buffer* to clear --- indicators over. --- @param length The number of characters in the range of text to clear --- indicators over. +-- @param pos The start position of the range of text in *buffer* to clear indicators over. +-- @param length The number of characters in the range of text to clear indicators over. function indicator_clear_range(buffer, pos, length) end --- --- 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. -- @param buffer A buffer. -- @param indicator An indicator number in the range of `1` to `32`. @@ -913,18 +864,16 @@ function indicator_clear_range(buffer, pos, length) end function indicator_end(buffer, indicator, pos) end --- --- 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`. -- @param buffer A buffer. --- @param pos The start position of the range of text in *buffer* to set --- indicators over. --- @param length The number of characters in the range of text to set indicators --- over. +-- @param pos The start position of the range of text in *buffer* to set indicators over. +-- @param length The number of characters in the range of text to set indicators over. function indicator_fill_range(buffer, pos, length) end --- --- 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. -- @param buffer A buffer. -- @param indicator An indicator number in the range of `1` to `32`. @@ -934,22 +883,19 @@ function indicator_start(buffer, indicator, pos) end --- -- 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. -- @param buffer A buffer. --- @param pos The position in *buffer* to insert text at, or `-1` for the --- current position. +-- @param pos The position in *buffer* to insert text at, or `-1` for the current position. -- @param text The text to insert. function insert_text(buffer, pos, text) end --- --- 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. -- @param buffer A buffer. --- @param start_pos The start position of the range of text in *buffer* to --- check for a word boundary at. --- @param end_pos The end position of the range of text in *buffer* to check for --- a word boundary at. +-- @param start_pos The start position of the range of text in *buffer* to check for a word +-- boundary at. +-- @param end_pos The end position of the range of text in *buffer* to check for a word +-- boundary at. function is_range_word(buffer, start_pos, end_pos) end --- @@ -973,14 +919,12 @@ function line_delete(buffer) end function line_down(buffer) end --- --- 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. -- @param buffer A buffer. function line_down_extend(buffer) end --- --- 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. -- @param buffer A buffer. function line_down_rect_extend(buffer) end @@ -1000,49 +944,46 @@ function line_end(buffer) end function line_end_display(buffer) end --- --- 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. -- @param buffer A buffer. function line_end_display_extend(buffer) end --- --- 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. -- @param buffer A buffer. function line_end_extend(buffer) end --- --- 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. -- @param buffer A buffer. function line_end_rect_extend(buffer) end --- --- 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. -- @param buffer A buffer. function line_end_wrap(buffer) end --- --- 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. -- @param buffer A buffer. function line_end_wrap_extend(buffer) end --- -- 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`. -- @param buffer A buffer. -- @param pos The position in *buffer* to get the line number of. -- @return number function line_from_position(buffer, pos) end --- --- 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)`. -- @param buffer A buffer. -- @param line The line number in *buffer* to get the length of. -- @return number @@ -1069,24 +1010,21 @@ function line_up(buffer) end function line_up_extend(buffer) end --- --- 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. -- @param buffer A buffer. function line_up_rect_extend(buffer) end --- --- 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. -- @param buffer A buffer. function lines_join(buffer) end --- -- 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. -- @param buffer A buffer. --- @param width The pixel width to split lines at. When `0`, uses the width of --- the view. +-- @param width The pixel width to split lines at. When `0`, uses the width of the view. function lines_split(buffer, pixel_width) end --- @@ -1100,10 +1038,9 @@ function lower_case(buffer) end function margin_text_clear_all(buffer) end --- --- 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. -- @param buffer A buffer. -- @param line The line number to add the marker on. -- @param marker The marker number in the range of `1` to `32` to add. @@ -1111,32 +1048,30 @@ function margin_text_clear_all(buffer) end function marker_add(buffer, line, marker) end --- --- 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. -- @param buffer A buffer. -- @param line The line number to add the markers on. --- @param 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. +-- @param 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. function marker_add_set(buffer, line, marker_mask) end --- --- 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*. -- @param buffer A buffer. -- @param line The line number to delete the marker on. --- @param marker The marker number in the range of `1` to `32` to delete from --- *line*, or `-1` to delete all markers from the line. +-- @param marker The marker number in the range of `1` to `32` to delete from *line*, or `-1` +-- to delete all markers from the line. function marker_delete(buffer, line, marker) end --- --- 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. -- @param buffer A buffer. --- @param 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. +-- @param 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. function marker_delete_all(buffer, marker) end --- @@ -1147,60 +1082,56 @@ function marker_delete_handle(buffer, handle) end --- -- 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. -- @param buffer A buffer. -- @param line The line number to get markers on. -- @return number function marker_get(buffer, line) end --- --- 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. -- @param buffer A buffer. -- @param line The line number to get markers on. -- @param n The marker to get the handle of. function marker_handle_from_line(buffer, line, n) end --- --- 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. -- @param buffer A buffer. -- @param handle The identifier of a marker returned by `buffer.marker_add()`. -- @return number function marker_line_from_handle(buffer, handle) end --- --- 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. -- @param buffer A buffer. -- @param line The start line to search from. --- @param 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. +-- @param 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 number function marker_next(buffer, line, marker_mask) end --- --- 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. -- @param buffer A buffer. -- @param line The line number to get markers on. -- @param n The marker to get the number of. function marker_number_from_line(buffer, line, n) end --- --- 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. -- @param buffer A buffer. -- @param line The start line to search from. --- @param 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. +-- @param 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 number function marker_previous(buffer, line, marker_mask) end @@ -1220,16 +1151,14 @@ function move_selected_lines_down(buffer) end function move_selected_lines_up(buffer) end --- --- 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. -- @param buffer A buffer. function multiple_select_add_each(buffer) end --- --- 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. -- @param buffer A buffer. function multiple_select_add_next(buffer) end @@ -1252,14 +1181,12 @@ function new_line(buffer) end function page_down(buffer) end --- --- 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. -- @param buffer A buffer. function page_down_extend(buffer) end --- --- 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. -- @param buffer A buffer. function page_down_rect_extend(buffer) end @@ -1274,8 +1201,7 @@ function page_up(buffer) end function page_up_extend(buffer) end --- --- 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. -- @param buffer A buffer. function page_up_rect_extend(buffer) end @@ -1286,8 +1212,7 @@ function page_up_rect_extend(buffer) end function para_down(buffer) end --- --- 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. -- @param buffer A buffer. function para_down_extend(buffer) end @@ -1299,30 +1224,27 @@ function para_down_extend(buffer) end function para_up(buffer) end --- --- 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. -- @param buffer A buffer. function para_up_extend(buffer) end --- --- 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`. -- @param buffer A buffer. function paste(buffer) end --- --- 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*. -- @param buffer A buffer. -- @param pos The position in *buffer* to get the position after from. function position_after(buffer, pos) end --- --- 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*. -- @param buffer A buffer. -- @param pos The position in *buffer* to get the position before from. -- @return number @@ -1337,15 +1259,13 @@ function position_before(buffer, pos) end function position_from_line(buffer, line) end --- --- 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`. -- @param buffer A buffer. -- @param pos The position in *buffer* to get the relative position from. --- @param 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. +-- @param 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 number function position_relative(buffer, pos, n) end @@ -1361,20 +1281,18 @@ function redo(buffer) end function replace_sel(buffer, text) end --- --- 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. -- @param buffer A buffer. -- @param text The text to replace the target range with. -- @return number function replace_target(buffer, text) end --- --- 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. -- @param buffer A buffer. -- @param text The text to replace the target range with. -- @return number @@ -1386,16 +1304,16 @@ function replace_target_re(buffer, text) end function rotate_selection(buffer) end --- --- 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. -- @param buffer A buffer. function search_anchor(buffer) end --- --- 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. -- @param buffer A buffer. -- @param text The text to search the target range for. -- @return number @@ -1403,9 +1321,9 @@ function search_anchor(buffer) end function search_in_target(buffer, text) end --- --- 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. -- @param buffer A buffer. -- @param flags The search flags to use. See `buffer.search_flags`. @@ -1415,9 +1333,8 @@ function search_in_target(buffer, text) end function search_next(buffer, flags, text) end --- --- 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. -- @param buffer A buffer. -- @param flags The search flags to use. See `buffer.search_flags`. -- @param text The text to search for. @@ -1437,8 +1354,8 @@ function select_all(buffer) end function selection_duplicate(buffer) end --- --- 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. -- @param buffer A buffer. -- @see word_chars -- @see whitespace_chars @@ -1446,8 +1363,7 @@ function selection_duplicate(buffer) end function set_chars_default(buffer) end --- --- 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. -- @param buffer A buffer -- @param pos The position in *buffer* to move to. function set_empty_selection(buffer, pos) end @@ -1458,29 +1374,26 @@ function set_empty_selection(buffer, pos) end function set_save_point(buffer) end --- --- 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. -- @param buffer A buffer. --- @param start_pos The start position of the range of text in *buffer* to --- select. If negative, it means the end of the buffer. --- @param 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`). +-- @param start_pos The start position of the range of text in *buffer* to select. If negative, +-- it means the end of the buffer. +-- @param 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`). function set_sel(buffer, start_pos, end_pos) end --- --- 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. -- @param buffer A buffer. -- @param end_pos The caret position of the range of text to select in *buffer*. --- @param start_pos The anchor position of the range of text to select in --- *buffer*. +-- @param start_pos The anchor position of the range of text to select in *buffer*. function set_selection(buffer, end_pos, start_pos) end --- --- 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`]() should be called before `buffer:set_styling()`. -- @param buffer A buffer. -- @param length The number of characters to style. @@ -1488,8 +1401,8 @@ function set_selection(buffer, end_pos, start_pos) end function set_styling(buffer, length, style) end --- --- 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. -- @param buffer A buffer. -- @param start_pos The position of the beginning of the target range. -- @param end_pos The position of the end of the target range. @@ -1503,8 +1416,7 @@ function set_text(buffer, text) end --- -- 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()`. -- @param buffer A buffer. -- @param position The position in *buffer* to start styling at. -- @param unused Unused number. `0` can be safely used. @@ -1513,14 +1425,12 @@ function set_text(buffer, text) end function start_styling(buffer, position, unused) end --- --- 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. -- @param buffer A buffer. function stuttered_page_down(buffer) end --- --- 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. -- @param buffer A buffer. function stuttered_page_down_extend(buffer) end @@ -1530,8 +1440,7 @@ function stuttered_page_down_extend(buffer) end function stuttered_page_up(buffer) end --- --- 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. -- @param buffer A buffer. function stuttered_page_up_extend(buffer) end @@ -1541,26 +1450,25 @@ function stuttered_page_up_extend(buffer) end function swap_main_anchor_caret(buffer) end --- --- 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. -- @param buffer A buffer. function tab(buffer) end --- --- 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. -- @param buffer A buffer. function target_from_selection(buffer) end --- --- 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. -- @param buffer A buffer. function target_whole_document(buffer) end --- --- 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`. -- @param buffer A buffer. -- @see caret_sticky function toggle_caret_sticky(buffer) end @@ -1576,35 +1484,32 @@ function undo(buffer) end function upper_case(buffer) end --- --- 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. -- @param buffer A buffer. -- @param id The list identifier number greater than zero to use. --- @param items The sorted string of words to show, separated by --- `buffer.auto_c_separator` characters (initially spaces). +-- @param items The sorted string of words to show, separated by `buffer.auto_c_separator` +-- characters (initially spaces). -- @see _SCINTILLA.next_user_list_type -- @see events.USER_LIST_SELECTION function user_list_show(buffer, id, items) end --- --- 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. -- @param buffer A buffer. function vc_home(buffer) end --- --- 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. -- @param buffer A buffer. function vc_home_display(buffer) end --- --- 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. -- @param buffer A buffer. function vc_home_display_extend(buffer) end @@ -1614,35 +1519,32 @@ function vc_home_display_extend(buffer) end function vc_home_extend(buffer) end --- --- 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. -- @param buffer A buffer. function vc_home_rect_extend(buffer) end --- --- 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. -- @param buffer A buffer. function vc_home_wrap(buffer) end --- --- 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. -- @param buffer A buffer. function vc_home_wrap_extend(buffer) end --- -- 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. -- @param buffer A buffer. -- @param pos The position in *buffer* of the word. --- @param 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. +-- @param 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. function word_end_position(buffer, pos, only_word_chars) end --- @@ -1652,55 +1554,48 @@ function word_end_position(buffer, pos, only_word_chars) end function word_left(buffer) end --- --- 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. -- @param buffer A buffer. function word_left_end(buffer) end --- --- 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. -- @param buffer A buffer. function word_left_end_extend(buffer) end --- --- 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. -- @param buffer A buffer. function word_left_extend(buffer) end --- -- 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. -- @param buffer A buffer. function word_part_left(buffer) end --- --- 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. -- @param buffer A buffer. function word_part_left_extend(buffer) end --- -- 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. -- @param buffer A buffer. function word_part_right(buffer) end --- --- 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. -- @param buffer A buffer. function word_part_right_extend(buffer) end @@ -1712,45 +1607,40 @@ function word_part_right_extend(buffer) end function word_right(buffer) end --- --- 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. -- @param buffer A buffer. function word_right_end(buffer) end --- --- 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. -- @param buffer A buffer. function word_right_end_extend(buffer) end --- --- 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. -- @param buffer A buffer. function word_right_extend(buffer) end --- -- 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. -- @param buffer A buffer. -- @param pos The position in *buffer* of the word. --- @param 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. +-- @param 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. function word_start_position(buffer, pos, only_word_chars) end -- External functions. --- -- 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. -- @param buffer A buffer. -- @see events.BUFFER_DELETED function delete(buffer) end @@ -1771,8 +1661,8 @@ function new() end function text_range(buffer, start_pos, end_pos) end --- --- 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. -- @param buffer A buffer. -- @param string The style name to get the number of. -- @return style number, between `1` and `256`. @@ -1781,8 +1671,7 @@ function style_of_name(buffer, style_name) end --- -- 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. -- @param buffer A buffer. -- @name reload function reload(buffer) end @@ -1799,18 +1688,17 @@ function save(buffer) end -- Saves the buffer to file *filename* or the user-specified filename. -- Emits a `FILE_AFTER_SAVE` event. -- @param buffer A buffer. --- @param filename Optional new filepath to save the buffer to. If `nil`, the --- user is prompted for one. +-- @param filename Optional new filepath to save the buffer to. If `nil`, the user is prompted +-- for one. -- @name save_as function save_as(buffer, filename) end --- --- 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. -- @param buffer A buffer. --- @param force Optional flag that discards unsaved changes without prompting --- the user. The default value is `false`. +-- @param force Optional flag that discards unsaved changes without prompting the user. The +-- default value is `false`. -- @return `true` if the buffer was closed; `nil` otherwise. -- @name close function close(buffer, force) end @@ -1818,27 +1706,26 @@ function close(buffer, force) end --- -- Converts the buffer's contents to encoding *encoding*. -- @param buffer A buffer. --- @param encoding The string encoding to set. Valid encodings are ones that GNU --- iconv accepts. If `nil`, assumes a binary encoding. +-- @param encoding The string encoding to set. Valid encodings are ones that GNU iconv accepts. If +-- `nil`, assumes a binary encoding. -- @usage buffer:set_encoding('CP1252') function set_encoding(buffer, encoding) end --- -- 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. -- @param buffer A buffer. --- @param 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. +-- @param 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. function get_lexer(buffer, current) end --- --- 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. -- @param buffer A buffer. --- @param name Optional string lexer name to set. If `nil`, attempts to --- auto-detect the buffer's lexer. +-- @param name Optional string lexer name to set. If `nil`, attempts to auto-detect the +-- buffer's lexer. -- @usage buffer:set_lexer('lexer_name') function set_lexer(buffer, name) end diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc index adaeaea3..89471c59 100644 --- a/core/.iconv.luadoc +++ b/core/.iconv.luadoc @@ -1,26 +1,23 @@ -- Copyright 2007-2020 Mitchell. See LICENSE. --- This is a DUMMY FILE used for making LuaDoc for built-in functions in the --- string table. +-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the string table. --- Extends Lua's `string` library to provide character set conversions. module('string') --- --- 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. @@ -29,8 +26,8 @@ module('string') -- * 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/ -- @param text The text to convert. diff --git a/core/.os.luadoc b/core/.os.luadoc index 8ce09344..03d76bca 100644 --- a/core/.os.luadoc +++ b/core/.os.luadoc @@ -1,34 +1,30 @@ -- Copyright 2007-2020 Mitchell. See LICENSE. --- This is a DUMMY FILE used for making LuaDoc for built-in functions in the --- os table. +-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the os table. --- Extends Lua's `os` library to provide process spawning capabilities. module('os') --- --- 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. --- @param cmd A command line string that contains the program's name followed by --- arguments to pass to it. `PATH` is searched for program names. --- @param cwd Optional current working directory (cwd) for the child --- process. When omitted, the parent's cwd is used. --- @param env Optional map of environment variables for the child process. --- When omitted, Textadept's environment is used. --- @param 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. --- @param 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. --- @param 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. +-- @param cmd A command line string that contains the program's name followed by arguments to +-- pass to it. `PATH` is searched for program names. +-- @param cwd Optional current working directory (cwd) for the child process. When omitted, +-- the parent's cwd is used. +-- @param env Optional map of environment variables for the child process. When omitted, +-- Textadept's environment is used. +-- @param 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. +-- @param 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. +-- @param exit_cb Optional Lua function that is called when the child process finishes. The +-- child's exit status is passed. -- @return proc or nil plus an error message on failure -- @usage os.spawn('lua ' .. buffer.filename, print) -- @usage proc = os.spawn('lua -e "print(io.read())"', print) @@ -38,48 +34,42 @@ module('os') local spawn --- --- 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 "running" or "terminated" function spawn_proc:status() end --- --- 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 integer status code function spawn_proc:wait() end --- --- 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. --- @param 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. +-- 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. +-- @param 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 string of bytes read function spawn_proc:read(arg) end --- -- 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). -- @param ... Standard input for *spawn_proc*. function spawn_proc:write(...) end --- --- 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. function spawn_proc:close() end --- -- Kills running process *spawn_proc*, or sends it Unix signal *signal*. --- @param signal Optional Unix signal to send to *spawn_proc*. The default value --- is 9 (`SIGKILL`), which kills the process. +-- @param signal Optional Unix signal to send to *spawn_proc*. The default value is 9 (`SIGKILL`), +-- which kills the process. function spawn_proc:kill() end diff --git a/core/.ui.dialogs.luadoc b/core/.ui.dialogs.luadoc index 3b13b8cb..fd327254 100644 --- a/core/.ui.dialogs.luadoc +++ b/core/.ui.dialogs.luadoc @@ -1,40 +1,34 @@ -- Copyright 2007-2020 Mitchell. See LICENSE. --- This is a DUMMY FILE used for making LuaDoc for built-in functions in the --- ui.dialogs table. +-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the ui.dialogs table. --- Provides a set of interactive dialog prompts for user input. module('ui.dialogs') --- --- 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"`. -- @param options Table of key-value option pairs for the message box. -- -- * `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. -- @return selected button or exit code -- @usage ui.dialogs.msgbox{title = 'EOL Mode', text = 'Which EOL?', -- icon = 'gtk-dialog-question', button1 = 'CRLF', button2 = 'CR', @@ -42,396 +36,332 @@ module('ui.dialogs') function msgbox(options) end --- --- 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"`. -- @param options Table of key-value option pairs for the message box. -- -- * `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 selected button or exit code function ok_msgbox(options) end --- --- 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"`. -- @param options Table of key-value option pairs for the message box. -- -- * `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 selected button or exit code function yesno_msgbox(options) end --- --- 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"`. -- @param 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 selected button or exit code, input text -- @usage ui.dialogs.inputbox{title = 'Goto Line', informative_text = 'Line:', -- text = '1'} function inputbox(options) end --- --- 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"`. -- @param 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 selected button or exit code, input text function standard_inputbox(options) end --- --- 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"`. -- @param 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 selected button or exit code, input text function secure_inputbox(options) end --- --- 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"`. -- @param 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 selected button or exit code, input text function secure_standard_inputbox(options) end --- --- 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`. -- @param options Table of key-value option pairs for the dialog. -- -- * `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`. -- @return filename, list of filenames, or nil -- @usage ui.dialogs.fileselect{title = 'Open C File', with_directory = _HOME, -- with_extension = {'c', 'h'}, select_multiple = true} function fileselect(options) end --- --- 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`. -- @param options Table of key-value option pairs for the dialog. -- -- * `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 filename or nil function filesave(options) end --- --- 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"`. -- @param options Table of key-value option pairs for the dialog. -- -- * `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. -- @return selected button or exit code, textbox text --- @usage ui.dialogs.textbox{title = 'License Agreement', --- informative_text = 'You agree to:', text_from_file = _HOME..'/LICENSE'} +-- @usage ui.dialogs.textbox{title = 'License Agreement', informative_text = 'You agree to:', +-- text_from_file = _HOME..'/LICENSE'} function textbox(options) end --- --- 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`. -- @param options Table of key-value option pairs for the progressbar dialog. -- -- * `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. --- @param 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. +-- @param 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. -- @return nil or "stopped" -- @usage ui.dialogs.progressbar({stoppable = true}, -- function() if work() then return percent, status else return nil end end) function progressbar(options, f) end --- --- 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"`. -- @param options Table of key-value option pairs for the drop-down dialog. -- -- * `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. -- @return selected button or exit code, selected item --- @usage ui.dialogs.dropdown{title = 'Select Encoding', width = 200, --- items = io.encodings, string_output = true} +-- @usage ui.dialogs.dropdown{title = 'Select Encoding', width = 200, items = io.encodings, +-- string_output = true} function dropdown(options) end --- --- 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"`. -- @param options Table of key-value option pairs for the drop-down dialog. -- -- * `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 selected button or exit code, selected item function standard_dropdown(options) end --- --- 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. -- @param options Table of key-value option pairs for the filtered list dialog. -- @@ -440,64 +370,51 @@ function standard_dropdown(options) end -- * `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. -- @return selected button or exit code, selected item or list of selected items -- @usage ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'}, -- items = {'a', 'b', 'c', 'd'}} function filteredlist(options) end --- --- 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"`. -- @param options Table of key-value option pairs for the option select dialog. -- -- * `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. -- @return selected button or exit code, list of selected options -- @usage ui.dialogs.optionselect{title = 'Language', -- informative_text = 'Check the languages you understand', @@ -505,30 +422,28 @@ function filteredlist(options) end function optionselect(options) end --- --- 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`. -- @param 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`. -- @return selected color -- @usage ui.dialogs.colorselect{title = 'Foreground color', color = 0x000000, -- palette = {'#000000', 0x0000FF, '#00FF00', 0xFF0000}} function colorselect(options) end --- --- 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`. -- @param options Table of key-value option pairs for the option select dialog. -- @@ -536,12 +451,9 @@ function colorselect(options) end -- * `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`. -- @return selected font, including style and size --- @usage ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace', --- font_size = 10} +-- @usage ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace', font_size = 10} function fontselect(options) end diff --git a/core/.view.luadoc b/core/.view.luadoc index 8fb460de..88d9e218 100644 --- a/core/.view.luadoc +++ b/core/.view.luadoc @@ -4,17 +4,15 @@ --- -- 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`](), 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`](), even if undocumented. +-- Any view fields set on startup (e.g. in *~/.textadept/init.lua*) will be the default, +-- initial values for all views. -- @field additional_caret_fore (number) -- The foreground color, in "0xBBGGRR" format, of additional carets. -- @field additional_carets_blink (bool) @@ -24,8 +22,7 @@ -- Display additional carets. -- The default value is `true`. -- @field 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. -- @field additional_sel_back (number, Write-only) -- The background color, in "0xBBGGRR" format, of additional selections. @@ -43,20 +40,17 @@ -- * `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. -- -- The default value is `view.ANNOTATION_HIDDEN`. -- @field 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`. -- @field 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. -- @field call_tip_fore_hlt (number, Write-only) -- A call tip's highlighted text foreground color, in "0xBBGGRR" format. -- @field call_tip_pos_start (number, Write-only) @@ -66,31 +60,27 @@ -- The default value is `false`. -- @field 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`. -- @field caret_fore (number) -- The caret's foreground color, in "0xBBGGRR" format. -- @field 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. -- @field 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. -- @field 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`. -- @field caret_line_visible (bool) -- Color the background of the line that contains the caret a different color. -- The default value is `false`. -- @field 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. -- @field caret_period (number) -- The time between caret blinks in milliseconds. -- A value of `0` stops blinking. @@ -105,9 +95,8 @@ -- * `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`. -- @field caret_width (number) @@ -127,8 +116,8 @@ -- -- The default value is `view.CURSORNORMAL`. -- @field 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`. -- @field edge_column (number) -- The column number to mark long lines at. -- @field edge_mode (number) @@ -137,11 +126,11 @@ -- * `view.EDGE_NONE` -- Long lines are not marked. -- * `view.EDGE_LINE` --- Draw a single vertical line whose color is [`view.edge_color`]() at --- column [`view.edge_column`](). +-- Draw a single vertical line whose color is [`view.edge_color`]() at column +-- [`view.edge_column`](). -- * `view.EDGE_BACKGROUND` --- Change the background color of text after column [`view.edge_column`]() --- to [`view.edge_color`](). +-- Change the background color of text after column [`view.edge_column`]() to +-- [`view.edge_color`](). -- * `view.EDGE_MULTILINE` -- Draw vertical lines whose colors and columns are defined by calls to -- [`view:multi_edge_add_line()`](). @@ -179,10 +168,10 @@ -- -- The default value is `view.FOLDDISPLAYTEXT_HIDDEN`. -- @field 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()`]() 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()`]() instead. -- @field fold_flags (number, Read-only) -- Bit-mask of folding lines to draw in the buffer. -- @@ -206,8 +195,8 @@ -- Display the horizontal scroll bar. -- The default value is `true`. -- @field 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. -- @field idle_styling (number) -- The idle styling mode. -- This mode has no effect when `view.wrap_mode` is on. @@ -215,8 +204,8 @@ -- * `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` @@ -225,45 +214,42 @@ -- The default value is `view.IDLESTYLING_NONE`. -- @field 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`. -- @field 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. -- @field 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. -- @field 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. -- @field 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. -- @field 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. -- @field indic_style (table) -- Table of styles for indicator numbers from `1` to `32`. @@ -283,10 +269,9 @@ -- * `view.INDIC_BOX` -- A bounding box. -- * `view.INDIC_ROUNDBOX` --- A translucent box with rounded corners around the text. Use --- [`view.indic_alpha`]() and [`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`]() and +-- [`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` @@ -297,22 +282,20 @@ -- 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`]() and --- [`view.indic_outline_alpha`]() starting with the top-left pixel. +-- Translucency alternates between [`view.indic_alpha`]() and [`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` @@ -321,21 +304,20 @@ -- 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()`]() for custom indicators. -- Changing an indicator's style resets that indicator's hover style. -- @field 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`. -- @field 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. -- @field lines_on_screen (number, Read-only) -- The number of completely visible lines in the view. -- It is possible to have a partial line visible at the bottom of the view. @@ -343,12 +325,11 @@ -- The number of margins. -- The default value is `5`. -- @field 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`. -- @field 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. @@ -360,44 +341,39 @@ -- The pixel size of the left margin of the buffer text. -- The default value is `1`. -- @field 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. -- @field margin_options (number) -- 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`. -- @field margin_right (number) -- The pixel size of the right margin of the buffer text. -- The default value is `1`. -- @field 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`. -- @field 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` @@ -405,32 +381,27 @@ -- * `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. -- @field 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). -- @field 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. -- @field 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`. -- @field 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`. -- @field 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`. -- @field 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. -- @field mouse_selection_rectangular_switch (bool) --- Whether or not pressing [`view.rectangular_selection_modifier`]() when --- selecting text normally with the mouse turns on rectangular selection. +-- Whether or not pressing [`view.rectangular_selection_modifier`]() when selecting text +-- normally with the mouse turns on rectangular selection. -- The default value is `false`. -- @field multi_edge_column (table, Read-only) -- Table of edge column positions per edge column number. @@ -438,14 +409,13 @@ -- @field property (table) -- Map of key-value string pairs used by lexers. -- @field 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. -- @field 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. -- @field 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. @@ -458,39 +428,34 @@ -- The default value is `view.MOD_CTRL`. -- @field 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()`]() to remove a representation. -- @field rgba_image_height (number) --- The height of the RGBA image to be defined using --- [`view.marker_define_rgba_image()`](). +-- The height of the RGBA image to be defined using [`view.marker_define_rgba_image()`](). -- @field rgba_image_scale (number) -- The scale factor in percent of the RGBA image to be defined using -- [`view.marker_define_rgba_image()`](). --- This is useful on macOS with a retina display where each display unit is 2 --- pixels: use a factor of `200` so that each image pixel is displayed using a --- screen pixel. The default scale, `100`, will stretch each image pixel to --- cover 4 screen pixels on a retina display. +-- 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. -- @field rgba_image_width (number) --- The width of the RGBA image to be defined using --- [`view.marker_define_rgba_image()`]() and +-- The width of the RGBA image to be defined using [`view.marker_define_rgba_image()`]() and -- [`view.register_rgba_image()`](). -- @field 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`](). +-- 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`](). -- The default value is `2000`. -- @field scroll_width_tracking (bool) --- Continuously update the horizontal scrolling width to match the maximum --- width of a displayed line beyond [`view.scroll_width`](). +-- Continuously update the horizontal scrolling width to match the maximum width of a displayed +-- line beyond [`view.scroll_width`](). -- The default value is `false`. -- @field 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. -- @field sel_eol_filled (bool) -- Extend the selection to the view's right margin. @@ -498,11 +463,9 @@ -- @field size (number) -- The split resizer's pixel position if the view is a split one. -- @field 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`. -- @field 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`. -- @field style_case (table) -- Table of letter case modes of text for style numbers from `1` to `256`. @@ -518,33 +481,32 @@ -- -- The default values are `view.CASE_MIXED`. -- @field 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. -- @field 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`. -- @field style_font (table) -- Table of string font names of text for style numbers from `1` to `256`. -- @field 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`. -- @field 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`. -- @field style_size (table) -- Table of font sizes of text for style numbers from `1` to `256`. -- @field 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`. -- @field 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`. -- @field tab_draw_mode (number) -- The draw mode of visible tabs. @@ -575,8 +537,7 @@ -- -- The default value is `view.WS_INVISIBLE`. -- @field 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`. -- @field wrap_indent_mode (number) -- The wrapped line indent mode. @@ -634,8 +595,8 @@ -- The default value is `view.WRAPVISUALFLAGLOC_DEFAULT`. -- @field 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. -- @field zoom (number) -- The number of points to add to the size of all fonts. -- Negative values are allowed, down to `-10`. @@ -949,37 +910,34 @@ module('view') local buffer --- --- 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`. -- @param view A view. --- @param pos The position in *view*'s buffer to highlight, or `-1` to remove --- the highlight. +-- @param pos The position in *view*'s buffer to highlight, or `-1` to remove the highlight. function brace_bad_light(view, pos) end --- --- 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`. -- @param view A view. -- @param use_indicator Whether or not to use an indicator. -- @param indicator The indicator number to use. function brace_bad_light_indicator(view, use_indicator, indicator) end --- --- 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. -- @param view A view. -- @param pos1 The first position in *view*'s buffer to highlight. -- @param pos2 The second position in *view*'s buffer to highlight. function brace_highlight(view, pos1, pos2) end --- --- 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`. -- @param view A view. -- @param use_indicator Whether or not to use an indicator. -- @param indicator The indicator number to use. @@ -1003,52 +961,49 @@ function call_tip_cancel(view) end function call_tip_pos_start(view) end --- --- 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`. -- @param view A view. -- @param start_pos The start position in a call tip text to highlight. -- @param end_pos The end position in a call tip text to highlight. function call_tip_set_hlt(view, start_pos, end_pos) end --- --- 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. -- @param view A view. -- @param pos The position in *view*'s buffer to show a call tip at. -- @param text The call tip text to show. function call_tip_show(view, pos, text) end --- --- 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()`. -- @param view A view. function clear_registered_images(view) end --- --- 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). -- @param view A view. --- @param char The string character in `buffer.representations` to remove the --- alternate string representation for. +-- @param char The string character in `buffer.representations` to remove the alternate string +-- representation for. function clear_representation(view, char) end --- --- 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. -- @param view A view. -- @param line The line number in *view* to start at. -- @return number function contracted_fold_next(view, line) end --- --- 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`. -- @param view A view. -- @param display_line The display line number to use. -- @return number @@ -1061,17 +1016,15 @@ function doc_line_from_visible(view, display_line) end function ensure_visible(view, line) end --- --- 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()`. -- @param view A view. -- @param line The line number in *view* to ensure visible. function ensure_visible_enforce_policy(view, line) end --- -- 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. -- @param view A view. -- @param action The fold action to perform. Valid values are: -- * `view.FOLDACTION_CONTRACT` @@ -1080,8 +1033,8 @@ function ensure_visible_enforce_policy(view, line) end function fold_all(view, action) end --- --- 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*. -- @param view A view. -- @param line The line number in *view* to set the fold states for. -- @param action The fold action to perform. Valid values are: @@ -1091,8 +1044,7 @@ function fold_all(view, action) end function fold_children(view, line, action) end --- --- 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*. -- @param view A view. -- @param line The line number in *view* to set the fold state for. -- @param action The fold action to perform. Valid values are: @@ -1108,8 +1060,7 @@ function get_default_fold_display_text(view) end --- -- 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. -- @param view A view. -- @param start_line The start line of the range of lines in *view* to hide. -- @param end_line The end line of the range of lines in *view* to hide. @@ -1134,70 +1085,57 @@ function line_scroll_down(view) end function line_scroll_up(view) end --- --- 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*. -- @param view A view. --- @param marker The marker number in the range of `1` to `32` to set *symbol* --- for. +-- @param marker The marker number in the range of `1` to `32` to set *symbol* for. -- @param symbol The marker symbol: `buffer.MARK_*`. -- @see _SCINTILLA.next_marker_number function marker_define(view, marker, symbol) end --- --- 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*. -- @param view A view. --- @param marker The marker number in the range of `1` to `32` to define --- pixmap *pixmap* for. +-- @param marker The marker number in the range of `1` to `32` to define pixmap *pixmap* for. -- @param pixmap The string pixmap data. function marker_define_pixmap(view, marker, pixmap) end --- --- 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*. -- @param view A view. --- @param marker The marker number in the range of `1` to `32` to define RGBA --- data *pixels* for. --- @param 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 +-- @param marker The marker number in the range of `1` to `32` to define RGBA data *pixels* for. +-- @param 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]`. function marker_define_rgba_image(view, marker, pixels) end --- --- 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`. -- @param view A view. -- @param enabled Whether or not to enable highlight. function marker_enable_highlight(view, enabled) end --- --- 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()`. -- @param view A view. --- @param marker The marker number in the range of `1` to `32` to get the symbol --- of. +-- @param marker The marker number in the range of `1` to `32` to get the symbol of. -- @return number function marker_symbol_defined(view, marker) end --- --- 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. -- @param view A view. -- @param column The column number to add a vertical line at. -- @param color The color in "0xBBGGRR" format. @@ -1209,24 +1147,20 @@ function multi_edge_add_line(view, column, color) end function multi_edge_clear_all(view) end --- --- 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. -- @param view A view. -- @param type Integer type to register the image with. -- @param xpm_data The XPM data as described in `view.marker_define_pixmap()`. function register_image(view, type, xpm_data) end --- --- 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. -- @param view A view. -- @param type Integer type to register the image with. --- @param pixels The RGBA data as described in --- `view.marker_define_rgba_image()`. +-- @param pixels The RGBA data as described in `view.marker_define_rgba_image()`. function register_rgba_image(view, type, pixels) end --- @@ -1248,10 +1182,9 @@ function scroll_to_end(view) end function scroll_to_start(view) end --- --- 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. -- @param view A view. -- @param secondary_pos The secondary range position to scroll into view. @@ -1266,25 +1199,24 @@ function scroll_range(view, secondary_pos, primary_pos) end function set_default_fold_display_text(view, text) end --- --- 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`. -- @param view A view. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. function set_fold_margin_color(view, use_setting, color) end --- --- 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`. -- @param view A view. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. function set_fold_margin_hi_color(view, use_setting, color) end --- --- 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. -- @param view A view. -- @param use_setting Whether or not to use *color*. @@ -1292,8 +1224,8 @@ function set_fold_margin_hi_color(view, use_setting, color) end function set_sel_back(view, use_setting, color) end --- --- 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. -- @param view A view. -- @param use_setting Whether or not to use *color*. @@ -1301,53 +1233,52 @@ function set_sel_back(view, use_setting, color) end function set_sel_fore(view, use_setting, color) end --- --- 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()`. -- @param view A view. --- @param policy The combination of `view.VISIBLE_SLOP` and --- `view.VISIBLE_STRICT` policy flags to set. +-- @param policy The combination of `view.VISIBLE_SLOP` and `view.VISIBLE_STRICT` policy flags +-- to set. -- @param y The number of lines from the vertical margins to keep the caret. function set_visible_policy(view, policy, y) end --- --- 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`. -- @param view A view. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. function set_whitespace_back(view, use_setting, color) end --- --- 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`. -- @param use_setting Whether or not to use *color*. -- @param color The color in "0xBBGGRR" format. function set_whitespace_fore(view, use_setting, color) end --- --- 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. -- @param view A view. --- @param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, --- `view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set. +-- @param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, `view.CARET_EVEN`, +-- and `view.CARET_JUMPS` policy flags to set. -- @param x The number of pixels from the horizontal margins to keep the caret. function set_x_caret_policy(view, policy, x) end --- --- 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. -- @param view A view. --- @param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, --- `view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set. +-- @param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, `view.CARET_EVEN`, +-- and `view.CARET_JUMPS` policy flags to set. -- @param y The number of lines from the vertical margins to keep the caret. function set_y_caret_policy(view, policy, y) end --- -- 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. -- @param view A view. -- @param start_line The start line of the range of lines in *view* to show. -- @param end_line The end line of the range of lines in *view* to show. @@ -1371,8 +1302,8 @@ function style_reset_default(view) end function text_height(view, line) end --- --- 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`. -- @param view A view. -- @param style_num The style number between `1` and `256` to use. -- @param text The text to measure the width of. @@ -1380,22 +1311,20 @@ function text_height(view, line) end function text_width(view, style_num, text) end --- --- 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). -- @param view A view. -- @param line The line number in *view* to toggle the fold on. -- @see set_default_fold_display_text function toggle_fold(view, line) end --- --- 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`. -- @param view A view. --- @param line The line number in *view* to toggle the fold on and display --- *text* after. +-- @param line The line number in *view* to toggle the fold on and display *text* after. -- @param text The text to display after the line. function toggle_fold_show_text(view, line, text) end @@ -1405,9 +1334,8 @@ function toggle_fold_show_text(view, line, text) end function vertical_center_caret(view) end --- --- 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. -- @param view A view. -- @param line The line number in *view* to use. @@ -1415,8 +1343,7 @@ function vertical_center_caret(view) end function visible_from_doc_line(view, line) end --- --- 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*. -- @param view A view. -- @param line The line number in *view* to use. -- @return number @@ -1435,14 +1362,13 @@ function zoom_out(view) end -- External functions. --- --- 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. -- @param view The view to split. --- @param vertical Optional flag indicating whether or not to split the view --- vertically. The default value is `false`, for horizontal. +-- @param vertical Optional flag indicating whether or not to split the view vertically. The +-- default value is `false`, for horizontal. -- @return old view and new view. -- @see events.VIEW_NEW function split(view, vertical) end @@ -1454,8 +1380,8 @@ function split(view, vertical) end function unsplit(view) end --- --- 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. -- @param view The view to switch buffers in. -- @param buffer A buffer or relative buffer number (typically 1 or -1). @@ -1465,15 +1391,14 @@ function unsplit(view) end function goto_buffer(view, buffer) end --- --- 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. -- @param view A view. -- @param name The name or absolute path of a theme to set. --- @param env Optional table of global variables themes can utilize to override --- default settings such as font and size. +-- @param env Optional table of global variables themes can utilize to override default settings +-- such as font and size. -- @usage view:set_theme('light', {font = 'Monospace', size = 12}) -- @name set_theme -- @see _G.lexer.colors diff --git a/core/args.lua b/core/args.lua index 0f805168..17c808d6 100644 --- a/core/args.lua +++ b/core/args.lua @@ -17,17 +17,14 @@ events.ARG_NONE = 'arg_none' local options = {} --- --- 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. -- @param short The string short version of the option. -- @param long The string long version of the option. -- @param narg The number of expected parameters for the option. --- @param f The Lua function to run when the option is set. It is passed *narg* --- string arguments. --- @param description The string description of the option for command line --- help. +-- @param f The Lua function to run when the option is set. It is passed *narg* string arguments. +-- @param description The string description of the option for command line help. -- @name register function M.register(short, long, narg, f, description) local option = { @@ -38,14 +35,12 @@ function M.register(short, long, narg, f, description) options[assert_type(long, 'string', 2)] = option end --- Processes command line argument table *arg*, handling options previously --- defined using `args.register()` and treating unrecognized arguments as --- filenames to open. --- Emits an `ARG_NONE` event when no arguments are present unless --- *no_emit_arg_none* is `true`. +-- Processes command line argument table *arg*, handling options previously defined using +-- `args.register()` and treating unrecognized arguments as filenames to open. +-- Emits an `ARG_NONE` event when no arguments are present unless *no_emit_arg_none* is `true`. -- @param arg Argument table. --- @param no_emit_arg_none When `true`, do not emit `ARG_NONE` when no arguments --- are present. The default value is `false`. +-- @param no_emit_arg_none When `true`, do not emit `ARG_NONE` when no arguments are present. +-- The default value is `false`. -- @see register -- @see _G.events local function process(arg, no_emit_arg_none) @@ -79,12 +74,10 @@ if not CURSES then print('Usage: textadept [args] [filenames]') local list = {} for name in pairs(options) do list[#list + 1] = name end - table.sort( - list, function(a, b) return a:match('[^-]+') < b:match('[^-]+') end) + table.sort(list, function(a, b) return a:match('[^-]+') < b:match('[^-]+') end) for _, name in ipairs(list) do local option = options[name] - print(string.format( - ' %s [%d args]: %s', name, option.narg, option.description)) + print(string.format(' %s [%d args]: %s', name, option.narg, option.description)) end os.exit() end, 'Shows this') @@ -93,10 +86,9 @@ if not CURSES then print(_RELEASE .. '\n' .. _COPYRIGHT) quit() end, 'Prints Textadept version and copyright') - -- After Textadept finishes initializing and processes arguments, remove the - -- help and version options in order to prevent another instance from sending - -- '-h', '--help', '-v', and '--version' to the first instance, killing the - -- latter. + -- After Textadept finishes initializing and processes arguments, remove the help and + -- version options in order to prevent another instance from sending '-h', '--help', '-v', + -- and '--version' to the first instance, killing the latter. events.connect(events.INITIALIZED, function() options['-h'], options['--help'] = nil, nil options['-v'], options['--version'] = nil, nil @@ -104,8 +96,7 @@ if not CURSES then end -- Set `_G._USERHOME`. --- This needs to be set as soon as possible since the processing of arguments is --- positional. +-- This needs to be set as soon as possible since the processing of arguments is positional. _USERHOME = os.getenv(not WIN32 and 'HOME' or 'USERPROFILE') .. '/.textadept' for i, option in ipairs(arg) do if (option == '-u' or option == '--userhome') and arg[i + 1] then @@ -115,23 +106,19 @@ for i, option in ipairs(arg) do end local mode = lfs.attributes(_USERHOME, 'mode') assert(not mode or mode == 'directory', '"%s" is not a directory', _USERHOME) -if not mode then - assert(lfs.mkdir(_USERHOME), 'cannot create "%s"', _USERHOME) -end +if not mode then assert(lfs.mkdir(_USERHOME), 'cannot create "%s"', _USERHOME) end local user_init = _USERHOME .. '/init.lua' mode = lfs.attributes(user_init, 'mode') assert(not mode or mode == 'file', '"%s" is not a file (%s)', user_init, mode) -if not mode then - assert(io.open(user_init, 'w'), 'unable to create "%s"', user_init):close() -end +if not mode then assert(io.open(user_init, 'w'), 'unable to create "%s"', user_init):close() end -- Placeholders. M.register('-u', '--userhome', 1, function() end, 'Sets alternate _USERHOME') M.register('-f', '--force', 0, function() end, 'Forces unique instance') -- Run unit tests. --- Note: have them run after the last `events.INITIALIZED` handler so everything --- is completely initialized (e.g. menus, macro module, etc.). +-- Note: have them run after the last `events.INITIALIZED` handler so everything is completely +-- initialized (e.g. menus, macro module, etc.). M.register('-t', '--test', 1, function(patterns) events.connect(events.INITIALIZED, function() local arg = {} diff --git a/core/assert.lua b/core/assert.lua index c0e7f44c..95b53628 100644 --- a/core/assert.lua +++ b/core/assert.lua @@ -6,35 +6,30 @@ module('assert')]] --- --- 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. -- @param v Value to assert. --- @param message Optional error message to show on error. The default value is --- "assertion failed!". --- @param ... If *message* is a format string, these arguments are passed to --- `string.format()`. +-- @param message Optional error message to show on error. The default value is "assertion failed!". +-- @param ... If *message* is a format string, these arguments are passed to `string.format()`. -- @name _G.assert function assert(v, message, ...) if v then return v end - if type(message) == 'string' and message:find('%%') then - message = string.format(message, ...) - end + if type(message) == 'string' and message:find('%%') then message = string.format(message, ...) end error(message or 'assertion failed!', 2) end --- --- 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. -- @param v Value to assert the type of. --- @param expected_type String type to assert. It may be a non-letter-delimited --- list of type options. --- @param narg The positional argument number *v* is associated with. This is --- not required to be a number. +-- @param expected_type String type to assert. It may be a non-letter-delimited list of type +-- options. +-- @param narg The positional argument number *v* is associated with. This is not required to +-- be a number. -- @usage assert_type(filename, 'string/nil', 1) -- @usage assert_type(option.setting, 'number', 'setting') -- implicates key -- @name _G.assert_type @@ -42,18 +37,13 @@ function assert_type(v, expected_type, narg) if type(v) == expected_type then return v end -- Note: do not use assert for performance reasons. if type(expected_type) ~= 'string' then - error(string.format( - "bad argument #2 to '%s' (string expected, got %s)", + error(string.format("bad argument #2 to '%s' (string expected, got %s)", debug.getinfo(1, 'n').name, type(expected_type)), 2) elseif narg == nil then - error(string.format( - "bad argument #3 to '%s' (value expected, got %s)", + error(string.format("bad argument #3 to '%s' (value expected, got %s)", debug.getinfo(1, 'n').name, type(narg)), 2) end - for type_option in expected_type:gmatch('%a+') do - if type(v) == type_option then return v end - end - error(string.format( - "bad argument #%s to '%s' (%s expected, got %s)", narg, + for type_option in expected_type:gmatch('%a+') do if type(v) == type_option then return v end end + error(string.format("bad argument #%s to '%s' (%s expected, got %s)", narg, debug.getinfo(2, 'n').name or '?', expected_type, type(v)), 3) end diff --git a/core/events.lua b/core/events.lua index c1a3aca0..07829919 100644 --- a/core/events.lua +++ b/core/events.lua @@ -6,25 +6,23 @@ local M = {} --- -- Textadept's core event structure and handlers. -- --- Textadept emits events when you do things like create a new buffer, press a --- key, click on a menu, etc. You can even emit events yourself using Lua. Each --- event has a set of event handlers, which are simply Lua functions called in --- the order they were connected to an event. For example, if you created a --- module that needs to do something each time Textadept creates a new buffer, --- connect a Lua function to the [`events.BUFFER_NEW`]() event: +-- Textadept emits events when you do things like create a new buffer, press a key, click on +-- a menu, etc. You can even emit events yourself using Lua. Each event has a set of event +-- handlers, which are simply Lua functions called in the order they were connected to an +-- event. For example, if you created a module that needs to do something each time Textadept +-- creates a new buffer, connect a Lua function to the [`events.BUFFER_NEW`]() event: -- -- events.connect(events.BUFFER_NEW, function() -- -- Do something here. -- end) -- --- Events themselves are nothing special. You do not have to declare one before --- using it. Events are simply strings containing arbitrary event names. When --- either you or Textadept emits an event, Textadept runs all event handlers --- connected to the event, passing any given arguments to the event's handler --- functions. If an event handler explicitly returns a value that is not `nil`, --- Textadept will not call subsequent handlers. This is useful if you want to --- stop the propagation of an event like a keypress if your event handler --- handled it, or if you want to use the event framework to pass values. +-- Events 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. -- -- @field APPLEEVENT_ODOC (string) -- Emitted when macOS tells Textadept to open a file. @@ -32,22 +30,20 @@ local M = {} -- -- * _`uri`_: The UTF-8-encoded URI to open. -- @field 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. -- @field AUTO_C_CANCELED (string) -- Emitted when canceling an autocompletion or user list. -- @field 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. -- * _`position`_: The autocompleted word's beginning position. -- @field 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()`]() 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()`]() before returning +-- from the event handler. -- Arguments: -- -- * _`text`_: The selection's text. @@ -56,8 +52,7 @@ local M = {} -- Emitted as items are highlighted in an autocompletion or user list. -- Arguments: -- --- * _`id`_: Either the *id* from [`buffer.user_list_show()`]() or `0` for an --- autocompletion list. +-- * _`id`_: Either the *id* from [`buffer.user_list_show()`]() or `0` for an autocompletion list. -- * _`text`_: The current selection's text. -- * _`position`_: The position the list was displayed at. -- @field BUFFER_AFTER_SWITCH (string) @@ -79,8 +74,8 @@ local M = {} -- 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. -- @field CHAR_ADDED (string) -- Emitted after the user types a text character into the buffer. -- Arguments: @@ -95,33 +90,28 @@ local M = {} -- -- * _`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. -- @field CSI (string) -- 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. -- @field 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*. -- * _`x`_: The x-coordinate of the mouse in the view. -- * _`y`_: The y-coordinate of the mouse in the view. -- @field DWELL_START (string) --- Emitted when the mouse is stationary for [`view.mouse_dwell_time`]() --- milliseconds. +-- Emitted when the mouse is stationary for [`view.mouse_dwell_time`]() milliseconds. -- Arguments: -- -- * _`position`_: The position closest to *x* and *y*. @@ -139,8 +129,7 @@ local M = {} -- * _`text`_: The text to search for. -- * _`next`_: Whether or not to search forward. -- @field 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. -- @field FOCUS (string) -- Emitted when Textadept receives focus. @@ -150,16 +139,13 @@ local M = {} -- 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. -- @field 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. @@ -182,29 +168,24 @@ local M = {} -- -- * _`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. -- @field MENU_CLICKED (string) -- Emitted after selecting a menu item. -- Arguments: -- --- * _`menu_id`_: The numeric ID of the menu item, which was defined in --- [`ui.menu()`](). +-- * _`menu_id`_: The numeric ID of the menu item, which was defined in [`ui.menu()`](). -- @field 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. @@ -213,11 +194,10 @@ local M = {} -- * _`alt`_: The "Alt"/"Option" modifier key is held down. -- @field 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()`](). -- @field REPLACE (string) -- Emitted to replace selected (found) text. @@ -235,15 +215,15 @@ local M = {} -- Emitted by [`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. -- @field RESET_BEFORE (string) -- Emitted before resetting Textadept's Lua state. -- Emitted by [`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. -- @field RESUME (string) -- Emitted when resuming Textadept from a suspended state. -- This event is only emitted by the terminal version. @@ -252,20 +232,18 @@ local M = {} -- @field SAVE_POINT_REACHED (string) -- Emitted after reaching a save point. -- @field 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. -- @field 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. @@ -320,16 +298,17 @@ module('events')]] -- Handler tables are auto-created as needed. -- @class table -- @name handlers -local handlers = setmetatable({}, {__index = function(t, k) - t[k] = {} - return t[k] -end}) +local handlers = setmetatable({}, { + __index = function(t, k) + t[k] = {} + return t[k] + end +}) --- --- 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. -- @param event The string event name. -- @param f The Lua function to connect to *event*. -- @param index Optional index to insert the handler into. @@ -353,23 +332,24 @@ end function M.disconnect(event, f) assert_type(f, 'function', 2) for i = 1, #handlers[assert_type(event, 'string', 1)] do - if handlers[event][i] == f then table.remove(handlers[event], i) break end + if handlers[event][i] == f then + table.remove(handlers[event], i) + break + end end end local error_emitted = false --- --- 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. -- @param event The string event name. -- @param ... Arguments passed to the handler. --- @return `nil` unless any any handler explicitly returned a non-`nil` value; --- otherwise returns that value +-- @return `nil` unless any any handler explicitly returned a non-`nil` value; otherwise returns +-- that value -- @usage events.emit('my_event', 'my message') -- @name emit function M.emit(event, ...) @@ -402,7 +382,9 @@ end) -- Set event constants. for _, v in pairs(_SCINTILLA.events) do M[v[1]:upper()] = v[1] end +-- LuaFormatter off local textadept_events = {'appleevent_odoc','buffer_after_switch','buffer_before_switch','buffer_deleted','buffer_new','csi','command_text_changed','error','find','find_text_changed','focus','initialized','keypress','menu_clicked','mouse','quit','replace','replace_all','reset_after','reset_before','resume','suspend', 'tab_clicked','unfocus','view_after_switch','view_before_switch','view_new'} +-- LuaFormatter on for _, v in pairs(textadept_events) do M[v:upper()] = v end return M diff --git a/core/file_io.lua b/core/file_io.lua index 6bd3692d..6760c4cd 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -27,12 +27,11 @@ -- 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. -- @field _G.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. @@ -42,7 +41,9 @@ module('io')]] -- Events. +-- LuaFormatter off local file_io_events = {'file_opened','file_before_reload','file_after_reload','file_before_save','file_after_save','file_changed'} +-- LuaFormatter on for _, v in ipairs(file_io_events) do events[v:upper()] = v end io.quick_open_max = 1000 @@ -55,16 +56,15 @@ io.recent_files = {} --- -- 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/ -- @usage io.encodings[#io.encodings + 1] = 'UTF-32' @@ -73,14 +73,12 @@ io.recent_files = {} io.encodings = {'UTF-8', 'ASCII', 'CP1252', 'UTF-16'} --- --- 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. --- @param filenames Optional string filename or table of filenames to open. If --- `nil`, the user is prompted with a fileselect dialog. --- @param 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`. +-- @param filenames Optional string filename or table of filenames to open. If `nil`, the user +-- is prompted with a fileselect dialog. +-- @param 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 _G.events -- @name open_file function io.open_file(filenames, encodings) @@ -88,8 +86,7 @@ function io.open_file(filenames, encodings) if not assert_type(filenames, 'string/table/nil', 1) then filenames = ui.dialogs.fileselect{ title = _L['Open File'], select_multiple = true, - with_directory = (buffer.filename or ''):match('^.+[/\\]') or - lfs.currentdir(), + with_directory = (buffer.filename or ''):match('^.+[/\\]') or lfs.currentdir(), width = CURSES and ui.size[1] - 2 or nil } if not filenames then return end @@ -99,7 +96,10 @@ function io.open_file(filenames, encodings) for i = 1, #filenames do local filename = lfs.abspath((filenames[i]:gsub('^file://', ''))) for _, buf in ipairs(_BUFFERS) do - if filename == buf.filename then view:goto_buffer(buf) goto continue end + if filename == buf.filename then + view:goto_buffer(buf) + goto continue + end end local text = '' @@ -189,7 +189,10 @@ end -- LuaDoc is in core/.buffer.luadoc. local function save(buffer) if not buffer then buffer = _G.buffer end - if not buffer.filename then buffer:save_as() return end + if not buffer.filename then + buffer:save_as() + return + end events.emit(events.FILE_BEFORE_SAVE, buffer.filename) local text = buffer:get_text() if buffer.encoding then text = text:iconv(buffer.encoding, 'UTF-8') end @@ -221,9 +224,7 @@ end -- @see buffer.save -- @name save_all_files function io.save_all_files() - for _, buffer in ipairs(_BUFFERS) do - if buffer.filename and buffer.modify then buffer:save() end - end + for _, buffer in ipairs(_BUFFERS) do if buffer.filename and buffer.modify then buffer:save() end end end -- LuaDoc is in core/.buffer.luadoc. @@ -233,9 +234,8 @@ local function close(buffer, force) local filename = buffer.filename or buffer._type or _L['Untitled'] if buffer.filename then filename = filename:iconv('UTF-8', _CHARSET) end local button = ui.dialogs.msgbox{ - title = _L['Close without saving?'], - text = _L['There are unsaved changes in'], informative_text = filename, - icon = 'gtk-dialog-question', button1 = _L['Cancel'], + title = _L['Close without saving?'], text = _L['There are unsaved changes in'], + informative_text = filename, icon = 'gtk-dialog-question', button1 = _L['Cancel'], button2 = _L['Close without saving'], width = CURSES and #filename > 40 and ui.size[1] - 2 or nil } @@ -245,8 +245,8 @@ local function close(buffer, force) return true end --- Detects if the current file has been externally modified and, if so, emits a --- `FILE_CHANGED` event. +-- Detects if the current file has been externally modified and, if so, emits a `FILE_CHANGED` +-- event. local function update_modified_file() if not buffer.filename then return end local mod_time = lfs.attributes(buffer.filename, 'modification') @@ -261,8 +261,8 @@ events.connect(events.FOCUS, update_modified_file) events.connect(events.RESUME, update_modified_file) --- --- 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 `true` if user did not cancel; `nil` otherwise. -- @see buffer.close @@ -281,19 +281,16 @@ events.connect(events.BUFFER_NEW, function() buffer.save, buffer.save_as, buffer.close = save, save_as, close end) -- Export for later storage into the first buffer, which does not exist yet. --- Cannot rely on `events.BUFFER_NEW` because init scripts (e.g. menus and key --- bindings) can access buffer functions before the first `events.BUFFER_NEW` is --- emitted. +-- Cannot rely on `events.BUFFER_NEW` because init scripts (e.g. menus and key bindings) can +-- access buffer functions before the first `events.BUFFER_NEW` is emitted. io._reload, io._save, io._save_as, io._close = reload, save, save_as, close --- Prompts the user to reload the current file if it has been externally --- modified. +-- Prompts the user to reload the current file if it has been externally modified. events.connect(events.FILE_CHANGED, function(filename) local button = ui.dialogs.msgbox{ title = _L['Reload?'], text = _L['Reload modified file?'], - informative_text = string.format( - '"%s"\n%s', filename:iconv('UTF-8', _CHARSET), - _L['has been modified. Reload it?']), + informative_text = string.format('"%s"\n%s', filename:iconv('UTF-8', _CHARSET), + _L['has been modified. Reload it?']), -- LuaFormatter icon = 'gtk-dialog-question', button1 = _L['Yes'], button2 = _L['No'], width = CURSES and #filename > 40 and ui.size[1] - 2 or nil } @@ -332,23 +329,19 @@ end local vcs = {'.bzr', '.git', '.hg', '.svn', '_FOSSIL_'} --- --- 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. --- @param 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. --- @param submodule Optional flag that indicates whether or not to return the --- root of the current submodule (if applicable). The default value is --- `false`. +-- Returns the root directory of the project that contains filesystem path *path*. +-- In order to be recognized, projects must be under version control. Recognized VCSes are +-- Bazaar, Fossil, Git, Mercurial, and SVN. +-- @param 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. +-- @param submodule Optional flag that indicates whether or not to return the root of the +-- current submodule (if applicable). The default value is `false`. -- @return string root or nil -- @name get_project_root function io.get_project_root(path, submodule) if type(path) == 'boolean' then path, submodule = nil, path end - if not assert_type(path, 'string/nil', 1) then - path = buffer.filename or lfs.currentdir() - end + if not assert_type(path, 'string/nil', 1) then path = buffer.filename or lfs.currentdir() end local dir = path:match('^(.+)[/\\]?') while dir do for i = 1, #vcs do @@ -368,38 +361,34 @@ end io.quick_open_filters = {} --- --- 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()`. --- @param paths Optional string directory path or table of directory paths to --- search. The default value is the current project's root directory, if --- available. --- @param 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`. --- @param 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 --- @usage io.quick_open(io.get_current_project(), '.lua') -- list all Lua files --- in the current project --- @usage io.quick_open(io.get_current_project(), '!/build') -- list all files --- in the current project except those in the build directory +-- `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()`. +-- @param paths Optional string directory path or table of directory paths to search. The +-- default value is the current project's root directory, if available. +-- @param 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`. +-- @param 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 +-- @usage io.quick_open(io.get_current_project(), '.lua') -- list all Lua files in the current +-- project +-- @usage io.quick_open(io.get_current_project(), '!/build') -- list all files in the current +-- project except those in the build directory -- @see io.quick_open_filters -- @see lfs.default_filter -- @see quick_open_max @@ -423,24 +412,20 @@ function io.quick_open(paths, filter, opts) end if #utf8_list >= io.quick_open_max then ui.dialogs.msgbox{ - title = _L['File Limit Exceeded'], - text = string.format( - '%d %s %d', io.quick_open_max, + title = _L['File Limit Exceeded'], text = string.format('%d %s %d', io.quick_open_max, _L['files or more were found. Showing the first'], io.quick_open_max), icon = 'gtk-dialog-info' } end local options = { - title = _L['Open File'], columns = _L['Filename'], items = utf8_list, - button1 = _L['OK'], button2 = _L['Cancel'], select_multiple = true, - string_output = true, width = CURSES and ui.size[1] - 2 or nil + title = _L['Open File'], columns = _L['Filename'], items = utf8_list, button1 = _L['OK'], + button2 = _L['Cancel'], select_multiple = true, string_output = true, + width = CURSES and ui.size[1] - 2 or nil } if opts then for k, v in pairs(opts) do options[k] = v end end local button, utf8_filenames = ui.dialogs.filteredlist(options) if button ~= _L['OK'] or not utf8_filenames then return end local filenames = {} - for i = 1, #utf8_filenames do - filenames[i] = utf8_filenames[i]:iconv(_CHARSET, 'UTF-8') - end + for i = 1, #utf8_filenames do filenames[i] = utf8_filenames[i]:iconv(_CHARSET, 'UTF-8') end io.open_file(filenames) end diff --git a/core/iface.lua b/core/iface.lua index 67f60b63..ad779241 100644 --- a/core/iface.lua +++ b/core/iface.lua @@ -5,8 +5,7 @@ local M = {} --[[ This comment is for LuaDoc. --- -- 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. module('_SCINTILLA')]] --- @@ -17,8 +16,8 @@ module('_SCINTILLA')]] M.constants = {ACCESSIBILITY_DISABLED=0,ACCESSIBILITY_ENABLED=1,ALPHA_NOALPHA=256,ALPHA_OPAQUE=255,ALPHA_TRANSPARENT=0,ANNOTATION_BOXED=2,ANNOTATION_HIDDEN=0,ANNOTATION_INDENTED=3,ANNOTATION_STANDARD=1,AUTOMATICFOLD_CHANGE=0x0004,AUTOMATICFOLD_CLICK=0x0002,AUTOMATICFOLD_SHOW=0x0001,CARETSTICKY_OFF=0,CARETSTICKY_ON=1,CARETSTICKY_WHITESPACE=2,CARETSTYLE_BLOCK=2,CARETSTYLE_BLOCK_AFTER=0x100,CARETSTYLE_INS_MASK=0xF,CARETSTYLE_INVISIBLE=0,CARETSTYLE_LINE=1,CARETSTYLE_OVERSTRIKE_BAR=0,CARETSTYLE_OVERSTRIKE_BLOCK=0x10,CARET_EVEN=0x08,CARET_JUMPS=0x10,CARET_SLOP=0x01,CARET_STRICT=0x04,CASEINSENSITIVEBEHAVIOR_IGNORECASE=1,CASEINSENSITIVEBEHAVIOR_RESPECTCASE=0,CASE_CAMEL=3,CASE_LOWER=2,CASE_MIXED=0,CASE_UPPER=1,CHARACTERSOURCE_DIRECT_INPUT=0,CHARACTERSOURCE_IME_RESULT=2,CHARACTERSOURCE_TENTATIVE_INPUT=1,CP_UTF8=65001,CURSORARROW=2,CURSORNORMAL=-1,CURSORREVERSEARROW=7,CURSORWAIT=4,EDGE_BACKGROUND=2,EDGE_LINE=1,EDGE_MULTILINE=3,EDGE_NONE=0,EOLANNOTATION_BOXED=2,EOLANNOTATION_HIDDEN=0,EOLANNOTATION_STANDARD=1,EOL_CR=1,EOL_CRLF=0,EOL_LF=2,FIND_CXX11REGEX=0x00800000,FIND_MATCHCASE=0x4,FIND_NONE=0x0,FIND_REGEXP=10485760,FIND_WHOLEWORD=0x2,FIND_WORDSTART=0x00100000,FOLDACTION_CONTRACT=0,FOLDACTION_EXPAND=1,FOLDACTION_TOGGLE=2,FOLDDISPLAYTEXT_BOXED=2,FOLDDISPLAYTEXT_HIDDEN=0,FOLDDISPLAYTEXT_STANDARD=1,FOLDFLAG_LEVELNUMBERS=0x0040,FOLDFLAG_LINEAFTER_CONTRACTED=0x0010,FOLDFLAG_LINEAFTER_EXPANDED=0x0008,FOLDFLAG_LINEBEFORE_CONTRACTED=0x0004,FOLDFLAG_LINEBEFORE_EXPANDED=0x0002,FOLDFLAG_LINESTATE=0x0080,FOLDLEVELBASE=0x400,FOLDLEVELHEADERFLAG=0x2000,FOLDLEVELNUMBERMASK=0x0FFF,FOLDLEVELWHITEFLAG=0x1000,IDLESTYLING_AFTERVISIBLE=2,IDLESTYLING_ALL=3,IDLESTYLING_NONE=0,IDLESTYLING_TOVISIBLE=1,IME_INLINE=1,IME_WINDOWED=0,INDICATOR_CONTAINER=9,INDICATOR_IME=33,INDICATOR_IME_MAX=36,INDICATOR_MAX=36,INDIC_BOX=6,INDIC_COMPOSITIONTHICK=14,INDIC_COMPOSITIONTHIN=15,INDIC_CONTAINER=8,INDIC_DASH=9,INDIC_DIAGONAL=3,INDIC_DOTBOX=12,INDIC_DOTS=10,INDIC_FULLBOX=16,INDIC_GRADIENT=20,INDIC_GRADIENTCENTER=21,INDIC_HIDDEN=5,INDIC_IME=32,INDIC_IME_MAX=35,INDIC_MAX=35,INDIC_PLAIN=0,INDIC_POINT=18,INDIC_POINTCHARACTER=19,INDIC_ROUNDBOX=7,INDIC_SQUIGGLE=1,INDIC_SQUIGGLELOW=11,INDIC_SQUIGGLEPIXMAP=13,INDIC_STRAIGHTBOX=8,INDIC_STRIKE=4,INDIC_TEXTFORE=17,INDIC_TT=2,IV_LOOKBOTH=3,IV_LOOKFORWARD=2,IV_NONE=0,IV_REAL=1,LASTSTEPINUNDOREDO=0x100,MARGINOPTION_NONE=0,MARGINOPTION_SUBLINESELECT=1,MARGIN_BACK=2,MARGIN_COLOR=6,MARGIN_FORE=3,MARGIN_NUMBER=1,MARGIN_RTEXT=5,MARGIN_SYMBOL=0,MARGIN_TEXT=4,MARKER_MAX=32,MARKNUM_FOLDER=31,MARKNUM_FOLDEREND=26,MARKNUM_FOLDERMIDTAIL=28,MARKNUM_FOLDEROPEN=32,MARKNUM_FOLDEROPENMID=27,MARKNUM_FOLDERSUB=30,MARKNUM_FOLDERTAIL=29,MARK_ARROW=2,MARK_ARROWDOWN=6,MARK_ARROWS=24,MARK_AVAILABLE=28,MARK_BACKGROUND=22,MARK_BOOKMARK=31,MARK_BOXMINUS=14,MARK_BOXMINUSCONNECTED=15,MARK_BOXPLUS=12,MARK_BOXPLUSCONNECTED=13,MARK_CHARACTER=10000,MARK_CIRCLE=0,MARK_CIRCLEMINUS=20,MARK_CIRCLEMINUSCONNECTED=21,MARK_CIRCLEPLUS=18,MARK_CIRCLEPLUSCONNECTED=19,MARK_DOTDOTDOT=23,MARK_EMPTY=5,MARK_FULLRECT=26,MARK_LCORNER=10,MARK_LCORNERCURVE=16,MARK_LEFTRECT=27,MARK_MINUS=7,MARK_PIXMAP=25,MARK_PLUS=8,MARK_RGBAIMAGE=30,MARK_ROUNDRECT=1,MARK_SHORTARROW=4,MARK_SMALLRECT=3,MARK_TCORNER=11,MARK_TCORNERCURVE=17,MARK_UNDERLINE=29,MARK_VERTICALBOOKMARK=32,MARK_VLINE=9,MASK_FOLDERS=0xFE000000,MAX_MARGIN=5,MODEVENTMASKALL=0x7FFFFF,MOD_ALT=4,MOD_BEFOREDELETE=0x800,MOD_BEFOREINSERT=0x400,MOD_CHANGEANNOTATION=0x20000,MOD_CHANGEEOLANNOTATION=0x400000,MOD_CHANGEFOLD=0x8,MOD_CHANGEINDICATOR=0x4000,MOD_CHANGELINESTATE=0x8000,MOD_CHANGEMARGIN=0x10000,MOD_CHANGEMARKER=0x200,MOD_CHANGESTYLE=0x4,MOD_CHANGETABSTOPS=0x200000,MOD_CONTAINER=0x40000,MOD_CTRL=2,MOD_DELETETEXT=0x2,MOD_INSERTCHECK=0x100000,MOD_INSERTTEXT=0x1,MOD_LEXERSTATE=0x80000,MOD_META=16,MOD_NONE=0x0,MOD_NORM=0,MOD_SHIFT=1,MOD_SUPER=8,MOUSE_DRAG=2,MOUSE_PRESS=1,MOUSE_RELEASE=3,MULTIAUTOC_EACH=1,MULTIAUTOC_ONCE=0,MULTILINEUNDOREDO=0x1000,MULTIPASTE_EACH=1,MULTIPASTE_ONCE=0,MULTISTEPUNDOREDO=0x80,ORDER_CUSTOM=2,ORDER_PERFORMSORT=1,ORDER_PRESORTED=0,PERFORMED_REDO=0x40,PERFORMED_UNDO=0x20,PERFORMED_USER=0x10,SEL_LINES=2,SEL_RECTANGLE=1,SEL_STREAM=0,SEL_THIN=3,STARTACTION=0x2000,STYLE_BRACEBAD=36,STYLE_BRACELIGHT=35,STYLE_CALLTIP=39,STYLE_CONTROLCHAR=37,STYLE_DEFAULT=33,STYLE_FOLDDISPLAYTEXT=40,STYLE_INDENTGUIDE=38,STYLE_LASTPREDEFINED=40,STYLE_LINENUMBER=34,STYLE_MAX=256,TD_LONGARROW=0,TD_STRIKEOUT=1,TIME_FOREVER=10000000,UNDO_NONE=0,UPDATE_CONTENT=0x1,UPDATE_H_SCROLL=0x8,UPDATE_SELECTION=0x2,UPDATE_V_SCROLL=0x4,VISIBLE_SLOP=0x01,VISIBLE_STRICT=0x04,VS_NONE=0,VS_NOWRAPLINESTART=4,VS_RECTANGULARSELECTION=1,VS_USERACCESSIBLE=2,WRAPINDENT_DEEPINDENT=3,WRAPINDENT_FIXED=0,WRAPINDENT_INDENT=2,WRAPINDENT_SAME=1,WRAPVISUALFLAGLOC_DEFAULT=0x0000,WRAPVISUALFLAGLOC_END_BY_TEXT=0x0001,WRAPVISUALFLAGLOC_START_BY_TEXT=0x0002,WRAPVISUALFLAG_END=0x0001,WRAPVISUALFLAG_MARGIN=0x0004,WRAPVISUALFLAG_NONE=0x0000,WRAPVISUALFLAG_START=0x0002,WRAP_CHAR=2,WRAP_NONE=0,WRAP_WHITESPACE=3,WRAP_WORD=1,WS_INVISIBLE=0,WS_VISIBLEAFTERINDENT=2,WS_VISIBLEALWAYS=1,WS_VISIBLEONLYININDENT=3} --- --- 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. @@ -34,8 +33,8 @@ M.constants = {ACCESSIBILITY_DISABLED=0,ACCESSIBILITY_ENABLED=1,ALPHA_NOALPHA=25 M.functions = {add_ref_document={2376,0,0,1},add_selection={2573,0,3,3},add_styled_text={2002,0,2,9},add_tab_stop={2676,0,3,1},add_text={2001,0,2,7},add_undo_action={2560,0,1,1},allocate={2446,0,3,0},allocate_extended_styles={2553,1,1,0},allocate_sub_styles={4020,1,1,1},annotation_clear_all={2547,0,0,0},append_text={2282,0,2,7},assign_cmd_key={2070,0,6,1},auto_c_active={2102,5,0,0},auto_c_cancel={2101,0,0,0},auto_c_complete={2104,0,0,0},auto_c_pos_start={2103,3,0,0},auto_c_select={2108,0,0,7},auto_c_show={2100,0,1,7},auto_c_stops={2105,0,0,7},back_tab={2328,0,0,0},begin_undo_action={2078,0,0,0},brace_bad_light={2352,0,3,0},brace_bad_light_indicator={2499,0,5,3},brace_highlight={2351,0,3,3},brace_highlight_indicator={2498,0,5,3},brace_match={2353,3,3,1},brace_match_next={2369,3,3,3},call_tip_active={2202,5,0,0},call_tip_cancel={2201,0,0,0},call_tip_pos_start={2203,3,0,0},call_tip_set_hlt={2204,0,3,3},call_tip_show={2200,0,3,7},can_paste={2173,5,0,0},can_redo={2016,5,0,0},can_undo={2174,5,0,0},cancel={2325,0,0,0},change_insertion={2672,0,2,7},change_lexer_state={2617,1,3,3},char_left={2304,0,0,0},char_left_extend={2305,0,0,0},char_left_rect_extend={2428,0,0,0},char_position_from_point={2561,3,1,1},char_position_from_point_close={2562,3,1,1},char_right={2306,0,0,0},char_right_extend={2307,0,0,0},char_right_rect_extend={2429,0,0,0},choose_caret_x={2399,0,0,0},clear={2180,0,0,0},clear_all={2004,0,0,0},clear_all_cmd_keys={2072,0,0,0},clear_cmd_key={2071,0,6,0},clear_document_style={2005,0,0,0},clear_registered_images={2408,0,0,0},clear_representation={2667,0,7,0},clear_selections={2571,0,0,0},clear_tab_stops={2675,0,3,0},colorize={4003,0,3,3},contracted_fold_next={2618,3,3,0},convert_eols={2029,0,1,0},copy={2178,0,0,0},copy_allow_line={2519,0,0,0},copy_range={2419,0,3,3},copy_text={2420,0,2,7},count_characters={2633,1,3,3},count_code_units={2715,1,3,3},create_document={2375,1,3,1},create_loader={2632,1,3,1},cut={2177,0,0,0},del_line_left={2395,0,0,0},del_line_right={2396,0,0,0},del_word_left={2335,0,0,0},del_word_right={2336,0,0,0},del_word_right_end={2518,0,0,0},delete_back={2326,0,0,0},delete_back_not_line={2344,0,0,0},delete_range={2645,0,3,2},describe_key_word_sets={4017,0,0,8},describe_property={4016,0,7,8},description_of_style={4032,0,3,8},doc_line_from_visible={2221,3,3,0},document_end={2318,0,0,0},document_end_extend={2319,0,0,0},document_start={2316,0,0,0},document_start_extend={2317,0,0,0},drop_selection_n={2671,0,3,0},edit_toggle_overtype={2324,0,0,0},empty_undo_buffer={2175,0,0,0},encoded_from_utf8={2449,0,7,8},end_undo_action={2079,0,0,0},ensure_visible={2232,0,3,0},ensure_visible_enforce_policy={2234,0,3,0},eol_annotation_clear_all={2744,0,0,0},expand_children={2239,0,3,1},find_column={2456,3,3,3},find_indicator_flash={2641,0,3,3},find_indicator_hide={2642,0,0,0},find_indicator_show={2640,0,3,3},find_text={2150,3,1,11},fold_all={2662,0,1,0},fold_children={2238,0,3,1},fold_line={2237,0,3,1},form_feed={2330,0,0,0},format_range={2151,3,5,12},free_sub_styles={4023,0,0,0},get_cur_line={2027,3,2,8},get_default_fold_display_text={2723,0,0,8},get_hotspot_active_back={2495,4,0,0},get_hotspot_active_fore={2494,4,0,0},get_line={2153,0,3,8},get_line_sel_end_position={2425,3,3,0},get_line_sel_start_position={2424,3,3,0},get_next_tab_stop={2677,1,3,1},get_sel_text={2161,0,0,8},get_styled_text={2015,3,0,10},get_text={2182,0,2,8},get_text_range={2162,3,0,10},goto_line={2024,0,3,0},goto_pos={2025,0,3,0},grab_focus={2400,0,0,0},hide_lines={2227,0,3,3},hide_selection={2163,0,5,0},home={2312,0,0,0},home_display={2345,0,0,0},home_display_extend={2346,0,0,0},home_extend={2313,0,0,0},home_rect_extend={2430,0,0,0},home_wrap={2349,0,0,0},home_wrap_extend={2450,0,0,0},indicator_all_on_for={2506,1,3,0},indicator_clear_range={2505,0,3,2},indicator_end={2509,3,3,3},indicator_fill_range={2504,0,3,2},indicator_start={2508,3,3,3},indicator_value_at={2507,1,3,3},insert_text={2003,0,3,7},is_range_word={2691,5,3,3},line_copy={2455,0,0,0},line_cut={2337,0,0,0},line_delete={2338,0,0,0},line_down={2300,0,0,0},line_down_extend={2301,0,0,0},line_down_rect_extend={2426,0,0,0},line_duplicate={2404,0,0,0},line_end={2314,0,0,0},line_end_display={2347,0,0,0},line_end_display_extend={2348,0,0,0},line_end_extend={2315,0,0,0},line_end_rect_extend={2432,0,0,0},line_end_wrap={2451,0,0,0},line_end_wrap_extend={2452,0,0,0},line_from_position={2166,3,3,0},line_length={2350,1,3,0},line_reverse={2354,0,0,0},line_scroll={2168,0,1,1},line_scroll_down={2342,0,0,0},line_scroll_up={2343,0,0,0},line_transpose={2339,0,0,0},line_up={2302,0,0,0},line_up_extend={2303,0,0,0},line_up_rect_extend={2427,0,0,0},lines_join={2288,0,0,0},lines_split={2289,0,1,0},load_lexer_library={4007,0,0,7},lower_case={2340,0,0,0},margin_text_clear_all={2536,0,0,0},marker_add={2043,1,3,3},marker_add_set={2466,0,3,1},marker_define={2040,0,3,1},marker_define_pixmap={2049,0,3,7},marker_define_rgba_image={2626,0,3,7},marker_delete={2044,0,3,3},marker_delete_all={2045,0,3,0},marker_delete_handle={2018,0,1,0},marker_enable_highlight={2293,0,5,0},marker_get={2046,1,3,0},marker_handle_from_line={2732,1,3,3},marker_line_from_handle={2017,3,1,0},marker_next={2047,3,3,1},marker_number_from_line={2733,3,3,3},marker_previous={2048,3,3,1},marker_symbol_defined={2529,1,3,0},move_caret_inside_view={2401,0,0,0},move_selected_lines_down={2621,0,0,0},move_selected_lines_up={2620,0,0,0},multi_edge_add_line={2694,0,1,4},multi_edge_clear_all={2695,0,0,0},multiple_select_add_each={2689,0,0,0},multiple_select_add_next={2688,0,0,0},name_of_style={4030,0,3,8},new_line={2329,0,0,0},null={2172,0,0,0},page_down={2322,0,0,0},page_down_extend={2323,0,0,0},page_down_rect_extend={2434,0,0,0},page_up={2320,0,0,0},page_up_extend={2321,0,0,0},page_up_rect_extend={2433,0,0,0},para_down={2413,0,0,0},para_down_extend={2414,0,0,0},para_up={2415,0,0,0},para_up_extend={2416,0,0,0},paste={2179,0,0,0},point_x_from_position={2164,1,0,3},point_y_from_position={2165,1,0,3},position_after={2418,3,3,0},position_before={2417,3,3,0},position_from_line={2167,3,3,0},position_from_point={2022,3,1,1},position_from_point_close={2023,3,1,1},position_relative={2670,3,3,1},position_relative_code_units={2716,3,3,3},private_lexer_call={4013,1,1,1},property_names={4014,0,0,8},property_type={4015,1,7,0},redo={2011,0,0,0},register_image={2405,0,1,7},register_rgba_image={2627,0,1,7},release_all_extended_styles={2552,0,0,0},release_document={2377,0,0,1},replace_sel={2170,0,0,7},replace_target={2194,1,2,7},replace_target_re={2195,1,2,7},rotate_selection={2606,0,0,0},scroll_caret={2169,0,0,0},scroll_range={2569,0,3,3},scroll_to_end={2629,0,0,0},scroll_to_start={2628,0,0,0},search_anchor={2366,0,0,0},search_in_target={2197,3,2,7},search_next={2367,3,1,7},search_prev={2368,3,1,7},select_all={2013,0,0,0},selection_duplicate={2469,0,0,0},set_chars_default={2444,0,0,0},set_default_fold_display_text={2722,0,0,7},set_empty_selection={2556,0,3,0},set_fold_margin_color={2290,0,5,4},set_fold_margin_hi_color={2291,0,5,4},set_hotspot_active_back={2411,0,5,4},set_hotspot_active_fore={2410,0,5,4},set_length_for_encode={2448,0,3,0},set_save_point={2014,0,0,0},set_sel={2160,0,3,3},set_sel_back={2068,0,5,4},set_sel_fore={2067,0,5,4},set_selection={2572,0,3,3},set_styling={2033,0,2,3},set_styling_ex={2073,0,2,7},set_target_range={2686,0,3,3},set_text={2181,0,0,7},set_visible_policy={2394,0,1,1},set_whitespace_back={2085,0,5,4},set_whitespace_fore={2084,0,5,4},set_x_caret_policy={2402,0,1,1},set_y_caret_policy={2403,0,1,1},show_lines={2226,0,3,3},start_record={3001,0,0,0},start_styling={2032,0,3,1},stop_record={3002,0,0,0},stuttered_page_down={2437,0,0,0},stuttered_page_down_extend={2438,0,0,0},stuttered_page_up={2435,0,0,0},stuttered_page_up_extend={2436,0,0,0},style_clear_all={2050,0,0,0},style_reset_default={2058,0,0,0},swap_main_anchor_caret={2607,0,0,0},tab={2327,0,0,0},tags_of_style={4031,0,3,8},target_as_utf8={2447,0,0,8},target_from_selection={2287,0,0,0},target_whole_document={2690,0,0,0},text_height={2279,1,3,0},text_width={2276,1,3,7},toggle_caret_sticky={2459,0,0,0},toggle_fold={2231,0,3,0},toggle_fold_show_text={2700,0,3,7},undo={2176,0,0,0},upper_case={2341,0,0,0},use_pop_up={2371,0,1,0},user_list_show={2117,0,1,7},vc_home={2331,0,0,0},vc_home_display={2652,0,0,0},vc_home_display_extend={2653,0,0,0},vc_home_extend={2332,0,0,0},vc_home_rect_extend={2431,0,0,0},vc_home_wrap={2453,0,0,0},vc_home_wrap_extend={2454,0,0,0},vertical_center_caret={2619,0,0,0},visible_from_doc_line={2220,3,3,0},word_end_position={2267,3,3,5},word_left={2308,0,0,0},word_left_end={2439,0,0,0},word_left_end_extend={2440,0,0,0},word_left_extend={2309,0,0,0},word_part_left={2390,0,0,0},word_part_left_extend={2391,0,0,0},word_part_right={2392,0,0,0},word_part_right_extend={2393,0,0,0},word_right={2310,0,0,0},word_right_end={2441,0,0,0},word_right_end_extend={2442,0,0,0},word_right_extend={2311,0,0,0},word_start_position={2266,3,3,5},wrap_count={2235,1,3,0},zoom_in={2333,0,0,0},zoom_out={2334,0,0,0},} --- --- 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. -- @see functions @@ -53,8 +52,8 @@ local marker_number, indic_number, list_type, image_type = 0, 0, 0, 0 --- -- 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 local marknum = _SCINTILLA.next_marker_number() -- @see view.marker_define -- @name next_marker_number @@ -66,8 +65,8 @@ end --- -- 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 local indic_num = _SCINTILLA.next_indic_number() -- @see view.indic_style -- @name next_indic_number @@ -78,10 +77,9 @@ function M.next_indic_number() end --- --- 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 local list_type = _SCINTILLA.next_user_list_type() -- @see buffer.user_list_show -- @name next_user_list_type @@ -91,10 +89,10 @@ function M.next_user_list_type() end --- --- 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 local image_type = _SCINTILLA.next_image_type() -- @see view.register_image -- @see view.register_rgba_image diff --git a/core/init.lua b/core/init.lua index 712d07a7..361edf3e 100644 --- a/core/init.lua +++ b/core/init.lua @@ -6,9 +6,7 @@ _COPYRIGHT = 'Copyright © 2007-2021 Mitchell. See LICENSE.\n' .. package.path = string.format('%s/core/?.lua;%s', _HOME, package.path) ---for _, arg in ipairs(arg) do --- if arg == '-t' or arg == '--test' then pcall(require, 'luacov') end ---end +-- for _, arg in ipairs(arg) do if arg == '-t' or arg == '--test' then pcall(require, 'luacov') end end require('assert') _SCINTILLA = require('iface') @@ -40,13 +38,11 @@ if CURSES and WIN32 then end end --- Replacement for original `buffer:text_range()`, which has a C struct for an --- argument. +-- Replacement for original `buffer:text_range()`, which has a C struct for an argument. -- Documentation is in core/.buffer.luadoc. local function text_range(buffer, start_pos, end_pos) local target_start, target_end = buffer.target_start, buffer.target_end - buffer:set_target_range( - math.max(1, assert_type(start_pos, 'number', 2)), + buffer:set_target_range(math.max(1, assert_type(start_pos, 'number', 2)), math.min(assert_type(end_pos, 'number', 3), buffer.length + 1)) local text = buffer.target_text buffer:set_target_range(target_start, target_end) -- restore @@ -56,13 +52,11 @@ end local GETNAMEDSTYLE = _SCINTILLA.properties.named_styles[1] -- Documentation is in core/.buffer.luadoc. local function style_of_name(buffer, style_name) - return buffer:private_lexer_call( - GETNAMEDSTYLE, assert_type(style_name, 'string', 2)) + return buffer:private_lexer_call(GETNAMEDSTYLE, assert_type(style_name, 'string', 2)) end -events.connect(events.BUFFER_NEW, function() - buffer.text_range, buffer.style_of_name = text_range, style_of_name -end) +events.connect(events.BUFFER_NEW, + function() buffer.text_range, buffer.style_of_name = text_range, style_of_name end) --[[ This comment is for LuaDoc. --- @@ -72,13 +66,12 @@ end) -- @field _RELEASE (string) -- The Textadept release version string. -- @field _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). -- @field _CHARSET (string) -- The filesystem's character encoding. -- This is used when [working with files](#io). @@ -108,8 +101,7 @@ local arg --- -- 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. -- @class table -- @usage _BUFFERS[n] --> buffer at index n -- @usage _BUFFERS[buffer] --> index of buffer in _BUFFERS @@ -119,8 +111,7 @@ local _BUFFERS --- -- 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. -- @class table -- @usage _VIEWS[n] --> view at index n -- @usage _VIEWS[view] --> index of view in _VIEWS @@ -143,8 +134,7 @@ local view -- The functions below are Lua C functions. --- --- 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 events.QUIT -- @class function -- @name quit @@ -152,21 +142,20 @@ local quit --- -- 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`. -- @class function -- @name reset local reset --- -- 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. -- @param interval The interval in seconds to call *f* after. -- @param f The function to call. -- @param ... Additional arguments to pass to *f*. diff --git a/core/keys.lua b/core/keys.lua index 72cb1161..f952f106 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -8,50 +8,43 @@ local M = {} -- -- ### 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`]() 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`]() 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 -- @@ -65,9 +58,9 @@ local M = {} -- -- ### 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, @@ -86,15 +79,14 @@ local M = {} -- 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`](). 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`](). An example key chain looks like: -- -- keys['alt+a'] = { -- a = function1, @@ -107,8 +99,7 @@ local M = {} -- The default value is `'esc'` for the `Esc` key. -- @field 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`. module('keys')]] @@ -116,18 +107,19 @@ local CTRL, ALT, CMD, SHIFT = 'ctrl+', 'alt+', 'cmd+', 'shift+' if CURSES then ALT = 'meta+' end M.CLEAR = 'esc' +-- LuaFormatter off --- -- 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. -- @class table -- @name KEYSYMS M.KEYSYMS = {--[[From Scintilla.h for CURSES]][7]='esc',[8]='\b',[9]='\t',[13]='\n',--[[From curses.h]][263]='\b',[343]='\n',--[[From Scintilla.h for CURSES]][300]='down',[301]='up',[302]='left',[303]='right',[304]='home',[305]='end',[306]='pgup',[307]='pgdn',[308]='del',[309]='ins',--[[From <gdk/gdkkeysyms.h>]][0xFE20]='\t'--[[backtab; will be 'shift'ed]],[0xFF08]='\b',[0xFF09]='\t',[0xFF0D]='\n',[0xFF1B]='esc',[0xFFFF]='del',[0xFF50]='home',[0xFF51]='left',[0xFF52]='up',[0xFF53]='right',[0xFF54]='down',[0xFF55]='pgup',[0xFF56]='pgdn',[0xFF57]='end',[0xFF63]='ins',[0xFF8D]='kpenter',[0xFF95]='kphome',[0xFF9C]='kpend',[0xFF96]='kpleft',[0xFF97]='kpup',[0xFF98]='kpright',[0xFF99]='kpdown',[0xFF9A]='kppgup',[0xFF9B]='kppgdn',[0xFFAA]='kpmul',[0xFFAB]='kpadd',[0xFFAD]='kpsub',[0xFFAF]='kpdiv',[0xFFAE]='kpdec',[0xFFB0]='kp0',[0xFFB1]='kp1',[0xFFB2]='kp2',[0xFFB3]='kp3',[0xFFB4]='kp4',[0xFFB5]='kp5',[0xFFB6]='kp6',[0xFFB7]='kp7',[0xFFB8]='kp8',[0xFFB9]='kp9',[0xFFBE]='f1',[0xFFBF]='f2',[0xFFC0]='f3',[0xFFC1]='f4',[0xFFC2]='f5',[0xFFC3]='f6',[0xFFC4]='f7',[0xFFC5]='f8',[0xFFC6]='f9',[0xFFC7]='f10',[0xFFC8]='f11',[0xFFC9]='f12'} +-- LuaFormatter on -- The current key sequence. local keychain = {} @@ -137,8 +129,7 @@ local keychain = {} -- @class table -- @name keychain M.keychain = setmetatable({}, { - __index = keychain, - __newindex = function() error('read-only table') end, + __index = keychain, __newindex = function() error('read-only table') end, __len = function() return #keychain end }) @@ -148,9 +139,8 @@ local function clear_key_seq() for i = 1, #keychain do keychain[i] = nil end end -- Return codes for `key_command()`. local INVALID, PROPAGATE, CHAIN, HALT = -1, 0, 1, 2 --- Error handler for key commands that simply emits the error. This is needed --- so `key_command()` can return `HALT` instead of never returning due to the --- error. +-- Error handler for key commands that simply emits the error. +-- This is needed so `key_command()` can return `HALT` instead of never returning due to the error. local function key_error(errmsg) events.emit(events.ERROR, errmsg) end -- Runs a key command associated with the current keychain. @@ -164,17 +154,15 @@ local function key_command(prefix) end if type(key) ~= 'function' and type(key) ~= 'table' then return INVALID end if type(key) == 'table' then - ui.statusbar_text = string.format( - '%s %s', _L['Keychain:'], table.concat(keychain, ' ')) + ui.statusbar_text = string.format('%s %s', _L['Keychain:'], table.concat(keychain, ' ')) return CHAIN end return select(2, xpcall(key, key_error)) == false and PROPAGATE or HALT end --- Handles Textadept keypresses, executing commands based on a mode or lexer as --- necessary. +-- Handles Textadept keypresses, executing commands based on a mode or lexer as necessary. events.connect(events.KEYPRESS, function(code, shift, control, alt, cmd, caps) - --print(code, M.KEYSYMS[code], shift, control, alt, cmd, caps) + -- print(code, M.KEYSYMS[code], shift, control, alt, cmd, caps) if caps and (shift or control or alt or cmd) and code < 256 then code = string[shift and 'upper' or 'lower'](string.char(code)):byte() end @@ -184,14 +172,17 @@ events.connect(events.KEYPRESS, function(code, shift, control, alt, cmd, caps) if shift and code >= 32 and code < 256 then shift = false end -- For composed keys on macOS, ignore alt. if OSX and alt and code < 256 then alt = false end - local key_seq = (control and CTRL or '') .. (alt and ALT or '') .. - (cmd and OSX and CMD or '') .. (shift and SHIFT or '') .. key - --print(key_seq) + local key_seq = (control and CTRL or '') .. (alt and ALT or '') .. (cmd and OSX and CMD or '') .. + (shift and SHIFT or '') .. key + -- print(key_seq) ui.statusbar_text = '' - --if CURSES then ui.statusbar_text = string.format('"%s"', key_seq) end + -- if CURSES then ui.statusbar_text = string.format('"%s"', key_seq) end local in_chain = #keychain > 0 - if in_chain and key_seq == M.CLEAR then clear_key_seq() return true end + if in_chain and key_seq == M.CLEAR then + clear_key_seq() + return true + end keychain[#keychain + 1] = key_seq local status = PROPAGATE @@ -212,12 +203,13 @@ end) --[[ This comment is for LuaDoc. --- --- 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. -- @class table -- @name _G.keys local keys]] +-- LuaFormatter off for lexer in string.gmatch('actionscript ada apdl ansi_c antlr apl applescript asp autoit awk b_lang bash batch bibtex boo chuck clojure cmake coffeescript context cpp crystal csharp css cuda desktop django dmd dockerfile dot eiffel elixir elm erlang fantom faust fennel fish forth fortran fsharp fstab gap gettext gherkin glsl gnuplot go groovy gtkrc haskell html icon idl inform ini Io java javascript jq json jsp julia latex ledger less lilypond lisp logtalk lua makefile matlab meson moonscript myrddin nemerle networkd nim nsis objective_c pascal perl php pico8 pike pkgbuild pony prolog props protobuf ps pure python rails rc reason rebol rest rexx rhtml routeros rstats ruby rust sass scala scheme smalltalk sml snobol4 spin sql systemd tcl tex text toml typescript vala vb vbscript verilog vhdl wsf xml xs xtend yaml zig', '%S+') do M[lexer] = {} end +-- LuaFormatter on return M diff --git a/core/lfs_ext.lua b/core/lfs_ext.lua index 090de173..3f34803f 100644 --- a/core/lfs_ext.lua +++ b/core/lfs_ext.lua @@ -2,27 +2,26 @@ --[[ This comment is for LuaDoc. --- --- 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. module('lfs')]] +-- LuaFormatter off --- --- 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 walk -- @class table -- @name default_filter lfs.default_filter = {--[[Extensions]]'!.a','!.bmp','!.bz2','!.class','!.dll','!.exe','!.gif','!.gz','!.jar','!.jpeg','!.jpg','!.o','!.pdf','!.png','!.so','!.tar','!.tgz','!.tif','!.tiff','!.xz','!.zip',--[[Directories]]'!/%.bzr$','!/%.git$','!/%.hg$','!/%.svn$','!/_FOSSIL_$','!/node_modules$'} +-- LuaFormatter on -- Documentation is in `lfs.walk()`. --- @param seen Utility table that holds directories seen. If there is a --- duplicate, stop walking down that path (it's probably a recursive symlink). --- @param level Utility value indicating the directory level this function is --- at. +-- @param seen Utility table that holds directories seen. If there is a duplicate, stop walking +-- down that path (it's probably a recursive symlink). +-- @param level Utility value indicating the directory level this function is at. local function walk(dir, filter, n, include_dirs, seen, level) if not seen then seen = {} end local sep = not WIN32 and '/' or '\\' @@ -52,9 +51,7 @@ local function walk(dir, filter, n, include_dirs, seen, level) coroutine.yield(os_filename) elseif mode == 'directory' then local link = lfs.symlinkattributes(filename, 'target') - if link and seen[lfs.abspath(link .. sep, dir):gsub('[/\\]+$', '')] then - goto continue - end + if link and seen[lfs.abspath(link .. sep, dir):gsub('[/\\]+$', '')] then goto continue end if include_dirs then coroutine.yield(os_filename .. sep) end if n and (level or 0) >= n then goto continue end walk(filename, filter, n, include_dirs, seen, (level or 0) + 1) @@ -64,39 +61,33 @@ local function walk(dir, filter, n, include_dirs, seen, level) end --- --- 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). -- @param dir The directory path to iterate over. --- @param filter Optional filter for files and directories to include and --- exclude. The default value is `lfs.default_filter`. --- @param n Optional maximum number of directory levels to descend into. --- The default value is `nil`, which indicates no limit. --- @param 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. +-- @param filter Optional filter for files and directories to include and exclude. The default +-- value is `lfs.default_filter`. +-- @param n Optional maximum number of directory levels to descend into. The default value is +-- `nil`, which indicates no limit. +-- @param 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 filter -- @name walk function lfs.walk(dir, filter, n, include_dirs) dir = assert_type(dir, 'string', 1):match('^(..-)[/\\]?$') - if not assert_type(filter, 'string/table/nil', 2) then - filter = lfs.default_filter - end + if not assert_type(filter, 'string/table/nil', 2) then filter = lfs.default_filter end assert_type(n, 'number/nil', 3) - -- Process the given filter into something that can match files more easily - -- and/or quickly. For example, convert '.ext' shorthand to '%.ext$', - -- substitute '/' with '[/\\]', and enable hash lookup for file extensions - -- to include or exclude. + -- Process the given filter into something that can match files more easily and/or quickly. For + -- example, convert '.ext' shorthand to '%.ext$', substitute '/' with '[/\\]', and enable + -- hash lookup for file extensions to include or exclude. local processed_filter = { - consider_any = true, - exts = setmetatable({}, {__index = function() return true end}) + consider_any = true, exts = setmetatable({}, {__index = function() return true end}) } for _, patt in ipairs(type(filter) == 'table' and filter or {filter}) do patt = patt:gsub('^(!?)%%?%.([^.]+)$', '%1%%.%2$') -- '.lua' to '%.lua$' @@ -111,15 +102,14 @@ function lfs.walk(dir, filter, n, include_dirs) processed_filter[#processed_filter + 1] = patt end end - local co = coroutine.create( - function() walk(dir, processed_filter, n, include_dirs) end) + local co = coroutine.create(function() walk(dir, processed_filter, n, include_dirs) end) return function() return select(2, coroutine.resume(co)) end end --- -- 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. -- @param filename The relative or absolute path to a file. -- @param prefix Optional prefix path prepended to a relative filename. -- @return string absolute path @@ -127,11 +117,8 @@ end function lfs.abspath(filename, prefix) assert_type(filename, 'string', 1) assert_type(prefix, 'string/nil', 2) - if WIN32 then - filename = filename:gsub('/', '\\'):gsub('^%l:[/\\]', string.upper) - end - if not filename:find(not WIN32 and '^/' or '^%a:[/\\]') and - not (WIN32 and filename:find('^\\\\')) then + if WIN32 then filename = filename:gsub('/', '\\'):gsub('^%l:[/\\]', string.upper) end + if not filename:find(not WIN32 and '^/' or '^%a:[/\\]') and not (WIN32 and filename:find('^\\\\')) then if not prefix then prefix = lfs.currentdir() end filename = prefix .. (not WIN32 and '/' or '\\') .. filename end diff --git a/core/locale.conf b/core/locale.conf index 5deeac29..ea283aec 100644 --- a/core/locale.conf +++ b/core/locale.conf @@ -1,27 +1,26 @@ # Copyright 2007-2020 Mitchell. See LICENSE. # American English localization file for Textadept. # -# When translating this file into your native language, all translated text must -# be encoded in UTF-8. For each "key = value" line, please replace the "value" -# part with the translation of "key". Any whitespace around '=' is ignored. +# When translating this file into your native language, all translated text must be encoded in +# UTF-8. For each "key = value" line, please replace the "value" part with the translation of +# "key". Any whitespace around '=' is ignored. # -# Note: for languages that support it, buttons and menu items may have a "_" -# before any single letter, which means that pressing the "Alt" modifier key -# along with that letter will activate (click) the button or menu item. You are -# free to use or omit these "_" mnemonics from your translations as you see fit. +# Note: for languages that support it, buttons and menu items may have a "_" before any single +# letter, which means that pressing the "Alt" modifier key along with that letter will activate +# (click) the button or menu item. You are free to use or omit these "_" mnemonics from your +# translations as you see fit. # [core/file_io.lua] # The title of dialogs prompting the user to open a file. Open File = Open File -# The error message displayed when a file's text encoding could not be detected -# and when that text cannot be converted into UTF-8 for display. +# The error message displayed when a file's text encoding could not be detected and when that +# text cannot be converted into UTF-8 for display. Encoding conversion failed. = Encoding conversion failed. # The title of dialogs prompting the user to save a file. Save File = Save File # The text displayed for untitled and unsaved buffers. Untitled = Untitled -# The text displayed in a dialog when the user attempts to close a file with -# unsaved changes. +# The text displayed in a dialog when the user attempts to close a file with unsaved changes. Close without saving? = Close without saving? There are unsaved changes in = There are unsaved changes in Cancel = _Cancel @@ -34,19 +33,17 @@ Yes = _Yes No = _No # The column label for lists of filenames in dialogs. Filename = File -# The text displayed in a dialog when more than X files were found in the quick -# open dialog. +# The text displayed in a dialog when more than X files were found in the quick open dialog. files or more were found. Showing the first = files or more were found. Showing the first File Limit Exceeded = File Limit Exceeded OK = _OK # [core/keys.lua] -# The statusbar text shown when the user has pressed a key that is part of a key -# chain (e.g. "Ctrl+Alt+V" followed by "S"). Textadept is waiting for another -# keypress. +# The statusbar text shown when the user has pressed a key that is part of a key chain +# (e.g. "Ctrl+Alt+V" followed by "S"). Textadept is waiting for another keypress. Keychain: = Keychain: -# The statusbar text shown when the user started a key chain, but the next -# keypress was unrecognized. Thus the key sequence is invalid. +# The statusbar text shown when the user started a key chain, but the next keypress was +# unrecognized. Thus the key sequence is invalid. Invalid sequence = Invalid sequence # [core/ui.lua] @@ -56,8 +53,7 @@ Invalid sequence = Invalid sequence Name = Name # The title of the dialog for switching between open buffers. Switch Buffers = Switch Buffers -# The line-ending, indentation, and positional buffer information shown in the -# statusbar. +# The line-ending, indentation, and positional buffer information shown in the statusbar. CRLF = CRLF LF = LF Tabs: = Tabs: @@ -66,8 +62,8 @@ Line: = Line: Col: = Col: # The statusbar text shown when the user resets Textadept's internal Lua state. Lua reset = Lua reset -# The text displayed in a dialog when the user attempts to quit Textadept with -# unsaved changes in open buffers. +# The text displayed in a dialog when the user attempts to quit Textadept with unsaved changes +# in open buffers. Quit without saving? = Quit without saving? The following buffers are unsaved: = The following buffers are unsaved: Quit without saving = Quit _without saving @@ -81,8 +77,8 @@ Bookmark = Bookmark # The text displayed in the dialog for jumping to a particular line. Go To = Go To Line Number: = Line Number: -# The statusbar message displayed when a shell command used to filter text -# through returns a non-zero status (indicating failure). +# The statusbar message displayed when a shell command used to filter text through returns a +# non-zero status (indicating failure). returned non-zero status = returned non-zero status # [modules/textadept/find.lua] @@ -100,8 +96,7 @@ Whole word = _Whole word Regex = Rege_x In files = _In files # The button text displayed in the terminal version's find & replace pane. -# These should be as short as possible, as most terminals are 80 characters in -# width. +# These should be as short as possible, as most terminals are 80 characters in width. [Next] = [Next] [Prev] = [Prev] [Replace] = [Replace] @@ -110,8 +105,7 @@ Case(F1) = Case(F1) Word(F2) = Word(F2) Regex(F3) = Regex(F3) Files(F4) = Files(F4) -# The statusbar text shown when a search has wrapped back to the beginning of -# the buffer. +# The statusbar text shown when a search has wrapped back to the beginning of the buffer. Search wrapped = Search wrapped # Part of the statusbar text "Match X/Y" shown during searches. Match = Match @@ -142,8 +136,8 @@ Save Macro = Save Macro Load Macro = Load Macro # [modules/textadept/menu.lua] -# Typical "File" menu items for creating new files, opening, saving, and closing -# existing files, opening and saving sessions, and quitting Textadept. +# Typical "File" menu items for creating new files, opening, saving, and closing existing files, +# opening and saving sessions, and quitting Textadept. File = _File New = _New Open = _Open @@ -174,8 +168,8 @@ Complete Word = Complete _Word Toggle Block Comment = Toggle _Block Comment Transpose Characters = T_ranspose Characters Join Lines = _Join Lines -# The menu item for filtering text through a shell command and replacing input -# text with that command's output text. +# The menu item for filtering text through a shell command and replacing input text with that +# command's output text. Filter Through = Filter Thr_ough # Menu items for selecting text and entities. Select = _Select @@ -216,8 +210,7 @@ Goto Next File Found = Goto Nex_t File Found Goto Previous File Found = Goto Previou_s File Found # Menu item for jumping to a specific line in a buffer. Jump to = _Jump to -# Menu items for various tools and utilities for editing and working with source -# code. +# Menu items for various tools and utilities for editing and working with source code. Tools = _Tools # Menu item for opening Textadept's Lua command entry. Command Entry = Command _Entry @@ -228,8 +221,8 @@ Run = _Run Compile = _Compile # Menu item for setting command line arguments for run and compile commands. Set Arguments... = Set _Arguments... -# The text displayed in the dialog for specifying command line arguments for run -# and compile commands. +# The text displayed in the dialog for specifying command line arguments for run and compile +# commands. Command line arguments = Command line arguments For Run: = For Run: For Compile: = For Compile: @@ -255,30 +248,30 @@ Start/Stop Recording = Start/Stop _Recording Play = _Play Save... = Sa_ve... Load... = _Load... -# Menu items for launching a quick open dialog in order to open files in certain -# directories. A quick open dialog lists all files in a directory and its -# subdirectories and filters the list down as the user types. +# Menu items for launching a quick open dialog in order to open files in certain directories. A +# quick open dialog lists all files in a directory and its subdirectories and filters the list +# down as the user types. Quick Open = Quick _Open Quickly Open User Home = Quickly Open _User Home Quickly Open Textadept Home = Quickly Open _Textadept Home Quickly Open Current Directory = Quickly Open _Current Directory Quickly Open Current Project = Quickly Open Current _Project -# Menu items for working with snippets, insert-able pieces of code that act like -# templates with placeholders for user input. +# Menu items for working with snippets, insert-able pieces of code that act like templates with +# placeholders for user input. Snippets = _Snippets Insert Snippet... = _Insert Snippet... Expand Snippet/Next Placeholder = _Expand Snippet/Next Placeholder Previous Snippet Placeholder = _Previous Snippet Placeholder Cancel Snippet = _Cancel Snippet Complete Trigger Word = Complete Trigger _Word -# Menu items for auto-completing programming language symbols and showing -# documentation for them (e.g. typing `textadept.editing.` followed by a -# "Complete Symbol" would show all possible completions for that symbol). +# Menu items for auto-completing programming language symbols and showing documentation for them +# (e.g. typing `textadept.editing.` followed by a "Complete Symbol" would show all possible +# completions for that symbol). Complete Symbol = Complete S_ymbol Show Documentation = S_how Documentation -# Menu item for inspecting the character under the caret. The character's byte -# information, the lexer used to syntax-highlight that character, and the -# character's lexical style (e.g. string, comment, number, etc.) are shown. +# Menu item for inspecting the character under the caret. The character's byte information, the +# lexer used to syntax-highlight that character, and the character's lexical style (e.g. string, +# comment, number, etc.) are shown. Show Style = Sho_w Style Lexer = Lexer Style = Style @@ -306,11 +299,9 @@ UTF-16 Encoding = UTF-1_6 Encoding # Menu items for changing the way the current buffer is displayed. Toggle Wrap Mode = Toggle _Wrap Mode Toggle View Whitespace = Toggle View White_space -# Menu items for changing the syntax-highlighting language for the current -# buffer. +# Menu items for changing the syntax-highlighting language for the current buffer. Select Lexer... = Select _Lexer... -# Menu items for navigating between views, splitting them, closing them, and -# resizing them. +# Menu items for navigating between views, splitting them, closing them, and resizing them. View = _View Next View = _Next View Previous View = _Previous View @@ -320,14 +311,12 @@ Unsplit View = _Unsplit View Unsplit All Views = Unsplit _All Views Grow View = _Grow View Shrink View = Shrin_k View -# Menu item for folding (showing/hiding) the block of code the starts on the -# current line. Fold-able blocks of code are typically classes, functions, and -# control structures. +# Menu item for folding (showing/hiding) the block of code the starts on the current +# line. Fold-able blocks of code are typically classes, functions, and control structures. Toggle Current Fold = Toggle Current _Fold # Menu item for showing line indentation markers. Toggle Show Indent Guides = Toggle Show In_dent Guides -# Menu item for allowing the caret to move beyond line ends and into "virtual -# space". +# Menu item for allowing the caret to move beyond line ends and into "virtual space". Toggle Virtual Space = Toggle _Virtual Space # Menu items for changing the zoom factor of displayed buffer text. Zoom In = Zoom _In @@ -338,15 +327,15 @@ Help = _Help Show Manual = Show _Manual Show LuaDoc = Show _LuaDoc About = _About -# The text displayed in the dialog for running an arbitrary menu command. Any -# key binding associated with commands are also shown. +# The text displayed in the dialog for running an arbitrary menu command. Any key binding +# associated with commands are also shown. Run Command = Run Command Command = Command Key Binding = Key Binding # [modules/textadept/file_types.lua] -# The title of the dialog for selecting a lexer for the current buffer. Lexers -# perform syntax highlighting of source code. +# The title of the dialog for selecting a lexer for the current buffer. Lexers perform syntax +# highlighting of source code. Select Lexer = Select Lexer # [modules/textadept/session.lua] @@ -359,9 +348,8 @@ The following session files were not found = The following session files were no Save Session = Save Session # [modules/textadept/snippets.lua] -# The text displayed in the dialog for selecting a snippet to insert. Snippets -# have a trigger word (pressing the "Tab" key after that word inserts the -# snippet) and snippet text. +# The text displayed in the dialog for selecting a snippet to insert. Snippets have a trigger +# word (pressing the "Tab" key after that word inserts the snippet) and snippet text. Select Snippet = Select Snippet Trigger = Trigger Snippet Text = Snippet Text diff --git a/core/locale.lua b/core/locale.lua index 7e115854..57fbff27 100644 --- a/core/locale.lua +++ b/core/locale.lua @@ -5,24 +5,20 @@ local M = {} --[[ This comment is for LuaDoc. --- -- 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. module('_L')]] local f = io.open(_USERHOME .. '/locale.conf', 'rb') if not f then local lang = (os.getenv('LANG') or ''):match('^[^_.@]+') -- TODO: LC_MESSAGES? - if lang then - f = io.open(string.format('%s/core/locales/locale.%s.conf', _HOME, lang)) - end + if lang then f = io.open(string.format('%s/core/locales/locale.%s.conf', _HOME, lang)) end end if not f then f = io.open(_HOME .. '/core/locale.conf', 'rb') end assert(f, '"core/locale.conf" not found') for line in f:lines() do - -- Any line that starts with a non-word character except '[' is considered a - -- comment. + -- Any line that starts with a non-word character except '[' is considered a comment. if not line:find('^%s*[%w_%[]') then goto continue end local id, str = line:match('^(.-)%s*=%s*(.-)\r?$') if id and str and assert(not M[id], 'duplicate locale key "%s"', id) then @@ -32,5 +28,4 @@ for line in f:lines() do end f:close() -return setmetatable( - M, {__index = function(_, k) return 'No Localization:' .. k end}) +return setmetatable(M, {__index = function(_, k) return 'No Localization:' .. k end}) diff --git a/core/ui.lua b/core/ui.lua index 19bf5881..eb366c93 100644 --- a/core/ui.lua +++ b/core/ui.lua @@ -26,15 +26,14 @@ local ui = ui -- @field tabs (bool) -- 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. -- @field silent_print (bool) -- Whether or not to print messages to buffers silently. --- This is not guaranteed to be a constant value, as Textadept may change it --- for the editor's own purposes. This flag should be used only in conjunction --- with a group of [`ui.print()`]() and [`ui._print()`]() function calls. --- The default value is `false`, and focuses buffers when messages are printed --- to them. +-- This is not guaranteed to be a constant value, as Textadept may change it for the editor's +-- own purposes. This flag should be used only in conjunction with a group of [`ui.print()`]() +-- and [`ui._print()`]() function calls. +-- The default value is `false`, and focuses buffers when messages are printed to them. -- @field SHOW_ALL_TABS (number) -- module('ui')]] @@ -43,10 +42,14 @@ ui.SHOW_ALL_TABS = 2 -- ui.tabs options must be greater than 1 ui.silent_print = false --- Helper function for jumping to another view to print to, or creating a new --- view to print to (the latter depending on settings). +-- Helper function for jumping to another view to print to, or creating a new view to print to +-- (the latter depending on settings). local function prepare_view() - if #_VIEWS > 1 then ui.goto_view(1) elseif not ui.tabs then view:split() end + if #_VIEWS > 1 then + ui.goto_view(1) + elseif not ui.tabs then + view:split() + end end -- Helper function for printing messages to buffers. @@ -54,7 +57,10 @@ end local function _print(buffer_type, ...) local buffer for _, buf in ipairs(_BUFFERS) do - if buf._type == buffer_type then buffer = buf break end + if buf._type == buffer_type then + buffer = buf + break + end end if not buffer then prepare_view() @@ -80,17 +86,14 @@ local function _print(buffer_type, ...) end --- -- 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. -- @param buffer_type String type of message buffer. -- @param ... Message strings. -- @usage ui._print(_L['[Message Buffer]'], message) -- @name _print -function ui._print(buffer_type, ...) - _print(assert_type(buffer_type, 'string', 1), ...) -end +function ui._print(buffer_type, ...) _print(assert_type(buffer_type, 'string', 1), ...) end --- -- Prints the given string messages to the message buffer. @@ -99,8 +102,7 @@ end -- @name print function ui.print(...) ui._print(_L['[Message Buffer]'], ...) end --- Returns 0xBBGGRR colors transformed into "#RRGGBB" for the colorselect --- dialog. +-- Returns 0xBBGGRR colors transformed into "#RRGGBB" for the colorselect dialog. -- @param value Number color to transform. -- @return string or nil if the transform failed local function torgb(value) @@ -110,89 +112,83 @@ local function torgb(value) end -- Documentation is in core/.ui.dialogs.luadoc. -ui.dialogs = setmetatable({}, {__index = function(_, k) - -- Wrapper for `ui.dialog(k)`, transforming the given table of arguments into - -- a set of command line arguments and transforming the resulting standard - -- output into Lua objects. - -- @param options Table of key-value command line options for gtdialog. - -- @param f Work function for progressbar dialogs. - -- @return Lua objects depending on the dialog kind - return function(options, f) - if not options.button1 then options.button1 = _L['OK'] end - if k == 'filteredlist' and not options.width then - options.width = ui.size[1] - 2 * (CURSES and 1 or 100) - end - -- Transform key-value pairs into command line arguments. - local args = {} - for option, value in pairs(options) do - if assert_type(value, 'string/number/table/boolean', option) then - args[#args + 1] = '--' .. option:gsub('_', '-') - if type(value) == 'table' then - for i, val in ipairs(value) do - local narg = string.format('%s[%d]', option, i) - assert_type(val, 'string/number', narg) - if option == 'palette' and type(val) == 'number' then - value[i] = torgb(val) -- nil return is okay - elseif option == 'select' and assert_type(val, 'number', narg) then - value[i] = val - 1 -- convert from 1-based index to 0-based index +ui.dialogs = setmetatable({}, { + __index = function(_, k) + -- Wrapper for `ui.dialog(k)`, transforming the given table of arguments into a set of + -- command line arguments and transforming the resulting standard output into Lua objects. + -- @param options Table of key-value command line options for gtdialog. + -- @param f Work function for progressbar dialogs. + -- @return Lua objects depending on the dialog kind + return function(options, f) + if not options.button1 then options.button1 = _L['OK'] end + if k == 'filteredlist' and not options.width then + options.width = ui.size[1] - 2 * (CURSES and 1 or 100) + end + -- Transform key-value pairs into command line arguments. + local args = {} + for option, value in pairs(options) do + if assert_type(value, 'string/number/table/boolean', option) then + args[#args + 1] = '--' .. option:gsub('_', '-') + if type(value) == 'table' then + for i, val in ipairs(value) do + local narg = string.format('%s[%d]', option, i) + assert_type(val, 'string/number', narg) + if option == 'palette' and type(val) == 'number' then + value[i] = torgb(val) -- nil return is okay + elseif option == 'select' and assert_type(val, 'number', narg) then + value[i] = val - 1 -- convert from 1-based index to 0-based index + end end + elseif option == 'color' and type(value) == 'number' then + value = torgb(value) + elseif option == 'select' and assert_type(value, 'number', option) then + value = value - 1 -- convert from 1-based index to 0-based index end - elseif option == 'color' and type(value) == 'number' then - value = torgb(value) - elseif option == 'select' and assert_type(value, 'number', option) then - value = value - 1 -- convert from 1-based index to 0-based index + if type(value) ~= 'boolean' then args[#args + 1] = value end end - if type(value) ~= 'boolean' then args[#args + 1] = value end - end - end - if k == 'progressbar' then - args[#args + 1] = assert_type(f, 'function', 2) - end - -- Call gtdialog, stripping any trailing newline in the output. - local result = ui.dialog( - k:gsub('_', '-'), table.unpack(args)):match('^(.-)\n?$') - -- Depending on the dialog type, transform the result into Lua objects. - if k == 'fileselect' or k == 'filesave' then - if result == '' then return nil end - if WIN32 and not CURSES then result = result:iconv(_CHARSET, 'UTF-8') end - if k == 'filesave' or not options.select_multiple then return result end - local filenames = {} - for filename in result:gmatch('[^\n]+') do - filenames[#filenames + 1] = filename - end - return filenames - elseif k == 'filteredlist' or k == 'optionselect' or - k:find('input') and result:match('^[^\n]+\n?(.*)$'):find('\n') then - local button, value = result:match('^([^\n]+)\n?(.*)$') - if not options.string_output then button = tonumber(button) end - if k == 'optionselect' then - options.select_multiple = true - elseif k:find('input') then - options.string_output, options.select_multiple = true, true end - local items, patt = {}, not k:find('input') and '[^\n]+' or '([^\n]*)\n' - for item in (value .. '\n'):gmatch(patt) do - items[#items + 1] = options.string_output and item or tonumber(item) + 1 - end - return button, options.select_multiple and items or items[1] - elseif k == 'colorselect' then - if options.string_output then return result ~= '' and result or nil end - local r, g, b = result:match('^#(%x%x)(%x%x)(%x%x)$') - local bgr = r and g and b and string.format('0x%s%s%s', b, g, r) or nil - return tonumber(bgr) - elseif k == 'fontselect' or k == 'progressbar' then - return result ~= '' and result or nil - elseif not options.string_output then - local i, value = result:match('^(%-?%d+)\n?(.*)$') - i = tonumber(i) - if k:find('dropdown') then - value = i > 0 and tonumber(value) + 1 or nil + if k == 'progressbar' then args[#args + 1] = assert_type(f, 'function', 2) end + -- Call gtdialog, stripping any trailing newline in the output. + local result = ui.dialog(k:gsub('_', '-'), table.unpack(args)):match('^(.-)\n?$') + -- Depending on the dialog type, transform the result into Lua objects. + if k == 'fileselect' or k == 'filesave' then + if result == '' then return nil end + if WIN32 and not CURSES then result = result:iconv(_CHARSET, 'UTF-8') end + if k == 'filesave' or not options.select_multiple then return result end + local filenames = {} + for filename in result:gmatch('[^\n]+') do filenames[#filenames + 1] = filename end + return filenames + elseif k == 'filteredlist' or k == 'optionselect' or + (k:find('input') and result:match('^[^\n]+\n?(.*)$'):find('\n')) then + local button, value = result:match('^([^\n]+)\n?(.*)$') + if not options.string_output then button = tonumber(button) end + if k == 'optionselect' then + options.select_multiple = true + elseif k:find('input') then + options.string_output, options.select_multiple = true, true + end + local items, patt = {}, not k:find('input') and '[^\n]+' or '([^\n]*)\n' + for item in (value .. '\n'):gmatch(patt) do + items[#items + 1] = options.string_output and item or tonumber(item) + 1 + end + return button, options.select_multiple and items or items[1] + elseif k == 'colorselect' then + if options.string_output then return result ~= '' and result or nil end + local r, g, b = result:match('^#(%x%x)(%x%x)(%x%x)$') + local bgr = r and g and b and string.format('0x%s%s%s', b, g, r) or nil + return tonumber(bgr) + elseif k == 'fontselect' or k == 'progressbar' then + return result ~= '' and result or nil + elseif not options.string_output then + local i, value = result:match('^(%-?%d+)\n?(.*)$') + i = tonumber(i) + if k:find('dropdown') then value = i > 0 and tonumber(value) + 1 or nil end + return i, value end - return i, value + return result:match('([^\n]+)\n?(.*)$') end - return result:match('([^\n]+)\n?(.*)$') end -end}) +}) local buffers_zorder = {} @@ -218,18 +214,15 @@ events.connect(events.VIEW_AFTER_SWITCH, update_zorder) events.connect(events.BUFFER_DELETED, update_zorder) -- Saves and restores buffer zorder data during a reset. -events.connect( - events.RESET_BEFORE, function(persist) persist.ui_zorder = buffers_zorder end) -events.connect( - events.RESET_AFTER, function(persist) buffers_zorder = persist.ui_zorder end) +events.connect(events.RESET_BEFORE, function(persist) persist.ui_zorder = buffers_zorder end) +events.connect(events.RESET_AFTER, function(persist) buffers_zorder = persist.ui_zorder end) --- -- 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). --- @param zorder Flag that indicates whether or not to list buffers by their --- z-order. The default value is `false`. +-- 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). +-- @param zorder Flag that indicates whether or not to list buffers by their z-order. The +-- default value is `false`. -- @name switch_buffer function ui.switch_buffer(zorder) local buffers = not zorder and _BUFFERS or buffers_zorder @@ -251,29 +244,26 @@ end --- -- 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. -- @param filename The filename of the buffer to go to. --- @param 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`. --- @param preferred_view Optional view to open the desired buffer in if the --- buffer is not visible in any other view. --- @param 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`. +-- @param 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`. +-- @param preferred_view Optional view to open the desired buffer in if the buffer is not +-- visible in any other view. +-- @param 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`. -- @name goto_file function ui.goto_file(filename, split, preferred_view, sloppy) assert_type(filename, 'string', 1) - local patt = string.format( -- TODO: escape filename properly - '%s%s$', not sloppy and '^' or '', - not sloppy and filename or filename:match('[^/\\]+$')) + local patt = string.format('%s%s$', not sloppy and '^' or '', + not sloppy and filename or filename:match('[^/\\]+$')) -- TODO: escape filename properly if WIN32 then patt = patt:gsub('%a', function(letter) return string.format('[%s%s]', letter:upper(), letter:lower()) @@ -285,13 +275,19 @@ function ui.goto_file(filename, split, preferred_view, sloppy) local other_view = _VIEWS[preferred_view] for _, view in ipairs(_VIEWS) do local filename = view.buffer.filename or '' - if filename:find(patt) then ui.goto_view(view) return end + if filename:find(patt) then + ui.goto_view(view) + return + end if not other_view and view ~= _G.view then other_view = view end end if other_view then ui.goto_view(other_view) end end for _, buf in ipairs(_BUFFERS) do - if (buf.filename or ''):find(patt) then view:goto_buffer(buf) return end + if (buf.filename or ''):find(patt) then + view:goto_buffer(buf) + return + end end io.open_file(filename) end @@ -300,18 +296,14 @@ end events.connect(events.VIEW_NEW, function() events.emit(events.UPDATE_UI, 3) end) -- Switches between buffers when a tab is clicked. -events.connect( - events.TAB_CLICKED, function(index) view:goto_buffer(_BUFFERS[index]) end) +events.connect(events.TAB_CLICKED, function(index) view:goto_buffer(_BUFFERS[index]) end) -- Sets the title of the Textadept window to the buffer's filename. local function set_title() local filename = buffer.filename or buffer._type or _L['Untitled'] - if buffer.filename then - filename = select(2, pcall(string.iconv, filename, 'UTF-8', _CHARSET)) - end + if buffer.filename then filename = select(2, pcall(string.iconv, filename, 'UTF-8', _CHARSET)) end local basename = buffer.filename and filename:match('[^/\\]+$') or filename - ui.title = string.format( - '%s %s Textadept (%s)', basename, buffer.modify and '*' or '-', filename) + ui.title = string.format('%s %s Textadept (%s)', basename, buffer.modify and '*' or '-', filename) buffer.tab_label = basename .. (buffer.modify and '*' or '') end @@ -322,9 +314,8 @@ events.connect(events.SAVE_POINT_LEFT, set_title) -- Open uri(s). events.connect(events.URI_DROPPED, function(utf8_uris) for utf8_path in utf8_uris:gmatch('file://([^\r\n]+)') do - local path = utf8_path:gsub('%%(%x%x)', function(hex) - return string.char(tonumber(hex, 16)) - end):iconv(_CHARSET, 'UTF-8') + local path = utf8_path:gsub('%%(%x%x)', function(hex) return string.char(tonumber(hex, 16)) end) + :iconv(_CHARSET, 'UTF-8') -- In WIN32, ignore a leading '/', but not '//' (network path). if WIN32 and not path:match('^//') then path = path:sub(2, -1) end local mode = lfs.attributes(path, 'mode') @@ -332,9 +323,8 @@ events.connect(events.URI_DROPPED, function(utf8_uris) end ui.goto_view(view) -- work around any view focus synchronization issues end) -events.connect(events.APPLEEVENT_ODOC, function(uri) - return events.emit(events.URI_DROPPED, 'file://' .. uri) -end) +events.connect(events.APPLEEVENT_ODOC, + function(uri) return events.emit(events.URI_DROPPED, 'file://' .. uri) end) -- Sets buffer statusbar text. events.connect(events.UPDATE_UI, function(updated) @@ -346,11 +336,11 @@ events.connect(events.UPDATE_UI, function(updated) local col = buffer.column[pos] local lang = buffer:get_lexer() local eol = buffer.eol_mode == buffer.EOL_CRLF and _L['CRLF'] or _L['LF'] - local tabs = string.format( - '%s %d', buffer.use_tabs and _L['Tabs:'] or _L['Spaces:'], buffer.tab_width) + local tabs = string.format('%s %d', buffer.use_tabs and _L['Tabs:'] or _L['Spaces:'], + buffer.tab_width) local encoding = buffer.encoding or '' - ui.buffer_statusbar_text = string.format( - text, _L['Line:'], line, max, _L['Col:'], col, lang, eol, tabs, encoding) + ui.buffer_statusbar_text = string.format(text, _L['Line:'], line, max, _L['Col:'], col, lang, eol, + tabs, encoding) end) -- Save buffer properties. @@ -420,8 +410,7 @@ end events.connect(events.BUFFER_AFTER_SWITCH, restore_view_state) events.connect(events.VIEW_AFTER_SWITCH, restore_view_state) -events.connect( - events.RESET_AFTER, function() ui.statusbar_text = _L['Lua reset'] end) +events.connect(events.RESET_AFTER, function() ui.statusbar_text = _L['Lua reset'] end) -- Prompts for confirmation if any buffers are modified. events.connect(events.QUIT, function() @@ -435,19 +424,16 @@ events.connect(events.QUIT, function() end if #utf8_list == 0 then return end local button = ui.dialogs.msgbox{ - title = _L['Quit without saving?'], - text = _L['The following buffers are unsaved:'], - informative_text = table.concat(utf8_list, '\n'), - icon = 'gtk-dialog-question', button1 = _L['Cancel'], - button2 = _L['Quit without saving'], + title = _L['Quit without saving?'], text = _L['The following buffers are unsaved:'], + informative_text = table.concat(utf8_list, '\n'), icon = 'gtk-dialog-question', + button1 = _L['Cancel'], button2 = _L['Quit without saving'], width = CURSES and ui.size[1] - 2 or nil } if button ~= 2 then return true end -- prevent quit end) -- Keeps track of, and switches back to the previous buffer after buffer close. -events.connect( - events.BUFFER_BEFORE_SWITCH, function() view._prev_buffer = buffer end) +events.connect(events.BUFFER_BEFORE_SWITCH, function() view._prev_buffer = buffer end) events.connect(events.BUFFER_DELETED, function() if _BUFFERS[view._prev_buffer] and buffer ~= view._prev_buffer then restore_view_state() -- events.BUFFER_AFTER_SWITCH is not emitted in time @@ -455,15 +441,11 @@ events.connect(events.BUFFER_DELETED, function() end end) --- Properly handle clipboard text between views in curses, enables and disables --- mouse mode, and focuses and resizes views based on mouse events. +-- Properly handle clipboard text between views in curses, enables and disables mouse mode, +-- and focuses and resizes views based on mouse events. if CURSES then - events.connect(events.VIEW_BEFORE_SWITCH, function() - ui._clipboard_text = ui.clipboard_text - end) - events.connect(events.VIEW_AFTER_SWITCH, function() - ui.clipboard_text = ui._clipboard_text - end) + events.connect(events.VIEW_BEFORE_SWITCH, function() ui._clipboard_text = ui.clipboard_text end) + events.connect(events.VIEW_AFTER_SWITCH, function() ui.clipboard_text = ui._clipboard_text end) if not WIN32 then local function enable_mouse() io.stdout:write("\x1b[?1002h"):flush() end @@ -485,8 +467,7 @@ if CURSES then return get_view(view[1], y, x) elseif vertical and x > size or not vertical and y > size then -- Zero y or x relative to the other view based on split orientation. - return get_view( - view[2], vertical and y or y - size - 1, vertical and x - size - 1 or x) + return get_view(view[2], vertical and y or y - size - 1, vertical and x - size - 1 or x) else return view -- in-between views; return the split itself end @@ -516,8 +497,8 @@ end events.connect(events.INITIALIZED, function() local lua_error = (not WIN32 and '^/' or '^%a:[/\\]') .. '.-%.lua:%d+:' -- Print internal Lua error messages as they are reported. - -- Attempt to mimic the Lua interpreter's error message format so tools that - -- look for it can recognize these errors too. + -- Attempt to mimic the Lua interpreter's error message format so tools that look for it can + -- recognize these errors too. events.connect(events.ERROR, function(text) if text and text:find(lua_error) then text = 'lua: ' .. text end ui.print(text) @@ -528,8 +509,7 @@ end) --- -- 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 textadept.menu.menubar -- @class table -- @name menubar @@ -544,13 +524,11 @@ local size The functions below are Lua C functions. --- --- Low-level function for prompting the user with a [gtdialog][] of kind *kind* --- with the given string and table arguments, returning a formatted string of --- the dialog's output. --- You probably want to use the higher-level functions in the [`ui.dialogs`]() --- module. --- Table arguments containing strings are allowed and expanded in place. This is --- useful for filtered list dialogs with many items. +-- Low-level function for prompting the user with a [gtdialog][] of kind *kind* with the given +-- string and table arguments, returning a formatted string of the dialog's output. +-- You probably want to use the higher-level functions in the [`ui.dialogs`]() module. +-- Table arguments containing strings are allowed and expanded in place. This is useful for +-- filtered list dialogs with many items. -- -- [gtdialog]: https://orbitalquark.github.io/gtdialog/manual.html -- @param kind The kind of gtdialog. @@ -563,18 +541,16 @@ local dialog --- -- Returns a split table that contains Textadept's current split view structure. -- 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. +-- @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. -- @class function -- @name get_split_table local get_split_table --- --- 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. -- @param view A view or relative view number (typically 1 or -1). -- @see _G._VIEWS @@ -585,17 +561,15 @@ local get_split_table local goto_view --- --- 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. --- @param 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. +-- @param 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 ui.menu{ {'_New', 1}, {'_Open', 2}, {''}, {'_Quit', 4} } -- @usage ui.menu{ {'_New', 1, string.byte('n'), 4} } -- 'Ctrl+N' -- @see events.MENU_CLICKED 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 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.  @@ -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.  -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 --------------------------------------------------------------------------------- +---  -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.   -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.)  @@ -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.  -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.  -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.  --------------------------------------------------------------------------------- +--- ### 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.  -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  -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.  @@ -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  -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.   -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.  -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.  @@ -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.   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.  #### 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`.  -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. @@ -1,20 +1,17 @@ -- Copyright 2007-2021 Mitchell. See LICENSE. package.path = table.concat({ - _USERHOME .. '/modules/?.lua', _USERHOME .. '/modules/?/init.lua', - _HOME .. '/modules/?.lua', _HOME .. '/modules/?/init.lua', package.path + _USERHOME .. '/modules/?.lua', _USERHOME .. '/modules/?/init.lua', _HOME .. '/modules/?.lua', + _HOME .. '/modules/?/init.lua', package.path }, ';'); package.cpath = table.concat({ string.format('%s/modules/?.%s', _USERHOME, not WIN32 and 'so' or 'dll'), - string.format('%s/modules/?.%s', _HOME, not WIN32 and 'so' or 'dll'), - package.cpath + string.format('%s/modules/?.%s', _HOME, not WIN32 and 'so' or 'dll'), package.cpath }, ';') --- Populate initial `_G.buffer` with temporarily exported io functions now that --- it exists. This is needed for menus and key bindings. -for name, f in pairs(io) do - if name:find('^_') then buffer[name:sub(2)], io[name] = f, nil end -end +-- Populate initial `_G.buffer` with temporarily exported io functions now that it exists. This +-- is needed for menus and key bindings. +for name, f in pairs(io) do if name:find('^_') then buffer[name:sub(2)], io[name] = f, nil end end textadept = require('textadept') @@ -24,39 +21,35 @@ local SETLEXERLANGUAGE = _SCINTILLA.properties.lexer_language[2] local function set_theme(view, name, env) for k in pairs(lexer.colors) do lexer.colors[k] = nil end -- clear mimic if not assert_type(name, 'string', 2):find('[/\\]') then - name = package.searchpath(name, string.format( - '%s/themes/?.lua;%s/themes/?.lua', _USERHOME, _HOME)) + name = package.searchpath(name, + string.format('%s/themes/?.lua;%s/themes/?.lua', _USERHOME, _HOME)) end if not name or not lfs.attributes(name) then return end if not assert_type(env, 'table/nil', 3) then env = {} end local orig_view = _G.view if view ~= orig_view then ui.goto_view(view) end loadfile(name, 't', setmetatable(env, {__index = _G}))() - -- Force reload of all styles since the current lexer may have defined its own - -- styles. (The LPeg lexer has only refreshed default lexer styles.) + -- Force reload of all styles since the current lexer may have defined its own styles. (The + -- LPeg lexer has only refreshed default lexer styles.) -- Note: cannot use `buffer.set_lexer()` because it may not exist yet. buffer:private_lexer_call(SETLEXERLANGUAGE, buffer._lexer or 'text') if view ~= orig_view then ui.goto_view(orig_view) end end events.connect(events.VIEW_NEW, function() view.set_theme = set_theme end) view.set_theme = set_theme -- needed for the first view --- On reset, _LOADED['lexer'] is removed. Force a reload in order for set_theme --- to work properly. +-- On reset, _LOADED['lexer'] is removed. Force a reload in order for set_theme to work properly. if not arg then view:goto_buffer(buffer) end --- The remainder of this file defines default buffer and view properties and --- applies them to subsequent buffers and views. Normally, a setting like --- `buffer.use_tabs = false` only applies to the current (initial) buffer. --- However, temporarily tap into buffer and view's metatables in order to --- capture these initial settings (both from Textadept's init.lua and from the --- user's init.lua) so they can be applied to subsequent buffers and views. +-- The remainder of this file defines default buffer and view properties and applies them to +-- subsequent buffers and views. Normally, a setting like `buffer.use_tabs = false` only applies +-- to the current (initial) buffer.However, temporarily tap into buffer and view's metatables in +-- order to capture these initial settings (both from Textadept's init.lua and from the user's +-- init.lua) so they can be applied to subsequent buffers and views. local settings = {} local buffer_mt, view_mt = getmetatable(buffer), getmetatable(view) -local function repr(v) - return string.format(type(v) == 'string' and '%q' or '%s', v) -end +local function repr(v) return string.format(type(v) == 'string' and '%q' or '%s', v) end for _, mt in ipairs{buffer_mt, view_mt} do mt.__orig_index, mt.__orig_newindex = mt.__index, mt.__newindex mt.__index = function(t, k) @@ -66,17 +59,14 @@ for _, mt in ipairs{buffer_mt, view_mt} do local args = {...} if type(args[1]) == 'table' then table.remove(args, 1) end -- self for i = 1, #args do args[i] = repr(args[i]) end - settings[#settings + 1] = string.format( - 'buffer:%s(%s)', k, table.concat(args, ',')) + settings[#settings + 1] = string.format('buffer:%s(%s)', k, table.concat(args, ',')) return v(...) end elseif type(v) == 'table' then local property_mt = getmetatable(v) setmetatable(v, { - __index = property_mt.__index, - __newindex = function(property, k2, v2) - settings[#settings + 1] = string.format( - 'buffer.%s[%s]=%s', k, repr(k2), repr(v2)) + __index = property_mt.__index, __newindex = function(property, k2, v2) + settings[#settings + 1] = string.format('buffer.%s[%s]=%s', k, repr(k2), repr(v2)) local ok, errmsg = pcall(property_mt.__newindex, property, k2, v2) if not ok then error(errmsg, 2) end end @@ -90,27 +80,29 @@ for _, mt in ipairs{buffer_mt, view_mt} do end end --- Mimic the `lexer` module because (1) it is not yet available and (2) even if --- it was, color, style, and property settings would not be captured during --- init. +-- Mimic the `lexer` module because (1) it is not yet available and (2) even if it was, color, +-- style, and property settings would not be captured during init. local property = view.property -local colors = setmetatable({}, {__newindex = function(t, name, color) - if type(color) == 'string' then - local r, g, b = color:match('^#(%x%x)(%x%x)(%x%x)$') - color = tonumber(string.format('%s%s%s', b, g, r), 16) or 0 +local colors = setmetatable({}, { + __newindex = function(t, name, color) + if type(color) == 'string' then + local r, g, b = color:match('^#(%x%x)(%x%x)(%x%x)$') + color = tonumber(string.format('%s%s%s', b, g, r), 16) or 0 + end + property['color.' .. name] = color + rawset(t, name, color) -- cache instead of __index for property[...] end - property['color.' .. name] = color - rawset(t, name, color) -- cache instead of __index for property[...] -end}) -local styles = setmetatable({}, {__newindex = function(_, name, props) - local settings = {} - for k, v in pairs(props) do - settings[#settings + 1] = type(v) ~= 'boolean' and - string.format('%s:%s', k, v) or - string.format('%s%s', v and '' or 'not', k) +}) +local styles = setmetatable({}, { + __newindex = function(_, name, props) + local settings = {} + for k, v in pairs(props) do + settings[#settings + 1] = type(v) ~= 'boolean' and string.format('%s:%s', k, v) or + string.format('%s%s', v and '' or 'not', k) + end + property['style.' .. name] = table.concat(settings, ',') end - property['style.' .. name] = table.concat(settings, ',') -end}) +}) lexer = setmetatable({colors = colors, styles = styles}, { __newindex = function(_, k, v) property[k ~= 'folding' and k:gsub('_', '.') or 'fold'] = v and '1' or '0' @@ -125,30 +117,28 @@ view:set_theme(not CURSES and 'light' or 'term') -- Multiple Selection and Virtual Space buffer.multiple_selection, buffer.additional_selection_typing = true, true buffer.multi_paste = buffer.MULTIPASTE_EACH ---buffer.virtual_space_options = buffer.VS_RECTANGULARSELECTION | --- buffer.VS_USERACCESSIBLE +-- buffer.virtual_space_options = buffer.VS_RECTANGULARSELECTION | buffer.VS_USERACCESSIBLE view.rectangular_selection_modifier = view.MOD_ALT view.mouse_selection_rectangular_switch = true ---view.additional_carets_blink = false ---view.additional_carets_visible = false +-- view.additional_carets_blink = false +-- view.additional_carets_visible = false -- Scrolling. view:set_x_caret_policy(view.CARET_SLOP, 20) -view:set_y_caret_policy( - view.CARET_SLOP | view.CARET_STRICT | view.CARET_EVEN, 1) +view:set_y_caret_policy(view.CARET_SLOP | view.CARET_STRICT | view.CARET_EVEN, 1) view:set_visible_policy(view.VISIBLE_SLOP | view.VISIBLE_STRICT, 5) ---view.h_scroll_bar = CURSES ---view.v_scroll_bar = false +-- view.h_scroll_bar = CURSES +-- view.v_scroll_bar = false if CURSES and not (WIN32 or LINUX or BSD) then view.v_scroll_bar = false end ---view.scroll_width = ---view.scroll_width_tracking = true ---view.end_at_last_line = false +-- view.scroll_width = +-- view.scroll_width_tracking = true +-- view.end_at_last_line = false -- Whitespace view.view_ws = view.WS_INVISIBLE ---view.whitespace_size = ---view.extra_ascent = ---view.extra_descent = +-- view.whitespace_size = +-- view.extra_ascent = +-- view.extra_descent = -- Line Endings buffer.eol_mode = WIN32 and buffer.EOL_CRLF or buffer.EOL_LF @@ -158,17 +148,17 @@ view.view_eol = false if not CURSES then view.idle_styling = view.IDLESTYLING_ALL end -- Caret and Selection Styles. ---view.sel_eol_filled = true +-- view.sel_eol_filled = true view.caret_line_visible = not CURSES ---view.caret_line_visible_always = true ---view.caret_period = 0 ---view.caret_style = view.CARETSTYLE_BLOCK ---view.caret_width = ---buffer.caret_sticky = buffer.CARETSTICKY_ON +-- view.caret_line_visible_always = true +-- view.caret_period = 0 +-- view.caret_style = view.CARETSTYLE_BLOCK +-- view.caret_width = +-- buffer.caret_sticky = buffer.CARETSTICKY_ON -- Margins. ---view.margin_left = ---view.margin_right = +-- view.margin_left = +-- view.margin_right = -- Line Number Margin. view.margin_type_n[1] = view.MARGIN_NUMBER local function resize_line_number_margin() @@ -200,14 +190,14 @@ view.eol_annotation_visible = view.EOLANNOTATION_BOXED -- Other. buffer.buffered_draw = not CURSES and not OSX -- Quartz buffers drawing on macOS ---buffer.word_chars = ---buffer.whitespace_chars = ---buffer.punctuation_chars = +-- buffer.word_chars = +-- buffer.whitespace_chars = +-- buffer.punctuation_chars = -- Tabs and Indentation Guides. -- Note: tab and indentation settings apply to individual buffers. buffer.tab_width, buffer.use_tabs = 2, false ---buffer.indent = 2 +-- buffer.indent = 2 buffer.tab_indents, buffer.back_space_un_indents = true, true view.indentation_guides = not CURSES and view.IV_LOOKBOTH or view.IV_NONE @@ -216,41 +206,38 @@ view:marker_define(textadept.bookmarks.MARK_BOOKMARK, view.MARK_FULLRECT) view:marker_define(textadept.run.MARK_WARNING, view.MARK_FULLRECT) view:marker_define(textadept.run.MARK_ERROR, view.MARK_FULLRECT) -- Arrow Folding Symbols. ---view:marker_define(buffer.MARKNUM_FOLDEROPEN, view.MARK_ARROWDOWN) ---view:marker_define(buffer.MARKNUM_FOLDER, view.MARK_ARROW) ---view:marker_define(buffer.MARKNUM_FOLDERSUB, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDERTAIL, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDEREND, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDEROPENMID, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDERMIDTAIL, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDEROPEN, view.MARK_ARROWDOWN) +-- view:marker_define(buffer.MARKNUM_FOLDER, view.MARK_ARROW) +-- view:marker_define(buffer.MARKNUM_FOLDERSUB, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDERTAIL, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDEREND, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDEROPENMID, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDERMIDTAIL, view.MARK_EMPTY) -- Plus/Minus Folding Symbols. ---view:marker_define(buffer.MARKNUM_FOLDEROPEN, view.MARK_MINUS) ---view:marker_define(buffer.MARKNUM_FOLDER, view.MARK_PLUS) ---view:marker_define(buffer.MARKNUM_FOLDERSUB, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDERTAIL, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDEREND, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDEROPENMID, view.MARK_EMPTY) ---view:marker_define(buffer.MARKNUM_FOLDERMIDTAIL, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDEROPEN, view.MARK_MINUS) +-- view:marker_define(buffer.MARKNUM_FOLDER, view.MARK_PLUS) +-- view:marker_define(buffer.MARKNUM_FOLDERSUB, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDERTAIL, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDEREND, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDEROPENMID, view.MARK_EMPTY) +-- view:marker_define(buffer.MARKNUM_FOLDERMIDTAIL, view.MARK_EMPTY) -- Circle Tree Folding Symbols. ---view:marker_define(buffer.MARKNUM_FOLDEROPEN, view.MARK_CIRCLEMINUS) ---view:marker_define(buffer.MARKNUM_FOLDER, view.MARK_CIRCLEPLUS) ---view:marker_define(buffer.MARKNUM_FOLDERSUB, view.MARK_VLINE) ---view:marker_define(buffer.MARKNUM_FOLDERTAIL, view.MARK_LCORNERCURVE) ---view:marker_define( --- buffer.MARKNUM_FOLDEREND, view.MARK_CIRCLEPLUSCONNECTED) ---view:marker_define( --- buffer.MARKNUM_FOLDEROPENMID, view.MARK_CIRCLEMINUSCONNECTED) ---view:marker_define(buffer.MARKNUM_FOLDERMIDTAIL, view.MARK_TCORNERCURVE) +-- view:marker_define(buffer.MARKNUM_FOLDEROPEN, view.MARK_CIRCLEMINUS) +-- view:marker_define(buffer.MARKNUM_FOLDER, view.MARK_CIRCLEPLUS) +-- view:marker_define(buffer.MARKNUM_FOLDERSUB, view.MARK_VLINE) +-- view:marker_define(buffer.MARKNUM_FOLDERTAIL, view.MARK_LCORNERCURVE) +-- view:marker_define(buffer.MARKNUM_FOLDEREND, view.MARK_CIRCLEPLUSCONNECTED) +-- view:marker_define(buffer.MARKNUM_FOLDEROPENMID, view.MARK_CIRCLEMINUSCONNECTED) +-- view:marker_define(buffer.MARKNUM_FOLDERMIDTAIL, view.MARK_TCORNERCURVE) -- Box Tree Folding Symbols. view:marker_define(buffer.MARKNUM_FOLDEROPEN, view.MARK_BOXMINUS) view:marker_define(buffer.MARKNUM_FOLDER, view.MARK_BOXPLUS) view:marker_define(buffer.MARKNUM_FOLDERSUB, view.MARK_VLINE) view:marker_define(buffer.MARKNUM_FOLDERTAIL, view.MARK_LCORNER) view:marker_define(buffer.MARKNUM_FOLDEREND, view.MARK_BOXPLUSCONNECTED) -view:marker_define( - buffer.MARKNUM_FOLDEROPENMID, view.MARK_BOXMINUSCONNECTED) +view:marker_define(buffer.MARKNUM_FOLDEROPENMID, view.MARK_BOXMINUSCONNECTED) view:marker_define(buffer.MARKNUM_FOLDERMIDTAIL, view.MARK_TCORNER) ---view:marker_enable_highlight(true) +-- view:marker_enable_highlight(true) -- Indicators. view.indic_style[ui.find.INDIC_FIND] = view.INDIC_ROUNDBOX @@ -263,46 +250,43 @@ view.indic_style[textadept.snippets.INDIC_PLACEHOLDER] = not CURSES and view.INDIC_DOTBOX or view.INDIC_STRAIGHTBOX -- Autocompletion. ---buffer.auto_c_separator = ---buffer.auto_c_cancel_at_start = false ---buffer.auto_c_fill_ups = '(' +-- buffer.auto_c_separator = +-- buffer.auto_c_cancel_at_start = false +-- buffer.auto_c_fill_ups = '(' buffer.auto_c_choose_single = true ---buffer.auto_c_ignore_case = true ---buffer.auto_c_case_insensitive_behavior = --- buffer.CASEINSENSITIVEBEHAVIOR_IGNORECASE +-- buffer.auto_c_ignore_case = true +-- buffer.auto_c_case_insensitive_behavior = buffer.CASEINSENSITIVEBEHAVIOR_IGNORECASE buffer.auto_c_multi = buffer.MULTIAUTOC_EACH ---buffer.auto_c_auto_hide = false ---buffer.auto_c_drop_rest_of_word = true ---buffer.auto_c_type_separator = ---view.auto_c_max_height = ---view.auto_c_max_width = +-- buffer.auto_c_auto_hide = false +-- buffer.auto_c_drop_rest_of_word = true +-- buffer.auto_c_type_separator = +-- view.auto_c_max_height = +-- view.auto_c_max_width = -- Call Tips. -view.call_tip_use_style = buffer.tab_width * - view:text_width(view.STYLE_CALLTIP, ' ') ---view.call_tip_position = true +view.call_tip_use_style = buffer.tab_width * view:text_width(view.STYLE_CALLTIP, ' ') +-- view.call_tip_position = true -- Folding. lexer.folding = true ---lexer.fold_by_indentation = true ---lexer.fold_line_groups = true ---lexer.fold_on_zero_sum_lines = true ---lexer.fold_compact = true -view.automatic_fold = view.AUTOMATICFOLD_SHOW | view.AUTOMATICFOLD_CLICK | - view.AUTOMATICFOLD_CHANGE +-- lexer.fold_by_indentation = true +-- lexer.fold_line_groups = true +-- lexer.fold_on_zero_sum_lines = true +-- lexer.fold_compact = true +view.automatic_fold = view.AUTOMATICFOLD_SHOW | view.AUTOMATICFOLD_CLICK | view.AUTOMATICFOLD_CHANGE view.fold_flags = not CURSES and view.FOLDFLAG_LINEAFTER_CONTRACTED or 0 view.fold_display_text_style = view.FOLDDISPLAYTEXT_BOXED -- Line Wrapping. view.wrap_mode = view.WRAP_NONE ---view.wrap_visual_flags = view.WRAPVISUALFLAG_MARGIN ---view.wrap_visual_flags_location = view.WRAPVISUALFLAGLOC_END_BY_TEXT ---view.wrap_indent_mode = view.WRAPINDENT_SAME ---view.wrap_start_indent = +-- view.wrap_visual_flags = view.WRAPVISUALFLAG_MARGIN +-- view.wrap_visual_flags_location = view.WRAPVISUALFLAGLOC_END_BY_TEXT +-- view.wrap_indent_mode = view.WRAPINDENT_SAME +-- view.wrap_start_indent = -- Long Lines. ---view.edge_mode = not CURSES and view.EDGE_LINE or view.EDGE_BACKGROUND ---view.edge_column = 80 +-- view.edge_mode = not CURSES and view.EDGE_LINE or view.EDGE_BACKGROUND +-- view.edge_column = 80 -- Accessibility. buffer.accessibility = buffer.ACCESSIBILITY_DISABLED @@ -312,13 +296,12 @@ local user_init = _USERHOME .. '/init.lua' if lfs.attributes(user_init) then local ok, errmsg = pcall(dofile, user_init) if not ok then - events.connect( - events.INITIALIZED, function() events.emit(events.ERROR, errmsg) end) + events.connect(events.INITIALIZED, function() events.emit(events.ERROR, errmsg) end) end end --- Generate default buffer settings for subsequent buffers and remove temporary --- buffer and view metatable listeners. +-- Generate default buffer settings for subsequent buffers and remove temporary buffer and view +-- metatable listeners. local load_settings = load(table.concat(settings, '\n')) for _, mt in ipairs{buffer_mt, view_mt} do mt.__index, mt.__newindex = mt.__orig_index, mt.__orig_newindex @@ -339,31 +322,25 @@ events.connect(events.BUFFER_NEW, function() load_settings() buffer:private_lexer_call(SETLEXERLANGUAGE, 'text') _G.lexer = require('lexer') -- replace mimic - if buffer == ui.command_entry then - ui.command_entry.caret_line_visible = false - end + if buffer == ui.command_entry then ui.command_entry.caret_line_visible = false end end, 1) -- Sets default properties for a Scintilla window. events.connect(events.VIEW_NEW, function() local buffer, view = _G.buffer, _G.view -- Allow redefinitions of these Scintilla key bindings. - for _, code in utf8.codes('[]/\\ZYXCVALTDU') do - view:clear_cmd_key(code | view.MOD_CTRL << 16) - end + for _, code in utf8.codes('[]/\\ZYXCVALTDU') do view:clear_cmd_key(code | view.MOD_CTRL << 16) end for _, code in utf8.codes('LTUZ') do view:clear_cmd_key(code | (view.MOD_CTRL | view.MOD_SHIFT) << 16) end - -- Since BUFFER_NEW loads themes and settings on startup, only load them for - -- subsequent views. + -- Since BUFFER_NEW loads themes and settings on startup, only load them for subsequent views. if #_VIEWS == 1 then return end load_settings() - -- Refresh styles in case a lexer has extra style settings. When - -- load_settings() calls `view.property['style.default'] = ...`, the LPeg - -- lexer resets all styles to that default. However, some lexers have extra - -- style settings that are not set by load_settings(), and thus need - -- refreshing. This is not an issue in BUFFER_NEW since a lexer is set - -- immediately afterwards, which refreshes styles. + -- Refresh styles in case a lexer has extra style settings. When load_settings() calls + -- `view.property['style.default'] = ...`, the LPeg lexer resets all styles to that default. + -- However, some lexers have extra style settings that are not set by load_settings(), and + -- thus need refreshing. This is not an issue in BUFFER_NEW since a lexer is set immediately + -- afterwards, which refreshes styles. -- Note: `buffer:set_lexer()` is insufficient for some reason. buffer:private_lexer_call(SETLEXERLANGUAGE, buffer._lexer or 'text') end, 1) diff --git a/modules/ansi_c/api b/modules/ansi_c/api index 58902be2..0bb18062 100644 --- a/modules/ansi_c/api +++ b/modules/ansi_c/api @@ -1,290 +1,290 @@ -assert assert(int expression) [void]\nMacro used for internal error detection. (Ignored if NDEBUG is defined where \n<assert.h> is included.) If `expression` equals zero, message printed on stderr\nand abort called to terminate execution. Source filename and line number in\nmessage are from preprocessor macros __FILE__ and __LINE__. +assert assert(int expression) [void]\nMacro used for internal error detection. (Ignored if NDEBUG is defined where <assert.h> is\nincluded.) If `expression` equals zero, message printed on stderr and abort called to terminate\nexecution. Source filename and line number in message are from preprocessor macros __FILE__\nand __LINE__.\n -isalnum isalnum(int c) [int]\nisalpha(c) or isdigit(c) -isalpha isalpha(int c) [int]\nisupper(c) or islower(c) -iscntrl iscntrl(int c) [int]\nis control character. In ASCII, control characters are 0x00 (NUL) to 0x1F (US),\nand 0x7F (DEL) -isdigit isdigit(int c) [int]\nis decimal digit -isgraph isgraph(int c) [int]\nis printing character other than space -islower islower(int c) [int]\nis lower-case letter -isprint isprint(int c) [int]\nis printing character (including space). In ASCII, printing characters are 0x20\n(' ') to 0x7E ('~') -ispunct ispunct(int c) [int]\nis printing character other than space, letter, digit -isspace isspace(int c) [int]\nis space, formfeed, newline, carriage return, tab, vertical tab -isupper isupper(int c) [int]\nis upper-case letter -isxdigit isxdigit(int c) [int]\nis hexadecimal digit -tolower tolower(int c) [int]\nreturn lower-case equivalent -toupper toupper(int c) [int]\nreturn upper-case equivalent +isalnum isalnum(int c) [int]\nisalpha(c) or isdigit(c)\n +isalpha isalpha(int c) [int]\nisupper(c) or islower(c)\n +iscntrl iscntrl(int c) [int]\nis control character. In ASCII, control characters are 0x00 (NUL) to 0x1F (US), and 0x7F (DEL)\n +isdigit isdigit(int c) [int]\nis decimal digit\n +isgraph isgraph(int c) [int]\nis printing character other than space\n +islower islower(int c) [int]\nis lower-case letter\n +isprint isprint(int c) [int]\nis printing character (including space). In ASCII, printing characters are 0x20 (' ') to 0x7E ('~')\n +ispunct ispunct(int c) [int]\nis printing character other than space, letter, digit\n +isspace isspace(int c) [int]\nis space, formfeed, newline, carriage return, tab, vertical tab\n +isupper isupper(int c) [int]\nis upper-case letter\n +isxdigit isxdigit(int c) [int]\nis hexadecimal digit\n +tolower tolower(int c) [int]\nreturn lower-case equivalent\n +toupper toupper(int c) [int]\nreturn upper-case equivalent\n -errno errno\nobject to which certain library functions assign specific positive values on\nerror -EDOM EDOM\ncode used for domain errors -ERANGE ERANGE\ncode used for range errors +errno errno\nobject to which certain library functions assign specific positive values on\nerror\n +EDOM EDOM\ncode used for domain errors\n +ERANGE ERANGE\ncode used for range errors\n -FLT_RADIX FLT_RADIX\nradix of floating-point representations -FLT_ROUNDS FLT_ROUNDS\nfloating-point rounding mode +FLT_RADIX FLT_RADIX\nradix of floating-point representations\n +FLT_ROUNDS FLT_ROUNDS\nfloating-point rounding mode\n -FLT_DIG FLT_DIG\nprecision of float (in decimal digits) -DBL_DIG DBL_DIG\nprecision of double (in decimal digits) -LDBL_DIG LDBL_DIG\nprecision of long double (in decimal digits) +FLT_DIG FLT_DIG\nprecision of float (in decimal digits)\n +DBL_DIG DBL_DIG\nprecision of double (in decimal digits)\n +LDBL_DIG LDBL_DIG\nprecision of long double (in decimal digits)\n -FLT_EPSILON FLT_EPSILON\nsmallest float number x such that 1.0 + x != 1.0 -DBL_EPSILON DBL_EPSILON\nsmallest double number x such that 1.0 + x != 1.0 -LDBL_EPSILON LDBL_EPSILON\nsmallest long double number x such that 1.0 + x != 1.0 +FLT_EPSILON FLT_EPSILON\nsmallest float number x such that 1.0 + x != 1.0\n +DBL_EPSILON DBL_EPSILON\nsmallest double number x such that 1.0 + x != 1.0\n +LDBL_EPSILON LDBL_EPSILON\nsmallest long double number x such that 1.0 + x != 1.0\n -FLT_MANT_DIG FLT_MANT_DIG\nnumber of float digits, base FLT_RADIX, in mantissa -DBL_MANT_DIG DBL_MANT_DIG\nnumber of double digits, base FLT_RADIX, in mantissa -LDBL_MANT_DIG LDBL_MANT_DIG\nnumber of long double digits, base FLT_RADIX, in mantissa +FLT_MANT_DIG FLT_MANT_DIG\nnumber of float digits, base FLT_RADIX, in mantissa\n +DBL_MANT_DIG DBL_MANT_DIG\nnumber of double digits, base FLT_RADIX, in mantissa\n +LDBL_MANT_DIG LDBL_MANT_DIG\nnumber of long double digits, base FLT_RADIX, in mantissa\n -FLT_MAX FLT_MAX\nmaximum float number -DBL_MAX DBL_MAX\nmaximum double number -LDBL_MAX LDBL_MAX\nmaximum long double number +FLT_MAX FLT_MAX\nmaximum float number\n +DBL_MAX DBL_MAX\nmaximum double number\n +LDBL_MAX LDBL_MAX\nmaximum long double number\n -FLT_MAX_EXP FLT_MAX_EXP\nlargest positive integer exponent to which FLT_RADIX can be raised and remain\nrepresentable -DBL_MAX_EXP DBL_MAX_EXP\nlargest positive integer exponent to which FLT_RADIX can be raised and remain\nrepresentable -LDBL_MAX_EXP LDBL_MAX_EXP\nlargest positive integer exponent to which FLT_RADIX can be raised and remain\nrepresentable +FLT_MAX_EXP FLT_MAX_EXP\nlargest positive integer exponent to which FLT_RADIX can be raised and remain representable\n +DBL_MAX_EXP DBL_MAX_EXP\nlargest positive integer exponent to which FLT_RADIX can be raised and remain representable\n +LDBL_MAX_EXP LDBL_MAX_EXP\nlargest positive integer exponent to which FLT_RADIX can be raised and remain representable\n -FLT_MIN FLT_MIN\nminimum normalised float number -DBL_MIN DBL_MIN\nminimum normalised double number -LDBL_MIN LDBL_MIN\nminimum normalised long double number +FLT_MIN FLT_MIN\nminimum normalised float number\n +DBL_MIN DBL_MIN\nminimum normalised double number\n +LDBL_MIN LDBL_MIN\nminimum normalised long double number\n -FLT_MIN_EXP FLT_MIN_EXP\nsmallest negative integer exponent to which FLT_RADIX can be raised and remain\nrepresentable -DBL_MIN_EXP DBL_MIN_EXP\nsmallest negative integer exponent to which FLT_RADIX can be raised and remain\nrepresentable -LDBL_MIN_EXP LDBL_MIN_EXP\nsmallest negative integer exponent to which FLT_RADIX can be raised and remain\nrepresentable +FLT_MIN_EXP FLT_MIN_EXP\nsmallest negative integer exponent to which FLT_RADIX can be raised and remain representable\n +DBL_MIN_EXP DBL_MIN_EXP\nsmallest negative integer exponent to which FLT_RADIX can be raised and remain representable\n +LDBL_MIN_EXP LDBL_MIN_EXP\nsmallest negative integer exponent to which FLT_RADIX can be raised and remain representable\n -CHAR_BIT CHAR_BIT\nnumber of bits in a char -CHAR_MAX CHAR_MAX\nmaximum value of type char -CHAR_MIN CHAR_MIN\nminimum value of type char -SCHAR_MAX SCHAR_MAX\nmaximum value of type signed char -SCHAR_MIN SCHAR_MIN\nminimum value of type signed char -UCHAR_MAX UCHAR_MAX\nmaximum value of type unsigned char -SHRT_MAX SHRT_MAX\nmaximum value of type short -SHRT_MIN SHRT_MIN\nminimum value of type short -USHRT_MAX USHRT_MAX\nmaximum value of type unsigned short -INT_MAX INT_MAX\nmaximum value of type int -INT_MIN INT_MIN\nminimum value of type int -UINT_MAX UINT_MAX\nmaximum value of type unsigned int -LONG_MAX LONG_MAX\nmaximum value of type long -LONG_MIN LONG_MIN\nminimum value of type long -ULONG_MAX ULONG_MAX\nmaximum value of type unsigned long +CHAR_BIT CHAR_BIT\nnumber of bits in a char\n +CHAR_MAX CHAR_MAX\nmaximum value of type char\n +CHAR_MIN CHAR_MIN\nminimum value of type char\n +SCHAR_MAX SCHAR_MAX\nmaximum value of type signed char\n +SCHAR_MIN SCHAR_MIN\nminimum value of type signed char\n +UCHAR_MAX UCHAR_MAX\nmaximum value of type unsigned char\n +SHRT_MAX SHRT_MAX\nmaximum value of type short\n +SHRT_MIN SHRT_MIN\nminimum value of type short\n +USHRT_MAX USHRT_MAX\nmaximum value of type unsigned short\n +INT_MAX INT_MAX\nmaximum value of type int\n +INT_MIN INT_MIN\nminimum value of type int\n +UINT_MAX UINT_MAX\nmaximum value of type unsigned int\n +LONG_MAX LONG_MAX\nmaximum value of type long\n +LONG_MIN LONG_MIN\nminimum value of type long\n +ULONG_MAX ULONG_MAX\nmaximum value of type unsigned long\n -lconv lconv [struct]\nDescribes formatting of monetary and other numeric values\nImplementations may change field order and include additional fields. Standard C\nLibrary functions use only `decimal_point`. -decimal_point lconv.decimal_point [char*]\ndecimal point for non-monetary values -grouping lconv.grouping [char*]\nsizes of digit groups for non-monetary values -thousands_sep lconv.thousands_sep [char*]\nseparator for digit groups for non-monetary values (left of "decimal point") -currency_symbol lconv.currency_symbol [char*]\ncurrency symbol -int_curr_symbol lconv.int_curr_symbol [char*]\ninternational currency symbol -mon_decimal_point lconv.mon_decimal_point [char*]\ndecimal point for monetary values -mon_grouping lconv.mon_grouping [char*]\nsizes of digit groups for monetary values -mon_thousands_sep lconv.mon_thousands_sep [char*]\nseparator for digit groups for monetary values (left of "decimal point") -negative_sign lconv.negative_sign [char*]\nnegative sign for monetary values -positive_sign lconv.positive_sign [char*]\npositive sign for monetary values -frac_digits lconv.frac_digits [char]\nnumber of digits to be displayed to right of "decimal point" for monetary values -int_frac_digits lconv.int_frac_digits [char]\nnumber of digits to be displayed to right of "decimal point" for international\nmonetary values -n_cs_precedes lconv.n_cs_precedes [char]\nwhether currency symbol precedes (1) or follows (0) negative monetary values -n_sep_by_space lconv.n_sep_by_space [char]\nwhether currency symbol is (1) or is not (0) separated by space from negative\nmonetary values -n_sign_posn lconv.n_sign_posn [char]\nformat for negative monetary values:\n0: parentheses surround quantity and currency symbol\n 1: sign precedes quantity and currency symbol\n 2: sign follows quantity and currency symbol\n 3: sign immediately precedes currency symbol\n 4: sign immediately follows currency symbol -p_cs_precedes lconv.p_cs_precedes [char]\nwhether currency symbol precedes (1) or follows (0) positive monetary values -p_sep_by_space lconv.p_sep_by_space [char]\nwhether currency symbol is (1) or is not (0) separated by space from\nnon-negative monetary values -p_sign_posn lconv.p_sign_posn [char]\nformat for non-negative monetary values, with values as for n_sign_posn +lconv lconv [struct]\nDescribes formatting of monetary and other numeric values Implementations may change field\norder and include additional fields. Standard C Library functions use only `decimal_point`.\n +decimal_point lconv.decimal_point [char*]\ndecimal point for non-monetary values\n +grouping lconv.grouping [char*]\nsizes of digit groups for non-monetary values\n +thousands_sep lconv.thousands_sep [char*]\nseparator for digit groups for non-monetary values (left of "decimal point")\n +currency_symbol lconv.currency_symbol [char*]\ncurrency symbol\n +int_curr_symbol lconv.int_curr_symbol [char*]\ninternational currency symbol\n +mon_decimal_point lconv.mon_decimal_point [char*]\ndecimal point for monetary values\n +mon_grouping lconv.mon_grouping [char*]\nsizes of digit groups for monetary values\n +mon_thousands_sep lconv.mon_thousands_sep [char*]\nseparator for digit groups for monetary values (left of "decimal point")\n +negative_sign lconv.negative_sign [char*]\nnegative sign for monetary values\n +positive_sign lconv.positive_sign [char*]\npositive sign for monetary values\n +frac_digits lconv.frac_digits [char]\nnumber of digits to be displayed to right of "decimal point" for monetary values\n +int_frac_digits lconv.int_frac_digits [char]\nnumber of digits to be displayed to right of "decimal point" for international monetary values\n +n_cs_precedes lconv.n_cs_precedes [char]\nwhether currency symbol precedes (1) or follows (0) negative monetary values\n +n_sep_by_space lconv.n_sep_by_space [char]\nwhether currency symbol is (1) or is not (0) separated by space from negative monetary values\n +n_sign_posn lconv.n_sign_posn [char]\nformat for negative monetary values:\n\n * 0: parentheses surround quantity and currency symbol\n * 1: sign precedes quantity and currency symbol\n * 2: sign follows quantity and currency symbol\n * 3: sign immediately precedes currency symbol\n * 4: sign immediately follows currency symbol\n +p_cs_precedes lconv.p_cs_precedes [char]\nwhether currency symbol precedes (1) or follows (0) positive monetary values\n +p_sep_by_space lconv.p_sep_by_space [char]\nwhether currency symbol is (1) or is not (0) separated by space from non-negative monetary values\n +p_sign_posn lconv.p_sign_posn [char]\nformat for non-negative monetary values, with values as for n_sign_posn\n -localeconv localeconv(void) [lconv*]\nreturns pointer to formatting information for current locale -setlocale setlocale(int category, const char* locale) [char*]\nSets components of locale according to specified `category` and `locale`.\nReturns string describing new locale or null on error. (Implementations are\npermitted to define values of `category` additional to those describe here.) -LC_ALL LC_ALL\ncategory argument for all categories -LC_NUMERIC LC_NUMERIC\ncategory for numeric formatting information -LC_MONETARY LC_MONETARY\ncategory for monetary formatting information -LC_COLLATE LC_COLLATE\ncategory for information affecting collating functions -LC_CTYPE LC_CTYPE\ncategory for information affecting character class tests functions -LC_TIME LC_TIME\ncategory for information affecting time conversions functions -NULL NULL\nnull pointer constant +localeconv localeconv(void) [lconv*]\nreturns pointer to formatting information for current locale\n +setlocale setlocale(int category, const char* locale) [char*]\nSets components of locale according to specified `category` and `locale`. Returns string\ndescribing new locale or null on error. (Implementations are permitted to define values of\n`category` additional to those describe here.)\n +LC_ALL LC_ALL\ncategory argument for all categories\n +LC_NUMERIC LC_NUMERIC\ncategory for numeric formatting information\n +LC_MONETARY LC_MONETARY\ncategory for monetary formatting information\n +LC_COLLATE LC_COLLATE\ncategory for information affecting collating functions\n +LC_CTYPE LC_CTYPE\ncategory for information affecting character class tests functions\n +LC_TIME LC_TIME\ncategory for information affecting time conversions functions\n +NULL NULL\nnull pointer constant\n -HUGE_VAL HUGE_VAL\nmagnitude returned (with correct sign) on overflow error -exp exp(double x) [double]\nexponential of `x` -log log(double x) [double]\nnatural logarithm of `x` -log10 log10(double x) [double]\nbase-10 logarithm of `x` -pow pow(double x, double y) [double]\n`x` raised to power `y` -sqrt sqrt(double x) [double]\nsquare root of `x` -ceil ceil(double x) [double]\nsmallest integer not less than `x` -floor floor(double x) [double]\nlargest integer not greater than `x` -fabs fabs(double x) [double]\nabsolute value of `x` -ldexp ldexp(double x, int n) [double]\n`x` times 2 to the power `n` -frexp frexp(double x, int* exp) [double]\nif `x` non-zero, returns value, with absolute value in interval [1/2, 1), and\nassigns to `*exp` integer such that product of return value and 2 raised to the\npower `*exp` equals `x`; if `x` zero, both return value and `*exp` are zero -modf modf(double x, double* ip) [double]\nreturns fractional part and assigns to `*ip` integral part of `x`, both with\nsame sign as `x` -fmod fmod(double x, double y) [double]\nif `y` non-zero, floating-point remainder of `x`/`y`, with same sign as `x`; if\n`y` zero, result is implementation-defined -sin sin(double x) [double]\nsine of `x` -cos cos(double x) [double]\ncosine of `x` -tan tan(double x) [double]\ntangent of `x` -asin asin(double x) [double]\narc-sine of `x` -acos acos(double x) [double]\narc-cosine of `x` -atan atan(double x) [double]\narc-tangent of `x` -atan2 atan2(double y, double x) [double]\narc-tangent of `y`/`x` -sinh sinh(double x) [double]\nhyperbolic sine of `x` -cosh cosh(double x) [double]\nhyperbolic cosine of `x` -tanh tanh(double x) [double]\nhyperbolic tangent of `x` +HUGE_VAL HUGE_VAL\nmagnitude returned (with correct sign) on overflow error\n +exp exp(double x) [double]\nexponential of `x`\n +log log(double x) [double]\nnatural logarithm of `x`\n +log10 log10(double x) [double]\nbase-10 logarithm of `x`\n +pow pow(double x, double y) [double]\n`x` raised to power `y`\n +sqrt sqrt(double x) [double]\nsquare root of `x`\n +ceil ceil(double x) [double]\nsmallest integer not less than `x`\n +floor floor(double x) [double]\nlargest integer not greater than `x`\n +fabs fabs(double x) [double]\nabsolute value of `x`\n +ldexp ldexp(double x, int n) [double]\n`x` times 2 to the power `n`\n +frexp frexp(double x, int* exp) [double]\nif `x` non-zero, returns value, with absolute value in interval [1/2, 1), and assigns to `*exp`\ninteger such that product of return value and 2 raised to the power `*exp` equals `x`; if `x`\nzero, both return value and `*exp` are zero\n +modf modf(double x, double* ip) [double]\nreturns fractional part and assigns to `*ip` integral part of `x`, both with same sign as `x`\n +fmod fmod(double x, double y) [double]\nif `y` non-zero, floating-point remainder of `x`/`y`, with same sign as `x`; if `y` zero,\nresult is implementation-defined\n +sin sin(double x) [double]\nsine of `x`\n +cos cos(double x) [double]\ncosine of `x`\n +tan tan(double x) [double]\ntangent of `x`\n +asin asin(double x) [double]\narc-sine of `x`\n +acos acos(double x) [double]\narc-cosine of `x`\n +atan atan(double x) [double]\narc-tangent of `x`\n +atan2 atan2(double y, double x) [double]\narc-tangent of `y`/`x`\n +sinh sinh(double x) [double]\nhyperbolic sine of `x`\n +cosh cosh(double x) [double]\nhyperbolic cosine of `x`\n +tanh tanh(double x) [double]\nhyperbolic tangent of `x`\n -jmp_buf jmp_buf\ntype of object holding context information -setjmp setjmp(jmp_buf env) [int]\nSaves context information in `env` and returns zero. Subsequent call to longjmp\nwith same `env` returns non-zero. -longjmp longjmp(jmp_buf env, int val) [void]\nRestores context saved by most recent call to setjmp with specified `env`.\nExecution resumes as a second return from setjmp, with returned value `val` if\nspecified value non-zero, or 1 otherwise. +jmp_buf jmp_buf\ntype of object holding context information\n +setjmp setjmp(jmp_buf env) [int]\nSaves context information in `env` and returns zero. Subsequent call to longjmp with same `env`\nreturns non-zero.\n +longjmp longjmp(jmp_buf env, int val) [void]\nRestores context saved by most recent call to setjmp with specified `env`. Execution resumes as\na second return from setjmp, with returned value `val` if specified value non-zero, or 1 otherwise.\n -SIGABRT SIGABRT\nabnormal termination -SIGFPE SIGFPE\narithmetic error -SIGILL SIGILL\ninvalid execution -SIGINT SIGINT\n(asynchronous) interactive attention -SIGSEGV SIGSEGV\nillegal storage access -SIGTERM SIGTERM\n(asynchronous) termination request -SIG_DFL SIG_DFL\nspecifies default signal handling -SIG_ERR SIG_ERR\nsignal return value indicating error -SIG_IGN SIG_IGN\nspecifies that signal should be ignored -raise raise(int sig) [int]\nSends signal sig. Returns zero on success. +SIGABRT SIGABRT\nabnormal termination\n +SIGFPE SIGFPE\narithmetic error\n +SIGILL SIGILL\ninvalid execution\n +SIGINT SIGINT\n(asynchronous) interactive attention\n +SIGSEGV SIGSEGV\nillegal storage access\n +SIGTERM SIGTERM\n(asynchronous) termination request\n +SIG_DFL SIG_DFL\nspecifies default signal handling\n +SIG_ERR SIG_ERR\nsignal return value indicating error\n +SIG_IGN SIG_IGN\nspecifies that signal should be ignored\n +raise raise(int sig) [int]\nSends signal sig. Returns zero on success.\n -va_list va_list\ntype of object holding context information -va_start va_start(va_list ap, lastarg) [void]\nInitialisation macro which must be called once before any unnamed argument is\naccessed. Stores context information in `ap`. `lastarg` is the last named\nparameter of the function. -va_arg va_arg(va_list ap, type) [type]\nYields value of the type (`type`) and value of the next unnamed argument. -va_end va_end(va_list ap) [void]\nTermination macro which must be called once after argument processing and before\nexit from function. +va_list va_list\ntype of object holding context information\n +va_start va_start(va_list ap, lastarg) [void]\nInitialisation macro which must be called once before any unnamed argument is accessed. Stores\ncontext information in `ap`. `lastarg` is the last named parameter of the function.\n +va_arg va_arg(va_list ap, type) [type]\nYields value of the type (`type`) and value of the next unnamed argument.\n +va_end va_end(va_list ap) [void]\nTermination macro which must be called once after argument processing and before exit from\nfunction.\n -NULL NULL\nNull pointer constant. -offsetof offsetof(stype, m)\nOffset (in bytes) of member m from start of structure type `stype`. -ptrdiff_t ptrdiff_t\nType for objects declared to store result of subtracting pointers. -size_t size_t\nType for objects declared to store result of sizeof operator. +NULL NULL\nNull pointer constant.\n +offsetof offsetof(stype, m)\nOffset (in bytes) of member m from start of structure type `stype`.\n +ptrdiff_t ptrdiff_t\nType for objects declared to store result of subtracting pointers.\n +size_t size_t\nType for objects declared to store result of sizeof operator.\n -BUFSIZ BUFSIZ\nSize of buffer used by setbuf. -EOF EOF\nValue used to indicate end-of-stream or to report an error. -FILENAME_MAX FILENAME_MAX\nMaximum length required for array of characters to hold a filename. -FOPEN_MAX FOPEN_MAX\nMaximum number of files which may be open simultaneously. -L_tmpnam L_tmpnam\nNumber of characters required for temporary filename generated by tmpnam. -NULL NULL\nNull pointer constant. -SEEK_CUR SEEK_CUR\nValue for origin argument to fseek specifying current file position. -SEEK_END SEEK_END\nValue for origin argument to fseek specifying end of file. -SEEK_SET SEEK_SET\nValue for origin argument to fseek specifying beginning of file. -TMP_MAX TMP_MAX\nMinimum number of unique filenames generated by calls to tmpnam. -_IOFBF _IOFBF\nValue for mode argument to setvbuf specifying full buffering. -_IOLBF _IOLBF\nValue for mode argument to setvbuf specifying line buffering. -_IONBF _IONBF\nValue for mode argument to setvbuf specifying no buffering. -stdin stdin\nFile pointer for standard input stream. Automatically opened when program\nexecution begins. -stdout stdout\nFile pointer for standard output stream. Automatically opened when program\nexecution begins. -stderr stderr\nFile pointer for standard error stream. Automatically opened when program\nexecution begins. -FILE FILE\nType of object holding information necessary to control a stream. -fpos_t fpos_t\nType for objects declared to store file position information. -size_t size_t\nType for objects declared to store result of sizeof operator. -fopen fopen(const char* filename, const char* mode) [FILE*]\nOpens file named `filename` and returns a stream, or NULL on failure. `mode` may\nbe one of the following for text files:\n "r": text reading\n "w": text writing\n "a": text append\n "r+": text update (reading and writing)\n "w+": text update, discarding previous content (if any)\n "a+": text append, reading, and writing at end\nor one of those strings with b included (after the first character), for\nbinary files. -freopen freopen(const char* filename, const char* mode, FILE* stream) [FILE*]\nCloses file associated with `stream`, then opens file `filename` with specified\nmode and associates it with `stream`. Returns `stream` or NULL on error. -fflush fflush(FILE* stream) [int]\nFlushes stream `stream` and returns zero on success or EOF on error. Effect\nundefined for input stream. fflush(NULL) flushes all output streams. -fclose fclose(FILE* stream) [int]\nCloses stream `stream` (after flushing, if output stream). Returns EOF on error,\nzero otherwise. -remove remove(const char* filename) [int]\nRemoves specified file. Returns non-zero on failure. -rename rename(const char* oldname, const char* newname) [int]\nChanges name of file `oldname` to `newname`. Returns non-zero on failure. -tmpfile tmpfile() [FILE*]\nCreates temporary file (mode "wb+") which will be removed when closed or on\nnormal program termination. Returns stream or NULL on failure. -tmpnam tmpnam(char s[L_tmpnam]) [char*]\nAssigns to `s` (if `s` non-null) and returns unique name for a temporary file.\nUnique name is returned for each of the first TMP_MAX invocations. -setvbuf setvbuf(FILE* stream, char* buf, int mode, size_t size) [int]\nControls buffering for stream `stream`. mode is _IOFBF for full buffering,\n_IOLBF for line buffering, _IONBF for no buffering. Non-null `buf` specifies\nbuffer of size `size` to be used; otherwise, a buffer is allocated. Returns\nnon-zero on error. Call must be before any other operation on stream. -setbuf setbuf(FILE* stream, char* buf) [void]\nControls buffering for stream `stream`. For null `buf`, turns off buffering,\notherwise equivalent to `(void)setvbuf(stream, buf, _IOFBF, BUFSIZ)`. -fprintf fprintf(FILE* stream, const char* format, ...) [int]\nConverts (according to format `format`) and writes output to stream `stream`.\nNumber of characters written, or negative value on error, is returned.\nConversion specifications consist of:\n * %\n * (optional) flag:\n -: left adjust\n +: always sign\n space: space if no sign\n 0: zero pad\n #: Alternate form: for conversion character o, first digit will be zero, for\n [xX], prefix 0x or 0X to non-zero value, for [eEfgG], always decimal\n point, for [gG] trailing zeros not removed.\n * (optional) minimum width: if specified as *, value taken from next argument\n (which must be int).\n * (optional) . (separating width from precision):\n * (optional) precision: for conversion character s, maximum characters to be\n printed from the string, for [eEf], digits after decimal point, for [gG],\n significant digits, for an integer, minimum number of digits to be printed.\n If specified as *, value taken from next argument (which must be int).\n * (optional) length modifier:\n h: short or unsigned short\n l: long or unsigned long\n L: long double\n * conversion character:\n d,i: int argument, printed in signed decimal notation\n o: int argument, printed in unsigned octal notation\n x,X: int argument, printed in unsigned hexadecimal notation\n u: int argument, printed in unsigned decimal notation\n c: int argument, printed as single character\n s: char* argument\n f: double argument, printed with format [-]mmm.ddd\n e,E: double argument, printed with format [-]m.dddddd(e|E)(+|-)xx\n g,G: double argument\n p: void* argument, printed as pointer\n n: int* argument : the number of characters written to this point is written\n into argument\n %: no argument; prints % -printf printf(const char* format, ...) [int]\nprintf(f, ...) is equivalent to fprintf(stdout, f, ...) -sprintf sprintf(char* s, const char* format, ...) [int]\nLike fprintf, but output written into string `s`, which *must be large enough to\nhold the output*, rather than to a stream. Output is NUL-terminated. Returns\nlength (excluding the terminating NUL). -vfprintf vfprintf(FILE* stream, const char* format, va_list arg) [int]\nEquivalent to fprintf with variable argument list replaced by `arg`, which must\nhave been initialised by the va_start macro (and may have been used in calls to\nva_arg). -vprintf vprintf(const char* format, va_list arg) [int]\nEquivalent to printf with variable argument list replaced by `arg`, which must\nhave been initialised by the va_start macro (and may have been used in calls to\nva_arg). -vsprintf vsprintf(char* s, const char* format, va_list arg) [int]\nEquivalent to sprintf with variable argument list replaced by `arg`, which must\nhave been initialised by the va_start macro (and may have been used in calls to\nva_arg). -fscanf fscanf(FILE* stream, const char* format, ...) [int]\nPerforms formatted input conversion, reading from stream `stream` according to\nformat `format`. The function returns when `format` is fully processed. Returns\nnumber of items converted and assigned, or EOF if end-of-file or error occurs\nbefore any conversion. Each of the arguments following format *must be a\npointer*. Format string may contain:\n * blanks and tabs, which are ignored\n * ordinary characters, which are expected to match next non-white-space of\n input\n * conversion specifications, consisting of:\n * %\n * (optional) assignment suppression character "*"\n * (optional) maximum field width\n * (optional) target width indicator:\n h: argument is pointer to short rather than int\n l: argument is pointer to long rather than int, or double rather than\n float\n L: argument is pointer to long double rather than float\n * conversion character:\n d: decimal integer; int* parameter required\n i: integer; int* parameter required; decimal, octal or hex\n o: octal integer; int* parameter required\n u: unsigned decimal integer; unsigned int* parameter required\n x: hexadecimal integer; int* parameter required\n c: characters; char* parameter required; white-space is not skipped, and\n NUL-termination is not performed\n s: string of non-white-space; char* parameter required; string is\n NUL-terminated\n e,f,g: floating-point number; float* parameter required\n p: pointer value; void* parameter required\n n: chars read so far; int* parameter required\n [...]: longest non-empty string from specified set; char* parameter\n required; string is NUL-terminated\n [^...]: longest non-empty string not from specified set; char* parameter\n required; string is NUL-terminated\n %: literal %; no assignment -scanf scanf(const char* format, ...) [int]\nscanf(f, ...) is equivalent to fscanf(stdin, f, ...) -sscanf sscanf(char* s, const char* format, ...) [int]\nLike fscanf, but input read from string `s`. -fgetc fgetc(FILE* stream) [int]\nReturns next character from (input) stream `stream`, or EOF on end-of-file or\nerror. -fgets fgets(char* s, int n, FILE* stream) [char*]\nCopies characters from (input) stream `stream` to `s`, stopping when `n`-1\ncharacters copied, newline copied, end-of-file reached or error occurs. If no\nerror, `s` is NUL-terminated. Returns NULL on end-of-file or error, `s`\notherwise. -fputc fputc(int c, FILE* stream) [int]\nWrites `c`, to stream `stream`. Returns `c`, or EOF on error. -fputs fputs(const char* s, FILE* stream) [char*]\nWrites `s`, to (output) stream `stream`. Returns non-negative on success or EOF\non error. -getc getc(FILE* stream) [int]\nEquivalent to fgetc except that it may be a macro. -getchar getchar(void) [int]\nEquivalent to getc(stdin). -gets gets(char* s) [char*]\nCopies characters from stdin into `s` until newline encountered, end-of-file\nreached, or error occurs. Does not copy newline. NUL-terminates `s`. Returns\n`s`, or NULL on end-of-file or error. *Should not be used because of the\npotential for buffer overflow.* -putc putc(int c, FILE* stream) [int]\nEquivalent to fputc except that it may be a macro. -putchar putchar(int c) [int]\nputchar(c) is equivalent to putc(c, stdout). -puts puts(const char* s) [int]\nWrites `s` (excluding terminating NUL) and a newline to stdout. Returns\nnon-negative on success, EOF on error. -ungetc ungetc(int c, FILE* stream) [int]\nPushes `c` (which must not be EOF), onto (input) stream `stream` such that it\nwill be returned by the next read. Only one character of pushback is guaranteed\n(for each stream). Returns `c`, or EOF on error. -fread fread(void* ptr, size_t size, size_t nobj, FILE* stream) [size_t]\nReads (at most) `nobj` objects of size `size` from stream `stream` into `ptr`\nand returns number of objects read. (feof and ferror can be used to check\nstatus.) -fwrite fwrite(const void* ptr, size_t size, size_t nobj, FILE* stream) [size_t]\nWrites to stream `stream`, `nobj` objects of size `size` from array `ptr`.\nReturns number of objects written. -fseek fseek(FILE* stream, long offset, int origin) [int]\nSets file position for stream `stream` and clears end-of-file indicator. For a\nbinary stream, file position is set to `offset` bytes from the position\nindicated by `origin`: beginning of file for SEEK_SET, current position for\nSEEK_CUR, or end of file for SEEK_END. Behaviour is similar for a text stream,\nbut `offset` must be zero or, for SEEK_SET only, a value returned by ftell.\nReturns non-zero on error. -ftell ftell(FILE* stream) [long]\nReturns current file position for stream `stream`, or -1 on error. -rewind rewind(FILE* stream) [void]\nEquivalent to fseek(stream, 0L, SEEK_SET); clearerr(stream). -fgetpos fgetpos(FILE* stream, fpos_t* ptr) [int]\nStores current file position for stream `stream` in `*ptr`. Returns non-zero on\nerror. -fsetpos fsetpos(FILE* stream, const fpos_t* ptr) [int]\nSets current position of stream `stream` to `*ptr`. Returns non-zero on error. -clearerr clearerr(FILE* stream) [void]\nClears end-of-file and error indicators for stream `stream`. -feof feof(FILE* stream) [int]\nReturns non-zero if end-of-file indicator is set for stream `stream`. -ferror ferror(FILE* stream) [int]\nReturns non-zero if error indicator is set for stream `stream`. -perror perror(const char* s) [void]\nPrints `s` (if non-null) and strerror(errno) to standard error as would:\n fprintf(stderr, "%s: %s\\n", (s != NULL ? s : ""), strerror(errno)) +BUFSIZ BUFSIZ\nSize of buffer used by setbuf.\n +EOF EOF\nValue used to indicate end-of-stream or to report an error.\n +FILENAME_MAX FILENAME_MAX\nMaximum length required for array of characters to hold a filename.\n +FOPEN_MAX FOPEN_MAX\nMaximum number of files which may be open simultaneously.\n +L_tmpnam L_tmpnam\nNumber of characters required for temporary filename generated by tmpnam.\n +NULL NULL\nNull pointer constant.\n +SEEK_CUR SEEK_CUR\nValue for origin argument to fseek specifying current file position.\n +SEEK_END SEEK_END\nValue for origin argument to fseek specifying end of file.\n +SEEK_SET SEEK_SET\nValue for origin argument to fseek specifying beginning of file.\n +TMP_MAX TMP_MAX\nMinimum number of unique filenames generated by calls to tmpnam.\n +_IOFBF _IOFBF\nValue for mode argument to setvbuf specifying full buffering.\n +_IOLBF _IOLBF\nValue for mode argument to setvbuf specifying line buffering.\n +_IONBF _IONBF\nValue for mode argument to setvbuf specifying no buffering.\n +stdin stdin\nFile pointer for standard input stream. Automatically opened when program execution begins.\n +stdout stdout\nFile pointer for standard output stream. Automatically opened when program execution begins.\n +stderr stderr\nFile pointer for standard error stream. Automatically opened when program execution begins.\n +FILE FILE\nType of object holding information necessary to control a stream.\n +fpos_t fpos_t\nType for objects declared to store file position information.\n +size_t size_t\nType for objects declared to store result of sizeof operator.\n +fopen fopen(const char* filename, const char* mode) [FILE*]\nOpens file named `filename` and returns a stream, or NULL on failure. `mode` may be one of the\nfollowing for text files:\n\n * "r": text reading\n * "w": text writing\n * "a": text append\n * "r+": text update (reading and writing)\n * "w+": text update, discarding previous content (if any)\n * "a+": text append, reading, and writing at end\n \nor one of those strings with b included (after the first character), for binary files.\n +freopen freopen(const char* filename, const char* mode, FILE* stream) [FILE*]\nCloses file associated with `stream`, then opens file `filename` with specified mode and\nassociates it with `stream`. Returns `stream` or NULL on error.\n +fflush fflush(FILE* stream) [int]\nFlushes stream `stream` and returns zero on success or EOF on error. Effect undefined for input\nstream. fflush(NULL) flushes all output streams.\n +fclose fclose(FILE* stream) [int]\nCloses stream `stream` (after flushing, if output stream). Returns EOF on error, zero otherwise.\n +remove remove(const char* filename) [int]\nRemoves specified file. Returns non-zero on failure.\n +rename rename(const char* oldname, const char* newname) [int]\nChanges name of file `oldname` to `newname`. Returns non-zero on failure.\n +tmpfile tmpfile() [FILE*]\nCreates temporary file (mode "wb+") which will be removed when closed or on normal program\ntermination. Returns stream or NULL on failure.\n +tmpnam tmpnam(char s[L_tmpnam]) [char*]\nAssigns to `s` (if `s` non-null) and returns unique name for a temporary file. Unique name is\nreturned for each of the first TMP_MAX invocations.\n +setvbuf setvbuf(FILE* stream, char* buf, int mode, size_t size) [int]\nControls buffering for stream `stream`. mode is _IOFBF for full buffering, _IOLBF for line\nbuffering, _IONBF for no buffering. Non-null `buf` specifies buffer of size `size` to be used;\notherwise, a buffer is allocated. Returns non-zero on error. Call must be before any other\noperation on stream.\n +setbuf setbuf(FILE* stream, char* buf) [void]\nControls buffering for stream `stream`. For null `buf`, turns off buffering, otherwise equivalent\nto `(void)setvbuf(stream, buf, _IOFBF, BUFSIZ)`.\n +fprintf fprintf(FILE* stream, const char* format, ...) [int]\nConverts (according to format `format`) and writes output to stream `stream`. Number of\ncharacters written, or negative value on error, is returned. Conversion specifications consist of:\n\n * %\n * (optional) flag:\n -: left adjust\n +: always sign\n space: space if no sign\n 0: zero pad\n #: Alternate form: for conversion character o, first digit will be zero, for [xX], prefix 0x or\n 0X to non-zero value, for [eEfgG], always decimal point, for [gG] trailing zeros not removed.\n * (optional) minimum width: if specified as *, value taken from next argument (which must\n be int).\n * (optional) . (separating width from precision):\n * (optional) precision: for conversion character s, maximum characters to be printed from the\n string, for [eEf], digits after decimal point, for [gG], significant digits, for an integer,\n minimum number of digits to be printed. If specified as *, value taken from next argument\n (which must be int).\n * (optional) length modifier:\n h: short or unsigned short\n l: long or unsigned long\n L: long double\n * conversion character:\n d,i: int argument, printed in signed decimal notation\n o: int argument, printed in unsigned octal notation\n x,X: int argument, printed in unsigned hexadecimal notation\n u: int argument, printed in unsigned decimal notation\n c: int argument, printed as single character\n s: char* argument\n f: double argument, printed with format [-]mmm.ddd\n e,E: double argument, printed with format [-]m.dddddd(e|E)(+|-)xx\n g,G: double argument\n p: void* argument, printed as pointer\n n: int* argument : the number of characters written to this point is written into argument\n %: no argument; prints %\n +printf printf(const char* format, ...) [int]\nprintf(f, ...) is equivalent to fprintf(stdout, f, ...)\n +sprintf sprintf(char* s, const char* format, ...) [int]\nLike fprintf, but output written into string `s`, which *must be large enough to hold the output*,\nrather than to a stream. Output is NUL-terminated. Returns length (excluding the terminating NUL).\n +vfprintf vfprintf(FILE* stream, const char* format, va_list arg) [int]\nEquivalent to fprintf with variable argument list replaced by `arg`, which must have been\ninitialised by the va_start macro (and may have been used in calls to va_arg).\n +vprintf vprintf(const char* format, va_list arg) [int]\nEquivalent to printf with variable argument list replaced by `arg`, which must have been\ninitialised by the va_start macro (and may have been used in calls to va_arg).\n +vsprintf vsprintf(char* s, const char* format, va_list arg) [int]\nEquivalent to sprintf with variable argument list replaced by `arg`, which must have been\ninitialised by the va_start macro (and may have been used in calls to va_arg).\n +fscanf fscanf(FILE* stream, const char* format, ...) [int]\nPerforms formatted input conversion, reading from stream `stream` according to format `format`. The\nfunction returns when `format` is fully processed. Returns number of items converted and assigned,\nor EOF if end-of-file or error occurs before any conversion. Each of the arguments following\nformat *must be a pointer*. Format string may contain:\n\n * blanks and tabs, which are ignored\n * ordinary characters, which are expected to match next non-white-space of input\n * conversion specifications, consisting of:\n * %\n * (optional) assignment suppression character "*"\n * (optional) maximum field width\n * (optional) target width indicator:\n h: argument is pointer to short rather than int\n l: argument is pointer to long rather than int, or double rather than float\n L: argument is pointer to long double rather than float\n * conversion character:\n d: decimal integer; int* parameter required\n i: integer; int* parameter required; decimal, octal or hex\n o: octal integer; int* parameter required\n u: unsigned decimal integer; unsigned int* parameter required\n x: hexadecimal integer; int* parameter required\n c: characters; char* parameter required; white-space is not skipped, and NUL-termination is\n not performed\n s: string of non-white-space; char* parameter required; string is NUL-terminated\n e,f,g: floating-point number; float* parameter required\n p: pointer value; void* parameter required\n n: chars read so far; int* parameter required\n [...]: longest non-empty string from specified set; char* parameter required; string is\n NUL-terminated\n [^...]: longest non-empty string not from specified set; char* parameter required; string is\n NUL-terminated\n %: literal %; no assignment\n +scanf scanf(const char* format, ...) [int]\nscanf(f, ...) is equivalent to fscanf(stdin, f, ...)\n +sscanf sscanf(char* s, const char* format, ...) [int]\nLike fscanf, but input read from string `s`.\n +fgetc fgetc(FILE* stream) [int]\nReturns next character from (input) stream `stream`, or EOF on end-of-file or error.\n +fgets fgets(char* s, int n, FILE* stream) [char*]\nCopies characters from (input) stream `stream` to `s`, stopping when `n`-1 characters copied,\nnewline copied, end-of-file reached or error occurs. If no error, `s` is NUL-terminated. Returns\nNULL on end-of-file or error, `s` otherwise.\n +fputc fputc(int c, FILE* stream) [int]\nWrites `c`, to stream `stream`. Returns `c`, or EOF on error.\n +fputs fputs(const char* s, FILE* stream) [char*]\nWrites `s`, to (output) stream `stream`. Returns non-negative on success or EOF on error.\n +getc getc(FILE* stream) [int]\nEquivalent to fgetc except that it may be a macro.\n +getchar getchar(void) [int]\nEquivalent to getc(stdin).\n +gets gets(char* s) [char*]\nCopies characters from stdin into `s` until newline encountered, end-of-file reached, or error\noccurs. Does not copy newline. NUL-terminates `s`. Returns `s`, or NULL on end-of-file or\nerror. *Should not be used because of the potential for buffer overflow.*\n +putc putc(int c, FILE* stream) [int]\nEquivalent to fputc except that it may be a macro.\n +putchar putchar(int c) [int]\nputchar(c) is equivalent to putc(c, stdout).\n +puts puts(const char* s) [int]\nWrites `s` (excluding terminating NUL) and a newline to stdout. Returns non-negative on success,\nEOF on error.\n +ungetc ungetc(int c, FILE* stream) [int]\nPushes `c` (which must not be EOF), onto (input) stream `stream` such that it will be returned\nby the next read. Only one character of pushback is guaranteed (for each stream). Returns `c`,\nor EOF on error.\n +fread fread(void* ptr, size_t size, size_t nobj, FILE* stream) [size_t]\nReads (at most) `nobj` objects of size `size` from stream `stream` into `ptr` and returns number\nof objects read. (feof and ferror can be used to check status.)\n +fwrite fwrite(const void* ptr, size_t size, size_t nobj, FILE* stream) [size_t]\nWrites to stream `stream`, `nobj` objects of size `size` from array `ptr`. Returns number of\nobjects written.\n +fseek fseek(FILE* stream, long offset, int origin) [int]\nSets file position for stream `stream` and clears end-of-file indicator. For a binary stream,\nfile position is set to `offset` bytes from the position indicated by `origin`: beginning of file\nfor SEEK_SET, current position for SEEK_CUR, or end of file for SEEK_END. Behaviour is similar\nfor a text stream, but `offset` must be zero or, for SEEK_SET only, a value returned by ftell.\nReturns non-zero on error.\n +ftell ftell(FILE* stream) [long]\nReturns current file position for stream `stream`, or -1 on error.\n +rewind rewind(FILE* stream) [void]\nEquivalent to fseek(stream, 0L, SEEK_SET); clearerr(stream).\n +fgetpos fgetpos(FILE* stream, fpos_t* ptr) [int]\nStores current file position for stream `stream` in `*ptr`. Returns non-zero on error.\n +fsetpos fsetpos(FILE* stream, const fpos_t* ptr) [int]\nSets current position of stream `stream` to `*ptr`. Returns non-zero on error.\n +clearerr clearerr(FILE* stream) [void]\nClears end-of-file and error indicators for stream `stream`.\n +feof feof(FILE* stream) [int]\nReturns non-zero if end-of-file indicator is set for stream `stream`.\n +ferror ferror(FILE* stream) [int]\nReturns non-zero if error indicator is set for stream `stream`.\n +perror perror(const char* s) [void]\nPrints `s` (if non-null) and strerror(errno) to standard error as would:\n\n fprintf(stderr, "%s: %s\n", (s != NULL ? s : ""), strerror(errno))\n -EXIT_FAILURE EXIT_FAILURE\nValue for status argument to exit indicating failure. -EXIT_SUCCESS EXIT_SUCCESS\nValue for status argument to exit indicating success. -RAND_MAX RAND_MAX\nMaximum value returned by rand(). -NULL NULL\nNull pointer constant. -div_t div_t\nReturn type of div(). -quot div_t.quot [int]\nquotient -rem div_t.rem [int]\nremainder -ldiv_t ldiv_t\nReturn type of ldiv(). -qout ldiv_t.quot [long]\nquotient -rem ldiv_t.rem [long]\nremainder -size_t size_t\nType for objects declared to store result of sizeof operator. -abs abs(int n) [int] -labs labs(long n) [long]\nReturns absolute value of `n`. -div div(int num, int denom) [div_t] -ldiv ldiv(long num, long denom) [ldiv_t]\nReturns quotient and remainder of `num`/`denom`. -atof atof(const char* s) [double]\nEquivalent to strtod(s, (char**)NULL) except that errno is not necessarily set\non conversion error. -atoi atoi(const char* s) [int]\nEquivalent to (int)strtol(s, (char**)NULL, 10) except that errno is not\nnecessarily set on conversion error. -atol atol(const char* s) [long]\nEquivalent to strtol(s, (char**)NULL, 10) except that errno is not necessarily\nset on conversion error. -strtod strtod(const char* s, char** endp) [double]\nConverts initial characters (ignoring leading white space) of `s` to type\ndouble. If `endp` non-null, stores pointer to unconverted suffix in `*endp`. On\noverflow, sets errno to ERANGE and returns HUGE_VAL with the appropriate sign;\non underflow, sets errno to ERANGE and returns zero; otherwise returns converted\nvalue. -strtol strtol(const char* s, char** endp, int base) [long]\nConverts initial characters (ignoring leading white space) of `s` to type long.\nIf `endp` non-null, stores pointer to unconverted suffix in `*endp`. If base\nbetween 2 and 36, that base used for conversion; if zero, leading (after any\nsign) 0X or 0x implies hexadecimal, leading 0 (after any sign) implies octal,\notherwise decimal assumed. Leading 0X or 0x permitted for base hexadecimal. On\noverflow, sets errno to ERANGE and returns LONG_MAX or LONG_MIN (as appropriate\nfor sign); otherwise returns converted value. -strtoul strtoul(const char* s, char** endp, int base) [unsigned long]\nAs for strtol except result is unsigned long and value on overflow is ULONG_MAX. -calloc calloc(size_t nobj, size_t size) [void*]\nReturns pointer to _zero-initialised_ newly-allocated space for an array of\n`nobj` objects each of size `size`, or NULL on error. -malloc malloc(size_t size) [void*]\nReturns pointer to _uninitialised_ newly-allocated space for an object of size\n`size`, or NULL on error. -realloc realloc(void* p, size_t size) [void*]\nReturns pointer to newly-allocated space for an object of size `size`,\ninitialised, to minimum of old and new sizes, to existing contents of `p` (if\nnon-null), or NULL on error. On success, old object deallocated, otherwise\nunchanged. -free free(void* p) [void]\nIf `p` non-null, deallocates space to which it points. -abort abort() [void]\nTerminates program abnormally, by calling raise(SIGABRT). -exit exit(int status) [void]\nTerminates program normally. Functions installed using atexit are called (in\nreverse order to that in which installed), open files are flushed, open streams\nare closed and control is returned to environment. `status` is returned to\nenvironment in implementation-dependent manner. Zero or EXIT_SUCCESS indicates\nsuccessful termination and EXIT_FAILURE indicates unsuccessful termination.\nImplementations may define other values. -atexit atexit(void (*fcm)(void)) [int]\nRegisters `fcn` to be called when program terminates normally (or when main\nreturns). Returns non-zero on failure. -system system(const char* s) [int]\nIf `s` is not NULL, passes `s` to environment for execution, and returns \nreported by command processor; if `s` is NULL, non-zero returned if environment\nhas a command processor. -getenv getenv(const char* name) [char*]\nReturns string associated with name `name` from implementation's environment, or\nNULL if no such string exists. -bsearch bsearch(const void* key, const void* base, size_t n, size_t size, int (*cmp)(const void* keyval, const void* datum)) [void*]\nSearches ordered array `base` (of `n` objects each of size `size`) for item\nmatching key according to comparison function `cmp`. `cmp` must return negative\nvalue if first argument is less than second, zero if equal and positive if\ngreater. Items of `base` are assumed to be in ascending order (according to\n`cmp`). Returns a pointer to an item matching `key`, or NULL if none found. -qsort qsort(void* base, size_t n, size_t size, int (*cmp)(const void*, const void*)) [void]\nArranges into ascending order array `base` (of `n` objects each of size `size`)\naccording to comparison function `cmp`. `cmp` must return negative value if\nfirst argument is less than second, zero if equal and positive if greater. -rand rand(void) [int]\nReturns pseudo-random number in range 0 to RAND_MAX. -srand srand(unsigned int seed) [void]\nUses seed as seed for new sequence of pseudo-random numbers. Initial seed is 1. +EXIT_FAILURE EXIT_FAILURE\nValue for status argument to exit indicating failure.\n +EXIT_SUCCESS EXIT_SUCCESS\nValue for status argument to exit indicating success.\n +RAND_MAX RAND_MAX\nMaximum value returned by rand().\n +NULL NULL\nNull pointer constant.\n +div_t div_t\nReturn type of div().\n +quot div_t.quot [int]\nquotient\n +rem div_t.rem [int]\nremainder\n +ldiv_t ldiv_t\nReturn type of ldiv().\n +qout ldiv_t.quot [long]\nquotient\n +rem ldiv_t.rem [long]\nremainder\n +size_t size_t\nType for objects declared to store result of sizeof operator.\n +abs abs(int n) [int]\n +labs labs(long n) [long]\nReturns absolute value of `n`.\n +div div(int num, int denom) [div_t]\n +ldiv ldiv(long num, long denom) [ldiv_t]\nReturns quotient and remainder of `num`/`denom`.\n +atof atof(const char* s) [double]\nEquivalent to strtod(s, (char**)NULL) except that errno is not necessarily set on conversion error.\n +atoi atoi(const char* s) [int]\nEquivalent to (int)strtol(s, (char**)NULL, 10) except that errno is not necessarily set on\nconversion error.\n +atol atol(const char* s) [long]\nEquivalent to strtol(s, (char**)NULL, 10) except that errno is not necessarily set on conversion\nerror.\n +strtod strtod(const char* s, char** endp) [double]\nConverts initial characters (ignoring leading white space) of `s` to type double. If `endp`\nnon-null, stores pointer to unconverted suffix in `*endp`. On overflow, sets errno to ERANGE and\nreturns HUGE_VAL with the appropriate sign; on underflow, sets errno to ERANGE and returns zero;\notherwise returns converted value.\n +strtol strtol(const char* s, char** endp, int base) [long]\nConverts initial characters (ignoring leading white space) of `s` to type long. If `endp`\nnon-null, stores pointer to unconverted suffix in `*endp`. If base between 2 and 36, that base\nused for conversion; if zero, leading (after any sign) 0X or 0x implies hexadecimal, leading 0\n(after any sign) implies octal, otherwise decimal assumed. Leading 0X or 0x permitted for base\nhexadecimal. On overflow, sets errno to ERANGE and returns LONG_MAX or LONG_MIN (as appropriate\nfor sign); otherwise returns converted value.\n +strtoul strtoul(const char* s, char** endp, int base) [unsigned long]\nAs for strtol except result is unsigned long and value on overflow is ULONG_MAX.\n +calloc calloc(size_t nobj, size_t size) [void*]\nReturns pointer to _zero-initialised_ newly-allocated space for an array of `nobj` objects each\nof size `size`, or NULL on error.\n +malloc malloc(size_t size) [void*]\nReturns pointer to _uninitialised_ newly-allocated space for an object of size `size`, or NULL\non error.\n +realloc realloc(void* p, size_t size) [void*]\nReturns pointer to newly-allocated space for an object of size `size`, initialised, to minimum\nof old and new sizes, to existing contents of `p` (if non-null), or NULL on error. On success,\nold object deallocated, otherwise unchanged.\n +free free(void* p) [void]\nIf `p` non-null, deallocates space to which it points.\n +abort abort() [void]\nTerminates program abnormally, by calling raise(SIGABRT).\n +exit exit(int status) [void]\nTerminates program normally. Functions installed using atexit are called (in reverse order to\nthat in which installed), open files are flushed, open streams are closed and control is returned\nto environment. `status` is returned to environment in implementation-dependent manner. Zero or\nEXIT_SUCCESS indicates successful termination and EXIT_FAILURE indicates unsuccessful termination.\nImplementations may define other values.\n +atexit atexit(void (*fcm)(void)) [int]\nRegisters `fcn` to be called when program terminates normally (or when main returns). Returns\nnon-zero on failure.\n +system system(const char* s) [int]\nIf `s` is not NULL, passes `s` to environment for execution, and returns reported by command\nprocessor; if `s` is NULL, non-zero returned if environment has a command processor.\n +getenv getenv(const char* name) [char*]\nReturns string associated with name `name` from implementation's environment, or NULL if no\nsuch string exists.\n +bsearch bsearch(const void* key, const void* base, size_t n, size_t size, int (*cmp)(const void* keyval, const void* datum)) [void*]\nSearches ordered array `base` (of `n` objects each of size `size`) for item matching key according\nto comparison function `cmp`. `cmp` must return negative value if first argument is less than\nsecond, zero if equal and positive if greater. Items of `base` are assumed to be in ascending\norder (according to `cmp`). Returns a pointer to an item matching `key`, or NULL if none found.\n +qsort qsort(void* base, size_t n, size_t size, int (*cmp)(const void*, const void*)) [void]\nArranges into ascending order array `base` (of `n` objects each of size `size`) according to\ncomparison function `cmp`. `cmp` must return negative value if first argument is less than\nsecond, zero if equal and positive if greater.\n +rand rand(void) [int]\nReturns pseudo-random number in range 0 to RAND_MAX.\n +srand srand(unsigned int seed) [void]\nUses seed as seed for new sequence of pseudo-random numbers. Initial seed is 1.\n -NULL NULL\nNull pointer constant. -size_t size_t\nType for objects declared to store result of sizeof operator. -strcpy strcpy(char* s, const char* ct) [char*]\nCopies `ct` to `s` including terminating NUL and returns `s`. -strncpy strncpy(char* s, const char* ct, size_t n) [char*]\nCopies at most `n` characters of `ct` to `s`. Pads with NUL characters if `ct`\nis of length less than `n`. *Note that this may leave `s` without\nNUL-termination.* Return `s`. -strcat strcat(char* s, const char* ct) [char*]\nConcatenate `ct` to `s` and return `s`. -strncat strncat(char* s, const char* ct, size_t n) [char*]\nConcatenate at most `n` characters of `ct` to `s`. NUL-terminates `s` and return it. -strcmp strcmp(const char* cs, const char* ct) [int]\nCompares `cs` with `ct`, returning negative value if `cs`<`ct`, zero if\n`cs`==`ct`, positive value if `cs`>`ct`. -strncmp strncmp(const char* cs, const char* ct, size_t n) [int]\nCompares at most (the first) `n` characters of `cs` and `ct`, returning negative\nvalue if `cs`<`ct`, zero if `cs`==`ct`, positive value if `cs`>`ct`. -strcoll strcoll(const char* cs, const char* ct) [int]\nCompares `cs` with `ct` according to locale, returning negative value if\n`cs`<`ct`, zero if `cs`==`ct`, positive value if `cs`>`ct`. -strchr strchr(const char* cs, int c) [char*]\nReturns pointer to first occurrence of `c` in `cs`, or NULL if not found. -strrchr strrchr(const char* cs, int c) [char*]\nReturns pointer to last occurrence of `c` in `cs`, or NULL if not found. -strspn strspn(const char* cs, const char* ct) [size_t]\nReturns length of prefix of `cs` which consists of characters which are in `ct`. -strcspn strcspn(const char* cs, const char* ct) [size_t]\nReturns length of prefix of `cs` which consists of characters which are not in\n`ct`. -strpbrk strpbrk(const char* cs, const char* ct) [char*]\nReturns pointer to first occurrence in `cs` of any character of `ct`, or NULL if\nnone is found. -strstr strstr(const char* cs, const char* ct) [char*]\nReturns pointer to first occurrence of `ct` within `cs`, or NULL if none is\nfound. -strlen strlen(const char* cs) [size_t]\nReturns length of `cs`. -strerror strerror(int n) [char*]\nReturns pointer to implementation-defined message string corresponding with\nerror `n`. -strtok strtok(char* s, const char* t) [char*]\nSearches `s` for next token delimited by any character from `ct`. Non-NULL `s`\nindicates the first call of a sequence. If a token is found, it is\nNUL-terminated and returned, otherwise NULL is returned. `ct` need not be\nidentical for each call in a sequence. -strxfrm strxfrm(char* s, const char* ct, size_t n) [size_t]\nStores in `s` no more than `n` characters (including terminating NUL) of a\nstring produced from `ct` according to a locale-specific transformation. Returns\nlength of entire transformed string. -memcpy memcpy(void* s, const void* ct, size_t n) [void*]\nCopies `n` characters from `ct` to `s` and returns `s`. *`s` may be corrupted if\nobjects overlap.* -memmove memmove(void* s, const void* ct, size_t n) [void*]\nCopies `n` characters from `ct` to `s` and returns `s`. *`s` will not be\ncorrupted if objects overlap.* -memcmp memcmp(const void* cs, const void* ct, size_t n) [int]\nCompares at most (the first) `n` characters of `cs` and `ct`, returning negative\nvalue if `cs`<`ct`, zero if `cs`==`ct`, positive value if `cs`>`ct`. -memchr memchr(const void* cs, int c, size_t n) [void*]\nReturns pointer to first occurrence of `c` in first `n` characters of `cs`, or\nNULL if not found. -memset memset(void* s, int c, size_t n) [void*]\nReplaces each of the first `n` characters of `s` by `c` and returns `s`. +NULL NULL\nNull pointer constant.\n +size_t size_t\nType for objects declared to store result of sizeof operator.\n +strcpy strcpy(char* s, const char* ct) [char*]\nCopies `ct` to `s` including terminating NUL and returns `s`.\n +strncpy strncpy(char* s, const char* ct, size_t n) [char*]\nCopies at most `n` characters of `ct` to `s`. Pads with NUL characters if `ct` is of length\nless than `n`. *Note that this may leave `s` without NUL-termination.* Return `s`.\n +strcat strcat(char* s, const char* ct) [char*]\nConcatenate `ct` to `s` and return `s`.\n +strncat strncat(char* s, const char* ct, size_t n) [char*]\nConcatenate at most `n` characters of `ct` to `s`. NUL-terminates `s` and return it.\n +strcmp strcmp(const char* cs, const char* ct) [int]\nCompares `cs` with `ct`, returning negative value if `cs`<`ct`, zero if `cs`==`ct`, positive\nvalue if `cs`>`ct`.\n +strncmp strncmp(const char* cs, const char* ct, size_t n) [int]\nCompares at most (the first) `n` characters of `cs` and `ct`, returning negative value if\n`cs`<`ct`, zero if `cs`==`ct`, positive value if `cs`>`ct`.\n +strcoll strcoll(const char* cs, const char* ct) [int]\nCompares `cs` with `ct` according to locale, returning negative value if `cs`<`ct`, zero if\n`cs`==`ct`, positive value if `cs`>`ct`.\n +strchr strchr(const char* cs, int c) [char*]\nReturns pointer to first occurrence of `c` in `cs`, or NULL if not found.\n +strrchr strrchr(const char* cs, int c) [char*]\nReturns pointer to last occurrence of `c` in `cs`, or NULL if not found.\n +strspn strspn(const char* cs, const char* ct) [size_t]\nReturns length of prefix of `cs` which consists of characters which are in `ct`.\n +strcspn strcspn(const char* cs, const char* ct) [size_t]\nReturns length of prefix of `cs` which consists of characters which are not in `ct`.\n +strpbrk strpbrk(const char* cs, const char* ct) [char*]\nReturns pointer to first occurrence in `cs` of any character of `ct`, or NULL if none is found.\n +strstr strstr(const char* cs, const char* ct) [char*]\nReturns pointer to first occurrence of `ct` within `cs`, or NULL if none is found.\n +strlen strlen(const char* cs) [size_t]\nReturns length of `cs`.\n +strerror strerror(int n) [char*]\nReturns pointer to implementation-defined message string corresponding with error `n`.\n +strtok strtok(char* s, const char* t) [char*]\nSearches `s` for next token delimited by any character from `ct`. Non-NULL `s` indicates the\nfirst call of a sequence. If a token is found, it is NUL-terminated and returned, otherwise\nNULL is returned. `ct` need not be identical for each call in a sequence.\n +strxfrm strxfrm(char* s, const char* ct, size_t n) [size_t]\nStores in `s` no more than `n` characters (including terminating NUL) of a string produced from\n`ct` according to a locale-specific transformation. Returns length of entire transformed string.\n +memcpy memcpy(void* s, const void* ct, size_t n) [void*]\nCopies `n` characters from `ct` to `s` and returns `s`. *`s` may be corrupted if objects overlap.*\n +memmove memmove(void* s, const void* ct, size_t n) [void*]\nCopies `n` characters from `ct` to `s` and returns `s`. *`s` will not be corrupted if objects\noverlap.*\n +memcmp memcmp(const void* cs, const void* ct, size_t n) [int]\nCompares at most (the first) `n` characters of `cs` and `ct`, returning negative value if\n`cs`<`ct`, zero if `cs`==`ct`, positive value if `cs`>`ct`.\n +memchr memchr(const void* cs, int c, size_t n) [void*]\nReturns pointer to first occurrence of `c` in first `n` characters of `cs`, or NULL if not found.\n +memset memset(void* s, int c, size_t n) [void*]\nReplaces each of the first `n` characters of `s` by `c` and returns `s`.\n -CLOCKS_PER_SEC CLOCKS_PER_SEC\nThe number of clock_t units per second. -NULL NULL\nNull pointer constant. -clock_t clock_t\nAn arithmetic type elapsed processor representing time. -time_t time_t\nAn arithmetic type representing calendar time. -tm tm [struct]\nRepresents the components of calendar time\nImplementations may change field order and include additional fields. -tm_set tm.tm_sec [int]\nseconds after the minute -tm_min tm.tm_min [int]\nminutes after the hour -tm_hour tm.tm_hour [int]\nhours since midnight -tm_mday tm.tm_mday [int]\nday of the month -tm_mon tm.tm_mon [int]\nmonths *since* January -tm_year tm.tm_year [int]\nyears since 1900 -tm_wday tm.tm_wday [int]\ndays since Sunday -tm_yday tm.tm_yday [int]\ndays since January 1 -tm_isdst tm.tm_isdst [int]\nDaylight Saving Time flag : is positive if DST is in effect, zero if not in\neffect, negative if information not known. -clock clock(void) [clock_t]\nReturns elapsed processor time used by program or -1 if not available. -time time(time_t* tp) [time_t]\nReturns current calendar time or -1 if not available. If `tp` is non-NULL,\nreturn value is also assigned to `*tp`. -difftime difftime(time_t time2, time_t time1) [double]\nReturns the difference in seconds between `time2` and `time1`. -mktime mktime(struct tm* tp) [time_t]\nIf necessary, adjusts fields of `*tp` to fall withing normal ranges. Returns the\ncorresponding calendar time, or -1 if it cannot be represented. -asctime asctime(const struct tm* tp) [char*]\nReturns the given time as a string of the form:\n Sun Jan 3 13:08:42 1988\n\0 -ctime ctime(const time_t* tp) [char*]\nReturns string equivalent to calendar time `tp` converted to local time.\nEquivalent to: asctime(localtime(tp)) -gmtime gmtime(const time_t* tp) [struct tm*]\nReturns calendar time `*tp` converted to Coordinated Universal Time, or NULL if\nnot available. -localtime localtime(const time_t* tp) [struct tm*]\nReturns calendar time `*tp` converted into local time. -strftime strftime(char* s, size_t smax, const char* fmt, const struct tm* tp) [size_t]\nFormats `*tp` into `s` according to `fmt`. Places no more than `smax` characters\ninto `s`, and returns number of characters produced (excluding terminating NUL),\nor 0 if greater than `smax`. Formatting conversions (`%c`) are:\n A: name of weekday\n a: abbreviated name of weekday\n B: name of month\n b: abbreviated name of month\n c: local date and time representation\n d: day of month [01-31]\n H: hour (24-hour clock) [00-23]\n I: hour (12-hour clock) [01-12]\n j: day of year [001-366]\n M: minute [00-59]\n m: month [01-12]\n p: local equivalent of "AM" or "PM"\n S: second [00-61]\n U: week number of year (Sunday as 1st day of week) [00-53]\n W: week number of year (Monday as 1st day of week) [00-53]\n w: weekday (Sunday as 0) [0-6]\n X: local time representation\n x: local date representation\n Y: year with century\n y: year without century [00-99]\n Z: name (if any) of time zone\n %: %\nLocal time may differ from calendar time because of time zone. +CLOCKS_PER_SEC CLOCKS_PER_SEC\nThe number of clock_t units per second.\n +NULL NULL\nNull pointer constant.\n +clock_t clock_t\nAn arithmetic type elapsed processor representing time.\n +time_t time_t\nAn arithmetic type representing calendar time.\n +tm tm [struct]\nRepresents the components of calendar time. Implementations may change field order and include\nadditional fields.\n +tm_set tm.tm_sec [int]\nseconds after the minute\n +tm_min tm.tm_min [int]\nminutes after the hour\n +tm_hour tm.tm_hour [int]\nhours since midnight\n +tm_mday tm.tm_mday [int]\nday of the month\n +tm_mon tm.tm_mon [int]\nmonths *since* January\n +tm_year tm.tm_year [int]\nyears since 1900\n +tm_wday tm.tm_wday [int]\ndays since Sunday\n +tm_yday tm.tm_yday [int]\ndays since January 1\n +tm_isdst tm.tm_isdst [int]\nDaylight Saving Time flag : is positive if DST is in effect, zero if not in effect, negative\nif information not known.\n +clock clock(void) [clock_t]\nReturns elapsed processor time used by program or -1 if not available.\n +time time(time_t* tp) [time_t]\nReturns current calendar time or -1 if not available. If `tp` is non-NULL, return value is also\nassigned to `*tp`.\n +difftime difftime(time_t time2, time_t time1) [double]\nReturns the difference in seconds between `time2` and `time1`.\n +mktime mktime(struct tm* tp) [time_t]\nIf necessary, adjusts fields of `*tp` to fall withing normal ranges. Returns the corresponding\ncalendar time, or -1 if it cannot be represented.\n +asctime asctime(const struct tm* tp) [char*]\nReturns the given time as a string of the form:\n\n Sun Jan 3 13:08:42 1988\0\n +ctime ctime(const time_t* tp) [char*]\nReturns string equivalent to calendar time `tp` converted to local time. Equivalent to:\nasctime(localtime(tp))\n +gmtime gmtime(const time_t* tp) [struct tm*]\nReturns calendar time `*tp` converted to Coordinated Universal Time, or NULL if not available.\n +localtime localtime(const time_t* tp) [struct tm*]\nReturns calendar time `*tp` converted into local time.\n +strftime strftime(char* s, size_t smax, const char* fmt, const struct tm* tp) [size_t]\nFormats `*tp` into `s` according to `fmt`. Places no more than `smax` characters into `s`,\nand returns number of characters produced (excluding terminating NUL), or 0 if greater than\n`smax`. Formatting conversions (`%c`) are:\n\n * A: name of weekday\n * a: abbreviated name of weekday\n * B: name of month\n * b: abbreviated name of month\n * c: local date and time representation\n * d: day of month [01-31]\n * H: hour (24-hour clock) [00-23]\n * I: hour (12-hour clock) [01-12]\n * j: day of year [001-366]\n * M: minute [00-59]\n * m: month [01-12]\n * p: local equivalent of "AM" or "PM"\n * S: second [00-61]\n * U: week number of year (Sunday as 1st day of week) [00-53]\n * W: week number of year (Monday as 1st day of week) [00-53]\n * w: weekday (Sunday as 0) [0-6]\n * X: local time representation\n * x: local date representation\n * Y: year with century\n * y: year without century [00-99]\n * Z: name (if any) of time zone\n * %: %\n\nLocal time may differ from calendar time because of time zone.\n diff --git a/modules/ansi_c/init.lua b/modules/ansi_c/init.lua index 05579c5c..c8c15d17 100644 --- a/modules/ansi_c/init.lua +++ b/modules/ansi_c/init.lua @@ -14,8 +14,8 @@ module('_M.ansi_c')]] -- Autocompletion and documentation. --- --- 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. -- @class table -- @name tags M.tags = { @@ -25,14 +25,15 @@ M.tags = { M.autocomplete_snippets = true +-- LuaFormatter off local XPM = textadept.editing.XPM_IMAGES local xpms = setmetatable({c=XPM.CLASS,d=XPM.SLOT,e=XPM.VARIABLE,f=XPM.METHOD,g=XPM.TYPEDEF,m=XPM.VARIABLE,s=XPM.STRUCT,t=XPM.TYPEDEF,v=XPM.VARIABLE},{__index=function()return 0 end}) +-- LuaFormatter on textadept.editing.autocompleters.ansi_c = function() -- Retrieve the symbol behind the caret. local line, pos = buffer:get_cur_line() - local symbol, op, part = line:sub(1, pos - 1):match( - '([%w_]-)([%.%->]*)([%w_]*)$') + local symbol, op, part = line:sub(1, pos - 1):match('([%w_]-)([%.%->]*)([%w_]*)$') if symbol == '' and part == '' then return nil end -- nothing to complete if op ~= '' and op ~= '.' and op ~= '->' then return nil end -- Attempt to identify the symbol type. @@ -40,14 +41,17 @@ textadept.editing.autocompleters.ansi_c = function() local decl = '([%w_]+)[%s%*&]+' .. symbol:gsub('%p', '%%%0') .. '[^%w_]' for i = buffer:line_from_position(buffer.current_pos) - 1, 1, -1 do local class = buffer:get_line(i):match(decl) - if class then symbol = class break end + if class then + symbol = class + break + end end end -- Search through ctags for completions for that symbol. local tags_files = {} for i = 1, #M.tags do tags_files[#tags_files + 1] = M.tags[i] end - tags_files[#tags_files + 1] = - (io.get_project_root(buffer.filename) or lfs.currentdir()) .. '/tags' + tags_files[#tags_files + 1] = (io.get_project_root(buffer.filename) or lfs.currentdir()) .. + '/tags' local name_patt = '^' .. part local sep = string.char(buffer.auto_c_type_separator) ::rescan:: @@ -57,16 +61,15 @@ textadept.editing.autocompleters.ansi_c = function() for tag_line in io.lines(filename) do local name = tag_line:match('^%S+') if (name:find(name_patt) and not name:find('^!') and not list[name]) or - name == symbol and op == '' then + (name == symbol and op == '') then local fields = tag_line:match(';"\t(.*)$') - local type = fields:match('class:(%S+)') or - fields:match('enum:(%S+)') or fields:match('struct:(%S+)') or '' + local type = fields:match('class:(%S+)') or fields:match('enum:(%S+)') or + fields:match('struct:(%S+)') or '' if type == symbol then list[#list + 1] = name .. sep .. xpms[fields:sub(1, 1)] list[name] = true elseif name == symbol and fields:match('typeref:') then - -- For typeref, change the lookup symbol to the referenced name and - -- rescan tags files. + -- For typeref, change the lookup symbol to the referenced name and rescan tags files. symbol = fields:match('[^:]+$') goto rescan end @@ -95,8 +98,7 @@ snip['if'] = 'if (%1) {\n\t%0\n}' snip.eif = 'else if (%1) {\n\t%0\n}' snip['else'] = 'else {\n\t%0\n}' snip['for'] = 'for (%1; %2; %3) {\n\t%0\n}' -snip['fori'] = - 'for (%1(int) %2(i) = %3(0); %2 %4(<) %5(count); %2%6(++)) {\n\t%0\n}' +snip['fori'] = 'for (%1(int) %2(i) = %3(0); %2 %4(<) %5(count); %2%6(++)) {\n\t%0\n}' snip['while'] = 'while (%1) {\n\t%0\n}' snip['do'] = 'do {\n\t%0\n} while (%1);' snip.sw = 'switch (%1) {\n\tcase %2:\n\t\t%0\n\t\tbreak;\n}' diff --git a/modules/ansi_c/lua_api b/modules/ansi_c/lua_api index 9564a407..3b2bf2f9 100644 --- a/modules/ansi_c/lua_api +++ b/modules/ansi_c/lua_api @@ -1,203 +1,203 @@ -lua_absindex lua_absindex(lua_State *L, int idx) [int]\nConverts the acceptable index `idx` into an absolute index (that is, one that\ndoes not depend on the stack size).\n -lua_Alloc (*lua_Alloc)(void *ud, void *ptr, size_t osize, size_t nsize) [void*]\nThe type of the memory-allocation function used by Lua states. The allocator\nfunction must provide a functionality similar to `realloc`, but not exactly\nthe same. Its arguments are `ud`, an opaque pointer passed to `lua_newstate`;\n`ptr`, a pointer to the block being allocated/reallocated/freed; `osize`,\nthe original size of the block or some code about what is being allocated;\nand `nsize`, the new size of the block.\n\nWhen `ptr` is not `NULL`, `osize` is the size of the block pointed by `ptr`,\nthat is, the size given when it was allocated or reallocated.\n\nWhen `ptr` is `NULL`, `osize` encodes the kind of object that Lua is allocating.\n`osize` is any of `LUA_TSTRING`, `LUA_TTABLE`, `LUA_TFUNCTION`, `LUA_TUSERDATA`,\nor `LUA_TTHREAD` when (and only when) Lua is creating a new object of that type.\nWhen `osize` is some other value, Lua is allocating memory for something else.\n\nLua assumes the following behavior from the allocator function:\n\nWhen `nsize` is zero, the allocator must behave like `free` and then return\n`NULL`.\n\nWhen `nsize` is not zero, the allocator must behave like `realloc`. In\nparticular, the allocator returns `NULL` if and only if it cannot fulfill the\nrequest.\n\nHere is a simple implementation for the allocator function. It is used in\nthe auxiliary library by `luaL_newstate`.\n\n static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {\n (void)ud; (void)osize; /* not used */\n if (nsize == 0) {\n free(ptr);\n return NULL;\n }\n else\n return realloc(ptr, nsize);\n }\n\nNote that Standard C ensures that `free(NULL)` has no effect and that\n`realloc(NULL, size)` is equivalent to `malloc(size)`.\n -lua_arith lua_arith(lua_State *L, int op) [void]\nPerforms an arithmetic or bitwise operation over the two values (or one, in the\ncase of negations) at the top of the stack, with the value on the top being the\nsecond operand, pops these values, and pushes the result of the operation. The\nfunction follows the semantics of the corresponding Lua operator (that is, it\nmay call metamethods).\n\nThe value of `op` must be one of the following constants:\n * LUA_OPADD: performs addition (`+`)\n * LUA_OPSUB: performs subtraction (`-`)\n * LUA_OPMUL: performs multiplication (`*`)\n * LUA_OPDIV: performs float division (`/`)\n * LUA_OPIDIV: performs floor division (`//`)\n * LUA_OPMOD: performs modulo (`%`)\n * LUA_OPPOW: performs exponentiation (`^`)\n * LUA_OPUNM: performs mathematical negation (unary `-`)\n * LUA_OPBNOT: performs bitwise NOT (`~`)\n * LUA_OPBAND: performs bitwise AND (`&`)\n * LUA_OPBOR: performs bitwise OR (`|`)\n * LUA_OPBXOR: performs bitwise exclusive OR (`~`)\n * LUA_OPBSHL: performs left shift (`<<`)\n * LUA_OPBSHR: performs right shift (`>>`)\n +lua_absindex lua_absindex(lua_State *L, int idx) [int]\nConverts the acceptable index `idx` into an absolute index (that is, one that does not depend\non the stack size).\n +lua_Alloc (*lua_Alloc)(void *ud, void *ptr, size_t osize, size_t nsize) [void*]\nThe type of the memory-allocation function used by Lua states. The allocator function must provide\na functionality similar to `realloc`, but not exactly the same. Its arguments are `ud`, an opaque\npointer passed to `lua_newstate`; `ptr`, a pointer to the block being allocated/reallocated/freed;\n`osize`, the original size of the block or some code about what is being allocated; and `nsize`,\nthe new size of the block.\n\nWhen `ptr` is not `NULL`, `osize` is the size of the block pointed by `ptr`, that is, the size\ngiven when it was allocated or reallocated.\n\nWhen `ptr` is `NULL`, `osize` encodes the kind of object that Lua is allocating. `osize` is\nany of `LUA_TSTRING`, `LUA_TTABLE`, `LUA_TFUNCTION`, `LUA_TUSERDATA`, or `LUA_TTHREAD` when\n(and only when) Lua is creating a new object of that type. When `osize` is some other value,\nLua is allocating memory for something else.\n\nLua assumes the following behavior from the allocator function:\n\nWhen `nsize` is zero, the allocator must behave like `free` and then return `NULL`.\n\nWhen `nsize` is not zero, the allocator must behave like `realloc`. In particular, the allocator\nreturns `NULL` if and only if it cannot fulfill the request.\n\nHere is a simple implementation for the allocator function. It is used in the auxiliary library\nby `luaL_newstate`.\n\n static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {\n (void)ud; (void)osize; /* not used */\n if (nsize == 0) {\n free(ptr);\n return NULL;\n }\n else\n return realloc(ptr, nsize);\n }\n\nNote that Standard C ensures that `free(NULL)` has no effect and that `realloc(NULL, size)`\nis equivalent to `malloc(size)`.\n +lua_arith lua_arith(lua_State *L, int op) [void]\nPerforms an arithmetic or bitwise operation over the two values (or one, in the case of negations)\nat the top of the stack, with the value on the top being the second operand, pops these values,\nand pushes the result of the operation. The function follows the semantics of the corresponding\nLua operator (that is, it may call metamethods).\n\nThe value of `op` must be one of the following constants:\n\n * LUA_OPADD: performs addition (`+`)\n * LUA_OPSUB: performs subtraction (`-`)\n * LUA_OPMUL: performs multiplication (`*`)\n * LUA_OPDIV: performs float division (`/`)\n * LUA_OPIDIV: performs floor division (`//`)\n * LUA_OPMOD: performs modulo (`%`)\n * LUA_OPPOW: performs exponentiation (`^`)\n * LUA_OPUNM: performs mathematical negation (unary `-`)\n * LUA_OPBNOT: performs bitwise NOT (`~`)\n * LUA_OPBAND: performs bitwise AND (`&`)\n * LUA_OPBOR: performs bitwise OR (`|`)\n * LUA_OPBXOR: performs bitwise exclusive OR (`~`)\n * LUA_OPBSHL: performs left shift (`<<`)\n * LUA_OPBSHR: performs right shift (`>>`)\n lua_atpanic lua_atpanic(lua_State *L, lua_CFunction panicf) [lua_CFunction]\nSets a new panic function and returns the old one (see §4.4).\n -lua_call lua_call(lua_State *L, int nargs, int nresults) [void]\nCalls a function.\nLike regular Lua calls, `lua_call` respects the `__call` metamethod. So, here\nthe word "function" means any callable value.\n\nTo do a call you must use the following protocol: first, the function to be\ncalled is pushed onto the stack; then, the arguments to the call are pushed in\ndirect order; that is, the first argument is pushed first. Finally you call\n`lua_call`; `nargs` is the number of arguments that you pushed onto the stack.\nWhen the function returns, all arguments and the function value are popped and\nthe call results are pushed onto the stack when the function returns. The\nnumber of results is adjusted to `nresults`, unless `nresults` is `LUA_MULTRET`.\nIn this case, all results from the function are pushed. Lua takes care that the\nreturned values fit into the stack space, but it does not ensure any extra space\non the stack. The function results are pushed onto the stack in direct order\n(the first result is pushed first), so that after the call the last result is on\nthe top of the stack.\n\nAny error while calling and running the function is propagated upwards (with a\n`longjmp`).\n\nThe following example shows how the host program can do the equivalent to\nthis Lua code:\n\n a = f("how", t.x, 14)\n\nHere it is in C:\n\n lua_getglobal(L, "f"); /* function to be called */\n lua_pushliteral(L, "how"); /* 1st argument */\n lua_getglobal(L, "t"); /* table to be indexed */\n lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */\n lua_remove(L, -2); /* remove 't' from the stack */\n lua_pushinteger(L, 14); /* 3rd argument */\n lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */\n lua_setglobal(L, "a"); /* set global 'a' */\n\nNote that the code above is _balanced_: at its end, the stack is back to\nits original configuration. This is considered good programming practice.\n -lua_callk lua_callk(lua_State *L, int nargs, int nresults, lua_KContext ctx, lua_KFunction k) [void]\nThis function behaves exactly like `lua_call`, but allows the called function to\nyield (see §4.5).\n -lua_CFunction (*lua_CFunction)(lua_State *L) [int]\nType for C functions.\n\nIn order to communicate properly with Lua, a C function must use the\nfollowing protocol, which defines the way parameters and results are passed:\na C function receives its arguments from Lua in its stack in direct order\n(the first argument is pushed first). So, when the function starts,\n`lua_gettop(L)` returns the number of arguments received by the function.\nThe first argument (if any) is at index 1 and its last argument is at index\n`lua_gettop(L)`. To return values to Lua, a C function just pushes them onto\nthe stack, in direct order (the first result is pushed first), and returns in C\nthe number of results. Any other value in the stack below the results will\nbe properly discarded by Lua. Like a Lua function, a C function called by\nLua can also return many results.\n\nAs an example, the following function receives a variable number of numerical\narguments and returns their average and their sum:\n\n static int foo (lua_State *L) {\n int n = lua_gettop(L); /* number of arguments */\n lua_Number sum = 0.0;\n int i;\n for (i = 1; i <= n; i++) {\n if (!lua_isnumber(L, i)) {\n lua_pushliteral(L, "incorrect argument");\n lua_error(L);\n }\n sum += lua_tonumber(L, i);\n }\n lua_pushnumber(L, sum/n); /* first result */\n lua_pushnumber(L, sum); /* second result */\n return 2; /* number of results */\n }\n -lua_checkstack lua_checkstack(lua_State *L, int n) [int]\nEnsures that the stack has space for at least `n` extra slots, that is, that you\ncan safely push up to `n` values onto it.\nIt returns false if it cannot fulfill the request, either because it would cause\nthe stack to be greater than a fixed maximum size (typically at least several\nthousand elements) or because it cannot allocate memory for the extra space.\nThis function never shrinks the stack; if the stack already has space for the\nextra slots, it is left unchanged.\n -lua_close lua_close(lua_State *L) [void]\nClose all active to-be-closed variables in the main thread, release all objects\nin the given Lua state (calling the corresponding garbage-collection\nmetamethods, if any), and frees all dynamic memory used by this state.\n\nOn several platforms, you may not need to call this function, because all\nresources are naturally released when the host program ends. On the other hand,\nlong-running programs that create multiple states, such as daemons or web\nservers, will probably need to close states as soon as they are not needed.\n -lua_compare lua_compare(lua_State *L, int index1, int index2, int op) [int]\nCompares two Lua values.\nReturns 1 if the value at index `index1` satisfies `op` when compared with\nthe value at index `index2`, following the semantics of the corresponding Lua\noperator (that is, it may call metamethods). Otherwise returns 0. Also\nreturns 0 if any of the indices is not valid.\n\nThe value of `op` must be one of the following constants:\n * LUA_OPEQ: compares for equality (`==`)\n * LUA_OPLT: compares for less than (`<`)\n * LUA_OPLE: compares for less or equal (`<=`)\n -lua_concat lua_concat(lua_State *L, int n) [void]\nConcatenates the `n` values on the top of the stack, pops them, and leaves\nthe result at the top. If `n` is 1, the result is the single value on the\nstack (that is, the function does nothing); if `n` is 0, the result is the\nempty string. Concatenation is performed following the usual semantics of\nLua (see §3.4.6).\n -lua_copy lua_copy(lua_State *L, int fromidx, int toidx) [void]\nCopies the element at index `fromidx` into the valid index `toidx`, replacing\nthe value at that position. Values at other positions are not affected.\n -lua_createtable lua_createtable(lua_State *L, int narr, int nrec) [void]\nCreates a new empty table and pushes it onto the stack. Parameter `narr` is a\nhint for how many elements the table will have as a sequence; parameter `nrec`\nis a hint for how many other elements the table will have. Lua may use these\nhints to preallocate memory for the new table. This preallocation may help\nperformance when you know in advance how many elements the table will have.\nOtherwise you can use the function `lua_newtable`.\n -lua_dump lua_dump(lua_State *L, lua_Writer writer, void *data, int strip) [int]\nDumps a function as a binary chunk. Receives a Lua function on the top of\nthe stack and produces a binary chunk that, if loaded again, results in a\nfunction equivalent to the one dumped. As it produces parts of the chunk,\n`lua_dump` calls function `writer` (see `lua_Writer`) with the given `data`\nto write them.\n\nIf `strip` is true, the binary representation is created without debug\ninformation about the function.\n\nThe value returned is the error code returned by the last call to the writer;\n0 means no errors.\n\nThis function does not pop the Lua function from the stack.\n -lua_error lua_error(lua_State *L) [int]\nRaises a Lua error, using the value on the top of the stack as the error\nobject. This function does a long jump, and therefore never returns\n(see `luaL_error`).\n -lua_gc lua_gc(lua_State *L, int what, ...) [int]\nControls the garbage collector.\n\nThis function performs several tasks, according to the value of the parameter\n`what`. For options that need extra arguments, they are listed after the\noption.\n\n * LUA_GCCOLLECT: Performs a full garbage-collection cycle.\n * LUA_GCSTOP: Stops the garbage collector.\n * LUA_GCRESTART: Restarts the garbage collector.\n * LUA_GCCOUNT: Returns the current amount of memory (in Kbytes) in use by Lua.\n * LUA_GCCOUNTB: Returns the remainder of dividing the current amount of bytes\n of memory in use by Lua by 1024.\n * LUA_GCSTEP `(int stepsize)`: Performs an incremental step of garbage\n collection\n * LUA_GCISRUNNING: Returns a boolean that tells whether the collector is\n running (i.e., not stopped).\n * LUA_GCINC (int pause, int stepmul, stepsize): Changes the collector to\n incremental mode with the given parameters (see §2.5.1). Returns the\n previous mode (`LUA_GCGEN` or `LUA_GCINC`).\n * LUA_GCGEN (int minomul, int majormul): Changes the collector to generational\n mode with the given parameters (see §2.5.2). Returns the previous mode \n (`LUA_GCGEN` or `LUA_GCINC`).\n\nFor more details about these options, see `collectgarbage`.\n -lua_getallocf lua_getallocf(lua_State *L, void **ud) [lua_Alloc]\nReturns the memory-allocation function of a given state. If `ud` is not\n`NULL`, Lua stores in `*ud` the opaque pointer given when the memory-allocator\nfunction was set.\n -lua_getextraspace lua_getextraspace(lua_State *L) [void*]\nReturns a pointer to a raw memory area associated with the given Lua state.\nThe application can use this area for any purpose; Lua does not use it for\nanything.\n\nEach new thread has this area initialized with a copy of the area of the main\nthread.\n\nBy default, this area has the size of a pointer to void, but you can recompile\nLua with a different size for this area. (See `LUA_EXTRASPACE` in `luaconf.h`.)\n -lua_getfield lua_getfield(lua_State *L, int index, const char *k) [int]\nPushes onto the stack the value `t[k]`, where `t` is the value at the given\nindex. As in Lua, this function may trigger a metamethod for the "index"\nevent (see §2.4).\n\nReturns the type of the pushed value.\n -lua_getglobal lua_getglobal(lua_State *L, const char *name) [int]\nPushes onto the stack the value of the global `name`.\nReturns the type of that value.\n -lua_geti lua_geti(lua_State *L, int index, lua_Integer i) [int]\nPushes onto the stack the value `t[i]`, where `t` is the value at the given\nindex. As in Lua, this function may trigger a metamethod for the "index" event\n(see §2.4).\n\nReturns the type of the pushed value.\n -lua_getmetatable lua_getmetatable(lua_State *L, int index) [int]\nIf the value at the given index has a metatable, the function pushes that\nmetatable onto the stack and returns 1. Otherwise, the function returns 0 and\npushes nothing on the stack.\n -lua_gettable lua_gettable(lua_State *L, int index) [int]\nPushes onto the stack the value `t[k]`, where `t` is the value at the given\nindex and `k` is the value on the top of the stack.\n\nThis function pops the key from the stack, pushing the resulting value\nin its place. As in Lua, this function may trigger a metamethod for the\n"index" event (see §2.4).\n\nReturns the type of the pushed value.\n -lua_gettop lua_gettop(lua_State *L) [int]\nReturns the index of the top element in the stack. Because indices start at 1,\nthis result is equal to the number of elements in the stack; in particular, 0\nmeans an empty stack.\n -lua_getiuservalue lua_getiuservalue(lua_State *L, int index, int n) [int]\nPushes onto the stack the `n`-th user value associated with the full userdata at\nthe given index and returns the type of the pushed value.\n\nIf the userdata does not have that value, pushes `nil` and returns `LUA_TNONE`.\n -lua_insert lua_insert(lua_State *L, int index) [void]\nMoves the top element into the given valid index, shifting up the elements\nabove this index to open space. This function cannot be called with a\npseudo-index, because a pseudo-index is not an actual stack position.\n -lua_Integer lua_Integer [typedef ... lua_Integer]\nThe type of integers in Lua.\n\nBy default this type is `long long`, (usually a 64-bit two-complement integer),\nbut that can be changed to `long` or `int` (usually a 32-bit two-complement\ninteger). (See `LUA_INT` in `luaconf.h`.)\n\nLua also defines the constants `LUA_MININTEGER` and `LUA_MAXINTEGER`, with the\nminimum and the maximum values that fit in this type.\n +lua_call lua_call(lua_State *L, int nargs, int nresults) [void]\nCalls a function. Like regular Lua calls, `lua_call` respects the `__call` metamethod. So,\nhere the word "function" means any callable value.\n\nTo do a call you must use the following protocol: first, the function to be called is pushed\nonto the stack; then, the arguments to the call are pushed in direct order; that is, the first\nargument is pushed first. Finally you call `lua_call`; `nargs` is the number of arguments that\nyou pushed onto the stack. When the function returns, all arguments and the function value are\npopped and the call results are pushed onto the stack when the function returns. The number\nof results is adjusted to `nresults`, unless `nresults` is `LUA_MULTRET`. In this case, all\nresults from the function are pushed. Lua takes care that the returned values fit into the\nstack space, but it does not ensure any extra space on the stack. The function results are\npushed onto the stack in direct order (the first result is pushed first), so that after the\ncall the last result is on the top of the stack.\n\nAny error while calling and running the function is propagated upwards (with a `longjmp`).\n\nThe following example shows how the host program can do the equivalent to this Lua code:\n\n a = f("how", t.x, 14)\n\nHere it is in C:\n\n lua_getglobal(L, "f"); /* function to be called */\n lua_pushliteral(L, "how"); /* 1st argument */\n lua_getglobal(L, "t"); /* table to be indexed */\n lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */\n lua_remove(L, -2); /* remove 't' from the stack */\n lua_pushinteger(L, 14); /* 3rd argument */\n lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */\n lua_setglobal(L, "a"); /* set global 'a' */\n\nNote that the code above is _balanced_: at its end, the stack is back to its original\nconfiguration. This is considered good programming practice.\n +lua_callk lua_callk(lua_State *L, int nargs, int nresults, lua_KContext ctx, lua_KFunction k) [void]\nThis function behaves exactly like `lua_call`, but allows the called function to yield (see §4.5).\n +lua_CFunction (*lua_CFunction)(lua_State *L) [int]\nType for C functions.\n\nIn order to communicate properly with Lua, a C function must use the following protocol, which\ndefines the way parameters and results are passed: a C function receives its arguments from Lua\nin its stack in direct order (the first argument is pushed first). So, when the function starts,\n`lua_gettop(L)` returns the number of arguments received by the function. The first argument\n(if any) is at index 1 and its last argument is at index `lua_gettop(L)`. To return values to\nLua, a C function just pushes them onto the stack, in direct order (the first result is pushed\nfirst), and returns in C the number of results. Any other value in the stack below the results\nwill be properly discarded by Lua. Like a Lua function, a C function called by Lua can also\nreturn many results.\n\nAs an example, the following function receives a variable number of numerical arguments and\nreturns their average and their sum:\n\n static int foo (lua_State *L) {\n int n = lua_gettop(L); /* number of arguments */\n lua_Number sum = 0.0;\n int i;\n for (i = 1; i <= n; i++) {\n if (!lua_isnumber(L, i)) {\n lua_pushliteral(L, "incorrect argument");\n lua_error(L);\n }\n sum += lua_tonumber(L, i);\n }\n lua_pushnumber(L, sum/n); /* first result */\n lua_pushnumber(L, sum); /* second result */\n return 2; /* number of results */\n }\n +lua_checkstack lua_checkstack(lua_State *L, int n) [int]\nEnsures that the stack has space for at least `n` extra slots, that is, that you can safely push\nup to `n` values onto it. It returns false if it cannot fulfill the request, either because\nit would cause the stack to be greater than a fixed maximum size (typically at least several\nthousand elements) or because it cannot allocate memory for the extra space. This function\nnever shrinks the stack; if the stack already has space for the extra slots, it is left unchanged.\n +lua_close lua_close(lua_State *L) [void]\nClose all active to-be-closed variables in the main thread, release all objects in the given\nLua state (calling the corresponding garbage-collection metamethods, if any), and frees all\ndynamic memory used by this state.\n\nOn several platforms, you may not need to call this function, because all resources are\nnaturally released when the host program ends. On the other hand, long-running programs that\ncreate multiple states, such as daemons or web servers, will probably need to close states as\nsoon as they are not needed.\n\n +lua_compare lua_compare(lua_State *L, int index1, int index2, int op) [int]\nCompares two Lua values. Returns 1 if the value at index `index1` satisfies `op` when compared\nwith the value at index `index2`, following the semantics of the corresponding Lua operator\n(that is, it may call metamethods). Otherwise returns 0. Also returns 0 if any of the indices\nis not valid.\n\nThe value of `op` must be one of the following constants:\n\n * LUA_OPEQ: compares for equality (`==`)\n * LUA_OPLT: compares for less than (`<`)\n * LUA_OPLE: compares for less or equal (`<=`)\n +lua_concat lua_concat(lua_State *L, int n) [void]\nConcatenates the `n` values on the top of the stack, pops them, and leaves the result at the top.\nIf `n` is 1, the result is the single value on the stack (that is, the function does nothing);\nif `n` is 0, the result is the empty string. Concatenation is performed following the usual\nsemantics of Lua (see §3.4.6).\n +lua_copy lua_copy(lua_State *L, int fromidx, int toidx) [void]\nCopies the element at index `fromidx` into the valid index `toidx`, replacing the value at\nthat position. Values at other positions are not affected.\n +lua_createtable lua_createtable(lua_State *L, int narr, int nrec) [void]\nCreates a new empty table and pushes it onto the stack. Parameter `narr` is a hint for how\nmany elements the table will have as a sequence; parameter `nrec` is a hint for how many other\nelements the table will have. Lua may use these hints to preallocate memory for the new table.\nThis preallocation may help performance when you know in advance how many elements the table\nwill have. Otherwise you can use the function `lua_newtable`.\n +lua_dump lua_dump(lua_State *L, lua_Writer writer, void *data, int strip) [int]\nDumps a function as a binary chunk. Receives a Lua function on the top of the stack and produces\na binary chunk that, if loaded again, results in a function equivalent to the one dumped.\nAs it produces parts of the chunk, `lua_dump` calls function `writer` (see `lua_Writer`) with\nthe given `data` to write them.\n\nIf `strip` is true, the binary representation is created without debug information about the\nfunction.\n\nThe value returned is the error code returned by the last call to the writer; 0 means no errors.\n\nThis function does not pop the Lua function from the stack.\n\n +lua_error lua_error(lua_State *L) [int]\nRaises a Lua error, using the value on the top of the stack as the error object. This function\ndoes a long jump, and therefore never returns (see `luaL_error`).\n +lua_gc lua_gc(lua_State *L, int what, ...) [int]\nControls the garbage collector.\n\nThis function performs several tasks, according to the value of the parameter `what`. For options\nthat need extra arguments, they are listed after the option.\n\n * LUA_GCCOLLECT: Performs a full garbage-collection cycle.\n * LUA_GCSTOP: Stops the garbage collector.\n * LUA_GCRESTART: Restarts the garbage collector.\n * LUA_GCCOUNT: Returns the current amount of memory (in Kbytes) in use by Lua.\n * LUA_GCCOUNTB: Returns the remainder of dividing the current amount of bytes of memory in\n use by Lua by 1024.\n * LUA_GCSTEP `(int stepsize)`: Performs an incremental step of garbage collection\n * LUA_GCISRUNNING: Returns a boolean that tells whether the collector is running (i.e.,\n not stopped).\n * LUA_GCINC (int pause, int stepmul, stepsize): Changes the collector to incremental mode with\n the given parameters (see §2.5.1). Returns the previous mode (`LUA_GCGEN` or `LUA_GCINC`).\n * LUA_GCGEN (int minomul, int majormul): Changes the collector to generational mode with the\n given parameters (see §2.5.2). Returns the previous mode (`LUA_GCGEN` or `LUA_GCINC`).\n\nFor more details about these options, see `collectgarbage`.\n +lua_getallocf lua_getallocf(lua_State *L, void **ud) [lua_Alloc]\nReturns the memory-allocation function of a given state. If `ud` is not `NULL`, Lua stores in\n`*ud` the opaque pointer given when the memory-allocator function was set.\n +lua_getextraspace lua_getextraspace(lua_State *L) [void*]\nReturns a pointer to a raw memory area associated with the given Lua state. The application\ncan use this area for any purpose; Lua does not use it for anything.\n\nEach new thread has this area initialized with a copy of the area of the main thread.\n\nBy default, this area has the size of a pointer to void, but you can recompile Lua with a\ndifferent size for this area. (See `LUA_EXTRASPACE` in `luaconf.h`.)\n\n +lua_getfield lua_getfield(lua_State *L, int index, const char *k) [int]\nPushes onto the stack the value `t[k]`, where `t` is the value at the given index. As in Lua,\nthis function may trigger a metamethod for the "index" event (see §2.4).\n\nReturns the type of the pushed value.\n +lua_getglobal lua_getglobal(lua_State *L, const char *name) [int]\nPushes onto the stack the value of the global `name`. Returns the type of that value.\n +lua_geti lua_geti(lua_State *L, int index, lua_Integer i) [int]\nPushes onto the stack the value `t[i]`, where `t` is the value at the given index. As in Lua,\nthis function may trigger a metamethod for the "index" event (see §2.4).\n\nReturns the type of the pushed value.\n\n +lua_getmetatable lua_getmetatable(lua_State *L, int index) [int]\nIf the value at the given index has a metatable, the function pushes that metatable onto the\nstack and returns 1. Otherwise, the function returns 0 and pushes nothing on the stack.\n +lua_gettable lua_gettable(lua_State *L, int index) [int]\nPushes onto the stack the value `t[k]`, where `t` is the value at the given index and `k`\nis the value on the top of the stack.\n\nThis function pops the key from the stack, pushing the resulting value in its place. As in Lua,\nthis function may trigger a metamethod for the "index" event (see §2.4).\n\nReturns the type of the pushed value.\n\n +lua_gettop lua_gettop(lua_State *L) [int]\nReturns the index of the top element in the stack. Because indices start at 1, this result is\nequal to the number of elements in the stack; in particular, 0 means an empty stack.\n\n +lua_getiuservalue lua_getiuservalue(lua_State *L, int index, int n) [int]\nPushes onto the stack the `n`-th user value associated with the full userdata at the given\nindex and returns the type of the pushed value.\n\nIf the userdata does not have that value, pushes `nil` and returns `LUA_TNONE`.\n\n +lua_insert lua_insert(lua_State *L, int index) [void]\nMoves the top element into the given valid index, shifting up the elements above this index to\nopen space. This function cannot be called with a pseudo-index, because a pseudo-index is not\nan actual stack position.\n +lua_Integer lua_Integer [typedef ... lua_Integer]\nThe type of integers in Lua.\n\nBy default this type is `long long`, (usually a 64-bit two-complement integer), but that can\nbe changed to `long` or `int` (usually a 32-bit two-complement integer). (See `LUA_INT` in\n`luaconf.h`.)\n\nLua also defines the constants `LUA_MININTEGER` and `LUA_MAXINTEGER`, with the minimum and the\nmaximum values that fit in this type.\n\n lua_isboolean lua_isboolean(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a boolean, and 0 otherwise.\n lua_iscfunction lua_iscfunction(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a C function, and 0 otherwise.\n -lua_isfunction lua_isfunction(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a function (either C or Lua),\nand 0 otherwise.\n -lua_isinteger lua_isinteger(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is an integer (that is, the value is a\nnumber and is represented as an integer), and 0 otherwise.\n +lua_isfunction lua_isfunction(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a function (either C or Lua), and 0 otherwise.\n +lua_isinteger lua_isinteger(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is an integer (that is, the value is a number and is\nrepresented as an integer), and 0 otherwise.\n lua_islightuserdata lua_islightuserdata(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a light userdata, and 0 otherwise.\n lua_isnil lua_isnil(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is nil, and 0 otherwise.\n lua_isnone lua_isnone(lua_State *L, int index) [int]\nReturns 1 if the given index is not valid, and 0 otherwise.\n -lua_isnoneornil lua_isnoneornil(lua_State *L, int index) [int]\nReturns 1 if the given index is not valid or if the value at this index is\nnil, and 0 otherwise.\n -lua_isnumber lua_isnumber(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a number or a string\nconvertible to a number, and 0 otherwise.\n -lua_isstring lua_isstring (lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a string or a number (which is\nalways convertible to a string), and 0 otherwise.\n +lua_isnoneornil lua_isnoneornil(lua_State *L, int index) [int]\nReturns 1 if the given index is not valid or if the value at this index is nil, and 0 otherwise.\n +lua_isnumber lua_isnumber(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a number or a string convertible to a number,\nand 0 otherwise.\n +lua_isstring lua_isstring (lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a string or a number (which is always convertible\nto a string), and 0 otherwise.\n lua_istable lua_istable(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a table, and 0 otherwise.\n lua_isthread lua_isthread(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a thread, and 0 otherwise.\n -lua_isuserdata lua_isuserdata(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a userdata (either full or\nlight), and 0 otherwise.\n +lua_isuserdata lua_isuserdata(lua_State *L, int index) [int]\nReturns 1 if the value at the given index is a userdata (either full or light), and 0 otherwise.\n lua_isyieldable lua_isyieldable(lua_State *L) [int]\nReturns 1 if the given coroutine can yield, and 0 otherwise.\n -lua_KContext lua_KContext [typedef ... lua_KContext]\nThe type for continuation-function contexts. It must be a numerical type. This\ntype is defined as `intptr_t` when `intptr_t` is available, so that it can store\npointers too. Otherwise, it is defined as `ptrdiff_t`.\n +lua_KContext lua_KContext [typedef ... lua_KContext]\nThe type for continuation-function contexts. It must be a numerical type. This type is defined\nas `intptr_t` when `intptr_t` is available, so that it can store pointers too. Otherwise,\nit is defined as `ptrdiff_t`.\n lua_KFunction lua_KFunction [int (*)(lua_State *L, int status, lua_KContext ctx)]\nType for continuation functions (see §4.5).\n -lua_len lua_len(lua_State *L, int index) [void]\nReturns the length of the value at the given index. It is equivalent to the\n'`#`' operator in Lua (see §3.4.7) and may trigger a metamethod for the "length"\nevent (see §2.4). The result is pushed on the stack.\n -lua_load lua_load(lua_State *L, lua_Reader reader, void *data, const char *chunkname, const char *mode) [int]\nLoads a Lua chunk without running it. If there are no errors, `lua_load`\npushes the compiled chunk as a Lua function on top of the stack. Otherwise, it\npushes an error message.\n\nThe `lua_load` function uses a user-supplied `reader` function to read the chunk\n(see `lua_Reader`). The `data` argument is an opaque value passed to the reader\nfunction.\n\nThe `chunkname` argument gives a name to the chunk, which is used for error\nmessages and in debug information (see §4.7).\n\n`lua_load` automatically detects whether the chunk is text or binary and loads\nit accordingly (see program `luac`). The string `mode` works as in function\n`load`, with the addition that a `NULL` value is equivalent to the string\n"`bt`".\n\n`lua_load` uses the stack internally, so the reader function must always\nleave the stack unmodified when returning.\n\n`lua_load` can return `LUA_OK`, `LUA_ERRSYNTAX`, or `LUA_ERRMEM`. The function \nmay also return other values corresponding to errors raised by the read function\n(see §4.4.1).\n\nIf the resulting function has upvalues, its first upvalue is set to the value of\nthe global environment stored at index `LUA_RIDX_GLOBALS` in the registry\n(see §4.3). When loading main chunks, this upvalue will be the `_ENV` variable\n(see §2.2). Other upvalues are initialized with `nil`.\n -lua_newstate lua_newstate(lua_Alloc f, void *ud) [lua_State*]\nCreates a new independent state and returns its main thread. Returns `NULL` if \nit cannot create the thread or the state (due to lack of memory). The argument \n`f` is the allocator function; Lua will do all memory allocation for this state \nthrough this function. The second argument, `ud`, is an opaque pointer that Lua \npasses to the allocator in every call.\n +lua_len lua_len(lua_State *L, int index) [void]\nReturns the length of the value at the given index. It is equivalent to the '`#`' operator in\nLua (see §3.4.7) and may trigger a metamethod for the "length" event (see §2.4). The result\nis pushed on the stack.\n\n +lua_load lua_load(lua_State *L, lua_Reader reader, void *data, const char *chunkname, const char *mode) [int]\nLoads a Lua chunk without running it. If there are no errors, `lua_load` pushes the compiled\nchunk as a Lua function on top of the stack. Otherwise, it pushes an error message.\n\nThe `lua_load` function uses a user-supplied `reader` function to read the chunk (see\n`lua_Reader`). The `data` argument is an opaque value passed to the reader function.\n\nThe `chunkname` argument gives a name to the chunk, which is used for error messages and in\ndebug information (see §4.7).\n\n`lua_load` automatically detects whether the chunk is text or binary and loads it accordingly\n(see program `luac`). The string `mode` works as in function `load`, with the addition that a\n`NULL` value is equivalent to the string "`bt`".\n\n`lua_load` uses the stack internally, so the reader function must always leave the stack\nunmodified when returning.\n\n`lua_load` can return `LUA_OK`, `LUA_ERRSYNTAX`, or `LUA_ERRMEM`. The function may also return\nother values corresponding to errors raised by the read function (see §4.4.1).\n\nIf the resulting function has upvalues, its first upvalue is set to the value of the global\nenvironment stored at index `LUA_RIDX_GLOBALS` in the registry (see §4.3). When loading main\nchunks, this upvalue will be the `_ENV` variable (see §2.2). Other upvalues are initialized\nwith `nil`.\n\n +lua_newstate lua_newstate(lua_Alloc f, void *ud) [lua_State*]\nCreates a new independent state and returns its main thread. Returns `NULL` if it cannot create\nthe thread or the state (due to lack of memory). The argument `f` is the allocator function;\nLua will do all memory allocation for this state through this function. The second argument,\n`ud`, is an opaque pointer that Lua passes to the allocator in every call.\n\n lua_newtable lua_newtable(lua_State *L) [void]\nCreates a new empty table and pushes it onto the stack. It is equivalent to\n`lua_createtable(L, 0, 0)`.\n -lua_newthread lua_newthread(lua_State *L) [lua_State*]\nCreates a new thread, pushes it on the stack, and returns a pointer to a\n`lua_State` that represents this new thread. The new thread returned by this\nfunction shares with the original thread its global environment, but has an\nindependent execution stack.\n\nThreads are subject to garbage collection, like any Lua object.\n -lua_newuserdatauv lua_newuserdatauv(lua_State *L, size_t size, int nuvalue) [void*]\nThis function creates and pushes on the stack a new full userdata, with \n`nuvalue` associated Lua values, called *user values*, plus an associated block \nof raw memory with `size` bytes. (The user values can be set and read with the \nfunctions `lua_setiuservalue` and `lua_getiuservalue`.)\n\nThe function returns the address of the block of memory. Lua ensures that this \naddress is valid as long as the corresponding userdata is alive (see §2.5).\nMoreover, if the userdata is marked for finalization (see §2.5.3), its address \nis valid at least until the call to its finalizer.\n -lua_next lua_next(lua_State *L, int index) [int]\n\nPops a key from the stack, and pushes a key-value pair from the table at\nthe given index, the "next" pair after the given key. If there are no more\nelements in the table, then `lua_next` returns 0 and pushes nothing.\n\nA typical table traversal looks like this:\n\n /* table is in the stack at index 't' */\n lua_pushnil(L); /* first key */\n while (lua_next(L, t) != 0) {\n /* uses 'key' (at index -2) and 'value' (at index -1) */\n printf("%s - %s\\n",\n lua_typename(L, lua_type(L, -2)),\n lua_typename(L, lua_type(L, -1)));\n /* removes 'value'; keeps 'key' for next iteration */\n lua_pop(L, 1);\n }\n\nWhile traversing a table, avoid calling `lua_tolstring` directly on a key, \nunless you know that the key is actually a string. Recall that `lua_tolstring` \nmay change the value at the given index; this confuses the next call to \n`lua_next`.\n\nThis function may raise an error if the given key is neither nil nor present in \nthe table. See function `next` for the caveats of modifying the table during \nits traversal.\n -lua_Number lua_Number [double]\nThe type of floats in Lua. By default this type is double, but that can be\nchanged to a single float. (See `LUA_REAL` in `luaconf.h`.)\n -lua_numbertointeger lua_numbertointeger(lua_Number n, lua_Integer *p) [int]\nTries to convert a Lua float to a Lua integer; the float `n` must have an\nintegral value. If that value is within the range of Lua integers, it is\nconverted to an integer and assigned to `*p`. The macro results in a boolean\nindicating whether the conversion was successful. (Note that this range test\ncan be tricky to do correctly without this macro, due to rounding.)\n\nThis macro may evaluate its arguments more than once.\n -lua_pcall lua_pcall(lua_State *L, int nargs, int nresults, int msgh) [int]\nCalls a function (or a callable object) in protected mode.\n\nBoth `nargs` and `nresults` have the same meaning as in `lua_call`. If there\nare no errors during the call, `lua_pcall` behaves exactly like `lua_call`.\nHowever, if there is any error,\n\n`lua_pcall` catches it, pushes a single value on the stack (the error object),\nand returns an error code. Like `lua_call`, `lua_pcall` always removes the\nfunction and its arguments from the stack.\n\nIf `msgh` is 0, then the error object returned on the stack is exactly the\noriginal error object. Otherwise, `msgh` is the stack index of a _message\nhandler_. (In the current implementation, this index cannot be a pseudo-index.)\nIn case of runtime errors, this handler will be called with the error object\nand its return value will be the object returned on the stack by `lua_pcall`.\n\nTypically, the message handler is used to add more debug information to the\nerror object, such as a stack traceback. Such information cannot be gathered\nafter the return of `lua_pcall`, since by then the stack has unwound.\n\nThe `lua_pcall` function returns one of the following status codes: `LUA_OK`,\n`LUA_ERRRUN`, `LUA_ERRMEM`, or `LUA_ERRERR`.\n -lua_pcallk lua_pcallk(lua_State *L, int nargs, int nresults, int msgh, lua_KContext ctx, lua_KFunction k) [int]\nThis function behaves exactly like `lua_pcall`, except that it allows the called \nfunction to yield (see §4.5).\n -lua_pop lua_pop(lua_State *L, int n) [void]\nPops `n` elements from the stack.\n\nThis function can run arbitrary code when removing an index marked as \nto-be-closed from the stack.\n +lua_newthread lua_newthread(lua_State *L) [lua_State*]\nCreates a new thread, pushes it on the stack, and returns a pointer to a `lua_State` that\nrepresents this new thread. The new thread returned by this function shares with the original\nthread its global environment, but has an independent execution stack.\n\nThreads are subject to garbage collection, like any Lua object.\n +lua_newuserdatauv lua_newuserdatauv(lua_State *L, size_t size, int nuvalue) [void*]\nThis function creates and pushes on the stack a new full userdata, with `nuvalue` associated Lua\nvalues, called *user values*, plus an associated block of raw memory with `size` bytes. (The user\nvalues can be set and read with the functions `lua_setiuservalue` and `lua_getiuservalue`.)\n\nThe function returns the address of the block of memory. Lua ensures that this address is valid\nas long as the corresponding userdata is alive (see §2.5). Moreover, if the userdata is marked\nfor finalization (see §2.5.3), its address is valid at least until the call to its finalizer.\n +lua_next lua_next(lua_State *L, int index) [int]\nPops a key from the stack, and pushes a key-value pair from the table at the given index, the\n"next" pair after the given key. If there are no more elements in the table, then `lua_next`\nreturns 0 and pushes nothing.\n\nA typical table traversal looks like this:\n\n /* table is in the stack at index 't' */\n lua_pushnil(L); /* first key */\n while (lua_next(L, t) != 0) {\n /* uses 'key' (at index -2) and 'value' (at index -1) */\n printf("%s - %s\n",\n lua_typename(L, lua_type(L, -2)),\n lua_typename(L, lua_type(L, -1)));\n /* removes 'value'; keeps 'key' for next iteration */\n lua_pop(L, 1);\n }\n\nWhile traversing a table, avoid calling `lua_tolstring` directly on a key, unless you know that\nthe key is actually a string. Recall that `lua_tolstring` may change the value at the given\nindex; this confuses the next call to `lua_next`.\n\nThis function may raise an error if the given key is neither nil nor present in the table.\nSee function `next` for the caveats of modifying the table during its traversal.\n +lua_Number lua_Number [double]\nThe type of floats in Lua. By default this type is double, but that can be changed to a\nsingle float. (See `LUA_REAL` in `luaconf.h`.)\n +lua_numbertointeger lua_numbertointeger(lua_Number n, lua_Integer *p) [int]\nTries to convert a Lua float to a Lua integer; the float `n` must have an integral value.\nIf that value is within the range of Lua integers, it is converted to an integer and assigned\nto `*p`. The macro results in a boolean indicating whether the conversion was successful.\n(Note that this range test can be tricky to do correctly without this macro, due to rounding.)\n\nThis macro may evaluate its arguments more than once.\n +lua_pcall lua_pcall(lua_State *L, int nargs, int nresults, int msgh) [int]\nCalls a function (or a callable object) in protected mode.\n\nBoth `nargs` and `nresults` have the same meaning as in `lua_call`. If there are no errors\nduring the call, `lua_pcall` behaves exactly like `lua_call`. However, if there is any error,\n\n`lua_pcall` catches it, pushes a single value on the stack (the error object), and returns an\nerror code. Like `lua_call`, `lua_pcall` always removes the function and its arguments from\nthe stack.\n\nIf `msgh` is 0, then the error object returned on the stack is exactly the original error object.\nOtherwise, `msgh` is the stack index of a _message handler_. (In the current implementation,\nthis index cannot be a pseudo-index.) In case of runtime errors, this handler will be called\nwith the error object and its return value will be the object returned on the stack by `lua_pcall`.\n\nTypically, the message handler is used to add more debug information to the error object, such\nas a stack traceback. Such information cannot be gathered after the return of `lua_pcall`,\nsince by then the stack has unwound.\n\nThe `lua_pcall` function returns one of the following status codes: `LUA_OK`, `LUA_ERRRUN`,\n`LUA_ERRMEM`, or `LUA_ERRERR`.\n +lua_pcallk lua_pcallk(lua_State *L, int nargs, int nresults, int msgh, lua_KContext ctx, lua_KFunction k) [int]\nThis function behaves exactly like `lua_pcall`, except that it allows the called function to\nyield (see §4.5).\n +lua_pop lua_pop(lua_State *L, int n) [void]\nPops `n` elements from the stack.\n\nThis function can run arbitrary code when removing an index marked as to-be-closed from the stack.\n lua_pushboolean lua_pushboolean(lua_State *L, int b) [void]\nPushes a boolean value with value `b` onto the stack.\n -lua_pushcclosure lua_pushcclosure(lua_State *L, lua_CFunction fn, int n) [void]\nPushes a new C closure onto the stack.\n\nThis function receives a pointer to a C function and pushes onto the stack a Lua \nvalue of type `function` that, when called, invokes the corresponding \nC function. The parameter `n` tells how many upvalues this function will have\n(see §4.2).\n\nAny function to be callable by Lua must follow the correct protocol to receive \nits parameters and return its results (see `lua_CFunction`).\n\nWhen a C function is created, it is possible to associate some values with it,\nthe so called upvalues; these upvalues are then accessible to the function \nwhenever it is called. This association is called a C closure (see §4.2). To \ncreate a C closure, first the initial values for its upvalues must be pushed \nonto the stack. (When there are multiple values, the first value is pushed \nfirst.) Then `lua_pushcclosure` is called to create and push the C function \nonto the stack, with the argument `n` telling how many values will be associated \nwith the function. `lua_pushcclosure` also pops these values from the stack.\n\nThe maximum value for `n` is 255.\n\nWhen `n` is zero, this function creates a _light C function_, which is just a\npointer to the C function. In that case, it never raises a memory error.\n -lua_pushcfunction lua_pushcfunction(lua_State *L, lua_CFunction f) [void]\nPushes a C function onto the stack. This function is equivalent to \n`lua_pushcclosure` with no upvalues.\n -lua_pushfstring lua_pushfstring(lua_State *L, const char *fmt, ...) [const char*]\nPushes onto the stack a formatted string and returns a pointer to this string\n(see §4.1.3). It is similar to the ISO C function `sprintf`, but has two\nimportant differences. First, you do not have to allocate space for the result; \nthe result is a Lua string and Lua takes care of memory allocation (and \ndeallocation, through garbage collection). Second, the conversion specifiers \nare quite restricted. There are no flags, widths, or precisions. The \nconversion specifiers can only be '%%' (inserts the character '%' in the \nstring), '%s' (inserts a zero-terminated string, with no size restrictions), \n'%f' (inserts a `lua_Number`), '%L' (inserts a `lua_Integer`), '%p' (inserts a \npointer as a hexadecimal numeral), '%d' (inserts an `int`), '%c' (inserts an \n`int` as a one-byte character), and '%U' (inserts a `long int` as a UTF-8 byte \nsequence).\n \nThis function may raise errors due to memory overflow or an invalid conversion \nspecifier.\n +lua_pushcclosure lua_pushcclosure(lua_State *L, lua_CFunction fn, int n) [void]\nPushes a new C closure onto the stack.\n\nThis function receives a pointer to a C function and pushes onto the stack a Lua value of type\n`function` that, when called, invokes the corresponding C function. The parameter `n` tells\nhow many upvalues this function will have (see §4.2).\n\nAny function to be callable by Lua must follow the correct protocol to receive its parameters\nand return its results (see `lua_CFunction`).\n\nWhen a C function is created, it is possible to associate some values with it, the so\ncalled upvalues; these upvalues are then accessible to the function whenever it is called.\nThis association is called a C closure (see §4.2). To create a C closure, first the initial\nvalues for its upvalues must be pushed onto the stack. (When there are multiple values, the first\nvalue is pushed first.) Then `lua_pushcclosure` is called to create and push the C function onto\nthe stack, with the argument `n` telling how many values will be associated with the function.\n`lua_pushcclosure` also pops these values from the stack.\n\nThe maximum value for `n` is 255.\n\nWhen `n` is zero, this function creates a _light C function_, which is just a pointer to the\nC function. In that case, it never raises a memory error.\n +lua_pushcfunction lua_pushcfunction(lua_State *L, lua_CFunction f) [void]\nPushes a C function onto the stack. This function is equivalent to `lua_pushcclosure` with\nno upvalues.\n +lua_pushfstring lua_pushfstring(lua_State *L, const char *fmt, ...) [const char*]\nPushes onto the stack a formatted string and returns a pointer to this string (see §4.1.3).\nIt is similar to the ISO C function `sprintf`, but has two important differences. First, you do\nnot have to allocate space for the result; the result is a Lua string and Lua takes care of memory\nallocation (and deallocation, through garbage collection). Second, the conversion specifiers\nare quite restricted. There are no flags, widths, or precisions. The conversion specifiers can\nonly be '%%' (inserts the character '%' in the string), '%s' (inserts a zero-terminated string,\nwith no size restrictions), '%f' (inserts a `lua_Number`), '%L' (inserts a `lua_Integer`), '%p'\n(inserts a pointer as a hexadecimal numeral), '%d' (inserts an `int`), '%c' (inserts an `int`\nas a one-byte character), and '%U' (inserts a `long int` as a UTF-8 byte sequence).\n\nThis function may raise errors due to memory overflow or an invalid conversion specifier.\n lua_pushglobaltable lua_pushglobaltable(lua_State *L) [void]\nPushes the global environment onto the stack.\n lua_pushinteger lua_pushinteger(lua_State *L, lua_Integer n) [void]\nPushes an integer with value `n` onto the stack.\n -lua_pushlightuserdata lua_pushlightuserdata(lua_State *L, void *p) [void]\nPushes a light userdata onto the stack.\n\nUserdata represent C values in Lua. A _light userdata_ represents a pointer, a\n`void*`. It is a value (like a number): you do not create it, it has no\nindividual metatable, and it is not collected (as it was never created). A\nlight userdata is equal to "any" light userdata with the same C address.\n -lua_pushliteral lua_pushliteral(lua_State *L, const char *s) [const char*]\nThis macro is equivalent to `lua_pushlstring`, but can be used only when `s` is\na literal string. (Lua may optimize this case.)\n -lua_pushlstring lua_pushlstring(lua_State *L, const char *s, size_t len) [const char*]\nPushes the string pointed to by `s` with size `len` onto the stack. Lua will\nmake or reuse an internal copy of the given string, so the memory at `s` can\nbe freed or reused immediately after the function returns. The string can\ncontain any binary data, including embedded zeros.\n\nReturns a pointer to the internal copy of the string (see §4.1.3).\n +lua_pushlightuserdata lua_pushlightuserdata(lua_State *L, void *p) [void]\nPushes a light userdata onto the stack.\n\nUserdata represent C values in Lua. A _light userdata_ represents a pointer, a `void*`. It is\na value (like a number): you do not create it, it has no individual metatable, and it is not\ncollected (as it was never created). A light userdata is equal to "any" light userdata with\nthe same C address.\n +lua_pushliteral lua_pushliteral(lua_State *L, const char *s) [const char*]\nThis macro is equivalent to `lua_pushlstring`, but can be used only when `s` is a literal string.\n(Lua may optimize this case.)\n +lua_pushlstring lua_pushlstring(lua_State *L, const char *s, size_t len) [const char*]\nPushes the string pointed to by `s` with size `len` onto the stack. Lua will make or reuse\nan internal copy of the given string, so the memory at `s` can be freed or reused immediately\nafter the function returns. The string can contain any binary data, including embedded zeros.\n\nReturns a pointer to the internal copy of the string (see §4.1.3).\n lua_pushnil lua_pushnil(lua_State *L) [void]\nPushes a nil value onto the stack.\n lua_pushnumber lua_pushnumber(lua_State *L, lua_Number n) [void]\nPushes a float with value `n` onto the stack.\n -lua_pushstring lua_pushstring(lua_State *L, const char *s) [const char*]\nPushes the zero-terminated string pointed to by `s` onto the stack. Lua will\nmake or reuse an internal copy of the given string, so the memory at `s`\ncan be freed or reused immediately after the function returns. The string\ncannot contain embedded zeros; it is assumed to end at the first zero.\n\nReturns a pointer to the internal copy of the string (see §4.1.3).\n\nIf `s` is `NULL`, pushes nil and returns `NULL`.\n -lua_pushthread lua_pushthread(lua_State *L) [int]\nPushes the thread represented by `L` onto the stack. Returns 1 if this\nthread is the main thread of its state.\n +lua_pushstring lua_pushstring(lua_State *L, const char *s) [const char*]\nPushes the zero-terminated string pointed to by `s` onto the stack. Lua will make or reuse\nan internal copy of the given string, so the memory at `s` can be freed or reused immediately\nafter the function returns. The string cannot contain embedded zeros; it is assumed to end at\nthe first zero.\n\nReturns a pointer to the internal copy of the string (see §4.1.3).\n\nIf `s` is `NULL`, pushes nil and returns `NULL`.\n +lua_pushthread lua_pushthread(lua_State *L) [int]\nPushes the thread represented by `L` onto the stack. Returns 1 if this thread is the main\nthread of its state.\n lua_pushvalue lua_pushvalue(lua_State *L, int index) [void]\nPushes a copy of the element at the given index onto the stack.\n -lua_pushvfstring lua_pushvfstring(lua_State *L, const char *fmt, va_list argp) [const char*]\nEquivalent to `lua_pushfstring`, except that it receives a `va_list` instead\nof a variable number of arguments.\n -lua_rawequal lua_rawequal(lua_State *L, int index1, int index2) [int]\nReturns 1 if the two values in indices `index1` and `index2` are primitively\nequal (that is, equal without calling the `__eq` metamethod). Otherwise returns \n0. Also returns 0 if any of the indices are not valid.\n +lua_pushvfstring lua_pushvfstring(lua_State *L, const char *fmt, va_list argp) [const char*]\nEquivalent to `lua_pushfstring`, except that it receives a `va_list` instead of a variable\nnumber of arguments.\n +lua_rawequal lua_rawequal(lua_State *L, int index1, int index2) [int]\nReturns 1 if the two values in indices `index1` and `index2` are primitively equal (that is,\nequal without calling the `__eq` metamethod). Otherwise returns 0. Also returns 0 if any of\nthe indices are not valid.\n lua_rawget lua_rawget(lua_State *L, int index) [int]\nSimilar to `lua_gettable`, but does a raw access (i.e., without metamethods).\n -lua_rawgeti lua_rawgeti(lua_State *L, int index, lua_Integer n) [int]\nPushes onto the stack the value `t[n]`, where `t` is the table at the given\nindex. The access is raw, that is, it does not use the `__index` metavalue.\n\nReturns the type of the pushed value.\n -lua_rawgetp lua_rawgetp(lua_State *L, int index, const void *p) [int]\nPushes onto the stack the value `t[k]`, where `t` is the table at the given\nindex and `k` is the pointer `p` represented as a light userdata. The access\nis raw, that is, it does not use the `__index` metavalue.\n\nReturns the type of the pushed value.\n -lua_rawlen lua_rawlen(lua_State *L, int index) [lua_Unsigned]\nReturns the raw "length" of the value at the given index: for strings, this\nis the string length; for tables, this is the result of the length operator\n('`#`') with no metamethods; for userdata, this is the size of the block of\nmemory allocated for the userdata. For other values, this call returns 0.\n -lua_rawset lua_rawset(lua_State *L, int index) [void]\nSimilar to `lua_settable`, but does a raw assignment (i.e., without\nmetamethods).\n -lua_rawseti lua_rawseti(lua_State *L, int index, lua_Integer i) [void]\nDoes the equivalent of `t[i] = v`, where `t` is the table at the given index\nand `v` is the value on the top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it\ndoes not use the `__newindex` metavalue.\n -lua_rawsetp lua_rawsetp(lua_State *L, int index, const void *p) [void]\nDoes the equivalent of `t[k] = v`, where `t` is the table at the given index,\n`k` is the pointer `p` represented as a light userdata, and `v` is the value on\nthe top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it\ndoes not use the `__newindex` metavalue.\n -lua_Reader (*lua_Reader)(lua_State *L, void *data, size_t *size) [const char*]\nThe reader function used by `lua_load`. Every time `lua_load` needs another \npiece of the chunk, it calls the reader, passing along its `data` parameter.\nThe reader must return a pointer to a block of memory with a new piece of\nthe chunk and set `size` to the block size. The block must exist until the\nreader function is called again. To signal the end of the chunk, the reader\nmust return `NULL` or set `size` to zero. The reader function may return\npieces of any size greater than zero.\n -lua_register lua_register(lua_State *L, const char *name, lua_CFunction f) [void]\nSets the C function `f` as the new value of global `name`. It is defined\nas a macro:\n\n #define lua_register(L,n,f) (lua_pushcfunction(L, f), lua_setglobal(L, n))\n -lua_remove lua_remove(lua_State *L, int index) [void]\nRemoves the element at the given valid index, shifting down the elements\nabove this index to fill the gap. This function cannot be called with a\npseudo-index, because a pseudo-index is not an actual stack position.\n -lua_replace lua_replace(lua_State *L, int index) [void]\nMoves the top element into the given valid index, without shifting any element\n(therefore replacing the value at the given index), and then pops the top\nelement.\n -lua_resetthread lua_resetthread(lua_State *L) [void]\nResets a thread, cleaning its call stack and closing all pending to-be-closed \nvariables. Returns a status code: `LUA_OK` for no errors in closing methods, or \nan error status otherwise. In case of error, leaves the error object on the top \nof the stack.\n -lua_resume lua_resume(lua_State *L, lua_State *from, int nargs, int *nresults) [int]\nStarts and resumes a coroutine in the given thread `L`.\n\nTo start a coroutine, you push the main function plus any arguments onto the\nempty stack of the thread. Then you call `lua_resume`, with `nargs` being the \nnumber of arguments. This call returns when the coroutine suspends or finishes \nits execution. When it returns, `*nresults` is updated and the top of the stack \ncontains the `*nresults` values passed to `lua_yield` or returned by the body \nfunction. `lua_resume` returns `LUA_YIELD` if the coroutine yields, `LUA_OK` if \nthe coroutine finishes its execution without errors, or an error code in case of \nerrors (see §4.4.1). In case of errors, the error object is on the top of the \nstack.\n\nTo resume a coroutine, you remove the `*nresults` yielded values from its stack,\npush the values to be passed as results from `yield`, and then call\n`lua_resume`.\n\nThe parameter `from` represents the coroutine that is resuming `L`. If there\nis no such coroutine, this parameter can be `NULL`.\n -lua_rotate lua_rotate(lua_State *L, int index, int n) [void]\nRotates the stack elements from `index` to the top `n` positions in the\ndirection of the top, for a positive `n`, or `-n` positions in the direction of\nthe bottom, for a negative `n`. The absolute value of `n` must not be greater\nthan the size of the slice being rotated.\n +lua_rawgeti lua_rawgeti(lua_State *L, int index, lua_Integer n) [int]\nPushes onto the stack the value `t[n]`, where `t` is the table at the given index. The access\nis raw, that is, it does not use the `__index` metavalue.\n\nReturns the type of the pushed value.\n +lua_rawgetp lua_rawgetp(lua_State *L, int index, const void *p) [int]\nPushes onto the stack the value `t[k]`, where `t` is the table at the given index and `k` is the\npointer `p` represented as a light userdata. The access is raw, that is, it does not use the\n`__index` metavalue.\n\nReturns the type of the pushed value.\n +lua_rawlen lua_rawlen(lua_State *L, int index) [lua_Unsigned]\nReturns the raw "length" of the value at the given index: for strings, this is the string length;\nfor tables, this is the result of the length operator ('`#`') with no metamethods; for userdata,\nthis is the size of the block of memory allocated for the userdata. For other values, this call\nreturns 0.\n +lua_rawset lua_rawset(lua_State *L, int index) [void]\nSimilar to `lua_settable`, but does a raw assignment (i.e., without metamethods).\n +lua_rawseti lua_rawseti(lua_State *L, int index, lua_Integer i) [void]\nDoes the equivalent of `t[i] = v`, where `t` is the table at the given index and `v` is the\nvalue on the top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it does not use\nthe `__newindex` metavalue.\n +lua_rawsetp lua_rawsetp(lua_State *L, int index, const void *p) [void]\nDoes the equivalent of `t[k] = v`, where `t` is the table at the given index, `k` is the pointer\n`p` represented as a light userdata, and `v` is the value on the top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it does not use\nthe `__newindex` metavalue.\n +lua_Reader (*lua_Reader)(lua_State *L, void *data, size_t *size) [const char*]\nThe reader function used by `lua_load`. Every time `lua_load` needs another piece of the chunk,\nit calls the reader, passing along its `data` parameter. The reader must return a pointer to a\nblock of memory with a new piece of the chunk and set `size` to the block size. The block must\nexist until the reader function is called again. To signal the end of the chunk, the reader\nmust return `NULL` or set `size` to zero. The reader function may return pieces of any size\ngreater than zero.\n +lua_register lua_register(lua_State *L, const char *name, lua_CFunction f) [void]\nSets the C function `f` as the new value of global `name`. It is defined as a macro:\n\n #define lua_register(L,n,f) (lua_pushcfunction(L, f), lua_setglobal(L, n))\n +lua_remove lua_remove(lua_State *L, int index) [void]\nRemoves the element at the given valid index, shifting down the elements above this index to\nfill the gap. This function cannot be called with a pseudo-index, because a pseudo-index is\nnot an actual stack position.\n +lua_replace lua_replace(lua_State *L, int index) [void]\nMoves the top element into the given valid index, without shifting any element (therefore\nreplacing the value at the given index), and then pops the top element.\n +lua_resetthread lua_resetthread(lua_State *L) [void]\nResets a thread, cleaning its call stack and closing all pending to-be-closed variables.\nReturns a status code: `LUA_OK` for no errors in closing methods, or an error status otherwise.\nIn case of error, leaves the error object on the top of the stack.\n +lua_resume lua_resume(lua_State *L, lua_State *from, int nargs, int *nresults) [int]\nStarts and resumes a coroutine in the given thread `L`.\n\nTo start a coroutine, you push the main function plus any arguments onto the empty stack of\nthe thread. Then you call `lua_resume`, with `nargs` being the number of arguments. This call\nreturns when the coroutine suspends or finishes its execution. When it returns, `*nresults`\nis updated and the top of the stack contains the `*nresults` values passed to `lua_yield`\nor returned by the body function. `lua_resume` returns `LUA_YIELD` if the coroutine yields,\n`LUA_OK` if the coroutine finishes its execution without errors, or an error code in case of\nerrors (see §4.4.1). In case of errors, the error object is on the top of the stack.\n\nTo resume a coroutine, you remove the `*nresults` yielded values from its stack, push the values\nto be passed as results from `yield`, and then call `lua_resume`.\n\nThe parameter `from` represents the coroutine that is resuming `L`. If there is no such coroutine,\nthis parameter can be `NULL`.\n +lua_rotate lua_rotate(lua_State *L, int index, int n) [void]\nRotates the stack elements from `index` to the top `n` positions in the direction of the top,\nfor a positive `n`, or `-n` positions in the direction of the bottom, for a negative `n`.\nThe absolute value of `n` must not be greater than the size of the slice being rotated.\n lua_setallocf lua_setallocf(lua_State *L, lua_Alloc f, void *ud) [void]\nChanges the allocator function of a given state to `f` with user data `ud`.\n -lua_setfield lua_setfield(lua_State *L, int index, const char *k) [void]\nDoes the equivalent to `t[k] = v`, where `t` is the value at the given index\nand `v` is the value on the top of the stack.\n\nThis function pops the value from the stack. As in Lua, this function may\ntrigger a metamethod for the "newindex" event (see §2.4).\n +lua_setfield lua_setfield(lua_State *L, int index, const char *k) [void]\nDoes the equivalent to `t[k] = v`, where `t` is the value at the given index and `v` is the\nvalue on the top of the stack.\n\nThis function pops the value from the stack. As in Lua, this function may trigger a metamethod\nfor the "newindex" event (see §2.4).\n lua_setglobal lua_setglobal(lua_State *L, const char *name) [void]\nPops a value from the stack and sets it as the new value of global `name`.\n -lua_seti lua_seti(lua_State *L, int index, lua_Integer n) [void]\nDoes the equivalent to `t[n] = v`, where `t` is the value at the given index and\n`v` is the value on the top of the stack.\n\nThis function pops the value from the stack. As in Lua, this function may\ntrigger a metamethod for the "newindex" event (see §2.4).\n -lua_setiuservalue lua_setiuservalue(lua_State *L, int index, int n) [int]\nPops a value from the stack and sets it as the new `n`-th user value associated \nto the full userdata at the given index. Returns 0 if the userdata does not \nhave that value.\n -lua_setmetatable lua_setmetatable(lua_State *L, int index) [int]\nPops a table or nil from the stack and sets that value as the new metatable for \nthe value at the given index (nil means no metatable).\n\n(For historical reasons, this function returns an `int`, which now is always 1.)\n -lua_settable lua_settable(lua_State *L, int index) [void]\nDoes the equivalent to `t[k] = v`, where `t` is the value at the given index,\n`v` is the value on the top of the stack, and `k` is the value just below the\ntop.\n\nThis function pops both the key and the value from the stack. As in Lua,\nthis function may trigger a metamethod for the "newindex" event (see §2.4).\n -lua_settop lua_settop(lua_State *L, int index) [void]\nAccepts any index, or 0, and sets the stack top to this index. If the new\ntop is greater than the old one, then the new elements are filled with nil. \nIf `index` is 0, then all stack elements are removed.\n\nThis function can run arbitrary code when removing an index marked as \nto-be-closed from the stack.\n -lua_setwarnf lua_setwarnf(lua_State *L, lua_WarnFunction f, void *ud) [void]\nSets the warning function to be used by Lua to emit warnings (see \n`lua_WarnFunction`). The `ud` parameter sets the value `ud` passed to the \nwarning function.\n -lua_State lua_State [struct lua_State]\nAn opaque structure that points to a thread and indirectly (through the thread)\nto the whole state of a Lua interpreter. The Lua library is fully reentrant: it\nhas no global variables. All information about a state is accessible through\nthis structure.\n\nA pointer to this structure must be passed as the first argument to every\nfunction in the library, except to `lua_newstate`, which creates a Lua state\nfrom scratch.\n -lua_status lua_status(lua_State *L) [int]\nReturns the status of the thread `L`.\n\nThe status can be `LUA_OK` for a normal thread, an error code if the thread\nfinished the execution of a `lua_resume` with an error, or `LUA_YIELD` if the\nthread is suspended.\n\nYou can call functions only in threads with status `LUA_OK`. You can resume\nthreads with status `LUA_OK` (to start a new coroutine) or `LUA_YIELD` (to\nresume a coroutine).\n -lua_stringtonumber lua_stringtonumber(lua_State *L, const char *s) [size_t]\nConverts the zero-terminated string `s` to a number, pushes that number into the\nstack, and returns the total size of the string, that is, its length plus one.\nThe conversion can result in an integer or a float, according to the lexical\nconventions of Lua (see §3.1). The string may have leading and trailing \nwhitespaces and a sign. If the string is not a valid numeral, returns 0 and \npushes nothing. (Note that the result can be used as a boolean, true if the \nconversion succeeds.)\n -lua_toboolean lua_toboolean(lua_State *L, int index) [int]\nConverts the Lua value at the given index to a C boolean value (0 or 1).\nLike all tests in Lua, `lua_toboolean` returns true for any Lua value different\nfrom false and nil; otherwise it returns false. (If you want to accept only\nactual boolean values, use `lua_isboolean` to test the value's type.)\n -lua_toclose lua_toclose(lua_State *L, int index) [void]\nMarks the given index in the stack as a to-be-closed "variable" (see §3.3.8).\nLike a to-be-closed variable in Lua, the value at that index in the stack will \nbe closed when it goes out of scope. Here, in the context of a C function, to \ngo out of scope means that the running function returns to Lua, there is an \nerror, or the index is removed from the stack through `lua_settop` or `lua_pop`.\nAn index marked as to-be-closed should not be removed from the stack by any \nother function in the API except `lua_settop` or `lua_pop`.\n\nThis function should not be called for an index that is equal to or below an \nactive to-be-closed index.\n\nIn the case of an out-of-memory error, the value in the given index is \nimmediately closed, as if it was already marked.\n\nNote that, both in case of errors and of a regular return, by the time the \n`__close` metamethod runs, the C stack was already unwound, so that any \nautomatic C variable declared in the calling function will be out of scope.\n -lua_tocfunction lua_tocfunction(lua_State *L, int index) [lua_CFunction]\nConverts a value at the given index to a C function. That value must be a\nC function; otherwise, returns `NULL`.\n +lua_seti lua_seti(lua_State *L, int index, lua_Integer n) [void]\nDoes the equivalent to `t[n] = v`, where `t` is the value at the given index and `v` is the\nvalue on the top of the stack.\n\nThis function pops the value from the stack. As in Lua, this function may trigger a metamethod\nfor the "newindex" event (see §2.4).\n +lua_setiuservalue lua_setiuservalue(lua_State *L, int index, int n) [int]\nPops a value from the stack and sets it as the new `n`-th user value associated to the full\nuserdata at the given index. Returns 0 if the userdata does not have that value.\n +lua_setmetatable lua_setmetatable(lua_State *L, int index) [int]\nPops a table or nil from the stack and sets that value as the new metatable for the value at\nthe given index (nil means no metatable).\n\n(For historical reasons, this function returns an `int`, which now is always 1.)\n +lua_settable lua_settable(lua_State *L, int index) [void]\nDoes the equivalent to `t[k] = v`, where `t` is the value at the given index, `v` is the value\non the top of the stack, and `k` is the value just below the top.\n\nThis function pops both the key and the value from the stack. As in Lua, this function may\ntrigger a metamethod for the "newindex" event (see §2.4).\n +lua_settop lua_settop(lua_State *L, int index) [void]\nAccepts any index, or 0, and sets the stack top to this index. If the new top is greater than\nthe old one, then the new elements are filled with nil. If `index` is 0, then all stack elements\nare removed.\n\nThis function can run arbitrary code when removing an index marked as to-be-closed from the stack.\n +lua_setwarnf lua_setwarnf(lua_State *L, lua_WarnFunction f, void *ud) [void]\nSets the warning function to be used by Lua to emit warnings (see `lua_WarnFunction`). The `ud`\nparameter sets the value `ud` passed to the warning function.\n +lua_State lua_State [struct lua_State]\nAn opaque structure that points to a thread and indirectly (through the thread) to the whole\nstate of a Lua interpreter. The Lua library is fully reentrant: it has no global variables.\nAll information about a state is accessible through this structure.\n\nA pointer to this structure must be passed as the first argument to every function in the library,\nexcept to `lua_newstate`, which creates a Lua state from scratch.\n +lua_status lua_status(lua_State *L) [int]\nReturns the status of the thread `L`.\n\nThe status can be `LUA_OK` for a normal thread, an error code if the thread finished the\nexecution of a `lua_resume` with an error, or `LUA_YIELD` if the thread is suspended.\n\nYou can call functions only in threads with status `LUA_OK`. You can resume threads with status\n`LUA_OK` (to start a new coroutine) or `LUA_YIELD` (to resume a coroutine).\n +lua_stringtonumber lua_stringtonumber(lua_State *L, const char *s) [size_t]\nConverts the zero-terminated string `s` to a number, pushes that number into the stack, and\nreturns the total size of the string, that is, its length plus one. The conversion can result\nin an integer or a float, according to the lexical conventions of Lua (see §3.1). The string\nmay have leading and trailing whitespaces and a sign. If the string is not a valid numeral,\nreturns 0 and pushes nothing. (Note that the result can be used as a boolean, true if the\nconversion succeeds.)\n +lua_toboolean lua_toboolean(lua_State *L, int index) [int]\nConverts the Lua value at the given index to a C boolean value (0 or 1). Like all tests in\nLua, `lua_toboolean` returns true for any Lua value different from false and nil; otherwise it\nreturns false. (If you want to accept only actual boolean values, use `lua_isboolean` to test\nthe value's type.)\n +lua_toclose lua_toclose(lua_State *L, int index) [void]\nMarks the given index in the stack as a to-be-closed "variable" (see §3.3.8). Like a to-be-closed\nvariable in Lua, the value at that index in the stack will be closed when it goes out of scope.\nHere, in the context of a C function, to go out of scope means that the running function returns to\nLua, there is an error, or the index is removed from the stack through `lua_settop` or `lua_pop`.\nAn index marked as to-be-closed should not be removed from the stack by any other function in\nthe API except `lua_settop` or `lua_pop`.\n\nThis function should not be called for an index that is equal to or below an active to-be-closed\nindex.\n\nIn the case of an out-of-memory error, the value in the given index is immediately closed,\nas if it was already marked.\n\nNote that, both in case of errors and of a regular return, by the time the `__close` metamethod\nruns, the C stack was already unwound, so that any automatic C variable declared in the calling\nfunction will be out of scope.\n +lua_tocfunction lua_tocfunction(lua_State *L, int index) [lua_CFunction]\nConverts a value at the given index to a C function. That value must be a C function; otherwise,\nreturns `NULL`.\n lua_tointeger lua_tointeger(lua_State *L, int index) [lua_Integer]\nEquivalent to `lua_tointegerx` with `isnum` equal to `NULL`.\n -lua_tointegerx lua_tointegerx(lua_State *L, int index, int *isnum) [lua_Integer]\nConverts the Lua value at the given index to the signed integral type\n`lua_Integer`. The Lua value must be an integer, or a number or a string\nconvertible to an integer (see §3.4.3); otherwise, `lua_tointegerx` returns 0.\n\nIf `isnum` is not `NULL`, its referent is assigned a boolean value that\nindicates whether the operation succeeded.\n -lua_tolstring lua_tolstring(lua_State *L, int index, size_t *len) [const char*]\nConverts the Lua value at the given index to a C string. If `len` is not\n`NULL`, it sets `*len` with the string length. The Lua value must be a string\nor a number; otherwise, the function returns `NULL`. If the value is a number,\nthen `lua_tolstring` also _changes the actual value in the stack to a string_.\n(This change confuses `lua_next` when `lua_tolstring` is applied to keys during\na table traversal.)\n\n`lua_tolstring` returns a pointer to a string inside the Lua state (see §4.1.3). \nThis string always has a zero ('\0') after its last character (as in C), but can \ncontain other zeros in its body.\n +lua_tointegerx lua_tointegerx(lua_State *L, int index, int *isnum) [lua_Integer]\nConverts the Lua value at the given index to the signed integral type `lua_Integer`. The Lua\nvalue must be an integer, or a number or a string convertible to an integer (see §3.4.3);\notherwise, `lua_tointegerx` returns 0.\n\nIf `isnum` is not `NULL`, its referent is assigned a boolean value that indicates whether the\noperation succeeded.\n +lua_tolstring lua_tolstring(lua_State *L, int index, size_t *len) [const char*]\nConverts the Lua value at the given index to a C string. If `len` is not `NULL`, it sets `*len`\nwith the string length. The Lua value must be a string or a number; otherwise, the function\nreturns `NULL`. If the value is a number, then `lua_tolstring` also _changes the actual value\nin the stack to a string_. (This change confuses `lua_next` when `lua_tolstring` is applied\nto keys during a table traversal.)\n\n`lua_tolstring` returns a pointer to a string inside the Lua state (see §4.1.3). This string\nalways has a zero ('\0') after its last character (as in C), but can contain other zeros in\nits body.\n lua_tonumber lua_tonumber(lua_State *L, int index) [lua_Number]\nEquivalent to `lua_tonumberx` with `isnum` equal to `NULL`.\n -lua_tonumberx lua_tonumberx(lua_State *L, int index, int *isnum) [lua_Number]\nConverts the Lua value at the given index to the C type `lua_Number` (see\n`lua_Number`). The Lua value must be a number or a string convertible to a\nnumber (see §3.4.3); otherwise, `lua_tonumberx` returns 0.\n\nIf `isnum` is not `NULL`, its referent is assigned a boolean value that\nindicates whether the operation succeeded.\n -lua_topointer lua_topointer(lua_State *L, int index) [const void*]\nConverts the value at the given index to a generic C pointer (`void*`).\nThe value can be a userdata, a table, a thread, a string, or a function; \notherwise, `lua_topointer` returns `NULL`. Different objects will give \ndifferent pointers. There is no way to convert the pointer back to its original \nvalue.\n\nTypically this function is used only for debug information.\n +lua_tonumberx lua_tonumberx(lua_State *L, int index, int *isnum) [lua_Number]\nConverts the Lua value at the given index to the C type `lua_Number` (see `lua_Number`).\nThe Lua value must be a number or a string convertible to a number (see §3.4.3); otherwise,\n`lua_tonumberx` returns 0.\n\nIf `isnum` is not `NULL`, its referent is assigned a boolean value that indicates whether the\noperation succeeded.\n +lua_topointer lua_topointer(lua_State *L, int index) [const void*]\nConverts the value at the given index to a generic C pointer (`void*`). The value can be a\nuserdata, a table, a thread, a string, or a function; otherwise, `lua_topointer` returns `NULL`.\nDifferent objects will give different pointers. There is no way to convert the pointer back\nto its original value.\n\nTypically this function is used only for debug information.\n lua_tostring lua_tostring(lua_State *L, int index) [const char*]\nEquivalent to `lua_tolstring` with `len` equal to `NULL`.\n -lua_tothread lua_tothread(lua_State *L, int index) [lua_State*]\nConverts the value at the given index to a Lua thread (represented as\n`lua_State*`). This value must be a thread; otherwise, the function\nreturns `NULL`.\n -lua_touserdata lua_touserdata(lua_State *L, int index) [void*]\nIf the value at the given index is a full userdata, returns its memory-block \naddress. If the value is a light userdata, returns its value (a pointer). \nOtherwise, returns `NULL`.\n -lua_type lua_type(lua_State *L, int index) [int]\nReturns the type of the value in the given index, or `LUA_TNONE` for a non-valid\nbut acceptable index.\n\nThe types returned by `lua_type` are coded by the following constants defined in\n`lua.h`: `LUA_TNIL`, `LUA_TNUMBER`, `LUA_TBOOLEAN`, `LUA_TSTRING`, `LUA_TTABLE`,\n`LUA_TFUNCTION`, `LUA_TUSERDATA`, `LUA_TTHREAD`, and `LUA_TLIGHTUSERDATA`.\n -lua_typename lua_typename(lua_State *L, int tp) [const char*]\nReturns the name of the type encoded by the value `tp`, which must be one\nthe values returned by `lua_type`.\n +lua_tothread lua_tothread(lua_State *L, int index) [lua_State*]\nConverts the value at the given index to a Lua thread (represented as `lua_State*`). This value\nmust be a thread; otherwise, the function returns `NULL`.\n +lua_touserdata lua_touserdata(lua_State *L, int index) [void*]\nIf the value at the given index is a full userdata, returns its memory-block address. If the\nvalue is a light userdata, returns its value (a pointer). Otherwise, returns `NULL`.\n +lua_type lua_type(lua_State *L, int index) [int]\nReturns the type of the value in the given index, or `LUA_TNONE` for a non-valid but acceptable\nindex.\n\nThe types returned by `lua_type` are coded by the following constants defined in `lua.h`:\n`LUA_TNIL`, `LUA_TNUMBER`, `LUA_TBOOLEAN`, `LUA_TSTRING`, `LUA_TTABLE`, `LUA_TFUNCTION`,\n`LUA_TUSERDATA`, `LUA_TTHREAD`, and `LUA_TLIGHTUSERDATA`.\n +lua_typename lua_typename(lua_State *L, int tp) [const char*]\nReturns the name of the type encoded by the value `tp`, which must be one the values returned by\n`lua_type`.\n lua_Unsigned lua_Unsigned [typedef ... lua_Unsigned]\nThe unsigned version of `lua_Integer`.\n -lua_upvalueindex lua_upvalueindex(lua_State *L, int i) [int]\nReturns the pseudo-index that represents the `i`-th upvalue of the running\nfunction (see §4.2). `i` must be in the range *[1,256]*.\n +lua_upvalueindex lua_upvalueindex(lua_State *L, int i) [int]\nReturns the pseudo-index that represents the `i`-th upvalue of the running function (see §4.2).\n`i` must be in the range *[1,256]*.\n lua_version lua_version(lua_State *L) [lua_Number]\nReturns the version number of this core.\n -lua_WarnFunction lua_WarnFunction [void (*)(void *ud, const char *msg, int tocont)]\nThe type of warning functions, called by Lua to emit warnings. The first \nparameter is an opaque pointer set by `lua_setwarnf`. The second parameter is \nthe warning message. The third parameter is a boolean that indicates whether \nthe message is to be continued by the message in the next call.\n\nSee `warn` for more details about warnings.\n -lua_warning lua_warning(lua_State *L, const char *msg, int tocont) [void]\nEmits a warning with the given message. A message in a call with `tocont` true \nshould be continued in another call to this function.\n\nSee `warn` for more details about warnings.\n -lua_Writer (*lua_Writer)(lua_State *L, const void* p, size_t sz, void* ud) [int]\nThe type of the writer function used by `lua_dump`. Every time `lua_dump`\nproduces another piece of chunk, it calls the writer, passing along the buffer\nto be written (`p`), its size (`sz`), and the `ud` parameter supplied to\n`lua_dump`.\n\nThe writer returns an error code: 0 means no errors; any other value means\nan error and stops `lua_dump` from calling the writer again.\n -lua_xmove lua_xmove(lua_State *from, lua_State *to, int n) [void]\nExchange values between different threads of the same state.\n\nThis function pops `n` values from the stack `from`, and pushes them onto\nthe stack `to`.\n -lua_yield lua_yield(lua_State *L, int nresults) [int]\nThis function is equivalent to `lua_yieldk`, but it has no continuation\n(see §4.5). Therefore, when the thread resumes, it continues the function that\ncalled the function calling `lua_yield`. To avoid surprises, this function \nshould be called only in a tail call.\n -lua_yieldk lua_yieldk(lua_State *L, int nresults, lua_KContext ctx, lua_KFunction k) [int]\nYields a coroutine (thread).\n\nWhen a C function calls `lua_yieldk`, the running coroutine suspends its\nexecution, and the call to `lua_resume` that started this coroutine returns.\nThe parameter `nresults` is the number of values from the stack that will be\npassed as results to `lua_resume`.\n\nWhen the coroutine is resumed again, Lua calls the given continuation function\n`k` to continue the execution of the C function that yielded (see §4.5). This\ncontinuation function receives the same stack from the previous function, with\nthe `n` results removed and replaced by the arguments passed to `lua_resume`.\nMoreover, the continuation function receives the value `ctx` that was passed to\n`lua_yield`.\n\nUsually, this function does not return; when the coroutine eventually resumes,\nit continues executing the continuation function. However, there is one special\ncase, which is when this function is called from inside a line or a count hook\n(see §4.7). In that case, `lua_yieldk` should be called with no continuation\n(probably in the form of `lua_yield` and no results), and the hook should return\nimmediately after the call. Lua will yield and, when the coroutine resumes\nagain, it will continue the normal execution of the (Lua) function that\ntriggered the hook.\n\nThis function can raise an error if it is called from a thread with a pending C\ncall with no continuation function (what is called a *C-call boundary*), or it \nis called from a thread that is not running inside a resume (typically the main \nthread).\n -lua_Debug lua_Debug [struct]\ntypedef struct lua_Debug {\n int event;\n const char *name; /* (n) */\n const char *namewhat; /* (n) */\n const char *what; /* (S) */\n const char *source; /* (S) */\n size_t srclen; /* (S) */\n int currentline; /* (l) */\n int linedefined; /* (S) */\n int lastlinedefined; /* (S) */\n unsigned char nups; /* (u) number of upvalues */\n unsigned char nparams; /* (u) number of parameters */\n char isvararg; /* (u) */\n char istailcall; /* (t) */\n unsigned short ftransfer; /* (r) index of first value transferred */\n unsigned short ntransfer; /* (r) number of transferred values */\n char short_src[LUA_IDSIZE]; /* (S) */\n /* private part */\n _other fields_\n} lua_Debug;\n\nA structure used to carry different pieces of information about a function or an\nactivation record. `lua_getstack` fills only the private part of this\nstructure, for later use. To fill the other fields of `lua_Debug` with useful\ninformation, you must call `lua_getinfo`.\n\nThe fields of `lua_Debug` have the following meaning:\n * source: the source of the chunk that created the function. If `source`\n starts with a '`@`', it means that the function was defined in a file where\n the file name follows the '`@`'. If `source` starts with a '`=`', the\n remainder of its contents describes the source in a user-dependent manner.\n Otherwise, the function was defined in a string where `source` is that\n string.\n * srclen: The length of the string `source`.\n * short_src: a "printable" version of `source`, to be used in error messages.\n * linedefined: the line number where the definition of the function starts.\n * lastlinedefined: the line number where the definition of the function ends.\n * what: the string "Lua" if the function is a Lua function, "C" if it is a\n C function, "main" if it is the main part of a chunk.\n * currentline: the current line where the given function is executing.\n When no line information is available, `currentline` is set to -1.\n * name: a reasonable name for the given function. Because functions in Lua\n are first-class values, they do not have a fixed name: some functions\n can be the value of multiple global variables, while others can be\n stored only in a table field. The `lua_getinfo` function checks how the\n function was called to find a suitable name. If it cannot find a name,\n then `name` is set to `NULL`.\n * namewhat: explains the `name` field. The value of `namewhat` can be\n "global", "local", "method", "field", "upvalue", or "" (the empty string),\n according to how the function was called. (Lua uses the empty string\n when no other option seems to apply.)\n * istailcall: true if this function invocation was called by a tail call. In\n this case, the caller of this level is not in the stack.\n * nups: the number of upvalues of the function.\n * nparams: the number of parameters of the function (always 0 for C\n functions).\n * isvararg: true if the function is a vararg function (always true for C\n functions).\n * ftransfer: the index in the stack of the first value being "transferred",\n that is, parameters in a call or return values in a return. (The other \n values are in consecutive indices.) Using this index, you can access and \n modify these values through `lua_getlocal` and `lua_setlocal`. This field \n is only meaningful during a call hook, denoting the first parameter, or a \n return hook, denoting the first value being returned. (For call hooks, this \n value is always 1.)\n * ntransfer: The number of values being transferred (see previous item).\n (For calls of Lua functions, this value is always equal to `nparams`.)\n +lua_WarnFunction lua_WarnFunction [void (*)(void *ud, const char *msg, int tocont)]\nThe type of warning functions, called by Lua to emit warnings. The first parameter is an opaque\npointer set by `lua_setwarnf`. The second parameter is the warning message. The third parameter\nis a boolean that indicates whether the message is to be continued by the message in the next call.\n\nSee `warn` for more details about warnings.\n +lua_warning lua_warning(lua_State *L, const char *msg, int tocont) [void]\nEmits a warning with the given message. A message in a call with `tocont` true should be\ncontinued in another call to this function.\n\nSee `warn` for more details about warnings.\n +lua_Writer (*lua_Writer)(lua_State *L, const void* p, size_t sz, void* ud) [int]\nThe type of the writer function used by `lua_dump`. Every time `lua_dump` produces another\npiece of chunk, it calls the writer, passing along the buffer to be written (`p`), its size\n(`sz`), and the `ud` parameter supplied to `lua_dump`.\n\nThe writer returns an error code: 0 means no errors; any other value means an error and stops\n`lua_dump` from calling the writer again.\n +lua_xmove lua_xmove(lua_State *from, lua_State *to, int n) [void]\nExchange values between different threads of the same state.\n\nThis function pops `n` values from the stack `from`, and pushes them onto the stack `to`.\n +lua_yield lua_yield(lua_State *L, int nresults) [int]\nThis function is equivalent to `lua_yieldk`, but it has no continuation (see §4.5). Therefore,\nwhen the thread resumes, it continues the function that called the function calling `lua_yield`.\nTo avoid surprises, this function should be called only in a tail call.\n +lua_yieldk lua_yieldk(lua_State *L, int nresults, lua_KContext ctx, lua_KFunction k) [int]\nYields a coroutine (thread).\n\nWhen a C function calls `lua_yieldk`, the running coroutine suspends its execution, and the\ncall to `lua_resume` that started this coroutine returns. The parameter `nresults` is the\nnumber of values from the stack that will be passed as results to `lua_resume`.\n\nWhen the coroutine is resumed again, Lua calls the given continuation function `k` to continue\nthe execution of the C function that yielded (see §4.5). This continuation function receives\nthe same stack from the previous function, with the `n` results removed and replaced by the\narguments passed to `lua_resume`. Moreover, the continuation function receives the value `ctx`\nthat was passed to `lua_yield`.\n\nUsually, this function does not return; when the coroutine eventually resumes, it continues\nexecuting the continuation function. However, there is one special case, which is when this\nfunction is called from inside a line or a count hook (see §4.7). In that case, `lua_yieldk`\nshould be called with no continuation (probably in the form of `lua_yield` and no results),\nand the hook should return immediately after the call. Lua will yield and, when the coroutine\nresumes again, it will continue the normal execution of the (Lua) function that triggered the hook.\n\nThis function can raise an error if it is called from a thread with a pending C call with no\ncontinuation function (what is called a *C-call boundary*), or it is called from a thread that\nis not running inside a resume (typically the main thread).\n +lua_Debug lua_Debug [struct]\ntypedef struct lua_Debug {\n int event;\n const char *name; /* (n) */\n const char *namewhat; /* (n) */\n const char *what; /* (S) */\n const char *source; /* (S) */\n size_t srclen; /* (S) */\n int currentline; /* (l) */\n int linedefined; /* (S) */\n int lastlinedefined; /* (S) */\n unsigned char nups; /* (u) number of upvalues */\n unsigned char nparams; /* (u) number of parameters */\n char isvararg; /* (u) */\n char istailcall; /* (t) */\n unsigned short ftransfer; /* (r) index of first value transferred */\n unsigned short ntransfer; /* (r) number of transferred values */\n char short_src[LUA_IDSIZE]; /* (S) */\n /* private part */\n _other fields_\n} lua_Debug;\n\nA structure used to carry different pieces of information about a function or an activation record.\n`lua_getstack` fills only the private part of this structure, for later use. To fill the other\nfields of `lua_Debug` with useful information, you must call `lua_getinfo`.\n\nThe fields of `lua_Debug` have the following meaning:\n\n * source: the source of the chunk that created the function. If `source` starts with a '`@`',\n it means that the function was defined in a file where the file name follows the '`@`'.\n If `source` starts with a '`=`', the remainder of its contents describes the source in\n a user-dependent manner. Otherwise, the function was defined in a string where `source`\n is that string.\n * srclen: The length of the string `source`.\n * short_src: a "printable" version of `source`, to be used in error messages.\n * linedefined: the line number where the definition of the function starts.\n * lastlinedefined: the line number where the definition of the function ends.\n * what: the string "Lua" if the function is a Lua function, "C" if it is a C function, "main"\n if it is the main part of a chunk.\n * currentline: the current line where the given function is executing. When no line information\n is available, `currentline` is set to -1.\n * name: a reasonable name for the given function. Because functions in Lua are first-class\n values, they do not have a fixed name: some functions can be the value of multiple global\n variables, while others can be stored only in a table field. The `lua_getinfo` function\n checks how the function was called to find a suitable name. If it cannot find a name,\n then `name` is set to `NULL`.\n * namewhat: explains the `name` field. The value of `namewhat` can be "global", "local",\n "method", "field", "upvalue", or "" (the empty string), according to how the function\n was called. (Lua uses the empty string when no other option seems to apply.)\n * istailcall: true if this function invocation was called by a tail call. In this case,\n the caller of this level is not in the stack.\n * nups: the number of upvalues of the function.\n * nparams: the number of parameters of the function (always 0 for C functions).\n * isvararg: true if the function is a vararg function (always true for C functions).\n * ftransfer: the index in the stack of the first value being "transferred", that is, parameters\n in a call or return values in a return. (The other values are in consecutive indices.)\n Using this index, you can access and modify these values through `lua_getlocal` and\n `lua_setlocal`. This field is only meaningful during a call hook, denoting the first\n parameter, or a return hook, denoting the first value being returned. (For call hooks,\n this value is always 1.)\n * ntransfer: The number of values being transferred (see previous item). (For calls of Lua\n functions, this value is always equal to `nparams`.)\n lua_gethook lua_gethook(lua_State *L) [lua_Hook]\nReturns the current hook function.\n lua_gethookcount lua_gethookcount(lua_State *L) [int]\nReturns the current hook count.\n lua_gethookmask lua_gethookmask(lua_State *L) [int]\nReturns the current hook mask.\n -lua_getinfo lua_getinfo(lua_State *L, const char *what, lua_Debug *ar) [int]\nGets information about a specific function or function invocation.\n\nTo get information about a function invocation, the parameter `ar` must be a\nvalid activation record that was filled by a previous call to `lua_getstack`\nor given as argument to a hook (see `lua_Hook`).\n\nTo get information about a function you push it onto the stack and start the\n`what` string with the character '>'. (In that case, `lua_getinfo` pops the\nfunction from the top of the stack.) For instance, to know in which line a\nfunction `f` was defined, you can write the following code:\n\n lua_Debug ar;\n lua_getglobal(L, "f"); /* get global 'f' */\n lua_getinfo(L, ">S", &ar);\n printf("%d\\n", ar.linedefined);\n\nEach character in the string `what` selects some fields of the structure\n`ar` to be filled or a value to be pushed on the stack:\n * 'n': fills in the field `name` and `namewhat`;\n * 'S': fills in the fields `source`, `short_src`, `linedefined`,\n `lastlinedefined`, and `what`;\n * 'l': fills in the field `currentline`;\n * 't': fills in the field `istailcall`;\n * 'u': fills in the fields `nups`, `nparams`, and `isvararg`;\n * 'f': pushes onto the stack the function that is running at the given level;\n * 'L': pushes onto the stack a table whose indices are the numbers of the\n lines that are valid on the function. (A _valid line_ is a line with\n some associated code, that is, a line where you can put a break point.\n Non-valid lines include empty lines and comments.)\n \n If this option is given together with option 'f', its table is pushed after\n the function.\n \n This is the only option that can raise a memory error.\n\nThis function returns 0 to signal an invalid option in `what`; even then the\nvalid options are handled correctly.\n -lua_getlocal lua_getlocal(lua_State *L, const lua_Debug *ar, int n) [const char*]\nGets information about a local variable or a temporary value of a given \nactivation record or a given function.\n\nIn the first case, the parameter `ar` must be a valid activation record that was\nfilled by a previous call to `lua_getstack` or given as argument to a hook (see\n`lua_Hook`). The index `n` selects which local variable to inspect; see\n`debug.getlocal` for details about variable indices and names.\n\n`lua_getlocal` pushes the variable's value onto the stack and returns its name.\n\nIn the second case, `ar` must be `NULL` and the function to be inspected must\nbe on the top of the stack. In this case, only parameters of Lua functions are\nvisible (as there is no information about what variables are active) and no\nvalues are pushed onto the stack.\n\nReturns `NULL` (and pushes nothing) when the index is greater than the number of\nactive local variables.\n -lua_getstack lua_getstack(lua_State *L, int level, lua_Debug *ar) [int]\nGets information about the interpreter runtime stack.\n\nThis function fills parts of a `lua_Debug` structure with an identification of\nthe _activation record_ of the function executing at a given level. Level 0\nis the current running function, whereas level _n+1_ is the function that\nhas called level _n_ (except for tail calls, which do not count in the stack).\nWhen called with a level greater than the stack depth, `lua_getstack` returns 0; \notherwise it returns 1.\n -lua_getupvalue lua_getupvalue(lua_State *L, int funcindex, int n) [const char*]\nGets information about the `n`-th upvalue of the closure at index `funcindex`.\nIt pushes the upvalue's value onto the stack and returns its name. Returns \n`NULL` (and pushes nothing) when the index `n` is greater than the number of \nupvalues.\n\nSee `debug.getupvalue` for more information about upvalues.\n -lua_Hook (*lua_Hook)(lua_State *L, lua_Debug *ar) [void]\nType for debugging hook functions.\n\nWhenever a hook is called, its `ar` argument has its field `event` set to the\nspecific event that triggered the hook. Lua identifies these events with\nthe following constants: `LUA_HOOKCALL`, `LUA_HOOKRET`, `LUA_HOOKTAILCALL`,\n`LUA_HOOKLINE`, and `LUA_HOOKCOUNT`. Moreover, for line events, the\nfield `currentline` is also set. To get the value of any other field in\n`ar`, the hook must call `lua_getinfo`.\n\nFor call events, `event` can be `LUA_HOOKCALL`, the normal value, or\n`LUA_HOOKTAILCALL`, for a tail call; in this case, there will be no\ncorresponding return event.\n\nWhile Lua is running a hook, it disables other calls to hooks. Therefore,\nif a hook calls back Lua to execute a function or a chunk, this execution\noccurs without any calls to hooks.\n\nHook functions cannot have continuations, that is, they cannot call\n`lua_yieldk`, `lua_pcallk`, or `lua_callk` with a non-null `k`.\n\nHook functions can yield under the following conditions: Only count and line\nevents can yield and they cannot yield any value; to yield a hook function must\nfinish its execution calling `lua_yield` with `nresults` equal to zero.\n -lua_sethook lua_sethook(lua_State *L, lua_Hook f, int mask, int count) [void]\nSets the debugging hook function.\n\nArgument `f` is the hook function.\n\n`mask` specifies on which events the hook will be called: it is formed by a\nbitwise OR of the constants `LUA_MASKCALL`, `LUA_MASKRET`, `LUA_MASKLINE`,\nand `LUA_MASKCOUNT`. The `count` argument is only meaningful when the mask\nincludes `LUA_MASKCOUNT`. For each event, the hook is called as explained\nbelow:\n * The call hook: is called when the interpreter calls a function. The hook is\n called just after Lua enters the new function.\n * The return hook: is called when the interpreter returns from a function.\n The hook is called just before Lua leaves the function.\n * The line hook: is called when the interpreter is about to start the\n execution of a new line of code, or when it jumps back in the code (even\n to the same line). This event only happens while Lua is executing a\n Lua function.\n * The count hook: is called after the interpreter executes every `count`\n instructions. This event only happens while Lua is executing a Lua\n function.\n\nHooks are disabled by setting `mask` to zero.\n -lua_setlocal lua_setlocal(lua_State *L, const lua_Debug *ar, int n) [const char*]\nSets the value of a local variable of a given activation record. Parameters\n`ar` and `n` are as in `lua_getlocal` (see `lua_getlocal`). `lua_setlocal`\nassigns the value on the top of the stack to the variable and returns its name.\nIt also pops the value from the stack.\n\nReturns `NULL` (and pops nothing) when the index is greater than the number\nof active local variables.\n\nParameters `ar` and `n` are as in the function `lua_getlocal`.\n -lua_setupvalue lua_setupvalue(lua_State *L, int funcindex, int n) [const char*]\nSets the value of a closure's upvalue. It assigns the value on the top of\nthe stack to the upvalue and returns its name. It also pops the value from\nthe stack. Parameters `funcindex` and `n` are as in the `lua_getupvalue`\n(see `lua_getupvalue`).\n\nReturns `NULL` (and pops nothing) when the index is greater than the number\nof upvalues.\n\nParameters `funcindex` and `n` are as in the function `lua_getupvalue`.\n -lua_upvalueid lua_upvalueid(lua_State *L, int funcindex, int n) [void*]\nReturns a unique identifier for the upvalue numbered `n` from the closure at\nindex `funcindex`. Parameters `funcindex` and `n` are as in the\n`lua_getupvalue` (see `lua_getupvalue`) (but `n` cannot be greater than the\nnumber of upvalues).\n\nThese unique identifiers allow a program to check whether different closures\nshare upvalues. Lua closures that share an upvalue (that is, that access a same\nexternal local variable) will return identical ids for those upvalue indices.\n\nParameters `funcindex` and `n` are as in the function `lua_getupvalue`, but `n` \ncannot be greater than the number of upvalues.\n -lua_upvaluejoin lua_upvaluejoin(lua_State *L, int funcindex1, int n1, int funcindex2, int n2) [void]\nMake the `n1`-th upvalue of the Lua closure at index `funcindex1` refer to the\n`n2`-th upvalue of the Lua closure at index `funcindex2`.\n +lua_getinfo lua_getinfo(lua_State *L, const char *what, lua_Debug *ar) [int]\nGets information about a specific function or function invocation.\n\nTo get information about a function invocation, the parameter `ar` must be a valid activation\nrecord that was filled by a previous call to `lua_getstack` or given as argument to a hook (see\n`lua_Hook`).\n\nTo get information about a function you push it onto the stack and start the `what` string with\nthe character '>'. (In that case, `lua_getinfo` pops the function from the top of the stack.)\nFor instance, to know in which line a function `f` was defined, you can write the following code:\n\n lua_Debug ar;\n lua_getglobal(L, "f"); /* get global 'f' */\n lua_getinfo(L, ">S", &ar);\n printf("%d\n", ar.linedefined);\n\nEach character in the string `what` selects some fields of the structure `ar` to be filled or\na value to be pushed on the stack:\n\n * 'n': fills in the field `name` and `namewhat`;\n * 'S': fills in the fields `source`, `short_src`, `linedefined`, `lastlinedefined`, and `what`;\n * 'l': fills in the field `currentline`;\n * 't': fills in the field `istailcall`;\n * 'u': fills in the fields `nups`, `nparams`, and `isvararg`;\n * 'f': pushes onto the stack the function that is running at the given level;\n * 'L': pushes onto the stack a table whose indices are the numbers of the lines that are\n valid on the function. (A _valid line_ is a line with some associated code, that is,\n a line where you can put a break point. Non-valid lines include empty lines and comments.)\n\n If this option is given together with option 'f', its table is pushed after the function.\n\n This is the only option that can raise a memory error.\n\nThis function returns 0 to signal an invalid option in `what`; even then the valid options are\nhandled correctly.\n +lua_getlocal lua_getlocal(lua_State *L, const lua_Debug *ar, int n) [const char*]\nGets information about a local variable or a temporary value of a given activation record or\na given function.\n\nIn the first case, the parameter `ar` must be a valid activation record that was filled by a\nprevious call to `lua_getstack` or given as argument to a hook (see `lua_Hook`). The index\n`n` selects which local variable to inspect; see `debug.getlocal` for details about variable\nindices and names.\n\n`lua_getlocal` pushes the variable's value onto the stack and returns its name.\n\nIn the second case, `ar` must be `NULL` and the function to be inspected must be on the top\nof the stack. In this case, only parameters of Lua functions are visible (as there is no\ninformation about what variables are active) and no values are pushed onto the stack.\n\nReturns `NULL` (and pushes nothing) when the index is greater than the number of active local\nvariables.\n +lua_getstack lua_getstack(lua_State *L, int level, lua_Debug *ar) [int]\nGets information about the interpreter runtime stack.\n\nThis function fills parts of a `lua_Debug` structure with an identification of the _activation\nrecord_ of the function executing at a given level. Level 0 is the current running function,\nwhereas level _n+1_ is the function that has called level _n_ (except for tail calls, which do\nnot count in the stack). When called with a level greater than the stack depth, `lua_getstack`\nreturns 0; otherwise it returns 1.\n +lua_getupvalue lua_getupvalue(lua_State *L, int funcindex, int n) [const char*]\nGets information about the `n`-th upvalue of the closure at index `funcindex`. It pushes\nthe upvalue's value onto the stack and returns its name. Returns `NULL` (and pushes nothing)\nwhen the index `n` is greater than the number of upvalues.\n\nSee `debug.getupvalue` for more information about upvalues.\n +lua_Hook (*lua_Hook)(lua_State *L, lua_Debug *ar) [void]\nType for debugging hook functions.\n\nWhenever a hook is called, its `ar` argument has its field `event` set to the specific event that\ntriggered the hook. Lua identifies these events with the following constants: `LUA_HOOKCALL`,\n`LUA_HOOKRET`, `LUA_HOOKTAILCALL`, `LUA_HOOKLINE`, and `LUA_HOOKCOUNT`. Moreover, for line\nevents, the field `currentline` is also set. To get the value of any other field in `ar`,\nthe hook must call `lua_getinfo`.\n\nFor call events, `event` can be `LUA_HOOKCALL`, the normal value, or `LUA_HOOKTAILCALL`, for\na tail call; in this case, there will be no corresponding return event.\n\nWhile Lua is running a hook, it disables other calls to hooks. Therefore, if a hook calls back\nLua to execute a function or a chunk, this execution occurs without any calls to hooks.\n\nHook functions cannot have continuations, that is, they cannot call `lua_yieldk`, `lua_pcallk`,\nor `lua_callk` with a non-null `k`.\n\nHook functions can yield under the following conditions: Only count and line events can yield\nand they cannot yield any value; to yield a hook function must finish its execution calling\n`lua_yield` with `nresults` equal to zero.\n +lua_sethook lua_sethook(lua_State *L, lua_Hook f, int mask, int count) [void]\nSets the debugging hook function.\n\nArgument `f` is the hook function.\n\n`mask` specifies on which events the hook will be called: it is formed by a bitwise OR of the\nconstants `LUA_MASKCALL`, `LUA_MASKRET`, `LUA_MASKLINE`, and `LUA_MASKCOUNT`. The `count`\nargument is only meaningful when the mask includes `LUA_MASKCOUNT`. For each event, the hook\nis called as explained below:\n\n * The call hook: is called when the interpreter calls a function. The hook is called just\n after Lua enters the new function.\n * The return hook: is called when the interpreter returns from a function. The hook is called\n just before Lua leaves the function.\n * The line hook: is called when the interpreter is about to start the execution of a new\n line of code, or when it jumps back in the code (even to the same line). This event only\n happens while Lua is executing a Lua function.\n * The count hook: is called after the interpreter executes every `count` instructions.\n This event only happens while Lua is executing a Lua function.\n\nHooks are disabled by setting `mask` to zero.\n +lua_setlocal lua_setlocal(lua_State *L, const lua_Debug *ar, int n) [const char*]\nSets the value of a local variable of a given activation record. Parameters `ar` and `n` are\nas in `lua_getlocal` (see `lua_getlocal`). `lua_setlocal` assigns the value on the top of the\nstack to the variable and returns its name. It also pops the value from the stack.\n\nReturns `NULL` (and pops nothing) when the index is greater than the number of active local\nvariables.\n\nParameters `ar` and `n` are as in the function `lua_getlocal`.\n +lua_setupvalue lua_setupvalue(lua_State *L, int funcindex, int n) [const char*]\nSets the value of a closure's upvalue. It assigns the value on the top of the stack to the\nupvalue and returns its name. It also pops the value from the stack. Parameters `funcindex`\nand `n` are as in the `lua_getupvalue` (see `lua_getupvalue`).\n\nReturns `NULL` (and pops nothing) when the index is greater than the number of upvalues.\n\nParameters `funcindex` and `n` are as in the function `lua_getupvalue`.\n +lua_upvalueid lua_upvalueid(lua_State *L, int funcindex, int n) [void*]\nReturns a unique identifier for the upvalue numbered `n` from the closure at index `funcindex`.\nParameters `funcindex` and `n` are as in the `lua_getupvalue` (see `lua_getupvalue`) (but `n`\ncannot be greater than the number of upvalues).\n\nThese unique identifiers allow a program to check whether different closures share upvalues.\nLua closures that share an upvalue (that is, that access a same external local variable) will\nreturn identical ids for those upvalue indices.\n\nParameters `funcindex` and `n` are as in the function `lua_getupvalue`, but `n` cannot be\ngreater than the number of upvalues.\n +lua_upvaluejoin lua_upvaluejoin(lua_State *L, int funcindex1, int n1, int funcindex2, int n2) [void]\nMake the `n1`-th upvalue of the Lua closure at index `funcindex1` refer to the `n2`-th upvalue\nof the Lua closure at index `funcindex2`.\n luaL_addchar luaL_addchar(luaL_Buffer *B, char c) [void]\nAdds the byte `c` to the buffer `B` (see `luaL_Buffer`).\n -luaL_addgsub luaL_addgsub(luaL_Buffer *B, const char *s, const char *p, const char *r) [const void]\nAdds a copy of the string `s` to the buffer `B` (see `luaL_Buffer`), replacing \nany occurrence of the string `p` with the string `r`.\n -luaL_addlstring luaL_addlstring(luaL_Buffer *B, const char *s, size_t l) [void]\nAdds the string pointed to by `s` with length `l` to the buffer `B` (see\n`luaL_Buffer`). The string can contain embedded zeros.\n -luaL_addsize luaL_addsize(luaL_Buffer *B, size_t n) [void]\nAdds to the buffer `B` a string of length `n` previously copied to the buffer \narea (see `luaL_prepbuffer`).\n -luaL_addstring luaL_addstring(luaL_Buffer *B, const char *s) [void]\nAdds the zero-terminated string pointed to by `s` to the buffer `B` (see\n`luaL_Buffer`).\n -luaL_addvalue luaL_addvalue(luaL_Buffer *B) [void]\nAdds the value on the top of the stack to the buffer `B` (see `luaL_Buffer`).\nPops the value.\n\nThis is the only function on string buffers that can (and must) be called with\nan extra element on the stack, which is the value to be added to the buffer.\n -luaL_argcheck luaL_argcheck(lua_State *L, int cond, int arg, const char *extramsg) [void]\nChecks whether `cond` is true. If it is not, raises an error with a standard\nmessage (see `luaL_argerror`).\n -luaL_argerror luaL_argerror(lua_State *L, int arg, const char *extramsg) [int]\nRaises an error reporting a problem with argument `arg` of the C function that\ncalled it, using a standard message that includes `extramsg` as a comment:\n\n bad argument #_arg_ to '_funcname_' (_extramsg_)\n\nThis function never returns.\n -luaL_argexpected luaL_argexpected(lua_State *L, int cond, int arg, const char *tname) [void]\nChecks whether `cond` is true. If it is not, raises an error about the type of \nthe argument `arg` with a standard message (see `luaL_typeerror`).\n -luaL_Buffer luaL_Buffer [struct]\nType for a _string buffer_.\n\nA string buffer allows C code to build Lua strings piecemeal. Its pattern\nof use is as follows:\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it with a call `luaL_buffinit(L, &b)`.\n * Then add string pieces to the buffer calling any of the `luaL_add*`\n functions.\n * Finish by calling `luaL_pushresult(&b)`. This call leaves the final string\n on the top of the stack.\n\nIf you know beforehand the maximum size of the resulting string, you can use the\nbuffer like this:\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it and preallocate a space of size `sz` with a call\n `luaL_buffinitsize(L, &b, sz)`.\n * Then produce the string into that space.\n * Finish by calling `luaL_pushresultsize(&b, sz)`, where `sz` is the total\n size of the resulting string copied into that space (which may be less than\n or equal to the preallocated size).\n\nDuring its normal operation, a string buffer uses a variable number of\nstack slots. So, while using a buffer, you cannot assume that you know\nwhere the top of the stack is. You can use the stack between successive\ncalls to buffer operations as long as that use is balanced; that is, when you\ncall a buffer operation, the stack is at the same level it was immediately\nafter the previous buffer operation. (The only exception to this rule is\n`luaL_addvalue`.) After calling `luaL_pushresult`, the stack is back to its\nlevel when the buffer was initialized, plus the final string on its top.\n -luaL_buffaddr luaL_buffaddr(luaL_Buffer *B) [char*]\nReturns the address of the current content of buffer `B` (see `luaL_Buffer`).\nNote that any addition to the buffer may invalidate this address.\n -luaL_buffinit luaL_buffinit(lua_State *L, luaL_Buffer *B) [void]\nInitializes a buffer `B` (see `luaL_Buffer`). This function does not allocate \nany space; the buffer must be declared as a variable.\n +luaL_addgsub luaL_addgsub(luaL_Buffer *B, const char *s, const char *p, const char *r) [const void]\nAdds a copy of the string `s` to the buffer `B` (see `luaL_Buffer`), replacing any occurrence\nof the string `p` with the string `r`.\n +luaL_addlstring luaL_addlstring(luaL_Buffer *B, const char *s, size_t l) [void]\nAdds the string pointed to by `s` with length `l` to the buffer `B` (see `luaL_Buffer`).\nThe string can contain embedded zeros.\n +luaL_addsize luaL_addsize(luaL_Buffer *B, size_t n) [void]\nAdds to the buffer `B` a string of length `n` previously copied to the buffer area (see\n`luaL_prepbuffer`).\n +luaL_addstring luaL_addstring(luaL_Buffer *B, const char *s) [void]\nAdds the zero-terminated string pointed to by `s` to the buffer `B` (see `luaL_Buffer`).\n +luaL_addvalue luaL_addvalue(luaL_Buffer *B) [void]\nAdds the value on the top of the stack to the buffer `B` (see `luaL_Buffer`). Pops the value.\n\nThis is the only function on string buffers that can (and must) be called with an extra element\non the stack, which is the value to be added to the buffer.\n +luaL_argcheck luaL_argcheck(lua_State *L, int cond, int arg, const char *extramsg) [void]\nChecks whether `cond` is true. If it is not, raises an error with a standard message (see\n`luaL_argerror`).\n +luaL_argerror luaL_argerror(lua_State *L, int arg, const char *extramsg) [int]\nRaises an error reporting a problem with argument `arg` of the C function that called it,\nusing a standard message that includes `extramsg` as a comment:\n\n bad argument #_arg_ to '_funcname_' (_extramsg_)\n\nThis function never returns.\n +luaL_argexpected luaL_argexpected(lua_State *L, int cond, int arg, const char *tname) [void]\nChecks whether `cond` is true. If it is not, raises an error about the type of the argument\n`arg` with a standard message (see `luaL_typeerror`).\n +luaL_Buffer luaL_Buffer [struct]\nType for a _string buffer_.\n\nA string buffer allows C code to build Lua strings piecemeal. Its pattern of use is as follows:\n\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it with a call `luaL_buffinit(L, &b)`.\n * Then add string pieces to the buffer calling any of the `luaL_add*` functions.\n * Finish by calling `luaL_pushresult(&b)`. This call leaves the final string on the top of\n the stack.\n\nIf you know beforehand the maximum size of the resulting string, you can use the buffer like this:\n\n * First declare a variable `b` of type `luaL_Buffer`.\n * Then initialize it and preallocate a space of size `sz` with a call\n `luaL_buffinitsize(L, &b, sz)`.\n * Then produce the string into that space.\n * Finish by calling `luaL_pushresultsize(&b, sz)`, where `sz` is the total size of the resulting\n string copied into that space (which may be less than or equal to the preallocated size).\n\nDuring its normal operation, a string buffer uses a variable number of stack slots. So,\nwhile using a buffer, you cannot assume that you know where the top of the stack is. You can\nuse the stack between successive calls to buffer operations as long as that use is balanced;\nthat is, when you call a buffer operation, the stack is at the same level it was immediately\nafter the previous buffer operation. (The only exception to this rule is `luaL_addvalue`.)\nAfter calling `luaL_pushresult`, the stack is back to its level when the buffer was initialized,\nplus the final string on its top.\n +luaL_buffaddr luaL_buffaddr(luaL_Buffer *B) [char*]\nReturns the address of the current content of buffer `B` (see `luaL_Buffer`). Note that any\naddition to the buffer may invalidate this address.\n +luaL_buffinit luaL_buffinit(lua_State *L, luaL_Buffer *B) [void]\nInitializes a buffer `B` (see `luaL_Buffer`). This function does not allocate any space;\nthe buffer must be declared as a variable.\n luaL_bufflen luaL_bufflen(luaL_Buffer *B) [size_t]\nReturns the length of the current content of buffer `B` (see `luaL_Buffer`).\n luaL_buffinitsize luaL_buffinitsize(lua_State *L, luaL_Buffer *B, size_t sz) [char*]\nEquivalent to the sequence `luaL_buffinit`, `luaL_prepbuffsize`.\n -luaL_buffsub luaL_buffsub(luaL_Buffer *B, int n) [void]\nRemoves `n` bytes from the the buffer `B` (see `luaL_Buffer`). The buffer must \nhave at least that many bytes.\n -luaL_callmeta luaL_callmeta(lua_State *L, int obj, const char *e) [int]\nCalls a metamethod.\n\nIf the object at index `obj` has a metatable and this metatable has a field\n`e`, this function calls this field passing the object as its only argument.\nIn this case this function returns true and pushes onto the stack the value\nreturned by the call. If there is no metatable or no metamethod, this function\nreturns false without pushing any value on the stack.\n -luaL_checkany luaL_checkany(lua_State *L, int arg) [void]\nChecks whether the function has an argument of any type (including nil)\nat position `arg`.\n -luaL_checkinteger luaL_checkinteger(lua_State *L, int arg) [lua_Integer]\nChecks whether the function argument `arg` is an integer (or can be converted to\nan integer) and returns this integer.\n -luaL_checklstring luaL_checklstring(lua_State *L, int arg, size_t *l) [const char*]\nChecks whether the function argument `arg` is a string and returns this string;\nif `l` is not `NULL` fills its referent with the string's length.\n\nThis function uses `lua_tolstring` to get its result, so all conversions\nand caveats of that function apply here.\n -luaL_checknumber luaL_checknumber(lua_State *L, int arg) [lua_Number]\nChecks whether the function argument `arg` is a number and returns this number\nconverted to a `lua_Number`.\n -luaL_checkoption luaL_checkoption(lua_State *L, int arg, const char *def, const char *const lst[]) [int]\nChecks whether the function argument `arg` is a string and searches for this\nstring in the array `lst` (which must be NULL-terminated). Returns the index\nin the array where the string was found. Raises an error if the argument\nis not a string or if the string cannot be found.\n\nIf `def` is not `NULL`, the function uses `def` as a default value when\nthere is no argument `arg` or when this argument is nil.\n\nThis is a useful function for mapping strings to C enums. (The usual\nconvention in Lua libraries is to use strings instead of numbers to select\noptions.)\n -luaL_checkstack luaL_checkstack(lua_State *L, int sz, const char *msg) [void]\nGrows the stack size to `top + sz` elements, raising an error if the stack\ncannot grow to that size. `msg` is an additional text to go into the error\nmessage (or `NULL` for no additional text).\n -luaL_checkstring luaL_checkstring(lua_State *L, int arg) [const char*]\nChecks whether the function argument `arg` is a string and returns this string.\n\nThis function uses `lua_tolstring` to get its result, so all conversions\nand caveats of that function apply here.\n -luaL_checktype luaL_checktype(lua_State *L, int arg, int t) [void]\nChecks whether the function argument `arg` has type `t`. See `lua_type` for\nthe encoding of types for `t`.\n -luaL_checkudata luaL_checkudata(lua_State *L, int arg, const char *tname) [void*]\nChecks whether the function argument `arg` is a userdata of the type `tname`\n(see `luaL_newmetatable`) and returns the userdata's memory-block address (see\n`lua_touserdata`).\n -luaL_checkversion luaL_checkversion(lua_State *L) [void]\nChecks whether the code making the call and the Lua library being called are \nusing the same version of Lua and the same numeric types.\n -luaL_dofile luaL_dofile(lua_State *L, const char *filename) [int]\nLoads and runs the given file. It is defined as the following macro:\n\n (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\nIt returns `LUA_OK` if there are no errors, or an error code in case of errors\n(see §4.4.1).\n -luaL_dostring luaL_dostring(lua_State *L, const char *str) [int]\nLoads and runs the given string. It is defined as the following macro:\n\n (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\nIt returns `LUA_OK` if there are no errors, or an error code in case of errors\n(see §4.4.1).\n -luaL_error luaL_error(lua_State *L, const char *fmt, ...) [int]\nRaises an error. The error message format is given by `fmt` plus any extra\narguments, following the same rules of `lua_pushfstring`. It also adds at\nthe beginning of the message the file name and the line number where the\nerror occurred, if this information is available.\n\nThis function never returns, but it is an idiom to use it in C functions as\n`return luaL_error(args)`.\n -luaL_execresult luaL_execresult(lua_State *L, int stat) [int]\nThis function produces the return values for process-related functions in the\nstandard library (`os.execute` and `io.close`).\n -luaL_fileresult luaL_fileresult(lua_State *L, int stat, const char *fname) [int]\nThis function produces the return values for file-related functions in the\nstandard library (`io.open`, `os.rename`, `file:seek`, etc.).\n -luaL_getmetafield luaL_getmetafield(lua_State *L, int obj, const char *e) [int]\nPushes onto the stack the field `e` from the metatable of the object at index\n`obj` and returns the type of pushed value. If the object does not have a metatable, or if the metatable does\nnot have this field, pushes nothing and returns `LUA_TNIL`.\n -luaL_getmetatable luaL_getmetatable(lua_State *L, const char *tname) [int]\nPushes onto the stack the metatable associated with the name `tname` in the\nregistry (see `luaL_newmetatable`), or nil if there is no metatable associated \nwith that name. Returns the type of that pushed value.\n -luaL_getsubtable luaL_getsubtable(lua_State *L, int idx, const char *fname) [int]\nEnsures that the value `t[fname]`, where `t` is the value at index `idx`, is\na table, and pushes that table onto the stack. Returns true if it finds a\nprevious table there and false if it creates a new table.\n -luaL_gsub luaL_gsub(lua_State *L, const char *s, const char *p, const char *r) [const char*]\nCreates a copy of string `s`, replacing any occurrence of the string `p` with \nthe string `r`. Pushes the resulting string on the stack and returns it.\n -luaL_len luaL_len(lua_State *L, int index) [lua_Integer]\nReturns the "length" of the value at the given index as a number; it is\nequivalent to the '`#`' operator in Lua (see §3.4.7). Raises an error if the\nresult of the operation is not an integer. (This case can only happen through\nmetamethods.)\n +luaL_buffsub luaL_buffsub(luaL_Buffer *B, int n) [void]\nRemoves `n` bytes from the the buffer `B` (see `luaL_Buffer`). The buffer must have at least\nthat many bytes.\n +luaL_callmeta luaL_callmeta(lua_State *L, int obj, const char *e) [int]\nCalls a metamethod.\n\nIf the object at index `obj` has a metatable and this metatable has a field `e`, this function\ncalls this field passing the object as its only argument. In this case this function returns\ntrue and pushes onto the stack the value returned by the call. If there is no metatable or no\nmetamethod, this function returns false without pushing any value on the stack.\n +luaL_checkany luaL_checkany(lua_State *L, int arg) [void]\nChecks whether the function has an argument of any type (including nil) at position `arg`.\n +luaL_checkinteger luaL_checkinteger(lua_State *L, int arg) [lua_Integer]\nChecks whether the function argument `arg` is an integer (or can be converted to an integer)\nand returns this integer.\n +luaL_checklstring luaL_checklstring(lua_State *L, int arg, size_t *l) [const char*]\nChecks whether the function argument `arg` is a string and returns this string; if `l` is not\n`NULL` fills its referent with the string's length.\n\nThis function uses `lua_tolstring` to get its result, so all conversions and caveats of that\nfunction apply here.\n +luaL_checknumber luaL_checknumber(lua_State *L, int arg) [lua_Number]\nChecks whether the function argument `arg` is a number and returns this number converted to a\n`lua_Number`.\n +luaL_checkoption luaL_checkoption(lua_State *L, int arg, const char *def, const char *const lst[]) [int]\nChecks whether the function argument `arg` is a string and searches for this string in the array\n`lst` (which must be NULL-terminated). Returns the index in the array where the string was found.\nRaises an error if the argument is not a string or if the string cannot be found.\n\nIf `def` is not `NULL`, the function uses `def` as a default value when there is no argument\n`arg` or when this argument is nil.\n\nThis is a useful function for mapping strings to C enums. (The usual convention in Lua libraries\nis to use strings instead of numbers to select options.)\n +luaL_checkstack luaL_checkstack(lua_State *L, int sz, const char *msg) [void]\nGrows the stack size to `top + sz` elements, raising an error if the stack cannot grow to that\nsize. `msg` is an additional text to go into the error message (or `NULL` for no additional text).\n +luaL_checkstring luaL_checkstring(lua_State *L, int arg) [const char*]\nChecks whether the function argument `arg` is a string and returns this string.\n\nThis function uses `lua_tolstring` to get its result, so all conversions and caveats of that\nfunction apply here.\n +luaL_checktype luaL_checktype(lua_State *L, int arg, int t) [void]\nChecks whether the function argument `arg` has type `t`. See `lua_type` for the encoding of\ntypes for `t`.\n +luaL_checkudata luaL_checkudata(lua_State *L, int arg, const char *tname) [void*]\nChecks whether the function argument `arg` is a userdata of the type `tname` (see\n`luaL_newmetatable`) and returns the userdata's memory-block address (see `lua_touserdata`).\n +luaL_checkversion luaL_checkversion(lua_State *L) [void]\nChecks whether the code making the call and the Lua library being called are using the same\nversion of Lua and the same numeric types.\n +luaL_dofile luaL_dofile(lua_State *L, const char *filename) [int]\nLoads and runs the given file. It is defined as the following macro:\n\n (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\nIt returns `LUA_OK` if there are no errors, or an error code in case of errors (see §4.4.1).\n +luaL_dostring luaL_dostring(lua_State *L, const char *str) [int]\nLoads and runs the given string. It is defined as the following macro:\n\n (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\nIt returns `LUA_OK` if there are no errors, or an error code in case of errors (see §4.4.1).\n +luaL_error luaL_error(lua_State *L, const char *fmt, ...) [int]\nRaises an error. The error message format is given by `fmt` plus any extra arguments, following\nthe same rules of `lua_pushfstring`. It also adds at the beginning of the message the file\nname and the line number where the error occurred, if this information is available.\n\nThis function never returns, but it is an idiom to use it in C functions as `return\nluaL_error(args)`.\n +luaL_execresult luaL_execresult(lua_State *L, int stat) [int]\nThis function produces the return values for process-related functions in the standard library\n(`os.execute` and `io.close`).\n +luaL_fileresult luaL_fileresult(lua_State *L, int stat, const char *fname) [int]\nThis function produces the return values for file-related functions in the standard library\n(`io.open`, `os.rename`, `file:seek`, etc.).\n +luaL_getmetafield luaL_getmetafield(lua_State *L, int obj, const char *e) [int]\nPushes onto the stack the field `e` from the metatable of the object at index `obj` and returns\nthe type of pushed value. If the object does not have a metatable, or if the metatable does\nnot have this field, pushes nothing and returns `LUA_TNIL`.\n +luaL_getmetatable luaL_getmetatable(lua_State *L, const char *tname) [int]\nPushes onto the stack the metatable associated with the name `tname` in the registry (see\n`luaL_newmetatable`), or nil if there is no metatable associated with that name. Returns the\ntype of that pushed value.\n +luaL_getsubtable luaL_getsubtable(lua_State *L, int idx, const char *fname) [int]\nEnsures that the value `t[fname]`, where `t` is the value at index `idx`, is a table, and\npushes that table onto the stack. Returns true if it finds a previous table there and false\nif it creates a new table.\n +luaL_gsub luaL_gsub(lua_State *L, const char *s, const char *p, const char *r) [const char*]\nCreates a copy of string `s`, replacing any occurrence of the string `p` with the string `r`.\nPushes the resulting string on the stack and returns it.\n +luaL_len luaL_len(lua_State *L, int index) [lua_Integer]\nReturns the "length" of the value at the given index as a number; it is equivalent to the '`#`'\noperator in Lua (see §3.4.7). Raises an error if the result of the operation is not an integer.\n(This case can only happen through metamethods.)\n luaL_loadbuffer luaL_loadbuffer(lua_State *L, const char *buff, size_t sz, const char *name) [int]\nEquivalent to `luaL_loadbufferx` with `mode` equal to `NULL`.\n -luaL_loadbufferx luaL_loadbufferx(lua_State *L, const char *buff, size_t sz, const char *name, const char *mode) [int]\nLoads a buffer as a Lua chunk. This function uses `lua_load` to load the\nchunk in the buffer pointed to by `buff` with size `sz`.\n\nThis function returns the same results as `lua_load`. `name` is the chunk\nname, used for debug information and error messages. The string `mode` works as\nin the function `lua_load`.\n +luaL_loadbufferx luaL_loadbufferx(lua_State *L, const char *buff, size_t sz, const char *name, const char *mode) [int]\nLoads a buffer as a Lua chunk. This function uses `lua_load` to load the chunk in the buffer\npointed to by `buff` with size `sz`.\n\nThis function returns the same results as `lua_load`. `name` is the chunk name, used for debug\ninformation and error messages. The string `mode` works as in the function `lua_load`.\n luaL_loadfile luaL_loadfile(lua_State *L, const char *filename) [int]\nEquivalent to `luaL_loadfilex` with `mode` equal to `NULL`.\n -luaL_loadfilex luaL_loadfilex(lua_State *L, const char *filename, const char *mode) [int]\nLoads a file as a Lua chunk. This function uses `lua_load` to load the chunk\nin the file named `filename`. If `filename` is `NULL`, then it loads from the\nstandard input. The first line in the file is ignored if it starts with a `#`.\n\nThe string `mode` works as in the function `lua_load`.\n\nThis function returns the same results as `lua_load` or `LUA_ERRFILE` for \nfile-related errors.\n\nAs `lua_load`, this function only loads the chunk; it does not run it.\n -luaL_loadstring luaL_loadstring(lua_State *L, const char *s) [int]\nLoads a string as a Lua chunk. This function uses `lua_load` to load the\nchunk in the zero-terminated string `s`.\n\nThis function returns the same results as `lua_load`.\n\nAlso as `lua_load`, this function only loads the chunk; it does not run it.\n -luaL_newlib luaL_newlib(lua_State *L, const luaL_Reg l[]) [void]\nCreates a new table and registers there the functions in the list `l`.\n\nIt is implemented as the following macro:\n\n (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))\n \nThe array `l` must be the actual array, not a pointer to it.\n -luaL_newlibtable luaL_newlibtable(lua_State *L, const luaL_Reg l[]) [void]\nCreates a new table with a size optimized to store all entries in the array `l`\n(but does not actually store them). It is intended to be used in conjunction\nwith `luaL_setfuncs` (see `luaL_newlib`).\n\nIt is implemented as a macro. The array `l` must be the actual array, not a\npointer to it.\n -luaL_newmetatable luaL_newmetatable(lua_State *L, const char *tname) [int]\nIf the registry already has the key `tname`, returns 0. Otherwise, creates a\nnew table to be used as a metatable for userdata, adds to this new table the\npair `__name = tname`, adds to the registry the pair `[tname] = new table`, and\nreturns 1.\n\nIn both cases, the function pushes onto the stack the final value associated \nwith `tname` in the registry.\n -luaL_newstate luaL_newstate(void) [lua_State*]\nCreates a new Lua state. It calls `lua_newstate` with an allocator based\non the standard C allocation functions and then sets a warning function and a \npanic function (see §4.4) that print messages to the standard error output.\n\nReturns the new state, or `NULL` if there is a memory allocation error.\n +luaL_loadfilex luaL_loadfilex(lua_State *L, const char *filename, const char *mode) [int]\nLoads a file as a Lua chunk. This function uses `lua_load` to load the chunk in the file named\n`filename`. If `filename` is `NULL`, then it loads from the standard input. The first line\nin the file is ignored if it starts with a `#`.\n\nThe string `mode` works as in the function `lua_load`.\n\nThis function returns the same results as `lua_load` or `LUA_ERRFILE` for file-related errors.\n\nAs `lua_load`, this function only loads the chunk; it does not run it.\n +luaL_loadstring luaL_loadstring(lua_State *L, const char *s) [int]\nLoads a string as a Lua chunk. This function uses `lua_load` to load the chunk in the\nzero-terminated string `s`.\n\nThis function returns the same results as `lua_load`.\n\nAlso as `lua_load`, this function only loads the chunk; it does not run it.\n +luaL_newlib luaL_newlib(lua_State *L, const luaL_Reg l[]) [void]\nCreates a new table and registers there the functions in the list `l`.\n\nIt is implemented as the following macro:\n\n (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))\n\nThe array `l` must be the actual array, not a pointer to it.\n +luaL_newlibtable luaL_newlibtable(lua_State *L, const luaL_Reg l[]) [void]\nCreates a new table with a size optimized to store all entries in the array `l` (but does\nnot actually store them). It is intended to be used in conjunction with `luaL_setfuncs` (see\n`luaL_newlib`).\n\nIt is implemented as a macro. The array `l` must be the actual array, not a pointer to it.\n +luaL_newmetatable luaL_newmetatable(lua_State *L, const char *tname) [int]\nIf the registry already has the key `tname`, returns 0. Otherwise, creates a new table to be\nused as a metatable for userdata, adds to this new table the pair `__name = tname`, adds to\nthe registry the pair `[tname] = new table`, and returns 1.\n\nIn both cases, the function pushes onto the stack the final value associated with `tname`\nin the registry.\n +luaL_newstate luaL_newstate(void) [lua_State*]\nCreates a new Lua state. It calls `lua_newstate` with an allocator based on the standard C\nallocation functions and then sets a warning function and a panic function (see §4.4) that\nprint messages to the standard error output.\n\nReturns the new state, or `NULL` if there is a memory allocation error.\n luaL_openlibs luaL_openlibs(lua_State *L) [void]\nOpens all standard Lua libraries into the given state.\n -luaL_opt luaL_opt(L, func, arg, dflt);\nThis macro is defined as follows:\n (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))\nIn words, if the argument `arg` is nil or absent, the macro results in the\ndefault `dflt`. Otherwise, it results in the result of calling `func` with the\nstate `L` and the argument index `arg` as parameters. Note that it evaluates \nthe expression `dflt` only if needed.\n -luaL_optinteger luaL_optinteger(lua_State *L, int arg, lua_Integer d) [lua_Integer]\nIf the function argument `arg` is an integer (or it is convertable to an \ninteger), returns this integer. If this argument is absent or is nil, returns \n`d`. Otherwise, raises an error.\n -luaL_optlstring luaL_optlstring(lua_State *L, int arg, const char *d, size_t *l) [const char*]\nIf the function argument `arg` is a string, returns this string. If this\nargument is absent or is nil, returns `d`. Otherwise, raises an error.\n\nIf `l` is not `NULL`, fills its referent with the result's length. If the\nresult is `NULL` (only possible when returning `d` and `d == NULL`), its length\nis considered zero.\n -luaL_optnumber luaL_optnumber(lua_State *L, int arg, lua_Number d) [lua_Number]\nIf the function argument `arg` is a number, returns this number as a \n`lua_Number`. If this argument is absent or is nil, returns `d`. Otherwise, \nraises an error.\n -luaL_optstring luaL_optstring(lua_State *L, int arg, const char *d) [const char*]\nIf the function argument `arg` is a string, returns this string. If this\nargument is absent or is nil, returns `d`. Otherwise, raises an error.\n +luaL_opt luaL_opt(L, func, arg, dflt);\nThis macro is defined as follows:\n\n (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))\n\nIn words, if the argument `arg` is nil or absent, the macro results in the default `dflt`.\nOtherwise, it results in the result of calling `func` with the state `L` and the argument index\n`arg` as parameters. Note that it evaluates the expression `dflt` only if needed.\n +luaL_optinteger luaL_optinteger(lua_State *L, int arg, lua_Integer d) [lua_Integer]\nIf the function argument `arg` is an integer (or it is convertable to an integer), returns\nthis integer. If this argument is absent or is nil, returns `d`. Otherwise, raises an error.\n +luaL_optlstring luaL_optlstring(lua_State *L, int arg, const char *d, size_t *l) [const char*]\nIf the function argument `arg` is a string, returns this string. If this argument is absent\nor is nil, returns `d`. Otherwise, raises an error.\n\nIf `l` is not `NULL`, fills its referent with the result's length. If the result is `NULL`\n(only possible when returning `d` and `d == NULL`), its length is considered zero.\n +luaL_optnumber luaL_optnumber(lua_State *L, int arg, lua_Number d) [lua_Number]\nIf the function argument `arg` is a number, returns this number as a `lua_Number`. If this\nargument is absent or is nil, returns `d`. Otherwise, raises an error.\n +luaL_optstring luaL_optstring(lua_State *L, int arg, const char *d) [const char*]\nIf the function argument `arg` is a string, returns this string. If this argument is absent\nor is nil, returns `d`. Otherwise, raises an error.\n luaL_prepbuffer luaL_prepbuffer(luaL_Buffer *B) [char*]\nEquivalent to `luaL_prepbuffsize` with the predefined size `LUAL_BUFFERSIZE`.\n -luaL_prepbuffsize luaL_prepbuffsize(luaL_Buffer *B, size_t sz) [char*]\nReturns an address to a space of size `LUAL_BUFFERSIZE` where you can copy\na string to be added to buffer `B` (see `luaL_Buffer`). After copying the\nstring into this space you must call `luaL_addsize` with the size of the\nstring to actually add it to the buffer.\n +luaL_prepbuffsize luaL_prepbuffsize(luaL_Buffer *B, size_t sz) [char*]\nReturns an address to a space of size `LUAL_BUFFERSIZE` where you can copy a string to be added\nto buffer `B` (see `luaL_Buffer`). After copying the string into this space you must call\n`luaL_addsize` with the size of the string to actually add it to the buffer.\n luaL_pushfail luaL_pushfail(lua_State *L) [void]\nPushes the fail value onto the stack (see §6).\n -luaL_pushresult luaL_pushresult(luaL_Buffer *B) [void]\nFinishes the use of buffer `B` leaving the final string on the top of\nthe stack.\n +luaL_pushresult luaL_pushresult(luaL_Buffer *B) [void]\nFinishes the use of buffer `B` leaving the final string on the top of the stack.\n luaL_pushresultsize luaL_pushresultsize(luaL_Buffer *B, size_t sz) [void]\nEquivalent to the sequence `luaL_addsize`, `luaL_pushresult`.\n -luaL_ref luaL_ref(lua_State *L, int t) [int]\nCreates and returns a _reference_, in the table at index `t`, for the object\non the top of the stack (and pops the object).\n\nA reference is a unique integer key. As long as you do not manually add\ninteger keys into the table `t`, `luaL_ref` ensures the uniqueness of the key\nit returns. You can retrieve an object referred by the reference `r` by calling\n`lua_rawgeti(L, t, r)`. The function `luaL_unref` frees a reference.\n\nIf the object on the top of the stack is nil, `luaL_ref` returns the constant\n`LUA_REFNIL`. The constant `LUA_NOREF` is guaranteed to be different from\nany reference returned by `luaL_ref`.\n -luaL_Reg luaL_Reg [struct]\ntypedef struct luaL_Reg {\n const char *name;\n lua_CFunction func;\n} luaL_Reg;\n\nType for arrays of functions to be registered by `luaL_setfuncs\nis the function name and `func` is a pointer to the function. Any array of\n`luaL_Reg` must end with a sentinel entry in which both `name` and `func`\nare `NULL`.\n -luaL_requiref luaL_requiref(lua_State *L, const char *modname, lua_CFunction openf, int glb) [void]\nIf `package.loaded[modname]` is not true, calls the function `openf` with the\nstring `modname` as an argument and sets the call result to\n`package.loaded[modname]`, as if that function has been called through\n`require`.\n\nIf `glb` is true, also stores the module into the global `modname`.\n\nLeaves a copy of the module on the stack.\n -luaL_setfuncs luaL_setfuncs(lua_State *L, const luaL_Reg *l, int nup) [void]\nRegisters all functions in the array `l` (see `luaL_Reg`) into the table on the\ntop of the stack (below optional upvalues, see next).\n\nWhen `nup` is not zero, all functions are created with `nup` upvalues, \ninitialized with copies of the `nup` values previously pushed on the stack on \ntop of the library table. These values are popped from the stack after the \nregistration.\n -luaL_setmetatable luaL_setmetatable(lua_State *L, const char *tname) [void]\nSets the metatable of the object on the top of the stack as the metatable\nassociated with name `tname` in the registry (see `luaL_newmetatable`).\n -luaL_Stream luaL_Stream [typedef struct luaL_Stream {FILE *f; lua_CFunction closef;}]\nThe standard representation for file handles used by the standard I/O library.\n\nA file handle is implemented as a full userdata, with a metatable called\n`LUA_FILEHANDLE` (where `LUA_FILEHANDLE` is a macro with the actual metatable's\nname). The metatable is created by the I/O library (see `luaL_newmetatable`).\n\nThis userdata must start with the structure `luaL_Stream`; it can contain other\ndata after this initial structure. The field `f` points to the corresponding C\nstream (or it can be `NULL` to indicate an incompletely created handle). The\nfield `closef` points to a Lua function that will be called to close the stream \nwhen the handle is closed or collected; this function receives the file handle \nas its sole argument and must return either a true value, in case of success, or \na false value plus an error message, in case of error. Once Lua calls this \nfield, it changes the field value to `NULL` to signal that the handle is closed.\n -luaL_testudata luaL_testudata(lua_State *L, int arg, const char *tname) [void]\nThis function works like `luaL_checkudata`, except that, when the test fails,\nit returns `NULL` instead of raising an error.\n -luaL_tolstring luaL_tolstring(lua_State *L, int idx, size_t *len) [const char*]\nConverts any Lua value at the given index to a C string in a reasonable format.\nThe resulting string is pushed onto the stack and also returned by the function\n(see §4.1.3). If `len` is not `NULL`, the function also sets `*len` with the \nstring length.\n\nIf the value has a metatable with a `__tostring` field, then `luaL_tolstring`\ncalls the corresponding metamethod with the value as argument, and uses the\nresult of the call as its result.\n -luaL_traceback luaL_traceback(lua_State *L, lua_State *L1, const char *msg, int level) [void]\nCreates and pushes a traceback of the stack `L1`. If `msg` is not `NULL`, it is\nappended at the beginning of the traceback. The `level` parameter tells at\nwhich level to start the traceback.\n -luaL_typeerror luaL_typeerror(lua_State *L, int arg, const char *tname) [const char*]\nRaises a type error for the argument `arg` of the C function that called it,\nusing a standard message; `tname` is a "name" for the expected type. This \nfunction never returns.\n +luaL_ref luaL_ref(lua_State *L, int t) [int]\nCreates and returns a _reference_, in the table at index `t`, for the object on the top of the\nstack (and pops the object).\n\nA reference is a unique integer key. As long as you do not manually add integer keys into the\ntable `t`, `luaL_ref` ensures the uniqueness of the key it returns. You can retrieve an object\nreferred by the reference `r` by calling `lua_rawgeti(L, t, r)`. The function `luaL_unref`\nfrees a reference.\n\nIf the object on the top of the stack is nil, `luaL_ref` returns the constant `LUA_REFNIL`.\nThe constant `LUA_NOREF` is guaranteed to be different from any reference returned by `luaL_ref`.\n +luaL_Reg luaL_Reg [struct]\ntypedef struct luaL_Reg {\n const char *name;\n lua_CFunction func;\n} luaL_Reg;\n\nType for arrays of functions to be registered by `luaL_setfuncs is the function name and `func`\nis a pointer to the function. Any array of `luaL_Reg` must end with a sentinel entry in which\nboth `name` and `func` are `NULL`.\n +luaL_requiref luaL_requiref(lua_State *L, const char *modname, lua_CFunction openf, int glb) [void]\nIf `package.loaded[modname]` is not true, calls the function `openf` with the string `modname`\nas an argument and sets the call result to `package.loaded[modname]`, as if that function has\nbeen called through `require`.\n\nIf `glb` is true, also stores the module into the global `modname`.\n\nLeaves a copy of the module on the stack.\n +luaL_setfuncs luaL_setfuncs(lua_State *L, const luaL_Reg *l, int nup) [void]\nRegisters all functions in the array `l` (see `luaL_Reg`) into the table on the top of the stack\n(below optional upvalues, see next).\n\nWhen `nup` is not zero, all functions are created with `nup` upvalues, initialized with copies\nof the `nup` values previously pushed on the stack on top of the library table. These values\nare popped from the stack after the registration.\n +luaL_setmetatable luaL_setmetatable(lua_State *L, const char *tname) [void]\nSets the metatable of the object on the top of the stack as the metatable associated with name\n`tname` in the registry (see `luaL_newmetatable`).\n +luaL_Stream luaL_Stream [typedef struct luaL_Stream {FILE *f; lua_CFunction closef;}]\nThe standard representation for file handles used by the standard I/O library.\n\nA file handle is implemented as a full userdata, with a metatable called `LUA_FILEHANDLE`\n(where `LUA_FILEHANDLE` is a macro with the actual metatable's name). The metatable is created\nby the I/O library (see `luaL_newmetatable`).\n\nThis userdata must start with the structure `luaL_Stream`; it can contain other data after this\ninitial structure. The field `f` points to the corresponding C stream (or it can be `NULL`\nto indicate an incompletely created handle). The field `closef` points to a Lua function\nthat will be called to close the stream when the handle is closed or collected; this function\nreceives the file handle as its sole argument and must return either a true value, in case of\nsuccess, or a false value plus an error message, in case of error. Once Lua calls this field,\nit changes the field value to `NULL` to signal that the handle is closed.\n +luaL_testudata luaL_testudata(lua_State *L, int arg, const char *tname) [void]\nThis function works like `luaL_checkudata`, except that, when the test fails, it returns `NULL`\ninstead of raising an error.\n +luaL_tolstring luaL_tolstring(lua_State *L, int idx, size_t *len) [const char*]\nConverts any Lua value at the given index to a C string in a reasonable format. The resulting\nstring is pushed onto the stack and also returned by the function (see §4.1.3). If `len`\nis not `NULL`, the function also sets `*len` with the string length.\n\nIf the value has a metatable with a `__tostring` field, then `luaL_tolstring` calls the\ncorresponding metamethod with the value as argument, and uses the result of the call as its result.\n +luaL_traceback luaL_traceback(lua_State *L, lua_State *L1, const char *msg, int level) [void]\nCreates and pushes a traceback of the stack `L1`. If `msg` is not `NULL`, it is appended at\nthe beginning of the traceback. The `level` parameter tells at which level to start the traceback.\n +luaL_typeerror luaL_typeerror(lua_State *L, int arg, const char *tname) [const char*]\nRaises a type error for the argument `arg` of the C function that called it, using a standard\nmessage; `tname` is a "name" for the expected type. This function never returns.\n luaL_typename luaL_typename(lua_State *L, int index) [const char*]\nReturns the name of the type of the value at the given index.\n -luaL_unref luaL_unref(lua_State *L, int t, int ref) [void]\nReleases the reference `ref` from the table at index `t` (see `luaL_ref`).\nThe entry is removed from the table, so that the referred object can be\ncollected. The reference `ref` is also freed to be used again.\n\nIf `ref` is `LUA_NOREF` or `LUA_REFNIL`, `luaL_unref` does nothing.\n -luaL_where luaL_where(lua_State *L, int lvl) [void]\nPushes onto the stack a string identifying the current position of the\ncontrol at level `lvl` in the call stack. Typically this string has the\nfollowing format:\n\n _chunkname_:_currentline_:\n\nLevel 0 is the running function, level 1 is the function that called the\nrunning function, etc.\n\nThis function is used to build a prefix for error messages.\n +luaL_unref luaL_unref(lua_State *L, int t, int ref) [void]\nReleases the reference `ref` from the table at index `t` (see `luaL_ref`). The entry is\nremoved from the table, so that the referred object can be collected. The reference `ref`\nis also freed to be used again.\n\nIf `ref` is `LUA_NOREF` or `LUA_REFNIL`, `luaL_unref` does nothing.\n +luaL_where luaL_where(lua_State *L, int lvl) [void]\nPushes onto the stack a string identifying the current position of the control at level `lvl`\nin the call stack. Typically this string has the following format:\n\n _chunkname_:_currentline_:\n\nLevel 0 is the running function, level 1 is the function that called the running function, etc.\n\nThis function is used to build a prefix for error messages.\n diff --git a/modules/lua/api b/modules/lua/api index 7972af7c..de8fb106 100644 --- a/modules/lua/api +++ b/modules/lua/api @@ -1,223 +1,223 @@ -B lpeg.B(patt)\nReturns a pattern that matches only if the input string at the current\nposition is preceded by `patt`. Pattern `patt` must match only strings with\nsome fixed length, and it cannot contain captures.\n\nLike the and predicate, this pattern never consumes any input, independently\nof success or failure. -C lpeg.C(patt)\nCreates a simple capture, which captures the substring of the subject that\nmatches `patt`. The captured value is a string. If `patt` has other captures,\ntheir values are returned after this one. -Carg lpeg.Carg(n)\nCreates an argument capture. This pattern matches the empty string and\nproduces the value given as the nth extra argument given in the call to\n`lpeg.match`. -Cb lpeg.Cb(name)\nCreates a back capture. This pattern matches the empty string and produces\nthe values produced by the most recent group capture named `name`.\n\nMost recent means the last complete outermost group capture with the given\nname. A Complete capture means that the entire pattern corresponding to the\ncapture has matched. An Outermost capture means that the capture is not\ninside another complete capture.\n\nIn the same way that LPeg does not specify when it evaluates captures, it\ndoes not specify whether it reuses values previously produced by the group or\nre-evaluates them. -Cc lpeg.Cc([value, ...])\nCreates a constant capture. This pattern matches the empty string and\nproduces all given values as its captured values. -Cf lpeg.Cf(patt, func)\nCreates a fold capture. If patt produces a list of captures C1 C2 ... Cn,\nthis capture will produce the value func(...func(func(C1, C2), C3)..., Cn),\nthat is, it will fold (or accumulate, or reduce) the captures from `patt`\nusing function `func`.\n\nThis capture assumes that `patt` should produce at least one capture with at\nleast one value (of any type), which becomes the initial value of an\naccumulator. (If you need a specific initial value, you may prefix a constant\ncapture to `patt`.) For each subsequent capture, LPeg calls `func` with this\naccumulator as the first argument and all values produced by the capture as\nextra arguments; the first result from this call becomes the new value for\nthe accumulator. The final value of the accumulator becomes the captured\nvalue.\n\nAs an example, the following pattern matches a list of numbers separated by\ncommas and returns their addition:\n\n -- matches a numeral and captures its numerical value\n number = lpeg.R"09"^1 / tonumber\n -- matches a list of numbers, capturing their values\n list = number * ("," * number)^0\n -- auxiliary function to add two numbers\n function add (acc, newvalue) return acc + newvalue end\n -- folds the list of numbers adding them\n sum = lpeg.Cf(list, add)\n -- example of use\n print(sum:match("10,30,43")) --> 83 -Cg lpeg.Cg(patt [, name])\nCreates a group capture. It groups all values returned by `patt` into a\nsingle capture. The group may be anonymous (if no name is given) or named\nwith the given name.\n\nAn anonymous group serves to join values from several captures into a single\ncapture. A named group has a different behavior. In most situations, a named\ngroup returns no values at all. Its values are only relevant for a following\nback capture or when used inside a table capture. -Cmt lpeg.Cmt(patt, function)\nCreates a match-time capture. Unlike all other captures, this one is\nevaluated immediately when a match occurs (even if it is part of a larger\npattern that fails later). It forces the immediate evaluation of all its\nnested captures and then calls `function`.\n\nThe given function gets as arguments the entire subject, the current position\n(after the match of `patt`), plus any capture values produced by `patt`.\n\nThe first value returned by `function` defines how the match happens. If the\ncall returns a number, the match succeeds and the returned number becomes the\nnew current position. (Assuming a subject s and current position i, the\nreturned number must be in the range [i, len(s) + 1].) If the call returns\ntrue, the match succeeds without consuming any input. (So, to return true is\nequivalent to return i.) If the call returns false, nil, or no value, the\nmatch fails.\n\nAny extra values returned by the function become the values produced by the\ncapture. -Cp lpeg.Cp()\nCreates a position capture. It matches the empty string and captures the\nposition in the subject where the match occurs. The captured value is a\nnumber. -Cs lpeg.Cs(patt)\nCreates a substitution capture, which captures the substring of the subject\nthat matches `patt`, with substitutions. For any capture inside `patt` with a\nvalue, the substring that matched the capture is replaced by the capture\nvalue (which should be a string). The final captured value is the string\nresulting from all replacements. -Ct lpeg.Ct(patt)\nCreates a table capture. This capture returns a table with all values from\nall anonymous captures made by `patt` inside this table in successive integer\nkeys, starting at 1. Moreover, for each named capture group created by\n`patt`, the first value of the group is put into the table with the group\nname as its key. The captured value is only the table. -P lpeg.P(value)\nConverts the given value into a proper pattern, according to the following\nrules:\n * If the argument is a pattern, it is returned unmodified.\n * If the argument is a string, it is translated to a pattern that matches\n the string literally.\n * If the argument is a non-negative number n, the result is a pattern that\n matches exactly n characters.\n * If the argument is a negative number -n, the result is a pattern that\n succeeds only if the input string has less than n characters left:\n `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` (see the unary minus\n operation).\n * If the argument is a boolean, the result is a pattern that always\n succeeds or always fails (according to the boolean value), without\n consuming any input.\n * If the argument is a table, it is interpreted as a grammar (see\n Grammars).\n * If the argument is a function, returns a pattern equivalent to a\n match-time capture over the empty string. -R lpeg.R({range})\nReturns a pattern that matches any single character belonging to one of the\ngiven ranges. Each `range` is a string xy of length 2, representing all\ncharacters with code between the codes of x and y (both inclusive).\n\nAs an example, the pattern `lpeg.R("09")` matches any digit, and\n`lpeg.R("az", "AZ")` matches any ASCII letter. -S lpeg.S(string)\nReturns a pattern that matches any single character that appears in the given\nstring. (The S stands for Set.)\n\nAs an example, the pattern `lpeg.S("+-*/")` matches any arithmetic operator.\n\nNote that, if `s` is a character (that is, a string of length 1), then\n`lpeg.P(s)` is equivalent to `lpeg.S(s)` which is equivalent to\n`lpeg.R(s..s)`. Note also that both `lpeg.S("")` and `lpeg.R()` are patterns\nthat always fail. -V lpeg.V(v)\nThis operation creates a non-terminal (a variable) for a grammar. The created\nnon-terminal refers to the rule indexed by `v` in the enclosing grammar. (See\nGrammars for details.) +B lpeg.B(patt)\nReturns a pattern that matches only if the input string at the current position is preceded\nby `patt`. Pattern `patt` must match only strings with some fixed length, and it cannot\ncontain captures.\n\nLike the and predicate, this pattern never consumes any input, independently of success\nor failure. +C lpeg.C(patt)\nCreates a simple capture, which captures the substring of the subject that matches `patt`. The\ncaptured value is a string. If `patt` has other captures, their values are returned after\nthis one. +Carg lpeg.Carg(n)\nCreates an argument capture. This pattern matches the empty string and produces the value\ngiven as the nth extra argument given in the call to `lpeg.match`. +Cb lpeg.Cb(name)\nCreates a back capture. This pattern matches the empty string and produces the values produced\nby the most recent group capture named `name`.\n\nMost recent means the last complete outermost group capture with the given name. A Complete\ncapture means that the entire pattern corresponding to the capture has matched. An Outermost\ncapture means that the capture is not inside another complete capture.\n\nIn the same way that LPeg does not specify when it evaluates captures, it does not specify\nwhether it reuses values previously produced by the group or re-evaluates them. +Cc lpeg.Cc([value, ...])\nCreates a constant capture. This pattern matches the empty string and produces all given\nvalues as its captured values. +Cf lpeg.Cf(patt, func)\nCreates a fold capture. If patt produces a list of captures C1 C2 ... Cn, this capture will\nproduce the value func(...func(func(C1, C2), C3)..., Cn), that is, it will fold (or accumulate,\nor reduce) the captures from `patt` using function `func`.\n\nThis capture assumes that `patt` should produce at least one capture with at least one value\n(of any type), which becomes the initial value of an accumulator. (If you need a specific\ninitial value, you may prefix a constant capture to `patt`.) For each subsequent capture,\nLPeg calls `func` with this accumulator as the first argument and all values produced by\nthe capture as extra arguments; the first result from this call becomes the new value for\nthe accumulator. The final value of the accumulator becomes the captured value.\n\nAs an example, the following pattern matches a list of numbers separated by commas and\nreturns their addition:\n\n -- matches a numeral and captures its numerical value\n number = lpeg.R"09"^1 / tonumber\n -- matches a list of numbers, capturing their values\n list = number * ("," * number)^0\n -- auxiliary function to add two numbers\n function add (acc, newvalue) return acc + newvalue end\n -- folds the list of numbers adding them\n sum = lpeg.Cf(list, add)\n -- example of use\n print(sum:match("10,30,43")) --> 83 +Cg lpeg.Cg(patt [, name])\nCreates a group capture. It groups all values returned by `patt` into a single capture. The\ngroup may be anonymous (if no name is given) or named with the given name.\n\nAn anonymous group serves to join values from several captures into a single capture. A named\ngroup has a different behavior. In most situations, a named group returns no values at all. Its\nvalues are only relevant for a following back capture or when used inside a table capture. +Cmt lpeg.Cmt(patt, function)\nCreates a match-time capture. Unlike all other captures, this one is evaluated immediately\nwhen a match occurs (even if it is part of a larger pattern that fails later). It forces\nthe immediate evaluation of all its nested captures and then calls `function`.\n\nThe given function gets as arguments the entire subject, the current position (after the\nmatch of `patt`), plus any capture values produced by `patt`.\n\nThe first value returned by `function` defines how the match happens. If the call returns a\nnumber, the match succeeds and the returned number becomes the new current position. (Assuming\na subject s and current position i, the returned number must be in the range [i, len(s) +\n1].) If the call returns true, the match succeeds without consuming any input. (So, to return\ntrue is equivalent to return i.) If the call returns false, nil, or no value, the match fails.\n\nAny extra values returned by the function become the values produced by the capture. +Cp lpeg.Cp()\nCreates a position capture. It matches the empty string and captures the position in the\nsubject where the match occurs. The captured value is a number. +Cs lpeg.Cs(patt)\nCreates a substitution capture, which captures the substring of the subject that matches\n`patt`, with substitutions. For any capture inside `patt` with a value, the substring that\nmatched the capture is replaced by the capture value (which should be a string). The final\ncaptured value is the string resulting from all replacements. +Ct lpeg.Ct(patt)\nCreates a table capture. This capture returns a table with all values from all anonymous\ncaptures made by `patt` inside this table in successive integer keys, starting at 1. Moreover,\nfor each named capture group created by `patt`, the first value of the group is put into\nthe table with the group name as its key. The captured value is only the table. +P lpeg.P(value)\nConverts the given value into a proper pattern, according to the following rules:\n\n * If the argument is a pattern, it is returned unmodified.\n * If the argument is a string, it is translated to a pattern that matches the string\n literally.\n * If the argument is a non-negative number n, the result is a pattern that matches exactly\n n characters.\n * If the argument is a negative number -n, the result is a pattern that succeeds only if the\n input string has less than n characters left: `lpeg.P(-n)` is equivalent to `-lpeg.P(n)`\n (see the unary minus operation).\n * If the argument is a boolean, the result is a pattern that always succeeds or always fails\n (according to the boolean value), without consuming any input.\n * If the argument is a table, it is interpreted as a grammar (see Grammars).\n * If the argument is a function, returns a pattern equivalent to a match-time capture over\n the empty string. +R lpeg.R({range})\nReturns a pattern that matches any single character belonging to one of the given ranges. Each\n`range` is a string xy of length 2, representing all characters with code between the codes\nof x and y (both inclusive).\n\nAs an example, the pattern `lpeg.R("09")` matches any digit, and `lpeg.R("az", "AZ")`\nmatches any ASCII letter. +S lpeg.S(string)\nReturns a pattern that matches any single character that appears in the given string. (The\nS stands for Set.)\n\nAs an example, the pattern `lpeg.S("+-*/")` matches any arithmetic operator.\n\nNote that, if `s` is a character (that is, a string of length 1), then `lpeg.P(s)` is equivalent\nto `lpeg.S(s)` which is equivalent to `lpeg.R(s..s)`. Note also that both `lpeg.S("")` and\n`lpeg.R()` are patterns that always fail. +V lpeg.V(v)\nThis operation creates a non-terminal (a variable) for a grammar. The created non-terminal\nrefers to the rule indexed by `v` in the enclosing grammar. (See Grammars for details.) _G _G._G (module)\nLua _G module. -_G _G._G (table)\nA global variable (not a function) that holds the global environment\n(see §2.2). Lua itself does not use this variable; changing its value does\nnot affect any environment, nor vice versa. -_VERSION _G._VERSION (string)\nA global variable (not a function) that holds a string containing the\nrunning Lua version. The current value of this variable is "`Lua 5.4`". +_G _G._G (table)\nA global variable (not a function) that holds the global environment (see §2.2). Lua\nitself does not use this variable; changing its value does not affect any environment,\nnor vice versa. +_VERSION _G._VERSION (string)\nA global variable (not a function) that holds a string containing the running Lua version. The\ncurrent value of this variable is "`Lua 5.4`". abs math.abs(x)\nReturns the maximum value between `x` and `-x`. (integer/float) acos math.acos(x)\nReturns the arc cosine of `x` (in radians). -arshift bit32.arshift(x, disp)\nReturns the number `x` shifted `disp` bits to the right. The number `disp`\nmay be any representable integer. Negative displacements shift to the left.\n\nThis shift operation is what is called arithmetic shift. Vacant bits on the\nleft are filled with copies of the higher bit of `x`; vacant bits on the\nright are filled with zeros. In particular, displacements with absolute\nvalues higher than 31 result in zero or `0xFFFFFFFF` (all original bits are\nshifted out).\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. +arshift bit32.arshift(x, disp)\nReturns the number `x` shifted `disp` bits to the right. The number `disp` may be any\nrepresentable integer. Negative displacements shift to the left.\n\nThis shift operation is what is called arithmetic shift. Vacant bits on the left are filled\nwith copies of the higher bit of `x`; vacant bits on the right are filled with zeros. In\nparticular, displacements with absolute values higher than 31 result in zero or `0xFFFFFFFF`\n(all original bits are shifted out).\n\nNew in Lua 5.2. Deprecated in Lua 5.3. asin math.asin(x)\nReturns the arc sine of `x` (in radians). -assert _G.assert(v [, message])\nRaises an error if the value of its argument `v` is false (i.e., nil or\nfalse); otherwise, returns all its arguments. In case of error, `message` is\nthe error object; when absent, it defaults to "assertion failed!". -atan math.atan(y [, x])\nReturns the arc tangent of `y/x` (in radians), but uses the signs\nof both parameters to find the quadrant of the result. It also handles\ncorrectly the case of `x` being zero.\n\nThe default value for `x` is 1, so that the call `math.atan(y)` returns the\narc tangent of `y`. -atan2 math.atan2(y, x)\nReturns the arc tangent of `y/x` (in radians), but uses the signs\nof both parameters to find the quadrant of the result. (It also handles\ncorrectly the case of `x` being zero.)\n\nDeprecated in Lua 5.3. -attributes lfs.attributes(filepath [, aname | atable])\nReturns a table with the file attributes corresponding to filepath (or nil\nfollowed by an error message in case of error). If the second optional\nargument is given and is a string, then only the value of the named attribute\nis returned (this use is equivalent to lfs.attributes(filepath)[aname], but\nthe table is not created and only one attribute is retrieved from the O.S.).\nIf a table is passed as the second argument, it is filled with attributes and\nreturned instead of a new table. The attributes are described as follows;\nattribute mode is a string, all the others are numbers, and the time related\nattributes use the same time reference of os.time:\n dev: on Unix systems, this represents the device that the inode resides on.\n On Windows systems, represents the drive number of the disk containing\n the file\n ino: on Unix systems, this represents the inode number. On Windows systems\n this has no meaning\n mode: string representing the associated protection mode (the values could\n be file, directory, link, socket, named pipe, char device, block\n device or other)\n nlink: number of hard links to the file\n uid: user-id of owner (Unix only, always 0 on Windows)\n gid: group-id of owner (Unix only, always 0 on Windows)\n rdev: on Unix systems, represents the device type, for special file inodes.\n On Windows systems represents the same as dev\n access: time of last access\n modification: time of last data modification\n change: time of last file status change\n size: file size, in bytes\n permissions: file permissions string\n blocks: block allocated for file; (Unix only)\n blksize: optimal file system I/O blocksize; (Unix only)\n\nThis function uses stat internally thus if the given filepath is a symbolic\nlink, it is followed (if it points to another link the chain is followed\nrecursively) and the information is about the file it refers to. To obtain\ninformation about the link itself, see function lfs.symlinkattributes. -band bit32.band(...)\nReturns the bitwise "and" of its operands.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. +assert _G.assert(v [, message])\nRaises an error if the value of its argument `v` is false (i.e., nil or false); otherwise,\nreturns all its arguments. In case of error, `message` is the error object; when absent,\nit defaults to "assertion failed!". +atan math.atan(y [, x])\nReturns the arc tangent of `y/x` (in radians), but uses the signs of both parameters to find\nthe quadrant of the result. It also handles correctly the case of `x` being zero.\n\nThe default value for `x` is 1, so that the call `math.atan(y)` returns the arc tangent of `y`. +atan2 math.atan2(y, x)\nReturns the arc tangent of `y/x` (in radians), but uses the signs of both parameters to find\nthe quadrant of the result. (It also handles correctly the case of `x` being zero.)\n\nDeprecated in Lua 5.3. +attributes lfs.attributes(filepath [, aname | atable])\nReturns a table with the file attributes corresponding to filepath (or nil followed by\nan error message in case of error). If the second optional argument is given and is a\nstring, then only the value of the named attribute is returned (this use is equivalent to\nlfs.attributes(filepath)[aname], but the table is not created and only one attribute is\nretrieved from the O.S.). If a table is passed as the second argument, it is filled with\nattributes and returned instead of a new table. The attributes are described as follows;\nattribute mode is a string, all the others are numbers, and the time related attributes use\nthe same time reference of os.time:\n\n dev: on Unix systems, this represents the device that the inode resides on. On Windows\n systems, represents the drive number of the disk containing the file\n ino: on Unix systems, this represents the inode number. On Windows systems this has no meaning\n mode: string representing the associated protection mode (the values could be file,\n directory, link, socket, named pipe, char device, block device or other)\n nlink: number of hard links to the file\n uid: user-id of owner (Unix only, always 0 on Windows)\n gid: group-id of owner (Unix only, always 0 on Windows)\n rdev: on Unix systems, represents the device type, for special file inodes. On Windows\n systems represents the same as dev\n access: time of last access\n modification: time of last data modification\n change: time of last file status change\n size: file size, in bytes\n permissions: file permissions string\n blocks: block allocated for file; (Unix only)\n blksize: optimal file system I/O blocksize; (Unix only)\n\nThis function uses stat internally thus if the given filepath is a symbolic link, it is\nfollowed (if it points to another link the chain is followed recursively) and the information\nis about the file it refers to. To obtain information about the link itself, see function\nlfs.symlinkattributes. +band bit32.band(...)\nReturns the bitwise "and" of its operands.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. bit32 _G.bit32 (module)\nLua bit32 module. -bnot bit32.bnot(x)\nReturns the bitwise negation of `x`. For any integer `x`, the following\nidentity holds:\n\n assert(bit32.bnot(x) == (-1 - x) % 2^32)\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -bor bit32.bor(...)\nReturns the bitwise "or" of its operands.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -btest bit32.btest(...)\nReturns a boolean signaling whether the bitwise "and" of its operands is\ndifferent from zero.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -byte string.byte(s [, i [, j]])\nReturns the internal numerical codes of the characters `s[i]`, `s[i+1]`,\n···, `s[j]`. The default value for `i` is 1; the default value for `j`\nis `i`. These indices are corrected following the same rules of function\n`string.sub`.\n\nNumerical codes are not necessarily portable across platforms. +bnot bit32.bnot(x)\nReturns the bitwise negation of `x`. For any integer `x`, the following identity holds:\n\n assert(bit32.bnot(x) == (-1 - x) % 2^32)\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +bor bit32.bor(...)\nReturns the bitwise "or" of its operands.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +btest bit32.btest(...)\nReturns a boolean signaling whether the bitwise "and" of its operands is different from zero.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +byte string.byte(s [, i [, j]])\nReturns the internal numerical codes of the characters `s[i]`, `s[i+1]`, ···, `s[j]`. The\ndefault value for `i` is 1; the default value for `j` is `i`. These indices are corrected\nfollowing the same rules of function `string.sub`.\n\nNumerical codes are not necessarily portable across platforms. ceil math.ceil(x)\nReturns the smallest integral value greater than or equal to `x`. -char string.char(···)\nReceives zero or more integers. Returns a string with length equal to\nthe number of arguments, in which each character has the internal numerical\ncode equal to its corresponding argument.\n\nNumerical codes are not necessarily portable across platforms. -char utf8.char(···)\nReceives zero or more integers, converts each one to its corresponding UTF-8\nbyte sequence and returns a string with the concatenation of all these\nsequences.\n\nNew in Lua 5.3. -charpattern utf8.charpattern (string)\nThe pattern (a string, not a function) "\0-\x7F\xC2-\xFD*"\n(see §6.4.1), which matches exactly one UTF-8 byte sequence, assuming that\nthe subject is a valid UTF-8 string.\n\nNew in Lua 5.3. +char string.char(···)\nReceives zero or more integers. Returns a string with length equal to the number of arguments,\nin which each character has the internal numerical code equal to its corresponding argument.\n\nNumerical codes are not necessarily portable across platforms. +char utf8.char(···)\nReceives zero or more integers, converts each one to its corresponding UTF-8 byte sequence\nand returns a string with the concatenation of all these sequences.\n\nNew in Lua 5.3. +charpattern utf8.charpattern (string)\nThe pattern (a string, not a function) "\0-\x7F\xC2-\xFD*" (see §6.4.1), which\nmatches exactly one UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string.\n\nNew in Lua 5.3. chdir lfs.chdir(path)\nChanges the current working directory to the given path.\n\nReturns true in case of success or nil plus an error string. -clock os.clock()\nReturns an approximation of the amount in seconds of CPU time used by\nthe program, as returned by the underlying ISO C function `clock`. -close coroutine.close(co)\nCloses coroutine `co`, that is, closes all its pending to-be-closed variables\nand puts the coroutine in a dead state. The given coroutine must be dead or\nsuspended. In case of error closing some variable, returns false plus the\nerror object; otherwise returns true. -close file:close()\nCloses `file`. Note that files are automatically closed when their\nhandles are garbage collected, but that takes an unpredictable amount of\ntime to happen.\n\nWhen closing a file handle created with `io.popen`, `file:close` returns the\nsame values returned by `os.execute`. -close io.close([file])\nEquivalent to `file:close()`. Without a `file`, closes the default\noutput file. -codepoint utf8.codepoint(s [, i [, j [, lax]]])\nReturns the codepoints (as integers) from all characters in `s` that start\nbetween byte position `i` and `j` (both included). The default for `i` is 1\nand for `j` is `i`. It raises an error if it meets any invalid byte sequence.\n\nThis function only accepts valid sequences (well formed and not overlong).\nBy default, it only accepts byte sequences that result in valid Unicode code\npoints, rejecting values greater than `10FFFF` and surrogates. The boolean\nargument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are\naccepted. (Not well formed and overlong sequences are still rejected.)\n\nNew in Lua 5.3. -codes utf8.codes(s [, lax])\nReturns values so that the construction\n\n for p, c in utf8.codes(s) do *body* end\n\nwill iterate over all UTF-8 characters in string `s`, with `p` being the\nposition (in bytes) and `c` the code point of each character. It raises an\nerror if it meets any invalid byte sequence.\n\nThis function only accepts valid sequences (well formed and not overlong).\nBy default, it only accepts byte sequences that result in valid Unicode code\npoints, rejecting values greater than `10FFFF` and surrogates. The boolean\nargument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are\naccepted. (Not well formed and overlong sequences are still rejected.)\n\nNew in Lua 5.3. -collectgarbage _G.collectgarbage([opt [, arg]])\nThis function is a generic interface to the garbage collector. It\nperforms different functions according to its first argument, `opt`:\n "collect": performs a full garbage-collection cycle. This is the default\n option.\n "stop": stops automatic execution of the garbage collector.\n "restart": restarts automatic execution of the garbage collector.\n "count": returns the total memory in use by Lua in Kbytes. The value has a\n fractional part, so that it multiplied by 1024 gives the exact\n number of bytes in use by Lua.\n "step": performs a garbage-collection step. The step "size" is controlled\n by `arg`. With a zero value, the collector will perform one basic\n (indivisible) step. For non-zero values, the collector will perform\n as if that amount of memory (in Kbytes) had been allocated by Lua.\n Returns true if the step finished a collection cycle.\n "isrunning": returns a boolean that tells whether the collector is running\n (i.e., not stopped).\n "incremental": change the collector mode to incremental. This option can be\n followed by three numbers: the garbage-collector pause, the\n step multiplier, and the step size (see §2.5.1). A zero means to not\n change that value.\n "generational": change the collector mode to generational. This option can\n be followed by two numbers: the garbage-collector minor\n multiplier and the major multiplier (see §2.5.2). A zero\n means to not change that value.\n\nSee §2.5 for more details about garbage collection and some of these options. -concat table.concat(list [, sep [, i [, j]]])\nGiven a list where all elements are strings or numbers, returns the string\n`list[i]..sep..list[i+1] ··· sep..list[j]`. The default value for `sep` is\nthe empty string, the default for `i` is 1, and the default for `j` is\n`#list`. If `i` is greater than `j`, returns the empty string. -config package.config (string)\nA string describing some compile-time configurations for packages. This\nstring is a sequence of lines:\n The first line is the directory separator string. Default is '`\`' for\n Windows and '`/`' for all other systems.\n The second line is the character that separates templates in a path.\n Default is '`;`'.\n The third line is the string that marks the substitution points in a\n template. Default is '`?`'.\n The fourth line is a string that, in a path in Windows, is replaced by\n the executable's directory. Default is '`!`'.\n The fifth line is a mark to ignore all text after it when building the\n `luaopen_` function name. Default is '`-`'.\n\nNew in Lua 5.2. +clock os.clock()\nReturns an approximation of the amount in seconds of CPU time used by the program, as returned\nby the underlying ISO C function `clock`. +close coroutine.close(co)\nCloses coroutine `co`, that is, closes all its pending to-be-closed variables and puts the\ncoroutine in a dead state. The given coroutine must be dead or suspended. In case of error\nclosing some variable, returns false plus the error object; otherwise returns true. +close file:close()\nCloses `file`. Note that files are automatically closed when their handles are garbage\ncollected, but that takes an unpredictable amount of time to happen.\n\nWhen closing a file handle created with `io.popen`, `file:close` returns the same values\nreturned by `os.execute`. +close io.close([file])\nEquivalent to `file:close()`. Without a `file`, closes the default output file. +codepoint utf8.codepoint(s [, i [, j [, lax]]])\nReturns the codepoints (as integers) from all characters in `s` that start between byte\nposition `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises\nan error if it meets any invalid byte sequence.\n\nThis function only accepts valid sequences (well formed and not overlong). By default, it only\naccepts byte sequences that result in valid Unicode code points, rejecting values greater than\n`10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values\nup to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.)\n\nNew in Lua 5.3. +codes utf8.codes(s [, lax])\nReturns values so that the construction\n\n for p, c in utf8.codes(s) do *body* end\n\nwill iterate over all UTF-8 characters in string `s`, with `p` being the position (in bytes) and\n`c` the code point of each character. It raises an error if it meets any invalid byte sequence.\n\nThis function only accepts valid sequences (well formed and not overlong). By default, it only\naccepts byte sequences that result in valid Unicode code points, rejecting values greater than\n`10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values\nup to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.)\n\nNew in Lua 5.3. +collectgarbage _G.collectgarbage([opt [, arg]])\nThis function is a generic interface to the garbage collector. It performs different functions\naccording to its first argument, `opt`:\n "collect": performs a full garbage-collection cycle. This is the default option.\n "stop": stops automatic execution of the garbage collector.\n "restart": restarts automatic execution of the garbage collector.\n "count": returns the total memory in use by Lua in Kbytes. The value has a fractional part,\n so that it multiplied by 1024 gives the exact number of bytes in use by Lua.\n "step": performs a garbage-collection step. The step "size" is controlled by `arg`. With a\n zero value, the collector will perform one basic (indivisible) step. For non-zero values,\n the collector will perform as if that amount of memory (in Kbytes) had been allocated\n by Lua. Returns true if the step finished a collection cycle.\n "isrunning": returns a boolean that tells whether the collector is running (i.e., not\n stopped).\n "incremental": change the collector mode to incremental. This option can be followed\n by three numbers: the garbage-collector pause, the step multiplier, and the step size\n (see §2.5.1). A zero means to not change that value.\n "generational": change the collector mode to generational. This option can be followed\n by two numbers: the garbage-collector minor multiplier and the major multiplier (see\n §2.5.2). A zero means to not change that value.\n\nSee §2.5 for more details about garbage collection and some of these options. +concat table.concat(list [, sep [, i [, j]]])\nGiven a list where all elements are strings or numbers, returns the string\n`list[i]..sep..list[i+1] ··· sep..list[j]`. The default value for `sep` is the empty\nstring, the default for `i` is 1, and the default for `j` is `#list`. If `i` is greater than\n`j`, returns the empty string. +config package.config (string)\nA string describing some compile-time configurations for packages. This string is a sequence\nof lines:\n\n * The first line is the directory separator string. Default is '`\`' for Windows and\n '`/`' for all other systems.\n * The second line is the character that separates templates in a path. Default is '`;`'.\n * The third line is the string that marks the substitution points in a template. Default\n is '`?`'.\n * The fourth line is a string that, in a path in Windows, is replaced by the executable's\n directory. Default is '`!`'.\n * The fifth line is a mark to ignore all text after it when building the `luaopen_`\n function name. Default is '`-`'.\n\nNew in Lua 5.2. coroutine _G.coroutine (module)\nLua coroutine module. cos math.cos(x)\nReturns the cosine of `x` (assumed to be in radians). cosh math.cosh(x)\nReturns the hyperbolic cosine of `x`.\n\nDeprecated in Lua 5.3. -cpath package.cpath (string)\nA string with the path used by `require` to search for a C loader.\nLua initializes the C path `package.cpath` in the same way it initializes\nthe Lua path `package.path`, using the environment variable `LUA_CPATH_5_4`\nor the environment variable `LUA_CPATH` or a default path defined in\n`luaconf.h`. -create coroutine.create(f)\nCreates a new coroutine, with body `f`. `f` must be a Lua\nfunction. Returns this new coroutine, an object with type `"thread"`. -currentdir lfs.currentdir()\nReturns a string with the current working directory or nil plus an error\nstring. -date os.date([format [, time]])\nReturns a string or a table containing date and time, formatted according\nto the given string `format`.\n\nIf the `time` argument is present, this is the time to be formatted\n(see the `os.time` function for a description of this value). Otherwise,\n`date` formats the current time.\n\nIf `format` starts with '`!`', then the date is formatted in Coordinated\nUniversal Time. After this optional character, if `format` is the string\n"`*t`", then `date` returns a table with the following fields: `year`,\n`month` (1-12), `day` (1-31), `hour` (0-23), `min` (0-59), `sec` (0-61, due\nto leap seconds), `wday` (weekday, 1-7, Sunday is 1), `yday` (day of the\nyear, 1-366), and `isdst` (daylight saving flag, a boolean). This last field\nmay be absent if the information is not available.\n\nIf `format` is not "`*t`", then `date` returns the date as a string,\nformatted according to the same rules as the ISO C function `strftime`.\n\nIf `format` is absent, it defaults to "`%c`", which gives a human-readable\ndate and time representation using the current locale.\n\nOn non-POSIX systems, this function may be not thread safe because of its\nreliance on C function `gmtime` and C function `localtime`. +cpath package.cpath (string)\nA string with the path used by `require` to search for a C loader.\n\nLua initializes the C path `package.cpath` in the same way it initializes the Lua path\n`package.path`, using the environment variable `LUA_CPATH_5_4` or the environment variable\n`LUA_CPATH` or a default path defined in `luaconf.h`. +create coroutine.create(f)\nCreates a new coroutine, with body `f`. `f` must be a Lua function. Returns this new coroutine,\nan object with type `"thread"`. +currentdir lfs.currentdir()\nReturns a string with the current working directory or nil plus an error string. +date os.date([format [, time]])\nReturns a string or a table containing date and time, formatted according to the given string\n`format`.\n\nIf the `time` argument is present, this is the time to be formatted (see the `os.time`\nfunction for a description of this value). Otherwise, `date` formats the current time.\n\nIf `format` starts with '`!`', then the date is formatted in Coordinated Universal Time. After\nthis optional character, if `format` is the string "`*t`", then `date` returns a table with\nthe following fields: `year`, `month` (1-12), `day` (1-31), `hour` (0-23), `min` (0-59),\n`sec` (0-61, due to leap seconds), `wday` (weekday, 1-7, Sunday is 1), `yday` (day of the\nyear, 1-366), and `isdst` (daylight saving flag, a boolean). This last field may be absent\nif the information is not available.\n\nIf `format` is not "`*t`", then `date` returns the date as a string, formatted according to\nthe same rules as the ISO C function `strftime`.\n\nIf `format` is absent, it defaults to "`%c`", which gives a human-readable date and time\nrepresentation using the current locale.\n\nOn non-POSIX systems, this function may be not thread safe because of its reliance on C\nfunction `gmtime` and C function `localtime`. debug _G.debug (module)\nLua debug module. -debug debug.debug()\nEnters an interactive mode with the user, running each string that\nthe user enters. Using simple commands and other debug facilities,\nthe user can inspect global and local variables, change their values,\nevaluate expressions, and so on. A line containing only the word `cont`\nfinishes this function, so that the caller continues its execution.\n\nNote that commands for `debug.debug` are not lexically nested within any\nfunction and so have no direct access to local variables. +debug debug.debug()\nEnters an interactive mode with the user, running each string that the user enters. Using\nsimple commands and other debug facilities, the user can inspect global and local variables,\nchange their values, evaluate expressions, and so on. A line containing only the word `cont`\nfinishes this function, so that the caller continues its execution.\n\nNote that commands for `debug.debug` are not lexically nested within any function and so\nhave no direct access to local variables. deg math.deg(x)\nConverts the angle `x` from radians to degrees. -difftime os.difftime(t2, t1)\nReturns the difference, in seconds, from time `t1` to time `t2` (where the\ntimes are values returned by `os.time`). In POSIX, Windows, and some other\nsystems, this value is exactly `t2`*-*`t1`. -dir lfs.dir(path)\nLua iterator over the entries of a given directory. Each time the iterator is\ncalled with dir_obj it returns a directory entry's name as a string, or nil\nif there are no more entries. You can also iterate by calling dir_obj:next(),\nand explicitly close the directory before the iteration finished with\ndir_obj:close(). Raises an error if path is not a directory. -dofile _G.dofile([filename])\nOpens the named file and executes its content as a Lua chunk. When\ncalled without arguments,\n`dofile` executes the content of the standard input (`stdin`). Returns\nall values returned by the chunk. In case of errors, `dofile` propagates\nthe error to its caller. (That is, `dofile` does not run in protected mode.) -dump string.dump(function [, strip])\nReturns a string containing a binary representation (a _binary chunk_) of the\ngiven function, so that a later `load` on this string returns a copy of the\nfunction (but with new upvalues). If `strip` is a true value, the binary\nrepresentation is created without debug information about the function (local\nvariable names, lines, etc.).\n\nFunctions with upvalues have only their number of upvalues saved. When\n(re)loaded, those upvalues receive fresh instances. (See the `load` function\nfor details about how these upvalues are initialized. You can use the debug\nlibrary to serialize and reload the upvalues of a function in a way adequate\nto your needs.) -error _G.error(message [, level])\nRaises an error (see §2.3) with `message` as the error object. This function\nnever returns.\n\nUsually, `error` adds some information about the error position at the\nbeginning of the message, if the message is a string. The `level` argument\nspecifies how to get the error position. With level 1 (the default), the\nerror position is where the `error` function was called. Level 2 points the\nerror to where the function that called `error` was called; and so on.\nPassing a level 0 avoids the addition of error position information to the\nmessage. -execute os.execute([command])\nThis function is equivalent to the ISO C function `system`. It passes\n`command` to be executed by an operating system shell. Its first result is\n`true` if the command terminated successfully, or `nil` otherwise. After this\nfirst result the function returns a string plus a number, as follows:\n "exit": the command terminated normally; the following number is the exit\n status of the command.\n "signal": the command was terminated by a signal; the following number is\n the signal that terminated the command.\n\nWhen called without a `command`, `os.execute` returns a boolean that is true\nif a shell is available. -exit os.exit([code [, close]])\nCalls the ISO C function `exit` to terminate the host program. If `code` is\n`true`, the returned status is `EXIT_SUCCESS`; if `code` is `false`, the\nreturned status is `EXIT_FAILURE`; if `code` is a number, the returned status\nis this number. The default value for `code` is `true`.\n\nIf the optional second argument `close` is true, closes the Lua state before\nexiting. +difftime os.difftime(t2, t1)\nReturns the difference, in seconds, from time `t1` to time `t2` (where the times are values\nreturned by `os.time`). In POSIX, Windows, and some other systems, this value is exactly\n`t2`*-*`t1`. +dir lfs.dir(path)\nLua iterator over the entries of a given directory. Each time the iterator is called\nwith dir_obj it returns a directory entry's name as a string, or nil if there are no more\nentries. You can also iterate by calling dir_obj:next(), and explicitly close the directory\nbefore the iteration finished with dir_obj:close(). Raises an error if path is not a directory. +dofile _G.dofile([filename])\nOpens the named file and executes its content as a Lua chunk. When called without arguments,\n`dofile` executes the content of the standard input (`stdin`). Returns all values returned\nby the chunk. In case of errors, `dofile` propagates the error to its caller. (That is,\n`dofile` does not run in protected mode.) +dump string.dump(function [, strip])\nReturns a string containing a binary representation (a _binary chunk_) of the given function, so\nthat a later `load` on this string returns a copy of the function (but with new upvalues). If\n`strip` is a true value, the binary representation is created without debug information\nabout the function (local variable names, lines, etc.).\n\nFunctions with upvalues have only their number of upvalues saved. When (re)loaded, those\nupvalues receive fresh instances. (See the `load` function for details about how these\nupvalues are initialized. You can use the debug library to serialize and reload the upvalues\nof a function in a way adequate to your needs.) +error _G.error(message [, level])\nRaises an error (see §2.3) with `message` as the error object. This function never returns.\n\nUsually, `error` adds some information about the error position at the beginning of the\nmessage, if the message is a string. The `level` argument specifies how to get the error\nposition. With level 1 (the default), the error position is where the `error` function\nwas called. Level 2 points the error to where the function that called `error` was called;\nand so on. Passing a level 0 avoids the addition of error position information to the message. +execute os.execute([command])\nThis function is equivalent to the ISO C function `system`. It passes `command` to be\nexecuted by an operating system shell. Its first result is `true` if the command terminated\nsuccessfully, or `nil` otherwise. After this first result the function returns a string plus\na number, as follows:\n\n * "exit": the command terminated normally; the following number is the exit status of\n the command.\n * "signal": the command was terminated by a signal; the following number is the signal\n that terminated the command.\n\nWhen called without a `command`, `os.execute` returns a boolean that is true if a shell\nis available. +exit os.exit([code [, close]])\nCalls the ISO C function `exit` to terminate the host program. If `code` is `true`, the returned\nstatus is `EXIT_SUCCESS`; if `code` is `false`, the returned status is `EXIT_FAILURE`; if\n`code` is a number, the returned status is this number. The default value for `code` is `true`.\n\nIf the optional second argument `close` is true, closes the Lua state before exiting. exp math.exp(x)\nReturns the value *e^x*. -extract bit32.extract(n, field [, width])\nReturns the unsigned number formed by the bits `field` to `field + width - 1`\nfrom `n`. Bits are numbered from 0 (least significant) to 31 (most\nsignificant). All accessed bits must be in the range [0, 31].\n\nThe default for `width` is 1.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -find string.find(s, pattern [, init [, plain]])\nLooks for the first match of `pattern` (see §6.4.1) in the string `s`. If it\nfinds a match, then `find` returns the indices of `s` where this occurrence\nstarts and ends; otherwise, it returns nil. A third, optional numerical\nargument `init` specifies where to start the search; its default value is 1\nand can be negative. A value of true as a fourth, optional argument `plain`\nturns off the pattern matching facilities, so the function does a plain\n"find substring" operation, with no characters in `pattern` being considered\nmagic.\n\nIf the pattern has captures, then in a successful match the captured values\nare also returned, after the two indices. +extract bit32.extract(n, field [, width])\nReturns the unsigned number formed by the bits `field` to `field + width - 1` from `n`. Bits\nare numbered from 0 (least significant) to 31 (most significant). All accessed bits must be\nin the range [0, 31].\n\nThe default for `width` is 1.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +find string.find(s, pattern [, init [, plain]])\nLooks for the first match of `pattern` (see §6.4.1) in the string `s`. If it finds a match,\nthen `find` returns the indices of `s` where this occurrence starts and ends; otherwise,\nit returns nil. A third, optional numerical argument `init` specifies where to start the\nsearch; its default value is 1 and can be negative. A value of true as a fourth, optional\nargument `plain` turns off the pattern matching facilities, so the function does a plain\n"find substring" operation, with no characters in `pattern` being considered magic.\n\nIf the pattern has captures, then in a successful match the captured values are also returned,\nafter the two indices. floor math.floor(x)\nReturns the largest integral value less than or equal to `x`. flush file:flush()\nSaves any written data to `file`. flush io.flush()\nEquivalent to `io.output():flush()`. -fmod math.fmod(x, y)\nReturns the remainder of the division of `x` by `y` that rounds the\nquotient towards zero. (integer/float) -format string.format(formatstring, ···)\nReturns a formatted version of its variable number of arguments following the\ndescription given in its first argument, which must be a string. The format\nstring follows the same rules as the ISO C function `sprintf`. The only\ndifferences are that the conversion specifiers and modifiers `*`, `h`, `L`,\n`l`, and `n` are not supported and that there is an extra specifier, `q`.\n\nThe specifier `q` formats booleans, nil, numbers, and strings in a way that\nthe result is a valid constant in Lua source code. Booleans and nil are\nwritten in the obvious way (`true`, `false`, `nil`). Floats are written in\nhexadecimal, to preserve full precision. A string is written between double\nquotes, using escape sequences when necessary to ensure that it can safely be\nread back by the Lua interpreter. For instance, the call\n\n string.format('%q', 'a string with "quotes" and \\n new line')\n\nmay produce the string:\n\n "a string with \"quotes\" and \\n new line"\n\nThis specifier does not support modifiers (flags, width, length).\n\nThe conversion specifiers `A` and `a` (when available), `E`, `e`, `f`, `G`,\nand `g` all expect a number as argument. The specifiers `c`, `d`, `i`, `o`,\n`u`, `X`, and `x` expect an integer. When Lua is compiled with a C89\ncompiler, the specifiers `A` and `a` (hexadecimal floats) do not support\nmodifiers.\n\nThe specifier `s` expects a string; if its argument is not a string, it is\nconverted to one following the same rules of `tostring`. If the specifier has\nany modifier, the corresponding string argument should not contain zeros.\n\nThe specifier `p` formats the pointer returned by `lua_topointer`. That gives\na unique string identifier for tables, userdata, threads, strings, and\nfunctions. For other values (numbers, nil, booleans), this specifier results\nin a string representing the pointer `NULL`. -frexp math.frexp(x)\nReturns `m` and `e` such that 'x = m2^e', `e` is an integer and the\nabsolute value of `m` is in the range *[0.5, 1)* (or zero when `x` is zero).\n\nDeprecated in Lua 5.3. -getenv os.getenv(varname)\nReturns the value of the process environment variable `varname`, or\nnil if the variable is not defined. -getfenv _G.getfenv([f])\nReturns the current environment in use by the function. `f` can be a Lua\nfunction or a number that specifies the function at that stack level:\nLevel 1 is the function calling `getfenv`. If the given function is not a\nLua function, or if `f` is 0, `getfenv` returns the global environment. The\ndefault for `f` is 1.\n\nDeprecated in Lua 5.2. +fmod math.fmod(x, y)\nReturns the remainder of the division of `x` by `y` that rounds the quotient towards\nzero. (integer/float) +format string.format(formatstring, ···)\nReturns a formatted version of its variable number of arguments following the description\ngiven in its first argument, which must be a string. The format string follows the same rules\nas the ISO C function `sprintf`. The only differences are that the conversion specifiers and\nmodifiers `*`, `h`, `L`, `l`, and `n` are not supported and that there is an extra specifier,\n`q`.\n\nThe specifier `q` formats booleans, nil, numbers, and strings in a way that the result is a\nvalid constant in Lua source code. Booleans and nil are written in the obvious way (`true`,\n`false`, `nil`). Floats are written in hexadecimal, to preserve full precision. A string is\nwritten between double quotes, using escape sequences when necessary to ensure that it can\nsafely be read back by the Lua interpreter. For instance, the call\n\n string.format('%q', 'a string with "quotes" and \\n new line')\n\nmay produce the string:\n\n "a string with \"quotes\" and \ new line"\n\nThis specifier does not support modifiers (flags, width, length).\n\nThe conversion specifiers `A` and `a` (when available), `E`, `e`, `f`, `G`, and `g` all\nexpect a number as argument. The specifiers `c`, `d`, `i`, `o`, `u`, `X`, and `x` expect an\ninteger. When Lua is compiled with a C89 compiler, the specifiers `A` and `a` (hexadecimal\nfloats) do not support modifiers.\n\nThe specifier `s` expects a string; if its argument is not a string, it is converted to one\nfollowing the same rules of `tostring`. If the specifier has any modifier, the corresponding\nstring argument should not contain zeros.\n\nThe specifier `p` formats the pointer returned by `lua_topointer`. That gives a unique string\nidentifier for tables, userdata, threads, strings, and functions. For other values (numbers,\nnil, booleans), this specifier results in a string representing the pointer `NULL`. +frexp math.frexp(x)\nReturns `m` and `e` such that 'x = m2^e', `e` is an integer and the absolute value of `m`\nis in the range *[0.5, 1)* (or zero when `x` is zero).\n\nDeprecated in Lua 5.3. +getenv os.getenv(varname)\nReturns the value of the process environment variable `varname`, or nil if the variable is\nnot defined. +getfenv _G.getfenv([f])\nReturns the current environment in use by the function. `f` can be a Lua function or a\nnumber that specifies the function at that stack level: Level 1 is the function calling\n`getfenv`. If the given function is not a Lua function, or if `f` is 0, `getfenv` returns\nthe global environment. The default for `f` is 1.\n\nDeprecated in Lua 5.2. getfenv debug.getfenv(o)\nReturns the environment of object `o`.\n\nDeprecated in Lua 5.2. -gethook debug.gethook([thread])\nReturns the current hook settings of the thread, as three values: the\ncurrent hook function, the current hook mask, and the current hook count,\nas set by the `debug.sethook` function.\n\nReturns nil if there is no active hook. -getinfo debug.getinfo([thread, ] f [, what])\nReturns a table with information about a function. You can give the\nfunction directly or you can give a number as the value of `f`, which means\nthe function running at level `f` of the call stack of the given thread:\nlevel 0 is the current function (`getinfo` itself); level 1 is the function\nthat called `getinfo` (except for tail calls, which do not count in the\nstack); and so on. If `f` is a number greater than the number of active\nfunctions, then `getinfo` returns nil.\n\nThe returned table can contain all the fields returned by `lua_getinfo`,\nwith the string `what` describing which fields to fill in. The default for\n`what` is to get all information available, except the table of valid\nlines. If present, the option '`f`' adds a field named `func` with\nthe function itself. If present, the option '`L`' adds a field named\n`activelines` with the table of valid lines.\n\nFor instance, the expression `debug.getinfo(1,"n").name` returns a table\nwith a name for the current function, if a reasonable name can be found,\nand the expression `debug.getinfo(print)` returns a table with all available\ninformation about the `print` function. -getlocal debug.getlocal([thread, ] f, local)\nThis function returns the name and the value of the local variable with index\n`local` of the function at level `f` of the stack. This function accesses not\nonly explicit local variables, but also parameters and temporary values.\n\nThe first parameter or local variable has index 1, and so on, following the\norder that they are declared in the code, counting only the variables that\nare active in the current scope of the function. Compile-time constants may\nnot appear in this listing, if they were optimized away by the compiler.\nNegative indices refer to vararg parameters; -1 is the first vararg\nparameter. The function returns nil if there is no variable with the given\nindex, and raises an error when called with a level out of range. (You can\ncall `debug.getinfo` to check whether the level is valid.)\n\nVariable names starting with '(' (open parenthesis) represent variables with\nno known names (internal variables such as loop control variables, and\nvariables from chunks saved without debug information).\n\nThe parameter `f` may also be a function. In that case, `getlocal` returns\nonly the name of function parameters. -getmetatable _G.getmetatable(object)\nIf `object` does not have a metatable, returns nil. Otherwise, if the\nobject's metatable has a `__metatable` field, returns the associated\nvalue. Otherwise, returns the metatable of the given object. -getmetatable debug.getmetatable(value)\nReturns the metatable of the given `value` or nil if it does not have\na metatable. +gethook debug.gethook([thread])\nReturns the current hook settings of the thread, as three values: the current hook function,\nthe current hook mask, and the current hook count, as set by the `debug.sethook` function.\n\nReturns nil if there is no active hook. +getinfo debug.getinfo([thread, ] f [, what])\nReturns a table with information about a function. You can give the function directly or\nyou can give a number as the value of `f`, which means the function running at level `f`\nof the call stack of the given thread: level 0 is the current function (`getinfo` itself);\nlevel 1 is the function that called `getinfo` (except for tail calls, which do not count in\nthe stack); and so on. If `f` is a number greater than the number of active functions, then\n`getinfo` returns nil.\n\nThe returned table can contain all the fields returned by `lua_getinfo`, with the string\n`what` describing which fields to fill in. The default for `what` is to get all information\navailable, except the table of valid lines. If present, the option '`f`' adds a field named\n`func` with the function itself. If present, the option '`L`' adds a field named `activelines`\nwith the table of valid lines.\n\nFor instance, the expression `debug.getinfo(1,"n").name` returns a table with a name for the\ncurrent function, if a reasonable name can be found, and the expression `debug.getinfo(print)`\nreturns a table with all available information about the `print` function. +getlocal debug.getlocal([thread, ] f, local)\nThis function returns the name and the value of the local variable with index `local` of the\nfunction at level `f` of the stack. This function accesses not only explicit local variables,\nbut also parameters and temporary values.\n\nThe first parameter or local variable has index 1, and so on, following the order that\nthey are declared in the code, counting only the variables that are active in the current\nscope of the function. Compile-time constants may not appear in this listing, if they were\noptimized away by the compiler. Negative indices refer to vararg parameters; -1 is the first\nvararg parameter. The function returns nil if there is no variable with the given index,\nand raises an error when called with a level out of range. (You can call `debug.getinfo`\nto check whether the level is valid.)\n\nVariable names starting with '(' (open parenthesis) represent variables with no known names\n(internal variables such as loop control variables, and variables from chunks saved without\ndebug information).\n\nThe parameter `f` may also be a function. In that case, `getlocal` returns only the name of\nfunction parameters. +getmetatable _G.getmetatable(object)\nIf `object` does not have a metatable, returns nil. Otherwise, if the object's metatable\nhas a `__metatable` field, returns the associated value. Otherwise, returns the metatable\nof the given object. +getmetatable debug.getmetatable(value)\nReturns the metatable of the given `value` or nil if it does not have a metatable. getregistry debug.getregistry()\nReturns the registry table (see §4.3). -getupvalue debug.getupvalue(f, up)\nThis function returns the name and the value of the upvalue with index\n`up` of the function `f`. The function returns nil if there is no upvalue\nwith the given index.\n\n(For Lua functions, upvalues are the external local variables that the\nfunction uses, and that are consequently included in its closure.)\n\nFor C functions, this function uses the empty string `""` as a name for all\nupvalues.\n\nVariable name '`?`' (interrogation mark) represents variables with no known\nnames (variables from chunks saved without debug information). -getuservalue debug.getuservalue(u, n)\nReturns the `n`-th user value associated to the userdata `u` plus a boolean,\nfalse, if the userdata does not have that value.\n\nNew in Lua 5.2. -gmatch string.gmatch(s, pattern [, init])\nReturns an iterator function that, each time it is called, returns the\nnext captures from `pattern` (see §6.4.1) over the string `s`. If `pattern`\nspecifies no captures, then the whole match is produced in each call. A\nthird, optional argument `init` specifies where to start the search; its\ndefault value is 1 and can be negative.\n\nAs an example, the following loop will iterate over all the words from string\n`s`, printing one per line:\n\n s = "hello world from Lua"\n for w in string.gmatch(s, "%a+") do\n print(w)\n end\n\nThe next example collects all pairs `key=value` from the given string into a\ntable:\n\n t = {}\n s = "from=world, to=Lua"\n for k, v in string.gmatch(s, "(%w+)=(%w+)") do\n t[k] = v\n end\n\nFor this function, a caret '`^`' at the start of a pattern does not work as\nan anchor, as this would prevent the iteration. -gsub string.gsub(s, pattern, repl [, n])\nReturns a copy of `s` in which all (or the first `n`, if given)\noccurrences of the `pattern` (see §6.4.1) have been replaced by a replacement\nstring specified by `repl`, which can be a string, a table, or a function.\n`gsub` also returns, as its second value, the total number of matches that\noccurred. The name `gsub` comes from "Global SUBstitution".\n\nIf `repl` is a string, then its value is used for replacement. The character\n`%` works as an escape character: any sequence in `repl` of the form `%d`,\nwith `d` between 1 and 9, stands for the value of the `d`-th captured\nsubstring; the sequence `%0` stands for the whole match; the sequence `%%`\nstands for a single `%`.\n\nIf `repl` is a table, then the table is queried for every match, using\nthe first capture as the key.\n\nIf `repl` is a function, then this function is called every time a match\noccurs, with all captured substrings passed as arguments, in order.\n\nIn any case, if the pattern specifies no captures, then it behaves as if the\nwhole pattern was inside a capture.\n\nIf the value returned by the table query or by the function call is a\nstring or a number, then it is used as the replacement string; otherwise,\nif it is false or nil, then there is no replacement (that is, the original\nmatch is kept in the string).\n\nHere are some examples:\n\n x = string.gsub("hello world", "(%w+)", "%1 %1")\n --> x="hello hello world world"\n x = string.gsub("hello world", "%w+", "%0 %0", 1)\n --> x="hello hello world"\n x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")\n --> x="world hello Lua from"\n x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)\n --> x="home = /home/roberto, user = roberto"\n x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)\n return load(s)()\n end)\n --> x="4+5 = 9"\n local t = {name="lua", version="5.4"}\n x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)\n --> x="lua-5.4.tar.gz" +getupvalue debug.getupvalue(f, up)\nThis function returns the name and the value of the upvalue with index `up` of the function\n`f`. The function returns nil if there is no upvalue with the given index.\n\n(For Lua functions, upvalues are the external local variables that the function uses, and\nthat are consequently included in its closure.)\n\nFor C functions, this function uses the empty string `""` as a name for all upvalues.\n\nVariable name '`?`' (interrogation mark) represents variables with no known names (variables\nfrom chunks saved without debug information). +getuservalue debug.getuservalue(u, n)\nReturns the `n`-th user value associated to the userdata `u` plus a boolean, false, if the\nuserdata does not have that value.\n\nNew in Lua 5.2. +gmatch string.gmatch(s, pattern [, init])\nReturns an iterator function that, each time it is called, returns the next captures from\n`pattern` (see §6.4.1) over the string `s`. If `pattern` specifies no captures, then the\nwhole match is produced in each call. A third, optional argument `init` specifies where to\nstart the search; its default value is 1 and can be negative.\n\nAs an example, the following loop will iterate over all the words from string `s`, printing\none per line:\n\n s = "hello world from Lua" for w in string.gmatch(s, "%a+") do\n print(w) end\n\nThe next example collects all pairs `key=value` from the given string into a table:\n\n t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do\n t[k] = v end\n\nFor this function, a caret '`^`' at the start of a pattern does not work as an anchor,\nas this would prevent the iteration. +gsub string.gsub(s, pattern, repl [, n])\nReturns a copy of `s` in which all (or the first `n`, if given) occurrences of the `pattern`\n(see §6.4.1) have been replaced by a replacement string specified by `repl`, which can be\na string, a table, or a function. `gsub` also returns, as its second value, the total number\nof matches that occurred. The name `gsub` comes from "Global SUBstitution".\n\nIf `repl` is a string, then its value is used for replacement. The character `%` works as an\nescape character: any sequence in `repl` of the form `%d`, with `d` between 1 and 9, stands\nfor the value of the `d`-th captured substring; the sequence `%0` stands for the whole match;\nthe sequence `%%` stands for a single `%`.\n\nIf `repl` is a table, then the table is queried for every match, using the first capture as\nthe key.\n\nIf `repl` is a function, then this function is called every time a match occurs, with all\ncaptured substrings passed as arguments, in order.\n\nIn any case, if the pattern specifies no captures, then it behaves as if the whole pattern\nwas inside a capture.\n\nIf the value returned by the table query or by the function call is a string or a number,\nthen it is used as the replacement string; otherwise, if it is false or nil, then there is\nno replacement (that is, the original match is kept in the string).\n\nHere are some examples:\n\n x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world" x =\n string.gsub("hello world", "%w+", "%0 %0", 1) --> x="hello hello world" x = string.gsub("hello\n world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from" x = string.gsub("home\n = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto"\n x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)\n return load(s)() end)\n --> x="4+5 = 9" local t = {name="lua", version="5.4"} x = string.gsub("$name-$version.tar.gz",\n "%$(%w+)", t) --> x="lua-5.4.tar.gz" huge math.huge (number)\nThe float value `HUGE_VAL`, a value greater than any other numerical value. -input io.input([file])\nWhen called with a file name, it opens the named file (in text mode),\nand sets its handle as the default input file. When called with a file\nhandle, it simply sets this file handle as the default input file. When\ncalled without parameters, it returns the current default input file.\n\nIn case of errors this function raises the error, instead of returning an\nerror code. -insert table.insert(list, [pos, ] value)\nInserts element `value` at position `pos` in `list`, shifting up the elements\n`list[pos], list[pos+1], ···, list[#list]`. The default value for `pos` is\n`#list+1`, so that a call `table.insert(t,x)` inserts `x` at the end of the\nlist `t`. +input io.input([file])\nWhen called with a file name, it opens the named file (in text mode), and sets its handle as\nthe default input file. When called with a file handle, it simply sets this file handle as the\ndefault input file. When called without parameters, it returns the current default input file.\n\nIn case of errors this function raises the error, instead of returning an error code. +insert table.insert(list, [pos, ] value)\nInserts element `value` at position `pos` in `list`, shifting up the elements `list[pos],\nlist[pos+1], ···, list[#list]`. The default value for `pos` is `#list+1`, so that a call\n`table.insert(t,x)` inserts `x` at the end of the list `t`. io _G.io (module)\nLua io module. -ipairs _G.ipairs(t)\nReturns three values (an iterator function, the table `t`, and 0) so that the\nconstruction\n\n for i,v in ipairs(t) do *body* end\n\nwill iterate over the key-value pairs (`1,t[1]`), (`2,t[2]`), ···, up to the\nfirst absent index. -isyieldable coroutine.isyieldable([co])\nReturns true when the coroutine `co` can yield. The default for `co` is the\nrunning coroutine.\n\nA coroutine is yieldable if it is not the main thread and it is not inside a\nnon-yieldable C function.\n\nNew in Lua 5.3. +ipairs _G.ipairs(t)\nReturns three values (an iterator function, the table `t`, and 0) so that the construction\n\n for i,v in ipairs(t) do *body* end\n\nwill iterate over the key-value pairs (`1,t[1]`), (`2,t[2]`), ···, up to the first\nabsent index. +isyieldable coroutine.isyieldable([co])\nReturns true when the coroutine `co` can yield. The default for `co` is the running coroutine.\n\nA coroutine is yieldable if it is not the main thread and it is not inside a non-yieldable\nC function.\n\nNew in Lua 5.3. ldexp math.ldexp(m, e)\nReturns 'm2^e' (`e` should be an integer).\n\nDeprecated in Lua 5.3. -len string.len(s)\nReceives a string and returns its length. The empty string `""` has\nlength 0. Embedded zeros are counted, so `"a\000bc\000"` has length 5. -len utf8.len(s [, i [, j [, lax]]])\nReturns the number of UTF-8 characters in string `s` that start between\npositions `i` and `j` (both inclusive). The default for `i` is 1 and for `j`\nis -1. If it finds any invalid byte sequence, returns nil plus the position\nof the first invalid byte.\n\nThis function only accepts valid sequences (well formed and not overlong).\nBy default, it only accepts byte sequences that result in valid Unicode code\npoints, rejecting values greater than `10FFFF` and surrogates. The boolean\nargument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are\naccepted. (Not well formed and overlong sequences are still rejected.)\n\nNew in Lua 5.3. +len string.len(s)\nReceives a string and returns its length. The empty string `""` has length 0. Embedded zeros\nare counted, so `"a\000bc\000"` has length 5. +len utf8.len(s [, i [, j [, lax]]])\nReturns the number of UTF-8 characters in string `s` that start between positions `i` and `j`\n(both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte\nsequence, returns nil plus the position of the first invalid byte.\n\nThis function only accepts valid sequences (well formed and not overlong). By default, it only\naccepts byte sequences that result in valid Unicode code points, rejecting values greater than\n`10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values\nup to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.)\n\nNew in Lua 5.3. lfs _G.lfs (module)\nLua lfs module. -lines file:lines(···)\nReturns an iterator function that, each time it is called, reads the file\naccording to the given formats. When no format is given, uses "l" as a\ndefault. As an example, the construction\n\n for c in file:lines(1) do *body* end\n\nwill iterate over all characters of the file, starting at the current\nposition. Unlike `io.lines`, this function does not close the file when the\nloop ends. -lines io.lines([filename, ···])\nOpens the given file name in read mode and returns an iterator function that\nworks like `file:lines(···)` over the opened file. When the iterator function\nfails to read any value, it automatically closes the file. Besides the\niterator function, `io.lines` returns three other values: two nil values as\nplaceholders, plus the created file handle. Therefore, when used in a generic\nfor loop, the file is closed also if the loop is interrupted by an error or a\n`break`.\n\nThe call `io.lines()` (with no file name) is equivalent to\n`io.input():lines("l")`; that is, it iterates over the lines of the default\ninput file. In this case it does not close the file when the loop ends.\n\nIn case of errors opening the file, this function raises the error, instead\nof returning an error code. -link lfs.link(old, new[, symlink])\nCreates a link. The first argument is the object to link to and the second is\nthe name of the link. If the optional third argument is true, the link will\nbe a symbolic link (by default, a hard link is created). -load _G.load(chunk [, chunkname [, mode [, env]]])\nLoads a chunk.\n\nIf `chunk` is a string, the chunk is this string. If `chunk` is a function,\n`load` calls it repeatedly to get the chunk pieces. Each call to `chunk` must\nreturn a string that concatenates with previous results. A return of an empty\nstring, nil, or no value signals the end of the chunk.\n\nIf there are no syntactic errors, `load` returns the compiled chunk as a\nfunction; otherwise, it returns nil plus the error message.\n\nWhen you load a main chunk, the resulting function will always have exactly\none upvalue, the `_ENV` variable (see §2.2). However, when you load a binary\nchunk created from a function (see `string.dump`), the resulting function can\nhave an arbitrary number of upvalues, and there is no guarantee that its\nfirst upvalue will be the `_ENV` variable. (A non-main function may not even\nhave an `_ENV` upvalue.)\n\nRegardless, if the resulting function has any upvalues, its first upvalue is\nset to the value of `env`, if that parameter is given, or to the value of the\nglobal environment. Other upvalues are initialized with nil. All upvalues are\nfresh, that is, they are not shared with any other function.\n\n`chunkname` is used as the name of the chunk for error messages and debug\ninformation (see §4.7). When absent, it defaults to `chunk`, if `chunk` is a\nstring, or to "`=(load)`" otherwise.\n\nThe string `mode` controls whether the chunk can be text or binary (that is,\na precompiled chunk). It may be the string "`b`" (only binary chunks), "`t`"\n(only text chunks), or "`bt`" (both binary and text). The default is "`bt`".\n\nIt is safe to load malformed binary chunks; `load` signals an appropriate\nerror. However, Lua does not check the consistency of the code inside binary\nchunks; running maliciously crafted bytecode can crash the interpreter. -loaded package.loaded (table)\nA table used by `require` to control which modules are already loaded. When\nyou require a module `modname` and `package.loaded[modname]` is not false,\n`require` simply returns the value stored there.\nThis variable is only a reference to the real table; assignments to this\nvariable do not change the table used by `require`. +lines file:lines(···)\nReturns an iterator function that, each time it is called, reads the file according to the\ngiven formats. When no format is given, uses "l" as a default. As an example, the construction\n\n for c in file:lines(1) do *body* end\n\nwill iterate over all characters of the file, starting at the current position. Unlike\n`io.lines`, this function does not close the file when the loop ends. +lines io.lines([filename, ···])\nOpens the given file name in read mode and returns an iterator function that works like\n`file:lines(···)` over the opened file. When the iterator function fails to read any value,\nit automatically closes the file. Besides the iterator function, `io.lines` returns three other\nvalues: two nil values as placeholders, plus the created file handle. Therefore, when used in\na generic for loop, the file is closed also if the loop is interrupted by an error or a `break`.\n\nThe call `io.lines()` (with no file name) is equivalent to `io.input():lines("l")`; that is,\nit iterates over the lines of the default input file. In this case it does not close the\nfile when the loop ends.\n\nIn case of errors opening the file, this function raises the error, instead of returning an\nerror code. +link lfs.link(old, new[, symlink])\nCreates a link. The first argument is the object to link to and the second is the name of the\nlink. If the optional third argument is true, the link will be a symbolic link (by default,\na hard link is created). +load _G.load(chunk [, chunkname [, mode [, env]]])\nLoads a chunk.\n\nIf `chunk` is a string, the chunk is this string. If `chunk` is a function, `load` calls\nit repeatedly to get the chunk pieces. Each call to `chunk` must return a string that\nconcatenates with previous results. A return of an empty string, nil, or no value signals\nthe end of the chunk.\n\nIf there are no syntactic errors, `load` returns the compiled chunk as a function; otherwise,\nit returns nil plus the error message.\n\nWhen you load a main chunk, the resulting function will always have exactly one upvalue, the\n`_ENV` variable (see §2.2). However, when you load a binary chunk created from a function\n(see `string.dump`), the resulting function can have an arbitrary number of upvalues,\nand there is no guarantee that its first upvalue will be the `_ENV` variable. (A non-main\nfunction may not even have an `_ENV` upvalue.)\n\nRegardless, if the resulting function has any upvalues, its first upvalue is set to the\nvalue of `env`, if that parameter is given, or to the value of the global environment. Other\nupvalues are initialized with nil. All upvalues are fresh, that is, they are not shared with\nany other function.\n\n`chunkname` is used as the name of the chunk for error messages and debug information (see\n§4.7). When absent, it defaults to `chunk`, if `chunk` is a string, or to "`=(load)`"\notherwise.\n\nThe string `mode` controls whether the chunk can be text or binary (that is, a precompiled\nchunk). It may be the string "`b`" (only binary chunks), "`t`" (only text chunks), or "`bt`"\n(both binary and text). The default is "`bt`".\n\nIt is safe to load malformed binary chunks; `load` signals an appropriate error. However,\nLua does not check the consistency of the code inside binary chunks; running maliciously\ncrafted bytecode can crash the interpreter. +loaded package.loaded (table)\nA table used by `require` to control which modules are already loaded. When you require\na module `modname` and `package.loaded[modname]` is not false, `require` simply returns\nthe value stored there.\n\nThis variable is only a reference to the real table; assignments to this variable do not\nchange the table used by `require`. loaders package.loaders (table)\nSee `package.searchers`.\n\nDeprecated in Lua 5.2. -loadfile _G.loadfile([filename [, mode [, env]]])\nSimilar to `load`, but gets the chunk from file `filename` or from the\nstandard input, if no file name is given. -loadlib package.loadlib(libname, funcname)\nDynamically links the host program with the C library `libname`.\n\nIf `funcname` is "`*`", then it only links with the library, making the\nsymbols exported by the library available to other dynamically linked\nlibraries. Otherwise, it looks for a function `funcname` inside the library\nand returns this function as a C function. So, `funcname` must follow the\n`lua_CFunction` prototype (see `lua_CFunction`).\n\nThis is a low-level function. It completely bypasses the package and module\nsystem. Unlike `require`, it does not perform any path searching and does\nnot automatically adds extensions. `libname` must be the complete file name\nof the C library, including if necessary a path and an extension. `funcname`\nmust be the exact name exported by the C library (which may depend on the\nC compiler and linker used).\n\nThis function is not supported by Standard C. As such, it is only available\non some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix\nsystems that support the `dlfcn` standard).\n\nThis function is inherently insecure, as it allows Lua to call any function\nin any readable dynamic library in the system. (Lua calls any function\nassuming the function has a proper prototype and respects a proper protocol\n(see lua_CFunction). Therefore, calling an arbitrary function in an arbitrary\ndynamic library more often than not results in an access violation.) -loadstring _G.loadstring(string [, chunkname])\nSimilar to `load`, but gets the chunk from the given string. To load and\nrun a given string, use the idiom assert(loadstring(s))() When absent,\n`chunkname` defaults to the given string.\n\nDeprecated in Lua 5.2. -locale lpeg.locale([table])\nReturns a table with patterns for matching some character classes according\nto the current locale. The table has fields named `alnum`, `alpha`, `cntrl`,\n`digit`, `graph`, `lower`, `print`, `punct`, `space`, `upper`, and `xdigit`,\neach one containing a correspondent pattern. Each pattern matches any single\ncharacter that belongs to its class.\n\nIf called with an argument `table`, then it creates those fields inside the\ngiven table and returns that table. -lock lfs.lock(filehandle, mode[, start[, length]])\nLocks a file or a part of it. This function works on open files; the file\nhandle should be specified as the first argument. The string mode could be\neither r (for a read/shared lock) or w (for a write/exclusive lock). The\noptional arguments start and length can be used to specify a starting point\nand its length; both should be numbers.\n\nReturns true if the operation was successful; in case of error, it returns\nnil plus an error string. -lock_dir lfs.lock_dir(path, [seconds_stale])\nCreates a lockfile (called lockfile.lfs) in path if it does not exist and\nreturns the lock. If the lock already exists checks if it's stale, using the\nsecond parameter (default for the second parameter is INT_MAX, which in\npractice means the lock will never be stale. To free the the lock call\nlock:free().\n\nIn case of any errors it returns nil and the error message. In particular,\nif the lock exists and is not stale it returns the "File exists" message. -log math.log(x [, base])\nReturns the logarithm of `x` in the given base. The default for `base` is 'e'\n(so that the function returns the natural logarithm of `x`). +loadfile _G.loadfile([filename [, mode [, env]]])\nSimilar to `load`, but gets the chunk from file `filename` or from the standard input,\nif no file name is given. +loadlib package.loadlib(libname, funcname)\nDynamically links the host program with the C library `libname`.\n\nIf `funcname` is "`*`", then it only links with the library, making the symbols exported\nby the library available to other dynamically linked libraries. Otherwise, it looks for\na function `funcname` inside the library and returns this function as a C function. So,\n`funcname` must follow the `lua_CFunction` prototype (see `lua_CFunction`).\n\nThis is a low-level function. It completely bypasses the package and module system. Unlike\n`require`, it does not perform any path searching and does not automatically adds\nextensions. `libname` must be the complete file name of the C library, including if necessary\na path and an extension. `funcname` must be the exact name exported by the C library (which\nmay depend on the C compiler and linker used).\n\nThis function is not supported by Standard C. As such, it is only available on some platforms\n(Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the `dlfcn`\nstandard).\n\nThis function is inherently insecure, as it allows Lua to call any function in any readable\ndynamic library in the system. (Lua calls any function assuming the function has a proper\nprototype and respects a proper protocol (see lua_CFunction). Therefore, calling an arbitrary\nfunction in an arbitrary dynamic library more often than not results in an access violation.) +loadstring _G.loadstring(string [, chunkname])\nSimilar to `load`, but gets the chunk from the given string. To load and run a given string,\nuse the idiom assert(loadstring(s))() When absent, `chunkname` defaults to the given string.\n\nDeprecated in Lua 5.2. +locale lpeg.locale([table])\nReturns a table with patterns for matching some character classes according to the current\nlocale. The table has fields named `alnum`, `alpha`, `cntrl`, `digit`, `graph`, `lower`,\n`print`, `punct`, `space`, `upper`, and `xdigit`, each one containing a correspondent\npattern. Each pattern matches any single character that belongs to its class.\n\nIf called with an argument `table`, then it creates those fields inside the given table and\nreturns that table. +lock lfs.lock(filehandle, mode[, start[, length]])\nLocks a file or a part of it. This function works on open files; the file handle should be\nspecified as the first argument. The string mode could be either r (for a read/shared lock)\nor w (for a write/exclusive lock). The optional arguments start and length can be used to\nspecify a starting point and its length; both should be numbers.\n\nReturns true if the operation was successful; in case of error, it returns nil plus an\nerror string. +lock_dir lfs.lock_dir(path, [seconds_stale])\nCreates a lockfile (called lockfile.lfs) in path if it does not exist and returns the lock. If\nthe lock already exists checks if it's stale, using the second parameter (default for the\nsecond parameter is INT_MAX, which in practice means the lock will never be stale. To free\nthe the lock call lock:free().\n\nIn case of any errors it returns nil and the error message. In particular, if the lock exists\nand is not stale it returns the "File exists" message. +log math.log(x [, base])\nReturns the logarithm of `x` in the given base. The default for `base` is 'e' (so that the\nfunction returns the natural logarithm of `x`). log10 math.log10(x)\nReturns the base-10 logarithm of `x`.\n\nDeprecated in Lua 5.2. -lower string.lower(s)\nReceives a string and returns a copy of this string with all uppercase\nletters changed to lowercase. All other characters are left unchanged. The\ndefinition of what an uppercase letter is depends on the current locale. +lower string.lower(s)\nReceives a string and returns a copy of this string with all uppercase letters changed to\nlowercase. All other characters are left unchanged. The definition of what an uppercase\nletter is depends on the current locale. lpeg _G.lpeg (module)\nLua lpeg module. -lrotate bit32.lrotate(x, disp)\nReturns the number `x` rotated `disp` bits to the left. The number `disp` may\nbe any representable integer.\n\nFor any valid displacement, the following identity holds:\n\n assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))\n\nIn particular, negative displacements rotate to the right.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -lshift bit32.lshift(x, disp)\nReturns the number `x` shifted `disp` bits to the left. The number `disp` may\nbe any representable integer. Negative displacements shift to the right. In\nany direction, vacant bits are filled with zeros. In particular,\ndisplacements with absolute values higher than 31 result in zero (all bits\nare shifted out).\n\nFor positive displacements, the following equality holds:\n\n assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -match lpeg.match(pattern, subject [, init])\nThe matching function. It attempts to match the given pattern against the\nsubject string. If the match succeeds, returns the index in the subject of\nthe first character after the match, or the captured values (if the pattern\ncaptured any value).\n\nAn optional numeric argument `init` makes the match start at that position in\nthe subject string. As usual in Lua libraries, a negative value counts from\nthe end.\n\nUnlike typical pattern-matching functions, match works only in anchored mode;\nthat is, it tries to match the pattern with a prefix of the given subject\nstring (at position `init`), not with an arbitrary substring of the subject.\nSo, if we want to find a pattern anywhere in a string, we must either write a\nloop in Lua or write a pattern that matches anywhere. This second approach is\neasy and quite efficient; see examples. -match string.match(s, pattern [, init])\nLooks for the first *match* of the `pattern` (see §6.4.1) in the string `s`.\nIf it finds one, then `match` returns the captures from the pattern;\notherwise it returns nil. If `pattern` specifies no captures, then the whole\nmatch is returned. A third, optional numerical argument `init` specifies\nwhere to start the search; its default value is 1 and can be negative. +lrotate bit32.lrotate(x, disp)\nReturns the number `x` rotated `disp` bits to the left. The number `disp` may be any\nrepresentable integer.\n\nFor any valid displacement, the following identity holds:\n\n assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))\n\nIn particular, negative displacements rotate to the right.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +lshift bit32.lshift(x, disp)\nReturns the number `x` shifted `disp` bits to the left. The number `disp` may be any\nrepresentable integer. Negative displacements shift to the right. In any direction, vacant\nbits are filled with zeros. In particular, displacements with absolute values higher than\n31 result in zero (all bits are shifted out).\n\nFor positive displacements, the following equality holds:\n\n assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +match lpeg.match(pattern, subject [, init])\nThe matching function. It attempts to match the given pattern against the subject string. If\nthe match succeeds, returns the index in the subject of the first character after the match,\nor the captured values (if the pattern captured any value).\n\nAn optional numeric argument `init` makes the match start at that position in the subject\nstring. As usual in Lua libraries, a negative value counts from the end.\n\nUnlike typical pattern-matching functions, match works only in anchored mode; that is, it\ntries to match the pattern with a prefix of the given subject string (at position `init`),\nnot with an arbitrary substring of the subject. So, if we want to find a pattern anywhere in\na string, we must either write a loop in Lua or write a pattern that matches anywhere. This\nsecond approach is easy and quite efficient; see examples. +match string.match(s, pattern [, init])\nLooks for the first *match* of the `pattern` (see §6.4.1) in the string `s`. If it finds one,\nthen `match` returns the captures from the pattern; otherwise it returns nil. If `pattern`\nspecifies no captures, then the whole match is returned. A third, optional numerical argument\n`init` specifies where to start the search; its default value is 1 and can be negative. math _G.math (module)\nLua math module. -max math.max(x, ···)\nReturns the argument with the maximum value, according to the Lua operator\n`<`. +max math.max(x, ···)\nReturns the argument with the maximum value, according to the Lua operator `<`. maxinteger math.maxinteger (number)\nAn integer with the maximum value for an integer.\n\nNew in Lua 5.3. -maxn table.maxn(table)\nReturns the largest positive numerical index of the given table, or zero if\nthe table has no positive numerical indices. (To do its job this function\ndoes a linear traversal of the whole table.)\n\nDeprecated in Lua 5.2. -min math.min(x, ···)\nReturns the argument with the minimum value, according to the Lua operator\n`<`. +maxn table.maxn(table)\nReturns the largest positive numerical index of the given table, or zero if the table has\nno positive numerical indices. (To do its job this function does a linear traversal of the\nwhole table.)\n\nDeprecated in Lua 5.2. +min math.min(x, ···)\nReturns the argument with the minimum value, according to the Lua operator `<`. mininteger math.mininteger (number)\nAn integer with the minimum value for an integer.\n\nNew in Lua 5.3. -mkdir lfs.mkdir(dirname)\nCreates a new directory. The argument is the name of the new directory.\n\nReturns true in case of success or nil, an error message and a\nsystem-dependent error code in case of error. -modf math.modf(x)\nReturns the integral part of `x` and the fractional part of `x`. Its second\nresult is always a float. -module _G.module(name [, ···])\nCreates a module. If there is a table in `package.loaded[name]`, this table\nis the module. Otherwise, if there is a global table `t` with the given name,\nthis table is the module. Otherwise creates a new table `t` and sets it as\nthe value of the global `name` and the value of `package.loaded[name]`. This\nfunction also initializes `t._NAME` with the given name, `t._M` with the\nmodule (`t` itself), and `t._PACKAGE` with the package name (the full module\nname minus last component; see below). Finally, `module` sets `t` as the new\nenvironment of the current function and the new value of\n`package.loaded[name]`, so that `require` returns `t`. If `name` is a\ncompound name (that is, one with components separated by dots), `module`\ncreates (or reuses, if they already exist) tables for each component. For\ninstance, if `name` is `a.b.c`, then `module` stores the module table in\nfield `c` of field `b` of global `a`. This function can receive optional\n*options* after the module name, where each option is a function to be\napplied over the module.\n\nDeprecated in Lua 5.2. -move table.move(a1, f, e, t [, a2])\nMoves elements from the table `a1` to the table `a2`, performing the\nequivalent to the following multiple assignment: `a2[t], ··· = a1[f], ···,\na1[e]`. The default for `a2` is `a1`. The destination range can overlap with\nthe source range. Index `f` must be positive.\n\nReturns the destination table `a2`.\n\nNew in Lua 5.3. -next _G.next(table [, index])\nAllows a program to traverse all fields of a table. Its first argument is\na table and its second argument is an index in this table. A call to `next`\nreturns the next index of the table and its associated value. When called\nwith nil as its second argument, `next` returns an initial index and its\nassociated value. When called with the last index, or with nil in an empty\ntable, `next` returns nil. If the second argument is absent, then it is\ninterpreted as nil. In particular, you can use `next(t)` to check whether a\ntable is empty.\n\nThe order in which the indices are enumerated is not specified, *even for\nnumeric indices*. (To traverse a table in numeric order, use a numerical\n`for`.)\n\nThe behavior of `next` is undefined if, during the traversal, you assign any\nvalue to a non-existent field in the table. You may however modify existing\nfields. In particular, you may set existing fields to nil. -offset utf8.offset(s, n [, i])\nReturns the position (in bytes) where the encoding of the `n`-th character of\n`s` (counting from position `i`) starts. A negative `n` gets characters\nbefore position `i`. The default for `i` is 1 when `n` is non-negative and\n`#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the\n`n`-th character from the end of the string. If the specified character is\nneither in the subject nor right after its end, the function returns nil.\n\nAs a special case, when `n` is 0 the function returns the start of the\nencoding of the character that contains the `i`-th byte of `s`.\n\nThis function assumes that `s` is a valid UTF-8 string.\n\nNew in Lua 5.3. -open io.open(filename [, mode])\nThis function opens a file, in the mode specified in the string `mode`. It\nreturns a new file handle, or, in case of errors, nil plus an error message.\n\nThe `mode` string can be any of the following:\n "r": read mode (the default);\n "w": write mode;\n "a": append mode;\n "r+": update mode, all previous data is preserved;\n "w+": update mode, all previous data is erased;\n "a+": append update mode, previous data is preserved, writing is only\n allowed at the end of file.\n\nThe `mode` string can also have a '`b`' at the end, which is needed in\nsome systems to open the file in binary mode. +mkdir lfs.mkdir(dirname)\nCreates a new directory. The argument is the name of the new directory.\n\nReturns true in case of success or nil, an error message and a system-dependent error code\nin case of error. +modf math.modf(x)\nReturns the integral part of `x` and the fractional part of `x`. Its second result is always\na float. +module _G.module(name [, ···])\nCreates a module. If there is a table in `package.loaded[name]`, this table is the\nmodule. Otherwise, if there is a global table `t` with the given name, this table is the\nmodule. Otherwise creates a new table `t` and sets it as the value of the global `name`\nand the value of `package.loaded[name]`. This function also initializes `t._NAME` with the\ngiven name, `t._M` with the module (`t` itself), and `t._PACKAGE` with the package name\n(the full module name minus last component; see below). Finally, `module` sets `t` as the\nnew environment of the current function and the new value of `package.loaded[name]`, so that\n`require` returns `t`. If `name` is a compound name (that is, one with components separated\nby dots), `module` creates (or reuses, if they already exist) tables for each component. For\ninstance, if `name` is `a.b.c`, then `module` stores the module table in field `c` of field\n`b` of global `a`. This function can receive optional *options* after the module name,\nwhere each option is a function to be applied over the module.\n\nDeprecated in Lua 5.2. +move table.move(a1, f, e, t [, a2])\nMoves elements from the table `a1` to the table `a2`, performing the equivalent to the\nfollowing multiple assignment: `a2[t], ··· = a1[f], ···, a1[e]`. The default for `a2`\nis `a1`. The destination range can overlap with the source range. Index `f` must be positive.\n\nReturns the destination table `a2`.\n\nNew in Lua 5.3. +next _G.next(table [, index])\nAllows a program to traverse all fields of a table. Its first argument is a table and its\nsecond argument is an index in this table. A call to `next` returns the next index of the\ntable and its associated value. When called with nil as its second argument, `next` returns\nan initial index and its associated value. When called with the last index, or with nil in\nan empty table, `next` returns nil. If the second argument is absent, then it is interpreted\nas nil. In particular, you can use `next(t)` to check whether a table is empty.\n\nThe order in which the indices are enumerated is not specified, *even for numeric indices*. (To\ntraverse a table in numeric order, use a numerical `for`.)\n\nThe behavior of `next` is undefined if, during the traversal, you assign any value to a\nnon-existent field in the table. You may however modify existing fields. In particular,\nyou may set existing fields to nil. +offset utf8.offset(s, n [, i])\nReturns the position (in bytes) where the encoding of the `n`-th character of `s` (counting\nfrom position `i`) starts. A negative `n` gets characters before position `i`. The default\nfor `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)`\ngets the offset of the `n`-th character from the end of the string. If the specified character\nis neither in the subject nor right after its end, the function returns nil.\n\nAs a special case, when `n` is 0 the function returns the start of the encoding of the\ncharacter that contains the `i`-th byte of `s`.\n\nThis function assumes that `s` is a valid UTF-8 string.\n\nNew in Lua 5.3. +open io.open(filename [, mode])\nThis function opens a file, in the mode specified in the string `mode`. It returns a new\nfile handle, or, in case of errors, nil plus an error message.\n\nThe `mode` string can be any of the following:\n\n * "r": read mode (the default);\n * "w": write mode;\n * "a": append mode;\n * "r+": update mode, all previous data is preserved;\n * "w+": update mode, all previous data is erased;\n * "a+": append update mode, previous data is preserved, writing is only allowed at the\n end of file.\n\nThe `mode` string can also have a '`b`' at the end, which is needed in some systems to open\nthe file in binary mode. os _G.os (module)\nLua os module. output io.output([file])\nSimilar to `io.input`, but operates over the default output file. -pack string.pack(fmt, v1, v2, ···)\nReturns a binary string containing the values `v1`, `v2`, etc. serialized in\nbinary form (packed) according to the format string `fmt` (see §6.4.2).\n\nNew in Lua 5.3. -pack table.pack(···)\nReturns a new table with all parameters stored into keys 1, 2, etc. and with\na field "`n`" with the total number of parameters. Note that the resulting\ntable may not be a sequence, if some arguments are nil.\n\nNew in Lua 5.2. +pack string.pack(fmt, v1, v2, ···)\nReturns a binary string containing the values `v1`, `v2`, etc. serialized in binary form\n(packed) according to the format string `fmt` (see §6.4.2).\n\nNew in Lua 5.3. +pack table.pack(···)\nReturns a new table with all parameters stored into keys 1, 2, etc. and with a field "`n`"\nwith the total number of parameters. Note that the resulting table may not be a sequence,\nif some arguments are nil.\n\nNew in Lua 5.2. package _G.package (module)\nLua package module. -packsize string.packsize(fmt)\nReturns the size of a string resulting from `string.pack` with the given\nformat. The format string cannot have the variable-length options 's' or 'z'\n(see §6.4.2).\n\nNew in Lua 5.3. -pairs _G.pairs(t)\nIf `t` has a metamethod `__pairs`, calls it with `t` as argument and returns\nthe first three results from the call.\n\nOtherwise, returns three values: the `next` function, the table `t`, and nil,\nso that the construction\n\n for k,v in pairs(t) do *body* end\n\nwill iterate over all key–value pairs of table `t`.\n\nSee function `next` for the caveats of modifying the table during its\ntraversal. -path package.path (string)\nA string with the path used by `require` to search for a Lua loader.\nAt start-up, Lua initializes this variable with the value of the\nenvironment variable `LUA_PATH_5_4` or the environment variable `LUA_PATH`\nor with a default path defined in `luaconf.h`, if those environment\nvariables are not defined. A "`;;`" in the value of the environment\nvariable is replaced by the default path. -pcall _G.pcall(f [, arg1, ···])\nCalls the function `f` with the given arguments in *protected mode*. This\nmeans that any error inside `f` is not propagated; instead, `pcall` catches\nthe error and returns a status code. Its first result is the status code (a\nboolean), which is true if the call succeeds without errors. In such case,\n`pcall` also returns all results from the call, after this first result. In\ncase of any error, `pcall` returns false plus the error object. Note that\nerrors caught by `pcall` do not call a message handler. +packsize string.packsize(fmt)\nReturns the size of a string resulting from `string.pack` with the given format. The format\nstring cannot have the variable-length options 's' or 'z' (see §6.4.2).\n\nNew in Lua 5.3. +pairs _G.pairs(t)\nIf `t` has a metamethod `__pairs`, calls it with `t` as argument and returns the first three\nresults from the call.\n\nOtherwise, returns three values: the `next` function, the table `t`, and nil, so that the\nconstruction\n\n for k,v in pairs(t) do *body* end\n\nwill iterate over all key–value pairs of table `t`.\n\nSee function `next` for the caveats of modifying the table during its traversal. +path package.path (string)\nA string with the path used by `require` to search for a Lua loader.\n\nAt start-up, Lua initializes this variable with the value of the environment variable\n`LUA_PATH_5_4` or the environment variable `LUA_PATH` or with a default path defined in\n`luaconf.h`, if those environment variables are not defined. A "`;;`" in the value of the\nenvironment variable is replaced by the default path. +pcall _G.pcall(f [, arg1, ···])\nCalls the function `f` with the given arguments in *protected mode*. This means that any\nerror inside `f` is not propagated; instead, `pcall` catches the error and returns a status\ncode. Its first result is the status code (a boolean), which is true if the call succeeds\nwithout errors. In such case, `pcall` also returns all results from the call, after this\nfirst result. In case of any error, `pcall` returns false plus the error object. Note that\nerrors caught by `pcall` do not call a message handler. pi math.pi (number)\nThe value of 'π'. -popen io.popen(prog [, mode])\nStarts the program `prog` in a separated process and returns a file handle\nthat you can use to read data from this program (if `mode` is `"r"`,\nthe default) or to write data to this program (if `mode` is `"w"`).\n\nThis function is system dependent and is not available on all platforms. -pow math.pow(x, y)\nReturns *x^y*. (You can also use the expression `x^y` to compute this\nvalue.)\n\nDeprecated in Lua 5.3. -preload package.preload (table)\nA table to store loaders for specific modules (see `require`).\nThis variable is only a reference to the real table; assignments to this\nvariable do not change the table used by `require`. -print _G.print(···)\nReceives any number of arguments and prints their values to `stdout`,\nconverting each argument to a string following the same rules of `tostring`.\n\nThe function `print` is not intended for formatted output, but only as a\nquick way to show a value, for instance for debugging. For complete control\nover the output, use `string.format` and `io.write`. +popen io.popen(prog [, mode])\nStarts the program `prog` in a separated process and returns a file handle that you can use\nto read data from this program (if `mode` is `"r"`, the default) or to write data to this\nprogram (if `mode` is `"w"`).\n\nThis function is system dependent and is not available on all platforms. +pow math.pow(x, y)\nReturns *x^y*. (You can also use the expression `x^y` to compute this value.)\n\nDeprecated in Lua 5.3. +preload package.preload (table)\nA table to store loaders for specific modules (see `require`).\n\nThis variable is only a reference to the real table; assignments to this variable do not\nchange the table used by `require`. +print _G.print(···)\nReceives any number of arguments and prints their values to `stdout`, converting each argument\nto a string following the same rules of `tostring`.\n\nThe function `print` is not intended for formatted output, but only as a quick way to show a\nvalue, for instance for debugging. For complete control over the output, use `string.format`\nand `io.write`. rad math.rad(x)\nConverts the angle `x` from degrees to radians. -random math.random([m [, n]])\nWhen called without arguments, returns a pseudo-random float with uniform\ndistribution in the range [0,1). When called with two integers `m` and `n`,\n`math.random` returns a pseudo-random integer with uniform distribution in\nthe range `[m, n]. The call `math.random(n)`, for a positive `n`, is\nequivalent to `math.random(1,n)`. The call `math.random(0)` produces an\ninteger with all bits (pseudo)random.\n\nThis function uses the `xoshiro256**` algorithm to produce pseudo-random\n64-bit integers, which are the results of calls with argument 0. Other\nresults (ranges and floats) are unbiased extracted from these integers.\n\nLua initializes its pseudo-random generator with the equivalent of a call to\n`math.randomseed` with no arguments, so that `math.random` should generate\ndifferent sequences of results each time the program runs. -randomseed math.randomseed([x [, y]])\nWhen called with at least one argument, the integer parameters `x` and `y`\nare joined into a 128-bit *seed* that is used to reinitialize the\npseudo-random generator; equal seeds produce equal sequences of numbers. The\ndefault for `y` is zero.\n\nWhen called with no arguments, Lua generates a seed with a weak attempt for\nrandomness.\n\nThis function returns the two seed components that were effectively used, so\nthat setting them again repeats the sequence.\n\nTo ensure a required level of randomness to the initial state (or contrarily,\nto have a deterministic sequence, for instance when debugging a program), you\nshould call `math.randomseed` with explicit arguments. -rawequal _G.rawequal(v1, v2)\nChecks whether `v1` is equal to `v2`, without invoking the `__eq`\nmetamethod. Returns a boolean. -rawget _G.rawget(table, index)\nGets the real value of `table[index]`, without using the `__index`\nmetavalue. `table` must be a table; `index` may be any value. -rawlen _G.rawlen(v)\nReturns the length of the object `v`,\nwhich must be a table or a string,\nwithout invoking the `__len` metamethod.\nReturns an integer.\n\nNew in Lua 5.2. -rawset _G.rawset(table, index, value)\nSets the real value of `table[index]` to `value`, without using the\n`__newindex` metavalue. `table` must be a table, `index` any value different\nfrom nil and NaN, and `value` any Lua value.\n\nThis function returns `table`. -read file:read(···)\nReads the file `file`, according to the given formats, which specify\nwhat to read. For each format, the function returns a string or a number\nwith the characters read, or nil if it cannot read data with the specified\nformat. (In this latter case, the function does not read subsequent formats.)\nWhen called without arguments, it uses a default format that reads the next\nline (see below).\n\nThe available formats are\n "n": reads a numeral and returns it as a float or an integer, following the\n lexical conventions of Lua. (The numeral may have leading whitespaces\n and a sign.) This format always reads the longest input sequence that\n is a valid prefix for a number; if that prefix does not form a valid\n number (e.g., an empty string, "0x", or "3.4e-") or it is too long\n (more than 200 characters), it is discarded and the format returns\n nil.\n "a": reads the whole file, starting at the current position. On end of\n file, it returns the empty string; this format never fails.\n "l": reads the next line skipping the end of line, returning nil on\n end of file. This is the default format.\n "L": reads the next line keeping the end-of-line character (if present),\n returning nil on end of file.\n *number*: reads a string with up to this number of bytes, returning nil on\n end of file. If *number* is zero, it reads nothing and returns an\n empty string, or nil on end of file.\n\nThe formats "l" and "L" should be used only for text files. +random math.random([m [, n]])\nWhen called without arguments, returns a pseudo-random float with uniform distribution in the\nrange [0,1). When called with two integers `m` and `n`, `math.random` returns a pseudo-random\ninteger with uniform distribution in the range `[m, n]. The call `math.random(n)`, for a\npositive `n`, is equivalent to `math.random(1,n)`. The call `math.random(0)` produces an\ninteger with all bits (pseudo)random.\n\nThis function uses the `xoshiro256**` algorithm to produce pseudo-random 64-bit integers,\nwhich are the results of calls with argument 0. Other results (ranges and floats) are unbiased\nextracted from these integers.\n\nLua initializes its pseudo-random generator with the equivalent of a call to `math.randomseed`\nwith no arguments, so that `math.random` should generate different sequences of results each\ntime the program runs. +randomseed math.randomseed([x [, y]])\nWhen called with at least one argument, the integer parameters `x` and `y` are joined into a\n128-bit *seed* that is used to reinitialize the pseudo-random generator; equal seeds produce\nequal sequences of numbers. The default for `y` is zero.\n\nWhen called with no arguments, Lua generates a seed with a weak attempt for randomness.\n\nThis function returns the two seed components that were effectively used, so that setting\nthem again repeats the sequence.\n\nTo ensure a required level of randomness to the initial state (or contrarily, to have\na deterministic sequence, for instance when debugging a program), you should call\n`math.randomseed` with explicit arguments. +rawequal _G.rawequal(v1, v2)\nChecks whether `v1` is equal to `v2`, without invoking the `__eq` metamethod. Returns a boolean. +rawget _G.rawget(table, index)\nGets the real value of `table[index]`, without using the `__index` metavalue. `table` must\nbe a table; `index` may be any value. +rawlen _G.rawlen(v)\nReturns the length of the object `v`, which must be a table or a string, without invoking the\n`__len` metamethod. Returns an integer.\n\nNew in Lua 5.2. +rawset _G.rawset(table, index, value)\nSets the real value of `table[index]` to `value`, without using the `__newindex`\nmetavalue. `table` must be a table, `index` any value different from nil and NaN, and `value`\nany Lua value.\n\nThis function returns `table`. +read file:read(···)\nReads the file `file`, according to the given formats, which specify what to read. For each\nformat, the function returns a string or a number with the characters read, or nil if it\ncannot read data with the specified format. (In this latter case, the function does not read\nsubsequent formats.) When called without arguments, it uses a default format that reads\nthe next line (see below).\n\nThe available formats are\n\n * "n": reads a numeral and returns it as a float or an integer, following the lexical\n conventions of Lua. (The numeral may have leading whitespaces and a sign.) This format\n always reads the longest input sequence that is a valid prefix for a number; if that\n prefix does not form a valid number (e.g., an empty string, "0x", or "3.4e-") or it is\n too long (more than 200 characters), it is discarded and the format returns nil.\n * "a": reads the whole file, starting at the current position. On end of file, it returns\n the empty string; this format never fails.\n * "l": reads the next line skipping the end of line, returning nil on end of file. This\n is the default format.\n * "L": reads the next line keeping the end-of-line character (if present), returning nil\n on end of file.\n * *number*: reads a string with up to this number of bytes, returning nil on end of file. If\n *number* is zero, it reads nothing and returns an empty string, or nil on end of file.\n\nThe formats "l" and "L" should be used only for text files. read io.read(···)\nEquivalent to `io.input():read(···)`. -remove os.remove(filename)\nDeletes the file (or empty directory, on POSIX systems) with the given name.\nIf this function fails, it returns nil, plus a string describing the error\nand the error code. -remove table.remove(list [, pos])\nRemoves from `list` the element at position `pos`, returning the value of the\nremoved element. When `pos` is an integer between 1 and `#list`, it shifts\ndown the elements `list[pos+1], list[pos+2], ···, list[#list]` and erases\nelement `list[#list]`; The index `pos` can also be 0 when `#list` is 0, or\n`#list + 1`.\n\nThe default value for `pos` is `#list`, so that a call `table.remove(l)`\nremoves the last element of the list `l`. -rename os.rename(oldname, newname)\nRenames file or directory named `oldname` to `newname`. If this function\nfails, it returns nil, plus a string describing the error and the error code. -rep string.rep(s, n [, sep])\nReturns a string that is the concatenation of `n` copies of the string `s`\nseparated by the string `sep`. The default value for `sep` is the empty\nstring (that is, no separator). Returns the empty string if `n` is not\npositive.\n\n(Note that it is very easy to exhaust the memory of your machine with a\nsingle call to this function.) -replace bit32.replace(n, v, field [, width])\nReturns a copy of `n` with the bits `field` to `field + width - 1` replaced\nby the value `v`. See `bit32.extract` for details about `field` and `width`.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -require _G.require(modname)\nLoads the given module. The function starts by looking into the\n`package.loaded` table to determine whether `modname` is already loaded. If\nit is, then `require` returns the value stored at `package.loaded[modname]`.\n(The absence of a second result in this case signals that this call did not\nhave to load the module.) Otherwise, it tries to find a *loader* for the\nmodule.\n\nTo find a loader, `require` is guided by the table `package.searchers`. Each\nitem in this table is a search function, that searches for the module in a\nparticular way. By changing this table, we can change how `require` looks for\na module. The following explanation is based on the default configuration for\n`package.searchers`.\n\nFirst `require` queries `package.preload[modname]`. If it has a value,\nthis value (which must be a function) is the loader. Otherwise `require`\nsearches for a Lua loader using the path stored in `package.path`. If\nthat also fails, it searches for a C loader using the path stored in\n`package.cpath`. If that also fails, it tries an *all-in-one* loader (see\n`package.searchers`).\n\nOnce a loader is found, `require` calls the loader with two arguments:\n`modname` and an extra value, a *loader data*, also returned by the searcher.\nThe loader data can be any value useful to the module; for the default\nsearchers, it indicates where the loader was found. (For instance, if the\nloader came from a file, this extra value is the file path.) If the loader\nreturns any non-nil value, `require` assigns the returned value to\n`package.loaded[modname]`. If the loader does not return a non-nil value and\nhas not assigned any value to `package.loaded[modname]`, then `require`\nassigns true to this entry. In any case, `require` returns the final value of\n`package.loaded[modname]`. Besides that value, `require` also returns as a\nsecond result the loader data returned by the searcher, which indicates how\n`require` found the module.\n\nIf there is any error loading or running the module, or if it cannot find\nany loader for the module, then `require` raises an error. -resume coroutine.resume(co [, val1, ···])\nStarts or continues the execution of coroutine `co`. The first time\nyou resume a coroutine, it starts running its body. The values `val1`,\n··· are passed as the arguments to the body function. If the coroutine\nhas yielded, `resume` restarts it; the values `val1`, ··· are passed\nas the results from the yield.\n\nIf the coroutine runs without any errors, `resume` returns true plus any\nvalues passed to `yield` (when the coroutine yields) or any values returned\nby the body function (when the coroutine terminates). If there is any error,\n`resume` returns false plus the error message. +remove os.remove(filename)\nDeletes the file (or empty directory, on POSIX systems) with the given name. If this function\nfails, it returns nil, plus a string describing the error and the error code. +remove table.remove(list [, pos])\nRemoves from `list` the element at position `pos`, returning the value of the removed\nelement. When `pos` is an integer between 1 and `#list`, it shifts down the elements\n`list[pos+1], list[pos+2], ···, list[#list]` and erases element `list[#list]`; The index\n`pos` can also be 0 when `#list` is 0, or `#list + 1`.\n\nThe default value for `pos` is `#list`, so that a call `table.remove(l)` removes the last\nelement of the list `l`. +rename os.rename(oldname, newname)\nRenames file or directory named `oldname` to `newname`. If this function fails, it returns\nnil, plus a string describing the error and the error code. +rep string.rep(s, n [, sep])\nReturns a string that is the concatenation of `n` copies of the string `s` separated by the\nstring `sep`. The default value for `sep` is the empty string (that is, no separator). Returns\nthe empty string if `n` is not positive.\n\n(Note that it is very easy to exhaust the memory of your machine with a single call to\nthis function.) +replace bit32.replace(n, v, field [, width])\nReturns a copy of `n` with the bits `field` to `field + width - 1` replaced by the value\n`v`. See `bit32.extract` for details about `field` and `width`.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +require _G.require(modname)\nLoads the given module. The function starts by looking into the `package.loaded` table to\ndetermine whether `modname` is already loaded. If it is, then `require` returns the value\nstored at `package.loaded[modname]`. (The absence of a second result in this case signals\nthat this call did not have to load the module.) Otherwise, it tries to find a *loader*\nfor the module.\n\nTo find a loader, `require` is guided by the table `package.searchers`. Each item in this\ntable is a search function, that searches for the module in a particular way. By changing\nthis table, we can change how `require` looks for a module. The following explanation is\nbased on the default configuration for `package.searchers`.\n\nFirst `require` queries `package.preload[modname]`. If it has a value, this value (which must be\na function) is the loader. Otherwise `require` searches for a Lua loader using the path stored\nin `package.path`. If that also fails, it searches for a C loader using the path stored in\n`package.cpath`. If that also fails, it tries an *all-in-one* loader (see `package.searchers`).\n\nOnce a loader is found, `require` calls the loader with two arguments: `modname` and an\nextra value, a *loader data*, also returned by the searcher. The loader data can be any\nvalue useful to the module; for the default searchers, it indicates where the loader\nwas found. (For instance, if the loader came from a file, this extra value is the file\npath.) If the loader returns any non-nil value, `require` assigns the returned value to\n`package.loaded[modname]`. If the loader does not return a non-nil value and has not assigned\nany value to `package.loaded[modname]`, then `require` assigns true to this entry. In any\ncase, `require` returns the final value of `package.loaded[modname]`. Besides that value,\n`require` also returns as a second result the loader data returned by the searcher, which\nindicates how `require` found the module.\n\nIf there is any error loading or running the module, or if it cannot find any loader for\nthe module, then `require` raises an error. +resume coroutine.resume(co [, val1, ···])\nStarts or continues the execution of coroutine `co`. The first time you resume a coroutine,\nit starts running its body. The values `val1`, ··· are passed as the arguments to the body\nfunction. If the coroutine has yielded, `resume` restarts it; the values `val1`, ··· are\npassed as the results from the yield.\n\nIf the coroutine runs without any errors, `resume` returns true plus any values passed to\n`yield` (when the coroutine yields) or any values returned by the body function (when the\ncoroutine terminates). If there is any error, `resume` returns false plus the error message. reverse string.reverse(s)\nReturns a string that is the string `s` reversed. -rmdir lfs.rmdir(dirname)\nRemoves an existing directory. The argument is the name of the directory.\n\nReturns true in case of success or nil, an error message and a\nsystem-dependent error code in case of error. -rrotate bit32.rrotate(x, disp)\nReturns the number `x` rotated `disp` bits to the right. The number `disp`\nmay be any representable integer.\n\nFor any valid displacement, the following identity holds:\n\n assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32))\n\nIn particular, negative displacements rotate to the left.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -rshift bit32.rshift(x, disp)\nReturns the number `x` shifted `disp` bits to the right. The number `disp`\nmay be any representable integer. Negative displacements shift to the left.\nIn any direction, vacant bits are filled with zeros. In particular,\ndisplacements with absolute values higher than 31 result in zero (all bits\nare shifted out).\n\nFor positive displacements, the following equality holds:\n\n assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp))\n\nThis shift operation is what is called logical shift.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -running coroutine.running()\nReturns the running coroutine plus a boolean, true when the running coroutine\nis the main one. -searchers package.searchers (table)\nA table used by `require` to control how to find modules.\nEach entry in this table is a *searcher function*. When looking for a\nmodule, `require` calls each of these searchers in ascending order, with\nthe module name (the argument given to `require`) as its sole argument.\nIf the searcher finds the module, it returns another function, the module\n*loader*, plus an extra value, a *loader data*, that will be passed to that\nloader and returned as a second result by `require`. If it cannot find the\nmodule, it returns a string explaining why (or nil if it has nothing to\nsay).\nLua initializes this table with four functions.\nThe first searcher simply looks for a loader in the `package.preload`\ntable.\nThe second searcher looks for a loader as a Lua library, using the path\nstored at `package.path`. The search is done as described in function\n`package.searchpath`.\nThe third searcher looks for a loader as a C library, using the path given\nby the variable `package.cpath`. Again, the search is done as described in\nfunction `package.searchpath`. For instance, if the C path is the string\n "./?.so;./?.dll;/usr/local/?/init.so"\nthe searcher for module `foo` will try to open the files `./foo.so`,\n`./foo.dll`, and `/usr/local/foo/init.so`, in that order. Once it finds\na C library, this searcher first uses a dynamic link facility to link the\napplication with the library. Then it tries to find a C function inside the\nlibrary to be used as the loader. The name of this C function is the string\n"`luaopen_`" concatenated with a copy of the module name where each dot\nis replaced by an underscore. Moreover, if the module name has a hyphen,\nits suffix after (and including) the first hyphen is removed. For instance,\nif the module name is `a.b.c-v2.1 `, the function name will be\n`luaopen_a_b_c`. The fourth searcher tries an *all-in-one loader*. It\nsearches the C path for a library for the root name of the given module.\nFor instance, when requiring `a.b.c`, it will search for a C library for\n`a`. If found, it looks into it for an open function for the submodule; in\nour example, that would be `luaopen_a_b_c`. With this facility, a package\ncan pack several C submodules into one single library, with each submodule\nkeeping its original open function.\nAll searchers except the first one (preload) return as the extra value the\nfile path where the module was found, as returned by `package.searchpath`.\nThe first searcher always returns the string "`:preload:`".\nSearchers should raise no errors and have no side effects in Lua. (They may\nhave side effects in C, for instance by linking the application with a\nlibrary.)\n\nNew in Lua 5.2. -searchpath package.searchpath(name, path [, sep [, rep]])\nSearches for the given `name` in the given `path`.\n\nA path is a string containing a sequence of _templates_ separated by\nsemicolons. For each template, the function replaces each interrogation mark\n(if any) in the template with a copy of `name` wherein all occurrences of\n`sep` (a dot, by default) were replaced by `rep` (the system's directory\nseparator, by default), and then tries to open the resulting file name.\nFor instance, if the path is the string\n "./?.lua;./?.lc;/usr/local/?/init.lua"\nthe search for the name `foo.a` will try to open the files `./foo/a.lua`,\n`./foo/a.lc`, and `/usr/local/foo/a/init.lua`, in that order.\nReturns the resulting name of the first file that it can open in read mode\n(after closing the file), or nil plus an error message if none succeeds.\n(This error message lists all file names it tried to open.)\n\nNew in Lua 5.2. -seeall package.seeall(module)\nSets a metatable for `module` with its `__index` field referring to the\nglobal environment, so that this module inherits values from the global\nenvironment. To be used as an option to function `module`.\n\nDeprecated in Lua 5.2. -seek file:seek([whence [, offset]])\nSets and gets the file position, measured from the beginning of the\nfile, to the position given by `offset` plus a base specified by the string\n`whence`, as follows:\n "set": base is position 0 (beginning of the file);\n "cur": base is current position;\n "end": base is end of file;\n\nIn case of success, function `seek` returns the final file position,\nmeasured in bytes from the beginning of the file. If `seek` fails, it returns\nnil, plus a string describing the error.\n\nThe default value for `whence` is `"cur"`, and for `offset` is 0. Therefore,\nthe call `file:seek()` returns the current file position, without changing\nit; the call `file:seek("set")` sets the position to the beginning of the\nfile (and returns 0); and the call `file:seek("end")` sets the position\nto the end of the file, and returns its size. -select _G.select(index, ···)\nIf `index` is a number, returns all arguments after argument number\n`index`; a negative number indexes from the end (-1 is the last argument).\nOtherwise, `index` must be the string `"#"`, and `select` returns the total\nnumber of extra arguments it received. -setfenv _G.setfenv(f, table)\nSets the environment to be used by the given function. `f` can be a Lua\nfunction or a number that specifies the function at that stack level: Level 1\nis the function calling `setfenv`. `setfenv` returns the given function. As a\nspecial case, when `f` is 0 `setfenv` changes the environment of the running\nthread. In this case, `setfenv` returns no values.\n\nDeprecated in Lua 5.2. -setfenv debug.setfenv(object, table)\nSets the environment of the given `object` to the given `table`. Returns\n`object`.\n\nDeprecated in Lua 5.2. -sethook debug.sethook([thread, ] hook, mask [, count])\nSets the given function as the debug hook. The string `mask` and the number\n`count` describe when the hook will be called. The string mask may have any\ncombination of the following characters, with the given meaning:\n "c": the hook is called every time Lua calls a function;\n "r": the hook is called every time Lua returns from a function;\n "l": the hook is called every time Lua enters a new line of code.\n\nMoreover, with a `count` different from zero, the hook is called also after\nevery `count` instructions.\n\nWhen called without arguments, `debug.sethook` turns off the hook.\n\nWhen the hook is called, its first parameter is a string describing\nthe event that has triggered its call: `"call"`, `"tail call"`, `"return"`,\n`"line"`, and `"count"`. For line events, the hook also gets the new line\nnumber as its second parameter. Inside a hook, you can call `getinfo` with\nlevel 2 to get more information about the running function. (Level 0 is the\n`getinfo` function, and level 1 is the hook function.) -setlocal debug.setlocal([thread, ] level, local, value)\nThis function assigns the value `value` to the local variable with\nindex `local` of the function at level `level` of the stack. The function\nreturns nil if there is no local variable with the given index, and raises\nan error when called with a `level` out of range. (You can call `getinfo`\nto check whether the level is valid.) Otherwise, it returns the name of\nthe local variable.\n\nSee `debug.getlocal` for more information about variable indices and names. -setlocale os.setlocale(locale [, category])\nSets the current locale of the program. `locale` is a system-dependent string\nspecifying a locale; `category` is an optional string describing which\ncategory to change: `"all"`, `"collate"`, `"ctype"`, `"monetary"`,\n`"numeric"`, or `"time"`; the default category is `"all"`. The function\nreturns the name of the new locale, or nil if the request cannot be honored.\n\nIf `locale` is the empty string, the current locale is set to an\nimplementation-defined native locale. If `locale` is the string "`C`",\nthe current locale is set to the standard C locale.\n\nWhen called with nil as the first argument, this function only returns\nthe name of the current locale for the given category.\n\nThis function may not be thread safe because of its reliance on C function\n`setlocale`. -setmaxstack lpeg.setmaxstack(max)\nSets the maximum size for the backtrack stack used by LPeg to track calls and\nchoices. Most well-written patterns need little backtrack levels and\ntherefore you seldom need to change this maximum; but a few useful patterns\nmay need more space. Before changing this maximum you should try to rewrite\nyour pattern to avoid the need for extra space. -setmetatable _G.setmetatable(table, metatable)\nSets the metatable for the given table. If `metatable` is nil, removes the\nmetatable of the given table. If the original metatable has a `__metatable`\nfield, raises an error.\n\nThis function returns `table`.\n\nTo change the metatable of other types from Lua code, you must use the debug\nlibrary (see §6.10). -setmetatable debug.setmetatable(value, table)\nSets the metatable for the given `value` to the given `table` (which\ncan be nil). -setmode lfs.setmode(file, mode)\nSets the writing mode for a file. The mode string can be either "binary" or\n"text". Returns true followed by the previous mode string for the file, or\nnil followed by an error string in case of errors.. On non-Windows platforms,\nwhere the two modes are identical, setting the mode has no effect, and the\nmode is always returned as binary. -setupvalue debug.setupvalue(f, up, value)\nThis function assigns the value `value` to the upvalue with index `up`\nof the function `f`. The function returns nil if there is no upvalue with the\ngiven index. Otherwise, it returns the name of the upvalue.\n\nSee `debug.getupvalue` for more information about upvalues. -setuservalue debug.setuservalue(udata, value, n)\nSets the given `value` as the `n`-th user value associated to the given\n`udata`. `udata` must be a full userdata.\n\nReturns `udata`, or nil if the userdata does not have that value.\n\nNew in Lua 5.2. -setvbuf file:setvbuf(mode [, size])\nSets the buffering mode for a file. There are three available modes:\n "no": no buffering\n "full": full buffering\n "line": line buffering\n\nFor the last two cases, `size` is a hint for the size of the buffer, in\nbytes. The default is an appropriate size.\n\nThe specific behavior of each mode is non portable; check the underlying\nISO C function `setvbuf` in your platform for more details. +rmdir lfs.rmdir(dirname)\nRemoves an existing directory. The argument is the name of the directory.\n\nReturns true in case of success or nil, an error message and a system-dependent error code\nin case of error. +rrotate bit32.rrotate(x, disp)\nReturns the number `x` rotated `disp` bits to the right. The number `disp` may be any\nrepresentable integer.\n\nFor any valid displacement, the following identity holds:\n\n assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32))\n\nIn particular, negative displacements rotate to the left.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +rshift bit32.rshift(x, disp)\nReturns the number `x` shifted `disp` bits to the right. The number `disp` may be any\nrepresentable integer. Negative displacements shift to the left. In any direction, vacant\nbits are filled with zeros. In particular, displacements with absolute values higher than\n31 result in zero (all bits are shifted out).\n\nFor positive displacements, the following equality holds:\n\n assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp))\n\nThis shift operation is what is called logical shift.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +running coroutine.running()\nReturns the running coroutine plus a boolean, true when the running coroutine is the main one. +searchers package.searchers (table)\nA table used by `require` to control how to find modules.\n\nEach entry in this table is a *searcher function*. When looking for a module, `require`\ncalls each of these searchers in ascending order, with the module name (the argument given\nto `require`) as its sole argument. If the searcher finds the module, it returns another\nfunction, the module *loader*, plus an extra value, a *loader data*, that will be passed\nto that loader and returned as a second result by `require`. If it cannot find the module,\nit returns a string explaining why (or nil if it has nothing to say).\n\nLua initializes this table with four functions.\n\nThe first searcher simply looks for a loader in the `package.preload` table.\n\nThe second searcher looks for a loader as a Lua library, using the path stored at\n`package.path`. The search is done as described in function `package.searchpath`.\n\nThe third searcher looks for a loader as a C library, using the path given by the variable\n`package.cpath`. Again, the search is done as described in function `package.searchpath`. For\ninstance, if the C path is the string\n\n "./?.so;./?.dll;/usr/local/?/init.so"\n\nthe searcher for module `foo` will try to open the files `./foo.so`, `./foo.dll`, and\n`/usr/local/foo/init.so`, in that order. Once it finds a C library, this searcher first\nuses a dynamic link facility to link the application with the library. Then it tries to\nfind a C function inside the library to be used as the loader. The name of this C function\nis the string "`luaopen_`" concatenated with a copy of the module name where each dot\nis replaced by an underscore. Moreover, if the module name has a hyphen, its suffix after\n(and including) the first hyphen is removed. For instance, if the module name is `a.b.c-v2.1\n`, the function name will be `luaopen_a_b_c`.\n\nThe fourth searcher tries an *all-in-one loader*. It searches the C path for a library for\nthe root name of the given module. For instance, when requiring `a.b.c`, it will search for\na C library for `a`. If found, it looks into it for an open function for the submodule; in\nour example, that would be `luaopen_a_b_c`. With this facility, a package can pack several\nC submodules into one single library, with each submodule keeping its original open function.\n\nAll searchers except the first one (preload) return as the extra value the file path\nwhere the module was found, as returned by `package.searchpath`. The first searcher always\nreturns the string "`:preload:`".\n\nSearchers should raise no errors and have no side effects in Lua. (They may have side\neffects in C, for instance by linking the application with a library.)\n\nNew in Lua 5.2. +searchpath package.searchpath(name, path [, sep [, rep]])\nSearches for the given `name` in the given `path`.\n\nA path is a string containing a sequence of _templates_ separated by semicolons. For each\ntemplate, the function replaces each interrogation mark (if any) in the template with a copy\nof `name` wherein all occurrences of `sep` (a dot, by default) were replaced by `rep` (the\nsystem's directory separator, by default), and then tries to open the resulting file name.\nFor instance, if the path is the string\n\n "./?.lua;./?.lc;/usr/local/?/init.lua"\n\nthe search for the name `foo.a` will try to open the files `./foo/a.lua`, `./foo/a.lc`, and\n`/usr/local/foo/a/init.lua`, in that order.\n\nReturns the resulting name of the first file that it can open in read mode (after closing\nthe file), or nil plus an error message if none succeeds. (This error message lists all file\nnames it tried to open.)\n\nNew in Lua 5.2. +seeall package.seeall(module)\nSets a metatable for `module` with its `__index` field referring to the global environment,\nso that this module inherits values from the global environment. To be used as an option to\nfunction `module`.\n\nDeprecated in Lua 5.2. +seek file:seek([whence [, offset]])\nSets and gets the file position, measured from the beginning of the file, to the position\ngiven by `offset` plus a base specified by the string `whence`, as follows:\n\n * "set": base is position 0 (beginning of the file);\n * "cur": base is current position;\n * "end": base is end of file;\n\nIn case of success, function `seek` returns the final file position, measured in bytes from\nthe beginning of the file. If `seek` fails, it returns nil, plus a string describing the error.\n\nThe default value for `whence` is `"cur"`, and for `offset` is 0. Therefore, the\ncall `file:seek()` returns the current file position, without changing it; the call\n`file:seek("set")` sets the position to the beginning of the file (and returns 0); and the\ncall `file:seek("end")` sets the position to the end of the file, and returns its size. +select _G.select(index, ···)\nIf `index` is a number, returns all arguments after argument number `index`; a negative number\nindexes from the end (-1 is the last argument). Otherwise, `index` must be the string `"#"`,\nand `select` returns the total number of extra arguments it received. +setfenv _G.setfenv(f, table)\nSets the environment to be used by the given function. `f` can be a Lua function or a\nnumber that specifies the function at that stack level: Level 1 is the function calling\n`setfenv`. `setfenv` returns the given function. As a special case, when `f` is 0 `setfenv`\nchanges the environment of the running thread. In this case, `setfenv` returns no values.\n\nDeprecated in Lua 5.2. +setfenv debug.setfenv(object, table)\nSets the environment of the given `object` to the given `table`. Returns `object`.\n\nDeprecated in Lua 5.2. +sethook debug.sethook([thread, ] hook, mask [, count])\nSets the given function as the debug hook. The string `mask` and the number `count` describe\nwhen the hook will be called. The string mask may have any combination of the following\ncharacters, with the given meaning:\n\n * "c": the hook is called every time Lua calls a function;\n * "r": the hook is called every time Lua returns from a function;\n * "l": the hook is called every time Lua enters a new line of code.\n\nMoreover, with a `count` different from zero, the hook is called also after every `count`\ninstructions.\n\nWhen called without arguments, `debug.sethook` turns off the hook.\n\nWhen the hook is called, its first parameter is a string describing the event that has\ntriggered its call: `"call"`, `"tail call"`, `"return"`, `"line"`, and `"count"`. For line\nevents, the hook also gets the new line number as its second parameter. Inside a hook, you\ncan call `getinfo` with level 2 to get more information about the running function. (Level\n0 is the `getinfo` function, and level 1 is the hook function.) +setlocal debug.setlocal([thread, ] level, local, value)\nThis function assigns the value `value` to the local variable with index `local` of the\nfunction at level `level` of the stack. The function returns nil if there is no local variable\nwith the given index, and raises an error when called with a `level` out of range. (You can\ncall `getinfo` to check whether the level is valid.) Otherwise, it returns the name of the\nlocal variable.\n\nSee `debug.getlocal` for more information about variable indices and names. +setlocale os.setlocale(locale [, category])\nSets the current locale of the program. `locale` is a system-dependent string specifying\na locale; `category` is an optional string describing which category to change: `"all"`,\n`"collate"`, `"ctype"`, `"monetary"`, `"numeric"`, or `"time"`; the default category is\n`"all"`. The function returns the name of the new locale, or nil if the request cannot\nbe honored.\n\nIf `locale` is the empty string, the current locale is set to an implementation-defined native\nlocale. If `locale` is the string "`C`", the current locale is set to the standard C locale.\n\nWhen called with nil as the first argument, this function only returns the name of the\ncurrent locale for the given category.\n\nThis function may not be thread safe because of its reliance on C function `setlocale`. +setmaxstack lpeg.setmaxstack(max)\nSets the maximum size for the backtrack stack used by LPeg to track calls and choices. Most\nwell-written patterns need little backtrack levels and therefore you seldom need to change\nthis maximum; but a few useful patterns may need more space. Before changing this maximum\nyou should try to rewrite your pattern to avoid the need for extra space. +setmetatable _G.setmetatable(table, metatable)\nSets the metatable for the given table. If `metatable` is nil, removes the metatable of the\ngiven table. If the original metatable has a `__metatable` field, raises an error.\n\nThis function returns `table`.\n\nTo change the metatable of other types from Lua code, you must use the debug library\n(see §6.10). +setmetatable debug.setmetatable(value, table)\nSets the metatable for the given `value` to the given `table` (which can be nil). +setmode lfs.setmode(file, mode)\nSets the writing mode for a file. The mode string can be either "binary" or "text". Returns\ntrue followed by the previous mode string for the file, or nil followed by an error string\nin case of errors. On non-Windows platforms, where the two modes are identical, setting\nthe mode has no effect, and the mode is always returned as binary. +setupvalue debug.setupvalue(f, up, value)\nThis function assigns the value `value` to the upvalue with index `up` of the function\n`f`. The function returns nil if there is no upvalue with the given index. Otherwise, it\nreturns the name of the upvalue.\n\nSee `debug.getupvalue` for more information about upvalues. +setuservalue debug.setuservalue(udata, value, n)\nSets the given `value` as the `n`-th user value associated to the given `udata`. `udata`\nmust be a full userdata.\n\nReturns `udata`, or nil if the userdata does not have that value.\n\nNew in Lua 5.2. +setvbuf file:setvbuf(mode [, size])\nSets the buffering mode for a file. There are three available modes:\n\n * "no": no buffering\n * "full": full buffering\n * "line": line buffering\n\nFor the last two cases, `size` is a hint for the size of the buffer, in bytes. The default\nis an appropriate size.\n\nThe specific behavior of each mode is non portable; check the underlying ISO C function\n`setvbuf` in your platform for more details. sin math.sin(x)\nReturns the sine of `x` (assumed to be in radians). sinh math.sinh(x)\nReturns the hyperbolic sine of `x`.\n\nDeprecated in Lua 5.3. -sort table.sort(list [, comp])\nSorts the list elements in a given order, *in-place*, from `list[1]` to\n`list[#list]`. If `comp` is given, then it must be a function that receives\ntwo list elements and returns true when the first element must come before\nthe second in the final order (so that, after the sort, `i < j` implies\n`not comp(list[j],list[i])` will be true after the sort). If `comp` is not\ngiven, then the standard Lua operator `<` is used instead.\n\nNote that the `comp` function must not define a string partial order over the\nelements in the list; that is, it must be asymmetric and transitive.\nOtherwise, no valid sort may be possible.\n\nThe sort algorithm is not stable; that is, elements not comparable by the\ngiven order (e.g., equal elements) may have their relative positions changed\nby the sort. -sqrt math.sqrt(x)\nReturns the square root of `x`. (You can also use the expression `x^0.5`\nto compute this value.) -status coroutine.status(co)\nReturns the status of the coroutine `co`, as a string: `"running"`, if\nthe coroutine is running (that is, it is the one that called `status`);\n`"suspended"`, if the coroutine is suspended in a call to `yield`, or if it\nhas not started running yet; `"normal"` if the coroutine is active but not\nrunning (that is, it has resumed another coroutine); and `"dead"` if the\ncoroutine has finished its body function, or if it has stopped with an error. +sort table.sort(list [, comp])\nSorts the list elements in a given order, *in-place*, from `list[1]` to `list[#list]`. If\n`comp` is given, then it must be a function that receives two list elements and returns true\nwhen the first element must come before the second in the final order (so that, after the\nsort, `i < j` implies `not comp(list[j],list[i])` will be true after the sort). If `comp`\nis not given, then the standard Lua operator `<` is used instead.\n\nNote that the `comp` function must not define a string partial order over the elements in the\nlist; that is, it must be asymmetric and transitive. Otherwise, no valid sort may be possible.\n\nThe sort algorithm is not stable; that is, elements not comparable by the given order (e.g.,\nequal elements) may have their relative positions changed by the sort. +sqrt math.sqrt(x)\nReturns the square root of `x`. (You can also use the expression `x^0.5` to compute this value.) +status coroutine.status(co)\nReturns the status of the coroutine `co`, as a string: `"running"`, if the coroutine is\nrunning (that is, it is the one that called `status`); `"suspended"`, if the coroutine\nis suspended in a call to `yield`, or if it has not started running yet; `"normal"` if the\ncoroutine is active but not running (that is, it has resumed another coroutine); and `"dead"`\nif the coroutine has finished its body function, or if it has stopped with an error. stderr io.stderr (file)\nStandard error. stdin io.stdin (file)\nStandard in. stdout io.stdout (file)\nStandard out. string _G.string (module)\nLua string module. -sub string.sub(s, i [, j])\nReturns the substring of `s` that starts at `i` and continues until\n`j`; `i` and `j` can be negative. If `j` is absent, then it is assumed to\nbe equal to -1 (which is the same as the string length). In particular,\nthe call `string.sub(s,1,j)` returns a prefix of `s` with length `j`, and\n`string.sub(s, -i)` returns a suffix of `s` with length `i`.\n\nIf, after the translation of negative indices, `i` is less than 1, it is\ncorrected to 1. If `j` is greater than the string length, it is corrected to\nthat length. If, after these corrections, `i` is greater than `j`, the\nfunction returns the empty string. -symlinkattributes lfs.symlinkattributes(filepath [, aname])\nIdentical to lfs.attributes except that it obtains information about the link\nitself (not the file it refers to). It also adds a target field, containing\nthe file name that the symlink points to. On Windows this function does not\nyet support links, and is identical to lfs.attributes. +sub string.sub(s, i [, j])\nReturns the substring of `s` that starts at `i` and continues until `j`; `i` and `j` can\nbe negative. If `j` is absent, then it is assumed to be equal to -1 (which is the same as\nthe string length). In particular, the call `string.sub(s,1,j)` returns a prefix of `s`\nwith length `j`, and `string.sub(s, -i)` returns a suffix of `s` with length `i`.\n\nIf, after the translation of negative indices, `i` is less than 1, it is corrected to 1. If `j`\nis greater than the string length, it is corrected to that length. If, after these corrections,\n`i` is greater than `j`, the function returns the empty string. +symlinkattributes lfs.symlinkattributes(filepath [, aname])\nIdentical to lfs.attributes except that it obtains information about the link itself (not\nthe file it refers to). It also adds a target field, containing the file name that the\nsymlink points to. On Windows this function does not yet support links, and is identical\nto lfs.attributes. table _G.table (module)\nLua table module. tan math.tan(x)\nReturns the tangent of `x` (assumed to be in radians). tanh math.tanh(x)\nReturns the hyperbolic tangent of `x`.\n\nDeprecated in Lua 5.3. -time os.time([table])\nReturns the current time when called without arguments, or a time\nrepresenting the date and time specified by the given table. This table\nmust have fields `year`, `month`, and `day`, and may have fields `hour`\n(default is 12), `min` (default is 0), `sec` (default is 0), and `isdst`\n(default is nil). For a description of these fields, see the `os.date`\nfunction.\n\nWhen the function is called, the values in these fields do not need to be\ninside their valid ranges. For instance, if `sec` is -10, it means 10 seconds\nbefore the time specified by the other fields; if `hour` is 1000, it means\n1000 hours after the time specified by the other fields.\n\nThe returned value is a number, whose meaning depends on your system. In\nPOSIX, Windows, and some other systems, this number counts the number of\nseconds since some given start time (the "epoch"). In other systems, the\nmeaning is not specified, and the number returned by `time` can be used only\nas an argument to `os.date` and `os.difftime`.\n\nWhen called with a table, `os.time` also normalizes all the fields documented\nin the `os.date` function, so that they represent the same time as before the\ncall but with values inside their valid ranges. -tmpfile io.tmpfile()\nIn case of success, returns a handle for a temporary file. This file is\nopened in update mode and it is automatically removed when the program ends. -tmpname os.tmpname()\nReturns a string with a file name that can be used for a temporary\nfile. The file must be explicitly opened before its use and explicitly\nremoved when no longer needed.\n\nOn POSIX systems, this function also creates a file with that name, to avoid\nsecurity risks. (Someone else might create the file with wrong permissions in\nthe time between getting the name and creating the file.) You still have to\nopen the file to use it and to remove it (even if you do not use it).\n\nWhen possible, you may prefer to use `io.tmpfile`, which automatically\nremoves the file when the program ends. -tointeger math.tointeger(x)\nIf the value `x` is convertible to an integer, returns that integer.\nOtherwise, returns nil.\n\nNew in Lua 5.3. -tonumber _G.tonumber(e [, base])\nWhen called with no `base`, `tonumber` tries to convert its argument to a\nnumber. If the argument is already a number or a string convertible to a\nnumber, then `tonumber` returns this number; otherwise, it\nreturns nil.\n\nThe conversion of strings can result in integers or floats, according to the\nlexical conventions of Lua (see §3.1). The string may have leading and\ntrailing spaces and a sign.\n\nWhen called with `base`, then `e` must be a string to be interpreted as an\ninteger numeral in that base. The base may be any integer between 2 and 36,\ninclusive. In bases above 10, the letter '`A`' (in either upper or lower\ncase) represents 10, '`B`' represents 11, and so forth, with '`Z`'\nrepresenting 35. If the string `e` is not a valid numeral in the given base,\nthe function returns nil -tostring _G.tostring(v)\nReceives a value of any type and converts it to a string in a human-readable\nformat. Floats always produce strings with some floating-point indication\n(either a decimal dot or an exponent).\n\nIf the metatable of `v` has a `__tostring` field, then `tostring` calls the\ncorresponding value with `v` as argument, and uses the result of the call as\nits result. Otherwise, if the metatable of `v` has a `__name` field with a\nstring value, `tostring` may use that string in its final result.\n\nFor complete control of how numbers are converted, use `string.format`. -touch lfs.touch(filepath [, atime [, mtime]])\nSet access and modification times of a file. This function is a bind to utime\nfunction. The first argument is the filename, the second argument (atime) is\nthe access time, and the third argument (mtime) is the modification time.\nBoth times are provided in seconds (which should be generated with Lua\nstandard function os.time). If the modification time is omitted, the access\ntime provided is used; if both times are omitted, the current time is used.\n\nReturns true in case of success or nil, an error message and a\nsystem-dependent error code in case of error. -traceback debug.traceback([thread, ] [message] [, level])\nIf `message` is present but is neither a string nor nil, this function\nreturns `message` without further processing. Otherwise, it returns a string\nwith a traceback of the call stack. The optional `message` string is appended\nat the beginning of the traceback. An optional `level` number tells at which\nlevel to start the traceback (default is 1, the function calling\n`traceback`). -type _G.type(v)\nReturns the type of its only argument, coded as a string. The possible\nresults of this function are "\n`nil`" (a string, not the value nil), "`number`", "`string`", "`boolean`",\n"`table`", "`function`", "`thread`", and "`userdata`". -type io.type(obj)\nChecks whether `obj` is a valid file handle. Returns the string `"file"`\nif `obj` is an open file handle, `"closed file"` if `obj` is a closed file\nhandle, or nil if `obj` is not a file handle. -type lpeg.type(value)\nIf the given value is a pattern, returns the string "pattern". Otherwise\nreturns nil. -type math.type(x)\nReturns "integer" if `x` is an integer, "float" if it is a float, or nil if\nx is not a number.\n\nNew in Lua 5.3. -ult math.ult(m, n)\nReturns a boolean, true if integer `m` is below integer `n` when they are\ncompared as unsigned integers.\n\nNew in Lua 5.3. -unlock lfs.unlock(filehandle[, start[, length]])\nUnlocks a file or a part of it. This function works on open files; the file\nhandle should be specified as the first argument. The optional arguments\nstart and length can be used to specify a starting point and its length; both\nshould be numbers.\n\nReturns true if the operation was successful; in case of error, it returns\nnil plus an error string. -unpack _G.unpack(list [, i [, j]])\nReturns the elements from the given table. This function is equivalent to\nreturn list[i], list[i+1], ···, list[j] except that the above code can\nbe written only for a fixed number of elements. By default, `i` is 1 and\n`j` is the length of the list, as defined by the length operator\n(see §2.5.5).\n\nDeprecated in Lua 5.2. -unpack string.unpack(fmt, s [, pos])\nReturns the values packed in string `s` (see `string.pack`) according to the\nformat string `fmt` (see §6.4.2). An optional `pos` marks where to start\nreading in `s` (default is 1). After the read values, this function also\nreturns the index of the first unread byte in `s`.\n\nNew in Lua 5.3. +time os.time([table])\nReturns the current time when called without arguments, or a time representing the date and\ntime specified by the given table. This table must have fields `year`, `month`, and `day`,\nand may have fields `hour` (default is 12), `min` (default is 0), `sec` (default is 0), and\n`isdst` (default is nil). For a description of these fields, see the `os.date` function.\n\nWhen the function is called, the values in these fields do not need to be inside their\nvalid ranges. For instance, if `sec` is -10, it means 10 seconds before the time specified\nby the other fields; if `hour` is 1000, it means 1000 hours after the time specified by the\nother fields.\n\nThe returned value is a number, whose meaning depends on your system. In POSIX, Windows,\nand some other systems, this number counts the number of seconds since some given start time\n(the "epoch"). In other systems, the meaning is not specified, and the number returned by\n`time` can be used only as an argument to `os.date` and `os.difftime`.\n\nWhen called with a table, `os.time` also normalizes all the fields documented in the `os.date`\nfunction, so that they represent the same time as before the call but with values inside\ntheir valid ranges. +tmpfile io.tmpfile()\nIn case of success, returns a handle for a temporary file. This file is opened in update\nmode and it is automatically removed when the program ends. +tmpname os.tmpname()\nReturns a string with a file name that can be used for a temporary file. The file must be\nexplicitly opened before its use and explicitly removed when no longer needed.\n\nOn POSIX systems, this function also creates a file with that name, to avoid security\nrisks. (Someone else might create the file with wrong permissions in the time between getting\nthe name and creating the file.) You still have to open the file to use it and to remove it\n(even if you do not use it).\n\nWhen possible, you may prefer to use `io.tmpfile`, which automatically removes the file when\nthe program ends. +tointeger math.tointeger(x)\nIf the value `x` is convertible to an integer, returns that integer. Otherwise, returns nil.\n\nNew in Lua 5.3. +tonumber _G.tonumber(e [, base])\nWhen called with no `base`, `tonumber` tries to convert its argument to a number. If the\nargument is already a number or a string convertible to a number, then `tonumber` returns\nthis number; otherwise, it returns nil.\n\nThe conversion of strings can result in integers or floats, according to the lexical\nconventions of Lua (see §3.1). The string may have leading and trailing spaces and a sign.\n\nWhen called with `base`, then `e` must be a string to be interpreted as an integer numeral\nin that base. The base may be any integer between 2 and 36, inclusive. In bases above 10,\nthe letter '`A`' (in either upper or lower case) represents 10, '`B`' represents 11, and so\nforth, with '`Z`' representing 35. If the string `e` is not a valid numeral in the given base,\nthe function returns nil +tostring _G.tostring(v)\nReceives a value of any type and converts it to a string in a human-readable format. Floats\nalways produce strings with some floating-point indication (either a decimal dot or an\nexponent).\n\nIf the metatable of `v` has a `__tostring` field, then `tostring` calls the corresponding\nvalue with `v` as argument, and uses the result of the call as its result. Otherwise, if the\nmetatable of `v` has a `__name` field with a string value, `tostring` may use that string\nin its final result.\n\nFor complete control of how numbers are converted, use `string.format`. +touch lfs.touch(filepath [, atime [, mtime]])\nSet access and modification times of a file. This function is a bind to utime function. The\nfirst argument is the filename, the second argument (atime) is the access time, and the\nthird argument (mtime) is the modification time. Both times are provided in seconds (which\nshould be generated with Lua standard function os.time). If the modification time is omitted,\nthe access time provided is used; if both times are omitted, the current time is used.\n\nReturns true in case of success or nil, an error message and a system-dependent error code\nin case of error. +traceback debug.traceback([thread, ] [message] [, level])\nIf `message` is present but is neither a string nor nil, this function returns `message`\nwithout further processing. Otherwise, it returns a string with a traceback of the call\nstack. The optional `message` string is appended at the beginning of the traceback. An optional\n`level` number tells at which level to start the traceback (default is 1, the function calling\n`traceback`). +type _G.type(v)\nReturns the type of its only argument, coded as a string. The possible results of this\nfunction are " `nil`" (a string, not the value nil), "`number`", "`string`", "`boolean`",\n"`table`", "`function`", "`thread`", and "`userdata`". +type io.type(obj)\nChecks whether `obj` is a valid file handle. Returns the string `"file"` if `obj` is an\nopen file handle, `"closed file"` if `obj` is a closed file handle, or nil if `obj` is not\na file handle. +type lpeg.type(value)\nIf the given value is a pattern, returns the string "pattern". Otherwise returns nil. +type math.type(x)\nReturns "integer" if `x` is an integer, "float" if it is a float, or nil if x is not a number.\n\nNew in Lua 5.3. +ult math.ult(m, n)\nReturns a boolean, true if integer `m` is below integer `n` when they are compared as\nunsigned integers.\n\nNew in Lua 5.3. +unlock lfs.unlock(filehandle[, start[, length]])\nUnlocks a file or a part of it. This function works on open files; the file handle should\nbe specified as the first argument. The optional arguments start and length can be used to\nspecify a starting point and its length; both should be numbers.\n\nReturns true if the operation was successful; in case of error, it returns nil plus an\nerror string. +unpack _G.unpack(list [, i [, j]])\nReturns the elements from the given table. This function is equivalent to return list[i],\nlist[i+1], ···, list[j] except that the above code can be written only for a fixed number\nof elements. By default, `i` is 1 and `j` is the length of the list, as defined by the length\noperator (see §2.5.5).\n\nDeprecated in Lua 5.2. +unpack string.unpack(fmt, s [, pos])\nReturns the values packed in string `s` (see `string.pack`) according to the format string\n`fmt` (see §6.4.2). An optional `pos` marks where to start reading in `s` (default is\n1). After the read values, this function also returns the index of the first unread byte in `s`.\n\nNew in Lua 5.3. unpack table.unpack(list [, i [, j]])\nReturns the elements from the given list. This function is equivalent to\n\n return list[i], list[i+1], ···, list[j]\n\nBy default, `i` is 1 and `j` is `#list`.\n\nNew in Lua 5.2. -upper string.upper(s)\nReceives a string and returns a copy of this string with all lowercase\nletters changed to uppercase. All other characters are left unchanged. The\ndefinition of what a lowercase letter is depends on the current locale. -upvalueid debug.upvalueid(f, n)\nReturns a unique identifier (as a light userdata) for the upvalue numbered\n`n` from the given function.\n\nThese unique identifiers allow a program to check whether different closures\nshare upvalues. Lua closures that share an upvalue (that is, that access a\nsame external local variable) will return identical ids for those upvalue\nindices.\n\nNew in Lua 5.2. -upvaluejoin debug.upvaluejoin(f1, n1, f2, n2)\nMake the `n1`-th upvalue of the Lua closure `f1` refer to the `n2`-th upvalue\nof the Lua closure `f2`.\n\nNew in Lua 5.2. +upper string.upper(s)\nReceives a string and returns a copy of this string with all lowercase letters changed to\nuppercase. All other characters are left unchanged. The definition of what a lowercase letter\nis depends on the current locale. +upvalueid debug.upvalueid(f, n)\nReturns a unique identifier (as a light userdata) for the upvalue numbered `n` from the\ngiven function.\n\nThese unique identifiers allow a program to check whether different closures share upvalues. Lua\nclosures that share an upvalue (that is, that access a same external local variable) will\nreturn identical ids for those upvalue indices.\n\nNew in Lua 5.2. +upvaluejoin debug.upvaluejoin(f1, n1, f2, n2)\nMake the `n1`-th upvalue of the Lua closure `f1` refer to the `n2`-th upvalue of the Lua\nclosure `f2`.\n\nNew in Lua 5.2. utf8 _G.utf8 (module)\nLua utf8 module. version lpeg.version()\nReturns a string with the running version of LPeg. -warn _G.warn(msg1, ···)\nEmits a warning with a message composed by the concatenation of all its\narguments (which should be strings).\n\nBy convention, a one-piece message starting with '`@`' is intended to be a\n*control message*, which is a message to the warning system itself. In\nparticular, the standard warning function in Lua recognizes the control\nmessages "`@off`", to stop the emission of warnings, and "`@on`", to\n(re)start the emission; it ignores unknown control messages.\n\nNew in Lua 5.4. -wrap coroutine.wrap(f)\nCreates a new coroutine, with body `f`; `f` must be a Lua\nfunction. Returns a function that resumes the coroutine each time it is\ncalled. Any arguments passed to this function behave as the extra arguments\nto `resume`. The function returns the same values returned by `resume`,\nexcept the first boolean. In case of error, the function closes the coroutine\nand propagates the error. -write file:write(···)\nWrites the value of each of its arguments to `file`. The arguments must be\nstrings or numbers.\n\nIn case of success, this function returns `file`. Otherwise it returns nil\nplus a string describing the error. +warn _G.warn(msg1, ···)\nEmits a warning with a message composed by the concatenation of all its arguments (which\nshould be strings).\n\nBy convention, a one-piece message starting with '`@`' is intended to be a *control message*,\nwhich is a message to the warning system itself. In particular, the standard warning function in\nLua recognizes the control messages "`@off`", to stop the emission of warnings, and "`@on`",\nto (re)start the emission; it ignores unknown control messages.\n\nNew in Lua 5.4. +wrap coroutine.wrap(f)\nCreates a new coroutine, with body `f`; `f` must be a Lua function. Returns a function that\nresumes the coroutine each time it is called. Any arguments passed to this function behave as\nthe extra arguments to `resume`. The function returns the same values returned by `resume`,\nexcept the first boolean. In case of error, the function closes the coroutine and propagates\nthe error. +write file:write(···)\nWrites the value of each of its arguments to `file`. The arguments must be strings or numbers.\n\nIn case of success, this function returns `file`. Otherwise it returns nil plus a string\ndescribing the error. write io.write(···)\nEquivalent to `io.output():write(···)`. -xor bit32.xor(...)\nReturns the bitwise "exclusive or" of its operands.\n\nNew in Lua 5.2.\nDeprecated in Lua 5.3. -xpcall _G.xpcall(f, msgh [, arg1, ···])\nThis function is similar to `pcall`, except that it sets a new message\nhandler `msgh`. -yield coroutine.yield(···)\nSuspends the execution of the calling coroutine. Any arguments to `yield` are\npassed as extra results to `resume`.
\ No newline at end of file +xor bit32.xor(...)\nReturns the bitwise "exclusive or" of its operands.\n\nNew in Lua 5.2. Deprecated in Lua 5.3. +xpcall _G.xpcall(f, msgh [, arg1, ···])\nThis function is similar to `pcall`, except that it sets a new message handler `msgh`. +yield coroutine.yield(···)\nSuspends the execution of the calling coroutine. Any arguments to `yield` are passed as\nextra results to `resume`.
\ No newline at end of file diff --git a/modules/lua/init.lua b/modules/lua/init.lua index d327266d..00508de3 100644 --- a/modules/lua/init.lua +++ b/modules/lua/init.lua @@ -13,27 +13,25 @@ module('_M.lua')]] -- Autocompletion and documentation. --- Returns a function that, when called from a Textadept Lua file, the Lua --- command entry, or a special Lua buffer (e.g. a REPL), returns the given --- Textadept tags or API file for use in autocompletion and documentation. +-- Returns a function that, when called from a Textadept Lua file, the Lua command entry, or +-- a special Lua buffer (e.g. a REPL), returns the given Textadept tags or API file for use in +-- autocompletion and documentation. -- @param filename Textadept tags or api file to return. local function ta_api(filename) local home = '^' .. _HOME:gsub('%p', '%%%0'):gsub('%%[/\\]', '[/\\]') local userhome = '^' .. _USERHOME:gsub('%p', '%%%0'):gsub('%%[/\\]', '[/\\]') return function() - local buffer_filename = buffer.filename or '' - return (buffer_filename:find(home) or buffer_filename:find(userhome) or - buffer == ui.command_entry or buffer._type) and filename + local ta_file = (buffer.filename or ''):find(home) or (buffer.filename or ''):find(userhome) + return (ta_file or buffer == ui.command_entry or buffer._type) and filename end end --- --- 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. -- @class table -- @name tags M.tags = { @@ -43,8 +41,8 @@ M.tags = { --- -- 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. -- @class table -- @name expr_types -- @usage _M.lua.expr_types['^spawn%b()%s*$'] = 'proc' @@ -59,8 +57,7 @@ textadept.editing.autocompleters.lua = function() local list = {} -- Retrieve the symbol behind the caret. local line, pos = buffer:get_cur_line() - local symbol, op, part = line:sub(1, pos - 1):match( - '([%w_%.]-)([%.:]?)([%w_]*)$') + local symbol, op, part = line:sub(1, pos - 1):match('([%w_%.]-)([%.:]?)([%w_]*)$') if symbol == '' and part == '' then return nil end -- nothing to complete if symbol == '' and M.autocomplete_snippets then local _, snippets = textadept.editing.autocompleters.snippet() @@ -73,7 +70,10 @@ textadept.editing.autocompleters.lua = function() local expr = buffer:get_line(i):match(assignment) if not expr then goto continue end for patt, type in pairs(M.expr_types) do - if expr:find(patt) then symbol = type break end + if expr:find(patt) then + symbol = type + break + end end ::continue:: end diff --git a/modules/lua/lua.luadoc b/modules/lua/lua.luadoc index 8dc89938..52d81aeb 100644 --- a/modules/lua/lua.luadoc +++ b/modules/lua/lua.luadoc @@ -3,438 +3,391 @@ -- @class table -- @name _G -- @field _G (table) --- A global variable (not a function) that holds the global environment --- (see §2.2). Lua itself does not use this variable; changing its value does --- not affect any environment, nor vice versa. +-- A global variable (not a function) that holds the global environment (see §2.2). Lua +-- itself does not use this variable; changing its value does not affect any environment, +-- nor vice versa. -- @field _VERSION (string) --- A global variable (not a function) that holds a string containing the --- running Lua version. The current value of this variable is "`Lua 5.4`". +-- A global variable (not a function) that holds a string containing the running Lua version. The +-- current value of this variable is "`Lua 5.4`". local _G --- --- Raises an error if the value of its argument `v` is false (i.e., nil or --- false); otherwise, returns all its arguments. In case of error, `message` is --- the error object; when absent, it defaults to "assertion failed!". +-- Raises an error if the value of its argument `v` is false (i.e., nil or false); otherwise, +-- returns all its arguments. In case of error, `message` is the error object; when absent, +-- it defaults to "assertion failed!". function assert(v [, message]) end --- --- This function is a generic interface to the garbage collector. It --- performs different functions according to its first argument, `opt`: --- "collect": performs a full garbage-collection cycle. This is the default --- option. +-- This function is a generic interface to the garbage collector. It performs different functions +-- according to its first argument, `opt`: +-- "collect": performs a full garbage-collection cycle. This is the default option. -- "stop": stops automatic execution of the garbage collector. -- "restart": restarts automatic execution of the garbage collector. --- "count": returns the total memory in use by Lua in Kbytes. The value has a --- fractional part, so that it multiplied by 1024 gives the exact --- number of bytes in use by Lua. --- "step": performs a garbage-collection step. The step "size" is controlled --- by `arg`. With a zero value, the collector will perform one basic --- (indivisible) step. For non-zero values, the collector will perform --- as if that amount of memory (in Kbytes) had been allocated by Lua. --- Returns true if the step finished a collection cycle. --- "isrunning": returns a boolean that tells whether the collector is running --- (i.e., not stopped). --- "incremental": change the collector mode to incremental. This option can be --- followed by three numbers: the garbage-collector pause, the --- step multiplier, and the step size (see §2.5.1). A zero means to not --- change that value. --- "generational": change the collector mode to generational. This option can --- be followed by two numbers: the garbage-collector minor --- multiplier and the major multiplier (see §2.5.2). A zero --- means to not change that value. +-- "count": returns the total memory in use by Lua in Kbytes. The value has a fractional part, +-- so that it multiplied by 1024 gives the exact number of bytes in use by Lua. +-- "step": performs a garbage-collection step. The step "size" is controlled by `arg`. With a +-- zero value, the collector will perform one basic (indivisible) step. For non-zero values, +-- the collector will perform as if that amount of memory (in Kbytes) had been allocated +-- by Lua. Returns true if the step finished a collection cycle. +-- "isrunning": returns a boolean that tells whether the collector is running (i.e., not +-- stopped). +-- "incremental": change the collector mode to incremental. This option can be followed +-- by three numbers: the garbage-collector pause, the step multiplier, and the step size +-- (see §2.5.1). A zero means to not change that value. +-- "generational": change the collector mode to generational. This option can be followed +-- by two numbers: the garbage-collector minor multiplier and the major multiplier (see +-- §2.5.2). A zero means to not change that value. -- -- See §2.5 for more details about garbage collection and some of these options. function collectgarbage([opt [, arg]]) end --- --- Opens the named file and executes its content as a Lua chunk. When --- called without arguments, --- `dofile` executes the content of the standard input (`stdin`). Returns --- all values returned by the chunk. In case of errors, `dofile` propagates --- the error to its caller. (That is, `dofile` does not run in protected mode.) +-- Opens the named file and executes its content as a Lua chunk. When called without arguments, +-- `dofile` executes the content of the standard input (`stdin`). Returns all values returned +-- by the chunk. In case of errors, `dofile` propagates the error to its caller. (That is, +-- `dofile` does not run in protected mode.) function dofile([filename]) end --- --- Raises an error (see §2.3) with `message` as the error object. This function --- never returns. +-- Raises an error (see §2.3) with `message` as the error object. This function never returns. -- --- Usually, `error` adds some information about the error position at the --- beginning of the message, if the message is a string. The `level` argument --- specifies how to get the error position. With level 1 (the default), the --- error position is where the `error` function was called. Level 2 points the --- error to where the function that called `error` was called; and so on. --- Passing a level 0 avoids the addition of error position information to the --- message. +-- Usually, `error` adds some information about the error position at the beginning of the +-- message, if the message is a string. The `level` argument specifies how to get the error +-- position. With level 1 (the default), the error position is where the `error` function +-- was called. Level 2 points the error to where the function that called `error` was called; +-- and so on. Passing a level 0 avoids the addition of error position information to the message. function error(message [, level]) end --- --- Returns the current environment in use by the function. `f` can be a Lua --- function or a number that specifies the function at that stack level: --- Level 1 is the function calling `getfenv`. If the given function is not a --- Lua function, or if `f` is 0, `getfenv` returns the global environment. The --- default for `f` is 1. +-- Returns the current environment in use by the function. `f` can be a Lua function or a +-- number that specifies the function at that stack level: Level 1 is the function calling +-- `getfenv`. If the given function is not a Lua function, or if `f` is 0, `getfenv` returns +-- the global environment. The default for `f` is 1. -- -- Deprecated in Lua 5.2. function getfenv([f]) end --- --- If `object` does not have a metatable, returns nil. Otherwise, if the --- object's metatable has a `__metatable` field, returns the associated --- value. Otherwise, returns the metatable of the given object. +-- If `object` does not have a metatable, returns nil. Otherwise, if the object's metatable +-- has a `__metatable` field, returns the associated value. Otherwise, returns the metatable +-- of the given object. function getmetatable(object) end --- --- Returns three values (an iterator function, the table `t`, and 0) so that the --- construction +-- Returns three values (an iterator function, the table `t`, and 0) so that the construction -- -- for i,v in ipairs(t) do *body* end -- --- will iterate over the key-value pairs (`1,t[1]`), (`2,t[2]`), ···, up to the --- first absent index. +-- will iterate over the key-value pairs (`1,t[1]`), (`2,t[2]`), ···, up to the first +-- absent index. function ipairs(t) end --- -- Loads a chunk. -- --- If `chunk` is a string, the chunk is this string. If `chunk` is a function, --- `load` calls it repeatedly to get the chunk pieces. Each call to `chunk` must --- return a string that concatenates with previous results. A return of an empty --- string, nil, or no value signals the end of the chunk. --- --- If there are no syntactic errors, `load` returns the compiled chunk as a --- function; otherwise, it returns nil plus the error message. --- --- When you load a main chunk, the resulting function will always have exactly --- one upvalue, the `_ENV` variable (see §2.2). However, when you load a binary --- chunk created from a function (see `string.dump`), the resulting function can --- have an arbitrary number of upvalues, and there is no guarantee that its --- first upvalue will be the `_ENV` variable. (A non-main function may not even --- have an `_ENV` upvalue.) --- --- Regardless, if the resulting function has any upvalues, its first upvalue is --- set to the value of `env`, if that parameter is given, or to the value of the --- global environment. Other upvalues are initialized with nil. All upvalues are --- fresh, that is, they are not shared with any other function. --- --- `chunkname` is used as the name of the chunk for error messages and debug --- information (see §4.7). When absent, it defaults to `chunk`, if `chunk` is a --- string, or to "`=(load)`" otherwise. --- --- The string `mode` controls whether the chunk can be text or binary (that is, --- a precompiled chunk). It may be the string "`b`" (only binary chunks), "`t`" --- (only text chunks), or "`bt`" (both binary and text). The default is "`bt`". --- --- It is safe to load malformed binary chunks; `load` signals an appropriate --- error. However, Lua does not check the consistency of the code inside binary --- chunks; running maliciously crafted bytecode can crash the interpreter. +-- If `chunk` is a string, the chunk is this string. If `chunk` is a function, `load` calls +-- it repeatedly to get the chunk pieces. Each call to `chunk` must return a string that +-- concatenates with previous results. A return of an empty string, nil, or no value signals +-- the end of the chunk. +-- +-- If there are no syntactic errors, `load` returns the compiled chunk as a function; otherwise, +-- it returns nil plus the error message. +-- +-- When you load a main chunk, the resulting function will always have exactly one upvalue, the +-- `_ENV` variable (see §2.2). However, when you load a binary chunk created from a function +-- (see `string.dump`), the resulting function can have an arbitrary number of upvalues, +-- and there is no guarantee that its first upvalue will be the `_ENV` variable. (A non-main +-- function may not even have an `_ENV` upvalue.) +-- +-- Regardless, if the resulting function has any upvalues, its first upvalue is set to the +-- value of `env`, if that parameter is given, or to the value of the global environment. Other +-- upvalues are initialized with nil. All upvalues are fresh, that is, they are not shared with +-- any other function. +-- +-- `chunkname` is used as the name of the chunk for error messages and debug information (see +-- §4.7). When absent, it defaults to `chunk`, if `chunk` is a string, or to "`=(load)`" +-- otherwise. +-- +-- The string `mode` controls whether the chunk can be text or binary (that is, a precompiled +-- chunk). It may be the string "`b`" (only binary chunks), "`t`" (only text chunks), or "`bt`" +-- (both binary and text). The default is "`bt`". +-- +-- It is safe to load malformed binary chunks; `load` signals an appropriate error. However, +-- Lua does not check the consistency of the code inside binary chunks; running maliciously +-- crafted bytecode can crash the interpreter. function load(chunk [, chunkname [, mode [, env]]]) end --- --- Similar to `load`, but gets the chunk from file `filename` or from the --- standard input, if no file name is given. +-- Similar to `load`, but gets the chunk from file `filename` or from the standard input, +-- if no file name is given. function loadfile([filename [, mode [, env]]]) end --- --- Similar to `load`, but gets the chunk from the given string. To load and --- run a given string, use the idiom assert(loadstring(s))() When absent, --- `chunkname` defaults to the given string. +-- Similar to `load`, but gets the chunk from the given string. To load and run a given string, +-- use the idiom assert(loadstring(s))() When absent, `chunkname` defaults to the given string. -- -- Deprecated in Lua 5.2. function loadstring(string [, chunkname]) --- --- Creates a module. If there is a table in `package.loaded[name]`, this table --- is the module. Otherwise, if there is a global table `t` with the given name, --- this table is the module. Otherwise creates a new table `t` and sets it as --- the value of the global `name` and the value of `package.loaded[name]`. This --- function also initializes `t._NAME` with the given name, `t._M` with the --- module (`t` itself), and `t._PACKAGE` with the package name (the full module --- name minus last component; see below). Finally, `module` sets `t` as the new --- environment of the current function and the new value of --- `package.loaded[name]`, so that `require` returns `t`. If `name` is a --- compound name (that is, one with components separated by dots), `module` --- creates (or reuses, if they already exist) tables for each component. For --- instance, if `name` is `a.b.c`, then `module` stores the module table in --- field `c` of field `b` of global `a`. This function can receive optional --- *options* after the module name, where each option is a function to be --- applied over the module. +-- Creates a module. If there is a table in `package.loaded[name]`, this table is the +-- module. Otherwise, if there is a global table `t` with the given name, this table is the +-- module. Otherwise creates a new table `t` and sets it as the value of the global `name` +-- and the value of `package.loaded[name]`. This function also initializes `t._NAME` with the +-- given name, `t._M` with the module (`t` itself), and `t._PACKAGE` with the package name +-- (the full module name minus last component; see below). Finally, `module` sets `t` as the +-- new environment of the current function and the new value of `package.loaded[name]`, so that +-- `require` returns `t`. If `name` is a compound name (that is, one with components separated +-- by dots), `module` creates (or reuses, if they already exist) tables for each component. For +-- instance, if `name` is `a.b.c`, then `module` stores the module table in field `c` of field +-- `b` of global `a`. This function can receive optional *options* after the module name, +-- where each option is a function to be applied over the module. -- -- Deprecated in Lua 5.2. function module(name [, ···]) end --- --- Allows a program to traverse all fields of a table. Its first argument is --- a table and its second argument is an index in this table. A call to `next` --- returns the next index of the table and its associated value. When called --- with nil as its second argument, `next` returns an initial index and its --- associated value. When called with the last index, or with nil in an empty --- table, `next` returns nil. If the second argument is absent, then it is --- interpreted as nil. In particular, you can use `next(t)` to check whether a --- table is empty. +-- Allows a program to traverse all fields of a table. Its first argument is a table and its +-- second argument is an index in this table. A call to `next` returns the next index of the +-- table and its associated value. When called with nil as its second argument, `next` returns +-- an initial index and its associated value. When called with the last index, or with nil in +-- an empty table, `next` returns nil. If the second argument is absent, then it is interpreted +-- as nil. In particular, you can use `next(t)` to check whether a table is empty. -- --- The order in which the indices are enumerated is not specified, *even for --- numeric indices*. (To traverse a table in numeric order, use a numerical --- `for`.) +-- The order in which the indices are enumerated is not specified, *even for numeric indices*. (To +-- traverse a table in numeric order, use a numerical `for`.) -- --- The behavior of `next` is undefined if, during the traversal, you assign any --- value to a non-existent field in the table. You may however modify existing --- fields. In particular, you may set existing fields to nil. +-- The behavior of `next` is undefined if, during the traversal, you assign any value to a +-- non-existent field in the table. You may however modify existing fields. In particular, +-- you may set existing fields to nil. function next(table [, index]) end --- --- If `t` has a metamethod `__pairs`, calls it with `t` as argument and returns --- the first three results from the call. +-- If `t` has a metamethod `__pairs`, calls it with `t` as argument and returns the first three +-- results from the call. -- --- Otherwise, returns three values: the `next` function, the table `t`, and nil, --- so that the construction +-- Otherwise, returns three values: the `next` function, the table `t`, and nil, so that the +-- construction -- -- for k,v in pairs(t) do *body* end -- -- will iterate over all key–value pairs of table `t`. -- --- See function `next` for the caveats of modifying the table during its --- traversal. +-- See function `next` for the caveats of modifying the table during its traversal. function pairs(t) end --- --- Calls the function `f` with the given arguments in *protected mode*. This --- means that any error inside `f` is not propagated; instead, `pcall` catches --- the error and returns a status code. Its first result is the status code (a --- boolean), which is true if the call succeeds without errors. In such case, --- `pcall` also returns all results from the call, after this first result. In --- case of any error, `pcall` returns false plus the error object. Note that +-- Calls the function `f` with the given arguments in *protected mode*. This means that any +-- error inside `f` is not propagated; instead, `pcall` catches the error and returns a status +-- code. Its first result is the status code (a boolean), which is true if the call succeeds +-- without errors. In such case, `pcall` also returns all results from the call, after this +-- first result. In case of any error, `pcall` returns false plus the error object. Note that -- errors caught by `pcall` do not call a message handler. function pcall(f [, arg1, ···]) end --- --- Receives any number of arguments and prints their values to `stdout`, --- converting each argument to a string following the same rules of `tostring`. +-- Receives any number of arguments and prints their values to `stdout`, converting each argument +-- to a string following the same rules of `tostring`. -- --- The function `print` is not intended for formatted output, but only as a --- quick way to show a value, for instance for debugging. For complete control --- over the output, use `string.format` and `io.write`. +-- The function `print` is not intended for formatted output, but only as a quick way to show a +-- value, for instance for debugging. For complete control over the output, use `string.format` +-- and `io.write`. function print(···) end --- --- Checks whether `v1` is equal to `v2`, without invoking the `__eq` --- metamethod. Returns a boolean. +-- Checks whether `v1` is equal to `v2`, without invoking the `__eq` metamethod. Returns a boolean. function rawequal(v1, v2) end --- --- Gets the real value of `table[index]`, without using the `__index` --- metavalue. `table` must be a table; `index` may be any value. +-- Gets the real value of `table[index]`, without using the `__index` metavalue. `table` must +-- be a table; `index` may be any value. function rawget(table, index) end --- --- Returns the length of the object `v`, --- which must be a table or a string, --- without invoking the `__len` metamethod. --- Returns an integer. +-- Returns the length of the object `v`, which must be a table or a string, without invoking the +-- `__len` metamethod. Returns an integer. -- -- New in Lua 5.2. function rawlen(v) end --- --- Sets the real value of `table[index]` to `value`, without using the --- `__newindex` metavalue. `table` must be a table, `index` any value different --- from nil and NaN, and `value` any Lua value. +-- Sets the real value of `table[index]` to `value`, without using the `__newindex` +-- metavalue. `table` must be a table, `index` any value different from nil and NaN, and `value` +-- any Lua value. -- -- This function returns `table`. function rawset(table, index, value) end --- --- Sets the environment to be used by the given function. `f` can be a Lua --- function or a number that specifies the function at that stack level: Level 1 --- is the function calling `setfenv`. `setfenv` returns the given function. As a --- special case, when `f` is 0 `setfenv` changes the environment of the running --- thread. In this case, `setfenv` returns no values. +-- Sets the environment to be used by the given function. `f` can be a Lua function or a +-- number that specifies the function at that stack level: Level 1 is the function calling +-- `setfenv`. `setfenv` returns the given function. As a special case, when `f` is 0 `setfenv` +-- changes the environment of the running thread. In this case, `setfenv` returns no values. -- -- Deprecated in Lua 5.2. function setfenv(f, table) end --- --- If `index` is a number, returns all arguments after argument number --- `index`; a negative number indexes from the end (-1 is the last argument). --- Otherwise, `index` must be the string `"#"`, and `select` returns the total --- number of extra arguments it received. +-- If `index` is a number, returns all arguments after argument number `index`; a negative number +-- indexes from the end (-1 is the last argument). Otherwise, `index` must be the string `"#"`, +-- and `select` returns the total number of extra arguments it received. function select(index, ···) end --- --- Sets the metatable for the given table. If `metatable` is nil, removes the --- metatable of the given table. If the original metatable has a `__metatable` --- field, raises an error. +-- Sets the metatable for the given table. If `metatable` is nil, removes the metatable of the +-- given table. If the original metatable has a `__metatable` field, raises an error. -- -- This function returns `table`. -- --- To change the metatable of other types from Lua code, you must use the debug --- library (see §6.10). +-- To change the metatable of other types from Lua code, you must use the debug library +-- (see §6.10). function setmetatable(table, metatable) end --- --- When called with no `base`, `tonumber` tries to convert its argument to a --- number. If the argument is already a number or a string convertible to a --- number, then `tonumber` returns this number; otherwise, it --- returns nil. +-- When called with no `base`, `tonumber` tries to convert its argument to a number. If the +-- argument is already a number or a string convertible to a number, then `tonumber` returns +-- this number; otherwise, it returns nil. -- --- The conversion of strings can result in integers or floats, according to the --- lexical conventions of Lua (see §3.1). The string may have leading and --- trailing spaces and a sign. +-- The conversion of strings can result in integers or floats, according to the lexical +-- conventions of Lua (see §3.1). The string may have leading and trailing spaces and a sign. -- --- When called with `base`, then `e` must be a string to be interpreted as an --- integer numeral in that base. The base may be any integer between 2 and 36, --- inclusive. In bases above 10, the letter '`A`' (in either upper or lower --- case) represents 10, '`B`' represents 11, and so forth, with '`Z`' --- representing 35. If the string `e` is not a valid numeral in the given base, +-- When called with `base`, then `e` must be a string to be interpreted as an integer numeral +-- in that base. The base may be any integer between 2 and 36, inclusive. In bases above 10, +-- the letter '`A`' (in either upper or lower case) represents 10, '`B`' represents 11, and so +-- forth, with '`Z`' representing 35. If the string `e` is not a valid numeral in the given base, -- the function returns nil function tonumber(e [, base]) end --- --- Receives a value of any type and converts it to a string in a human-readable --- format. Floats always produce strings with some floating-point indication --- (either a decimal dot or an exponent). +-- Receives a value of any type and converts it to a string in a human-readable format. Floats +-- always produce strings with some floating-point indication (either a decimal dot or an +-- exponent). -- --- If the metatable of `v` has a `__tostring` field, then `tostring` calls the --- corresponding value with `v` as argument, and uses the result of the call as --- its result. Otherwise, if the metatable of `v` has a `__name` field with a --- string value, `tostring` may use that string in its final result. +-- If the metatable of `v` has a `__tostring` field, then `tostring` calls the corresponding +-- value with `v` as argument, and uses the result of the call as its result. Otherwise, if the +-- metatable of `v` has a `__name` field with a string value, `tostring` may use that string +-- in its final result. -- -- For complete control of how numbers are converted, use `string.format`. function tostring(v) end --- --- Returns the type of its only argument, coded as a string. The possible --- results of this function are " --- `nil`" (a string, not the value nil), "`number`", "`string`", "`boolean`", +-- Returns the type of its only argument, coded as a string. The possible results of this +-- function are " `nil`" (a string, not the value nil), "`number`", "`string`", "`boolean`", -- "`table`", "`function`", "`thread`", and "`userdata`". function type(v) end --- --- Returns the elements from the given table. This function is equivalent to --- return list[i], list[i+1], ···, list[j] except that the above code can --- be written only for a fixed number of elements. By default, `i` is 1 and --- `j` is the length of the list, as defined by the length operator --- (see §2.5.5). +-- Returns the elements from the given table. This function is equivalent to return list[i], +-- list[i+1], ···, list[j] except that the above code can be written only for a fixed number +-- of elements. By default, `i` is 1 and `j` is the length of the list, as defined by the length +-- operator (see §2.5.5). -- -- Deprecated in Lua 5.2. function unpack(list [, i [, j]]) end --- --- Emits a warning with a message composed by the concatenation of all its --- arguments (which should be strings). +-- Emits a warning with a message composed by the concatenation of all its arguments (which +-- should be strings). -- --- By convention, a one-piece message starting with '`@`' is intended to be a --- *control message*, which is a message to the warning system itself. In --- particular, the standard warning function in Lua recognizes the control --- messages "`@off`", to stop the emission of warnings, and "`@on`", to --- (re)start the emission; it ignores unknown control messages. +-- By convention, a one-piece message starting with '`@`' is intended to be a *control message*, +-- which is a message to the warning system itself. In particular, the standard warning function in +-- Lua recognizes the control messages "`@off`", to stop the emission of warnings, and "`@on`", +-- to (re)start the emission; it ignores unknown control messages. -- -- New in Lua 5.4. function warn(msg1, ···) end --- --- This function is similar to `pcall`, except that it sets a new message --- handler `msgh`. +-- This function is similar to `pcall`, except that it sets a new message handler `msgh`. function xpcall(f, msgh [, arg1, ···]) end --- --- Closes coroutine `co`, that is, closes all its pending to-be-closed variables --- and puts the coroutine in a dead state. The given coroutine must be dead or --- suspended. In case of error closing some variable, returns false plus the --- error object; otherwise returns true. +-- Closes coroutine `co`, that is, closes all its pending to-be-closed variables and puts the +-- coroutine in a dead state. The given coroutine must be dead or suspended. In case of error +-- closing some variable, returns false plus the error object; otherwise returns true. function coroutine.close(co) end --- --- Creates a new coroutine, with body `f`. `f` must be a Lua --- function. Returns this new coroutine, an object with type `"thread"`. +-- Creates a new coroutine, with body `f`. `f` must be a Lua function. Returns this new coroutine, +-- an object with type `"thread"`. function coroutine.create(f) end --- --- Returns true when the coroutine `co` can yield. The default for `co` is the --- running coroutine. +-- Returns true when the coroutine `co` can yield. The default for `co` is the running coroutine. -- --- A coroutine is yieldable if it is not the main thread and it is not inside a --- non-yieldable C function. +-- A coroutine is yieldable if it is not the main thread and it is not inside a non-yieldable +-- C function. -- -- New in Lua 5.3. function coroutine.isyieldable([co]) end --- --- Starts or continues the execution of coroutine `co`. The first time --- you resume a coroutine, it starts running its body. The values `val1`, --- ··· are passed as the arguments to the body function. If the coroutine --- has yielded, `resume` restarts it; the values `val1`, ··· are passed --- as the results from the yield. +-- Starts or continues the execution of coroutine `co`. The first time you resume a coroutine, +-- it starts running its body. The values `val1`, ··· are passed as the arguments to the body +-- function. If the coroutine has yielded, `resume` restarts it; the values `val1`, ··· are +-- passed as the results from the yield. -- --- If the coroutine runs without any errors, `resume` returns true plus any --- values passed to `yield` (when the coroutine yields) or any values returned --- by the body function (when the coroutine terminates). If there is any error, --- `resume` returns false plus the error message. +-- If the coroutine runs without any errors, `resume` returns true plus any values passed to +-- `yield` (when the coroutine yields) or any values returned by the body function (when the +-- coroutine terminates). If there is any error, `resume` returns false plus the error message. function coroutine.resume(co [, val1, ···]) end --- --- Returns the running coroutine plus a boolean, true when the running coroutine --- is the main one. +-- Returns the running coroutine plus a boolean, true when the running coroutine is the main one. function coroutine.running() end --- --- Returns the status of the coroutine `co`, as a string: `"running"`, if --- the coroutine is running (that is, it is the one that called `status`); --- `"suspended"`, if the coroutine is suspended in a call to `yield`, or if it --- has not started running yet; `"normal"` if the coroutine is active but not --- running (that is, it has resumed another coroutine); and `"dead"` if the --- coroutine has finished its body function, or if it has stopped with an error. +-- Returns the status of the coroutine `co`, as a string: `"running"`, if the coroutine is +-- running (that is, it is the one that called `status`); `"suspended"`, if the coroutine +-- is suspended in a call to `yield`, or if it has not started running yet; `"normal"` if the +-- coroutine is active but not running (that is, it has resumed another coroutine); and `"dead"` +-- if the coroutine has finished its body function, or if it has stopped with an error. function coroutine.status(co) end --- --- Creates a new coroutine, with body `f`; `f` must be a Lua --- function. Returns a function that resumes the coroutine each time it is --- called. Any arguments passed to this function behave as the extra arguments --- to `resume`. The function returns the same values returned by `resume`, --- except the first boolean. In case of error, the function closes the coroutine --- and propagates the error. +-- Creates a new coroutine, with body `f`; `f` must be a Lua function. Returns a function that +-- resumes the coroutine each time it is called. Any arguments passed to this function behave as +-- the extra arguments to `resume`. The function returns the same values returned by `resume`, +-- except the first boolean. In case of error, the function closes the coroutine and propagates +-- the error. function coroutine.wrap(f) end --- --- Suspends the execution of the calling coroutine. Any arguments to `yield` are --- passed as extra results to `resume`. +-- Suspends the execution of the calling coroutine. Any arguments to `yield` are passed as +-- extra results to `resume`. function coroutine.yield(···) end --- --- Loads the given module. The function starts by looking into the --- `package.loaded` table to determine whether `modname` is already loaded. If --- it is, then `require` returns the value stored at `package.loaded[modname]`. --- (The absence of a second result in this case signals that this call did not --- have to load the module.) Otherwise, it tries to find a *loader* for the --- module. --- --- To find a loader, `require` is guided by the table `package.searchers`. Each --- item in this table is a search function, that searches for the module in a --- particular way. By changing this table, we can change how `require` looks for --- a module. The following explanation is based on the default configuration for --- `package.searchers`. --- --- First `require` queries `package.preload[modname]`. If it has a value, --- this value (which must be a function) is the loader. Otherwise `require` --- searches for a Lua loader using the path stored in `package.path`. If --- that also fails, it searches for a C loader using the path stored in --- `package.cpath`. If that also fails, it tries an *all-in-one* loader (see --- `package.searchers`). --- --- Once a loader is found, `require` calls the loader with two arguments: --- `modname` and an extra value, a *loader data*, also returned by the searcher. --- The loader data can be any value useful to the module; for the default --- searchers, it indicates where the loader was found. (For instance, if the --- loader came from a file, this extra value is the file path.) If the loader --- returns any non-nil value, `require` assigns the returned value to --- `package.loaded[modname]`. If the loader does not return a non-nil value and --- has not assigned any value to `package.loaded[modname]`, then `require` --- assigns true to this entry. In any case, `require` returns the final value of --- `package.loaded[modname]`. Besides that value, `require` also returns as a --- second result the loader data returned by the searcher, which indicates how --- `require` found the module. --- --- If there is any error loading or running the module, or if it cannot find --- any loader for the module, then `require` raises an error. +-- Loads the given module. The function starts by looking into the `package.loaded` table to +-- determine whether `modname` is already loaded. If it is, then `require` returns the value +-- stored at `package.loaded[modname]`. (The absence of a second result in this case signals +-- that this call did not have to load the module.) Otherwise, it tries to find a *loader* +-- for the module. +-- +-- To find a loader, `require` is guided by the table `package.searchers`. Each item in this +-- table is a search function, that searches for the module in a particular way. By changing +-- this table, we can change how `require` looks for a module. The following explanation is +-- based on the default configuration for `package.searchers`. +-- +-- First `require` queries `package.preload[modname]`. If it has a value, this value (which must be +-- a function) is the loader. Otherwise `require` searches for a Lua loader using the path stored +-- in `package.path`. If that also fails, it searches for a C loader using the path stored in +-- `package.cpath`. If that also fails, it tries an *all-in-one* loader (see `package.searchers`). +-- +-- Once a loader is found, `require` calls the loader with two arguments: `modname` and an +-- extra value, a *loader data*, also returned by the searcher. The loader data can be any +-- value useful to the module; for the default searchers, it indicates where the loader +-- was found. (For instance, if the loader came from a file, this extra value is the file +-- path.) If the loader returns any non-nil value, `require` assigns the returned value to +-- `package.loaded[modname]`. If the loader does not return a non-nil value and has not assigned +-- any value to `package.loaded[modname]`, then `require` assigns true to this entry. In any +-- case, `require` returns the final value of `package.loaded[modname]`. Besides that value, +-- `require` also returns as a second result the loader data returned by the searcher, which +-- indicates how `require` found the module. +-- +-- If there is any error loading or running the module, or if it cannot find any loader for +-- the module, then `require` raises an error. function require(modname) end --- @@ -442,89 +395,93 @@ function require(modname) end -- @class table -- @name package -- @field config (string) --- A string describing some compile-time configurations for packages. This --- string is a sequence of lines: --- The first line is the directory separator string. Default is '`\`' for --- Windows and '`/`' for all other systems. --- The second line is the character that separates templates in a path. --- Default is '`;`'. --- The third line is the string that marks the substitution points in a --- template. Default is '`?`'. --- The fourth line is a string that, in a path in Windows, is replaced by --- the executable's directory. Default is '`!`'. --- The fifth line is a mark to ignore all text after it when building the --- `luaopen_` function name. Default is '`-`'. +-- A string describing some compile-time configurations for packages. This string is a sequence +-- of lines: +-- +-- * The first line is the directory separator string. Default is '`\`' for Windows and +-- '`/`' for all other systems. +-- * The second line is the character that separates templates in a path. Default is '`;`'. +-- * The third line is the string that marks the substitution points in a template. Default +-- is '`?`'. +-- * The fourth line is a string that, in a path in Windows, is replaced by the executable's +-- directory. Default is '`!`'. +-- * The fifth line is a mark to ignore all text after it when building the `luaopen_` +-- function name. Default is '`-`'. -- -- New in Lua 5.2. -- @field cpath (string) -- A string with the path used by `require` to search for a C loader. --- Lua initializes the C path `package.cpath` in the same way it initializes --- the Lua path `package.path`, using the environment variable `LUA_CPATH_5_4` --- or the environment variable `LUA_CPATH` or a default path defined in --- `luaconf.h`. +-- +-- Lua initializes the C path `package.cpath` in the same way it initializes the Lua path +-- `package.path`, using the environment variable `LUA_CPATH_5_4` or the environment variable +-- `LUA_CPATH` or a default path defined in `luaconf.h`. -- @field loaded (table) --- A table used by `require` to control which modules are already loaded. When --- you require a module `modname` and `package.loaded[modname]` is not false, --- `require` simply returns the value stored there. --- This variable is only a reference to the real table; assignments to this --- variable do not change the table used by `require`. +-- A table used by `require` to control which modules are already loaded. When you require +-- a module `modname` and `package.loaded[modname]` is not false, `require` simply returns +-- the value stored there. +-- +-- This variable is only a reference to the real table; assignments to this variable do not +-- change the table used by `require`. -- @field loaders (table) -- See `package.searchers`. -- -- Deprecated in Lua 5.2. -- @field path (string) -- A string with the path used by `require` to search for a Lua loader. --- At start-up, Lua initializes this variable with the value of the --- environment variable `LUA_PATH_5_4` or the environment variable `LUA_PATH` --- or with a default path defined in `luaconf.h`, if those environment --- variables are not defined. A "`;;`" in the value of the environment --- variable is replaced by the default path. +-- +-- At start-up, Lua initializes this variable with the value of the environment variable +-- `LUA_PATH_5_4` or the environment variable `LUA_PATH` or with a default path defined in +-- `luaconf.h`, if those environment variables are not defined. A "`;;`" in the value of the +-- environment variable is replaced by the default path. -- @field preload (table) -- A table to store loaders for specific modules (see `require`). --- This variable is only a reference to the real table; assignments to this --- variable do not change the table used by `require`. +-- +-- This variable is only a reference to the real table; assignments to this variable do not +-- change the table used by `require`. -- @field searchers (table) -- A table used by `require` to control how to find modules. --- Each entry in this table is a *searcher function*. When looking for a --- module, `require` calls each of these searchers in ascending order, with --- the module name (the argument given to `require`) as its sole argument. --- If the searcher finds the module, it returns another function, the module --- *loader*, plus an extra value, a *loader data*, that will be passed to that --- loader and returned as a second result by `require`. If it cannot find the --- module, it returns a string explaining why (or nil if it has nothing to --- say). +-- +-- Each entry in this table is a *searcher function*. When looking for a module, `require` +-- calls each of these searchers in ascending order, with the module name (the argument given +-- to `require`) as its sole argument. If the searcher finds the module, it returns another +-- function, the module *loader*, plus an extra value, a *loader data*, that will be passed +-- to that loader and returned as a second result by `require`. If it cannot find the module, +-- it returns a string explaining why (or nil if it has nothing to say). +-- -- Lua initializes this table with four functions. --- The first searcher simply looks for a loader in the `package.preload` --- table. --- The second searcher looks for a loader as a Lua library, using the path --- stored at `package.path`. The search is done as described in function --- `package.searchpath`. --- The third searcher looks for a loader as a C library, using the path given --- by the variable `package.cpath`. Again, the search is done as described in --- function `package.searchpath`. For instance, if the C path is the string +-- +-- The first searcher simply looks for a loader in the `package.preload` table. +-- +-- The second searcher looks for a loader as a Lua library, using the path stored at +-- `package.path`. The search is done as described in function `package.searchpath`. +-- +-- The third searcher looks for a loader as a C library, using the path given by the variable +-- `package.cpath`. Again, the search is done as described in function `package.searchpath`. For +-- instance, if the C path is the string +-- -- "./?.so;./?.dll;/usr/local/?/init.so" --- the searcher for module `foo` will try to open the files `./foo.so`, --- `./foo.dll`, and `/usr/local/foo/init.so`, in that order. Once it finds --- a C library, this searcher first uses a dynamic link facility to link the --- application with the library. Then it tries to find a C function inside the --- library to be used as the loader. The name of this C function is the string --- "`luaopen_`" concatenated with a copy of the module name where each dot --- is replaced by an underscore. Moreover, if the module name has a hyphen, --- its suffix after (and including) the first hyphen is removed. For instance, --- if the module name is `a.b.c-v2.1 `, the function name will be --- `luaopen_a_b_c`. The fourth searcher tries an *all-in-one loader*. It --- searches the C path for a library for the root name of the given module. --- For instance, when requiring `a.b.c`, it will search for a C library for --- `a`. If found, it looks into it for an open function for the submodule; in --- our example, that would be `luaopen_a_b_c`. With this facility, a package --- can pack several C submodules into one single library, with each submodule --- keeping its original open function. --- All searchers except the first one (preload) return as the extra value the --- file path where the module was found, as returned by `package.searchpath`. --- The first searcher always returns the string "`:preload:`". --- Searchers should raise no errors and have no side effects in Lua. (They may --- have side effects in C, for instance by linking the application with a --- library.) +-- +-- the searcher for module `foo` will try to open the files `./foo.so`, `./foo.dll`, and +-- `/usr/local/foo/init.so`, in that order. Once it finds a C library, this searcher first +-- uses a dynamic link facility to link the application with the library. Then it tries to +-- find a C function inside the library to be used as the loader. The name of this C function +-- is the string "`luaopen_`" concatenated with a copy of the module name where each dot +-- is replaced by an underscore. Moreover, if the module name has a hyphen, its suffix after +-- (and including) the first hyphen is removed. For instance, if the module name is `a.b.c-v2.1 +-- `, the function name will be `luaopen_a_b_c`. +-- +-- The fourth searcher tries an *all-in-one loader*. It searches the C path for a library for +-- the root name of the given module. For instance, when requiring `a.b.c`, it will search for +-- a C library for `a`. If found, it looks into it for an open function for the submodule; in +-- our example, that would be `luaopen_a_b_c`. With this facility, a package can pack several +-- C submodules into one single library, with each submodule keeping its original open function. +-- +-- All searchers except the first one (preload) return as the extra value the file path +-- where the module was found, as returned by `package.searchpath`. The first searcher always +-- returns the string "`:preload:`". +-- +-- Searchers should raise no errors and have no side effects in Lua. (They may have side +-- effects in C, for instance by linking the application with a library.) -- -- New in Lua 5.2. local package @@ -532,257 +489,226 @@ local package --- -- Dynamically links the host program with the C library `libname`. -- --- If `funcname` is "`*`", then it only links with the library, making the --- symbols exported by the library available to other dynamically linked --- libraries. Otherwise, it looks for a function `funcname` inside the library --- and returns this function as a C function. So, `funcname` must follow the --- `lua_CFunction` prototype (see `lua_CFunction`). --- --- This is a low-level function. It completely bypasses the package and module --- system. Unlike `require`, it does not perform any path searching and does --- not automatically adds extensions. `libname` must be the complete file name --- of the C library, including if necessary a path and an extension. `funcname` --- must be the exact name exported by the C library (which may depend on the --- C compiler and linker used). --- --- This function is not supported by Standard C. As such, it is only available --- on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix --- systems that support the `dlfcn` standard). --- --- This function is inherently insecure, as it allows Lua to call any function --- in any readable dynamic library in the system. (Lua calls any function --- assuming the function has a proper prototype and respects a proper protocol --- (see lua_CFunction). Therefore, calling an arbitrary function in an arbitrary --- dynamic library more often than not results in an access violation.) +-- If `funcname` is "`*`", then it only links with the library, making the symbols exported +-- by the library available to other dynamically linked libraries. Otherwise, it looks for +-- a function `funcname` inside the library and returns this function as a C function. So, +-- `funcname` must follow the `lua_CFunction` prototype (see `lua_CFunction`). +-- +-- This is a low-level function. It completely bypasses the package and module system. Unlike +-- `require`, it does not perform any path searching and does not automatically adds +-- extensions. `libname` must be the complete file name of the C library, including if necessary +-- a path and an extension. `funcname` must be the exact name exported by the C library (which +-- may depend on the C compiler and linker used). +-- +-- This function is not supported by Standard C. As such, it is only available on some platforms +-- (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the `dlfcn` +-- standard). +-- +-- This function is inherently insecure, as it allows Lua to call any function in any readable +-- dynamic library in the system. (Lua calls any function assuming the function has a proper +-- prototype and respects a proper protocol (see lua_CFunction). Therefore, calling an arbitrary +-- function in an arbitrary dynamic library more often than not results in an access violation.) function package.loadlib(libname, funcname) end --- -- Searches for the given `name` in the given `path`. -- --- A path is a string containing a sequence of _templates_ separated by --- semicolons. For each template, the function replaces each interrogation mark --- (if any) in the template with a copy of `name` wherein all occurrences of --- `sep` (a dot, by default) were replaced by `rep` (the system's directory --- separator, by default), and then tries to open the resulting file name. +-- A path is a string containing a sequence of _templates_ separated by semicolons. For each +-- template, the function replaces each interrogation mark (if any) in the template with a copy +-- of `name` wherein all occurrences of `sep` (a dot, by default) were replaced by `rep` (the +-- system's directory separator, by default), and then tries to open the resulting file name. -- For instance, if the path is the string +-- -- "./?.lua;./?.lc;/usr/local/?/init.lua" --- the search for the name `foo.a` will try to open the files `./foo/a.lua`, --- `./foo/a.lc`, and `/usr/local/foo/a/init.lua`, in that order. --- Returns the resulting name of the first file that it can open in read mode --- (after closing the file), or nil plus an error message if none succeeds. --- (This error message lists all file names it tried to open.) +-- +-- the search for the name `foo.a` will try to open the files `./foo/a.lua`, `./foo/a.lc`, and +-- `/usr/local/foo/a/init.lua`, in that order. +-- +-- Returns the resulting name of the first file that it can open in read mode (after closing +-- the file), or nil plus an error message if none succeeds. (This error message lists all file +-- names it tried to open.) -- -- New in Lua 5.2. function package.searchpath(name, path [, sep [, rep]]) end --- --- Sets a metatable for `module` with its `__index` field referring to the --- global environment, so that this module inherits values from the global --- environment. To be used as an option to function `module`. +-- Sets a metatable for `module` with its `__index` field referring to the global environment, +-- so that this module inherits values from the global environment. To be used as an option to +-- function `module`. -- -- Deprecated in Lua 5.2. function package.seeall(module) end --- --- Returns the internal numerical codes of the characters `s[i]`, `s[i+1]`, --- ···, `s[j]`. The default value for `i` is 1; the default value for `j` --- is `i`. These indices are corrected following the same rules of function --- `string.sub`. +-- Returns the internal numerical codes of the characters `s[i]`, `s[i+1]`, ···, `s[j]`. The +-- default value for `i` is 1; the default value for `j` is `i`. These indices are corrected +-- following the same rules of function `string.sub`. -- -- Numerical codes are not necessarily portable across platforms. function string.byte(s [, i [, j]]) end --- --- Receives zero or more integers. Returns a string with length equal to --- the number of arguments, in which each character has the internal numerical --- code equal to its corresponding argument. +-- Receives zero or more integers. Returns a string with length equal to the number of arguments, +-- in which each character has the internal numerical code equal to its corresponding argument. -- -- Numerical codes are not necessarily portable across platforms. function string.char(···) end --- --- Returns a string containing a binary representation (a _binary chunk_) of the --- given function, so that a later `load` on this string returns a copy of the --- function (but with new upvalues). If `strip` is a true value, the binary --- representation is created without debug information about the function (local --- variable names, lines, etc.). +-- Returns a string containing a binary representation (a _binary chunk_) of the given function, so +-- that a later `load` on this string returns a copy of the function (but with new upvalues). If +-- `strip` is a true value, the binary representation is created without debug information +-- about the function (local variable names, lines, etc.). -- --- Functions with upvalues have only their number of upvalues saved. When --- (re)loaded, those upvalues receive fresh instances. (See the `load` function --- for details about how these upvalues are initialized. You can use the debug --- library to serialize and reload the upvalues of a function in a way adequate --- to your needs.) +-- Functions with upvalues have only their number of upvalues saved. When (re)loaded, those +-- upvalues receive fresh instances. (See the `load` function for details about how these +-- upvalues are initialized. You can use the debug library to serialize and reload the upvalues +-- of a function in a way adequate to your needs.) function string.dump(function [, strip]) end --- --- Looks for the first match of `pattern` (see §6.4.1) in the string `s`. If it --- finds a match, then `find` returns the indices of `s` where this occurrence --- starts and ends; otherwise, it returns nil. A third, optional numerical --- argument `init` specifies where to start the search; its default value is 1 --- and can be negative. A value of true as a fourth, optional argument `plain` --- turns off the pattern matching facilities, so the function does a plain --- "find substring" operation, with no characters in `pattern` being considered --- magic. +-- Looks for the first match of `pattern` (see §6.4.1) in the string `s`. If it finds a match, +-- then `find` returns the indices of `s` where this occurrence starts and ends; otherwise, +-- it returns nil. A third, optional numerical argument `init` specifies where to start the +-- search; its default value is 1 and can be negative. A value of true as a fourth, optional +-- argument `plain` turns off the pattern matching facilities, so the function does a plain +-- "find substring" operation, with no characters in `pattern` being considered magic. -- --- If the pattern has captures, then in a successful match the captured values --- are also returned, after the two indices. +-- If the pattern has captures, then in a successful match the captured values are also returned, +-- after the two indices. function string.find(s, pattern [, init [, plain]]) end --- --- Returns a formatted version of its variable number of arguments following the --- description given in its first argument, which must be a string. The format --- string follows the same rules as the ISO C function `sprintf`. The only --- differences are that the conversion specifiers and modifiers `*`, `h`, `L`, --- `l`, and `n` are not supported and that there is an extra specifier, `q`. +-- Returns a formatted version of its variable number of arguments following the description +-- given in its first argument, which must be a string. The format string follows the same rules +-- as the ISO C function `sprintf`. The only differences are that the conversion specifiers and +-- modifiers `*`, `h`, `L`, `l`, and `n` are not supported and that there is an extra specifier, +-- `q`. -- --- The specifier `q` formats booleans, nil, numbers, and strings in a way that --- the result is a valid constant in Lua source code. Booleans and nil are --- written in the obvious way (`true`, `false`, `nil`). Floats are written in --- hexadecimal, to preserve full precision. A string is written between double --- quotes, using escape sequences when necessary to ensure that it can safely be --- read back by the Lua interpreter. For instance, the call +-- The specifier `q` formats booleans, nil, numbers, and strings in a way that the result is a +-- valid constant in Lua source code. Booleans and nil are written in the obvious way (`true`, +-- `false`, `nil`). Floats are written in hexadecimal, to preserve full precision. A string is +-- written between double quotes, using escape sequences when necessary to ensure that it can +-- safely be read back by the Lua interpreter. For instance, the call -- -- string.format('%q', 'a string with "quotes" and \n new line') -- -- may produce the string: -- --- "a string with \"quotes\" and \ --- new line" +-- "a string with \"quotes\" and \ new line" -- -- This specifier does not support modifiers (flags, width, length). -- --- The conversion specifiers `A` and `a` (when available), `E`, `e`, `f`, `G`, --- and `g` all expect a number as argument. The specifiers `c`, `d`, `i`, `o`, --- `u`, `X`, and `x` expect an integer. When Lua is compiled with a C89 --- compiler, the specifiers `A` and `a` (hexadecimal floats) do not support --- modifiers. +-- The conversion specifiers `A` and `a` (when available), `E`, `e`, `f`, `G`, and `g` all +-- expect a number as argument. The specifiers `c`, `d`, `i`, `o`, `u`, `X`, and `x` expect an +-- integer. When Lua is compiled with a C89 compiler, the specifiers `A` and `a` (hexadecimal +-- floats) do not support modifiers. -- --- The specifier `s` expects a string; if its argument is not a string, it is --- converted to one following the same rules of `tostring`. If the specifier has --- any modifier, the corresponding string argument should not contain zeros. +-- The specifier `s` expects a string; if its argument is not a string, it is converted to one +-- following the same rules of `tostring`. If the specifier has any modifier, the corresponding +-- string argument should not contain zeros. -- --- The specifier `p` formats the pointer returned by `lua_topointer`. That gives --- a unique string identifier for tables, userdata, threads, strings, and --- functions. For other values (numbers, nil, booleans), this specifier results --- in a string representing the pointer `NULL`. +-- The specifier `p` formats the pointer returned by `lua_topointer`. That gives a unique string +-- identifier for tables, userdata, threads, strings, and functions. For other values (numbers, +-- nil, booleans), this specifier results in a string representing the pointer `NULL`. function string.format(formatstring, ···) end --- --- Returns an iterator function that, each time it is called, returns the --- next captures from `pattern` (see §6.4.1) over the string `s`. If `pattern` --- specifies no captures, then the whole match is produced in each call. A --- third, optional argument `init` specifies where to start the search; its --- default value is 1 and can be negative. +-- Returns an iterator function that, each time it is called, returns the next captures from +-- `pattern` (see §6.4.1) over the string `s`. If `pattern` specifies no captures, then the +-- whole match is produced in each call. A third, optional argument `init` specifies where to +-- start the search; its default value is 1 and can be negative. -- --- As an example, the following loop will iterate over all the words from string --- `s`, printing one per line: +-- As an example, the following loop will iterate over all the words from string `s`, printing +-- one per line: -- --- s = "hello world from Lua" --- for w in string.gmatch(s, "%a+") do --- print(w) --- end +-- s = "hello world from Lua" for w in string.gmatch(s, "%a+") do +-- print(w) end -- --- The next example collects all pairs `key=value` from the given string into a --- table: +-- The next example collects all pairs `key=value` from the given string into a table: -- --- t = {} --- s = "from=world, to=Lua" --- for k, v in string.gmatch(s, "(%w+)=(%w+)") do --- t[k] = v --- end +-- t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do +-- t[k] = v end -- --- For this function, a caret '`^`' at the start of a pattern does not work as --- an anchor, as this would prevent the iteration. +-- For this function, a caret '`^`' at the start of a pattern does not work as an anchor, +-- as this would prevent the iteration. function string.gmatch(s, pattern [, init]) end --- --- Returns a copy of `s` in which all (or the first `n`, if given) --- occurrences of the `pattern` (see §6.4.1) have been replaced by a replacement --- string specified by `repl`, which can be a string, a table, or a function. --- `gsub` also returns, as its second value, the total number of matches that --- occurred. The name `gsub` comes from "Global SUBstitution". +-- Returns a copy of `s` in which all (or the first `n`, if given) occurrences of the `pattern` +-- (see §6.4.1) have been replaced by a replacement string specified by `repl`, which can be +-- a string, a table, or a function. `gsub` also returns, as its second value, the total number +-- of matches that occurred. The name `gsub` comes from "Global SUBstitution". -- --- If `repl` is a string, then its value is used for replacement. The character --- `%` works as an escape character: any sequence in `repl` of the form `%d`, --- with `d` between 1 and 9, stands for the value of the `d`-th captured --- substring; the sequence `%0` stands for the whole match; the sequence `%%` --- stands for a single `%`. +-- If `repl` is a string, then its value is used for replacement. The character `%` works as an +-- escape character: any sequence in `repl` of the form `%d`, with `d` between 1 and 9, stands +-- for the value of the `d`-th captured substring; the sequence `%0` stands for the whole match; +-- the sequence `%%` stands for a single `%`. -- --- If `repl` is a table, then the table is queried for every match, using --- the first capture as the key. +-- If `repl` is a table, then the table is queried for every match, using the first capture as +-- the key. -- --- If `repl` is a function, then this function is called every time a match --- occurs, with all captured substrings passed as arguments, in order. +-- If `repl` is a function, then this function is called every time a match occurs, with all +-- captured substrings passed as arguments, in order. -- --- In any case, if the pattern specifies no captures, then it behaves as if the --- whole pattern was inside a capture. +-- In any case, if the pattern specifies no captures, then it behaves as if the whole pattern +-- was inside a capture. -- --- If the value returned by the table query or by the function call is a --- string or a number, then it is used as the replacement string; otherwise, --- if it is false or nil, then there is no replacement (that is, the original --- match is kept in the string). +-- If the value returned by the table query or by the function call is a string or a number, +-- then it is used as the replacement string; otherwise, if it is false or nil, then there is +-- no replacement (that is, the original match is kept in the string). -- -- Here are some examples: -- --- x = string.gsub("hello world", "(%w+)", "%1 %1") --- --> x="hello hello world world" --- x = string.gsub("hello world", "%w+", "%0 %0", 1) --- --> x="hello hello world" --- x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --- --> x="world hello Lua from" --- x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) --- --> x="home = /home/roberto, user = roberto" +-- x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world" x = +-- string.gsub("hello world", "%w+", "%0 %0", 1) --> x="hello hello world" x = string.gsub("hello +-- world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from" x = string.gsub("home +-- = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto" -- x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) --- return load(s)() --- end) --- --> x="4+5 = 9" --- local t = {name="lua", version="5.4"} --- x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) --- --> x="lua-5.4.tar.gz" +-- return load(s)() end) +-- --> x="4+5 = 9" local t = {name="lua", version="5.4"} x = string.gsub("$name-$version.tar.gz", +-- "%$(%w+)", t) --> x="lua-5.4.tar.gz" function string.gsub(s, pattern, repl [, n]) end --- --- Receives a string and returns its length. The empty string `""` has --- length 0. Embedded zeros are counted, so `"a\000bc\000"` has length 5. +-- Receives a string and returns its length. The empty string `""` has length 0. Embedded zeros +-- are counted, so `"a\000bc\000"` has length 5. function string.len(s) end --- --- Receives a string and returns a copy of this string with all uppercase --- letters changed to lowercase. All other characters are left unchanged. The --- definition of what an uppercase letter is depends on the current locale. +-- Receives a string and returns a copy of this string with all uppercase letters changed to +-- lowercase. All other characters are left unchanged. The definition of what an uppercase +-- letter is depends on the current locale. function string.lower(s) end --- --- Looks for the first *match* of the `pattern` (see §6.4.1) in the string `s`. --- If it finds one, then `match` returns the captures from the pattern; --- otherwise it returns nil. If `pattern` specifies no captures, then the whole --- match is returned. A third, optional numerical argument `init` specifies --- where to start the search; its default value is 1 and can be negative. +-- Looks for the first *match* of the `pattern` (see §6.4.1) in the string `s`. If it finds one, +-- then `match` returns the captures from the pattern; otherwise it returns nil. If `pattern` +-- specifies no captures, then the whole match is returned. A third, optional numerical argument +-- `init` specifies where to start the search; its default value is 1 and can be negative. function string.match(s, pattern [, init]) end --- --- Returns a binary string containing the values `v1`, `v2`, etc. serialized in --- binary form (packed) according to the format string `fmt` (see §6.4.2). +-- Returns a binary string containing the values `v1`, `v2`, etc. serialized in binary form +-- (packed) according to the format string `fmt` (see §6.4.2). -- -- New in Lua 5.3. function string.pack(fmt, v1, v2, ···) end --- --- Returns the size of a string resulting from `string.pack` with the given --- format. The format string cannot have the variable-length options 's' or 'z' --- (see §6.4.2). +-- Returns the size of a string resulting from `string.pack` with the given format. The format +-- string cannot have the variable-length options 's' or 'z' (see §6.4.2). -- -- New in Lua 5.3. function string.packsize(fmt) end --- --- Returns a string that is the concatenation of `n` copies of the string `s` --- separated by the string `sep`. The default value for `sep` is the empty --- string (that is, no separator). Returns the empty string if `n` is not --- positive. +-- Returns a string that is the concatenation of `n` copies of the string `s` separated by the +-- string `sep`. The default value for `sep` is the empty string (that is, no separator). Returns +-- the empty string if `n` is not positive. -- --- (Note that it is very easy to exhaust the memory of your machine with a --- single call to this function.) +-- (Note that it is very easy to exhaust the memory of your machine with a single call to +-- this function.) function string.rep(s, n [, sep]) end --- @@ -790,31 +716,28 @@ function string.rep(s, n [, sep]) end function string.reverse(s) end --- --- Returns the substring of `s` that starts at `i` and continues until --- `j`; `i` and `j` can be negative. If `j` is absent, then it is assumed to --- be equal to -1 (which is the same as the string length). In particular, --- the call `string.sub(s,1,j)` returns a prefix of `s` with length `j`, and --- `string.sub(s, -i)` returns a suffix of `s` with length `i`. +-- Returns the substring of `s` that starts at `i` and continues until `j`; `i` and `j` can +-- be negative. If `j` is absent, then it is assumed to be equal to -1 (which is the same as +-- the string length). In particular, the call `string.sub(s,1,j)` returns a prefix of `s` +-- with length `j`, and `string.sub(s, -i)` returns a suffix of `s` with length `i`. -- --- If, after the translation of negative indices, `i` is less than 1, it is --- corrected to 1. If `j` is greater than the string length, it is corrected to --- that length. If, after these corrections, `i` is greater than `j`, the --- function returns the empty string. +-- If, after the translation of negative indices, `i` is less than 1, it is corrected to 1. If `j` +-- is greater than the string length, it is corrected to that length. If, after these corrections, +-- `i` is greater than `j`, the function returns the empty string. function string.sub(s, i [, j]) end --- --- Returns the values packed in string `s` (see `string.pack`) according to the --- format string `fmt` (see §6.4.2). An optional `pos` marks where to start --- reading in `s` (default is 1). After the read values, this function also --- returns the index of the first unread byte in `s`. +-- Returns the values packed in string `s` (see `string.pack`) according to the format string +-- `fmt` (see §6.4.2). An optional `pos` marks where to start reading in `s` (default is +-- 1). After the read values, this function also returns the index of the first unread byte in `s`. -- -- New in Lua 5.3. function string.unpack(fmt, s [, pos]) end --- --- Receives a string and returns a copy of this string with all lowercase --- letters changed to uppercase. All other characters are left unchanged. The --- definition of what a lowercase letter is depends on the current locale. +-- Receives a string and returns a copy of this string with all lowercase letters changed to +-- uppercase. All other characters are left unchanged. The definition of what a lowercase letter +-- is depends on the current locale. function string.upper(s) end --- @@ -822,16 +745,14 @@ function string.upper(s) end -- @class table -- @name utf8 -- @field charpattern (string) --- The pattern (a string, not a function) "[\0-\x7F\xC2-\xFD][\x80-\xBF]*" --- (see §6.4.1), which matches exactly one UTF-8 byte sequence, assuming that --- the subject is a valid UTF-8 string. +-- The pattern (a string, not a function) "[\0-\x7F\xC2-\xFD][\x80-\xBF]*" (see §6.4.1), which +-- matches exactly one UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string. -- -- New in Lua 5.3. --- --- Receives zero or more integers, converts each one to its corresponding UTF-8 --- byte sequence and returns a string with the concatenation of all these --- sequences. +-- Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence +-- and returns a string with the concatenation of all these sequences. -- -- New in Lua 5.3. function utf8.char(···) end @@ -841,58 +762,52 @@ function utf8.char(···) end -- -- for p, c in utf8.codes(s) do *body* end -- --- will iterate over all UTF-8 characters in string `s`, with `p` being the --- position (in bytes) and `c` the code point of each character. It raises an --- error if it meets any invalid byte sequence. +-- will iterate over all UTF-8 characters in string `s`, with `p` being the position (in bytes) and +-- `c` the code point of each character. It raises an error if it meets any invalid byte sequence. -- --- This function only accepts valid sequences (well formed and not overlong). --- By default, it only accepts byte sequences that result in valid Unicode code --- points, rejecting values greater than `10FFFF` and surrogates. The boolean --- argument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are --- accepted. (Not well formed and overlong sequences are still rejected.) +-- This function only accepts valid sequences (well formed and not overlong). By default, it only +-- accepts byte sequences that result in valid Unicode code points, rejecting values greater than +-- `10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values +-- up to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.) -- -- New in Lua 5.3. function utf8.codes(s [, lax]) end --- --- Returns the codepoints (as integers) from all characters in `s` that start --- between byte position `i` and `j` (both included). The default for `i` is 1 --- and for `j` is `i`. It raises an error if it meets any invalid byte sequence. +-- Returns the codepoints (as integers) from all characters in `s` that start between byte +-- position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises +-- an error if it meets any invalid byte sequence. -- --- This function only accepts valid sequences (well formed and not overlong). --- By default, it only accepts byte sequences that result in valid Unicode code --- points, rejecting values greater than `10FFFF` and surrogates. The boolean --- argument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are --- accepted. (Not well formed and overlong sequences are still rejected.) +-- This function only accepts valid sequences (well formed and not overlong). By default, it only +-- accepts byte sequences that result in valid Unicode code points, rejecting values greater than +-- `10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values +-- up to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.) -- -- New in Lua 5.3. function utf8.codepoint(s [, i [, j [, lax]]]) end --- --- Returns the number of UTF-8 characters in string `s` that start between --- positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` --- is -1. If it finds any invalid byte sequence, returns nil plus the position --- of the first invalid byte. +-- Returns the number of UTF-8 characters in string `s` that start between positions `i` and `j` +-- (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte +-- sequence, returns nil plus the position of the first invalid byte. -- --- This function only accepts valid sequences (well formed and not overlong). --- By default, it only accepts byte sequences that result in valid Unicode code --- points, rejecting values greater than `10FFFF` and surrogates. The boolean --- argument `lax` lifts these checks, so that all values up to `0x7FFFFFFF` are --- accepted. (Not well formed and overlong sequences are still rejected.) +-- This function only accepts valid sequences (well formed and not overlong). By default, it only +-- accepts byte sequences that result in valid Unicode code points, rejecting values greater than +-- `10FFFF` and surrogates. The boolean argument `lax` lifts these checks, so that all values +-- up to `0x7FFFFFFF` are accepted. (Not well formed and overlong sequences are still rejected.) -- -- New in Lua 5.3. function utf8.len(s [, i [, j [, lax]]]) end --- --- Returns the position (in bytes) where the encoding of the `n`-th character of --- `s` (counting from position `i`) starts. A negative `n` gets characters --- before position `i`. The default for `i` is 1 when `n` is non-negative and --- `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the --- `n`-th character from the end of the string. If the specified character is --- neither in the subject nor right after its end, the function returns nil. +-- Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting +-- from position `i`) starts. A negative `n` gets characters before position `i`. The default +-- for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` +-- gets the offset of the `n`-th character from the end of the string. If the specified character +-- is neither in the subject nor right after its end, the function returns nil. -- --- As a special case, when `n` is 0 the function returns the start of the --- encoding of the character that contains the `i`-th byte of `s`. +-- As a special case, when `n` is 0 the function returns the start of the encoding of the +-- character that contains the `i`-th byte of `s`. -- -- This function assumes that `s` is a valid UTF-8 string. -- @@ -901,31 +816,29 @@ function utf8.offset(s, n [, i]) end --- -- Given a list where all elements are strings or numbers, returns the string --- `list[i]..sep..list[i+1] ··· sep..list[j]`. The default value for `sep` is --- the empty string, the default for `i` is 1, and the default for `j` is --- `#list`. If `i` is greater than `j`, returns the empty string. +-- `list[i]..sep..list[i+1] ··· sep..list[j]`. The default value for `sep` is the empty +-- string, the default for `i` is 1, and the default for `j` is `#list`. If `i` is greater than +-- `j`, returns the empty string. function table.concat(list [, sep [, i [, j]]]) end --- --- Inserts element `value` at position `pos` in `list`, shifting up the elements --- `list[pos], list[pos+1], ···, list[#list]`. The default value for `pos` is --- `#list+1`, so that a call `table.insert(t,x)` inserts `x` at the end of the --- list `t`. +-- Inserts element `value` at position `pos` in `list`, shifting up the elements `list[pos], +-- list[pos+1], ···, list[#list]`. The default value for `pos` is `#list+1`, so that a call +-- `table.insert(t,x)` inserts `x` at the end of the list `t`. function table.insert(list, [pos,] value) end --- --- Returns the largest positive numerical index of the given table, or zero if --- the table has no positive numerical indices. (To do its job this function --- does a linear traversal of the whole table.) +-- Returns the largest positive numerical index of the given table, or zero if the table has +-- no positive numerical indices. (To do its job this function does a linear traversal of the +-- whole table.) -- -- Deprecated in Lua 5.2. function table.maxn(table) end --- --- Moves elements from the table `a1` to the table `a2`, performing the --- equivalent to the following multiple assignment: `a2[t], ··· = a1[f], ···, --- a1[e]`. The default for `a2` is `a1`. The destination range can overlap with --- the source range. Index `f` must be positive. +-- Moves elements from the table `a1` to the table `a2`, performing the equivalent to the +-- following multiple assignment: `a2[t], ··· = a1[f], ···, a1[e]`. The default for `a2` +-- is `a1`. The destination range can overlap with the source range. Index `f` must be positive. -- -- Returns the destination table `a2`. -- @@ -933,39 +846,35 @@ function table.maxn(table) end function table.move(a1, f, e, t [,a2]) end --- --- Returns a new table with all parameters stored into keys 1, 2, etc. and with --- a field "`n`" with the total number of parameters. Note that the resulting --- table may not be a sequence, if some arguments are nil. +-- Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "`n`" +-- with the total number of parameters. Note that the resulting table may not be a sequence, +-- if some arguments are nil. -- -- New in Lua 5.2. function table.pack(···) end --- --- Removes from `list` the element at position `pos`, returning the value of the --- removed element. When `pos` is an integer between 1 and `#list`, it shifts --- down the elements `list[pos+1], list[pos+2], ···, list[#list]` and erases --- element `list[#list]`; The index `pos` can also be 0 when `#list` is 0, or --- `#list + 1`. +-- Removes from `list` the element at position `pos`, returning the value of the removed +-- element. When `pos` is an integer between 1 and `#list`, it shifts down the elements +-- `list[pos+1], list[pos+2], ···, list[#list]` and erases element `list[#list]`; The index +-- `pos` can also be 0 when `#list` is 0, or `#list + 1`. -- --- The default value for `pos` is `#list`, so that a call `table.remove(l)` --- removes the last element of the list `l`. +-- The default value for `pos` is `#list`, so that a call `table.remove(l)` removes the last +-- element of the list `l`. function table.remove(list [, pos]) end --- --- Sorts the list elements in a given order, *in-place*, from `list[1]` to --- `list[#list]`. If `comp` is given, then it must be a function that receives --- two list elements and returns true when the first element must come before --- the second in the final order (so that, after the sort, `i < j` implies --- `not comp(list[j],list[i])` will be true after the sort). If `comp` is not --- given, then the standard Lua operator `<` is used instead. +-- Sorts the list elements in a given order, *in-place*, from `list[1]` to `list[#list]`. If +-- `comp` is given, then it must be a function that receives two list elements and returns true +-- when the first element must come before the second in the final order (so that, after the +-- sort, `i < j` implies `not comp(list[j],list[i])` will be true after the sort). If `comp` +-- is not given, then the standard Lua operator `<` is used instead. -- --- Note that the `comp` function must not define a string partial order over the --- elements in the list; that is, it must be asymmetric and transitive. --- Otherwise, no valid sort may be possible. +-- Note that the `comp` function must not define a string partial order over the elements in the +-- list; that is, it must be asymmetric and transitive. Otherwise, no valid sort may be possible. -- --- The sort algorithm is not stable; that is, elements not comparable by the --- given order (e.g., equal elements) may have their relative positions changed --- by the sort. +-- The sort algorithm is not stable; that is, elements not comparable by the given order (e.g., +-- equal elements) may have their relative positions changed by the sort. function table.sort(list [, comp]) end --- @@ -1009,18 +918,15 @@ function math.acos(x) end function math.asin(x) end --- --- Returns the arc tangent of `y/x` (in radians), but uses the signs --- of both parameters to find the quadrant of the result. It also handles --- correctly the case of `x` being zero. +-- Returns the arc tangent of `y/x` (in radians), but uses the signs of both parameters to find +-- the quadrant of the result. It also handles correctly the case of `x` being zero. -- --- The default value for `x` is 1, so that the call `math.atan(y)` returns the --- arc tangent of `y`. +-- The default value for `x` is 1, so that the call `math.atan(y)` returns the arc tangent of `y`. function math.atan(y [, x]) end --- --- Returns the arc tangent of `y/x` (in radians), but uses the signs --- of both parameters to find the quadrant of the result. (It also handles --- correctly the case of `x` being zero.) +-- Returns the arc tangent of `y/x` (in radians), but uses the signs of both parameters to find +-- the quadrant of the result. (It also handles correctly the case of `x` being zero.) -- -- Deprecated in Lua 5.3. function math.atan2(y, x) end @@ -1052,13 +958,13 @@ function math.exp(x) end function math.floor(x) end --- --- Returns the remainder of the division of `x` by `y` that rounds the --- quotient towards zero. (integer/float) +-- Returns the remainder of the division of `x` by `y` that rounds the quotient towards +-- zero. (integer/float) function math.fmod(x, y) end --- --- Returns `m` and `e` such that 'x = m2^e', `e` is an integer and the --- absolute value of `m` is in the range *[0.5, 1)* (or zero when `x` is zero). +-- Returns `m` and `e` such that 'x = m2^e', `e` is an integer and the absolute value of `m` +-- is in the range *[0.5, 1)* (or zero when `x` is zero). -- -- Deprecated in Lua 5.3. function math.frexp(x) end @@ -1070,8 +976,8 @@ function math.frexp(x) end function math.ldexp(m, e) end --- --- Returns the logarithm of `x` in the given base. The default for `base` is 'e' --- (so that the function returns the natural logarithm of `x`). +-- Returns the logarithm of `x` in the given base. The default for `base` is 'e' (so that the +-- function returns the natural logarithm of `x`). function math.log(x [, base]) end --- @@ -1081,23 +987,20 @@ function math.log(x [, base]) end function math.log10(x) end --- --- Returns the argument with the maximum value, according to the Lua operator --- `<`. +-- Returns the argument with the maximum value, according to the Lua operator `<`. function math.max(x, ···) end --- --- Returns the argument with the minimum value, according to the Lua operator --- `<`. +-- Returns the argument with the minimum value, according to the Lua operator `<`. function math.min(x, ···) end --- --- Returns the integral part of `x` and the fractional part of `x`. Its second --- result is always a float. +-- Returns the integral part of `x` and the fractional part of `x`. Its second result is always +-- a float. function math.modf(x) end --- --- Returns *x^y*. (You can also use the expression `x^y` to compute this --- value.) +-- Returns *x^y*. (You can also use the expression `x^y` to compute this value.) -- -- Deprecated in Lua 5.3. function math.pow(x, y) end @@ -1107,37 +1010,34 @@ function math.pow(x, y) end function math.rad(x) end --- --- When called without arguments, returns a pseudo-random float with uniform --- distribution in the range [0,1). When called with two integers `m` and `n`, --- `math.random` returns a pseudo-random integer with uniform distribution in --- the range `[m, n]. The call `math.random(n)`, for a positive `n`, is --- equivalent to `math.random(1,n)`. The call `math.random(0)` produces an +-- When called without arguments, returns a pseudo-random float with uniform distribution in the +-- range [0,1). When called with two integers `m` and `n`, `math.random` returns a pseudo-random +-- integer with uniform distribution in the range `[m, n]. The call `math.random(n)`, for a +-- positive `n`, is equivalent to `math.random(1,n)`. The call `math.random(0)` produces an -- integer with all bits (pseudo)random. -- --- This function uses the `xoshiro256**` algorithm to produce pseudo-random --- 64-bit integers, which are the results of calls with argument 0. Other --- results (ranges and floats) are unbiased extracted from these integers. +-- This function uses the `xoshiro256**` algorithm to produce pseudo-random 64-bit integers, +-- which are the results of calls with argument 0. Other results (ranges and floats) are unbiased +-- extracted from these integers. -- --- Lua initializes its pseudo-random generator with the equivalent of a call to --- `math.randomseed` with no arguments, so that `math.random` should generate --- different sequences of results each time the program runs. +-- Lua initializes its pseudo-random generator with the equivalent of a call to `math.randomseed` +-- with no arguments, so that `math.random` should generate different sequences of results each +-- time the program runs. function math.random([m [, n]]) end --- --- When called with at least one argument, the integer parameters `x` and `y` --- are joined into a 128-bit *seed* that is used to reinitialize the --- pseudo-random generator; equal seeds produce equal sequences of numbers. The --- default for `y` is zero. +-- When called with at least one argument, the integer parameters `x` and `y` are joined into a +-- 128-bit *seed* that is used to reinitialize the pseudo-random generator; equal seeds produce +-- equal sequences of numbers. The default for `y` is zero. -- --- When called with no arguments, Lua generates a seed with a weak attempt for --- randomness. +-- When called with no arguments, Lua generates a seed with a weak attempt for randomness. -- --- This function returns the two seed components that were effectively used, so --- that setting them again repeats the sequence. +-- This function returns the two seed components that were effectively used, so that setting +-- them again repeats the sequence. -- --- To ensure a required level of randomness to the initial state (or contrarily, --- to have a deterministic sequence, for instance when debugging a program), you --- should call `math.randomseed` with explicit arguments. +-- To ensure a required level of randomness to the initial state (or contrarily, to have +-- a deterministic sequence, for instance when debugging a program), you should call +-- `math.randomseed` with explicit arguments. function math.randomseed([x [, y]]) end --- @@ -1151,8 +1051,7 @@ function math.sin(x) end function math.sinh(x) end --- --- Returns the square root of `x`. (You can also use the expression `x^0.5` --- to compute this value.) +-- Returns the square root of `x`. (You can also use the expression `x^0.5` to compute this value.) function math.sqrt(x) end --- @@ -1166,101 +1065,88 @@ function math.tan(x) end function math.tanh(x) end --- --- If the value `x` is convertible to an integer, returns that integer. --- Otherwise, returns nil. +-- If the value `x` is convertible to an integer, returns that integer. Otherwise, returns nil. -- -- New in Lua 5.3. function math.tointeger(x) end --- --- Returns "integer" if `x` is an integer, "float" if it is a float, or nil if --- x is not a number. +-- Returns "integer" if `x` is an integer, "float" if it is a float, or nil if x is not a number. -- -- New in Lua 5.3. function math.type(x) end --- --- Returns a boolean, true if integer `m` is below integer `n` when they are --- compared as unsigned integers. +-- Returns a boolean, true if integer `m` is below integer `n` when they are compared as +-- unsigned integers. -- -- New in Lua 5.3. function math.ult(m, n) end --- --- Returns the number `x` shifted `disp` bits to the right. The number `disp` --- may be any representable integer. Negative displacements shift to the left. +-- Returns the number `x` shifted `disp` bits to the right. The number `disp` may be any +-- representable integer. Negative displacements shift to the left. -- --- This shift operation is what is called arithmetic shift. Vacant bits on the --- left are filled with copies of the higher bit of `x`; vacant bits on the --- right are filled with zeros. In particular, displacements with absolute --- values higher than 31 result in zero or `0xFFFFFFFF` (all original bits are --- shifted out). +-- This shift operation is what is called arithmetic shift. Vacant bits on the left are filled +-- with copies of the higher bit of `x`; vacant bits on the right are filled with zeros. In +-- particular, displacements with absolute values higher than 31 result in zero or `0xFFFFFFFF` +-- (all original bits are shifted out). -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.arshift(x, disp) end --- -- Returns the bitwise "and" of its operands. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.band(...) end --- --- Returns the bitwise negation of `x`. For any integer `x`, the following --- identity holds: +-- Returns the bitwise negation of `x`. For any integer `x`, the following identity holds: -- -- assert(bit32.bnot(x) == (-1 - x) % 2^32) -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.bnot(x) end --- -- Returns the bitwise "or" of its operands. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.bor(...) end --- --- Returns a boolean signaling whether the bitwise "and" of its operands is --- different from zero. +-- Returns a boolean signaling whether the bitwise "and" of its operands is different from zero. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.btest(...) end --- -- Returns the bitwise "exclusive or" of its operands. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.xor(...) end --- --- Returns the unsigned number formed by the bits `field` to `field + width - 1` --- from `n`. Bits are numbered from 0 (least significant) to 31 (most --- significant). All accessed bits must be in the range [0, 31]. +-- Returns the unsigned number formed by the bits `field` to `field + width - 1` from `n`. Bits +-- are numbered from 0 (least significant) to 31 (most significant). All accessed bits must be +-- in the range [0, 31]. -- -- The default for `width` is 1. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.extract(n, field [, width]) end --- --- Returns a copy of `n` with the bits `field` to `field + width - 1` replaced --- by the value `v`. See `bit32.extract` for details about `field` and `width`. +-- Returns a copy of `n` with the bits `field` to `field + width - 1` replaced by the value +-- `v`. See `bit32.extract` for details about `field` and `width`. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.replace(n, v, field [, width]) end --- --- Returns the number `x` rotated `disp` bits to the left. The number `disp` may --- be any representable integer. +-- Returns the number `x` rotated `disp` bits to the left. The number `disp` may be any +-- representable integer. -- -- For any valid displacement, the following identity holds: -- @@ -1268,28 +1154,25 @@ function bit32.replace(n, v, field [, width]) end -- -- In particular, negative displacements rotate to the right. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.lrotate(x, disp) end --- --- Returns the number `x` shifted `disp` bits to the left. The number `disp` may --- be any representable integer. Negative displacements shift to the right. In --- any direction, vacant bits are filled with zeros. In particular, --- displacements with absolute values higher than 31 result in zero (all bits --- are shifted out). +-- Returns the number `x` shifted `disp` bits to the left. The number `disp` may be any +-- representable integer. Negative displacements shift to the right. In any direction, vacant +-- bits are filled with zeros. In particular, displacements with absolute values higher than +-- 31 result in zero (all bits are shifted out). -- -- For positive displacements, the following equality holds: -- -- assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32) -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.lshift(x, disp) end --- --- Returns the number `x` rotated `disp` bits to the right. The number `disp` --- may be any representable integer. +-- Returns the number `x` rotated `disp` bits to the right. The number `disp` may be any +-- representable integer. -- -- For any valid displacement, the following identity holds: -- @@ -1297,16 +1180,14 @@ function bit32.lshift(x, disp) end -- -- In particular, negative displacements rotate to the left. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.rrotate(x, disp) end --- --- Returns the number `x` shifted `disp` bits to the right. The number `disp` --- may be any representable integer. Negative displacements shift to the left. --- In any direction, vacant bits are filled with zeros. In particular, --- displacements with absolute values higher than 31 result in zero (all bits --- are shifted out). +-- Returns the number `x` shifted `disp` bits to the right. The number `disp` may be any +-- representable integer. Negative displacements shift to the left. In any direction, vacant +-- bits are filled with zeros. In particular, displacements with absolute values higher than +-- 31 result in zero (all bits are shifted out). -- -- For positive displacements, the following equality holds: -- @@ -1314,8 +1195,7 @@ function bit32.rrotate(x, disp) end -- -- This shift operation is what is called logical shift. -- --- New in Lua 5.2. --- Deprecated in Lua 5.3. +-- New in Lua 5.2. Deprecated in Lua 5.3. function bit32.rshift(x, disp) end --- @@ -1331,8 +1211,7 @@ function bit32.rshift(x, disp) end local io --- --- Equivalent to `file:close()`. Without a `file`, closes the default --- output file. +-- Equivalent to `file:close()`. Without a `file`, closes the default output file. function io.close([file]) end --- @@ -1340,47 +1219,44 @@ function io.close([file]) end function io.flush() end --- --- When called with a file name, it opens the named file (in text mode), --- and sets its handle as the default input file. When called with a file --- handle, it simply sets this file handle as the default input file. When --- called without parameters, it returns the current default input file. +-- When called with a file name, it opens the named file (in text mode), and sets its handle as +-- the default input file. When called with a file handle, it simply sets this file handle as the +-- default input file. When called without parameters, it returns the current default input file. -- --- In case of errors this function raises the error, instead of returning an --- error code. +-- In case of errors this function raises the error, instead of returning an error code. function io.input([file]) end --- --- Opens the given file name in read mode and returns an iterator function that --- works like `file:lines(···)` over the opened file. When the iterator function --- fails to read any value, it automatically closes the file. Besides the --- iterator function, `io.lines` returns three other values: two nil values as --- placeholders, plus the created file handle. Therefore, when used in a generic --- for loop, the file is closed also if the loop is interrupted by an error or a --- `break`. +-- Opens the given file name in read mode and returns an iterator function that works like +-- `file:lines(···)` over the opened file. When the iterator function fails to read any value, +-- it automatically closes the file. Besides the iterator function, `io.lines` returns three other +-- values: two nil values as placeholders, plus the created file handle. Therefore, when used in +-- a generic for loop, the file is closed also if the loop is interrupted by an error or a `break`. -- --- The call `io.lines()` (with no file name) is equivalent to --- `io.input():lines("l")`; that is, it iterates over the lines of the default --- input file. In this case it does not close the file when the loop ends. +-- The call `io.lines()` (with no file name) is equivalent to `io.input():lines("l")`; that is, +-- it iterates over the lines of the default input file. In this case it does not close the +-- file when the loop ends. -- --- In case of errors opening the file, this function raises the error, instead --- of returning an error code. +-- In case of errors opening the file, this function raises the error, instead of returning an +-- error code. function io.lines([filename, ···]) end --- --- This function opens a file, in the mode specified in the string `mode`. It --- returns a new file handle, or, in case of errors, nil plus an error message. +-- This function opens a file, in the mode specified in the string `mode`. It returns a new +-- file handle, or, in case of errors, nil plus an error message. -- -- The `mode` string can be any of the following: --- "r": read mode (the default); --- "w": write mode; --- "a": append mode; --- "r+": update mode, all previous data is preserved; --- "w+": update mode, all previous data is erased; --- "a+": append update mode, previous data is preserved, writing is only --- allowed at the end of file. --- --- The `mode` string can also have a '`b`' at the end, which is needed in --- some systems to open the file in binary mode. +-- +-- * "r": read mode (the default); +-- * "w": write mode; +-- * "a": append mode; +-- * "r+": update mode, all previous data is preserved; +-- * "w+": update mode, all previous data is erased; +-- * "a+": append update mode, previous data is preserved, writing is only allowed at the +-- end of file. +-- +-- The `mode` string can also have a '`b`' at the end, which is needed in some systems to open +-- the file in binary mode. function io.open(filename [, mode]) end --- @@ -1388,9 +1264,9 @@ function io.open(filename [, mode]) end function io.output([file]) end --- --- Starts the program `prog` in a separated process and returns a file handle --- that you can use to read data from this program (if `mode` is `"r"`, --- the default) or to write data to this program (if `mode` is `"w"`). +-- Starts the program `prog` in a separated process and returns a file handle that you can use +-- to read data from this program (if `mode` is `"r"`, the default) or to write data to this +-- program (if `mode` is `"w"`). -- -- This function is system dependent and is not available on all platforms. function io.popen(prog [, mode]) end @@ -1400,14 +1276,14 @@ function io.popen(prog [, mode]) end function io.read(···) end --- --- In case of success, returns a handle for a temporary file. This file is --- opened in update mode and it is automatically removed when the program ends. +-- In case of success, returns a handle for a temporary file. This file is opened in update +-- mode and it is automatically removed when the program ends. function io.tmpfile() end --- --- Checks whether `obj` is a valid file handle. Returns the string `"file"` --- if `obj` is an open file handle, `"closed file"` if `obj` is a closed file --- handle, or nil if `obj` is not a file handle. +-- Checks whether `obj` is a valid file handle. Returns the string `"file"` if `obj` is an +-- open file handle, `"closed file"` if `obj` is a closed file handle, or nil if `obj` is not +-- a file handle. function io.type(obj) end --- @@ -1415,12 +1291,11 @@ function io.type(obj) end function io.write(···) end --- --- Closes `file`. Note that files are automatically closed when their --- handles are garbage collected, but that takes an unpredictable amount of --- time to happen. +-- Closes `file`. Note that files are automatically closed when their handles are garbage +-- collected, but that takes an unpredictable amount of time to happen. -- --- When closing a file handle created with `io.popen`, `file:close` returns the --- same values returned by `os.execute`. +-- When closing a file handle created with `io.popen`, `file:close` returns the same values +-- returned by `os.execute`. function file:close() end --- @@ -1428,228 +1303,210 @@ function file:close() end function file:flush() end --- --- Returns an iterator function that, each time it is called, reads the file --- according to the given formats. When no format is given, uses "l" as a --- default. As an example, the construction +-- Returns an iterator function that, each time it is called, reads the file according to the +-- given formats. When no format is given, uses "l" as a default. As an example, the construction -- -- for c in file:lines(1) do *body* end -- --- will iterate over all characters of the file, starting at the current --- position. Unlike `io.lines`, this function does not close the file when the --- loop ends. +-- will iterate over all characters of the file, starting at the current position. Unlike +-- `io.lines`, this function does not close the file when the loop ends. function file:lines(···) end --- --- Reads the file `file`, according to the given formats, which specify --- what to read. For each format, the function returns a string or a number --- with the characters read, or nil if it cannot read data with the specified --- format. (In this latter case, the function does not read subsequent formats.) --- When called without arguments, it uses a default format that reads the next --- line (see below). +-- Reads the file `file`, according to the given formats, which specify what to read. For each +-- format, the function returns a string or a number with the characters read, or nil if it +-- cannot read data with the specified format. (In this latter case, the function does not read +-- subsequent formats.) When called without arguments, it uses a default format that reads +-- the next line (see below). -- -- The available formats are --- "n": reads a numeral and returns it as a float or an integer, following the --- lexical conventions of Lua. (The numeral may have leading whitespaces --- and a sign.) This format always reads the longest input sequence that --- is a valid prefix for a number; if that prefix does not form a valid --- number (e.g., an empty string, "0x", or "3.4e-") or it is too long --- (more than 200 characters), it is discarded and the format returns --- nil. --- "a": reads the whole file, starting at the current position. On end of --- file, it returns the empty string; this format never fails. --- "l": reads the next line skipping the end of line, returning nil on --- end of file. This is the default format. --- "L": reads the next line keeping the end-of-line character (if present), --- returning nil on end of file. --- *number*: reads a string with up to this number of bytes, returning nil on --- end of file. If *number* is zero, it reads nothing and returns an --- empty string, or nil on end of file. +-- +-- * "n": reads a numeral and returns it as a float or an integer, following the lexical +-- conventions of Lua. (The numeral may have leading whitespaces and a sign.) This format +-- always reads the longest input sequence that is a valid prefix for a number; if that +-- prefix does not form a valid number (e.g., an empty string, "0x", or "3.4e-") or it is +-- too long (more than 200 characters), it is discarded and the format returns nil. +-- * "a": reads the whole file, starting at the current position. On end of file, it returns +-- the empty string; this format never fails. +-- * "l": reads the next line skipping the end of line, returning nil on end of file. This +-- is the default format. +-- * "L": reads the next line keeping the end-of-line character (if present), returning nil +-- on end of file. +-- * *number*: reads a string with up to this number of bytes, returning nil on end of file. If +-- *number* is zero, it reads nothing and returns an empty string, or nil on end of file. -- -- The formats "l" and "L" should be used only for text files. function file:read(···) end --- --- Sets and gets the file position, measured from the beginning of the --- file, to the position given by `offset` plus a base specified by the string --- `whence`, as follows: --- "set": base is position 0 (beginning of the file); --- "cur": base is current position; --- "end": base is end of file; +-- Sets and gets the file position, measured from the beginning of the file, to the position +-- given by `offset` plus a base specified by the string `whence`, as follows: -- --- In case of success, function `seek` returns the final file position, --- measured in bytes from the beginning of the file. If `seek` fails, it returns --- nil, plus a string describing the error. +-- * "set": base is position 0 (beginning of the file); +-- * "cur": base is current position; +-- * "end": base is end of file; -- --- The default value for `whence` is `"cur"`, and for `offset` is 0. Therefore, --- the call `file:seek()` returns the current file position, without changing --- it; the call `file:seek("set")` sets the position to the beginning of the --- file (and returns 0); and the call `file:seek("end")` sets the position --- to the end of the file, and returns its size. +-- In case of success, function `seek` returns the final file position, measured in bytes from +-- the beginning of the file. If `seek` fails, it returns nil, plus a string describing the error. +-- +-- The default value for `whence` is `"cur"`, and for `offset` is 0. Therefore, the +-- call `file:seek()` returns the current file position, without changing it; the call +-- `file:seek("set")` sets the position to the beginning of the file (and returns 0); and the +-- call `file:seek("end")` sets the position to the end of the file, and returns its size. function file:seek([whence [, offset]]) end --- -- Sets the buffering mode for a file. There are three available modes: --- "no": no buffering --- "full": full buffering --- "line": line buffering -- --- For the last two cases, `size` is a hint for the size of the buffer, in --- bytes. The default is an appropriate size. +-- * "no": no buffering +-- * "full": full buffering +-- * "line": line buffering +-- +-- For the last two cases, `size` is a hint for the size of the buffer, in bytes. The default +-- is an appropriate size. -- --- The specific behavior of each mode is non portable; check the underlying --- ISO C function `setvbuf` in your platform for more details. +-- The specific behavior of each mode is non portable; check the underlying ISO C function +-- `setvbuf` in your platform for more details. function file:setvbuf(mode [, size]) end --- --- Writes the value of each of its arguments to `file`. The arguments must be --- strings or numbers. +-- Writes the value of each of its arguments to `file`. The arguments must be strings or numbers. -- --- In case of success, this function returns `file`. Otherwise it returns nil --- plus a string describing the error. +-- In case of success, this function returns `file`. Otherwise it returns nil plus a string +-- describing the error. function file:write(···) end --- --- Returns an approximation of the amount in seconds of CPU time used by --- the program, as returned by the underlying ISO C function `clock`. +-- Returns an approximation of the amount in seconds of CPU time used by the program, as returned +-- by the underlying ISO C function `clock`. function os.clock() end --- --- Returns a string or a table containing date and time, formatted according --- to the given string `format`. +-- Returns a string or a table containing date and time, formatted according to the given string +-- `format`. -- --- If the `time` argument is present, this is the time to be formatted --- (see the `os.time` function for a description of this value). Otherwise, --- `date` formats the current time. +-- If the `time` argument is present, this is the time to be formatted (see the `os.time` +-- function for a description of this value). Otherwise, `date` formats the current time. -- --- If `format` starts with '`!`', then the date is formatted in Coordinated --- Universal Time. After this optional character, if `format` is the string --- "`*t`", then `date` returns a table with the following fields: `year`, --- `month` (1-12), `day` (1-31), `hour` (0-23), `min` (0-59), `sec` (0-61, due --- to leap seconds), `wday` (weekday, 1-7, Sunday is 1), `yday` (day of the --- year, 1-366), and `isdst` (daylight saving flag, a boolean). This last field --- may be absent if the information is not available. +-- If `format` starts with '`!`', then the date is formatted in Coordinated Universal Time. After +-- this optional character, if `format` is the string "`*t`", then `date` returns a table with +-- the following fields: `year`, `month` (1-12), `day` (1-31), `hour` (0-23), `min` (0-59), +-- `sec` (0-61, due to leap seconds), `wday` (weekday, 1-7, Sunday is 1), `yday` (day of the +-- year, 1-366), and `isdst` (daylight saving flag, a boolean). This last field may be absent +-- if the information is not available. -- --- If `format` is not "`*t`", then `date` returns the date as a string, --- formatted according to the same rules as the ISO C function `strftime`. +-- If `format` is not "`*t`", then `date` returns the date as a string, formatted according to +-- the same rules as the ISO C function `strftime`. -- --- If `format` is absent, it defaults to "`%c`", which gives a human-readable --- date and time representation using the current locale. +-- If `format` is absent, it defaults to "`%c`", which gives a human-readable date and time +-- representation using the current locale. -- --- On non-POSIX systems, this function may be not thread safe because of its --- reliance on C function `gmtime` and C function `localtime`. +-- On non-POSIX systems, this function may be not thread safe because of its reliance on C +-- function `gmtime` and C function `localtime`. function os.date([format [, time]]) end --- --- Returns the difference, in seconds, from time `t1` to time `t2` (where the --- times are values returned by `os.time`). In POSIX, Windows, and some other --- systems, this value is exactly `t2`*-*`t1`. +-- Returns the difference, in seconds, from time `t1` to time `t2` (where the times are values +-- returned by `os.time`). In POSIX, Windows, and some other systems, this value is exactly +-- `t2`*-*`t1`. function os.difftime(t2, t1) end --- --- This function is equivalent to the ISO C function `system`. It passes --- `command` to be executed by an operating system shell. Its first result is --- `true` if the command terminated successfully, or `nil` otherwise. After this --- first result the function returns a string plus a number, as follows: --- "exit": the command terminated normally; the following number is the exit --- status of the command. --- "signal": the command was terminated by a signal; the following number is --- the signal that terminated the command. +-- This function is equivalent to the ISO C function `system`. It passes `command` to be +-- executed by an operating system shell. Its first result is `true` if the command terminated +-- successfully, or `nil` otherwise. After this first result the function returns a string plus +-- a number, as follows: -- --- When called without a `command`, `os.execute` returns a boolean that is true --- if a shell is available. +-- * "exit": the command terminated normally; the following number is the exit status of +-- the command. +-- * "signal": the command was terminated by a signal; the following number is the signal +-- that terminated the command. +-- +-- When called without a `command`, `os.execute` returns a boolean that is true if a shell +-- is available. function os.execute([command]) end --- --- Calls the ISO C function `exit` to terminate the host program. If `code` is --- `true`, the returned status is `EXIT_SUCCESS`; if `code` is `false`, the --- returned status is `EXIT_FAILURE`; if `code` is a number, the returned status --- is this number. The default value for `code` is `true`. +-- Calls the ISO C function `exit` to terminate the host program. If `code` is `true`, the returned +-- status is `EXIT_SUCCESS`; if `code` is `false`, the returned status is `EXIT_FAILURE`; if +-- `code` is a number, the returned status is this number. The default value for `code` is `true`. -- --- If the optional second argument `close` is true, closes the Lua state before --- exiting. +-- If the optional second argument `close` is true, closes the Lua state before exiting. function os.exit([code [, close]]) end --- --- Returns the value of the process environment variable `varname`, or --- nil if the variable is not defined. +-- Returns the value of the process environment variable `varname`, or nil if the variable is +-- not defined. function os.getenv(varname) end --- --- Deletes the file (or empty directory, on POSIX systems) with the given name. --- If this function fails, it returns nil, plus a string describing the error --- and the error code. +-- Deletes the file (or empty directory, on POSIX systems) with the given name. If this function +-- fails, it returns nil, plus a string describing the error and the error code. function os.remove(filename) end --- --- Renames file or directory named `oldname` to `newname`. If this function --- fails, it returns nil, plus a string describing the error and the error code. +-- Renames file or directory named `oldname` to `newname`. If this function fails, it returns +-- nil, plus a string describing the error and the error code. function os.rename(oldname, newname) end --- --- Sets the current locale of the program. `locale` is a system-dependent string --- specifying a locale; `category` is an optional string describing which --- category to change: `"all"`, `"collate"`, `"ctype"`, `"monetary"`, --- `"numeric"`, or `"time"`; the default category is `"all"`. The function --- returns the name of the new locale, or nil if the request cannot be honored. +-- Sets the current locale of the program. `locale` is a system-dependent string specifying +-- a locale; `category` is an optional string describing which category to change: `"all"`, +-- `"collate"`, `"ctype"`, `"monetary"`, `"numeric"`, or `"time"`; the default category is +-- `"all"`. The function returns the name of the new locale, or nil if the request cannot +-- be honored. -- --- If `locale` is the empty string, the current locale is set to an --- implementation-defined native locale. If `locale` is the string "`C`", --- the current locale is set to the standard C locale. +-- If `locale` is the empty string, the current locale is set to an implementation-defined native +-- locale. If `locale` is the string "`C`", the current locale is set to the standard C locale. -- --- When called with nil as the first argument, this function only returns --- the name of the current locale for the given category. +-- When called with nil as the first argument, this function only returns the name of the +-- current locale for the given category. -- --- This function may not be thread safe because of its reliance on C function --- `setlocale`. +-- This function may not be thread safe because of its reliance on C function `setlocale`. function os.setlocale(locale [, category]) end --- --- Returns the current time when called without arguments, or a time --- representing the date and time specified by the given table. This table --- must have fields `year`, `month`, and `day`, and may have fields `hour` --- (default is 12), `min` (default is 0), `sec` (default is 0), and `isdst` --- (default is nil). For a description of these fields, see the `os.date` --- function. +-- Returns the current time when called without arguments, or a time representing the date and +-- time specified by the given table. This table must have fields `year`, `month`, and `day`, +-- and may have fields `hour` (default is 12), `min` (default is 0), `sec` (default is 0), and +-- `isdst` (default is nil). For a description of these fields, see the `os.date` function. -- --- When the function is called, the values in these fields do not need to be --- inside their valid ranges. For instance, if `sec` is -10, it means 10 seconds --- before the time specified by the other fields; if `hour` is 1000, it means --- 1000 hours after the time specified by the other fields. +-- When the function is called, the values in these fields do not need to be inside their +-- valid ranges. For instance, if `sec` is -10, it means 10 seconds before the time specified +-- by the other fields; if `hour` is 1000, it means 1000 hours after the time specified by the +-- other fields. -- --- The returned value is a number, whose meaning depends on your system. In --- POSIX, Windows, and some other systems, this number counts the number of --- seconds since some given start time (the "epoch"). In other systems, the --- meaning is not specified, and the number returned by `time` can be used only --- as an argument to `os.date` and `os.difftime`. +-- The returned value is a number, whose meaning depends on your system. In POSIX, Windows, +-- and some other systems, this number counts the number of seconds since some given start time +-- (the "epoch"). In other systems, the meaning is not specified, and the number returned by +-- `time` can be used only as an argument to `os.date` and `os.difftime`. -- --- When called with a table, `os.time` also normalizes all the fields documented --- in the `os.date` function, so that they represent the same time as before the --- call but with values inside their valid ranges. +-- When called with a table, `os.time` also normalizes all the fields documented in the `os.date` +-- function, so that they represent the same time as before the call but with values inside +-- their valid ranges. function os.time([table]) end --- --- Returns a string with a file name that can be used for a temporary --- file. The file must be explicitly opened before its use and explicitly --- removed when no longer needed. +-- Returns a string with a file name that can be used for a temporary file. The file must be +-- explicitly opened before its use and explicitly removed when no longer needed. -- --- On POSIX systems, this function also creates a file with that name, to avoid --- security risks. (Someone else might create the file with wrong permissions in --- the time between getting the name and creating the file.) You still have to --- open the file to use it and to remove it (even if you do not use it). +-- On POSIX systems, this function also creates a file with that name, to avoid security +-- risks. (Someone else might create the file with wrong permissions in the time between getting +-- the name and creating the file.) You still have to open the file to use it and to remove it +-- (even if you do not use it). -- --- When possible, you may prefer to use `io.tmpfile`, which automatically --- removes the file when the program ends. +-- When possible, you may prefer to use `io.tmpfile`, which automatically removes the file when +-- the program ends. function os.tmpname() end --- --- Enters an interactive mode with the user, running each string that --- the user enters. Using simple commands and other debug facilities, --- the user can inspect global and local variables, change their values, --- evaluate expressions, and so on. A line containing only the word `cont` +-- Enters an interactive mode with the user, running each string that the user enters. Using +-- simple commands and other debug facilities, the user can inspect global and local variables, +-- change their values, evaluate expressions, and so on. A line containing only the word `cont` -- finishes this function, so that the caller continues its execution. -- --- Note that commands for `debug.debug` are not lexically nested within any --- function and so have no direct access to local variables. +-- Note that commands for `debug.debug` are not lexically nested within any function and so +-- have no direct access to local variables. function debug.debug() end --- @@ -1659,60 +1516,54 @@ function debug.debug() end function debug.getfenv(o) end --- --- Returns the current hook settings of the thread, as three values: the --- current hook function, the current hook mask, and the current hook count, --- as set by the `debug.sethook` function. +-- Returns the current hook settings of the thread, as three values: the current hook function, +-- the current hook mask, and the current hook count, as set by the `debug.sethook` function. -- -- Returns nil if there is no active hook. function debug.gethook([thread]) end --- --- Returns a table with information about a function. You can give the --- function directly or you can give a number as the value of `f`, which means --- the function running at level `f` of the call stack of the given thread: --- level 0 is the current function (`getinfo` itself); level 1 is the function --- that called `getinfo` (except for tail calls, which do not count in the --- stack); and so on. If `f` is a number greater than the number of active --- functions, then `getinfo` returns nil. --- --- The returned table can contain all the fields returned by `lua_getinfo`, --- with the string `what` describing which fields to fill in. The default for --- `what` is to get all information available, except the table of valid --- lines. If present, the option '`f`' adds a field named `func` with --- the function itself. If present, the option '`L`' adds a field named --- `activelines` with the table of valid lines. --- --- For instance, the expression `debug.getinfo(1,"n").name` returns a table --- with a name for the current function, if a reasonable name can be found, --- and the expression `debug.getinfo(print)` returns a table with all available --- information about the `print` function. +-- Returns a table with information about a function. You can give the function directly or +-- you can give a number as the value of `f`, which means the function running at level `f` +-- of the call stack of the given thread: level 0 is the current function (`getinfo` itself); +-- level 1 is the function that called `getinfo` (except for tail calls, which do not count in +-- the stack); and so on. If `f` is a number greater than the number of active functions, then +-- `getinfo` returns nil. +-- +-- The returned table can contain all the fields returned by `lua_getinfo`, with the string +-- `what` describing which fields to fill in. The default for `what` is to get all information +-- available, except the table of valid lines. If present, the option '`f`' adds a field named +-- `func` with the function itself. If present, the option '`L`' adds a field named `activelines` +-- with the table of valid lines. +-- +-- For instance, the expression `debug.getinfo(1,"n").name` returns a table with a name for the +-- current function, if a reasonable name can be found, and the expression `debug.getinfo(print)` +-- returns a table with all available information about the `print` function. function debug.getinfo([thread,] f [, what]) end --- --- This function returns the name and the value of the local variable with index --- `local` of the function at level `f` of the stack. This function accesses not --- only explicit local variables, but also parameters and temporary values. +-- This function returns the name and the value of the local variable with index `local` of the +-- function at level `f` of the stack. This function accesses not only explicit local variables, +-- but also parameters and temporary values. -- --- The first parameter or local variable has index 1, and so on, following the --- order that they are declared in the code, counting only the variables that --- are active in the current scope of the function. Compile-time constants may --- not appear in this listing, if they were optimized away by the compiler. --- Negative indices refer to vararg parameters; -1 is the first vararg --- parameter. The function returns nil if there is no variable with the given --- index, and raises an error when called with a level out of range. (You can --- call `debug.getinfo` to check whether the level is valid.) +-- The first parameter or local variable has index 1, and so on, following the order that +-- they are declared in the code, counting only the variables that are active in the current +-- scope of the function. Compile-time constants may not appear in this listing, if they were +-- optimized away by the compiler. Negative indices refer to vararg parameters; -1 is the first +-- vararg parameter. The function returns nil if there is no variable with the given index, +-- and raises an error when called with a level out of range. (You can call `debug.getinfo` +-- to check whether the level is valid.) -- --- Variable names starting with '(' (open parenthesis) represent variables with --- no known names (internal variables such as loop control variables, and --- variables from chunks saved without debug information). +-- Variable names starting with '(' (open parenthesis) represent variables with no known names +-- (internal variables such as loop control variables, and variables from chunks saved without +-- debug information). -- --- The parameter `f` may also be a function. In that case, `getlocal` returns --- only the name of function parameters. +-- The parameter `f` may also be a function. In that case, `getlocal` returns only the name of +-- function parameters. function debug.getlocal([thread,] f, local) end --- --- Returns the metatable of the given `value` or nil if it does not have --- a metatable. +-- Returns the metatable of the given `value` or nil if it does not have a metatable. function debug.getmetatable(value) end --- @@ -1720,82 +1571,77 @@ function debug.getmetatable(value) end function debug.getregistry() end --- --- This function returns the name and the value of the upvalue with index --- `up` of the function `f`. The function returns nil if there is no upvalue --- with the given index. +-- This function returns the name and the value of the upvalue with index `up` of the function +-- `f`. The function returns nil if there is no upvalue with the given index. -- --- (For Lua functions, upvalues are the external local variables that the --- function uses, and that are consequently included in its closure.) +-- (For Lua functions, upvalues are the external local variables that the function uses, and +-- that are consequently included in its closure.) -- --- For C functions, this function uses the empty string `""` as a name for all --- upvalues. +-- For C functions, this function uses the empty string `""` as a name for all upvalues. -- --- Variable name '`?`' (interrogation mark) represents variables with no known --- names (variables from chunks saved without debug information). +-- Variable name '`?`' (interrogation mark) represents variables with no known names (variables +-- from chunks saved without debug information). function debug.getupvalue(f, up) end --- --- Returns the `n`-th user value associated to the userdata `u` plus a boolean, --- false, if the userdata does not have that value. +-- Returns the `n`-th user value associated to the userdata `u` plus a boolean, false, if the +-- userdata does not have that value. -- -- New in Lua 5.2. function debug.getuservalue(u, n) end --- --- Sets the environment of the given `object` to the given `table`. Returns --- `object`. +-- Sets the environment of the given `object` to the given `table`. Returns `object`. -- -- Deprecated in Lua 5.2. function debug.setfenv(object, table) end --- --- Sets the given function as the debug hook. The string `mask` and the number --- `count` describe when the hook will be called. The string mask may have any --- combination of the following characters, with the given meaning: --- "c": the hook is called every time Lua calls a function; --- "r": the hook is called every time Lua returns from a function; --- "l": the hook is called every time Lua enters a new line of code. +-- Sets the given function as the debug hook. The string `mask` and the number `count` describe +-- when the hook will be called. The string mask may have any combination of the following +-- characters, with the given meaning: +-- +-- * "c": the hook is called every time Lua calls a function; +-- * "r": the hook is called every time Lua returns from a function; +-- * "l": the hook is called every time Lua enters a new line of code. -- --- Moreover, with a `count` different from zero, the hook is called also after --- every `count` instructions. +-- Moreover, with a `count` different from zero, the hook is called also after every `count` +-- instructions. -- -- When called without arguments, `debug.sethook` turns off the hook. -- --- When the hook is called, its first parameter is a string describing --- the event that has triggered its call: `"call"`, `"tail call"`, `"return"`, --- `"line"`, and `"count"`. For line events, the hook also gets the new line --- number as its second parameter. Inside a hook, you can call `getinfo` with --- level 2 to get more information about the running function. (Level 0 is the --- `getinfo` function, and level 1 is the hook function.) +-- When the hook is called, its first parameter is a string describing the event that has +-- triggered its call: `"call"`, `"tail call"`, `"return"`, `"line"`, and `"count"`. For line +-- events, the hook also gets the new line number as its second parameter. Inside a hook, you +-- can call `getinfo` with level 2 to get more information about the running function. (Level +-- 0 is the `getinfo` function, and level 1 is the hook function.) function debug.sethook([thread,] hook, mask [, count]) end --- --- This function assigns the value `value` to the local variable with --- index `local` of the function at level `level` of the stack. The function --- returns nil if there is no local variable with the given index, and raises --- an error when called with a `level` out of range. (You can call `getinfo` --- to check whether the level is valid.) Otherwise, it returns the name of --- the local variable. +-- This function assigns the value `value` to the local variable with index `local` of the +-- function at level `level` of the stack. The function returns nil if there is no local variable +-- with the given index, and raises an error when called with a `level` out of range. (You can +-- call `getinfo` to check whether the level is valid.) Otherwise, it returns the name of the +-- local variable. -- -- See `debug.getlocal` for more information about variable indices and names. function debug.setlocal([thread,] level, local, value) end --- --- Sets the metatable for the given `value` to the given `table` (which --- can be nil). +-- Sets the metatable for the given `value` to the given `table` (which can be nil). function debug.setmetatable(value, table) end --- --- This function assigns the value `value` to the upvalue with index `up` --- of the function `f`. The function returns nil if there is no upvalue with the --- given index. Otherwise, it returns the name of the upvalue. +-- This function assigns the value `value` to the upvalue with index `up` of the function +-- `f`. The function returns nil if there is no upvalue with the given index. Otherwise, it +-- returns the name of the upvalue. -- -- See `debug.getupvalue` for more information about upvalues. function debug.setupvalue(f, up, value) end --- --- Sets the given `value` as the `n`-th user value associated to the given --- `udata`. `udata` must be a full userdata. +-- Sets the given `value` as the `n`-th user value associated to the given `udata`. `udata` +-- must be a full userdata. -- -- Returns `udata`, or nil if the userdata does not have that value. -- @@ -1803,29 +1649,27 @@ function debug.setupvalue(f, up, value) end function debug.setuservalue(udata, value, n) end --- --- If `message` is present but is neither a string nor nil, this function --- returns `message` without further processing. Otherwise, it returns a string --- with a traceback of the call stack. The optional `message` string is appended --- at the beginning of the traceback. An optional `level` number tells at which --- level to start the traceback (default is 1, the function calling +-- If `message` is present but is neither a string nor nil, this function returns `message` +-- without further processing. Otherwise, it returns a string with a traceback of the call +-- stack. The optional `message` string is appended at the beginning of the traceback. An optional +-- `level` number tells at which level to start the traceback (default is 1, the function calling -- `traceback`). function debug.traceback([thread,] [message] [,level]) end --- --- Returns a unique identifier (as a light userdata) for the upvalue numbered --- `n` from the given function. +-- Returns a unique identifier (as a light userdata) for the upvalue numbered `n` from the +-- given function. -- --- These unique identifiers allow a program to check whether different closures --- share upvalues. Lua closures that share an upvalue (that is, that access a --- same external local variable) will return identical ids for those upvalue --- indices. +-- These unique identifiers allow a program to check whether different closures share upvalues. Lua +-- closures that share an upvalue (that is, that access a same external local variable) will +-- return identical ids for those upvalue indices. -- -- New in Lua 5.2. function debug.upvalueid(f, n) end --- --- Make the `n1`-th upvalue of the Lua closure `f1` refer to the `n2`-th upvalue --- of the Lua closure `f2`. +-- Make the `n1`-th upvalue of the Lua closure `f1` refer to the `n2`-th upvalue of the Lua +-- closure `f2`. -- -- New in Lua 5.2. function debug.upvaluejoin(f1, n1, f2, n2) end @@ -1835,26 +1679,22 @@ function debug.upvaluejoin(f1, n1, f2, n2) end -- LPeg. --- --- The matching function. It attempts to match the given pattern against the --- subject string. If the match succeeds, returns the index in the subject of --- the first character after the match, or the captured values (if the pattern --- captured any value). +-- The matching function. It attempts to match the given pattern against the subject string. If +-- the match succeeds, returns the index in the subject of the first character after the match, +-- or the captured values (if the pattern captured any value). -- --- An optional numeric argument `init` makes the match start at that position in --- the subject string. As usual in Lua libraries, a negative value counts from --- the end. +-- An optional numeric argument `init` makes the match start at that position in the subject +-- string. As usual in Lua libraries, a negative value counts from the end. -- --- Unlike typical pattern-matching functions, match works only in anchored mode; --- that is, it tries to match the pattern with a prefix of the given subject --- string (at position `init`), not with an arbitrary substring of the subject. --- So, if we want to find a pattern anywhere in a string, we must either write a --- loop in Lua or write a pattern that matches anywhere. This second approach is --- easy and quite efficient; see examples. +-- Unlike typical pattern-matching functions, match works only in anchored mode; that is, it +-- tries to match the pattern with a prefix of the given subject string (at position `init`), +-- not with an arbitrary substring of the subject. So, if we want to find a pattern anywhere in +-- a string, we must either write a loop in Lua or write a pattern that matches anywhere. This +-- second approach is easy and quite efficient; see examples. function lpeg.match(pattern, subject [, init]) end --- --- If the given value is a pattern, returns the string "pattern". Otherwise --- returns nil. +-- If the given value is a pattern, returns the string "pattern". Otherwise returns nil. function lpeg.type(value) end --- @@ -1862,129 +1702,116 @@ function lpeg.type(value) end function lpeg.version() end --- --- Sets the maximum size for the backtrack stack used by LPeg to track calls and --- choices. Most well-written patterns need little backtrack levels and --- therefore you seldom need to change this maximum; but a few useful patterns --- may need more space. Before changing this maximum you should try to rewrite --- your pattern to avoid the need for extra space. +-- Sets the maximum size for the backtrack stack used by LPeg to track calls and choices. Most +-- well-written patterns need little backtrack levels and therefore you seldom need to change +-- this maximum; but a few useful patterns may need more space. Before changing this maximum +-- you should try to rewrite your pattern to avoid the need for extra space. function lpeg.setmaxstack(max) end --- --- Converts the given value into a proper pattern, according to the following --- rules: +-- Converts the given value into a proper pattern, according to the following rules: +-- -- * If the argument is a pattern, it is returned unmodified. --- * If the argument is a string, it is translated to a pattern that matches --- the string literally. --- * If the argument is a non-negative number n, the result is a pattern that --- matches exactly n characters. --- * If the argument is a negative number -n, the result is a pattern that --- succeeds only if the input string has less than n characters left: --- `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` (see the unary minus --- operation). --- * If the argument is a boolean, the result is a pattern that always --- succeeds or always fails (according to the boolean value), without --- consuming any input. --- * If the argument is a table, it is interpreted as a grammar (see --- Grammars). --- * If the argument is a function, returns a pattern equivalent to a --- match-time capture over the empty string. +-- * If the argument is a string, it is translated to a pattern that matches the string +-- literally. +-- * If the argument is a non-negative number n, the result is a pattern that matches exactly +-- n characters. +-- * If the argument is a negative number -n, the result is a pattern that succeeds only if the +-- input string has less than n characters left: `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` +-- (see the unary minus operation). +-- * If the argument is a boolean, the result is a pattern that always succeeds or always fails +-- (according to the boolean value), without consuming any input. +-- * If the argument is a table, it is interpreted as a grammar (see Grammars). +-- * If the argument is a function, returns a pattern equivalent to a match-time capture over +-- the empty string. function lpeg.P(value) end --- --- Returns a pattern that matches only if the input string at the current --- position is preceded by `patt`. Pattern `patt` must match only strings with --- some fixed length, and it cannot contain captures. +-- Returns a pattern that matches only if the input string at the current position is preceded +-- by `patt`. Pattern `patt` must match only strings with some fixed length, and it cannot +-- contain captures. -- --- Like the and predicate, this pattern never consumes any input, independently --- of success or failure. +-- Like the and predicate, this pattern never consumes any input, independently of success +-- or failure. function lpeg.B(patt) end --- --- Returns a pattern that matches any single character belonging to one of the --- given ranges. Each `range` is a string xy of length 2, representing all --- characters with code between the codes of x and y (both inclusive). +-- Returns a pattern that matches any single character belonging to one of the given ranges. Each +-- `range` is a string xy of length 2, representing all characters with code between the codes +-- of x and y (both inclusive). -- --- As an example, the pattern `lpeg.R("09")` matches any digit, and --- `lpeg.R("az", "AZ")` matches any ASCII letter. +-- As an example, the pattern `lpeg.R("09")` matches any digit, and `lpeg.R("az", "AZ")` +-- matches any ASCII letter. function lpeg.R({range}) end --- --- Returns a pattern that matches any single character that appears in the given --- string. (The S stands for Set.) +-- Returns a pattern that matches any single character that appears in the given string. (The +-- S stands for Set.) -- -- As an example, the pattern `lpeg.S("+-*/")` matches any arithmetic operator. -- --- Note that, if `s` is a character (that is, a string of length 1), then --- `lpeg.P(s)` is equivalent to `lpeg.S(s)` which is equivalent to --- `lpeg.R(s..s)`. Note also that both `lpeg.S("")` and `lpeg.R()` are patterns --- that always fail. +-- Note that, if `s` is a character (that is, a string of length 1), then `lpeg.P(s)` is equivalent +-- to `lpeg.S(s)` which is equivalent to `lpeg.R(s..s)`. Note also that both `lpeg.S("")` and +-- `lpeg.R()` are patterns that always fail. function lpeg.S(string) end --- --- This operation creates a non-terminal (a variable) for a grammar. The created --- non-terminal refers to the rule indexed by `v` in the enclosing grammar. (See --- Grammars for details.) +-- This operation creates a non-terminal (a variable) for a grammar. The created non-terminal +-- refers to the rule indexed by `v` in the enclosing grammar. (See Grammars for details.) function lpeg.V(v) end --- --- Returns a table with patterns for matching some character classes according --- to the current locale. The table has fields named `alnum`, `alpha`, `cntrl`, --- `digit`, `graph`, `lower`, `print`, `punct`, `space`, `upper`, and `xdigit`, --- each one containing a correspondent pattern. Each pattern matches any single --- character that belongs to its class. +-- Returns a table with patterns for matching some character classes according to the current +-- locale. The table has fields named `alnum`, `alpha`, `cntrl`, `digit`, `graph`, `lower`, +-- `print`, `punct`, `space`, `upper`, and `xdigit`, each one containing a correspondent +-- pattern. Each pattern matches any single character that belongs to its class. -- --- If called with an argument `table`, then it creates those fields inside the --- given table and returns that table. +-- If called with an argument `table`, then it creates those fields inside the given table and +-- returns that table. function lpeg.locale([table]) end --- --- Creates a simple capture, which captures the substring of the subject that --- matches `patt`. The captured value is a string. If `patt` has other captures, --- their values are returned after this one. +-- Creates a simple capture, which captures the substring of the subject that matches `patt`. The +-- captured value is a string. If `patt` has other captures, their values are returned after +-- this one. function lpeg.C(patt) end --- --- Creates an argument capture. This pattern matches the empty string and --- produces the value given as the nth extra argument given in the call to --- `lpeg.match`. +-- Creates an argument capture. This pattern matches the empty string and produces the value +-- given as the nth extra argument given in the call to `lpeg.match`. function lpeg.Carg(n) end --- --- Creates a back capture. This pattern matches the empty string and produces --- the values produced by the most recent group capture named `name`. +-- Creates a back capture. This pattern matches the empty string and produces the values produced +-- by the most recent group capture named `name`. -- --- Most recent means the last complete outermost group capture with the given --- name. A Complete capture means that the entire pattern corresponding to the --- capture has matched. An Outermost capture means that the capture is not --- inside another complete capture. +-- Most recent means the last complete outermost group capture with the given name. A Complete +-- capture means that the entire pattern corresponding to the capture has matched. An Outermost +-- capture means that the capture is not inside another complete capture. -- --- In the same way that LPeg does not specify when it evaluates captures, it --- does not specify whether it reuses values previously produced by the group or --- re-evaluates them. +-- In the same way that LPeg does not specify when it evaluates captures, it does not specify +-- whether it reuses values previously produced by the group or re-evaluates them. function lpeg.Cb(name) end --- --- Creates a constant capture. This pattern matches the empty string and --- produces all given values as its captured values. +-- Creates a constant capture. This pattern matches the empty string and produces all given +-- values as its captured values. function lpeg.Cc([value, ...]) end --- --- Creates a fold capture. If patt produces a list of captures C1 C2 ... Cn, --- this capture will produce the value func(...func(func(C1, C2), C3)..., Cn), --- that is, it will fold (or accumulate, or reduce) the captures from `patt` --- using function `func`. +-- Creates a fold capture. If patt produces a list of captures C1 C2 ... Cn, this capture will +-- produce the value func(...func(func(C1, C2), C3)..., Cn), that is, it will fold (or accumulate, +-- or reduce) the captures from `patt` using function `func`. -- --- This capture assumes that `patt` should produce at least one capture with at --- least one value (of any type), which becomes the initial value of an --- accumulator. (If you need a specific initial value, you may prefix a constant --- capture to `patt`.) For each subsequent capture, LPeg calls `func` with this --- accumulator as the first argument and all values produced by the capture as --- extra arguments; the first result from this call becomes the new value for --- the accumulator. The final value of the accumulator becomes the captured --- value. +-- This capture assumes that `patt` should produce at least one capture with at least one value +-- (of any type), which becomes the initial value of an accumulator. (If you need a specific +-- initial value, you may prefix a constant capture to `patt`.) For each subsequent capture, +-- LPeg calls `func` with this accumulator as the first argument and all values produced by +-- the capture as extra arguments; the first result from this call becomes the new value for +-- the accumulator. The final value of the accumulator becomes the captured value. -- --- As an example, the following pattern matches a list of numbers separated by --- commas and returns their addition: +-- As an example, the following pattern matches a list of numbers separated by commas and +-- returns their addition: -- -- -- matches a numeral and captures its numerical value -- number = lpeg.R"09"^1 / tonumber @@ -1999,84 +1826,72 @@ function lpeg.Cc([value, ...]) end function lpeg.Cf(patt, func) end --- --- Creates a group capture. It groups all values returned by `patt` into a --- single capture. The group may be anonymous (if no name is given) or named --- with the given name. +-- Creates a group capture. It groups all values returned by `patt` into a single capture. The +-- group may be anonymous (if no name is given) or named with the given name. -- --- An anonymous group serves to join values from several captures into a single --- capture. A named group has a different behavior. In most situations, a named --- group returns no values at all. Its values are only relevant for a following --- back capture or when used inside a table capture. +-- An anonymous group serves to join values from several captures into a single capture. A named +-- group has a different behavior. In most situations, a named group returns no values at all. Its +-- values are only relevant for a following back capture or when used inside a table capture. function lpeg.Cg(patt [, name]) end --- --- Creates a position capture. It matches the empty string and captures the --- position in the subject where the match occurs. The captured value is a --- number. +-- Creates a position capture. It matches the empty string and captures the position in the +-- subject where the match occurs. The captured value is a number. function lpeg.Cp() end --- --- Creates a substitution capture, which captures the substring of the subject --- that matches `patt`, with substitutions. For any capture inside `patt` with a --- value, the substring that matched the capture is replaced by the capture --- value (which should be a string). The final captured value is the string --- resulting from all replacements. +-- Creates a substitution capture, which captures the substring of the subject that matches +-- `patt`, with substitutions. For any capture inside `patt` with a value, the substring that +-- matched the capture is replaced by the capture value (which should be a string). The final +-- captured value is the string resulting from all replacements. function lpeg.Cs(patt) end --- --- Creates a table capture. This capture returns a table with all values from --- all anonymous captures made by `patt` inside this table in successive integer --- keys, starting at 1. Moreover, for each named capture group created by --- `patt`, the first value of the group is put into the table with the group --- name as its key. The captured value is only the table. +-- Creates a table capture. This capture returns a table with all values from all anonymous +-- captures made by `patt` inside this table in successive integer keys, starting at 1. Moreover, +-- for each named capture group created by `patt`, the first value of the group is put into +-- the table with the group name as its key. The captured value is only the table. function lpeg.Ct(patt) end --- --- Creates a match-time capture. Unlike all other captures, this one is --- evaluated immediately when a match occurs (even if it is part of a larger --- pattern that fails later). It forces the immediate evaluation of all its --- nested captures and then calls `function`. +-- Creates a match-time capture. Unlike all other captures, this one is evaluated immediately +-- when a match occurs (even if it is part of a larger pattern that fails later). It forces +-- the immediate evaluation of all its nested captures and then calls `function`. -- --- The given function gets as arguments the entire subject, the current position --- (after the match of `patt`), plus any capture values produced by `patt`. +-- The given function gets as arguments the entire subject, the current position (after the +-- match of `patt`), plus any capture values produced by `patt`. -- --- The first value returned by `function` defines how the match happens. If the --- call returns a number, the match succeeds and the returned number becomes the --- new current position. (Assuming a subject s and current position i, the --- returned number must be in the range [i, len(s) + 1].) If the call returns --- true, the match succeeds without consuming any input. (So, to return true is --- equivalent to return i.) If the call returns false, nil, or no value, the --- match fails. +-- The first value returned by `function` defines how the match happens. If the call returns a +-- number, the match succeeds and the returned number becomes the new current position. (Assuming +-- a subject s and current position i, the returned number must be in the range [i, len(s) + +-- 1].) If the call returns true, the match succeeds without consuming any input. (So, to return +-- true is equivalent to return i.) If the call returns false, nil, or no value, the match fails. -- --- Any extra values returned by the function become the values produced by the --- capture. +-- Any extra values returned by the function become the values produced by the capture. function lpeg.Cmt(patt, function) end -- LuaFileSystem. --- --- Returns a table with the file attributes corresponding to filepath (or nil --- followed by an error message in case of error). If the second optional --- argument is given and is a string, then only the value of the named attribute --- is returned (this use is equivalent to lfs.attributes(filepath)[aname], but --- the table is not created and only one attribute is retrieved from the O.S.). --- If a table is passed as the second argument, it is filled with attributes and --- returned instead of a new table. The attributes are described as follows; --- attribute mode is a string, all the others are numbers, and the time related --- attributes use the same time reference of os.time: --- dev: on Unix systems, this represents the device that the inode resides on. --- On Windows systems, represents the drive number of the disk containing --- the file --- ino: on Unix systems, this represents the inode number. On Windows systems --- this has no meaning --- mode: string representing the associated protection mode (the values could --- be file, directory, link, socket, named pipe, char device, block --- device or other) +-- Returns a table with the file attributes corresponding to filepath (or nil followed by +-- an error message in case of error). If the second optional argument is given and is a +-- string, then only the value of the named attribute is returned (this use is equivalent to +-- lfs.attributes(filepath)[aname], but the table is not created and only one attribute is +-- retrieved from the O.S.). If a table is passed as the second argument, it is filled with +-- attributes and returned instead of a new table. The attributes are described as follows; +-- attribute mode is a string, all the others are numbers, and the time related attributes use +-- the same time reference of os.time: +-- +-- dev: on Unix systems, this represents the device that the inode resides on. On Windows +-- systems, represents the drive number of the disk containing the file +-- ino: on Unix systems, this represents the inode number. On Windows systems this has no meaning +-- mode: string representing the associated protection mode (the values could be file, +-- directory, link, socket, named pipe, char device, block device or other) -- nlink: number of hard links to the file -- uid: user-id of owner (Unix only, always 0 on Windows) -- gid: group-id of owner (Unix only, always 0 on Windows) --- rdev: on Unix systems, represents the device type, for special file inodes. --- On Windows systems represents the same as dev +-- rdev: on Unix systems, represents the device type, for special file inodes. On Windows +-- systems represents the same as dev -- access: time of last access -- modification: time of last data modification -- change: time of last file status change @@ -2085,10 +1900,10 @@ function lpeg.Cmt(patt, function) end -- blocks: block allocated for file; (Unix only) -- blksize: optimal file system I/O blocksize; (Unix only) -- --- This function uses stat internally thus if the given filepath is a symbolic --- link, it is followed (if it points to another link the chain is followed --- recursively) and the information is about the file it refers to. To obtain --- information about the link itself, see function lfs.symlinkattributes. +-- This function uses stat internally thus if the given filepath is a symbolic link, it is +-- followed (if it points to another link the chain is followed recursively) and the information +-- is about the file it refers to. To obtain information about the link itself, see function +-- lfs.symlinkattributes. function lfs.attributes(filepath [, aname | atable]) end --- @@ -2098,93 +1913,86 @@ function lfs.attributes(filepath [, aname | atable]) end function lfs.chdir(path) end --- --- Creates a lockfile (called lockfile.lfs) in path if it does not exist and --- returns the lock. If the lock already exists checks if it's stale, using the --- second parameter (default for the second parameter is INT_MAX, which in --- practice means the lock will never be stale. To free the the lock call --- lock:free(). +-- Creates a lockfile (called lockfile.lfs) in path if it does not exist and returns the lock. If +-- the lock already exists checks if it's stale, using the second parameter (default for the +-- second parameter is INT_MAX, which in practice means the lock will never be stale. To free +-- the the lock call lock:free(). -- --- In case of any errors it returns nil and the error message. In particular, --- if the lock exists and is not stale it returns the "File exists" message. +-- In case of any errors it returns nil and the error message. In particular, if the lock exists +-- and is not stale it returns the "File exists" message. function lfs.lock_dir(path, [seconds_stale]) end --- --- Returns a string with the current working directory or nil plus an error --- string. +-- Returns a string with the current working directory or nil plus an error string. function lfs.currentdir() end --- --- Lua iterator over the entries of a given directory. Each time the iterator is --- called with dir_obj it returns a directory entry's name as a string, or nil --- if there are no more entries. You can also iterate by calling dir_obj:next(), --- and explicitly close the directory before the iteration finished with --- dir_obj:close(). Raises an error if path is not a directory. +-- Lua iterator over the entries of a given directory. Each time the iterator is called +-- with dir_obj it returns a directory entry's name as a string, or nil if there are no more +-- entries. You can also iterate by calling dir_obj:next(), and explicitly close the directory +-- before the iteration finished with dir_obj:close(). Raises an error if path is not a directory. function lfs.dir(path) end --- --- Locks a file or a part of it. This function works on open files; the file --- handle should be specified as the first argument. The string mode could be --- either r (for a read/shared lock) or w (for a write/exclusive lock). The --- optional arguments start and length can be used to specify a starting point --- and its length; both should be numbers. +-- Locks a file or a part of it. This function works on open files; the file handle should be +-- specified as the first argument. The string mode could be either r (for a read/shared lock) +-- or w (for a write/exclusive lock). The optional arguments start and length can be used to +-- specify a starting point and its length; both should be numbers. -- --- Returns true if the operation was successful; in case of error, it returns --- nil plus an error string. +-- Returns true if the operation was successful; in case of error, it returns nil plus an +-- error string. function lfs.lock(filehandle, mode[, start[, length]]) end --- --- Creates a link. The first argument is the object to link to and the second is --- the name of the link. If the optional third argument is true, the link will --- be a symbolic link (by default, a hard link is created). +-- Creates a link. The first argument is the object to link to and the second is the name of the +-- link. If the optional third argument is true, the link will be a symbolic link (by default, +-- a hard link is created). function lfs.link(old, new[, symlink]) end --- -- Creates a new directory. The argument is the name of the new directory. -- --- Returns true in case of success or nil, an error message and a --- system-dependent error code in case of error. +-- Returns true in case of success or nil, an error message and a system-dependent error code +-- in case of error. function lfs.mkdir(dirname) end --- -- Removes an existing directory. The argument is the name of the directory. -- --- Returns true in case of success or nil, an error message and a --- system-dependent error code in case of error. +-- Returns true in case of success or nil, an error message and a system-dependent error code +-- in case of error. function lfs.rmdir(dirname) end --- --- Sets the writing mode for a file. The mode string can be either "binary" or --- "text". Returns true followed by the previous mode string for the file, or --- nil followed by an error string in case of errors.. On non-Windows platforms, --- where the two modes are identical, setting the mode has no effect, and the --- mode is always returned as binary. +-- Sets the writing mode for a file. The mode string can be either "binary" or "text". Returns +-- true followed by the previous mode string for the file, or nil followed by an error string +-- in case of errors. On non-Windows platforms, where the two modes are identical, setting +-- the mode has no effect, and the mode is always returned as binary. function lfs.setmode(file, mode) end --- --- Identical to lfs.attributes except that it obtains information about the link --- itself (not the file it refers to). It also adds a target field, containing --- the file name that the symlink points to. On Windows this function does not --- yet support links, and is identical to lfs.attributes. +-- Identical to lfs.attributes except that it obtains information about the link itself (not +-- the file it refers to). It also adds a target field, containing the file name that the +-- symlink points to. On Windows this function does not yet support links, and is identical +-- to lfs.attributes. function lfs.symlinkattributes(filepath [, aname]) end --- --- Set access and modification times of a file. This function is a bind to utime --- function. The first argument is the filename, the second argument (atime) is --- the access time, and the third argument (mtime) is the modification time. --- Both times are provided in seconds (which should be generated with Lua --- standard function os.time). If the modification time is omitted, the access --- time provided is used; if both times are omitted, the current time is used. +-- Set access and modification times of a file. This function is a bind to utime function. The +-- first argument is the filename, the second argument (atime) is the access time, and the +-- third argument (mtime) is the modification time. Both times are provided in seconds (which +-- should be generated with Lua standard function os.time). If the modification time is omitted, +-- the access time provided is used; if both times are omitted, the current time is used. -- --- Returns true in case of success or nil, an error message and a --- system-dependent error code in case of error. +-- Returns true in case of success or nil, an error message and a system-dependent error code +-- in case of error. function lfs.touch(filepath [, atime [, mtime]]) end --- --- Unlocks a file or a part of it. This function works on open files; the file --- handle should be specified as the first argument. The optional arguments --- start and length can be used to specify a starting point and its length; both --- should be numbers. +-- Unlocks a file or a part of it. This function works on open files; the file handle should +-- be specified as the first argument. The optional arguments start and length can be used to +-- specify a starting point and its length; both should be numbers. -- --- Returns true if the operation was successful; in case of error, it returns --- nil plus an error string. +-- Returns true if the operation was successful; in case of error, it returns nil plus an +-- error string. function lfs.unlock(filehandle[, start[, length]]) end diff --git a/modules/lua/ta_api b/modules/lua/ta_api index 4d1736b0..de1896ee 100644 --- a/modules/lua/ta_api +++ b/modules/lua/ta_api @@ -8,17 +8,17 @@ ANNOTATION_STANDARD view.ANNOTATION_STANDARD (number, Read-only)\n APPLEEVENT_ODOC events.APPLEEVENT_ODOC (string)\nEmitted when macOS tells Textadept to open a file.\nArguments:\n\n* _`uri`_: The UTF-8-encoded URI to open. ARG_NONE events.ARG_NONE (string)\nEmitted when no command line arguments are passed to Textadept on startup. AUTO_C_CANCELED events.AUTO_C_CANCELED (string)\nEmitted when canceling an autocompletion or user list. -AUTO_C_CHAR_DELETED events.AUTO_C_CHAR_DELETED (string)\nEmitted after deleting a character while an autocompletion or user list is\nactive. -AUTO_C_COMPLETED events.AUTO_C_COMPLETED (string)\nEmitted after inserting an item from an autocompletion list into the\nbuffer.\nArguments:\n\n* _`text`_: The selection's text.\n* _`position`_: The autocompleted word's beginning position. -AUTO_C_SELECTION events.AUTO_C_SELECTION (string)\nEmitted after selecting an item from an autocompletion list, but before\ninserting that item into the buffer.\nAutomatic insertion can be canceled by calling\n`buffer:auto_c_cancel()` before returning from the event handler.\nArguments:\n\n* _`text`_: The selection's text.\n* _`position`_: The autocompleted word's beginning position. -AUTO_C_SELECTION_CHANGE events.AUTO_C_SELECTION_CHANGE (string)\nEmitted as items are highlighted in an autocompletion or user list.\nArguments:\n\n* _`id`_: Either the *id* from `buffer.user_list_show()` or `0` for an\n autocompletion list.\n* _`text`_: The current selection's text.\n* _`position`_: The position the list was displayed at. +AUTO_C_CHAR_DELETED events.AUTO_C_CHAR_DELETED (string)\nEmitted after deleting a character while an autocompletion or user list is active. +AUTO_C_COMPLETED events.AUTO_C_COMPLETED (string)\nEmitted after inserting an item from an autocompletion list into the buffer.\nArguments:\n\n* _`text`_: The selection's text.\n* _`position`_: The autocompleted word's beginning position. +AUTO_C_SELECTION events.AUTO_C_SELECTION (string)\nEmitted after selecting an item from an autocompletion list, but before inserting that\nitem into the buffer.\nAutomatic insertion can be canceled by calling `buffer:auto_c_cancel()` before returning\nfrom the event handler.\nArguments:\n\n* _`text`_: The selection's text.\n* _`position`_: The autocompleted word's beginning position. +AUTO_C_SELECTION_CHANGE events.AUTO_C_SELECTION_CHANGE (string)\nEmitted as items are highlighted in an autocompletion or user list.\nArguments:\n\n* _`id`_: Either the *id* from `buffer.user_list_show()` or `0` for an autocompletion list.\n* _`text`_: The current selection's text.\n* _`position`_: The position the list was displayed at. BSD _G.BSD (bool)\nWhether or not Textadept is running on BSD. BUFFER_AFTER_SWITCH events.BUFFER_AFTER_SWITCH (string)\nEmitted right after switching to another buffer.\nThe buffer being switched to is `buffer`.\nEmitted by `view.goto_buffer()`. BUFFER_BEFORE_SWITCH events.BUFFER_BEFORE_SWITCH (string)\nEmitted right before switching to another buffer.\nThe buffer being switched from is `buffer`.\nEmitted by `view.goto_buffer()`. BUFFER_DELETED events.BUFFER_DELETED (string)\nEmitted after deleting a buffer.\nEmitted by `buffer.delete()`. BUFFER_NEW events.BUFFER_NEW (string)\nEmitted after creating a new buffer.\nThe new buffer is `buffer`.\nEmitted on startup and by `buffer.new()`. -BUILD_OUTPUT events.BUILD_OUTPUT (string)\nEmitted when executing a project's build shell command.\nBy default, output is printed to the message buffer. In order to override\nthis behavior, connect to the event with an index of `1` and return `true`.\nArguments:\n\n* `output`: A line of string output from the command. -CALL_TIP_CLICK events.CALL_TIP_CLICK (string)\nEmitted when clicking on a calltip.\nArguments:\n\n* _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was\n clicked, and 0 otherwise. +BUILD_OUTPUT events.BUILD_OUTPUT (string)\nEmitted when executing a project's build shell command.\nBy default, output is printed to the message buffer. In order to override this behavior,\nconnect to the event with an index of `1` and return `true`.\nArguments:\n\n* `output`: A line of string output from the command. +CALL_TIP_CLICK events.CALL_TIP_CLICK (string)\nEmitted when clicking on a calltip.\nArguments:\n\n* _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was clicked, and\n 0 otherwise. CARETSTICKY_OFF buffer.CARETSTICKY_OFF (number, Read-only)\n CARETSTICKY_ON buffer.CARETSTICKY_ON (number, Read-only)\n CARETSTICKY_WHITESPACE buffer.CARETSTICKY_WHITESPACE (number, Read-only)\n @@ -41,18 +41,18 @@ CLASS textadept.editing.XPM_IMAGES.CLASS (table)\nThe image number for classes. CLEAR keys.CLEAR (string)\nThe key that clears the current key chain.\nIt cannot be part of a key chain.\nThe default value is `'esc'` for the `Esc` key. COMMAND_TEXT_CHANGED events.COMMAND_TEXT_CHANGED (string)\nEmitted when the text in the command entry changes.\n`ui.command_entry:get_text()` returns the current text. COMMENT lexer.COMMENT (string)\nThe token name for comment tokens. -COMPILE_OUTPUT events.COMPILE_OUTPUT (string)\nEmitted when executing a language's compile shell command.\nBy default, compiler output is printed to the message buffer. In order to\noverride this behavior, connect to the event with an index of `1` and\nreturn `true`.\nArguments:\n\n* `output`: A line of string output from the command.\n* `ext_or_lexer`: The file extension or lexer name associated with the\n executed compile command. +COMPILE_OUTPUT events.COMPILE_OUTPUT (string)\nEmitted when executing a language's compile shell command.\nBy default, compiler output is printed to the message buffer. In order to override this\nbehavior, connect to the event with an index of `1` and return `true`.\nArguments:\n\n* `output`: A line of string output from the command.\n* `ext_or_lexer`: The file extension or lexer name associated with the executed compile\n command. CONSTANT lexer.CONSTANT (string)\nThe token name for constant tokens. -CSI events.CSI (string)\nEmitted when the terminal version receives an unrecognized CSI sequence.\nArguments:\n\n* _`cmd`_: The 24-bit CSI command value. The lowest byte contains the\n command byte. The second lowest byte contains the leading byte, if any\n (e.g. '?'). The third lowest byte contains the intermediate byte, if any\n (e.g. '$').\n* _`args`_: Table of numeric arguments of the CSI sequence. +CSI events.CSI (string)\nEmitted when the terminal version receives an unrecognized CSI sequence.\nArguments:\n\n* _`cmd`_: The 24-bit CSI command value. The lowest byte contains the command byte. The\n second lowest byte contains the leading byte, if any (e.g. '?'). The third lowest byte\n contains the intermediate byte, if any (e.g. '$').\n* _`args`_: Table of numeric arguments of the CSI sequence. CURSES _G.CURSES (bool)\nWhether or not Textadept is running in a terminal.\nCurses feature incompatibilities are listed in the Appendix. CURSORARROW view.CURSORARROW (number, Read-only)\n CURSORNORMAL view.CURSORNORMAL (number, Read-only)\n CURSORREVERSEARROW view.CURSORREVERSEARROW (number, Read-only)\n CURSORWAIT view.CURSORWAIT (number, Read-only)\n DEFAULT lexer.DEFAULT (string)\nThe token name for default tokens. -DOUBLE_CLICK events.DOUBLE_CLICK (string)\nEmitted after double-clicking the mouse button.\nArguments:\n\n* _`position`_: The position double-clicked.\n* _`line`_: The line number of the position double-clicked.\n* _`modifiers`_: A bit-mask of any modifier keys held down:\n `view.MOD_CTRL`, `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n On macOS, the Command modifier key is reported as `view.MOD_CTRL` and\n Ctrl is `view.MOD_META`.\n Note: If you set `view.rectangular_selection_modifier` to\n `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n and "Alt" due to a Scintilla limitation with GTK. -DWELL_END events.DWELL_END (string)\nEmitted after `DWELL_START` when the user moves the mouse, presses a key,\nor scrolls the view.\nArguments:\n\n* _`position`_: The position closest to *x* and *y*.\n* _`x`_: The x-coordinate of the mouse in the view.\n* _`y`_: The y-coordinate of the mouse in the view. -DWELL_START events.DWELL_START (string)\nEmitted when the mouse is stationary for `view.mouse_dwell_time`\nmilliseconds.\nArguments:\n\n* _`position`_: The position closest to *x* and *y*.\n* _`x`_: The x-coordinate of the mouse in the view.\n* _`y`_: The y-coordinate of the mouse in the view. +DOUBLE_CLICK events.DOUBLE_CLICK (string)\nEmitted after double-clicking the mouse button.\nArguments:\n\n* _`position`_: The position double-clicked.\n* _`line`_: The line number of the position double-clicked.\n* _`modifiers`_: A bit-mask of any modifier keys held down: `view.MOD_CTRL`,\n `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. On macOS, the Command modifier\n key is reported as `view.MOD_CTRL` and Ctrl is `view.MOD_META`. Note: If you set\n `view.rectangular_selection_modifier` to `view.MOD_CTRL`, the "Control" modifier is\n reported as *both* "Control" and "Alt" due to a Scintilla limitation with GTK. +DWELL_END events.DWELL_END (string)\nEmitted after `DWELL_START` when the user moves the mouse, presses a key, or scrolls the view.\nArguments:\n\n* _`position`_: The position closest to *x* and *y*.\n* _`x`_: The x-coordinate of the mouse in the view.\n* _`y`_: The y-coordinate of the mouse in the view. +DWELL_START events.DWELL_START (string)\nEmitted when the mouse is stationary for `view.mouse_dwell_time` milliseconds.\nArguments:\n\n* _`position`_: The position closest to *x* and *y*.\n* _`x`_: The x-coordinate of the mouse in the view.\n* _`y`_: The y-coordinate of the mouse in the view. EDGE_BACKGROUND view.EDGE_BACKGROUND (number, Read-only)\n EDGE_LINE view.EDGE_LINE (number, Read-only)\n EDGE_MULTILINE view.EDGE_MULTILINE (number, Read-only)\n @@ -63,19 +63,19 @@ EOL_LF buffer.EOL_LF (number, Read-only)\n ERROR events.ERROR (string)\nEmitted when an error occurs.\nArguments:\n\n* _`text`_: The error message text. ERROR lexer.ERROR (string)\nThe token name for error tokens. FILE_AFTER_RELOAD events.FILE_AFTER_RELOAD (string)\nEmitted after reloading the current file.\nEmitted by `buffer:reload()`. -FILE_AFTER_SAVE events.FILE_AFTER_SAVE (string)\nEmitted right after saving a file to disk.\nEmitted by `buffer:save()` and `buffer:save_as()`.\nArguments:\n\n* _`filename`_: The filename of the file being saved.\n* _`saved_as`_: Whether or not the file was saved under a different\n filename. +FILE_AFTER_SAVE events.FILE_AFTER_SAVE (string)\nEmitted right after saving a file to disk.\nEmitted by `buffer:save()` and `buffer:save_as()`.\nArguments:\n\n* _`filename`_: The filename of the file being saved.\n* _`saved_as`_: Whether or not the file was saved under a different filename. FILE_BEFORE_RELOAD events.FILE_BEFORE_RELOAD (string)\nEmitted before reloading the current file.\nEmitted by `buffer:reload()`. FILE_BEFORE_SAVE events.FILE_BEFORE_SAVE (string)\nEmitted right before saving a file to disk.\nEmitted by `buffer:save()`.\nArguments:\n\n* _`filename`_: The filename of the file being saved. -FILE_CHANGED events.FILE_CHANGED (string)\nEmitted when Textadept detects that an open file was modified externally.\nWhen connecting to this event, connect with an index of 1 in order to\noverride the default prompt to reload the file.\nArguments:\n\n* _`filename`_: The filename externally modified. +FILE_CHANGED events.FILE_CHANGED (string)\nEmitted when Textadept detects that an open file was modified externally.\nWhen connecting to this event, connect with an index of 1 in order to override the default\nprompt to reload the file.\nArguments:\n\n* _`filename`_: The filename externally modified. FILE_OPENED events.FILE_OPENED (string)\nEmitted after opening a file in a new buffer.\nEmitted by `io.open_file()`.\nArguments:\n\n* _`filename`_: The opened file's filename. FIND events.FIND (string)\nEmitted to find text via the Find & Replace Pane.\nArguments:\n\n* _`text`_: The text to search for.\n* _`next`_: Whether or not to search forward. FIND_MATCHCASE buffer.FIND_MATCHCASE (number, Read-only)\n FIND_REGEXP buffer.FIND_REGEXP (number, Read-only)\n -FIND_RESULT_FOUND events.FIND_RESULT_FOUND (string)\nEmitted when a result is found. It is selected and has been scrolled into\nview.\nArguments:\n\n* _`find_text`_: The text originally searched for. -FIND_TEXT_CHANGED events.FIND_TEXT_CHANGED (string)\nEmitted when the text in the "Find" field of the Find & Replace Pane\nchanges.\n`ui.find.find_entry_text` contains the current text. +FIND_RESULT_FOUND events.FIND_RESULT_FOUND (string)\nEmitted when a result is found. It is selected and has been scrolled into view.\nArguments:\n\n* _`find_text`_: The text originally searched for. +FIND_TEXT_CHANGED events.FIND_TEXT_CHANGED (string)\nEmitted when the text in the "Find" field of the Find & Replace Pane changes.\n`ui.find.find_entry_text` contains the current text. FIND_WHOLEWORD buffer.FIND_WHOLEWORD (number, Read-only)\n FIND_WORDSTART buffer.FIND_WORDSTART (number, Read-only)\n -FIND_WRAPPED events.FIND_WRAPPED (string)\nEmitted when a text search wraps (passes through the beginning of the\nbuffer), either from bottom to top (when searching for a next occurrence),\nor from top to bottom (when searching for a previous occurrence).\nThis is useful for implementing a more visual or audible notice when a\nsearch wraps in addition to the statusbar message. +FIND_WRAPPED events.FIND_WRAPPED (string)\nEmitted when a text search wraps (passes through the beginning of the buffer), either\nfrom bottom to top (when searching for a next occurrence), or from top to bottom (when\nsearching for a previous occurrence).\nThis is useful for implementing a more visual or audible notice when a search wraps in\naddition to the statusbar message. FOCUS events.FOCUS (string)\nEmitted when Textadept receives focus.\nThis event is never emitted when Textadept is running in the terminal. FOLDACTION_CONTRACT view.FOLDACTION_CONTRACT (number, Read-only)\n FOLDACTION_EXPAND view.FOLDACTION_EXPAND (number, Read-only)\n @@ -98,9 +98,9 @@ FOLD_BLANK lexer.FOLD_BLANK (number)\nFlag indicating that the line is blank. FOLD_HEADER lexer.FOLD_HEADER (number)\nFlag indicating the line is fold point. FUNCTION lexer.FUNCTION (string)\nThe token name for function tokens. IDENTIFIER lexer.IDENTIFIER (string)\nThe token name for identifier tokens. -INDICATOR_CLICK events.INDICATOR_CLICK (string)\nEmitted when clicking the mouse on text that has an indicator present.\nArguments:\n\n* _`position`_: The clicked text's position.\n* _`modifiers`_: A bit-mask of any modifier keys held down:\n `view.MOD_CTRL`, `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n On macOS, the Command modifier key is reported as `view.MOD_CTRL` and\n Ctrl is `view.MOD_META`.\n Note: If you set `view.rectangular_selection_modifier` to\n `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n and "Alt" due to a Scintilla limitation with GTK. +INDICATOR_CLICK events.INDICATOR_CLICK (string)\nEmitted when clicking the mouse on text that has an indicator present.\nArguments:\n\n* _`position`_: The clicked text's position.\n* _`modifiers`_: A bit-mask of any modifier keys held down: `view.MOD_CTRL`,\n `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. On macOS, the Command modifier\n key is reported as `view.MOD_CTRL` and Ctrl is `view.MOD_META`. Note: If you set\n `view.rectangular_selection_modifier` to `view.MOD_CTRL`, the "Control" modifier is\n reported as *both* "Control" and "Alt" due to a Scintilla limitation with GTK. INDICATOR_MAX buffer.INDICATOR_MAX (number, Read-only)\n -INDICATOR_RELEASE events.INDICATOR_RELEASE (string)\nEmitted when releasing the mouse after clicking on text that has an\nindicator present.\nArguments:\n\n* _`position`_: The clicked text's position. +INDICATOR_RELEASE events.INDICATOR_RELEASE (string)\nEmitted when releasing the mouse after clicking on text that has an indicator present.\nArguments:\n\n* _`position`_: The clicked text's position. INDIC_BOX view.INDIC_BOX (number, Read-only)\n INDIC_BRACEMATCH textadept.editing.INDIC_BRACEMATCH (number)\nThe matching brace highlight indicator number. INDIC_COMPOSITIONTHICK view.INDIC_COMPOSITIONTHICK (number, Read-only)\n @@ -133,15 +133,15 @@ IV_LOOKFORWARD view.IV_LOOKFORWARD (number, Read-only)\n IV_NONE view.IV_NONE (number, Read-only)\n IV_REAL view.IV_REAL (number, Read-only)\n KEYPRESS events.KEYPRESS (string)\nEmitted when pressing a key.\nIf any handler returns `true`, the key is not inserted into the buffer.\nArguments:\n\n* _`code`_: The numeric key code.\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down.\n* _`cmd`_: The "Command" modifier key on macOS is held down.\n* _`caps_lock`_: The "Caps Lock" modifier is on. -KEYSYMS keys.KEYSYMS (table)\nLookup table for string representations of key codes higher than 255.\nKey codes can be identified by temporarily uncommenting the `print()`\nstatements in *core/keys.lua*.\nRecognized codes are: esc, \b, \t, \\n, down, up, left, right, home, end,\npgup, pgdn, del, ins, and f1-f12.\nThe GUI version also recognizes: kpenter, kphome, kpend, kpleft, kpup,\nkpright, kpdown, kppgup, kppgdn, kpmul, kpadd, kpsub, kpdiv, kpdec, and\nkp0-kp9. +KEYSYMS keys.KEYSYMS (table)\nLookup table for string representations of key codes higher than 255.\nKey codes can be identified by temporarily uncommenting the `print()` statements in\n*core/keys.lua*.\nRecognized codes are: esc, \b, \t, \\n, down, up, left, right, home, end, pgup, pgdn, del,\nins, and f1-f12.\nThe GUI version also recognizes: kpenter, kphome, kpend, kpleft, kpup, kpright, kpdown,\nkppgup, kppgdn, kpmul, kpadd, kpsub, kpdiv, kpdec, and kp0-kp9. KEYWORD lexer.KEYWORD (string)\nThe token name for keyword tokens. LABEL lexer.LABEL (string)\nThe token name for label tokens. -LEXER_LOADED events.LEXER_LOADED (string)\nEmitted after loading a language lexer.\nThis is useful for overriding a language module's key bindings or other\nproperties since the module is not loaded when Textadept starts.\nArguments:\n\n* _`name`_: The language lexer's name. +LEXER_LOADED events.LEXER_LOADED (string)\nEmitted after loading a language lexer.\nThis is useful for overriding a language module's key bindings or other properties since\nthe module is not loaded when Textadept starts.\nArguments:\n\n* _`name`_: The language lexer's name. LINUX _G.LINUX (bool)\nWhether or not Textadept is running on Linux. MARGINOPTION_NONE view.MARGINOPTION_NONE (number, Read-only)\n MARGINOPTION_SUBLINESELECT view.MARGINOPTION_SUBLINESELECT (number, Read-only)\n MARGIN_BACK view.MARGIN_BACK (number, Read-only)\n -MARGIN_CLICK events.MARGIN_CLICK (string)\nEmitted when clicking the mouse inside a sensitive margin.\nArguments:\n\n* _`margin`_: The margin number clicked.\n* _`position`_: The beginning position of the clicked margin's line.\n* _`modifiers`_: A bit-mask of any modifier keys held down:\n `view.MOD_CTRL`, `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`.\n On macOS, the Command modifier key is reported as `view.MOD_CTRL` and\n Ctrl is `view.MOD_META`.\n Note: If you set `view.rectangular_selection_modifier` to\n `view.MOD_CTRL`, the "Control" modifier is reported as *both* "Control"\n and "Alt" due to a Scintilla limitation with GTK. +MARGIN_CLICK events.MARGIN_CLICK (string)\nEmitted when clicking the mouse inside a sensitive margin.\nArguments:\n\n* _`margin`_: The margin number clicked.\n* _`position`_: The beginning position of the clicked margin's line.\n* _`modifiers`_: A bit-mask of any modifier keys held down: `view.MOD_CTRL`,\n `view.MOD_SHIFT`, `view.MOD_ALT`, and `view.MOD_META`. On macOS, the Command modifier\n key is reported as `view.MOD_CTRL` and Ctrl is `view.MOD_META`. Note: If you set\n `view.rectangular_selection_modifier` to `view.MOD_CTRL`, the "Control" modifier is\n reported as *both* "Control" and "Alt" due to a Scintilla limitation with GTK. MARGIN_COLOR view.MARGIN_COLOR (number, Read-only)\n MARGIN_FORE view.MARGIN_FORE (number, Read-only)\n MARGIN_NUMBER view.MARGIN_NUMBER (number, Read-only)\n @@ -194,14 +194,14 @@ MARK_VERTICALBOOKMARK view.MARK_VERTICALBOOKMARK (number, Read-only)\n MARK_VLINE view.MARK_VLINE (number, Read-only)\n MARK_WARNING textadept.run.MARK_WARNING (number)\nThe run or compile warning marker number. MASK_FOLDERS view.MASK_FOLDERS (number, Read-only)\n -MENU_CLICKED events.MENU_CLICKED (string)\nEmitted after selecting a menu item.\nArguments:\n\n* _`menu_id`_: The numeric ID of the menu item, which was defined in\n `ui.menu()`. +MENU_CLICKED events.MENU_CLICKED (string)\nEmitted after selecting a menu item.\nArguments:\n\n* _`menu_id`_: The numeric ID of the menu item, which was defined in `ui.menu()`. METHOD textadept.editing.XPM_IMAGES.METHOD (table)\nThe image number for methods. MOD_ALT view.MOD_ALT (number, Read-only)\n MOD_CTRL view.MOD_CTRL (number, Read-only)\n MOD_META view.MOD_META (number, Read-only)\n MOD_SHIFT view.MOD_SHIFT (number, Read-only)\n MOD_SUPER view.MOD_SUPER (number, Read-only)\n -MOUSE events.MOUSE (string)\nEmitted by the terminal version for an unhandled mouse event.\nA handler should return `true` if it handled the event. Otherwise Textadept\nwill try again. (This side effect for a `false` or `nil` return is useful\nfor sending the original mouse event to a different view that a handler\nhas switched to.)\nArguments:\n\n* _`event`_: The mouse event: `view.MOUSE_PRESS`, `view.MOUSE_DRAG`, or\n `view.MOUSE_RELEASE`.\n* _`button`_: The mouse button number.\n* _`y`_: The y-coordinate of the mouse event, starting from 1.\n* _`x`_: The x-coordinate of the mouse event, starting from 1.\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down. +MOUSE events.MOUSE (string)\nEmitted by the terminal version for an unhandled mouse event.\nA handler should return `true` if it handled the event. Otherwise Textadept will try again.\n(This side effect for a `false` or `nil` return is useful for sending the original mouse\nevent to a different view that a handler has switched to.)\nArguments:\n\n* _`event`_: The mouse event: `view.MOUSE_PRESS`, `view.MOUSE_DRAG`, or `view.MOUSE_RELEASE`.\n* _`button`_: The mouse button number.\n* _`y`_: The y-coordinate of the mouse event, starting from 1.\n* _`x`_: The x-coordinate of the mouse event, starting from 1.\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down. MOUSE_DRAG view.MOUSE_DRAG (number, Read-only)\n MOUSE_PRESS view.MOUSE_PRESS (number, Read-only)\n MOUSE_RELEASE view.MOUSE_RELEASE (number, Read-only)\n @@ -217,22 +217,22 @@ ORDER_PERFORMSORT buffer.ORDER_PERFORMSORT (number, Read-only)\n ORDER_PRESORTED buffer.ORDER_PRESORTED (number, Read-only)\n OSX _G.OSX (bool)\nWhether or not Textadept is running on macOS as a GUI application. PREPROCESSOR lexer.PREPROCESSOR (string)\nThe token name for preprocessor tokens. -QUIT events.QUIT (string)\nEmitted when quitting Textadept.\nWhen connecting to this event, connect with an index of 1 if the handler\nneeds to run before Textadept closes all open buffers. If a handler returns\n`true`, Textadept does not quit. It is not recommended to return `false`\nfrom a quit handler, as that may interfere with Textadept's normal shutdown\nprocedure.\nEmitted by `quit()`. +QUIT events.QUIT (string)\nEmitted when quitting Textadept.\nWhen connecting to this event, connect with an index of 1 if the handler needs to run\nbefore Textadept closes all open buffers. If a handler returns `true`, Textadept does not\nquit. It is not recommended to return `false` from a quit handler, as that may interfere\nwith Textadept's normal shutdown procedure.\nEmitted by `quit()`. REGEX lexer.REGEX (string)\nThe token name for regex tokens. REPLACE events.REPLACE (string)\nEmitted to replace selected (found) text.\nArguments:\n\n* _`text`_: The replacement text. REPLACE_ALL events.REPLACE_ALL (string)\nEmitted to replace all occurrences of found text.\nArguments:\n\n* _`find_text`_: The text to search for.\n* _`repl_text`_: The replacement text. -RESET_AFTER events.RESET_AFTER (string)\nEmitted after resetting Textadept's Lua state.\nEmitted by `reset()`.\nArguments:\n\n* _`persist`_: Table of data persisted by `events.RESET_BEFORE`. All\n handlers will have access to this same table. -RESET_BEFORE events.RESET_BEFORE (string)\nEmitted before resetting Textadept's Lua state.\nEmitted by `reset()`.\nArguments:\n\n* _`persist`_: Table to store persistent data in for use by\n `events.RESET_AFTER`. All handlers will have access to this same table. +RESET_AFTER events.RESET_AFTER (string)\nEmitted after resetting Textadept's Lua state.\nEmitted by `reset()`.\nArguments:\n\n* _`persist`_: Table of data persisted by `events.RESET_BEFORE`. All handlers will have\n access to this same table. +RESET_BEFORE events.RESET_BEFORE (string)\nEmitted before resetting Textadept's Lua state.\nEmitted by `reset()`.\nArguments:\n\n* _`persist`_: Table to store persistent data in for use by `events.RESET_AFTER`. All\n handlers will have access to this same table. RESUME events.RESUME (string)\nEmitted when resuming Textadept from a suspended state.\nThis event is only emitted by the terminal version. -RUN_OUTPUT events.RUN_OUTPUT (string)\nEmitted when executing a language's run shell command.\nBy default, output is printed to the message buffer. In order to override\nthis behavior, connect to the event with an index of `1` and return `true`.\nArguments:\n\n* `output`: A line of string output from the command.\n* `ext_or_lexer`: The file extension or lexer name associated with the\n executed run command. +RUN_OUTPUT events.RUN_OUTPUT (string)\nEmitted when executing a language's run shell command.\nBy default, output is printed to the message buffer. In order to override this behavior,\nconnect to the event with an index of `1` and return `true`.\nArguments:\n\n* `output`: A line of string output from the command.\n* `ext_or_lexer`: The file extension or lexer name associated with the executed run command. SAVE_POINT_LEFT events.SAVE_POINT_LEFT (string)\nEmitted after leaving a save point. SAVE_POINT_REACHED events.SAVE_POINT_REACHED (string)\nEmitted after reaching a save point. SEL_LINES buffer.SEL_LINES (number, Read-only)\n SEL_RECTANGLE buffer.SEL_RECTANGLE (number, Read-only)\n SEL_STREAM buffer.SEL_STREAM (number, Read-only)\n SEL_THIN buffer.SEL_THIN (number, Read-only)\n -SESSION_LOAD events.SESSION_LOAD (string)\nEmitted when loading a session.\nArguments:\n\n* `session`: Table of session data to load. All handlers will have access\n to this same table. -SESSION_SAVE events.SESSION_SAVE (string)\nEmitted when saving a session.\nArguments:\n\n* `session`: Table of session data to save. All handlers will have access\n to this same table, and Textadept's default handler reserves the use of\n some keys.\n Note that functions, userdata, and circular table values cannot be saved.\n The latter case is not recognized at all, so beware. +SESSION_LOAD events.SESSION_LOAD (string)\nEmitted when loading a session.\nArguments:\n\n* `session`: Table of session data to load. All handlers will have access to this same table. +SESSION_SAVE events.SESSION_SAVE (string)\nEmitted when saving a session.\nArguments:\n\n* `session`: Table of session data to save. All handlers will have access to this same\n table, and Textadept's default handler reserves the use of some keys.\n Note that functions, userdata, and circular table values cannot be saved. The latter\n case is not recognized at all, so beware. SHOW_ALL_TABS ui.SHOW_ALL_TABS (number)\n SIGNAL textadept.editing.XPM_IMAGES.SIGNAL (table)\nThe image number for signals. SLOT textadept.editing.XPM_IMAGES.SLOT (table)\nThe image number for slots. @@ -247,11 +247,11 @@ STYLE_FOLDDISPLAYTEXT view.STYLE_FOLDDISPLAYTEXT (number, Read-only)\n STYLE_INDENTGUIDE view.STYLE_INDENTGUIDE (number, Read-only)\n STYLE_LINENUMBER view.STYLE_LINENUMBER (number, Read-only)\n STYLE_MAX view.STYLE_MAX (number, Read-only)\n -SUSPEND events.SUSPEND (string)\nEmitted when suspending Textadept. If any handler returns `true`, Textadept\ndoes not suspend.\nThis event is only emitted by the terminal version. -TAB_CLICKED events.TAB_CLICKED (string)\nEmitted when the user clicks on a buffer tab.\nWhen connecting to this event, connect with an index of 1 if the handler\nneeds to run before Textadept switches between buffers.\nNote that Textadept always displays a context menu on right-click.\nArguments:\n\n* _`index`_: The numeric index of the clicked tab.\n* _`button`_: The mouse button number that was clicked, either `1` (left\n button), `2` (middle button), `3` (right button), `4` (wheel up), or `5`\n (wheel down).\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down.\n* _`cmd`_: The "Command" modifier key on macOS is held down. +SUSPEND events.SUSPEND (string)\nEmitted when suspending Textadept. If any handler returns `true`, Textadept does not suspend.\nThis event is only emitted by the terminal version. +TAB_CLICKED events.TAB_CLICKED (string)\nEmitted when the user clicks on a buffer tab.\nWhen connecting to this event, connect with an index of 1 if the handler needs to run\nbefore Textadept switches between buffers.\nNote that Textadept always displays a context menu on right-click.\nArguments:\n\n* _`index`_: The numeric index of the clicked tab.\n* _`button`_: The mouse button number that was clicked, either `1` (left button), `2`\n (middle button), `3` (right button), `4` (wheel up), or `5` (wheel down).\n* _`shift`_: The "Shift" modifier key is held down.\n* _`ctrl`_: The "Control" modifier key is held down.\n* _`alt`_: The "Alt"/"Option" modifier key is held down.\n* _`cmd`_: The "Command" modifier key on macOS is held down. TD_LONGARROW view.TD_LONGARROW (number, Read-only)\n TD_STRIKEOUT view.TD_STRIKEOUT (number, Read-only)\n -TEST_OUTPUT events.TEST_OUTPUT (string)\nEmitted when executing a project's shell command for running tests.\nBy default, output is printed to the message buffer. In order to override\nthis behavior, connect to the event with an index of `1` and return `true`.\nArguments:\n\n* `output`: A line of string output from the command. +TEST_OUTPUT events.TEST_OUTPUT (string)\nEmitted when executing a project's shell command for running tests.\nBy default, output is printed to the message buffer. In order to override this behavior,\nconnect to the event with an index of `1` and return `true`.\nArguments:\n\n* `output`: A line of string output from the command. TIME_FOREVER view.TIME_FOREVER (number, Read-only)\n TYPE lexer.TYPE (string)\nThe token name for type tokens. TYPEDEF textadept.editing.XPM_IMAGES.TYPEDEF (table)\nThe image number for type definitions. @@ -296,227 +296,227 @@ WS_VISIBLEALWAYS view.WS_VISIBLEALWAYS (number, Read-only)\n WS_VISIBLEONLYININDENT view.WS_VISIBLEONLYININDENT (number, Read-only)\n XPM_IMAGES textadept.editing.XPM_IMAGES (table)\nMap of image names to registered image numbers. ZOOM events.ZOOM (string)\nEmitted after changing `view.zoom`.\nEmitted by `view.zoom_in()` and `view.zoom_out()`. -_BUFFERS _G._BUFFERS (table)\nTable of all open buffers in Textadept.\nNumeric keys have buffer values and buffer keys have their associated numeric\nkeys.\n@see _G.buffer +_BUFFERS _G._BUFFERS (table)\nTable of all open buffers in Textadept.\nNumeric keys have buffer values and buffer keys have their associated numeric keys.\n@see _G.buffer _CHARSET _G._CHARSET (string)\nThe filesystem's character encoding.\nThis is used when working with files. _G _G._G (module)\nExtends Lua's _G table to provide extra functions and fields for Textadept. _HOME _G._HOME (string)\nThe path to Textadept's home, or installation, directory. -_L _G._L (module)\nMap of all messages used by Textadept to their localized form.\nIf the table does not contain the localized version of a given message, it\nreturns a string that starts with "No Localization:" via a metamethod.\nNote: the terminal version ignores any "_" mnemonics the GUI version would\nuse. -_M _G._M (module)\nA table of loaded Textadept language modules.\n\nLanguage modules are a special kind of module that Textadept automatically\nloads when editing source code in a particular programming language. The only\nthing "special" about them is they are named after a lexer. Otherwise they\nare plain Lua modules. The *~/.textadept/modules/* directory houses language\nmodules (along with other modules).\n\nA language module is designed to provide extra functionality for a single\nprogramming language. Some examples of what language modules can do:\n\n * Specify block comment syntax for lines of code\n * Define compile and run commands for source files\n * Set language-specific editor properties like indentation rules\n * Specify code autocompletion routines\n * Declare snippets\n * Define commands and key bindings for them\n * Add to the top-level menu or right-click editor context menu\n\nExamples of these features are described in the sections below. +_L _G._L (module)\nMap of all messages used by Textadept to their localized form.\nIf the table does not contain the localized version of a given message, it returns a string\nthat starts with "No Localization:" via a metamethod.\nNote: the terminal version ignores any "_" mnemonics the GUI version would use. +_M _G._M (module)\nA table of loaded Textadept language modules.\n\nLanguage modules are a special kind of module that Textadept automatically loads when editing\nsource code in a particular programming language. The only thing "special" about them is they\nare named after a lexer. Otherwise they are plain Lua modules. The *~/.textadept/modules/*\ndirectory houses language modules (along with other modules).\n\nA language module is designed to provide extra functionality for a single programming\nlanguage. Some examples of what language modules can do:\n\n * Specify block comment syntax for lines of code\n * Define compile and run commands for source files\n * Set language-specific editor properties like indentation rules\n * Specify code autocompletion routines\n * Declare snippets\n * Define commands and key bindings for them\n * Add to the top-level menu or right-click editor context menu\n\nExamples of these features are described in the sections below. _RELEASE _G._RELEASE (string)\nThe Textadept release version string. -_SCINTILLA _G._SCINTILLA (module)\nScintilla constants, functions, and properties.\nDo not modify anything in this module. Doing so will have unpredictable\nconsequences. -_USERHOME _G._USERHOME (string)\nThe path to the user's *~/.textadept/* directory, where all preferences and\nuser-data is stored.\nOn Windows machines *~/* is the value of the "USERHOME" environment\nvariable (typically *C:\Users\username\\* or\n*C:\Documents and Settings\username\\*). On Linux, BSD, and macOS\nmachines *~/* is the value of "$HOME" (typically */home/username/* and\n*/Users/username/* respectively). -_VIEWS _G._VIEWS (table)\nTable of all views in Textadept.\nNumeric keys have view values and view keys have their associated numeric\nkeys.\n@see _G.view -_print ui._print(buffer_type, ...)\nPrints the given string messages to the buffer of string type *buffer_type*.\nOpens a new buffer for printing messages to if necessary. If the message\nbuffer is already open in a view, the message is printed to that view.\nOtherwise the view is split (unless `ui.tabs` is `true`) and the message\nbuffer is displayed before being printed to.\n@param buffer_type String type of message buffer.\n@param ... Message strings.\n@usage ui._print(_L['[Message Buffer]'], message) -abspath lfs.abspath(filename, prefix)\nReturns the absolute path to string *filename*.\n*prefix* or `lfs.currentdir()` is prepended to a relative filename. The\nreturned path is not guaranteed to exist.\n@param filename The relative or absolute path to a file.\n@param prefix Optional prefix path prepended to a relative filename.\n@return string absolute path +_SCINTILLA _G._SCINTILLA (module)\nScintilla constants, functions, and properties.\nDo not modify anything in this module. Doing so will have unpredictable consequences. +_USERHOME _G._USERHOME (string)\nThe path to the user's *~/.textadept/* directory, where all preferences and user-data\nis stored.\nOn Windows machines *~/* is the value of the "USERHOME" environment variable (typically\n*C:\Users\username\\* or *C:\Documents and Settings\username\\*). On Linux, BSD, and macOS\nmachines *~/* is the value of "$HOME" (typically */home/username/* and */Users/username/*\nrespectively). +_VIEWS _G._VIEWS (table)\nTable of all views in Textadept.\nNumeric keys have view values and view keys have their associated numeric keys.\n@see _G.view +_print ui._print(buffer_type, ...)\nPrints the given string messages to the buffer of string type *buffer_type*.\nOpens a new buffer for printing messages to if necessary. If the message buffer is already\nopen in a view, the message is printed to that view. Otherwise the view is split (unless\n`ui.tabs` is `true`) and the message buffer is displayed before being printed to.\n@param buffer_type String type of message buffer.\n@param ... Message strings.\n@usage ui._print(_L['[Message Buffer]'], message) +abspath lfs.abspath(filename, prefix)\nReturns the absolute path to string *filename*.\n*prefix* or `lfs.currentdir()` is prepended to a relative filename. The returned path is\nnot guaranteed to exist.\n@param filename The relative or absolute path to a file.\n@param prefix Optional prefix path prepended to a relative filename.\n@return string absolute path active ui.command_entry.active (boolean)\nWhether or not the command entry is active. active ui.find.active (boolean)\nWhether or not the Find & Replace pane is active. -add_fold_point lexer.add_fold_point(lexer, token_name, start_symbol, end_symbol)\nAdds to lexer *lexer* a fold point whose beginning and end tokens are string\n*token_name* tokens with string content *start_symbol* and *end_symbol*,\nrespectively.\nIn the event that *start_symbol* may or may not be a fold point depending on\ncontext, and that additional processing is required, *end_symbol* may be a\nfunction that ultimately returns `1` (indicating a beginning fold point),\n`-1` (indicating an ending fold point), or `0` (indicating no fold point).\nThat function is passed the following arguments:\n\n * `text`: The text being processed for fold points.\n * `pos`: The position in *text* of the beginning of the line currently\n being processed.\n * `line`: The text of the line currently being processed.\n * `s`: The position of *start_symbol* in *line*.\n * `symbol`: *start_symbol* itself.\n@param lexer The lexer to add a fold point to.\n@param token_name The token name of text that indicates a fold point.\n@param start_symbol The text that indicates the beginning of a fold point.\n@param end_symbol Either the text that indicates the end of a fold point, or\n a function that returns whether or not *start_symbol* is a beginning fold\n point (1), an ending fold point (-1), or not a fold point at all (0).\n@usage lex:add_fold_point(lexer.OPERATOR, '{', '}')\n@usage lex:add_fold_point(lexer.KEYWORD, 'if', 'end')\n@usage lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('#'))\n@usage lex:add_fold_point('custom', function(text, pos, line, s, symbol)\n ... end) -add_rule lexer.add_rule(lexer, id, rule)\nAdds pattern *rule* identified by string *id* to the ordered list of rules\nfor lexer *lexer*.\n@param lexer The lexer to add the given rule to.\n@param id The id associated with this rule. It does not have to be the same\n as the name passed to `token()`.\n@param rule The LPeg pattern of the rule.\n@see modify_rule -add_selection buffer.add_selection(buffer, end_pos, start_pos)\nSelects the range of text between positions *start_pos* to *end_pos* as the\nmain selection, retaining all other selections as additional selections.\nSince an empty selection (i.e. the current position) still counts as a\nselection, use `buffer.set_selection()` first when setting a list of\nselections.\n@param buffer A buffer.\n@param end_pos The caret position of the range of text to select in *buffer*.\n@param start_pos The anchor position of the range of text to select in\n *buffer*.\n@see set_selection -add_style lexer.add_style(lexer, token_name, style)\nAssociates string *token_name* in lexer *lexer* with style table *style*.\n*style* may have the following fields:\n\n* `font`: String font name.\n* `size`: Integer font size.\n* `bold`: Whether or not the font face is bold. The default value is `false`.\n* `weight`: Integer weight or boldness of a font, between 1 and 999.\n* `italics`: Whether or not the font face is italic. The default value is\n `false`.\n* `underlined`: Whether or not the font face is underlined. The default value\n is `false`.\n* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `eolfilled`: Whether or not the background color extends to the end of the\n line. The default value is `false`.\n* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal,\n mixed case. The default value is `'m'`.\n* `visible`: Whether or not the text is visible. The default value is `true`.\n* `changeable`: Whether the text is changeable instead of read-only. The\n default value is `true`.\n\nField values may also contain "$(property.name)" expansions for properties\ndefined in Scintilla, theme files, etc.\n@param lexer The lexer to add a style to.\n@param token_name The name of the token to associated with the style.\n@param style A style string for Scintilla.\n@usage lex:add_style('longstring', lexer.styles.string)\n@usage lex:add_style('deprecated_func', lexer.styles['function'] ..\n {italics = true}\n@usage lex:add_style('visible_ws', lexer.styles.whitespace ..\n {back = lexer.colors.grey} -add_text buffer.add_text(buffer, text)\nAdds string *text* to the buffer at the caret position and moves the caret to\nthe end of the added text without scrolling it into view.\n@param buffer A buffer.\n@param text The text to add. +add_fold_point lexer.add_fold_point(lexer, token_name, start_symbol, end_symbol)\nAdds to lexer *lexer* a fold point whose beginning and end tokens are string *token_name*\ntokens with string content *start_symbol* and *end_symbol*, respectively.\nIn the event that *start_symbol* may or may not be a fold point depending on context, and that\nadditional processing is required, *end_symbol* may be a function that ultimately returns\n`1` (indicating a beginning fold point), `-1` (indicating an ending fold point), or `0`\n(indicating no fold point). That function is passed the following arguments:\n\n * `text`: The text being processed for fold points.\n * `pos`: The position in *text* of the beginning of the line currently being processed.\n * `line`: The text of the line currently being processed.\n * `s`: The position of *start_symbol* in *line*.\n * `symbol`: *start_symbol* itself.\n@param lexer The lexer to add a fold point to.\n@param token_name The token name of text that indicates a fold point.\n@param start_symbol The text that indicates the beginning of a fold point.\n@param end_symbol Either the text that indicates the end of a fold point, or a function that\n returns whether or not *start_symbol* is a beginning fold point (1), an ending fold point\n (-1), or not a fold point at all (0).\n@usage lex:add_fold_point(lexer.OPERATOR, '{', '}')\n@usage lex:add_fold_point(lexer.KEYWORD, 'if', 'end')\n@usage lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('#'))\n@usage lex:add_fold_point('custom', function(text, pos, line, s, symbol) ... end) +add_rule lexer.add_rule(lexer, id, rule)\nAdds pattern *rule* identified by string *id* to the ordered list of rules for lexer *lexer*.\n@param lexer The lexer to add the given rule to.\n@param id The id associated with this rule. It does not have to be the same as the name\n passed to `token()`.\n@param rule The LPeg pattern of the rule.\n@see modify_rule +add_selection buffer.add_selection(buffer, end_pos, start_pos)\nSelects the range of text between positions *start_pos* to *end_pos* as the main selection,\nretaining all other selections as additional selections.\nSince an empty selection (i.e. the current position) still counts as a selection, use\n`buffer.set_selection()` first when setting a list of selections.\n@param buffer A buffer.\n@param end_pos The caret position of the range of text to select in *buffer*.\n@param start_pos The anchor position of the range of text to select in *buffer*.\n@see set_selection +add_style lexer.add_style(lexer, token_name, style)\nAssociates string *token_name* in lexer *lexer* with style table *style*.\n*style* may have the following fields:\n\n* `font`: String font name.\n* `size`: Integer font size.\n* `bold`: Whether or not the font face is bold. The default value is `false`.\n* `weight`: Integer weight or boldness of a font, between 1 and 999.\n* `italics`: Whether or not the font face is italic. The default value is `false`.\n* `underlined`: Whether or not the font face is underlined. The default value is `false`.\n* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `eolfilled`: Whether or not the background color extends to the end of the line. The\n default value is `false`.\n* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal, mixed case. The\n default value is `'m'`.\n* `visible`: Whether or not the text is visible. The default value is `true`.\n* `changeable`: Whether the text is changeable instead of read-only. The default value is\n `true`.\n\nField values may also contain "$(property.name)" expansions for properties defined in Scintilla,\ntheme files, etc.\n@param lexer The lexer to add a style to.\n@param token_name The name of the token to associated with the style.\n@param style A style string for Scintilla.\n@usage lex:add_style('longstring', lexer.styles.string)\n@usage lex:add_style('deprecated_func', lexer.styles['function'] .. {italics = true}\n@usage lex:add_style('visible_ws', lexer.styles.whitespace .. {back = lexer.colors.grey} +add_text buffer.add_text(buffer, text)\nAdds string *text* to the buffer at the caret position and moves the caret to the end of\nthe added text without scrolling it into view.\n@param buffer A buffer.\n@param text The text to add. additional_caret_fore view.additional_caret_fore (number)\nThe foreground color, in "0xBBGGRR" format, of additional carets. additional_carets_blink view.additional_carets_blink (bool)\nAllow additional carets to blink.\nThe default value is `true`. additional_carets_visible view.additional_carets_visible (bool)\nDisplay additional carets.\nThe default value is `true`. -additional_sel_alpha view.additional_sel_alpha (number)\nThe alpha value, ranging from `0` (transparent) to `255` (opaque), of\nadditional selections.\nThe default value is `view.ALPHA_NOALPHA`, for no alpha. +additional_sel_alpha view.additional_sel_alpha (number)\nThe alpha value, ranging from `0` (transparent) to `255` (opaque), of additional selections.\nThe default value is `view.ALPHA_NOALPHA`, for no alpha. additional_sel_back view.additional_sel_back (number, Write-only)\nThe background color, in "0xBBGGRR" format, of additional selections.\nThis field has no effect when calling `view:set_sel_back(false, ...)`. additional_sel_fore view.additional_sel_fore (number, Write-only)\nThe foreground color, in "0xBBGGRR" format, of additional selections.\nThis field has no effect when calling `view:set_sel_fore(false, ...)`. additional_selection_typing buffer.additional_selection_typing (bool)\nType into multiple selections.\nThe default value is `false`. all_lines_visible view.all_lines_visible (bool, Read-only)\nWhether or not all lines are visible. -alnum lexer.alnum (pattern)\nA pattern that matches any alphanumeric character ('A'-'Z', 'a'-'z',\n '0'-'9'). +alnum lexer.alnum (pattern)\nA pattern that matches any alphanumeric character ('A'-'Z', 'a'-'z', '0'-'9'). alpha lexer.alpha (pattern)\nA pattern that matches any alphabetic character ('A'-'Z', 'a'-'z'). anchor buffer.anchor (number)\nThe anchor's position. annotation_clear_all buffer.annotation_clear_all(buffer)\nClears annotations from all lines.\n@param buffer A buffer. annotation_lines buffer.annotation_lines (table, Read-only)\nTable of the number of annotation text lines per line number. -annotation_style buffer.annotation_style (table)\nTable of style numbers for annotation text per line number.\nOnly some style attributes are active in annotations: font,\nsize/size_fractional, bold/weight, italics, fore, back, and character_set. +annotation_style buffer.annotation_style (table)\nTable of style numbers for annotation text per line number.\nOnly some style attributes are active in annotations: font, size/size_fractional, bold/weight,\nitalics, fore, back, and character_set. annotation_text buffer.annotation_text (table)\nTable of annotation text per line number. -annotation_visible view.annotation_visible (number)\nThe annotation visibility mode.\n\n* `view.ANNOTATION_HIDDEN`\n Annotations are invisible.\n* `view.ANNOTATION_STANDARD`\n Draw annotations left-justified with no decoration.\n* `view.ANNOTATION_BOXED`\n Indent annotations to match the annotated text and outline them with a\n box.\n* `view.ANNOTATION_INDENTED`\n Indent non-decorated annotations to match the annotated text.\n\nThe default value is `view.ANNOTATION_HIDDEN`. +annotation_visible view.annotation_visible (number)\nThe annotation visibility mode.\n\n* `view.ANNOTATION_HIDDEN`\n Annotations are invisible.\n* `view.ANNOTATION_STANDARD`\n Draw annotations left-justified with no decoration.\n* `view.ANNOTATION_BOXED`\n Indent annotations to match the annotated text and outline them with a box.\n* `view.ANNOTATION_INDENTED`\n Indent non-decorated annotations to match the annotated text.\n\nThe default value is `view.ANNOTATION_HIDDEN`. ansi_c _M.ansi_c (module)\nThe ansi_c module.\nIt provides utilities for editing C code. any lexer.any (pattern)\nA pattern that matches any single character. -api_files textadept.editing.api_files (table)\nMap of lexer names to API documentation file tables.\nFile tables contain API file paths or functions that return such paths.\nEach line in an API file consists of a symbol name (not a fully qualified\nsymbol name), a space character, and that symbol's documentation. "\\n"\nrepresents a newline character.\n@see show_documentation -append_history ui.command_entry.append_history(f, text)\nAppends string *text* to the history for command entry mode *f* or the\ncurrent or most recent mode.\nThis should only be called if `ui.command_entry.run()` is called with a keys\ntable that has a custom binding for the Enter key ('\\n').\nOtherwise, history is automatically appended as needed.\n@param f Optional command entry mode to append history to. This is a function\n passed to `ui.command_entry_run()`. If omitted, uses the current or most\n recent mode.\n@param text String text to append to history. -append_text buffer.append_text(buffer, text)\nAppends string *text* to the end of the buffer without modifying any existing\nselections or scrolling the text into view.\n@param buffer A buffer.\n@param text The text to append. +api_files textadept.editing.api_files (table)\nMap of lexer names to API documentation file tables.\nFile tables contain API file paths or functions that return such paths. Each line in an\nAPI file consists of a symbol name (not a fully qualified symbol name), a space character,\nand that symbol's documentation. "\\n" represents a newline character.\n@see show_documentation +append_history ui.command_entry.append_history(f, text)\nAppends string *text* to the history for command entry mode *f* or the current or most\nrecent mode.\nThis should only be called if `ui.command_entry.run()` is called with a keys table that has a\ncustom binding for the Enter key ('\\n'). Otherwise, history is automatically appended as needed.\n@param f Optional command entry mode to append history to. This is a function passed to\n `ui.command_entry_run()`. If omitted, uses the current or most recent mode.\n@param text String text to append to history. +append_text buffer.append_text(buffer, text)\nAppends string *text* to the end of the buffer without modifying any existing selections or\nscrolling the text into view.\n@param buffer A buffer.\n@param text The text to append. arg _G.arg (table)\nTable of command line parameters passed to Textadept.\n@see args args _G.args (module)\nProcesses command line arguments for Textadept. ascii lexer.ascii (pattern)\nA pattern that matches any ASCII character (codes 0 to 127). assert _G.assert (module)\nExtends `_G` with formatted assertions and function argument type checks. -assert _G.assert(v, message, ...)\nAsserts that value *v* is not `false` or `nil` and returns *v*, or calls\n`error()` with *message* as the error message, defaulting to "assertion\nfailed!". If *message* is a format string, the remaining arguments are passed\nto `string.format()` and the resulting string becomes the error message.\n@param v Value to assert.\n@param message Optional error message to show on error. The default value is\n "assertion failed!".\n@param ... If *message* is a format string, these arguments are passed to\n `string.format()`. -assert_type _G.assert_type(v, expected_type, narg)\nAsserts that value *v* has type string *expected_type* and returns *v*, or\ncalls `error()` with an error message that implicates function argument\nnumber *narg*.\nThis is intended to be used with API function arguments so users receive more\nhelpful error messages.\n@param v Value to assert the type of.\n@param expected_type String type to assert. It may be a non-letter-delimited\n list of type options.\n@param narg The positional argument number *v* is associated with. This is\n not required to be a number.\n@usage assert_type(filename, 'string/nil', 1)\n@usage assert_type(option.setting, 'number', 'setting') -- implicates key +assert _G.assert(v, message, ...)\nAsserts that value *v* is not `false` or `nil` and returns *v*, or calls `error()` with\n*message* as the error message, defaulting to "assertion failed!".\nIf *message* is a format string, the remaining arguments are passed to `string.format()`\nand the resulting string becomes the error message.\n@param v Value to assert.\n@param message Optional error message to show on error. The default value is "assertion failed!".\n@param ... If *message* is a format string, these arguments are passed to `string.format()`. +assert_type _G.assert_type(v, expected_type, narg)\nAsserts that value *v* has type string *expected_type* and returns *v*, or calls `error()`\nwith an error message that implicates function argument number *narg*.\nThis is intended to be used with API function arguments so users receive more helpful error\nmessages.\n@param v Value to assert the type of.\n@param expected_type String type to assert. It may be a non-letter-delimited list of type\n options.\n@param narg The positional argument number *v* is associated with. This is not required to\n be a number.\n@usage assert_type(filename, 'string/nil', 1)\n@usage assert_type(option.setting, 'number', 'setting') -- implicates key auto_c_active buffer.auto_c_active(buffer)\nReturns whether or not an autocompletion or user list is visible.\n@param buffer A buffer.\n@return bool -auto_c_auto_hide buffer.auto_c_auto_hide (bool)\nAutomatically cancel an autocompletion or user list when no entries match\ntyped text.\nThe default value is `true`. +auto_c_auto_hide buffer.auto_c_auto_hide (bool)\nAutomatically cancel an autocompletion or user list when no entries match typed text.\nThe default value is `true`. auto_c_cancel buffer.auto_c_cancel(buffer)\nCancels the displayed autocompletion or user list.\n@param buffer A buffer. -auto_c_cancel_at_start buffer.auto_c_cancel_at_start (bool)\nCancel an autocompletion list when backspacing to a position before where\nautocompletion started (instead of before the word being completed).\nThis option has no effect for a user list.\nThe default value is `true`. +auto_c_cancel_at_start buffer.auto_c_cancel_at_start (bool)\nCancel an autocompletion list when backspacing to a position before where autocompletion\nstarted (instead of before the word being completed).\nThis option has no effect for a user list.\nThe default value is `true`. auto_c_case_insensitive_behavior buffer.auto_c_case_insensitive_behavior (number)\nThe behavior mode for a case insensitive autocompletion or user list when\n`buffer.auto_c_ignore_case` is `true`.\n\n* `buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE`\n Prefer to select case-sensitive matches.\n* `buffer.CASEINSENSITIVEBEHAVIOR_IGNORECASE`\n No preference.\n\nThe default value is `buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE`. auto_c_choose_single buffer.auto_c_choose_single (bool)\nAutomatically choose the item in a single-item autocompletion list.\nThis option has no effect for a user list.\nThe default value is `false`. auto_c_complete buffer.auto_c_complete(buffer)\nCompletes the current word with the one selected in an autocompletion list.\n@param buffer A buffer. auto_c_current buffer.auto_c_current (number, Read-only)\nThe index of the currently selected item in an autocompletion or user list. auto_c_current_text buffer.auto_c_current_text (string, Read-only)\nThe text of the currently selected item in an autocompletion or user list. auto_c_drop_rest_of_word buffer.auto_c_drop_rest_of_word (bool)\nDelete any word characters immediately to the right of autocompleted text.\nThe default value is `false`. -auto_c_fill_ups buffer.auto_c_fill_ups (string, Write-only)\nThe set of characters that choose the currently selected item in an\nautocompletion or user list when the user types one of them.\nThe default value is `''`. +auto_c_fill_ups buffer.auto_c_fill_ups (string, Write-only)\nThe set of characters that choose the currently selected item in an autocompletion or user\nlist when the user types one of them.\nThe default value is `''`. auto_c_ignore_case buffer.auto_c_ignore_case (bool)\nIgnore case when searching an autocompletion or user list for matches.\nThe default value is `false`. -auto_c_max_height view.auto_c_max_height (number)\nThe maximum number of items per page to show in autocompletion and user\nlists. The default value is `5`. -auto_c_max_width view.auto_c_max_width (number)\nThe maximum number of characters per item to show in autocompletion and\nuser lists.\nThe default value is `0`, which automatically sizes the width to fit the\nlongest item. +auto_c_max_height view.auto_c_max_height (number)\nThe maximum number of items per page to show in autocompletion and user lists.\nThe default value is `5`. +auto_c_max_width view.auto_c_max_width (number)\nThe maximum number of characters per item to show in autocompletion and user lists.\nThe default value is `0`, which automatically sizes the width to fit the longest item. auto_c_multi buffer.auto_c_multi (number)\nThe multiple selection autocomplete mode.\n\n* `buffer.MULTIAUTOC_ONCE`\n Autocomplete into only the main selection.\n* `buffer.MULTIAUTOC_EACH`\n Autocomplete into all selections.\n\nThe default value is `buffer.MULTIAUTOC_ONCE`. -auto_c_order buffer.auto_c_order (number)\nThe order setting for autocompletion and user lists.\n\n* `buffer.ORDER_PRESORTED`\n Lists passed to `buffer.auto_c_show()` are in sorted, alphabetical\n order.\n* `buffer.ORDER_PERFORMSORT`\n Sort autocompletion lists passed to `buffer.auto_c_show()`.\n* `buffer.ORDER_CUSTOM`\n Lists passed to `buffer.auto_c_show()` are already in a custom order.\n\nThe default value is `buffer.ORDER_PRESORTED`. -auto_c_pos_start buffer.auto_c_pos_start(buffer)\nReturns the position where autocompletion started or where a user list was\nshown.\n@param buffer A buffer.\n@return number -auto_c_select buffer.auto_c_select(buffer, prefix)\nSelects the first item that starts with string *prefix* in an autocompletion\nor user list, using the case sensitivity setting `buffer.auto_c_ignore_case`.\n@param buffer A buffer.\n@param prefix The item in the list to select. -auto_c_separator buffer.auto_c_separator (number)\nThe byte value of the character that separates autocompletion and user list\nlist items.\nThe default value is `32` (' '). -auto_c_show buffer.auto_c_show(buffer, len_entered, items)\nDisplays an autocompletion list constructed from string *items* (whose items\nare delimited by `buffer.auto_c_separator` characters) using *len_entered*\nnumber of characters behind the caret as the prefix of the word to be\nautocompleted.\nThe sorted order of *items* (`buffer.auto_c_order`) must have already been\ndefined.\n@param buffer A buffer.\n@param len_entered The number of characters before the caret used to provide\n the context.\n@param items The sorted string of words to show, separated by\n `buffer.auto_c_separator` characters (initially spaces).\n@see auto_c_separator\n@see auto_c_order -auto_c_stops buffer.auto_c_stops(buffer, chars)\nAllows the user to type any character in string set *chars* in order to\ncancel an autocompletion or user list.\nThe default set is empty.\n@param buffer A buffer.\n@param chars The string of characters that cancel autocompletion. This string\n is empty by default. -auto_c_type_separator buffer.auto_c_type_separator (number)\nThe character byte that separates autocompletion and user list items and\ntheir image types.\nAutocompletion and user list items can display both an image and text.\nRegister images and their types using `view.register_image()` or\n`view.register_rgba_image()` before appending image types to list\nitems after type separator characters.\nThe default value is 63 ('?'). -auto_enclose textadept.editing.auto_enclose (bool)\nWhether or not to auto-enclose selected text when typing a punctuation\ncharacter, taking `textadept.editing.auto_pairs` into account.\nThe default value is `false`. +auto_c_order buffer.auto_c_order (number)\nThe order setting for autocompletion and user lists.\n\n* `buffer.ORDER_PRESORTED`\n Lists passed to `buffer.auto_c_show()` are in sorted, alphabetical order.\n* `buffer.ORDER_PERFORMSORT`\n Sort autocompletion lists passed to `buffer.auto_c_show()`.\n* `buffer.ORDER_CUSTOM`\n Lists passed to `buffer.auto_c_show()` are already in a custom order.\n\nThe default value is `buffer.ORDER_PRESORTED`. +auto_c_pos_start buffer.auto_c_pos_start(buffer)\nReturns the position where autocompletion started or where a user list was shown.\n@param buffer A buffer.\n@return number +auto_c_select buffer.auto_c_select(buffer, prefix)\nSelects the first item that starts with string *prefix* in an autocompletion or user list,\nusing the case sensitivity setting `buffer.auto_c_ignore_case`.\n@param buffer A buffer.\n@param prefix The item in the list to select. +auto_c_separator buffer.auto_c_separator (number)\nThe byte value of the character that separates autocompletion and user list list items.\nThe default value is `32` (' '). +auto_c_show buffer.auto_c_show(buffer, len_entered, items)\nDisplays an autocompletion list constructed from string *items* (whose items are delimited by\n`buffer.auto_c_separator` characters) using *len_entered* number of characters behind the\ncaret as the prefix of the word to be autocompleted.\nThe sorted order of *items* (`buffer.auto_c_order`) must have already been defined.\n@param buffer A buffer.\n@param len_entered The number of characters before the caret used to provide the context.\n@param items The sorted string of words to show, separated by `buffer.auto_c_separator`\n characters (initially spaces).\n@see auto_c_separator\n@see auto_c_order +auto_c_stops buffer.auto_c_stops(buffer, chars)\nAllows the user to type any character in string set *chars* in order to cancel an autocompletion\nor user list.\nThe default set is empty.\n@param buffer A buffer.\n@param chars The string of characters that cancel autocompletion. This string is empty\n by default. +auto_c_type_separator buffer.auto_c_type_separator (number)\nThe character byte that separates autocompletion and user list items and their image types.\nAutocompletion and user list items can display both an image and text. Register images\nand their types using `view.register_image()` or `view.register_rgba_image()`\nbefore appending image types to list items after type separator characters.\nThe default value is 63 ('?'). +auto_enclose textadept.editing.auto_enclose (bool)\nWhether or not to auto-enclose selected text when typing a punctuation character, taking\n`textadept.editing.auto_pairs` into account.\nThe default value is `false`. auto_indent textadept.editing.auto_indent (bool)\nMatch the previous line's indentation level after inserting a new line.\nThe default value is `true`. -auto_pairs textadept.editing.auto_pairs (table)\nMap of auto-paired characters like parentheses, brackets, braces, and quotes.\nThe ASCII values of opening characters are assigned to strings that contain\ncomplement characters. The default auto-paired characters are "()", "[]",\n"{}", "''", and """". -autocomplete textadept.editing.autocomplete(name)\nDisplays an autocompletion list provided by the autocompleter function\nassociated with string *name*, and returns `true` if completions were found.\n@param name The name of an autocompleter function in the `autocompleters`\n table to use for providing autocompletions.\n@see autocompleters +auto_pairs textadept.editing.auto_pairs (table)\nMap of auto-paired characters like parentheses, brackets, braces, and quotes.\nThe ASCII values of opening characters are assigned to strings that contain complement\ncharacters. The default auto-paired characters are "()", "[]", "{}", "''", and\n"""". +autocomplete textadept.editing.autocomplete(name)\nDisplays an autocompletion list provided by the autocompleter function associated with string\n*name*, and returns `true` if completions were found.\n@param name The name of an autocompleter function in the `autocompleters` table to use for\n providing autocompletions.\n@see autocompleters autocomplete_all_words textadept.editing.autocomplete_all_words (bool)\nAutocomplete the current word using words from all open buffers.\nIf `true`, performance may be slow when many buffers are open.\nThe default value is `false`. autocomplete_snippets _M.ansi_c.autocomplete_snippets (boolean)\nWhether or not to include snippets in autocompletion lists.\nThe default value is `true`. autocomplete_snippets _M.lua.autocomplete_snippets (boolean)\nWhether or not to include snippets in autocompletion lists.\nThe default value is `false`. -autocompleters textadept.editing.autocompleters (table)\nMap of autocompleter names to autocompletion functions.\nNames are typically lexer names and autocompletion functions typically\nautocomplete symbols.\nAutocompletion functions must return two values: the number of characters\nbehind the caret that are used as the prefix of the entity to be\nautocompleted, and a list of completions to be shown. Autocompletion lists\nare sorted automatically.\n@see autocomplete +autocompleters textadept.editing.autocompleters (table)\nMap of autocompleter names to autocompletion functions.\nNames are typically lexer names and autocompletion functions typically autocomplete symbols.\nAutocompletion functions must return two values: the number of characters behind the caret\nthat are used as the prefix of the entity to be autocompleted, and a list of completions to\nbe shown. Autocompletion lists are sorted automatically.\n@see autocomplete back textadept.history.back()\nNavigates backwards through the current view's history. back_space_un_indents buffer.back_space_un_indents (bool)\nUn-indent text when backspacing within indentation.\nThe default value is `false`. back_tab buffer.back_tab(buffer)\nUn-indents the text on the selected lines.\n@param buffer A buffer. begin_undo_action buffer.begin_undo_action(buffer)\nStarts a sequence of actions to be undone or redone as a single action.\nMay be nested.\n@param buffer A buffer. bookmarks textadept.bookmarks (module)\nBookmarks for Textadept. -brace_bad_light view.brace_bad_light(view, pos)\nHighlights the character at position *pos* as an unmatched brace character\nusing the `'style.bracebad'` style.\nRemoves highlighting when *pos* is `-1`.\n@param view A view.\n@param pos The position in *view*'s buffer to highlight, or `-1` to remove\n the highlight. -brace_bad_light_indicator view.brace_bad_light_indicator(view, use_indicator, indicator)\nHighlights unmatched brace characters with indicator number *indicator*, in\nthe range of `1` to `32`, instead of the\n`view.STYLE_BRACEBAD` style if *use_indicator* is `true`.\n@param view A view.\n@param use_indicator Whether or not to use an indicator.\n@param indicator The indicator number to use. -brace_highlight view.brace_highlight(view, pos1, pos2)\nHighlights the characters at positions *pos1* and *pos2* as matching braces\nusing the `'style.bracelight'` style.\nIf indent guides are enabled, locates the column with `buffer.column` and\nsets `view.highlight_guide` in order to highlight the indent guide.\n@param view A view.\n@param pos1 The first position in *view*'s buffer to highlight.\n@param pos2 The second position in *view*'s buffer to highlight. -brace_highlight_indicator view.brace_highlight_indicator(view, use_indicator, indicator)\nHighlights matching brace characters with indicator number *indicator*, in\nthe range of `1` to `32`, instead of the\n`view.STYLE_BRACELIGHT` style if *use_indicator* is `true`.\n@param view A view.\n@param use_indicator Whether or not to use an indicator.\n@param indicator The indicator number to use. -brace_match buffer.brace_match(buffer, pos, max_re_style)\nReturns the position of the matching brace for the brace character at\nposition *pos*, taking nested braces into account, or `-1`.\nThe brace characters recognized are '(', ')', '[', ']', '{', '}', '<', and\n'>' and must have the same style.\n@param buffer A buffer.\n@param pos The position of the brace in *buffer* to match.\n@param max_re_style Must be `0`. Reserved for expansion.\n@return number -brace_matches textadept.editing.brace_matches (table)\nTable of brace characters to highlight.\nThe ASCII values of brace characters are keys and are assigned non-`nil`\nvalues. The default brace characters are '(', ')', '[', ']', '{', and '}'. -buffer _G.buffer (module)\nA Textadept buffer object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual buffer instances, it is really only useful\nto work with the global one.\nMany of these functions and fields are derived from buffer-specific\nfunctionality of the Scintilla editing component, and additional information\ncan be found on the\nScintilla website.\nNote that with regard to Scintilla-specific functionality, this API is a\n_suggestion_, not a hard requirement. All of that functionality also exists\nin `view`, even if undocumented.\nAny buffer fields set on startup (e.g. in *~/.textadept/init.lua*) will be\nthe default, initial values for all buffers. +brace_bad_light view.brace_bad_light(view, pos)\nHighlights the character at position *pos* as an unmatched brace character using the\n`'style.bracebad'` style.\nRemoves highlighting when *pos* is `-1`.\n@param view A view.\n@param pos The position in *view*'s buffer to highlight, or `-1` to remove the highlight. +brace_bad_light_indicator view.brace_bad_light_indicator(view, use_indicator, indicator)\nHighlights unmatched brace characters with indicator number *indicator*, in the range of\n`1` to `32`, instead of the `view.STYLE_BRACEBAD` style if *use_indicator* is `true`.\n@param view A view.\n@param use_indicator Whether or not to use an indicator.\n@param indicator The indicator number to use. +brace_highlight view.brace_highlight(view, pos1, pos2)\nHighlights the characters at positions *pos1* and *pos2* as matching braces using the\n`'style.bracelight'` style.\nIf indent guides are enabled, locates the column with `buffer.column` and sets\n`view.highlight_guide` in order to highlight the indent guide.\n@param view A view.\n@param pos1 The first position in *view*'s buffer to highlight.\n@param pos2 The second position in *view*'s buffer to highlight. +brace_highlight_indicator view.brace_highlight_indicator(view, use_indicator, indicator)\nHighlights matching brace characters with indicator number *indicator*, in the range of `1`\nto `32`, instead of the `view.STYLE_BRACELIGHT` style if *use_indicator* is `true`.\n@param view A view.\n@param use_indicator Whether or not to use an indicator.\n@param indicator The indicator number to use. +brace_match buffer.brace_match(buffer, pos, max_re_style)\nReturns the position of the matching brace for the brace character at position *pos*, taking\nnested braces into account, or `-1`.\nThe brace characters recognized are '(', ')', '[', ']', '{', '}', '<', and '>' and must have\nthe same style.\n@param buffer A buffer.\n@param pos The position of the brace in *buffer* to match.\n@param max_re_style Must be `0`. Reserved for expansion.\n@return number +brace_matches textadept.editing.brace_matches (table)\nTable of brace characters to highlight.\nThe ASCII values of brace characters are keys and are assigned non-`nil` values. The default\nbrace characters are '(', ')', '[', ']', '{', and '}'. +buffer _G.buffer (module)\nA Textadept buffer object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual buffer instances, it is really only useful to work with\nthe global one.\nMany of these functions and fields are derived from buffer-specific functionality of the\nScintilla editing component, and additional information can be found on the [Scintilla\nwebsite](https://scintilla.org/ScintillaDoc.html). Note that with regard to Scintilla-specific\nfunctionality, this API is a _suggestion_, not a hard requirement. All of that functionality\nalso exists in `view`, even if undocumented.\nAny buffer fields set on startup (e.g. in *~/.textadept/init.lua*) will be the default,\ninitial values for all buffers. buffer _G.buffer (table)\nThe current buffer in the current view. buffer view.buffer (table)\nThe buffer the view currently contains. (Read-only) buffer_statusbar_text ui.buffer_statusbar_text (string, Write-only)\nThe text displayed in the buffer statusbar. -build textadept.run.build(root_directory)\nBuilds the project whose root path is *root_directory* or the current project\nusing the shell command from the `build_commands` table.\nIf a "makefile" type of build file is found, prompts the user for the full\nbuild command.\nThe current project is determined by either the buffer's filename or the\ncurrent working directory.\nEmits `BUILD_OUTPUT` events.\n@param root_directory The path to the project to build. The default value is\n the current project.\n@see build_commands\n@see _G.events -build_commands textadept.run.build_commands (table)\nMap of project root paths and "makefiles" to their associated "build" shell\ncommand line strings or functions that return such strings.\nFunctions may also return a working directory and process environment table\nto operate in. By default, the working directory is the project's root\ndirectory and the environment is Textadept's environment. +build textadept.run.build(root_directory)\nBuilds the project whose root path is *root_directory* or the current project using the\nshell command from the `build_commands` table.\nIf a "makefile" type of build file is found, prompts the user for the full build command. The\ncurrent project is determined by either the buffer's filename or the current working directory.\nEmits `BUILD_OUTPUT` events.\n@param root_directory The path to the project to build. The default value is the current project.\n@see build_commands\n@see _G.events +build_commands textadept.run.build_commands (table)\nMap of project root paths and "makefiles" to their associated "build" shell command line\nstrings or functions that return such strings.\nFunctions may also return a working directory and process environment table to operate\nin. By default, the working directory is the project's root directory and the environment\nis Textadept's environment. call_tip_active view.call_tip_active(view)\nReturns whether or not a call tip is visible.\n@param view A view.\n@return bool call_tip_cancel view.call_tip_cancel(view)\nRemoves the displayed call tip from view.\n@param view A view. call_tip_fore_hlt view.call_tip_fore_hlt (number, Write-only)\nA call tip's highlighted text foreground color, in "0xBBGGRR" format. call_tip_pos_start view.call_tip_pos_start (number, Write-only)\nThe position at which backspacing beyond it hides a visible call tip. call_tip_pos_start view.call_tip_pos_start(view)\nReturns a call tip's display position.\n@param view A view.\n@return number call_tip_position view.call_tip_position (boolean)\nDisplay a call tip above the current line instead of below it.\nThe default value is `false`. -call_tip_set_hlt view.call_tip_set_hlt(view, start_pos, end_pos)\nHighlights a call tip's text between positions *start_pos* to *end_pos* with\nthe color `view.call_tip_fore_hlt`.\n@param view A view.\n@param start_pos The start position in a call tip text to highlight.\n@param end_pos The end position in a call tip text to highlight. -call_tip_show view.call_tip_show(view, pos, text)\nDisplays a call tip at position *pos* with string *text* as the call tip's\ncontents.\nAny "\001" or "\002" bytes in *text* are replaced by clickable up or down\narrow visuals, respectively. These may be used to indicate that a symbol has\nmore than one call tip, for example.\n@param view A view.\n@param pos The position in *view*'s buffer to show a call tip at.\n@param text The call tip text to show. -call_tip_use_style view.call_tip_use_style (number)\nThe pixel width of tab characters in call tips.\nWhen non-zero, also enables the use of style number `view.STYLE_CALLTIP`\ninstead of `view.STYLE_DEFAULT` for call tip styles.\nThe default value is `0`. +call_tip_set_hlt view.call_tip_set_hlt(view, start_pos, end_pos)\nHighlights a call tip's text between positions *start_pos* to *end_pos* with the color\n`view.call_tip_fore_hlt`.\n@param view A view.\n@param start_pos The start position in a call tip text to highlight.\n@param end_pos The end position in a call tip text to highlight. +call_tip_show view.call_tip_show(view, pos, text)\nDisplays a call tip at position *pos* with string *text* as the call tip's contents.\nAny "\001" or "\002" bytes in *text* are replaced by clickable up or down arrow visuals,\nrespectively. These may be used to indicate that a symbol has more than one call tip,\nfor example.\n@param view A view.\n@param pos The position in *view*'s buffer to show a call tip at.\n@param text The call tip text to show. +call_tip_use_style view.call_tip_use_style (number)\nThe pixel width of tab characters in call tips.\nWhen non-zero, also enables the use of style number `view.STYLE_CALLTIP` instead of\n`view.STYLE_DEFAULT` for call tip styles.\nThe default value is `0`. can_redo buffer.can_redo(buffer)\nReturns whether or not there is an action to be redone.\n@param buffer A buffer.\n@return bool can_undo buffer.can_undo(buffer)\nReturns whether or not there is an action to be undone.\n@param buffer A buffer.\n@return bool -cancel buffer.cancel(buffer)\nCancels the active selection mode, autocompletion or user list, call tip,\netc.\n@param buffer A buffer. +cancel buffer.cancel(buffer)\nCancels the active selection mode, autocompletion or user list, call tip, etc.\n@param buffer A buffer. cancel_current textadept.snippets.cancel_current()\nCancels the active snippet, removing all inserted text.\nReturns `false` if no snippet is active.\n@return `false` if no snippet is active; `nil` otherwise. caret_fore view.caret_fore (number)\nThe caret's foreground color, in "0xBBGGRR" format. -caret_line_back view.caret_line_back (number)\nThe background color, in "0xBBGGRR" format, of the line that contains the\ncaret. -caret_line_back_alpha view.caret_line_back_alpha (number)\nThe caret line's background alpha value, ranging from `0` (transparent) to\n`255` (opaque).\nThe default value is `view.ALPHA_NOALPHA`, for no alpha. -caret_line_frame view.caret_line_frame (number)\nThe caret line's frame width in pixels.\nWhen non-zero, the line that contains the caret is framed instead of\ncolored in. The `view.caret_line_back` and `view.caret_line_back_alpha`\nproperties apply to the frame.\nThe default value is `0`. +caret_line_back view.caret_line_back (number)\nThe background color, in "0xBBGGRR" format, of the line that contains the caret. +caret_line_back_alpha view.caret_line_back_alpha (number)\nThe caret line's background alpha value, ranging from `0` (transparent) to `255` (opaque).\nThe default value is `view.ALPHA_NOALPHA`, for no alpha. +caret_line_frame view.caret_line_frame (number)\nThe caret line's frame width in pixels.\nWhen non-zero, the line that contains the caret is framed instead of colored in. The\n`view.caret_line_back` and `view.caret_line_back_alpha` properties apply to the frame.\nThe default value is `0`. caret_line_visible view.caret_line_visible (bool)\nColor the background of the line that contains the caret a different color.\nThe default value is `false`. -caret_line_visible_always view.caret_line_visible_always (bool)\nAlways show the caret line, even when the view is not in focus.\nThe default value is `false`, showing the line only when the view is in\nfocus. +caret_line_visible_always view.caret_line_visible_always (bool)\nAlways show the caret line, even when the view is not in focus.\nThe default value is `false`, showing the line only when the view is in focus. caret_period view.caret_period (number)\nThe time between caret blinks in milliseconds.\nA value of `0` stops blinking.\nThe default value is `500`. -caret_sticky buffer.caret_sticky (number)\nThe caret's preferred horizontal position when moving between lines.\n\n* `buffer.CARETSTICKY_OFF`\n Use the same position the caret had on the previous line.\n* `buffer.CARETSTICKY_ON`\n Use the last position the caret was moved to via the mouse, left/right\n arrow keys, home/end keys, etc. Typing text does not affect the position.\n* `buffer.CARETSTICKY_WHITESPACE`\n Use the position the caret had on the previous line, but prior to any\n inserted indentation.\n\nThe default value is `buffer.CARETSTICKY_OFF`. -caret_style view.caret_style (number)\nThe caret's visual style.\n\n* `view.CARETSTYLE_INVISIBLE`\n No caret.\n* `view.CARETSTYLE_LINE`\n A line caret.\n* `view.CARETSTYLE_BLOCK`\n A block caret.\n\nAny block setting may be combined with `view.CARETSTYLE_BLOCK_AFTER` via\nbitwise OR (`|`) in order to draw the caret after the end of a selection,\nas opposed to just inside it.\n\nThe default value is `view.CARETSTYLE_LINE`. +caret_sticky buffer.caret_sticky (number)\nThe caret's preferred horizontal position when moving between lines.\n\n* `buffer.CARETSTICKY_OFF`\n Use the same position the caret had on the previous line.\n* `buffer.CARETSTICKY_ON`\n Use the last position the caret was moved to via the mouse, left/right arrow keys,\n home/end keys, etc. Typing text does not affect the position.\n* `buffer.CARETSTICKY_WHITESPACE`\n Use the position the caret had on the previous line, but prior to any inserted indentation.\n\nThe default value is `buffer.CARETSTICKY_OFF`. +caret_style view.caret_style (number)\nThe caret's visual style.\n\n* `view.CARETSTYLE_INVISIBLE`\n No caret.\n* `view.CARETSTYLE_LINE`\n A line caret.\n* `view.CARETSTYLE_BLOCK`\n A block caret.\n\nAny block setting may be combined with `view.CARETSTYLE_BLOCK_AFTER` via bitwise OR (`|`)\nin order to draw the caret after the end of a selection, as opposed to just inside it.\n\nThe default value is `view.CARETSTYLE_LINE`. caret_width view.caret_width (number)\nThe line caret's pixel width in insert mode, between `0` and `20`.\nThe default value is `1`. char_at buffer.char_at (table, Read-only)\nTable of character bytes per position. char_left buffer.char_left(buffer)\nMoves the caret left one character.\n@param buffer A buffer. -char_left_extend buffer.char_left_extend(buffer)\nMoves the caret left one character, extending the selected text to the new\nposition.\n@param buffer A buffer. -char_left_rect_extend buffer.char_left_rect_extend(buffer)\nMoves the caret left one character, extending the rectangular selection to\nthe new position.\n@param buffer A buffer. +char_left_extend buffer.char_left_extend(buffer)\nMoves the caret left one character, extending the selected text to the new position.\n@param buffer A buffer. +char_left_rect_extend buffer.char_left_rect_extend(buffer)\nMoves the caret left one character, extending the rectangular selection to the new position.\n@param buffer A buffer. char_right buffer.char_right(buffer)\nMoves the caret right one character.\n@param buffer A buffer. -char_right_extend buffer.char_right_extend(buffer)\nMoves the caret right one character, extending the selected text to the new\nposition.\n@param buffer A buffer. -char_right_rect_extend buffer.char_right_rect_extend(buffer)\nMoves the caret right one character, extending the rectangular selection to\nthe new position.\n@param buffer A buffer. -choose_caret_x buffer.choose_caret_x(buffer)\nIdentifies the current horizontal caret position as the caret's preferred\nhorizontal position when moving between lines.\n@param buffer A buffer.\n@see caret_sticky +char_right_extend buffer.char_right_extend(buffer)\nMoves the caret right one character, extending the selected text to the new position.\n@param buffer A buffer. +char_right_rect_extend buffer.char_right_rect_extend(buffer)\nMoves the caret right one character, extending the rectangular selection to the new position.\n@param buffer A buffer. +choose_caret_x buffer.choose_caret_x(buffer)\nIdentifies the current horizontal caret position as the caret's preferred horizontal position\nwhen moving between lines.\n@param buffer A buffer.\n@see caret_sticky clear buffer.clear(buffer)\nDeletes the selected text or the character at the caret.\n@param buffer A buffer. clear textadept.bookmarks.clear()\nClears all bookmarks in the current buffer. clear textadept.history.clear()\nClears all view history. clear_all buffer.clear_all(buffer)\nDeletes the buffer's text.\n@param buffer A buffer. clear_document_style buffer.clear_document_style(buffer)\nClears all styling and folding information.\n@param buffer A buffer. -clear_registered_images view.clear_registered_images(view)\nClears all images registered using `view.register_image()` and\n`view.register_rgba_image()`.\n@param view A view. -clear_representation view.clear_representation(view, char)\nRemoves the alternate string representation for character *char* (which may\n be a multi-byte character).\n@param view A view.\n@param char The string character in `buffer.representations` to remove the\n alternate string representation for. +clear_registered_images view.clear_registered_images(view)\nClears all images registered using `view.register_image()` and `view.register_rgba_image()`.\n@param view A view. +clear_representation view.clear_representation(view, char)\nRemoves the alternate string representation for character *char* (which may be a multi-byte\n character).\n@param view A view.\n@param char The string character in `buffer.representations` to remove the alternate string\n representation for. clipboard_text ui.clipboard_text (string)\nThe text on the clipboard. -close buffer.close(buffer, force)\nCloses the buffer, prompting the user to continue if there are unsaved\nchanges (unless *force* is `true`), and returns `true` if the buffer was\nclosed.\n@param buffer A buffer.\n@param force Optional flag that discards unsaved changes without prompting\n the user. The default value is `false`.\n@return `true` if the buffer was closed; `nil` otherwise. -close spawn_proc:close()\nCloses standard input for process *spawn_proc*, effectively sending an EOF\n(end of file) to it. -close_all_buffers io.close_all_buffers()\nCloses all open buffers, prompting the user to continue if there are unsaved\nbuffers, and returns `true` if the user did not cancel.\nNo buffers are saved automatically. They must be saved manually.\n@return `true` if user did not cancel; `nil` otherwise.\n@see buffer.close +close buffer.close(buffer, force)\nCloses the buffer, prompting the user to continue if there are unsaved changes (unless *force*\nis `true`), and returns `true` if the buffer was closed.\n@param buffer A buffer.\n@param force Optional flag that discards unsaved changes without prompting the user. The\n default value is `false`.\n@return `true` if the buffer was closed; `nil` otherwise. +close spawn_proc:close()\nCloses standard input for process *spawn_proc*, effectively sending an EOF (end of file) to it. +close_all_buffers io.close_all_buffers()\nCloses all open buffers, prompting the user to continue if there are unsaved buffers, and\nreturns `true` if the user did not cancel.\nNo buffers are saved automatically. They must be saved manually.\n@return `true` if user did not cancel; `nil` otherwise.\n@see buffer.close cntrl lexer.cntrl (pattern)\nA pattern that matches any control character (ASCII codes 0 to 31). -colorize buffer.colorize(buffer, start_pos, end_pos)\nInstructs the lexer to style and mark fold points in the range of text\nbetween *start_pos* and *end_pos*.\nIf *end_pos* is `-1`, styles and marks to the end of the buffer.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to\n process.\n@param end_pos The end position of the range of text in *buffer* to process,\n or `-1` to process from *start_pos* to the end of *buffer*. -colors lexer.colors (table)\nMap of color name strings to color values in `0xBBGGRR` or `"#RRGGBB"`\nformat.\nNote: for applications running within a terminal emulator, only 16 color\nvalues are recognized, regardless of how many colors a user's terminal\nactually supports. (A terminal emulator's settings determines how to actually\ndisplay these recognized color values, which may end up being mapped to a\ncompletely different color set.) In order to use the light variant of a\ncolor, some terminals require a style's `bold` attribute must be set along\nwith that normal color. Recognized color values are black (0x000000), red\n(0x000080), green (0x008000), yellow (0x008080), blue (0x800000), magenta\n(0x800080), cyan (0x808000), white (0xC0C0C0), light black (0x404040), light\nred (0x0000FF), light green (0x00FF00), light yellow (0x00FFFF), light blue\n(0xFF0000), light magenta (0xFF00FF), light cyan (0xFFFF00), and light white\n(0xFFFFFF). -colorselect ui.dialogs.colorselect(options)\nPrompts the user with a color selection dialog defined by dialog options\ntable *options*, returning the color selected.\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the option select dialog.\n\n * `title`: The dialog's title text.\n * `color`: The initially selected color as either a number in "0xBBGGRR"\n format, or as a string in "#RRGGBB" format.\n * `palette`: The list of colors to show in the dialog's color palette.\n Up to 20 colors can be specified as either numbers in "0xBBGGRR" format\n or as strings in "#RRGGBB" format. If `true` (no list was given), a\n default palette is shown.\n * `string_output`: Return the selected color in string "#RRGGBB" format\n instead of as a number. The default value is `false`.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n@usage ui.dialogs.colorselect{title = 'Foreground color', color = 0x000000,\n palette = {'#000000', 0x0000FF, '#00FF00', 0xFF0000}}\n@return selected color +colorize buffer.colorize(buffer, start_pos, end_pos)\nInstructs the lexer to style and mark fold points in the range of text between *start_pos*\nand *end_pos*.\nIf *end_pos* is `-1`, styles and marks to the end of the buffer.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to process.\n@param end_pos The end position of the range of text in *buffer* to process, or `-1` to\n process from *start_pos* to the end of *buffer*. +colors lexer.colors (table)\nMap of color name strings to color values in `0xBBGGRR` or `"#RRGGBB"` format.\nNote: for applications running within a terminal emulator, only 16 color values are recognized,\nregardless of how many colors a user's terminal actually supports. (A terminal emulator's\nsettings determines how to actually display these recognized color values, which may end up\nbeing mapped to a completely different color set.) In order to use the light variant of a\ncolor, some terminals require a style's `bold` attribute must be set along with that normal\ncolor. Recognized color values are black (0x000000), red (0x000080), green (0x008000), yellow\n(0x008080), blue (0x800000), magenta (0x800080), cyan (0x808000), white (0xC0C0C0), light black\n(0x404040), light red (0x0000FF), light green (0x00FF00), light yellow (0x00FFFF), light blue\n(0xFF0000), light magenta (0xFF00FF), light cyan (0xFFFF00), and light white (0xFFFFFF). +colorselect ui.dialogs.colorselect(options)\nPrompts the user with a color selection dialog defined by dialog options table *options*,\nreturning the color selected.\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the option select dialog.\n\n * `title`: The dialog's title text.\n * `color`: The initially selected color as either a number in "0xBBGGRR" format, or as a\n string in "#RRGGBB" format.\n * `palette`: The list of colors to show in the dialog's color palette. Up to 20 colors can\n be specified as either numbers in "0xBBGGRR" format or as strings in "#RRGGBB" format. If\n `true` (no list was given), a default palette is shown.\n * `string_output`: Return the selected color in string "#RRGGBB" format instead of as a\n number. The default value is `false`.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n@usage ui.dialogs.colorselect{title = 'Foreground color', color = 0x000000,\n palette = {'#000000', 0x0000FF, '#00FF00', 0xFF0000}}\n@return selected color column buffer.column (table, Read-only)\nTable of column numbers (taking tab widths into account) per position.\nMulti-byte characters count as single characters. -command_entry ui.command_entry (module)\nTextadept's Command Entry.\nIt supports multiple modes that each have their own functionality (such as\nrunning Lua code and filtering text through shell commands) and history. -comment_string textadept.editing.comment_string (table)\nMap of lexer names to line comment strings for programming languages, used by\nthe `toggle_comment()` function.\nKeys are lexer names and values are either the language's line comment\nprefixes or block comment delimiters separated by a '|' character.\n@see toggle_comment -compile textadept.run.compile(filename)\nCompiles file *filename* or the current file using an appropriate shell\ncommand from the `compile_commands` table.\nThe shell command is determined from the file's filename, extension, or\nlanguage in that order.\nEmits `COMPILE_OUTPUT` events.\n@param filename Optional path to the file to compile. The default value is\n the current file's filename.\n@see compile_commands\n@see _G.events -compile_commands textadept.run.compile_commands (table)\nMap of filenames, file extensions, and lexer names to their associated\n"compile" shell command line strings or functions that return such strings.\nCommand line strings may have the following macros:\n\n + `%f`: The file's name, including its extension.\n + `%e`: The file's name, excluding its extension.\n + `%d`: The file's directory path.\n + `%p`: The file's full path.\n\nFunctions may also return a working directory and process environment table\nto operate in. By default, the working directory is the current file's parent\ndirectory and the environment is Textadept's environment. -connect events.connect(event, f, index)\nAdds function *f* to the set of event handlers for event *event* at position\n*index*.\nIf *index* not given, appends *f* to the set of handlers. *event* may be any\narbitrary string and does not need to have been previously defined.\n@param event The string event name.\n@param f The Lua function to connect to *event*.\n@param index Optional index to insert the handler into.\n@usage events.connect('my_event', function(msg) ui.print(msg) end)\n@see disconnect +command_entry ui.command_entry (module)\nTextadept's Command Entry.\nIt supports multiple modes that each have their own functionality (such as running Lua code\nand filtering text through shell commands) and history. +comment_string textadept.editing.comment_string (table)\nMap of lexer names to line comment strings for programming languages, used by the\n`toggle_comment()` function.\nKeys are lexer names and values are either the language's line comment prefixes or block\ncomment delimiters separated by a '|' character.\n@see toggle_comment +compile textadept.run.compile(filename)\nCompiles file *filename* or the current file using an appropriate shell command from the\n`compile_commands` table.\nThe shell command is determined from the file's filename, extension, or language in that order.\nEmits `COMPILE_OUTPUT` events.\n@param filename Optional path to the file to compile. The default value is the current\n file's filename.\n@see compile_commands\n@see _G.events +compile_commands textadept.run.compile_commands (table)\nMap of filenames, file extensions, and lexer names to their associated "compile" shell\ncommand line strings or functions that return such strings.\nCommand line strings may have the following macros:\n\n + `%f`: The file's name, including its extension.\n + `%e`: The file's name, excluding its extension.\n + `%d`: The file's directory path.\n + `%p`: The file's full path.\n\nFunctions may also return a working directory and process environment table to operate in. By\ndefault, the working directory is the current file's parent directory and the environment\nis Textadept's environment. +connect events.connect(event, f, index)\nAdds function *f* to the set of event handlers for event *event* at position *index*.\nIf *index* not given, appends *f* to the set of handlers. *event* may be any arbitrary string\nand does not need to have been previously defined.\n@param event The string event name.\n@param f The Lua function to connect to *event*.\n@param index Optional index to insert the handler into.\n@usage events.connect('my_event', function(msg) ui.print(msg) end)\n@see disconnect constants _SCINTILLA.constants (table)\nMap of Scintilla constant names to their numeric values.\n@see _G.buffer -context_menu textadept.menu.context_menu (table)\nThe default right-click context menu.\nSubmenus, and menu items can be retrieved by name in addition to table index\nnumber. +context_menu textadept.menu.context_menu (table)\nThe default right-click context menu.\nSubmenus, and menu items can be retrieved by name in addition to table index number. context_menu ui.context_menu (userdata)\nThe buffer's context menu, a `ui.menu()`.\nThis is a low-level field. You probably want to use the higher-level\n`textadept.menu.context_menu`. -contracted_fold_next view.contracted_fold_next(view, line)\nReturns the line number of the next contracted fold point starting from line\nnumber *line*, or `-1` if none exists.\n@param view A view.\n@param line The line number in *view* to start at.\n@return number +contracted_fold_next view.contracted_fold_next(view, line)\nReturns the line number of the next contracted fold point starting from line number *line*,\nor `-1` if none exists.\n@param view A view.\n@param line The line number in *view* to start at.\n@return number convert_eols buffer.convert_eols(buffer, mode)\nConverts all end of line characters to those in end of line mode *mode*.\n@param buffer A buffer.\n@param mode The end of line mode to convert to. Valid values are:\n * `buffer.EOL_CRLF`\n * `buffer.EOL_CR`\n * `buffer.EOL_LF` -convert_indentation textadept.editing.convert_indentation()\nConverts indentation between tabs and spaces according to `buffer.use_tabs`.\nIf `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are\nconverted to tabs. Otherwise, all indenting tabs are converted to\n`buffer.tab_width` spaces.\n@see buffer.use_tabs -copy buffer.copy(buffer)\nCopies the selected text to the clipboard.\nMultiple selections are copied in order with no delimiters. Rectangular\nselections are copied from top to bottom with end of line characters. Virtual\nspace is not copied.\n@param buffer A buffer. -copy_range buffer.copy_range(buffer, start_pos, end_pos)\nCopies to the clipboard the range of text between positions *start_pos* and\n*end_pos*.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to copy.\n@param end_pos The end position of the range of text in *buffer* to copy. +convert_indentation textadept.editing.convert_indentation()\nConverts indentation between tabs and spaces according to `buffer.use_tabs`.\nIf `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are converted to tabs.\nOtherwise, all indenting tabs are converted to `buffer.tab_width` spaces.\n@see buffer.use_tabs +copy buffer.copy(buffer)\nCopies the selected text to the clipboard.\nMultiple selections are copied in order with no delimiters. Rectangular selections are copied\nfrom top to bottom with end of line characters. Virtual space is not copied.\n@param buffer A buffer. +copy_range buffer.copy_range(buffer, start_pos, end_pos)\nCopies to the clipboard the range of text between positions *start_pos* and *end_pos*.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to copy.\n@param end_pos The end position of the range of text in *buffer* to copy. copy_text buffer.copy_text(buffer, text)\nCopies string *text* to the clipboard.\n@param buffer A buffer.\n@param text The text to copy. -count_characters buffer.count_characters(buffer, start_pos, end_pos)\nReturns the number of whole characters (taking multi-byte characters into\naccount) between positions *start_pos* and *end_pos*.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to start\n counting at.\n@param end_pos The end position of the range of text in *buffer* to stop\n counting at.\n@return number +count_characters buffer.count_characters(buffer, start_pos, end_pos)\nReturns the number of whole characters (taking multi-byte characters into account) between\npositions *start_pos* and *end_pos*.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to start counting at.\n@param end_pos The end position of the range of text in *buffer* to stop counting at.\n@return number current_pos buffer.current_pos (number)\nThe caret's position.\nWhen set, does not scroll the caret into view. cursor view.cursor (number)\nThe display cursor type.\n\n* `view.CURSORNORMAL`\n The text insert cursor.\n* `view.CURSORARROW`\n The arrow cursor.\n* `view.CURSORWAIT`\n The wait cursor.\n* `view.CURSORREVERSEARROW`\n The reversed arrow cursor.\n\nThe default value is `view.CURSORNORMAL`. -cut buffer.cut(buffer)\nCuts the selected text to the clipboard.\nMultiple selections are copied in order with no delimiters. Rectangular\nselections are copied from top to bottom with end of line characters. Virtual\nspace is not copied.\n@param buffer A buffer. +cut buffer.cut(buffer)\nCuts the selected text to the clipboard.\nMultiple selections are copied in order with no delimiters. Rectangular selections are copied\nfrom top to bottom with end of line characters. Virtual space is not copied.\n@param buffer A buffer. dec_num lexer.dec_num (pattern)\nA pattern that matches a decimal number. -default_filter lfs.default_filter (table)\nThe filter table containing common binary file extensions and version control\ndirectories to exclude when iterating over files and directories using\n`walk`.\nExtensions excluded: a, bmp, bz2, class, dll, exe, gif, gz, jar, jpeg, jpg,\no, pdf, png, so, tar, tgz, tif, tiff, xz, and zip.\nDirectories excluded: .bzr, .git, .hg, .svn, _FOSSIL_, and node_modules.\n@see walk -del_line_left buffer.del_line_left(buffer)\nDeletes the range of text from the caret to the beginning of the current\nline.\n@param buffer A buffer. +default_filter lfs.default_filter (table)\nThe filter table containing common binary file extensions and version control directories\nto exclude when iterating over files and directories using `walk`.\nExtensions excluded: a, bmp, bz2, class, dll, exe, gif, gz, jar, jpeg, jpg, o, pdf, png,\nso, tar, tgz, tif, tiff, xz, and zip.\nDirectories excluded: .bzr, .git, .hg, .svn, _FOSSIL_, and node_modules.\n@see walk +del_line_left buffer.del_line_left(buffer)\nDeletes the range of text from the caret to the beginning of the current line.\n@param buffer A buffer. del_line_right buffer.del_line_right(buffer)\nDeletes the range of text from the caret to the end of the current line.\n@param buffer A buffer. -del_word_left buffer.del_word_left(buffer)\nDeletes the word to the left of the caret, including any leading non-word\ncharacters.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -del_word_right buffer.del_word_right(buffer)\nDeletes the word to the right of the caret, including any trailing non-word\ncharacters.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -del_word_right_end buffer.del_word_right_end(buffer)\nDeletes the word to the right of the caret, excluding any trailing non-word\ncharacters.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -delete buffer.delete(buffer)\nDeletes the buffer.\n**Do not call this function.** Call `buffer:close()` instead. Emits a\n`BUFFER_DELETED` event.\n@param buffer A buffer.\n@see events.BUFFER_DELETED +del_word_left buffer.del_word_left(buffer)\nDeletes the word to the left of the caret, including any leading non-word characters.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +del_word_right buffer.del_word_right(buffer)\nDeletes the word to the right of the caret, including any trailing non-word characters.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +del_word_right_end buffer.del_word_right_end(buffer)\nDeletes the word to the right of the caret, excluding any trailing non-word characters.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +delete buffer.delete(buffer)\nDeletes the buffer.\n**Do not call this function.** Call `buffer:close()` instead. Emits a `BUFFER_DELETED` event.\n@param buffer A buffer.\n@see events.BUFFER_DELETED delete_back buffer.delete_back(buffer)\nDeletes the character behind the caret if no text is selected.\nOtherwise, deletes the selected text.\n@param buffer A buffer. -delete_back_not_line buffer.delete_back_not_line(buffer)\nDeletes the character behind the caret unless either the caret is at the\nbeginning of a line or text is selected.\nIf text is selected, deletes it.\n@param buffer A buffer. +delete_back_not_line buffer.delete_back_not_line(buffer)\nDeletes the character behind the caret unless either the caret is at the beginning of a line\nor text is selected.\nIf text is selected, deletes it.\n@param buffer A buffer. delete_range buffer.delete_range(buffer, pos, length)\nDeletes the range of text from position *pos* to *pos* + *length*.\n@param buffer A buffer.\n@param pos The start position of the range of text in *buffer* to delete.\n@param length The number of characters in the range of text to delete. -dialog ui.dialog(kind, ...)\nLow-level function for prompting the user with a gtdialog of kind *kind*\nwith the given string and table arguments, returning a formatted string of\nthe dialog's output.\nYou probably want to use the higher-level functions in the `ui.dialogs`\nmodule.\nTable arguments containing strings are allowed and expanded in place. This is\nuseful for filtered list dialogs with many items.\n@param kind The kind of gtdialog.\n@param ... Parameters to the gtdialog.\n@return string gtdialog result. +dialog ui.dialog(kind, ...)\nLow-level function for prompting the user with a gtdialog of kind *kind* with the given\nstring and table arguments, returning a formatted string of the dialog's output.\nYou probably want to use the higher-level functions in the `ui.dialogs` module.\nTable arguments containing strings are allowed and expanded in place. This is useful for\nfiltered list dialogs with many items.\n@param kind The kind of gtdialog.\n@param ... Parameters to the gtdialog.\n@return string gtdialog result. dialogs ui.dialogs (module)\nProvides a set of interactive dialog prompts for user input. digit lexer.digit (pattern)\nA pattern that matches any digit ('0'-'9'). disconnect events.disconnect(event, f)\nRemoves function *f* from the set of handlers for event *event*.\n@param event The string event name.\n@param f The Lua function connected to *event*.\n@see connect -doc_line_from_visible view.doc_line_from_visible(view, display_line)\nReturns the actual line number of displayed line number *display_line*,\ntaking wrapped, annotated, and hidden lines into account.\nIf *display_line* is less than or equal to `1`, returns `1`. If\n*display_line* is greater than the number of displayed lines, returns\n`buffer.line_count`.\n@param view A view.\n@param display_line The display line number to use.\n@return number +doc_line_from_visible view.doc_line_from_visible(view, display_line)\nReturns the actual line number of displayed line number *display_line*, taking wrapped,\nannotated, and hidden lines into account.\nIf *display_line* is less than or equal to `1`, returns `1`. If *display_line* is greater\nthan the number of displayed lines, returns `buffer.line_count`.\n@param view A view.\n@param display_line The display line number to use.\n@return number document_end buffer.document_end(buffer)\nMoves the caret to the end of the buffer.\n@param buffer A buffer. -document_end_extend buffer.document_end_extend(buffer)\nMoves the caret to the end of the buffer, extending the selected text to the\nnew position.\n@param buffer A buffer. +document_end_extend buffer.document_end_extend(buffer)\nMoves the caret to the end of the buffer, extending the selected text to the new position.\n@param buffer A buffer. document_start buffer.document_start(buffer)\nMoves the caret to the beginning of the buffer.\n@param buffer A buffer. -document_start_extend buffer.document_start_extend(buffer)\nMoves the caret to the beginning of the buffer, extending the selected text\nto the new position.\n@param buffer A buffer. +document_start_extend buffer.document_start_extend(buffer)\nMoves the caret to the beginning of the buffer, extending the selected text to the new position.\n@param buffer A buffer. drop_selection_n buffer.drop_selection_n(buffer, n)\nDrops existing selection number *n*.\n@param buffer A buffer.\n@param n The number of the existing selection. -dropdown ui.dialogs.dropdown(options)\nPrompts the user with a drop-down item selection dialog defined by dialog\noptions table *options*, returning the selected button's index along with the\nindex of the selected item.\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the selected item's text.\nIf the dialog closed due to *options*.`exit_onchange`, returns `4` along with\neither the selected item's index or its text. If the dialog timed out,\nreturns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or\n`"delete"`.\n@param options Table of key-value option pairs for the drop-down dialog.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `items`: The list of string items to show in the drop-down.\n * `button1`: The right-most button's label. The default value is\n `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2`\n to be set.\n * `exit_onchange`: Close the dialog after selecting a new item. The default\n value is `false`.\n * `select`: The index of the initially selected list item. The default\n value is `1`.\n * `string_output`: Return the selected button's label (instead of its\n index) and the selected item's text (instead of its index). If no item\n was selected, returns the dialog's exit status (instead of its exit\n code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.dropdown{title = 'Select Encoding', width = 200,\n items = io.encodings, string_output = true}\n@return selected button or exit code, selected item -edge_color view.edge_color (number)\nThe color, in "0xBBGGRR" format, of the single edge or background for long\nlines according to `view.edge_mode`. +dropdown ui.dialogs.dropdown(options)\nPrompts the user with a drop-down item selection dialog defined by dialog options table\n*options*, returning the selected button's index along with the index of the selected item.\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\nselected item's text. If the dialog closed due to *options*.`exit_onchange`, returns `4`\nalong with either the selected item's index or its text. If the dialog timed out, returns\n`0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the drop-down dialog.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `items`: The list of string items to show in the drop-down.\n * `button1`: The right-most button's label. The default value is `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2` to be set.\n * `exit_onchange`: Close the dialog after selecting a new item. The default value is `false`.\n * `select`: The index of the initially selected list item. The default value is `1`.\n * `string_output`: Return the selected button's label (instead of its index) and the selected\n item's text (instead of its index). If no item was selected, returns the dialog's exit\n status (instead of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.dropdown{title = 'Select Encoding', width = 200, items = io.encodings,\n string_output = true}\n@return selected button or exit code, selected item +edge_color view.edge_color (number)\nThe color, in "0xBBGGRR" format, of the single edge or background for long lines according\nto `view.edge_mode`. edge_column view.edge_column (number)\nThe column number to mark long lines at. -edge_mode view.edge_mode (number)\nThe long line mark mode.\n\n* `view.EDGE_NONE`\n Long lines are not marked.\n* `view.EDGE_LINE`\n Draw a single vertical line whose color is `view.edge_color` at\n column `view.edge_column`.\n* `view.EDGE_BACKGROUND`\n Change the background color of text after column `view.edge_column`\n to `view.edge_color`.\n* `view.EDGE_MULTILINE`\n Draw vertical lines whose colors and columns are defined by calls to\n `view:multi_edge_add_line()`. +edge_mode view.edge_mode (number)\nThe long line mark mode.\n\n* `view.EDGE_NONE`\n Long lines are not marked.\n* `view.EDGE_LINE`\n Draw a single vertical line whose color is `view.edge_color` at column\n `view.edge_column`.\n* `view.EDGE_BACKGROUND`\n Change the background color of text after column `view.edge_column` to\n `view.edge_color`.\n* `view.EDGE_MULTILINE`\n Draw vertical lines whose colors and columns are defined by calls to\n `view:multi_edge_add_line()`. edit_toggle_overtype buffer.edit_toggle_overtype(buffer)\nToggles `buffer.overtype`.\n@param buffer A buffer. editing textadept.editing (module)\nEditing features for Textadept. -editing_keys ui.command_entry.editing_keys (table)\nA metatable with typical platform-specific key bindings for text entries.\nThis metatable may be used to add basic editing and movement keys to command\nentry modes. It is automatically added to command entry modes unless a\nmetatable was previously set. -embed lexer.embed(lexer, child, start_rule, end_rule)\nEmbeds child lexer *child* in parent lexer *lexer* using patterns\n*start_rule* and *end_rule*, which signal the beginning and end of the\nembedded lexer, respectively.\n@param lexer The parent lexer.\n@param child The child lexer.\n@param start_rule The pattern that signals the beginning of the embedded\n lexer.\n@param end_rule The pattern that signals the end of the embedded lexer.\n@usage html:embed(css, css_start_rule, css_end_rule)\n@usage html:embed(lex, php_start_rule, php_end_rule) -- from php lexer -emit events.emit(event, ...)\nSequentially calls all handler functions for event *event* with the given\narguments.\n*event* may be any arbitrary string and does not need to have been previously\ndefined. If any handler explicitly returns a value that is not `nil`,\n`emit()` returns that value and ceases to call subsequent handlers. This is\nuseful for stopping the propagation of an event like a keypress after it has\nbeen handled, or for passing back values from handlers.\n@param event The string event name.\n@param ... Arguments passed to the handler.\n@usage events.emit('my_event', 'my message')\n@return `nil` unless any any handler explicitly returned a non-`nil` value;\n otherwise returns that value +editing_keys ui.command_entry.editing_keys (table)\nA metatable with typical platform-specific key bindings for text entries.\nThis metatable may be used to add basic editing and movement keys to command entry modes. It\nis automatically added to command entry modes unless a metatable was previously set. +embed lexer.embed(lexer, child, start_rule, end_rule)\nEmbeds child lexer *child* in parent lexer *lexer* using patterns *start_rule* and *end_rule*,\nwhich signal the beginning and end of the embedded lexer, respectively.\n@param lexer The parent lexer.\n@param child The child lexer.\n@param start_rule The pattern that signals the beginning of the embedded lexer.\n@param end_rule The pattern that signals the end of the embedded lexer.\n@usage html:embed(css, css_start_rule, css_end_rule)\n@usage html:embed(lex, php_start_rule, php_end_rule) -- from php lexer +emit events.emit(event, ...)\nSequentially calls all handler functions for event *event* with the given arguments.\n*event* may be any arbitrary string and does not need to have been previously defined. If\nany handler explicitly returns a value that is not `nil`, `emit()` returns that value and\nceases to call subsequent handlers. This is useful for stopping the propagation of an event\nlike a keypress after it has been handled, or for passing back values from handlers.\n@param event The string event name.\n@param ... Arguments passed to the handler.\n@usage events.emit('my_event', 'my message')\n@return `nil` unless any any handler explicitly returned a non-`nil` value; otherwise returns\n that value empty_undo_buffer buffer.empty_undo_buffer(buffer)\nDeletes the undo and redo history.\n@param buffer A buffer. -enclose textadept.editing.enclose(left, right)\nEncloses the selected text or the current word within strings *left* and\n*right*, taking multiple selections into account.\n@param left The left part of the enclosure.\n@param right The right part of the enclosure. +enclose textadept.editing.enclose(left, right)\nEncloses the selected text or the current word within strings *left* and *right*, taking\nmultiple selections into account.\n@param left The left part of the enclosure.\n@param right The right part of the enclosure. encoding buffer.encoding (string or nil)\nThe string encoding of the file, or `nil` for binary files. -encodings io.encodings (table)\nList of encodings to attempt to decode files as.\nYou should add to this list if you get a "Conversion failed" error when\ntrying to open a file whose encoding is not recognized. Valid encodings are\nGNU iconv's encodings and include:\n\n * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,\n KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},\n Mac{Roman,CentralEurope,Iceland,Croatian,Romania},\n Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.\n * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,\n UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA. +encodings io.encodings (table)\nList of encodings to attempt to decode files as.\nYou should add to this list if you get a "Conversion failed" error when trying to open a file\nwhose encoding is not recognized. Valid encodings are GNU iconv's encodings and include:\n\n * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R,\n KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},\n Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, Mac{Cyrillic,Ukraine,Greek,Turkish},\n Macintosh.\n * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16, UTF-16BE,\n UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA. end_at_last_line view.end_at_last_line (bool)\nDisable scrolling past the last line.\nThe default value is `true`. -end_styled buffer.end_styled (number, Read-only)\nThe current styling position or the last correctly styled character's\nposition. +end_styled buffer.end_styled (number, Read-only)\nThe current styling position or the last correctly styled character's position. end_undo_action buffer.end_undo_action(buffer)\nEnds a sequence of actions to be undone or redone as a single action.\n@param buffer A buffer. ensure_visible view.ensure_visible(view, line)\nEnsures line number *line* is visible by expanding any fold points hiding it.\n@param view A view.\n@param line The line number in *view* to ensure visible. -ensure_visible_enforce_policy view.ensure_visible_enforce_policy(view, line)\nEnsures line number *line* is visible by expanding any fold points hiding it\nbased on the vertical caret policy previously defined in\n`view.set_visible_policy()`.\n@param view A view.\n@param line The line number in *view* to ensure visible. +ensure_visible_enforce_policy view.ensure_visible_enforce_policy(view, line)\nEnsures line number *line* is visible by expanding any fold points hiding it based on the\nvertical caret policy previously defined in `view.set_visible_policy()`.\n@param view A view.\n@param line The line number in *view* to ensure visible. eol_annotation_clear_all buffer.eol_annotation_clear_all(buffer)\nClears EOL annotations from all lines.\n@param buffer A buffer. -eol_annotation_style buffer.eol_annotation_style (table)\nTable of style numbers for EOL annotation text per line number.\nOnly some style attributes are active in annotations: font,\nsize/size_fractional, bold/weight, italics, fore, back, and character_set. +eol_annotation_style buffer.eol_annotation_style (table)\nTable of style numbers for EOL annotation text per line number.\nOnly some style attributes are active in annotations: font, size/size_fractional, bold/weight,\nitalics, fore, back, and character_set. eol_annotation_text buffer.eol_annotation_text (table)\nTable of EOL annotation text per line number. eol_annotation_visible view.eol_annotation_visible (number)\nThe EOL annotation visibility mode.\n\n* `view.EOLANNOTATION_HIDDEN`\n EOL Annotations are invisible.\n* `view.EOLANNOTATION_STANDARD`\n Draw EOL annotations no decoration.\n* `view.EOLANNOTATION_BOXED`\n Draw EOL annotations outlined with a box.\n\nThe default value is `view.EOLANNOTATION_HIDDEN`. -eol_mode buffer.eol_mode (number)\nThe current end of line mode. Changing the current mode does not convert\nany of the buffer's existing end of line characters.\nUse `buffer.convert_eols()` to do so.\n\n* `buffer.EOL_CRLF`\n Carriage return with line feed ("\r\\n").\n* `buffer.EOL_CR`\n Carriage return ("\r").\n* `buffer.EOL_LF`\n Line feed ("\\n").\n\nThe default value is `buffer.EOL_CRLF` on Windows platforms,\n`buffer.EOL_LF` otherwise. -error_patterns textadept.run.error_patterns (table)\nMap of file extensions and lexer names to their associated lists of string\npatterns that match warning and error messages emitted by compile and run\ncommands for those file extensions and lexers.\nPatterns match single lines and contain captures for a filename, line number,\ncolumn number (optional), and warning or error message (optional).\nDouble-clicking a warning or error message takes the user to the source of\nthat warning/error.\nNote: `(.-)` captures in patterns are interpreted as filenames; `(%d+)`\ncaptures are interpreted as line numbers first, and then column numbers; and\nany other capture is treated as warning/error message text. -events _G.events (module)\nTextadept's core event structure and handlers.\n\nTextadept emits events when you do things like create a new buffer, press a\nkey, click on a menu, etc. You can even emit events yourself using Lua. Each\nevent has a set of event handlers, which are simply Lua functions called in\nthe order they were connected to an event. For example, if you created a\nmodule that needs to do something each time Textadept creates a new buffer,\nconnect a Lua function to the `events.BUFFER_NEW` event:\n\n events.connect(events.BUFFER_NEW, function()\n -- Do something here.\n end)\n\nEvents themselves are nothing special. You do not have to declare one before\nusing it. Events are simply strings containing arbitrary event names. When\neither you or Textadept emits an event, Textadept runs all event handlers\nconnected to the event, passing any given arguments to the event's handler\nfunctions. If an event handler explicitly returns a value that is not `nil`,\nTextadept will not call subsequent handlers. This is useful if you want to\nstop the propagation of an event like a keypress if your event handler\nhandled it, or if you want to use the event framework to pass values.\n +eol_mode buffer.eol_mode (number)\nThe current end of line mode.\nChanging the current mode does not convert any of the buffer's existing end of line\ncharacters. Use `buffer.convert_eols()` to do so.\n\n* `buffer.EOL_CRLF`\n Carriage return with line feed ("\r\\n").\n* `buffer.EOL_CR`\n Carriage return ("\r").\n* `buffer.EOL_LF`\n Line feed ("\\n").\n\nThe default value is `buffer.EOL_CRLF` on Windows platforms, `buffer.EOL_LF` otherwise. +error_patterns textadept.run.error_patterns (table)\nMap of file extensions and lexer names to their associated lists of string patterns that\nmatch warning and error messages emitted by compile and run commands for those file extensions\nand lexers.\nPatterns match single lines and contain captures for a filename, line number, column number\n(optional), and warning or error message (optional). Double-clicking a warning or error\nmessage takes the user to the source of that warning/error.\nNote: `(.-)` captures in patterns are interpreted as filenames; `(%d+)` captures are\ninterpreted as line numbers first, and then column numbers; and any other capture is treated\nas warning/error message text. +events _G.events (module)\nTextadept's core event structure and handlers.\n\nTextadept emits events when you do things like create a new buffer, press a key, click on\na menu, etc. You can even emit events yourself using Lua. Each event has a set of event\nhandlers, which are simply Lua functions called in the order they were connected to an\nevent. For example, if you created a module that needs to do something each time Textadept\ncreates a new buffer, connect a Lua function to the `events.BUFFER_NEW` event:\n\n events.connect(events.BUFFER_NEW, function()\n -- Do something here.\n end)\n\nEvents themselves are nothing special. You do not have to declare one before using it. Events\nare simply strings containing arbitrary event names. When either you or Textadept emits an\nevent, Textadept runs all event handlers connected to the event, passing any given arguments\nto the event's handler functions. If an event handler explicitly returns a value that is not\n`nil`, Textadept will not call subsequent handlers. This is useful if you want to stop the\npropagation of an event like a keypress if your event handler handled it, or if you want to\nuse the event framework to pass values.\n events _SCINTILLA.events (table)\nMap of Scintilla event IDs to tables of event names and event parameters. -expr_types _M.lua.expr_types (table)\nMap of expression patterns to their types.\nUsed for type-hinting when showing autocompletions for variables.\nExpressions are expected to match after the '=' sign of a statement. +expr_types _M.lua.expr_types (table)\nMap of expression patterns to their types.\nUsed for type-hinting when showing autocompletions for variables. Expressions are expected\nto match after the '=' sign of a statement. extend lexer.extend (pattern)\nA pattern that matches any ASCII extended character (codes 0 to 255). -extensions textadept.file_types.extensions (table)\nMap of file extensions to their associated lexer names.\nIf the file type is not recognized by its first-line, each file extension is\nmatched against the file's extension. +extensions textadept.file_types.extensions (table)\nMap of file extensions to their associated lexer names.\nIf the file type is not recognized by its first-line, each file extension is matched against\nthe file's extension. extra_ascent view.extra_ascent (number)\nThe amount of pixel padding above lines.\nThe default value is `0`. extra_descent view.extra_descent (number)\nThe amount of pixel padding below lines.\nThe default is `0`. file_types textadept.file_types (module)\nHandles file type detection for Textadept. filename buffer.filename (string)\nThe absolute file path associated with the buffer. -filesave ui.dialogs.filesave(options)\nPrompts the user with a file save dialog defined by dialog options table\n*options*, returning the string file chosen.\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the dialog.\n\n * `title`: The dialog's title text.\n * `with_directory`: The initial filesystem directory to show.\n * `with_file`: The initially chosen filename. This option requires\n `with_directory` to be set.\n * `with_extension`: The list of extensions selectable files must have.\n * `no_create_directories`: Prevent the user from creating new directories.\n The default value is `false`.\n@return filename or nil -fileselect ui.dialogs.fileselect(options)\nPrompts the user with a file selection dialog defined by dialog options\ntable *options*, returning the string file selected.\nIf *options*.`select_multiple` is `true`, returns the list of files selected.\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the dialog.\n\n * `title`: The dialog's title text.\n * `with_directory`: The initial filesystem directory to show.\n * `with_file`: The initially selected filename. This option requires\n `with_directory` to be set.\n * `with_extension`: The list of extensions selectable files must have.\n * `select_multiple`: Allow the user to select multiple files. The default\n value is `false`.\n * `select_only_directories`: Only allow the user to select directories. The\n default value is `false`.\n@usage ui.dialogs.fileselect{title = 'Open C File', with_directory = _HOME,\n with_extension = {'c', 'h'}, select_multiple = true}\n@return filename, list of filenames, or nil -filter_through textadept.editing.filter_through(command)\nPasses the selected text or all buffer text to string shell command *command*\nas standard input (stdin) and replaces the input text with the command's\nstandard output (stdout). *command* may contain shell pipes ('|').\nStandard input is as follows:\n\n1. If no text is selected, the entire buffer is used.\n2. If text is selected and spans a single line, only the selected text is\nused.\n3. If text is selected and spans multiple lines, all text on the lines that\nhave text selected is passed as stdin. However, if the end of the selection\nis at the beginning of a line, only the line ending delimiters from the\nprevious line are included. The rest of the line is excluded.\n@param command The Linux, BSD, macOS, or Windows shell command to filter text\n through. May contain pipes. -filteredlist ui.dialogs.filteredlist(options)\nPrompts the user with a filtered list item selection dialog defined by dialog\noptions table *options*, returning the selected button's index along with the\nindex or indices of the selected item or items (depending on whether or not\n*options*.`select_multiple` is `true`).\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the text of the selected item or items.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\nSpaces in the filter text are treated as wildcards.\n@param options Table of key-value option pairs for the filtered list dialog.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text.\n * `text`: The dialog's initial input text.\n * `columns`: The list of string column names for list rows.\n * `items`: The list of string items to show in the filtered list.\n * `button1`: The right-most button's label. The default value is\n `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2`\n to be set.\n * `select_multiple`: Allow the user to select multiple items. The default\n value is `false`.\n * `search_column`: The column number to filter the input text against. The\n default value is `1`. This option requires `columns` to be set and\n contain at least *n* column names.\n * `output_column`: The column number to use for `string_output`. The\n default value is `1`. This option requires `columns` to be set and\n contain at least *n* column names.\n * `string_output`: Return the selected button's label (instead of its\n index) and the selected item's text (instead of its index). If no item\n was selected, returns the dialog's exit status (instead of its exit\n code). The default value is `false`.\n * `width`: The dialog's pixel width. The default width stretches nearly the\n width of Textadept's window.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'},\n items = {'a', 'b', 'c', 'd'}}\n@return selected button or exit code, selected item or list of selected items +filesave ui.dialogs.filesave(options)\nPrompts the user with a file save dialog defined by dialog options table *options*, returning\nthe string file chosen.\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the dialog.\n\n * `title`: The dialog's title text.\n * `with_directory`: The initial filesystem directory to show.\n * `with_file`: The initially chosen filename. This option requires `with_directory` to be set.\n * `with_extension`: The list of extensions selectable files must have.\n * `no_create_directories`: Prevent the user from creating new directories. The default\n value is `false`.\n@return filename or nil +fileselect ui.dialogs.fileselect(options)\nPrompts the user with a file selection dialog defined by dialog options table *options*,\nreturning the string file selected.\nIf *options*.`select_multiple` is `true`, returns the list of files selected. If the user\ncanceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the dialog.\n\n * `title`: The dialog's title text.\n * `with_directory`: The initial filesystem directory to show.\n * `with_file`: The initially selected filename. This option requires `with_directory`\n to be set.\n * `with_extension`: The list of extensions selectable files must have.\n * `select_multiple`: Allow the user to select multiple files. The default value is `false`.\n * `select_only_directories`: Only allow the user to select directories. The default value is\n `false`.\n@usage ui.dialogs.fileselect{title = 'Open C File', with_directory = _HOME,\n with_extension = {'c', 'h'}, select_multiple = true}\n@return filename, list of filenames, or nil +filter_through textadept.editing.filter_through(command)\nPasses the selected text or all buffer text to string shell command *command* as standard input\n(stdin) and replaces the input text with the command's standard output (stdout). *command*\nmay contain shell pipes ('|').\nStandard input is as follows:\n\n1. If no text is selected, the entire buffer is used.\n2. If text is selected and spans a single line, only the selected text is used.\n3. If text is selected and spans multiple lines, all text on the lines that have text selected\n is passed as stdin. However, if the end of the selection is at the beginning of a line,\n only the line ending delimiters from the previous line are included. The rest of the line\n is excluded.\n@param command The Linux, BSD, macOS, or Windows shell command to filter text through. May\n contain pipes. +filteredlist ui.dialogs.filteredlist(options)\nPrompts the user with a filtered list item selection dialog defined by dialog options table\n*options*, returning the selected button's index along with the index or indices of the\nselected item or items (depending on whether or not *options*.`select_multiple` is `true`).\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\ntext of the selected item or items. If the dialog timed out, returns `0` or `"timeout"`. If\nthe user canceled the dialog, returns `-1` or `"delete"`.\nSpaces in the filter text are treated as wildcards.\n@param options Table of key-value option pairs for the filtered list dialog.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text.\n * `text`: The dialog's initial input text.\n * `columns`: The list of string column names for list rows.\n * `items`: The list of string items to show in the filtered list.\n * `button1`: The right-most button's label. The default value is `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2` to be set.\n * `select_multiple`: Allow the user to select multiple items. The default value is `false`.\n * `search_column`: The column number to filter the input text against. The default value is\n `1`. This option requires `columns` to be set and contain at least *n* column names.\n * `output_column`: The column number to use for `string_output`. The default value is\n `1`. This option requires `columns` to be set and contain at least *n* column names.\n * `string_output`: Return the selected button's label (instead of its index) and the selected\n item's text (instead of its index). If no item was selected, returns the dialog's exit\n status (instead of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width. The default width stretches nearly the width of\n Textadept's window.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'},\n items = {'a', 'b', 'c', 'd'}}\n@return selected button or exit code, selected item or list of selected items find ui.find (module)\nTextadept's Find & Replace pane. -find_column buffer.find_column(buffer, line, column)\nReturns the position of column number *column* on line number *line* (taking\ntab and multi-byte characters into account), or the position at the end of\nline *line*.\n@param buffer A buffer.\n@param line The line number in *buffer* to use.\n@param column The column number to use. +find_column buffer.find_column(buffer, line, column)\nReturns the position of column number *column* on line number *line* (taking tab and multi-byte\ncharacters into account), or the position at the end of line *line*.\n@param buffer A buffer.\n@param line The line number in *buffer* to use.\n@param column The column number to use. find_entry_text ui.find.find_entry_text (string)\nThe text in the "Find" entry. -find_in_files ui.find.find_in_files(dir, filter)\nSearches directory *dir* or the user-specified directory for files that match\nsearch text and search options (subject to optional filter *filter*), and\nprints the results to a buffer titled "Files Found", highlighting found text.\nUse the `find_entry_text`, `match_case`, `whole_word`, and `regex` fields to\nset the search text and option flags, respectively.\nA filter determines which files to search in, with the default filter being\n`ui.find.find_in_files_filters[dir]` (if it exists) or `lfs.default_filter`.\nA filter consists of Lua patterns that match file and directory paths to\ninclude or exclude. Patterns are inclusive by default. Exclusive patterns\nbegin with a '!'. If no inclusive patterns are given, any filename is\ninitially considered. As a convenience, file extensions can be specified\nliterally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/'\nalso matches the Windows directory separator ('[/\\]' is not needed).\nIf *filter* is `nil`, the filter from the `ui.find.find_in_files_filters`\ntable for *dir* is used. If that filter does not exist, `lfs.default_filter`\nis used.\n@param dir Optional directory path to search. If `nil`, the user is prompted\n for one.\n@param filter Optional filter for files and directories to exclude. The\n default value is `lfs.default_filter` unless a filter for *dir* is defined\n in `ui.find.find_in_files_filters`.\n@see find_in_files_filters -find_in_files_filters ui.find.find_in_files_filters (table)\nMap of directory paths to filters used in `ui.find.find_in_files()`.\nThis table is updated when the user manually specifies a filter in the\n"Filter" entry during an "In files" search.\n@see find_in_files +find_in_files ui.find.find_in_files(dir, filter)\nSearches directory *dir* or the user-specified directory for files that match search text\nand search options (subject to optional filter *filter*), and prints the results to a buffer\ntitled "Files Found", highlighting found text.\nUse the `find_entry_text`, `match_case`, `whole_word`, and `regex` fields to set the search\ntext and option flags, respectively.\nA filter determines which files to search in, with the default filter being\n`ui.find.find_in_files_filters[dir]` (if it exists) or `lfs.default_filter`. A filter consists\nof Lua patterns that match file and directory paths to include or exclude. Patterns are\ninclusive by default. Exclusive patterns begin with a '!'. If no inclusive patterns are given,\nany filename is initially considered. As a convenience, file extensions can be specified\nliterally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the\nWindows directory separator ('[/\\]' is not needed). If *filter* is `nil`, the filter from\nthe `ui.find.find_in_files_filters` table for *dir* is used. If that filter does not exist,\n`lfs.default_filter` is used.\n@param dir Optional directory path to search. If `nil`, the user is prompted for one.\n@param filter Optional filter for files and directories to exclude. The default value is\n `lfs.default_filter` unless a filter for *dir* is defined in `ui.find.find_in_files_filters`.\n@see find_in_files_filters +find_in_files_filters ui.find.find_in_files_filters (table)\nMap of directory paths to filters used in `ui.find.find_in_files()`.\nThis table is updated when the user manually specifies a filter in the "Filter" entry during\nan "In files" search.\n@see find_in_files find_label_text ui.find.find_label_text (string, Write-only)\nThe text of the "Find" label.\nThis is primarily used for localization. find_next ui.find.find_next()\nMimics pressing the "Find Next" button. find_next_button_text ui.find.find_next_button_text (string, Write-only)\nThe text of the "Find Next" button.\nThis is primarily used for localization. @@ -526,119 +526,119 @@ first_visible_line view.first_visible_line (number)\nThe line number of the line float lexer.float (pattern)\nA pattern that matches a floating point number. focus ui.command_entry.focus()\nOpens the command entry. focus ui.find.focus(options)\nDisplays and focuses the Find & Replace Pane.\n@param options Optional table of `ui.find` field options to initially set. -fold lexer.fold(lexer, text, start_pos, start_line, start_level)\nDetermines fold points in a chunk of text *text* using lexer *lexer*,\nreturning a table of fold levels associated with line numbers.\n*text* starts at position *start_pos* on line number *start_line* with a\nbeginning fold level of *start_level* in the buffer.\n@param lexer The lexer to fold text with.\n@param text The text in the buffer to fold.\n@param start_pos The position in the buffer *text* starts at, counting from\n 1.\n@param start_line The line number *text* starts on, counting from 1.\n@param start_level The fold level *text* starts on.\n@return table of fold levels associated with line numbers. -fold_all view.fold_all(view, action)\nContracts, expands, or toggles all fold points, depending on *action*.\nWhen toggling, the state of the first fold point determines whether to\nexpand or contract.\n@param view A view.\n@param action The fold action to perform. Valid values are:\n * `view.FOLDACTION_CONTRACT`\n * `view.FOLDACTION_EXPAND`\n * `view.FOLDACTION_TOGGLE` +fold lexer.fold(lexer, text, start_pos, start_line, start_level)\nDetermines fold points in a chunk of text *text* using lexer *lexer*, returning a table of\nfold levels associated with line numbers.\n*text* starts at position *start_pos* on line number *start_line* with a beginning fold\nlevel of *start_level* in the buffer.\n@param lexer The lexer to fold text with.\n@param text The text in the buffer to fold.\n@param start_pos The position in the buffer *text* starts at, counting from 1.\n@param start_line The line number *text* starts on, counting from 1.\n@param start_level The fold level *text* starts on.\n@return table of fold levels associated with line numbers. +fold_all view.fold_all(view, action)\nContracts, expands, or toggles all fold points, depending on *action*.\nWhen toggling, the state of the first fold point determines whether to expand or contract.\n@param view A view.\n@param action The fold action to perform. Valid values are:\n * `view.FOLDACTION_CONTRACT`\n * `view.FOLDACTION_EXPAND`\n * `view.FOLDACTION_TOGGLE` fold_by_indentation lexer.fold_by_indentation (boolean)\nWhether or not to fold based on indentation level if a lexer does not have\na folder.\nSome lexers automatically enable this option. It is disabled by default.\nThis is an alias for `lexer.property['fold.by.indentation'] = '1|0'`. -fold_children view.fold_children(view, line, action)\nContracts, expands, or toggles the fold point on line number *line*, as well\nas all of its children, depending on *action*.\n@param view A view.\n@param line The line number in *view* to set the fold states for.\n@param action The fold action to perform. Valid values are:\n * `view.FOLDACTION_CONTRACT`\n * `view.FOLDACTION_EXPAND`\n * `view.FOLDACTION_TOGGLE` +fold_children view.fold_children(view, line, action)\nContracts, expands, or toggles the fold point on line number *line*, as well as all of its\nchildren, depending on *action*.\n@param view A view.\n@param line The line number in *view* to set the fold states for.\n@param action The fold action to perform. Valid values are:\n * `view.FOLDACTION_CONTRACT`\n * `view.FOLDACTION_EXPAND`\n * `view.FOLDACTION_TOGGLE` fold_compact lexer.fold_compact (boolean)\nWhether or not blank lines after an ending fold point are included in that\nfold.\nThis option is disabled by default.\nThis is an alias for `lexer.property['fold.compact'] = '1|0'`. -fold_consecutive_lines lexer.fold_consecutive_lines(prefix)\nReturns for `lexer.add_fold_point()` the parameters needed to fold\nconsecutive lines that start with string *prefix*.\n@param prefix The prefix string (e.g. a line comment).\n@usage lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('--'))\n@usage lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('//'))\n@usage lex:add_fold_point(\n lexer.KEYWORD, lexer.fold_consecutive_lines('import')) +fold_consecutive_lines lexer.fold_consecutive_lines(prefix)\nReturns for `lexer.add_fold_point()` the parameters needed to fold consecutive lines that\nstart with string *prefix*.\n@param prefix The prefix string (e.g. a line comment).\n@usage lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('--'))\n@usage lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('//'))\n@usage lex:add_fold_point(lexer.KEYWORD, lexer.fold_consecutive_lines('import')) fold_display_text_style view.fold_display_text_style (number)\nThe fold display text mode.\n\n* `view.FOLDDISPLAYTEXT_HIDDEN`\n Fold display text is not shown.\n* `view.FOLDDISPLAYTEXT_STANDARD`\n Fold display text is shown with no decoration.\n* `view.FOLDDISPLAYTEXT_BOXED`\n Fold display text is shown outlined with a box.\n\nThe default value is `view.FOLDDISPLAYTEXT_HIDDEN`. -fold_expanded view.fold_expanded (table)\nTable of flags per line number that indicate whether or not fold points are\nexpanded for those line numbers.\nSetting expanded fold states does not toggle folds; it only updates fold\nmargin markers. Use `view.toggle_fold()` instead. +fold_expanded view.fold_expanded (table)\nTable of flags per line number that indicate whether or not fold points are expanded for\nthose line numbers.\nSetting expanded fold states does not toggle folds; it only updates fold margin markers. Use\n`view.toggle_fold()` instead. fold_flags view.fold_flags (number, Read-only)\nBit-mask of folding lines to draw in the buffer.\n\n* `view.FOLDFLAG_LINEBEFORE_EXPANDED`\n Draw lines above expanded folds.\n* `view.FOLDFLAG_LINEBEFORE_CONTRACTED`\n Draw lines above collapsed folds.\n* `view.FOLDFLAG_LINEAFTER_EXPANDED`\n Draw lines below expanded folds.\n* `view.FOLDFLAG_LINEAFTER_CONTRACTED`\n Draw lines below collapsed folds.\n* `view.FOLDFLAG_LEVELNUMBERS`\n Show hexadecimal fold levels in line margins.\n This option cannot be combined with `FOLDFLAG_LINESTATE`.\n* `view.FOLDFLAG_LINESTATE`\n Show line state in line margins.\n This option cannot be combined with `FOLDFLAG_LEVELNUMBERS`.\n\nThe default value is `0`. -fold_level buffer.fold_level (table)\nTable of fold level bit-masks per line number.\nFold level masks comprise of an integer level combined with any of the\nfollowing bit flags:\n\n* `buffer.FOLDLEVELBASE`\n The initial fold level.\n* `buffer.FOLDLEVELWHITEFLAG`\n The line is blank.\n* `buffer.FOLDLEVELHEADERFLAG`\n The line is a header, or fold point. -fold_level lexer.fold_level (table, Read-only)\nTable of fold level bit-masks for line numbers starting from 1.\nFold level masks are composed of an integer level combined with any of the\nfollowing bits:\n\n* `lexer.FOLD_BASE`\n The initial fold level.\n* `lexer.FOLD_BLANK`\n The line is blank.\n* `lexer.FOLD_HEADER`\n The line is a header, or fold point. -fold_line view.fold_line(view, line, action)\nContracts, expands, or toggles the fold point on line number *line*,\ndepending on *action*.\n@param view A view.\n@param line The line number in *view* to set the fold state for.\n@param action The fold action to perform. Valid values are:\n * `view.FOLDACTION_CONTRACT`\n * `view.FOLDACTION_EXPAND`\n * `view.FOLDACTION_TOGGLE` -fold_line_groups lexer.fold_line_groups (boolean)\nWhether or not to fold multiple, consecutive line groups (such as line\ncomments and import statements) and only show the top line.\nThis option is disabled by default.\nThis is an alias for `lexer.property['fold.line.groups'] = '1|0'`. -fold_on_zero_sum_lines lexer.fold_on_zero_sum_lines (boolean)\nWhether or not to mark as a fold point lines that contain both an ending\nand starting fold point. For example, `} else {` would be marked as a fold\npoint.\nThis option is disabled by default.\nThis is an alias for `lexer.property['fold.on.zero.sum.lines'] = '1|0'`. +fold_level buffer.fold_level (table)\nTable of fold level bit-masks per line number.\nFold level masks comprise of an integer level combined with any of the following bit flags:\n\n* `buffer.FOLDLEVELBASE`\n The initial fold level.\n* `buffer.FOLDLEVELWHITEFLAG`\n The line is blank.\n* `buffer.FOLDLEVELHEADERFLAG`\n The line is a header, or fold point. +fold_level lexer.fold_level (table, Read-only)\nTable of fold level bit-masks for line numbers starting from 1.\nFold level masks are composed of an integer level combined with any of the following bits:\n\n* `lexer.FOLD_BASE`\n The initial fold level.\n* `lexer.FOLD_BLANK`\n The line is blank.\n* `lexer.FOLD_HEADER`\n The line is a header, or fold point. +fold_line view.fold_line(view, line, action)\nContracts, expands, or toggles the fold point on line number *line*, depending on *action*.\n@param view A view.\n@param line The line number in *view* to set the fold state for.\n@param action The fold action to perform. Valid values are:\n * `view.FOLDACTION_CONTRACT`\n * `view.FOLDACTION_EXPAND`\n * `view.FOLDACTION_TOGGLE` +fold_line_groups lexer.fold_line_groups (boolean)\nWhether or not to fold multiple, consecutive line groups (such as line comments and import\nstatements) and only show the top line.\nThis option is disabled by default.\nThis is an alias for `lexer.property['fold.line.groups'] = '1|0'`. +fold_on_zero_sum_lines lexer.fold_on_zero_sum_lines (boolean)\nWhether or not to mark as a fold point lines that contain both an ending and starting fold\npoint. For example, `} else {` would be marked as a fold point.\nThis option is disabled by default. This is an alias for\n`lexer.property['fold.on.zero.sum.lines'] = '1|0'`. fold_parent buffer.fold_parent (table, Read-only)\nTable of fold point line numbers per child line number.\nA line number of `-1` means no line was found. folding lexer.folding (boolean)\nWhether or not folding is enabled for the lexers that support it.\nThis option is disabled by default.\nThis is an alias for `lexer.property['fold'] = '1|0'`. -fontselect ui.dialogs.fontselect(options)\nPrompts the user with a font selection dialog defined by dialog options\ntable *options*, returning the font selected (including style and size).\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the option select dialog.\n\n * `title`: The dialog's title text.\n * `text`: The font preview text.\n * `font_name`: The initially selected font name.\n * `font_size`: The initially selected font size. The default value is `12`.\n * `font_style`: The initially selected font style. The available options\n are `"regular"`, `"bold"`, `"italic"`, and `"bold italic"`. The default\n value is `"regular"`.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n@usage ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace',\n font_size = 10}\n@return selected font, including style and size +fontselect ui.dialogs.fontselect(options)\nPrompts the user with a font selection dialog defined by dialog options table *options*,\nreturning the font selected (including style and size).\nIf the user canceled the dialog, returns `nil`.\n@param options Table of key-value option pairs for the option select dialog.\n\n * `title`: The dialog's title text.\n * `text`: The font preview text.\n * `font_name`: The initially selected font name.\n * `font_size`: The initially selected font size. The default value is `12`.\n * `font_style`: The initially selected font style. The available options are `"regular"`,\n `"bold"`, `"italic"`, and `"bold italic"`. The default value is `"regular"`.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n@usage ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace', font_size = 10}\n@return selected font, including style and size forward textadept.history.forward()\nNavigates forwards through the current view's history. -functions _SCINTILLA.functions (table)\nMap of Scintilla function names to tables containing their IDs, return types,\nwParam types, and lParam types. Types are as follows:\n\n + `0`: Void.\n + `1`: Integer.\n + `2`: Length of the given lParam string.\n + `3`: Integer position.\n + `4`: Color, in "0xBBGGRR" format.\n + `5`: Boolean `true` or `false`.\n + `6`: Bitmask of Scintilla key modifiers and a key value.\n + `7`: String parameter.\n + `8`: String return value. +functions _SCINTILLA.functions (table)\nMap of Scintilla function names to tables containing their IDs, return types, wParam types,\nand lParam types. Types are as follows:\n\n + `0`: Void.\n + `1`: Integer.\n + `2`: Length of the given lParam string.\n + `3`: Integer position.\n + `4`: Color, in "0xBBGGRR" format.\n + `5`: Boolean `true` or `false`.\n + `6`: Bitmask of Scintilla key modifiers and a key value.\n + `7`: String parameter.\n + `8`: String return value. get_cur_line buffer.get_cur_line(buffer)\nReturns the current line's text and the caret's position on that line.\n@param buffer A buffer.\n@return string, number get_default_fold_display_text view.get_default_fold_display_text(view)\nReturns the default fold display text.\n@param view A view. -get_last_child buffer.get_last_child(buffer, line, level)\nReturns the line number of the last line after line number *line* whose fold\nlevel is greater than *level*.\nIf *level* is `-1`, returns the level of *line*.\n@param buffer A buffer.\n@param line The line number in *buffer* of a header line.\n@param level The fold level, or `-1` for the level of *line*. -get_lexer buffer.get_lexer(buffer, current)\nReturns the buffer's lexer name.\nIf *current* is `true`, returns the name of the lexer under the caret in\na multiple-language lexer.\n@param buffer A buffer.\n@param current Whether or not to get the lexer at the current caret position\n in multi-language lexers. The default is `false` and returns the parent\n lexer. +get_last_child buffer.get_last_child(buffer, line, level)\nReturns the line number of the last line after line number *line* whose fold level is greater\nthan *level*.\nIf *level* is `-1`, returns the level of *line*.\n@param buffer A buffer.\n@param line The line number in *buffer* of a header line.\n@param level The fold level, or `-1` for the level of *line*. +get_lexer buffer.get_lexer(buffer, current)\nReturns the buffer's lexer name.\nIf *current* is `true`, returns the name of the lexer under the caret in a multiple-language\nlexer.\n@param buffer A buffer.\n@param current Whether or not to get the lexer at the current caret position in multi-language\n lexers. The default is `false` and returns the parent lexer. get_line buffer.get_line(buffer, line)\nReturns the text on line number *line*, including end of line characters.\n@param buffer A buffer.\n@param line The line number in *buffer* to use.\n@return string, number -get_project_root io.get_project_root(path, submodule)\nReturns the root directory of the project that contains filesystem path\n*path*.\nIn order to be recognized, projects must be under version control. Recognized\nVCSes are Bazaar, Fossil, Git, Mercurial, and SVN.\n@param path Optional filesystem path to a project or a file contained within\n a project. The default value is the buffer's filename or the current\n working directory. This parameter may be omitted.\n@param submodule Optional flag that indicates whether or not to return the\n root of the current submodule (if applicable). The default value is\n `false`.\n@return string root or nil +get_project_root io.get_project_root(path, submodule)\nReturns the root directory of the project that contains filesystem path *path*.\nIn order to be recognized, projects must be under version control. Recognized VCSes are\nBazaar, Fossil, Git, Mercurial, and SVN.\n@param path Optional filesystem path to a project or a file contained within a project. The\n default value is the buffer's filename or the current working directory. This parameter\n may be omitted.\n@param submodule Optional flag that indicates whether or not to return the root of the\n current submodule (if applicable). The default value is `false`.\n@return string root or nil get_rule lexer.get_rule(lexer, id)\nReturns the rule identified by string *id*.\n@param lexer The lexer to fetch a rule from.\n@param id The id of the rule to fetch.\n@return pattern -get_sel_text buffer.get_sel_text(buffer)\nReturns the selected text.\nMultiple selections are included in order with no delimiters. Rectangular\nselections are included from top to bottom with end of line characters.\nVirtual space is not included.\n@param buffer A buffer.\n@return string, number -get_split_table ui.get_split_table()\nReturns a split table that contains Textadept's current split view structure.\nThis is primarily used in session saving.\n@return table of split views. Each split view entry is a table with 4\n fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either\n nested split view entries or the views themselves; `vertical` is a flag\n that indicates if the split is vertical or not; and `size` is the integer\n position of the split resizer. +get_sel_text buffer.get_sel_text(buffer)\nReturns the selected text.\nMultiple selections are included in order with no delimiters. Rectangular selections are\nincluded from top to bottom with end of line characters. Virtual space is not included.\n@param buffer A buffer.\n@return string, number +get_split_table ui.get_split_table()\nReturns a split table that contains Textadept's current split view structure.\nThis is primarily used in session saving.\n@return table of split views. Each split view entry is a table with 4 fields: `1`, `2`,\n `vertical`, and `size`. `1` and `2` have values of either nested split view entries or\n the views themselves; `vertical` is a flag that indicates if the split is vertical or not;\n and `size` is the integer position of the split resizer. get_text buffer.get_text(buffer)\nReturns the buffer's text.\n@param buffer A buffer. -goto_buffer view.goto_buffer(view, buffer)\nSwitches to buffer *buffer* or the buffer *buffer* number of buffers relative\nto the current one.\nEmits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events.\n@param view The view to switch buffers in.\n@param buffer A buffer or relative buffer number (typically 1 or -1).\n@see _G._BUFFERS\n@see events.BUFFER_BEFORE_SWITCH\n@see events.BUFFER_AFTER_SWITCH -goto_error textadept.run.goto_error(line_num, next)\nJumps to the source of the recognized compile/run warning or error on line\nnumber *line_num* in the message buffer.\nIf *line_num* is `nil`, jumps to the next or previous warning or error,\ndepending on boolean *next*. Displays an annotation with the warning or error\nmessage if possible.\n@param line_num Optional line number in the message buffer that contains the\n compile/run warning or error to go to. This parameter may be omitted\n completely.\n@param next Optional flag indicating whether to go to the next recognized\n warning/error or the previous one. Only applicable when *line_num* is\n `nil`.\n@see error_patterns -goto_file ui.goto_file(filename, split, preferred_view, sloppy)\nSwitches to the existing view whose buffer's filename is *filename*.\nIf no view was found and *split* is `true`, splits the current view in order\nto show the requested file. If *split* is `false`, shifts to the next or\n*preferred_view* view in order to show the requested file. If *sloppy* is\n`true`, requires only the basename of *filename* to match a buffer's\n`filename`. If the requested file was not found, it is opened in the desired\nview.\n@param filename The filename of the buffer to go to.\n@param split Optional flag that indicates whether or not to open the buffer\n in a split view if there is only one view. The default value is `false`.\n@param preferred_view Optional view to open the desired buffer in if the\n buffer is not visible in any other view.\n@param sloppy Optional flag that indicates whether or not to not match\n *filename* to `buffer.filename` exactly. When `true`, matches *filename* to\n only the last part of `buffer.filename` This is useful for run and compile\n commands which output relative filenames and paths instead of full ones and\n it is likely that the file in question is already open. The default value\n is `false`. -goto_file_found ui.find.goto_file_found(line_num, next)\nJumps to the source of the find in files search result on line number\n*line_num* in the buffer titled "Files Found" or, if *line_num* is `nil`,\njumps to the next or previous search result, depending on boolean *next*.\n@param line_num Optional line number in the files found buffer that contains\n the search result to go to. This parameter may be omitted completely.\n@param next Optional flag indicating whether to go to the next search result\n or the previous one. Only applicable when *line_num* is `nil`. -goto_line buffer.goto_line(buffer, line)\nMoves the caret to the beginning of line number *line* and scrolls it into\nview, event if *line* is hidden.\n@param buffer A buffer.\n@param line The line number in *buffer* to go to. -goto_line textadept.editing.goto_line(line)\nMoves the caret to the beginning of line number *line* or the user-specified\nline, ensuring *line* is visible.\n@param line Optional line number to go to. If `nil`, the user is prompted for\n one. -goto_mark textadept.bookmarks.goto_mark(next)\nPrompts the user to select a bookmarked line to move the caret to the\nbeginning of unless *next* is given.\nIf *next* is `true` or `false`, moves the caret to the beginning of the next\nor previously bookmarked line, respectively.\n@param next Optional flag indicating whether to go to the next or previous\n bookmarked line relative to the current line. The default value is `nil`,\n prompting the user for a bookmarked line to go to. +goto_buffer view.goto_buffer(view, buffer)\nSwitches to buffer *buffer* or the buffer *buffer* number of buffers relative to the\ncurrent one.\nEmits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events.\n@param view The view to switch buffers in.\n@param buffer A buffer or relative buffer number (typically 1 or -1).\n@see _G._BUFFERS\n@see events.BUFFER_BEFORE_SWITCH\n@see events.BUFFER_AFTER_SWITCH +goto_error textadept.run.goto_error(line_num, next)\nJumps to the source of the recognized compile/run warning or error on line number *line_num*\nin the message buffer.\nIf *line_num* is `nil`, jumps to the next or previous warning or error, depending on boolean\n*next*. Displays an annotation with the warning or error message if possible.\n@param line_num Optional line number in the message buffer that contains the compile/run\n warning or error to go to. This parameter may be omitted completely.\n@param next Optional flag indicating whether to go to the next recognized warning/error or\n the previous one. Only applicable when *line_num* is `nil`.\n@see error_patterns +goto_file ui.goto_file(filename, split, preferred_view, sloppy)\nSwitches to the existing view whose buffer's filename is *filename*.\nIf no view was found and *split* is `true`, splits the current view in order to show the\nrequested file. If *split* is `false`, shifts to the next or *preferred_view* view in order\nto show the requested file. If *sloppy* is `true`, requires only the basename of *filename*\nto match a buffer's `filename`. If the requested file was not found, it is opened in the\ndesired view.\n@param filename The filename of the buffer to go to.\n@param split Optional flag that indicates whether or not to open the buffer in a split view\n if there is only one view. The default value is `false`.\n@param preferred_view Optional view to open the desired buffer in if the buffer is not\n visible in any other view.\n@param sloppy Optional flag that indicates whether or not to not match *filename* to\n `buffer.filename` exactly. When `true`, matches *filename* to only the last part of\n `buffer.filename` This is useful for run and compile commands which output relative filenames\n and paths instead of full ones and it is likely that the file in question is already open.\n The default value is `false`. +goto_file_found ui.find.goto_file_found(line_num, next)\nJumps to the source of the find in files search result on line number *line_num* in the buffer\ntitled "Files Found" or, if *line_num* is `nil`, jumps to the next or previous search result,\ndepending on boolean *next*.\n@param line_num Optional line number in the files found buffer that contains the search\n result to go to. This parameter may be omitted completely.\n@param next Optional flag indicating whether to go to the next search result or the previous\n one. Only applicable when *line_num* is `nil`. +goto_line buffer.goto_line(buffer, line)\nMoves the caret to the beginning of line number *line* and scrolls it into view, event if\n*line* is hidden.\n@param buffer A buffer.\n@param line The line number in *buffer* to go to. +goto_line textadept.editing.goto_line(line)\nMoves the caret to the beginning of line number *line* or the user-specified line, ensuring\n*line* is visible.\n@param line Optional line number to go to. If `nil`, the user is prompted for one. +goto_mark textadept.bookmarks.goto_mark(next)\nPrompts the user to select a bookmarked line to move the caret to the beginning of unless\n*next* is given.\nIf *next* is `true` or `false`, moves the caret to the beginning of the next or previously\nbookmarked line, respectively.\n@param next Optional flag indicating whether to go to the next or previous bookmarked\n line relative to the current line. The default value is `nil`, prompting the user for a\n bookmarked line to go to. goto_pos buffer.goto_pos(buffer, pos)\nMoves the caret to position *pos* and scrolls it into view.\n@param buffer A buffer.\n@param pos The position in *buffer* to go to. -goto_view ui.goto_view(view)\nShifts to view *view* or the view *view* number of views relative to the\ncurrent one.\nEmits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.\n@param view A view or relative view number (typically 1 or -1).\n@see _G._VIEWS\n@see events.VIEW_BEFORE_SWITCH\n@see events.VIEW_AFTER_SWITCH +goto_view ui.goto_view(view)\nShifts to view *view* or the view *view* number of views relative to the current one.\nEmits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.\n@param view A view or relative view number (typically 1 or -1).\n@see _G._VIEWS\n@see events.VIEW_BEFORE_SWITCH\n@see events.VIEW_AFTER_SWITCH graph lexer.graph (pattern)\nA pattern that matches any graphical character ('!' to '~'). h_scroll_bar view.h_scroll_bar (bool)\nDisplay the horizontal scroll bar.\nThe default value is `true`. height ui.command_entry.height (number)\nThe height in pixels of the command entry. hex_num lexer.hex_num (pattern)\nA pattern that matches a hexadecimal number. -hide_lines view.hide_lines(view, start_line, end_line)\nHides the range of lines between line numbers *start_line* to *end_line*.\nThis has no effect on fold levels or fold flags and the first line cannot be\nhidden.\n@param view A view.\n@param start_line The start line of the range of lines in *view* to hide.\n@param end_line The end line of the range of lines in *view* to hide. -highlight_all_matches ui.find.highlight_all_matches (boolean)\nWhether or not to highlight all occurrences of found text in the current\nbuffer.\nThe default value is `false`. -highlight_guide view.highlight_guide (number)\nThe indentation guide column number to also highlight when highlighting\nmatching braces, or `0` to stop indentation guide highlighting. +hide_lines view.hide_lines(view, start_line, end_line)\nHides the range of lines between line numbers *start_line* to *end_line*.\nThis has no effect on fold levels or fold flags and the first line cannot be hidden.\n@param view A view.\n@param start_line The start line of the range of lines in *view* to hide.\n@param end_line The end line of the range of lines in *view* to hide. +highlight_all_matches ui.find.highlight_all_matches (boolean)\nWhether or not to highlight all occurrences of found text in the current buffer.\nThe default value is `false`. +highlight_guide view.highlight_guide (number)\nThe indentation guide column number to also highlight when highlighting matching braces,\nor `0` to stop indentation guide highlighting. highlight_words textadept.editing.highlight_words (number)\nThe word highlight mode.\n\n* `textadept.editing.HIGHLIGHT_CURRENT`\n Automatically highlight all instances of the current word.\n* `textadept.editing.HIGHLIGHT_SELECTED`\n Automatically highlight all instances of the selected word.\n* `textadept.editing.HIGHLIGHT_NONE`\n Do not automatically highlight words.\n\nThe default value is `textadept.editing.HIGHLIGHT_NONE`. -history textadept.history (module)\nRecords buffer positions within Textadept views over time and allows for\nnavigating through that history.\n\nThis module listens for text edit events and buffer switch events. Each time\nan insertion or deletion occurs, its location is recorded in the current\nview's location history. If the edit is close enough to the previous record,\nthe previous record is amended. Each time a buffer switch occurs, the before\nand after locations are also recorded. +history textadept.history (module)\nRecords buffer positions within Textadept views over time and allows for navigating through\nthat history.\n\nThis module listens for text edit events and buffer switch events. Each time an insertion\nor deletion occurs, its location is recorded in the current view's location history. If the\nedit is close enough to the previous record, the previous record is amended. Each time a\nbuffer switch occurs, the before and after locations are also recorded. home buffer.home(buffer)\nMoves the caret to the beginning of the current line.\n@param buffer A buffer. home_display buffer.home_display(buffer)\nMoves the caret to the beginning of the current wrapped line.\n@param buffer A buffer. -home_display_extend buffer.home_display_extend(buffer)\nMoves the caret to the beginning of the current wrapped line, extending the\nselected text to the new position.\n@param buffer A buffer. -home_extend buffer.home_extend(buffer)\nMoves the caret to the beginning of the current line, extending the selected\ntext to the new position.\n@param buffer A buffer. -home_rect_extend buffer.home_rect_extend(buffer)\nMoves the caret to the beginning of the current line, extending the\nrectangular selection to the new position.\n@param buffer A buffer. -home_wrap buffer.home_wrap(buffer)\nMoves the caret to the beginning of the current wrapped line or, if already\nthere, to the beginning of the actual line.\n@param buffer A buffer. +home_display_extend buffer.home_display_extend(buffer)\nMoves the caret to the beginning of the current wrapped line, extending the selected text\nto the new position.\n@param buffer A buffer. +home_extend buffer.home_extend(buffer)\nMoves the caret to the beginning of the current line, extending the selected text to the\nnew position.\n@param buffer A buffer. +home_rect_extend buffer.home_rect_extend(buffer)\nMoves the caret to the beginning of the current line, extending the rectangular selection\nto the new position.\n@param buffer A buffer. +home_wrap buffer.home_wrap(buffer)\nMoves the caret to the beginning of the current wrapped line or, if already there, to the\nbeginning of the actual line.\n@param buffer A buffer. home_wrap_extend buffer.home_wrap_extend(buffer)\nLike `buffer.home_wrap()`, but extends the selected text to the new position.\n@param buffer A buffer. -iconv string.iconv(text, new, old)\nConverts string *text* from encoding *old* to encoding *new* using GNU\nlibiconv, returning the string result.\nRaises an error if the encoding conversion failed.\nValid encodings are GNU libiconv's encodings and include:\n\n * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,\n KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},\n Mac{Roman,CentralEurope,Iceland,Croatian,Romania},\n Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.\n * Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.\n * Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2,\n ISO-2022-JP-1.\n * Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950,\n BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999,\n ISO-2022-CN, ISO-2022-CN-EXT.\n * Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.\n * Armenian: ARMSCII-8.\n * Georgian: Georgian-Academy, Georgian-PS.\n * Tajik: KOI8-T.\n * Kazakh: PT154, RK1048.\n * Thai: ISO-8859-11, TIS-620, CP874, MacThai.\n * Laotian: MuleLao-1, CP1133.\n * Vietnamese: VISCII, TCVN, CP1258.\n * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,\n UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.\n@param text The text to convert.\n@param new The string encoding to convert to.\n@param old The string encoding to convert from. -idle_styling view.idle_styling (number)\nThe idle styling mode.\nThis mode has no effect when `view.wrap_mode` is on.\n\n* `view.IDLESTYLING_NONE`\n Style all the currently visible text before displaying it.\n* `view.IDLESTYLING_TOVISIBLE`\n Style some text before displaying it and then style the rest\n incrementally in the background as an idle-time task.\n* `view.IDLESTYLING_AFTERVISIBLE`\n Style text after the currently visible portion in the background.\n* `view.IDLESTYLING_ALL`\n Style text both before and after the visible text in the background.\n\nThe default value is `view.IDLESTYLING_NONE`. +iconv string.iconv(text, new, old)\nConverts string *text* from encoding *old* to encoding *new* using GNU libiconv, returning\nthe string result.\nRaises an error if the encoding conversion failed.\nValid encodings are GNU libiconv's encodings and include:\n\n * European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R,\n KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},\n Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, Mac{Cyrillic,Ukraine,Greek,Turkish},\n Macintosh.\n * Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.\n * Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1.\n * Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS, BIG5-HKSCS:2004,\n BIG5-HKSCS:2001, BIG5-HKSCS:1999, ISO-2022-CN, ISO-2022-CN-EXT.\n * Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.\n * Armenian: ARMSCII-8.\n * Georgian: Georgian-Academy, Georgian-PS.\n * Tajik: KOI8-T.\n * Kazakh: PT154, RK1048.\n * Thai: ISO-8859-11, TIS-620, CP874, MacThai.\n * Laotian: MuleLao-1, CP1133.\n * Vietnamese: VISCII, TCVN, CP1258.\n * Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16, UTF-16BE,\n UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.\n@param text The text to convert.\n@param new The string encoding to convert to.\n@param old The string encoding to convert from. +idle_styling view.idle_styling (number)\nThe idle styling mode.\nThis mode has no effect when `view.wrap_mode` is on.\n\n* `view.IDLESTYLING_NONE`\n Style all the currently visible text before displaying it.\n* `view.IDLESTYLING_TOVISIBLE`\n Style some text before displaying it and then style the rest incrementally in the\n background as an idle-time task.\n* `view.IDLESTYLING_AFTERVISIBLE`\n Style text after the currently visible portion in the background.\n* `view.IDLESTYLING_ALL`\n Style text both before and after the visible text in the background.\n\nThe default value is `view.IDLESTYLING_NONE`. in_files ui.find.in_files (bool)\nFind search text in a directory of files.\nThe default value is `false`. in_files_label_text ui.find.in_files_label_text (string, Write-only)\nThe text of the "In files" label.\nThis is primarily used for localization. incremental ui.find.incremental (bool)\nFind search text incrementally as it is typed.\nThe default value is `false`. indent buffer.indent (number)\nThe number of spaces in one level of indentation.\nThe default value is `0`, which uses the value of `buffer.tab_width`. -indent_amount lexer.indent_amount (table, Read-only)\nTable of indentation amounts in character columns, for line numbers\nstarting from 1. -indentation_guides view.indentation_guides (number)\nThe indentation guide drawing mode.\nIndentation guides are dotted vertical lines that appear within indentation\nwhitespace at each level of indentation.\n\n* `view.IV_NONE`\n Does not draw any guides.\n* `view.IV_REAL`\n Draw guides only within indentation whitespace.\n* `view.IV_LOOKFORWARD`\n Draw guides beyond the current line up to the next non-empty line's\n indentation level, but with an additional level if the previous non-empty\n line is a fold point.\n* `view.IV_LOOKBOTH`\n Draw guides beyond the current line up to either the indentation level of\n the previous or next non-empty line, whichever is greater.\n\nThe default value is `view.IV_NONE`. -indic_alpha view.indic_alpha (table)\nTable of fill color alpha values, ranging from `0` (transparent) to `255`\n(opaque), for indicator numbers from `1` to `32` whose styles are either\n`INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.\nThe default values are `view.ALPHA_NOALPHA`, for no alpha. -indic_fore view.indic_fore (table)\nTable of foreground colors, in "0xBBGGRR" format, for indicator numbers\nfrom `1` to `32`.\nChanging an indicator's foreground color resets that indicator's hover\nforeground color. -indic_hover_fore view.indic_hover_fore (table)\nTable of hover foreground colors, in "0xBBGGRR" format, for indicator\nnumbers from `1` to `32`.\nThe default values are the respective indicator foreground colors. -indic_hover_style view.indic_hover_style (table)\nTable of hover styles for indicators numbers from `1` to `32`. An\nindicator's hover style drawn when either the cursor hovers over that\nindicator or the caret is within that indicator.\nThe default values are the respective indicator styles. -indic_outline_alpha view.indic_outline_alpha (table)\nTable of outline color alpha values, ranging from `0` (transparent) to\n`255` (opaque), for indicator numbers from `1` to `32` whose styles are\neither `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.\nThe default values are `view.ALPHA_NOALPHA`, for no alpha. -indic_style view.indic_style (table)\nTable of styles for indicator numbers from `1` to `32`.\n\n* `view.INDIC_PLAIN`\n An underline.\n* `view.INDIC_SQUIGGLE`\n A squiggly underline 3 pixels in height.\n* `view.INDIC_TT`\n An underline of small 'T' shapes.\n* `view.INDIC_DIAGONAL`\n An underline of diagonal hatches.\n* `view.INDIC_STRIKE`\n Strike out.\n* `view.INDIC_HIDDEN`\n Invisible.\n* `view.INDIC_BOX`\n A bounding box.\n* `view.INDIC_ROUNDBOX`\n A translucent box with rounded corners around the text. Use\n `view.indic_alpha` and `view.indic_outline_alpha` to set the\n fill and outline transparency, respectively. Their default values are\n `30` and `50`.\n* `view.INDIC_STRAIGHTBOX`\n Similar to `INDIC_ROUNDBOX` but with sharp corners.\n* `view.INDIC_DASH`\n A dashed underline.\n* `view.INDIC_DOTS`\n A dotted underline.\n* `view.INDIC_SQUIGGLELOW`\n A squiggly underline 2 pixels in height.\n* `view.INDIC_DOTBOX`\n Similar to `INDIC_STRAIGHTBOX` but with a dotted outline.\n Translucency alternates between `view.indic_alpha` and\n `view.indic_outline_alpha` starting with the top-left pixel.\n* `view.INDIC_SQUIGGLEPIXMAP`\n Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead\n of multiple line segments.\n* `view.INDIC_COMPOSITIONTHICK`\n A 2-pixel thick underline at the bottom of the line inset by 1 pixel on\n on either side. Similar in appearance to the target in Asian language\n input composition.\n* `view.INDIC_COMPOSITIONTHIN`\n A 1-pixel thick underline just before the bottom of the line inset by 1\n pixel on either side. Similar in appearance to the non-target ranges in\n Asian language input composition.\n* `view.INDIC_FULLBOX`\n Similar to `INDIC_STRAIGHTBOX` but extends to the top of its line,\n potentially touching any similar indicators on the line above.\n* `view.INDIC_TEXTFORE`\n Changes the color of text to an indicator's foreground color.\n* `view.INDIC_POINT`\n A triangle below the start of the indicator range.\n* `view.INDIC_POINTCHARACTER`\n A triangle below the center of the first character of the indicator\n range.\n* `view.INDIC_GRADIENT`\n A box with a vertical gradient from solid on top to transparent on\n bottom.\n* `view.INDIC_GRADIENTCENTER`\n A box with a centered gradient from solid in the middle to transparent on\n the top and bottom.\n\nUse `_SCINTILLA.next_indic_number()` for custom indicators.\nChanging an indicator's style resets that indicator's hover style. -indic_under view.indic_under (table)\nTable of flags that indicate whether or not to draw indicators behind text\ninstead of over the top of it for indicator numbers from `1` to `32`.\nThe default values are `false`. -indicator_all_on_for buffer.indicator_all_on_for(buffer, pos)\nReturns a bit-mask that represents which indicators are on at position *pos*.\nThe first bit is set if indicator 1 is on, the second bit for indicator 2,\netc.\n@param buffer A buffer.\n@param pos The position in *buffer* to get indicators at.\n@return number -indicator_clear_range buffer.indicator_clear_range(buffer, pos, length)\nClears indicator number `buffer.indicator_current` over the range of text\nfrom position *pos* to *pos* + *length*.\n@param buffer A buffer.\n@param pos The start position of the range of text in *buffer* to clear\n indicators over.\n@param length The number of characters in the range of text to clear\n indicators over. -indicator_current buffer.indicator_current (number)\nThe indicator number in the range of `1` to `32` used by\n`buffer.indicator_fill_range()` and\n`buffer.indicator_clear_range()`. -indicator_end buffer.indicator_end(buffer, indicator, pos)\nReturns the next boundary position, starting from position *pos*, of\nindicator number *indicator*, in the range of `1` to `32`.\nReturns `1` if *indicator* was not found.\n@param buffer A buffer.\n@param indicator An indicator number in the range of `1` to `32`.\n@param pos The position in *buffer* of the indicator. -indicator_fill_range buffer.indicator_fill_range(buffer, pos, length)\nFills the range of text from position *pos* to *pos* + *length* with\nindicator number `buffer.indicator_current`.\n@param buffer A buffer.\n@param pos The start position of the range of text in *buffer* to set\n indicators over.\n@param length The number of characters in the range of text to set indicators\n over. -indicator_start buffer.indicator_start(buffer, indicator, pos)\nReturns the previous boundary position, starting from position *pos*, of\nindicator number *indicator*, in the range of `1` to `32`.\nReturns `1` if *indicator* was not found.\n@param buffer A buffer.\n@param indicator An indicator number in the range of `1` to `32`.\n@param pos The position in *buffer* of the indicator. -inputbox ui.dialogs.inputbox(options)\nPrompts the user with an inputbox dialog defined by dialog options table\n*options*, returning the selected button's index along with the user's\ninput text (the latter as a string or table, depending on the type of\n*options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the user's input text.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a\n table, the first table value is the main message text and any subsequent\n values are used as the labels for multiple entry boxes. Providing a\n single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the\n table values are used to populate the multiple entry boxes defined by\n `informative_text`.\n * `button1`: The right-most button's label. The default value is\n `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2`\n to be set.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.inputbox{title = 'Goto Line', informative_text = 'Line:',\n text = '1'}\n@return selected button or exit code, input text -insert textadept.snippets.insert(text)\nInserts snippet text *text* or the snippet assigned to the trigger word\nbehind the caret.\nOtherwise, if a snippet is active, goes to the active snippet's next\nplaceholder. Returns `false` if no action was taken.\n@param text Optional snippet text to insert. If `nil`, attempts to insert a\n new snippet based on the trigger, the word behind caret, and the current\n lexer.\n@return `false` if no action was taken; `nil` otherwise.\n@see buffer.word_chars -insert_text buffer.insert_text(buffer, pos, text)\nInserts string *text* at position *pos*, removing any selections.\nIf *pos* is `-1`, inserts *text* at the caret position.\nIf the caret is after the *pos*, it is moved appropriately, but not scrolled\ninto view.\n@param buffer A buffer.\n@param pos The position in *buffer* to insert text at, or `-1` for the\n current position.\n@param text The text to insert. +indent_amount lexer.indent_amount (table, Read-only)\nTable of indentation amounts in character columns, for line numbers starting from 1. +indentation_guides view.indentation_guides (number)\nThe indentation guide drawing mode.\nIndentation guides are dotted vertical lines that appear within indentation whitespace at\neach level of indentation.\n\n* `view.IV_NONE`\n Does not draw any guides.\n* `view.IV_REAL`\n Draw guides only within indentation whitespace.\n* `view.IV_LOOKFORWARD`\n Draw guides beyond the current line up to the next non-empty line's indentation level,\n but with an additional level if the previous non-empty line is a fold point.\n* `view.IV_LOOKBOTH`\n Draw guides beyond the current line up to either the indentation level of the previous\n or next non-empty line, whichever is greater.\n\nThe default value is `view.IV_NONE`. +indic_alpha view.indic_alpha (table)\nTable of fill color alpha values, ranging from `0` (transparent) to `255` (opaque),\nfor indicator numbers from `1` to `32` whose styles are either `INDIC_ROUNDBOX`,\n`INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.\nThe default values are `view.ALPHA_NOALPHA`, for no alpha. +indic_fore view.indic_fore (table)\nTable of foreground colors, in "0xBBGGRR" format, for indicator numbers from `1` to `32`.\nChanging an indicator's foreground color resets that indicator's hover foreground color. +indic_hover_fore view.indic_hover_fore (table)\nTable of hover foreground colors, in "0xBBGGRR" format, for indicator numbers from `1` to\n`32`.\nThe default values are the respective indicator foreground colors. +indic_hover_style view.indic_hover_style (table)\nTable of hover styles for indicators numbers from `1` to `32`.\nAn indicator's hover style drawn when either the cursor hovers over that indicator or the\ncaret is within that indicator.\nThe default values are the respective indicator styles. +indic_outline_alpha view.indic_outline_alpha (table)\nTable of outline color alpha values, ranging from `0` (transparent) to `255` (opaque),\nfor indicator numbers from `1` to `32` whose styles are either `INDIC_ROUNDBOX`,\n`INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.\nThe default values are `view.ALPHA_NOALPHA`, for no alpha. +indic_style view.indic_style (table)\nTable of styles for indicator numbers from `1` to `32`.\n\n* `view.INDIC_PLAIN`\n An underline.\n* `view.INDIC_SQUIGGLE`\n A squiggly underline 3 pixels in height.\n* `view.INDIC_TT`\n An underline of small 'T' shapes.\n* `view.INDIC_DIAGONAL`\n An underline of diagonal hatches.\n* `view.INDIC_STRIKE`\n Strike out.\n* `view.INDIC_HIDDEN`\n Invisible.\n* `view.INDIC_BOX`\n A bounding box.\n* `view.INDIC_ROUNDBOX`\n A translucent box with rounded corners around the text. Use `view.indic_alpha` and\n `view.indic_outline_alpha` to set the fill and outline transparency, respectively.\n Their default values are `30` and `50`.\n* `view.INDIC_STRAIGHTBOX`\n Similar to `INDIC_ROUNDBOX` but with sharp corners.\n* `view.INDIC_DASH`\n A dashed underline.\n* `view.INDIC_DOTS`\n A dotted underline.\n* `view.INDIC_SQUIGGLELOW`\n A squiggly underline 2 pixels in height.\n* `view.INDIC_DOTBOX`\n Similar to `INDIC_STRAIGHTBOX` but with a dotted outline.\n Translucency alternates between `view.indic_alpha` and `view.indic_outline_alpha`\n starting with the top-left pixel.\n* `view.INDIC_SQUIGGLEPIXMAP`\n Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead of multiple\n line segments.\n* `view.INDIC_COMPOSITIONTHICK`\n A 2-pixel thick underline at the bottom of the line inset by 1 pixel on on either\n side. Similar in appearance to the target in Asian language input composition.\n* `view.INDIC_COMPOSITIONTHIN`\n A 1-pixel thick underline just before the bottom of the line inset by 1 pixel on either\n side. Similar in appearance to the non-target ranges in Asian language input composition.\n* `view.INDIC_FULLBOX`\n Similar to `INDIC_STRAIGHTBOX` but extends to the top of its line, potentially touching\n any similar indicators on the line above.\n* `view.INDIC_TEXTFORE`\n Changes the color of text to an indicator's foreground color.\n* `view.INDIC_POINT`\n A triangle below the start of the indicator range.\n* `view.INDIC_POINTCHARACTER`\n A triangle below the center of the first character of the indicator\n range.\n* `view.INDIC_GRADIENT`\n A box with a vertical gradient from solid on top to transparent on bottom.\n* `view.INDIC_GRADIENTCENTER`\n A box with a centered gradient from solid in the middle to transparent on the top\n and bottom.\n\nUse `_SCINTILLA.next_indic_number()` for custom indicators.\nChanging an indicator's style resets that indicator's hover style. +indic_under view.indic_under (table)\nTable of flags that indicate whether or not to draw indicators behind text instead of over\nthe top of it for indicator numbers from `1` to `32`.\nThe default values are `false`. +indicator_all_on_for buffer.indicator_all_on_for(buffer, pos)\nReturns a bit-mask that represents which indicators are on at position *pos*.\nThe first bit is set if indicator 1 is on, the second bit for indicator 2, etc.\n@param buffer A buffer.\n@param pos The position in *buffer* to get indicators at.\n@return number +indicator_clear_range buffer.indicator_clear_range(buffer, pos, length)\nClears indicator number `buffer.indicator_current` over the range of text from position *pos*\nto *pos* + *length*.\n@param buffer A buffer.\n@param pos The start position of the range of text in *buffer* to clear indicators over.\n@param length The number of characters in the range of text to clear indicators over. +indicator_current buffer.indicator_current (number)\nThe indicator number in the range of `1` to `32` used by `buffer.indicator_fill_range()`\nand `buffer.indicator_clear_range()`. +indicator_end buffer.indicator_end(buffer, indicator, pos)\nReturns the next boundary position, starting from position *pos*, of indicator number\n*indicator*, in the range of `1` to `32`.\nReturns `1` if *indicator* was not found.\n@param buffer A buffer.\n@param indicator An indicator number in the range of `1` to `32`.\n@param pos The position in *buffer* of the indicator. +indicator_fill_range buffer.indicator_fill_range(buffer, pos, length)\nFills the range of text from position *pos* to *pos* + *length* with indicator number\n`buffer.indicator_current`.\n@param buffer A buffer.\n@param pos The start position of the range of text in *buffer* to set indicators over.\n@param length The number of characters in the range of text to set indicators over. +indicator_start buffer.indicator_start(buffer, indicator, pos)\nReturns the previous boundary position, starting from position *pos*, of indicator number\n*indicator*, in the range of `1` to `32`.\nReturns `1` if *indicator* was not found.\n@param buffer A buffer.\n@param indicator An indicator number in the range of `1` to `32`.\n@param pos The position in *buffer* of the indicator. +inputbox ui.dialogs.inputbox(options)\nPrompts the user with an inputbox dialog defined by dialog options table *options*, returning\nthe selected button's index along with the user's input text (the latter as a string or table,\ndepending on the type of *options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\nuser's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled\nthe dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a table, the first\n table value is the main message text and any subsequent values are used as the labels\n for multiple entry boxes. Providing a single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the table values are\n used to populate the multiple entry boxes defined by `informative_text`.\n * `button1`: The right-most button's label. The default value is `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2` to be set.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.inputbox{title = 'Goto Line', informative_text = 'Line:',\n text = '1'}\n@return selected button or exit code, input text +insert textadept.snippets.insert(text)\nInserts snippet text *text* or the snippet assigned to the trigger word behind the caret.\nOtherwise, if a snippet is active, goes to the active snippet's next placeholder. Returns\n`false` if no action was taken.\n@param text Optional snippet text to insert. If `nil`, attempts to insert a new snippet\n based on the trigger, the word behind caret, and the current lexer.\n@return `false` if no action was taken; `nil` otherwise.\n@see buffer.word_chars +insert_text buffer.insert_text(buffer, pos, text)\nInserts string *text* at position *pos*, removing any selections.\nIf *pos* is `-1`, inserts *text* at the caret position.\nIf the caret is after the *pos*, it is moved appropriately, but not scrolled into view.\n@param buffer A buffer.\n@param pos The position in *buffer* to insert text at, or `-1` for the current position.\n@param text The text to insert. integer lexer.integer (pattern)\nA pattern that matches either a decimal, hexadecimal, or octal number. io _G.io (module)\nExtends Lua's `io` library with Textadept functions for working with files. -is_range_word buffer.is_range_word(buffer, start_pos, end_pos)\nReturns whether or not the the positions *start_pos* and *end_pos* are at\nword boundaries.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to\n check for a word boundary at.\n@param end_pos The end position of the range of text in *buffer* to check for\n a word boundary at. -join_lines textadept.editing.join_lines()\nJoins the currently selected lines or the current line with the line below\nit.\nAs long as any part of a line is selected, the entire line is eligible for\njoining. +is_range_word buffer.is_range_word(buffer, start_pos, end_pos)\nReturns whether or not the the positions *start_pos* and *end_pos* are at word boundaries.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to check for a word\n boundary at.\n@param end_pos The end position of the range of text in *buffer* to check for a word\n boundary at. +join_lines textadept.editing.join_lines()\nJoins the currently selected lines or the current line with the line below it.\nAs long as any part of a line is selected, the entire line is eligible for joining. keychain keys.keychain (table)\nThe current chain of key sequences. (Read-only.) keys _G.keys (module)\nManages key bindings in Textadept. -keys _G.keys (table)\nMap of key bindings to commands, with language-specific key tables assigned\nto a lexer name key. -keys textadept.keys (module)\nDefines key bindings for Textadept.\nThis set of key bindings is pretty standard among other text editors, at\nleast for basic editing commands and movements. -kill spawn_proc:kill(signal)\nKills running process *spawn_proc*, or sends it Unix signal *signal*.\n@param signal Optional Unix signal to send to *spawn_proc*. The default value\n is 9 (`SIGKILL`), which kills the process. -last_char_includes lexer.last_char_includes(s)\nCreates and returns a pattern that verifies the first non-whitespace\ncharacter behind the current match position is in string set *s*.\n@param s String character set like one passed to `lpeg.S()`.\n@usage local regex = lexer.last_char_includes('+-*!%^&|=,([{') *\n lexer.range('/')\n@return pattern +keys _G.keys (table)\nMap of key bindings to commands, with language-specific key tables assigned to a lexer name key. +keys textadept.keys (module)\nDefines key bindings for Textadept.\nThis set of key bindings is pretty standard among other text editors, at least for basic\nediting commands and movements. +kill spawn_proc:kill(signal)\nKills running process *spawn_proc*, or sends it Unix signal *signal*.\n@param signal Optional Unix signal to send to *spawn_proc*. The default value is 9 (`SIGKILL`),\n which kills the process. +last_char_includes lexer.last_char_includes(s)\nCreates and returns a pattern that verifies the first non-whitespace character behind the\ncurrent match position is in string set *s*.\n@param s String character set like one passed to `lpeg.S()`.\n@usage local regex = lexer.last_char_includes('+-*!%^&|=,([{') * lexer.range('/')\n@return pattern length buffer.length (number, Read-only)\nThe number of bytes in the buffer. -lex lexer.lex(lexer, text, init_style)\nLexes a chunk of text *text* (that has an initial style number of\n*init_style*) using lexer *lexer*, returning a table of token names and\npositions.\n@param lexer The lexer to lex text with.\n@param text The text in the buffer to lex.\n@param init_style The current style. Multiple-language lexers use this to\n determine which language to start lexing in.\n@return table of token names and positions. +lex lexer.lex(lexer, text, init_style)\nLexes a chunk of text *text* (that has an initial style number of *init_style*) using lexer\n*lexer*, returning a table of token names and positions.\n@param lexer The lexer to lex text with.\n@param text The text in the buffer to lex.\n@param init_style The current style. Multiple-language lexers use this to determine which\n language to start lexing in.\n@return table of token names and positions. lexer _G.lexer (module)\nLexes Scintilla documents and source code with Lua and LPeg. -lfs _G.lfs (module)\nExtends the `lfs` library to find files in directories and determine absolute\nfile paths. +lfs _G.lfs (module)\nExtends the `lfs` library to find files in directories and determine absolute file paths. line_copy buffer.line_copy(buffer)\nCopies the current line to the clipboard.\n@param buffer A buffer. line_count buffer.line_count (number, Read-only)\nThe number of lines in the buffer.\nThere is always at least one. line_cut buffer.line_cut(buffer)\nCuts the current line to the clipboard.\n@param buffer A buffer. line_delete buffer.line_delete(buffer)\nDeletes the current line.\n@param buffer A buffer. line_down buffer.line_down(buffer)\nMoves the caret down one line.\n@param buffer A buffer. -line_down_extend buffer.line_down_extend(buffer)\nMoves the caret down one line, extending the selected text to the new\nposition.\n@param buffer A buffer. -line_down_rect_extend buffer.line_down_rect_extend(buffer)\nMoves the caret down one line, extending the rectangular selection to the new\nposition.\n@param buffer A buffer. +line_down_extend buffer.line_down_extend(buffer)\nMoves the caret down one line, extending the selected text to the new position.\n@param buffer A buffer. +line_down_rect_extend buffer.line_down_rect_extend(buffer)\nMoves the caret down one line, extending the rectangular selection to the new position.\n@param buffer A buffer. line_duplicate buffer.line_duplicate(buffer)\nDuplicates the current line on a new line below.\n@param buffer A buffer. line_end buffer.line_end(buffer)\nMoves the caret to the end of the current line.\n@param buffer A buffer. line_end_display buffer.line_end_display(buffer)\nMoves the caret to the end of the current wrapped line.\n@param buffer A buffer. -line_end_display_extend buffer.line_end_display_extend(buffer)\nMoves the caret to the end of the current wrapped line, extending the\nselected text to the new position.\n@param buffer A buffer. -line_end_extend buffer.line_end_extend(buffer)\nMoves the caret to the end of the current line, extending the selected text\nto the new position.\n@param buffer A buffer. -line_end_position buffer.line_end_position (table, Read-only)\nTable of positions at the ends of lines, but before any end of line\ncharacters, per line number. -line_end_rect_extend buffer.line_end_rect_extend(buffer)\nMoves the caret to the end of the current line, extending the rectangular\nselection to the new position.\n@param buffer A buffer. -line_end_wrap buffer.line_end_wrap(buffer)\nMoves the caret to the end of the current wrapped line or, if already there,\nto the end of the actual line.\n@param buffer A buffer. -line_end_wrap_extend buffer.line_end_wrap_extend(buffer)\nLike `buffer.line_end_wrap()`, but extends the selected text to the new\nposition.\n@param buffer A buffer. -line_from_position buffer.line_from_position(buffer, pos)\nReturns the line number of the line that contains position *pos*.\nReturns `1` if *pos* is less than 1 or `buffer.line_count` if *pos* is\ngreater than `buffer.length + 1`.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the line number of.\n@return number -line_from_position lexer.line_from_position(pos)\nReturns the line number (starting from 1) of the line that contains position\n*pos*, which starts from 1.\n@param pos The position to get the line number of.\n@return number +line_end_display_extend buffer.line_end_display_extend(buffer)\nMoves the caret to the end of the current wrapped line, extending the selected text to the\nnew position.\n@param buffer A buffer. +line_end_extend buffer.line_end_extend(buffer)\nMoves the caret to the end of the current line, extending the selected text to the new position.\n@param buffer A buffer. +line_end_position buffer.line_end_position (table, Read-only)\nTable of positions at the ends of lines, but before any end of line characters, per\nline number. +line_end_rect_extend buffer.line_end_rect_extend(buffer)\nMoves the caret to the end of the current line, extending the rectangular selection to the\nnew position.\n@param buffer A buffer. +line_end_wrap buffer.line_end_wrap(buffer)\nMoves the caret to the end of the current wrapped line or, if already there, to the end of\nthe actual line.\n@param buffer A buffer. +line_end_wrap_extend buffer.line_end_wrap_extend(buffer)\nLike `buffer.line_end_wrap()`, but extends the selected text to the new position.\n@param buffer A buffer. +line_from_position buffer.line_from_position(buffer, pos)\nReturns the line number of the line that contains position *pos*.\nReturns `1` if *pos* is less than 1 or `buffer.line_count` if *pos* is greater than\n`buffer.length + 1`.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the line number of.\n@return number +line_from_position lexer.line_from_position(pos)\nReturns the line number (starting from 1) of the line that contains position *pos*, which\nstarts from 1.\n@param pos The position to get the line number of.\n@return number line_indent_position buffer.line_indent_position (table, Read-only)\nTable of positions at the ends of indentation per line number. line_indentation buffer.line_indentation (table)\nTable of column indentation amounts per line number. -line_length buffer.line_length(buffer, line)\nReturns the number of bytes on line number *line*, including end of line\ncharacters.\nTo get line length excluding end of line characters, use\n`buffer.line_end_position[line] - buffer.position_from_line(line)`.\n@param buffer A buffer.\n@param line The line number in *buffer* to get the length of.\n@return number +line_length buffer.line_length(buffer, line)\nReturns the number of bytes on line number *line*, including end of line characters.\nTo get line length excluding end of line characters, use `buffer.line_end_position[line]\n- buffer.position_from_line(line)`.\n@param buffer A buffer.\n@param line The line number in *buffer* to get the length of.\n@return number line_reverse buffer.line_reverse(buffer)\nReverses the order of the selected lines.\n@param buffer A buffer. line_scroll view.line_scroll(view, columns, lines)\nScrolls the buffer right *columns* columns and down *lines* lines.\nNegative values are allowed.\n@param view A view.\n@param columns The number of columns to scroll horizontally.\n@param lines The number of lines to scroll vertically. line_scroll_down view.line_scroll_down(view)\nScrolls the buffer down one line, keeping the caret visible.\n@param view A view. @@ -647,373 +647,373 @@ line_state lexer.line_state (table)\nTable of integer line states for line numbe line_transpose buffer.line_transpose(buffer)\nSwaps the current line with the previous one.\n@param buffer A buffer. line_up buffer.line_up(buffer)\nMoves the caret up one line.\n@param buffer A buffer. line_up_extend buffer.line_up_extend(buffer)\nMoves the caret up one line, extending the selected text to the new position.\n@param buffer A buffer. -line_up_rect_extend buffer.line_up_rect_extend(buffer)\nMoves the caret up one line, extending the rectangular selection to the new\nposition.\n@param buffer A buffer. -line_visible view.line_visible (table, Read-only)\nTable of flags per line number that indicate whether or not lines are\nvisible for those line numbers. -lines_join buffer.lines_join(buffer)\nJoins the lines in the target range, inserting spaces between the words\njoined at line boundaries.\n@param buffer A buffer. +line_up_rect_extend buffer.line_up_rect_extend(buffer)\nMoves the caret up one line, extending the rectangular selection to the new position.\n@param buffer A buffer. +line_visible view.line_visible (table, Read-only)\nTable of flags per line number that indicate whether or not lines are visible for those\nline numbers. +lines_join buffer.lines_join(buffer)\nJoins the lines in the target range, inserting spaces between the words joined at line\nboundaries.\n@param buffer A buffer. lines_on_screen view.lines_on_screen (number, Read-only)\nThe number of completely visible lines in the view.\nIt is possible to have a partial line visible at the bottom of the view. -lines_split buffer.lines_split(buffer, pixel_width, width)\nSplits the lines in the target range into lines *width* pixels wide.\nIf *width* is `0`, splits the lines in the target range into lines as wide as\nthe view.\n@param buffer A buffer.\n@param width The pixel width to split lines at. When `0`, uses the width of\n the view. -load lexer.load(name, alt_name, cache)\nInitializes or loads and returns the lexer of string name *name*.\nScintilla calls this function in order to load a lexer. Parent lexers also\ncall this function in order to load child lexers and vice-versa. The user\ncalls this function in order to load a lexer when using Scintillua as a Lua\nlibrary.\n@param name The name of the lexing language.\n@param alt_name The alternate name of the lexing language. This is useful for\n embedding the same child lexer with multiple sets of start and end tokens.\n@param cache Flag indicating whether or not to load lexers from the cache.\n This should only be `true` when initially loading a lexer (e.g. not from\n within another lexer for embedding purposes).\n The default value is `false`.\n@return lexer object -load textadept.macros.load(filename)\nLoads a macro from file *filename* or the user-selected file.\n@param filename Optional macro file to load. If `nil`, the user is prompted\n for one. -load textadept.session.load(filename)\nLoads session file *filename* or the user-selected session, returning `true`\nif a session file was opened and read.\nTextadept restores split views, opened buffers, cursor information, recent\nfiles, and bookmarks.\n@param filename Optional absolute path to the session file to load. If `nil`,\n the user is prompted for one.\n@usage textadept.session.load(filename)\n@return `true` if the session file was opened and read; `nil` otherwise. +lines_split buffer.lines_split(buffer, pixel_width, width)\nSplits the lines in the target range into lines *width* pixels wide.\nIf *width* is `0`, splits the lines in the target range into lines as wide as the view.\n@param buffer A buffer.\n@param width The pixel width to split lines at. When `0`, uses the width of the view. +load lexer.load(name, alt_name, cache)\nInitializes or loads and returns the lexer of string name *name*.\nScintilla calls this function in order to load a lexer. Parent lexers also call this function\nin order to load child lexers and vice-versa. The user calls this function in order to load\na lexer when using Scintillua as a Lua library.\n@param name The name of the lexing language.\n@param alt_name The alternate name of the lexing language. This is useful for embedding the\n same child lexer with multiple sets of start and end tokens.\n@param cache Flag indicating whether or not to load lexers from the cache. This should only\n be `true` when initially loading a lexer (e.g. not from within another lexer for embedding\n purposes). The default value is `false`.\n@return lexer object +load textadept.macros.load(filename)\nLoads a macro from file *filename* or the user-selected file.\n@param filename Optional macro file to load. If `nil`, the user is prompted for one. +load textadept.session.load(filename)\nLoads session file *filename* or the user-selected session, returning `true` if a session\nfile was opened and read.\nTextadept restores split views, opened buffers, cursor information, recent files, and bookmarks.\n@param filename Optional absolute path to the session file to load. If `nil`, the user is\n prompted for one.\n@usage textadept.session.load(filename)\n@return `true` if the session file was opened and read; `nil` otherwise. lower lexer.lower (pattern)\nA pattern that matches any lower case character ('a'-'z'). lower_case buffer.lower_case(buffer)\nConverts the selected text to lower case letters.\n@param buffer A buffer. lua _M.lua (module)\nThe lua module.\nIt provides utilities for editing Lua code. -macros textadept.macros (module)\nA module for recording, playing, saving, and loading keyboard macros.\nMenu commands are also recorded.\nAt this time, typing into multiple cursors during macro playback is not\nsupported. +macros textadept.macros (module)\nA module for recording, playing, saving, and loading keyboard macros.\nMenu commands are also recorded.\nAt this time, typing into multiple cursors during macro playback is not supported. main_selection buffer.main_selection (number)\nThe number of the main or most recent selection.\nOnly an existing selection can be made main. -margin_back_n view.margin_back_n (table)\nTable of background colors, in "0xBBGGRR" format, of margin numbers from\n`1` to `view.margins` (`5` by default).\nOnly affects margins of type `view.MARGIN_COLOR`. -margin_cursor_n view.margin_cursor_n (table)\nTable of cursor types shown over margin numbers from `1` to\n`view.margins` (`5` by default).\n\n* `view.CURSORARROW`\n Normal arrow cursor.\n* `view.CURSORREVERSEARROW`\n Reversed arrow cursor.\n\nThe default values are `view.CURSORREVERSEARROW`. +margin_back_n view.margin_back_n (table)\nTable of background colors, in "0xBBGGRR" format, of margin numbers from `1` to `view.margins`\n(`5` by default).\nOnly affects margins of type `view.MARGIN_COLOR`. +margin_cursor_n view.margin_cursor_n (table)\nTable of cursor types shown over margin numbers from `1` to `view.margins` (`5` by default).\n\n* `view.CURSORARROW`\n Normal arrow cursor.\n* `view.CURSORREVERSEARROW`\n Reversed arrow cursor.\n\nThe default values are `view.CURSORREVERSEARROW`. margin_left view.margin_left (number)\nThe pixel size of the left margin of the buffer text.\nThe default value is `1`. -margin_mask_n view.margin_mask_n (table)\nTable of bit-masks of markers whose symbols marker symbol margins can\ndisplay for margin numbers from `1` to `view.margins` (`5` by default).\nBit-masks are 32-bit values whose bits correspond to the 32 available\nmarkers.\nThe default values are `0`, `view.MASK_FOLDERS`, `0`, `0`, and `0`, for\na line margin and logical marker margin. -margin_options view.margin_options (number)\nA bit-mask of margin option settings.\n\n* `view.MARGINOPTION_NONE`\n None.\n* `view.MARGINOPTION_SUBLINESELECT`\n Select only a wrapped line's sub-line (rather than the entire line) when\n the line number margin is clicked.\n\nThe default value is `view.MARGINOPTION_NONE`. +margin_mask_n view.margin_mask_n (table)\nTable of bit-masks of markers whose symbols marker symbol margins can display for margin\nnumbers from `1` to `view.margins` (`5` by default).\nBit-masks are 32-bit values whose bits correspond to the 32 available markers.\nThe default values are `0`, `view.MASK_FOLDERS`, `0`, `0`, and `0`, for a line margin and\nlogical marker margin. +margin_options view.margin_options (number)\nA bit-mask of margin option settings.\n\n* `view.MARGINOPTION_NONE`\n None.\n* `view.MARGINOPTION_SUBLINESELECT`\n Select only a wrapped line's sub-line (rather than the entire line) when the line number\n margin is clicked.\n\nThe default value is `view.MARGINOPTION_NONE`. margin_right view.margin_right (number)\nThe pixel size of the right margin of the buffer text.\nThe default value is `1`. -margin_sensitive_n view.margin_sensitive_n (table)\nTable of flags that indicate whether or not mouse clicks in margins emit\n`MARGIN_CLICK` events for margin numbers from `1` to `view.margins` (`5`\nby default).\nThe default values are `false`. -margin_style buffer.margin_style (table)\nTable of style numbers in the text margin per line number.\nOnly some style attributes are active in text margins: font, size, bold,\nitalics, fore, and back. +margin_sensitive_n view.margin_sensitive_n (table)\nTable of flags that indicate whether or not mouse clicks in margins emit `MARGIN_CLICK`\nevents for margin numbers from `1` to `view.margins` (`5` by default).\nThe default values are `false`. +margin_style buffer.margin_style (table)\nTable of style numbers in the text margin per line number.\nOnly some style attributes are active in text margins: font, size, bold, italics, fore,\nand back. margin_text buffer.margin_text (table)\nTable of text displayed in text margins per line number. margin_text_clear_all buffer.margin_text_clear_all(buffer)\nClears all text in text margins.\n@param buffer A buffer. -margin_type_n view.margin_type_n (table)\nTable of margin types for margin numbers from `1` to `view.margins` (`5`\nby default).\n\n* `view.MARGIN_SYMBOL`\n A marker symbol margin.\n* `view.MARGIN_NUMBER`\n A line number margin.\n* `view.MARGIN_BACK`\n A marker symbol margin whose background color matches the default text\n background color.\n* `view.MARGIN_FORE`\n A marker symbol margin whose background color matches the default text\n foreground color.\n* `view.MARGIN_TEXT`\n A text margin.\n* `view.MARGIN_RTEXT`\n A right-justified text margin.\n* `view.MARGIN_COLOR`\n A marker symbol margin whose background color is configurable.\n\nThe default value for the first margin is `view.MARGIN_NUMBER`, followed\nby `view.MARGIN_SYMBOL` for the rest. -margin_width_n view.margin_width_n (table)\nTable of pixel margin widths for margin numbers from `1` to\n`view.margins` (`5` by default). +margin_type_n view.margin_type_n (table)\nTable of margin types for margin numbers from `1` to `view.margins` (`5` by default).\n\n* `view.MARGIN_SYMBOL`\n A marker symbol margin.\n* `view.MARGIN_NUMBER`\n A line number margin.\n* `view.MARGIN_BACK`\n A marker symbol margin whose background color matches the default text background color.\n* `view.MARGIN_FORE`\n A marker symbol margin whose background color matches the default text foreground color.\n* `view.MARGIN_TEXT`\n A text margin.\n* `view.MARGIN_RTEXT`\n A right-justified text margin.\n* `view.MARGIN_COLOR`\n A marker symbol margin whose background color is configurable.\n\nThe default value for the first margin is `view.MARGIN_NUMBER`, followed by\n`view.MARGIN_SYMBOL` for the rest. +margin_width_n view.margin_width_n (table)\nTable of pixel margin widths for margin numbers from `1` to `view.margins` (`5` by default). margins view.margins (number)\nThe number of margins.\nThe default value is `5`. -marker_add buffer.marker_add(buffer, line, marker)\nAdds marker number *marker*, in the range of `1` to `32`, to line number\n*line*, returning the added marker's handle which can be used in\n`buffer.marker_delete_handle()` and `buffer.marker_line_from_handle()`, or\n`-1` if *line* is invalid.\n@param buffer A buffer.\n@param line The line number to add the marker on.\n@param marker The marker number in the range of `1` to `32` to add.\n@return number -marker_add_set buffer.marker_add_set(buffer, line, marker_mask)\nAdds the markers specified in marker bit-mask *marker_mask* to line number\n*line*.\nThe first bit is set to add marker number 1, the second bit for marker number\n2, and so on up to marker number 32.\n@param buffer A buffer.\n@param line The line number to add the markers on.\n@param marker_mask The mask of markers to set. Set the first bit to set\n marker 1, the second bit for marker 2 and so on. -marker_alpha view.marker_alpha (table, Write-only)\nTable of alpha values, ranging from `0` (transparent) to `255` (opaque),\nof markers drawn in the text area (not the margin) for markers numbers from\n`1` to `32`.\nThe default values are `view.ALPHA_NOALPHA`, for no alpha. -marker_back view.marker_back (table, Write-only)\nTable of background colors, in "0xBBGGRR" format, of marker numbers from\n`1` to `32`. -marker_back_selected view.marker_back_selected (table, Write-only)\nTable of background colors, in "0xBBGGRR" format, of markers whose folding\nblocks are selected for marker numbers from `1` to `32`. -marker_define view.marker_define(view, marker, symbol)\nAssigns marker symbol *symbol* to marker number *marker*, in the range of `1`\nto `32`.\n*symbol* is shown in marker symbol margins next to lines marked with\n*marker*.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to set *symbol*\n for.\n@param symbol The marker symbol: `buffer.MARK_*`.\n@see _SCINTILLA.next_marker_number -marker_define_pixmap view.marker_define_pixmap(view, marker, pixmap)\nAssociates marker number *marker*, in the range of `1` to `32`, with XPM\nimage *pixmap*.\nThe `view.MARK_PIXMAP` marker symbol must be assigned to *marker*.\n*pixmap* is shown in marker symbol margins next to lines marked with\n*marker*.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to define\n pixmap *pixmap* for.\n@param pixmap The string pixmap data. -marker_define_rgba_image view.marker_define_rgba_image(view, marker, pixels)\nAssociates marker number *marker*, in the range of `1` to `32`, with RGBA\nimage *pixels*.\nThe dimensions for *pixels* (`view.rgba_image_width` and\n`view.rgba_image_height`) must have already been defined. *pixels* is a\nsequence of 4 byte pixel values (red, blue, green, and alpha) defining the\nimage line by line starting at the top-left pixel.\nThe `view.MARK_RGBAIMAGE` marker symbol must be assigned to *marker*.\n*pixels* is shown in symbol margins next to lines marked with *marker*.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to define RGBA\n data *pixels* for.\n@param pixels The string sequence of 4 byte pixel values starting with the\n pixels for the top line, with the leftmost pixel first, then continuing\n with the pixels for subsequent lines. There is no gap between lines for\n alignment reasons. Each pixel consists of, in order, a red byte, a green\n byte, a blue byte and an alpha byte. The color bytes are not premultiplied\n by the alpha value. That is, a fully red pixel that is 25% opaque will be\n `[FF, 00, 00, 3F]`. -marker_delete buffer.marker_delete(buffer, line, marker)\nDeletes marker number *marker*, in the range of `1` to `32`, from line number\n*line*. If *marker* is `-1`, deletes all markers from *line*.\n@param buffer A buffer.\n@param line The line number to delete the marker on.\n@param marker The marker number in the range of `1` to `32` to delete from\n *line*, or `-1` to delete all markers from the line. -marker_delete_all buffer.marker_delete_all(buffer, marker)\nDeletes marker number *marker*, in the range of `1` to `32`, from any line\nthat has it.\nIf *marker* is `-1`, deletes all markers from all lines.\n@param buffer A buffer.\n@param marker The marker number in the range of `1` to `32` to delete from\n all lines, or `-1` to delete all markers from all lines. +marker_add buffer.marker_add(buffer, line, marker)\nAdds marker number *marker*, in the range of `1` to `32`, to line number *line*, returning\nthe added marker's handle which can be used in `buffer.marker_delete_handle()` and\n`buffer.marker_line_from_handle()`, or `-1` if *line* is invalid.\n@param buffer A buffer.\n@param line The line number to add the marker on.\n@param marker The marker number in the range of `1` to `32` to add.\n@return number +marker_add_set buffer.marker_add_set(buffer, line, marker_mask)\nAdds the markers specified in marker bit-mask *marker_mask* to line number *line*.\nThe first bit is set to add marker number 1, the second bit for marker number 2, and so on\nup to marker number 32.\n@param buffer A buffer.\n@param line The line number to add the markers on.\n@param marker_mask The mask of markers to set. Set the first bit to set marker 1, the second\n bit for marker 2 and so on. +marker_alpha view.marker_alpha (table, Write-only)\nTable of alpha values, ranging from `0` (transparent) to `255` (opaque), of markers drawn\nin the text area (not the margin) for markers numbers from `1` to `32`.\nThe default values are `view.ALPHA_NOALPHA`, for no alpha. +marker_back view.marker_back (table, Write-only)\nTable of background colors, in "0xBBGGRR" format, of marker numbers from `1` to `32`. +marker_back_selected view.marker_back_selected (table, Write-only)\nTable of background colors, in "0xBBGGRR" format, of markers whose folding blocks are\nselected for marker numbers from `1` to `32`. +marker_define view.marker_define(view, marker, symbol)\nAssigns marker symbol *symbol* to marker number *marker*, in the range of `1` to `32`.\n*symbol* is shown in marker symbol margins next to lines marked with *marker*.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to set *symbol* for.\n@param symbol The marker symbol: `buffer.MARK_*`.\n@see _SCINTILLA.next_marker_number +marker_define_pixmap view.marker_define_pixmap(view, marker, pixmap)\nAssociates marker number *marker*, in the range of `1` to `32`, with XPM image *pixmap*.\nThe `view.MARK_PIXMAP` marker symbol must be assigned to *marker*. *pixmap* is shown in\nmarker symbol margins next to lines marked with *marker*.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to define pixmap *pixmap* for.\n@param pixmap The string pixmap data. +marker_define_rgba_image view.marker_define_rgba_image(view, marker, pixels)\nAssociates marker number *marker*, in the range of `1` to `32`, with RGBA image *pixels*.\nThe dimensions for *pixels* (`view.rgba_image_width` and `view.rgba_image_height`) must\nhave already been defined. *pixels* is a sequence of 4 byte pixel values (red, blue, green,\nand alpha) defining the image line by line starting at the top-left pixel.\nThe `view.MARK_RGBAIMAGE` marker symbol must be assigned to *marker*. *pixels* is shown in\nsymbol margins next to lines marked with *marker*.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to define RGBA data *pixels* for.\n@param pixels The string sequence of 4 byte pixel values starting with the pixels for the\n top line, with the leftmost pixel first, then continuing with the pixels for subsequent\n lines. There is no gap between lines for alignment reasons. Each pixel consists of, in\n order, a red byte, a green byte, a blue byte and an alpha byte. The color bytes are not\n premultiplied by the alpha value. That is, a fully red pixel that is 25% opaque will be\n `[FF, 00, 00, 3F]`. +marker_delete buffer.marker_delete(buffer, line, marker)\nDeletes marker number *marker*, in the range of `1` to `32`, from line number *line*. If\n*marker* is `-1`, deletes all markers from *line*.\n@param buffer A buffer.\n@param line The line number to delete the marker on.\n@param marker The marker number in the range of `1` to `32` to delete from *line*, or `-1`\n to delete all markers from the line. +marker_delete_all buffer.marker_delete_all(buffer, marker)\nDeletes marker number *marker*, in the range of `1` to `32`, from any line that has it.\nIf *marker* is `-1`, deletes all markers from all lines.\n@param buffer A buffer.\n@param marker The marker number in the range of `1` to `32` to delete from all lines, or\n `-1` to delete all markers from all lines. marker_delete_handle buffer.marker_delete_handle(buffer, handle)\nDeletes the marker with handle *handle* returned by `buffer.marker_add()`.\n@param buffer A buffer.\n@param handle The identifier of a marker returned by `buffer.marker_add()`. -marker_enable_highlight view.marker_enable_highlight(view, enabled)\nHighlights the margin fold markers for the current fold block if *enabled* is\n`true`.\n@param view A view.\n@param enabled Whether or not to enable highlight. -marker_fore view.marker_fore (table, Write-only)\nTable of foreground colors, in "0xBBGGRR" format, of marker numbers from\n`1` to `32`. -marker_get buffer.marker_get(buffer, line)\nReturns a bit-mask that represents the markers on line number *line*.\nThe first bit is set if marker number 1 is present, the second bit for marker\nnumber 2, and so on.\n@param buffer A buffer.\n@param line The line number to get markers on.\n@return number -marker_handle_from_line buffer.marker_handle_from_line(buffer, line, n)\nReturns the handle of the *n*th marker on line number *line*, or `-1` if no\nsuch marker exists.\n@param buffer A buffer.\n@param line The line number to get markers on.\n@param n The marker to get the handle of. -marker_line_from_handle buffer.marker_line_from_handle(buffer, handle)\nReturns the line number of the line that contains the marker with handle\n*handle* (returned `buffer.marker_add()`), or `-1` if the line was not found.\n@param buffer A buffer.\n@param handle The identifier of a marker returned by `buffer.marker_add()`.\n@return number -marker_next buffer.marker_next(buffer, line, marker_mask)\nReturns the first line number, starting at line number *line*, that contains\nall of the markers represented by marker bit-mask *marker_mask*.\nReturns `-1` if no line was found.\nThe first bit is set if marker 1 is set, the second bit for marker 2, etc.,\nup to marker 32.\n@param buffer A buffer.\n@param line The start line to search from.\n@param marker_mask The mask of markers to find. Set the first bit to find\n marker 1, the second bit for marker 2, and so on.\n@return number -marker_number_from_line buffer.marker_number_from_line(buffer, line, n)\nReturns the number of the *n*th marker on line number *line*, or `-1` if no\nsuch marker exists.\n@param buffer A buffer.\n@param line The line number to get markers on.\n@param n The marker to get the number of. -marker_previous buffer.marker_previous(buffer, line, marker_mask)\nReturns the last line number, before or on line number *line*, that contains\nall of the markers represented by marker bit-mask *marker_mask*.\nReturns `-1` if no line was found.\nThe first bit is set if marker 1 is set, the second bit for marker 2, etc.,\nup to marker 32.\n@param buffer A buffer.\n@param line The start line to search from.\n@param marker_mask The mask of markers to find. Set the first bit to find\n marker 1, the second bit for marker 2, and so on.\n@return number -marker_symbol_defined view.marker_symbol_defined(view, marker)\nReturns the symbol assigned to marker number *marker*, in the range of `1` to\n`32`, used in `view.marker_define()`,\n`view.marker_define_pixmap()`, or `view.marker_define_rgba_image()`.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to get the symbol\n of.\n@return number +marker_enable_highlight view.marker_enable_highlight(view, enabled)\nHighlights the margin fold markers for the current fold block if *enabled* is `true`.\n@param view A view.\n@param enabled Whether or not to enable highlight. +marker_fore view.marker_fore (table, Write-only)\nTable of foreground colors, in "0xBBGGRR" format, of marker numbers from `1` to `32`. +marker_get buffer.marker_get(buffer, line)\nReturns a bit-mask that represents the markers on line number *line*.\nThe first bit is set if marker number 1 is present, the second bit for marker number 2,\nand so on.\n@param buffer A buffer.\n@param line The line number to get markers on.\n@return number +marker_handle_from_line buffer.marker_handle_from_line(buffer, line, n)\nReturns the handle of the *n*th marker on line number *line*, or `-1` if no such marker exists.\n@param buffer A buffer.\n@param line The line number to get markers on.\n@param n The marker to get the handle of. +marker_line_from_handle buffer.marker_line_from_handle(buffer, handle)\nReturns the line number of the line that contains the marker with handle *handle* (returned\n`buffer.marker_add()`), or `-1` if the line was not found.\n@param buffer A buffer.\n@param handle The identifier of a marker returned by `buffer.marker_add()`.\n@return number +marker_next buffer.marker_next(buffer, line, marker_mask)\nReturns the first line number, starting at line number *line*, that contains all of the\nmarkers represented by marker bit-mask *marker_mask*.\nReturns `-1` if no line was found.\nThe first bit is set if marker 1 is set, the second bit for marker 2, etc., up to marker 32.\n@param buffer A buffer.\n@param line The start line to search from.\n@param marker_mask The mask of markers to find. Set the first bit to find marker 1, the\n second bit for marker 2, and so on.\n@return number +marker_number_from_line buffer.marker_number_from_line(buffer, line, n)\nReturns the number of the *n*th marker on line number *line*, or `-1` if no such marker exists.\n@param buffer A buffer.\n@param line The line number to get markers on.\n@param n The marker to get the number of. +marker_previous buffer.marker_previous(buffer, line, marker_mask)\nReturns the last line number, before or on line number *line*, that contains all of the\nmarkers represented by marker bit-mask *marker_mask*.\nReturns `-1` if no line was found.\nThe first bit is set if marker 1 is set, the second bit for marker 2, etc., up to marker 32.\n@param buffer A buffer.\n@param line The start line to search from.\n@param marker_mask The mask of markers to find. Set the first bit to find marker 1, the\n second bit for marker 2, and so on.\n@return number +marker_symbol_defined view.marker_symbol_defined(view, marker)\nReturns the symbol assigned to marker number *marker*, in the range of `1` to `32`, used in\n`view.marker_define()`,\n`view.marker_define_pixmap()`, or `view.marker_define_rgba_image()`.\n@param view A view.\n@param marker The marker number in the range of `1` to `32` to get the symbol of.\n@return number match_case ui.find.match_case (bool)\nMatch search text case sensitively.\nThe default value is `false`. match_case_label_text ui.find.match_case_label_text (string, Write-only)\nThe text of the "Match case" label.\nThis is primarily used for localization. maximized ui.maximized (bool)\nWhether or not Textadept's window is maximized. maximum_history_size textadept.history.maximum_history_size (number)\nThe maximum number of history records to keep per view.\nThe default value is `100`. -menu textadept.menu (module)\nDefines the menus used by Textadept.\nMenus are simply tables of menu items and submenus and may be edited in\nplace. A menu item itself is a table whose first element is a menu label and\nwhose second element is a menu command to run. Submenus have `title` keys\nassigned to string text. -menu ui.menu(menu_table)\nLow-level function for creating a menu from table *menu_table* and returning\nthe userdata.\nYou probably want to use the higher-level `textadept.menu.menubar`,\n`textadept.menu.context_menu`, or `textadept.menu.tab_context_menu` tables.\nEmits a `MENU_CLICKED` event when a menu item is selected.\n@param menu_table A table defining the menu. It is an ordered list of tables\n with a string menu item, integer menu ID, and optional GDK keycode and\n modifier mask. The latter two are used to display key shortcuts in the\n menu. '_' characters are treated as a menu mnemonics. If the menu item is\n empty, a menu separator item is created. Submenus are just nested\n menu-structure tables. Their title text is defined with a `title` key.\n@usage ui.menu{ {'_New', 1}, {'_Open', 2}, {''}, {'_Quit', 4} }\n@usage ui.menu{ {'_New', 1, string.byte('n'), 4} } -- 'Ctrl+N'\n@see events.MENU_CLICKED\n@see textadept.menu.menubar\n@see textadept.menu.context_menu\n@see textadept.menu.tab_context_menu -menubar textadept.menu.menubar (table)\nThe default main menubar.\nIndividual menus, submenus, and menu items can be retrieved by name in\naddition to table index number. -menubar ui.menubar (table)\nA table of menus defining a menubar. (Write-only).\nThis is a low-level field. You probably want to use the higher-level\n`textadept.menu.menubar`.\n@see textadept.menu.menubar +menu textadept.menu (module)\nDefines the menus used by Textadept.\nMenus are simply tables of menu items and submenus and may be edited in place. A menu item\nitself is a table whose first element is a menu label and whose second element is a menu\ncommand to run. Submenus have `title` keys assigned to string text. +menu ui.menu(menu_table)\nLow-level function for creating a menu from table *menu_table* and returning the userdata.\nYou probably want to use the higher-level `textadept.menu.menubar`,\n`textadept.menu.context_menu`, or `textadept.menu.tab_context_menu` tables.\nEmits a `MENU_CLICKED` event when a menu item is selected.\n@param menu_table A table defining the menu. It is an ordered list of tables with a string\n menu item, integer menu ID, and optional GDK keycode and modifier mask. The latter\n two are used to display key shortcuts in the menu. '_' characters are treated as a menu\n mnemonics. If the menu item is empty, a menu separator item is created. Submenus are just\n nested menu-structure tables. Their title text is defined with a `title` key.\n@usage ui.menu{ {'_New', 1}, {'_Open', 2}, {''}, {'_Quit', 4} }\n@usage ui.menu{ {'_New', 1, string.byte('n'), 4} } -- 'Ctrl+N'\n@see events.MENU_CLICKED\n@see textadept.menu.menubar\n@see textadept.menu.context_menu\n@see textadept.menu.tab_context_menu +menubar textadept.menu.menubar (table)\nThe default main menubar.\nIndividual menus, submenus, and menu items can be retrieved by name in addition to table\nindex number. +menubar ui.menubar (table)\nA table of menus defining a menubar. (Write-only).\nThis is a low-level field. You probably want to use the higher-level `textadept.menu.menubar`.\n@see textadept.menu.menubar minimum_line_distance textadept.history.minimum_line_distance (number)\nThe minimum number of lines between distinct history records.\nThe default value is `3`. -mode keys.mode (string)\nThe current key mode.\nWhen non-`nil`, all key bindings defined outside of `keys[mode]` are\nignored.\nThe default value is `nil`. +mode keys.mode (string)\nThe current key mode.\nWhen non-`nil`, all key bindings defined outside of `keys[mode]` are ignored.\nThe default value is `nil`. modify buffer.modify (bool, Read-only)\nWhether or not the buffer has unsaved changes. -modify_rule lexer.modify_rule(lexer, id, rule)\nReplaces in lexer *lexer* the existing rule identified by string *id* with\npattern *rule*.\n@param lexer The lexer to modify.\n@param id The id associated with this rule.\n@param rule The LPeg pattern of the rule. -mouse_dwell_time view.mouse_dwell_time (number)\nThe number of milliseconds the mouse must idle before generating a\n`DWELL_START` event. A time of `view.TIME_FOREVER` will never generate\none. -mouse_selection_rectangular_switch view.mouse_selection_rectangular_switch (bool)\nWhether or not pressing `view.rectangular_selection_modifier` when\nselecting text normally with the mouse turns on rectangular selection.\nThe default value is `false`. +modify_rule lexer.modify_rule(lexer, id, rule)\nReplaces in lexer *lexer* the existing rule identified by string *id* with pattern *rule*.\n@param lexer The lexer to modify.\n@param id The id associated with this rule.\n@param rule The LPeg pattern of the rule. +mouse_dwell_time view.mouse_dwell_time (number)\nThe number of milliseconds the mouse must idle before generating a `DWELL_START` event. A\ntime of `view.TIME_FOREVER` will never generate one. +mouse_selection_rectangular_switch view.mouse_selection_rectangular_switch (bool)\nWhether or not pressing `view.rectangular_selection_modifier` when selecting text\nnormally with the mouse turns on rectangular selection.\nThe default value is `false`. move_caret_inside_view buffer.move_caret_inside_view(buffer)\nMoves the caret into view if it is not already, removing any selections.\n@param buffer A buffer. move_extends_selection buffer.move_extends_selection (bool, Read-only)\nWhether or not regular caret movement alters the selected text.\n`buffer.selection_mode` dictates this property. move_selected_lines_down buffer.move_selected_lines_down(buffer)\nShifts the selected lines down one line.\n@param buffer A buffer. move_selected_lines_up buffer.move_selected_lines_up(buffer)\nShifts the selected lines up one line.\n@param buffer A buffer. -msgbox ui.dialogs.msgbox(options)\nPrompts the user with a generic message box dialog defined by dialog options\ntable *options*, returning the selected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the message box.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `informative_text`: The dialog's extra informative text.\n * `icon`: The dialog's GTK stock icon name. Examples are\n "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and\n "gtk-dialog-warning". The dialog does not display an icon by default.\n * `icon_file`: The dialog's icon file path. This option has no effect when\n `icon` is set.\n * `button1`: The right-most button's label. The default value is\n `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2`\n to be set.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.msgbox{title = 'EOL Mode', text = 'Which EOL?',\n icon = 'gtk-dialog-question', button1 = 'CRLF', button2 = 'CR',\n button3 = 'LF'}\n@return selected button or exit code -multi_edge_add_line view.multi_edge_add_line(view, column, color)\nAdds a new vertical line at column number *column* with color *color*, in\n"0xBBGGRR" format.\n@param view A view.\n@param column The column number to add a vertical line at.\n@param color The color in "0xBBGGRR" format. +msgbox ui.dialogs.msgbox(options)\nPrompts the user with a generic message box dialog defined by dialog options table *options*,\nreturning the selected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label. If the dialog timed\nout, returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the message box.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `informative_text`: The dialog's extra informative text.\n * `icon`: The dialog's GTK stock icon name. Examples are "gtk-dialog-error",\n "gtk-dialog-info", "gtk-dialog-question", and "gtk-dialog-warning". The dialog does not\n display an icon by default.\n * `icon_file`: The dialog's icon file path. This option has no effect when `icon` is set.\n * `button1`: The right-most button's label. The default value is `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2` to be set.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.msgbox{title = 'EOL Mode', text = 'Which EOL?',\n icon = 'gtk-dialog-question', button1 = 'CRLF', button2 = 'CR',\n button3 = 'LF'}\n@return selected button or exit code +multi_edge_add_line view.multi_edge_add_line(view, column, color)\nAdds a new vertical line at column number *column* with color *color*, in "0xBBGGRR" format.\n@param view A view.\n@param column The column number to add a vertical line at.\n@param color The color in "0xBBGGRR" format. multi_edge_clear_all view.multi_edge_clear_all(view)\nClears all vertical lines created by `view:multi_edge_add_line()`.\n@param view A view. multi_edge_column view.multi_edge_column (table, Read-only)\nTable of edge column positions per edge column number.\nA position of `-1` means no edge column was found. multi_paste buffer.multi_paste (number)\nThe multiple selection paste mode.\n\n* `buffer.MULTIPASTE_ONCE`\n Paste into only the main selection.\n* `buffer.MULTIPASTE_EACH`\n Paste into all selections.\n\nThe default value is `buffer.MULTIPASTE_ONCE`. -multiple_select_add_each buffer.multiple_select_add_each(buffer)\nAdds to the set of selections each occurrence of the main selection within\nthe target range.\nIf there is no selected text, the current word is used.\n@param buffer A buffer. -multiple_select_add_next buffer.multiple_select_add_next(buffer)\nAdds to the set of selections the next occurrence of the main selection\nwithin the target range, makes that occurrence the new main selection, and\nscrolls it into view.\nIf there is no selected text, the current word is used.\n@param buffer A buffer. +multiple_select_add_each buffer.multiple_select_add_each(buffer)\nAdds to the set of selections each occurrence of the main selection within the target range.\nIf there is no selected text, the current word is used.\n@param buffer A buffer. +multiple_select_add_next buffer.multiple_select_add_next(buffer)\nAdds to the set of selections the next occurrence of the main selection within the target\nrange, makes that occurrence the new main selection, and scrolls it into view.\nIf there is no selected text, the current word is used.\n@param buffer A buffer. multiple_selection buffer.multiple_selection (bool)\nEnable multiple selection.\nThe default value is `false`. name_of_style buffer.name_of_style(buffer, style)\nReturns the name of style number *style*, which is between `1` and `256`.\n@param buffer A buffer.\n@param style The style number between `1` and `256` to get the name of.\n@return string new buffer.new()\nCreates a new buffer, displays it in the current view, and returns it.\nEmits a `BUFFER_NEW` event.\n@return the new buffer.\n@see events.BUFFER_NEW -new lexer.new(name, opts)\nCreates a returns a new lexer with the given name.\n@param name The lexer's name.\n@param opts Table of lexer options. Options currently supported:\n * `lex_by_line`: Whether or not the lexer only processes whole lines of\n text (instead of arbitrary chunks of text) at a time.\n Line lexers cannot look ahead to subsequent lines.\n The default value is `false`.\n * `fold_by_indentation`: Whether or not the lexer does not define any fold\n points and that fold points should be calculated based on changes in line\n indentation.\n The default value is `false`.\n * `case_insensitive_fold_points`: Whether or not fold points added via\n `lexer.add_fold_point()` ignore case.\n The default value is `false`.\n * `inherit`: Lexer to inherit from.\n The default value is `nil`.\n@usage lexer.new('rhtml', {inherit = lexer.load('html')}) +new lexer.new(name, opts)\nCreates a returns a new lexer with the given name.\n@param name The lexer's name.\n@param opts Table of lexer options. Options currently supported:\n * `lex_by_line`: Whether or not the lexer only processes whole lines of text (instead of\n arbitrary chunks of text) at a time. Line lexers cannot look ahead to subsequent lines.\n The default value is `false`.\n * `fold_by_indentation`: Whether or not the lexer does not define any fold points and that\n fold points should be calculated based on changes in line indentation. The default value\n is `false`.\n * `case_insensitive_fold_points`: Whether or not fold points added via\n `lexer.add_fold_point()` ignore case. The default value is `false`.\n * `inherit`: Lexer to inherit from. The default value is `nil`.\n@usage lexer.new('rhtml', {inherit = lexer.load('html')}) new_line buffer.new_line(buffer)\nTypes a new line at the caret position according to `buffer.eol_mode`.\n@param buffer A buffer. newline lexer.newline (pattern)\nA pattern that matches a sequence of end of line characters. -next_image_type _SCINTILLA.next_image_type()\nReturns a unique image type identier number for use with\n`view.register_image()` and `view.register_rgba_image()`.\nUse this function for custom image types in order to prevent clashes with\nidentifiers of other custom image types.\n@usage local image_type = _SCINTILLA.next_image_type()\n@see view.register_image\n@see view.register_rgba_image -next_indic_number _SCINTILLA.next_indic_number()\nReturns a unique indicator number for use with custom indicators.\nUse this function for custom indicators in order to prevent clashes with\nidentifiers of other custom indicators.\n@usage local indic_num = _SCINTILLA.next_indic_number()\n@see view.indic_style -next_marker_number _SCINTILLA.next_marker_number()\nReturns a unique marker number for use with `view.marker_define()`.\nUse this function for custom markers in order to prevent clashes with\nidentifiers of other custom markers.\n@usage local marknum = _SCINTILLA.next_marker_number()\n@see view.marker_define -next_user_list_type _SCINTILLA.next_user_list_type()\nReturns a unique user list identier number for use with\n`buffer.user_list_show()`.\nUse this function for custom user lists in order to prevent clashes with\nlist identifiers of other custom user lists.\n@usage local list_type = _SCINTILLA.next_user_list_type()\n@see buffer.user_list_show +next_image_type _SCINTILLA.next_image_type()\nReturns a unique image type identier number for use with `view.register_image()` and\n`view.register_rgba_image()`.\nUse this function for custom image types in order to prevent clashes with identifiers of\nother custom image types.\n@usage local image_type = _SCINTILLA.next_image_type()\n@see view.register_image\n@see view.register_rgba_image +next_indic_number _SCINTILLA.next_indic_number()\nReturns a unique indicator number for use with custom indicators.\nUse this function for custom indicators in order to prevent clashes with identifiers of\nother custom indicators.\n@usage local indic_num = _SCINTILLA.next_indic_number()\n@see view.indic_style +next_marker_number _SCINTILLA.next_marker_number()\nReturns a unique marker number for use with `view.marker_define()`.\nUse this function for custom markers in order to prevent clashes with identifiers of other\ncustom markers.\n@usage local marknum = _SCINTILLA.next_marker_number()\n@see view.marker_define +next_user_list_type _SCINTILLA.next_user_list_type()\nReturns a unique user list identier number for use with `buffer.user_list_show()`.\nUse this function for custom user lists in order to prevent clashes with list identifiers\nof other custom user lists.\n@usage local list_type = _SCINTILLA.next_user_list_type()\n@see buffer.user_list_show nonnewline lexer.nonnewline (pattern)\nA pattern that matches any single, non-newline character. -number lexer.number (pattern)\nA pattern that matches a typical number, either a floating point, decimal,\nhexadecimal, or octal number. +number lexer.number (pattern)\nA pattern that matches a typical number, either a floating point, decimal, hexadecimal,\nor octal number. oct_num lexer.oct_num (pattern)\nA pattern that matches an octal number. -ok_msgbox ui.dialogs.ok_msgbox(options)\nPrompts the user with a generic message box dialog defined by dialog options\ntable *options* and with localized "Ok" and "Cancel" buttons, returning the\nselected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the message box.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `informative_text`: The dialog's extra informative text.\n * `icon`: The dialog's GTK stock icon name. Examples are\n "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and\n "gtk-dialog-warning". The dialog does not display an icon by default.\n * `icon_file`: The dialog's icon file path. This option has no effect when\n `icon` is set.\n * `no_cancel`: Do not display the "Cancel" button. The default value is\n `false`.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@return selected button or exit code -open_file io.open_file(filenames, encodings)\nOpens *filenames*, a string filename or list of filenames, or the\nuser-selected filename(s).\nEmits a `FILE_OPENED` event.\n@param filenames Optional string filename or table of filenames to open. If\n `nil`, the user is prompted with a fileselect dialog.\n@param encodings Optional string encoding or table of encodings file contents\n are in (one encoding per file). If `nil`, encoding auto-detection is\n attempted via `io.encodings`.\n@see _G.events +ok_msgbox ui.dialogs.ok_msgbox(options)\nPrompts the user with a generic message box dialog defined by dialog options table *options*\nand with localized "Ok" and "Cancel" buttons, returning the selected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label. If the dialog timed\nout, returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the message box.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `informative_text`: The dialog's extra informative text.\n * `icon`: The dialog's GTK stock icon name. Examples are "gtk-dialog-error",\n "gtk-dialog-info", "gtk-dialog-question", and "gtk-dialog-warning". The dialog does not\n display an icon by default.\n * `icon_file`: The dialog's icon file path. This option has no effect when `icon` is set.\n * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@return selected button or exit code +open_file io.open_file(filenames, encodings)\nOpens *filenames*, a string filename or list of filenames, or the user-selected filename(s).\nEmits a `FILE_OPENED` event.\n@param filenames Optional string filename or table of filenames to open. If `nil`, the user\n is prompted with a fileselect dialog.\n@param encodings Optional string encoding or table of encodings file contents are in (one\n encoding per file). If `nil`, encoding auto-detection is attempted via `io.encodings`.\n@see _G.events open_recent_file io.open_recent_file()\nPrompts the user to select a recently opened file to be reopened.\n@see recent_files -optionselect ui.dialogs.optionselect(options)\nPrompts the user with an option selection dialog defined by dialog options\ntable *options*, returning the selected button's index along with the indices\nof the selected options.\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the text of the selected options.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the option select dialog.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `items`: The list of string options to show in the option group.\n * `button1`: The right-most button's label. The default value is\n `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2`\n to be set.\n * `select`: The indices of initially selected options.\n * `string_output`: Return the selected button's label or the dialog's exit\n status along with the selected options' text instead of the button's\n index or the dialog's exit code along with the options' indices. The\n default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.optionselect{title = 'Language',\n informative_text = 'Check the languages you understand',\n items = {'English', 'Romanian'}, select = 1, string_output = true}\n@return selected button or exit code, list of selected options +optionselect ui.dialogs.optionselect(options)\nPrompts the user with an option selection dialog defined by dialog options table *options*,\nreturning the selected button's index along with the indices of the selected options.\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\ntext of the selected options. If the dialog timed out, returns `0` or `"timeout"`. If the\nuser canceled the dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the option select dialog.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `items`: The list of string options to show in the option group.\n * `button1`: The right-most button's label. The default value is `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2` to be set.\n * `select`: The indices of initially selected options.\n * `string_output`: Return the selected button's label or the dialog's exit status along\n with the selected options' text instead of the button's index or the dialog's exit code\n along with the options' indices. The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.optionselect{title = 'Language',\n informative_text = 'Check the languages you understand',\n items = {'English', 'Romanian'}, select = 1, string_output = true}\n@return selected button or exit code, list of selected options os _G.os (module)\nExtends Lua's `os` library to provide process spawning capabilities. overtype buffer.overtype (bool)\nEnable overtype mode, where typed characters overwrite existing ones.\nThe default value is `false`. page_down buffer.page_down(buffer)\nMoves the caret down one page.\n@param buffer A buffer. -page_down_extend buffer.page_down_extend(buffer)\nMoves the caret down one page, extending the selected text to the new\nposition.\n@param buffer A buffer. -page_down_rect_extend buffer.page_down_rect_extend(buffer)\nMoves the caret down one page, extending the rectangular selection to the new\nposition.\n@param buffer A buffer. +page_down_extend buffer.page_down_extend(buffer)\nMoves the caret down one page, extending the selected text to the new position.\n@param buffer A buffer. +page_down_rect_extend buffer.page_down_rect_extend(buffer)\nMoves the caret down one page, extending the rectangular selection to the new position.\n@param buffer A buffer. page_up buffer.page_up(buffer)\nMoves the caret up one page.\n@param buffer A buffer. page_up_extend buffer.page_up_extend(buffer)\nMoves the caret up one page, extending the selected text to the new position.\n@param buffer A buffer. -page_up_rect_extend buffer.page_up_rect_extend(buffer)\nMoves the caret up one page, extending the rectangular selection to the new\nposition.\n@param buffer A buffer. +page_up_rect_extend buffer.page_up_rect_extend(buffer)\nMoves the caret up one page, extending the rectangular selection to the new position.\n@param buffer A buffer. para_down buffer.para_down(buffer)\nMoves the caret down one paragraph.\nParagraphs are surrounded by one or more blank lines.\n@param buffer A buffer. -para_down_extend buffer.para_down_extend(buffer)\nMoves the caret down one paragraph, extending the selected text to the new\nposition.\nParagraphs are surrounded by one or more blank lines.\n@param buffer A buffer. +para_down_extend buffer.para_down_extend(buffer)\nMoves the caret down one paragraph, extending the selected text to the new position.\nParagraphs are surrounded by one or more blank lines.\n@param buffer A buffer. para_up buffer.para_up(buffer)\nMoves the caret up one paragraph.\nParagraphs are surrounded by one or more blank lines.\n@param buffer A buffer. -para_up_extend buffer.para_up_extend(buffer)\nMoves the caret up one paragraph, extending the selected text to the new\nposition.\nParagraphs are surrounded by one or more blank lines.\n@param buffer A buffer. -paste buffer.paste(buffer)\nPastes the clipboard's contents into the buffer, replacing any selected text\naccording to `buffer.multi_paste`.\n@param buffer A buffer. -paste_reindent textadept.editing.paste_reindent()\nPastes the text from the clipboard, taking into account the buffer's\nindentation settings and the indentation of the current and preceding lines. -paths textadept.snippets.paths (table)\nList of directory paths to look for snippet files in.\nFilenames are of the form *lexer.trigger.ext* or *trigger.ext* (*.ext* is an\noptional, arbitrary file extension). If the global `snippets` table does not\ncontain a snippet for a given trigger, this table is consulted for a matching\nfilename, and the contents of that file is inserted as a snippet.\nNote: If a directory has multiple snippets with the same trigger, the snippet\nchosen for insertion is not defined and may not be constant. +para_up_extend buffer.para_up_extend(buffer)\nMoves the caret up one paragraph, extending the selected text to the new position.\nParagraphs are surrounded by one or more blank lines.\n@param buffer A buffer. +paste buffer.paste(buffer)\nPastes the clipboard's contents into the buffer, replacing any selected text according to\n`buffer.multi_paste`.\n@param buffer A buffer. +paste_reindent textadept.editing.paste_reindent()\nPastes the text from the clipboard, taking into account the buffer's indentation settings\nand the indentation of the current and preceding lines. +paths textadept.snippets.paths (table)\nList of directory paths to look for snippet files in.\nFilenames are of the form *lexer.trigger.ext* or *trigger.ext* (*.ext* is an optional,\narbitrary file extension). If the global `snippets` table does not contain a snippet for\na given trigger, this table is consulted for a matching filename, and the contents of that\nfile is inserted as a snippet.\nNote: If a directory has multiple snippets with the same trigger, the snippet chosen for\ninsertion is not defined and may not be constant. patterns textadept.file_types.patterns (table)\nMap of first-line patterns to their associated lexer names.\nEach pattern is matched against the first line in the file. play textadept.macros.play()\nPlays a recorded or loaded macro.\n@see load -position_after buffer.position_after(buffer, pos)\nReturns the position of the character after position *pos* (taking multi-byte\ncharacters into account), or `buffer.length + 1` if there is no character\nafter *pos*.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the position after from. -position_before buffer.position_before(buffer, pos)\nReturns the position of the character before position *pos* (taking\nmulti-byte characters into account), or `1` if there is no character before\n*pos*.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the position before from.\n@return number +position_after buffer.position_after(buffer, pos)\nReturns the position of the character after position *pos* (taking multi-byte characters\ninto account), or `buffer.length + 1` if there is no character after *pos*.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the position after from. +position_before buffer.position_before(buffer, pos)\nReturns the position of the character before position *pos* (taking multi-byte characters\ninto account), or `1` if there is no character before *pos*.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the position before from.\n@return number position_from_line buffer.position_from_line(buffer, line)\nReturns the position at the beginning of line number *line*.\nReturns `-1` if *line* is greater than `buffer.line_count + 1`.\n@param buffer A buffer.\n@param line The line number in *buffer* to get the beginning position for.\n@return number -position_relative buffer.position_relative(buffer, pos, n)\nReturns the position *n* characters before or after position *pos* (taking\nmulti-byte characters into account).\nReturns `1` if the position is less than 1 or greater than\n`buffer.length + 1`.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the relative position from.\n@param n The relative number of characters to get the position for. A\n negative number indicates a position before while a positive number\n indicates a position after.\n@return number -previous textadept.snippets.previous()\nJumps back to the previous snippet placeholder, reverting any changes from\nthe current one.\nReturns `false` if no snippet is active.\n@return `false` if no snippet is active; `nil` otherwise. +position_relative buffer.position_relative(buffer, pos, n)\nReturns the position *n* characters before or after position *pos* (taking multi-byte\ncharacters into account).\nReturns `1` if the position is less than 1 or greater than `buffer.length + 1`.\n@param buffer A buffer.\n@param pos The position in *buffer* to get the relative position from.\n@param n The relative number of characters to get the position for. A negative number\n indicates a position before while a positive number indicates a position after.\n@return number +previous textadept.snippets.previous()\nJumps back to the previous snippet placeholder, reverting any changes from the current one.\nReturns `false` if no snippet is active.\n@return `false` if no snippet is active; `nil` otherwise. print lexer.print (pattern)\nA pattern that matches any printable character (' ' to '~'). print ui.print(...)\nPrints the given string messages to the message buffer.\nOpens a new buffer if one has not already been opened for printing messages.\n@param ... Message strings. -progressbar ui.dialogs.progressbar(options, f)\nDisplays a progressbar dialog, defined by dialog options table *options*,\nthat receives updates from function *f*.\nReturns "stopped" if *options*.`stoppable` is `true` and the user clicked the\n"Stop" button. Otherwise, returns `nil`.\n@param options Table of key-value option pairs for the progressbar dialog.\n\n * `title`: The dialog's title text.\n * `percent`: The initial progressbar percentage between 0 and 100.\n * `text`: The initial progressbar display text (GTK only).\n * `indeterminate`: Show the progress bar as "busy", with no percentage\n updates.\n * `stoppable`: Show the "Stop" button.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n@param f Function repeatedly called to do work and provide progress updates.\n The function is called without arguments and must return either `nil`,\n which indicates work is complete, or a progress percentage number in the\n range 0-100 and an optional string to display (GTK only). If the text is\n either "stop disable" or "stop enable" and *options*.`stoppable` is `true`,\n the "Stop" button is disabled or enabled, respectively.\n@usage ui.dialogs.progressbar({stoppable = true},\n function() if work() then return percent, status else return nil end end)\n@return nil or "stopped" -properties _SCINTILLA.properties (table)\nMap of Scintilla property names to table values containing their "get"\nfunction IDs, "set" function IDs, return types, and wParam types.\nThe wParam type will be non-zero if the property is indexable.\nTypes are the same as in the `functions` table.\n@see functions +progressbar ui.dialogs.progressbar(options, f)\nDisplays a progressbar dialog, defined by dialog options table *options*, that receives\nupdates from function *f*.\nReturns "stopped" if *options*.`stoppable` is `true` and the user clicked the "Stop"\nbutton. Otherwise, returns `nil`.\n@param options Table of key-value option pairs for the progressbar dialog.\n\n * `title`: The dialog's title text.\n * `percent`: The initial progressbar percentage between 0 and 100.\n * `text`: The initial progressbar display text (GTK only).\n * `indeterminate`: Show the progress bar as "busy", with no percentage updates.\n * `stoppable`: Show the "Stop" button.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n@param f Function repeatedly called to do work and provide progress updates. The function is\n called without arguments and must return either `nil`, which indicates work is complete,\n or a progress percentage number in the range 0-100 and an optional string to display (GTK\n only). If the text is either "stop disable" or "stop enable" and *options*.`stoppable` is\n `true`, the "Stop" button is disabled or enabled, respectively.\n@usage ui.dialogs.progressbar({stoppable = true},\n function() if work() then return percent, status else return nil end end)\n@return nil or "stopped" +properties _SCINTILLA.properties (table)\nMap of Scintilla property names to table values containing their "get" function IDs, "set"\nfunction IDs, return types, and wParam types.\nThe wParam type will be non-zero if the property is indexable.\nTypes are the same as in the `functions` table.\n@see functions property lexer.property (table)\nMap of key-value string pairs. property view.property (table)\nMap of key-value string pairs used by lexers. -property_expanded lexer.property_expanded (table, Read-only)\nMap of key-value string pairs with `$()` and `%()` variable replacement\nperformed in values. -property_expanded view.property_expanded (table, Read-only)\nMap of key-value string pairs used by lexers with `$()` and `%()` variable\nreplacement performed in values. -property_int lexer.property_int (table, Read-only)\nMap of key-value pairs with values interpreted as numbers, or `0` if not\nfound. -property_int view.property_int (table, Read-only)\nMap of key-value pairs used by lexers with values interpreted as numbers,\nor `0` if not found. -punct lexer.punct (pattern)\nA pattern that matches any punctuation character ('!' to '/', ':' to '@',\n'[' to ''', '{' to '~'). -punctuation_chars buffer.punctuation_chars (string)\nThe string set of characters recognized as punctuation characters.\nSet this only after setting `buffer.word_chars`.\nThe default value is a string that contains all non-word and non-whitespace\ncharacters. -quick_open io.quick_open(paths, filter, opts)\nPrompts the user to select files to be opened from *paths*, a string\ndirectory path or list of directory paths, using a filtered list dialog.\nIf *paths* is `nil`, uses the current project's root directory, which is\nobtained from `io.get_project_root()`.\nString or list *filter* determines which files to show in the dialog, with\nthe default filter being `io.quick_open_filters[path]` (if it exists) or\n`lfs.default_filter`. A filter consists of Lua patterns that match file and\ndirectory paths to include or exclude. Patterns are inclusive by default.\nExclusive patterns begin with a '!'. If no inclusive patterns are given, any\npath is initially considered. As a convenience, file extensions can be\nspecified literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'),\nand '/' also matches the Windows directory separator ('[/\\]' is not needed).\nThe number of files in the list is capped at `quick_open_max`.\nIf *filter* is `nil` and *paths* is ultimately a string, the filter from the\n`io.quick_open_filters` table is used. If that filter does not exist,\n`lfs.default_filter` is used.\n*opts* is an optional table of additional options for\n`ui.dialogs.filteredlist()`.\n@param paths Optional string directory path or table of directory paths to\n search. The default value is the current project's root directory, if\n available.\n@param filter Optional filter for files and directories to include and/or\n exclude. The default value is `lfs.default_filter` unless a filter for\n *paths* is defined in `io.quick_open_filters`.\n@param opts Optional table of additional options for\n `ui.dialogs.filteredlist()`.\n@usage io.quick_open(buffer.filename:match('^(.+)[/\\]')) -- list all files\n in the current file's directory, subject to the default filter\n@usage io.quick_open(io.get_current_project(), '.lua') -- list all Lua files\n in the current project\n@usage io.quick_open(io.get_current_project(), '!/build') -- list all files\n in the current project except those in the build directory\n@see io.quick_open_filters\n@see lfs.default_filter\n@see quick_open_max\n@see ui.dialogs.filteredlist +property_expanded lexer.property_expanded (table, Read-only)\nMap of key-value string pairs with `$()` and `%()` variable replacement performed in values. +property_expanded view.property_expanded (table, Read-only)\nMap of key-value string pairs used by lexers with `$()` and `%()` variable replacement\nperformed in values. +property_int lexer.property_int (table, Read-only)\nMap of key-value pairs with values interpreted as numbers, or `0` if not found. +property_int view.property_int (table, Read-only)\nMap of key-value pairs used by lexers with values interpreted as numbers, or `0` if not found. +punct lexer.punct (pattern)\nA pattern that matches any punctuation character ('!' to '/', ':' to '@', '[' to ''',\n'{' to '~'). +punctuation_chars buffer.punctuation_chars (string)\nThe string set of characters recognized as punctuation characters.\nSet this only after setting `buffer.word_chars`.\nThe default value is a string that contains all non-word and non-whitespace characters. +quick_open io.quick_open(paths, filter, opts)\nPrompts the user to select files to be opened from *paths*, a string directory path or list\nof directory paths, using a filtered list dialog.\nIf *paths* is `nil`, uses the current project's root directory, which is obtained from\n`io.get_project_root()`.\nString or list *filter* determines which files to show in the dialog, with the default\nfilter being `io.quick_open_filters[path]` (if it exists) or `lfs.default_filter`. A filter\nconsists of Lua patterns that match file and directory paths to include or exclude. Patterns\nare inclusive by default. Exclusive patterns begin with a '!'. If no inclusive patterns are\ngiven, any path is initially considered. As a convenience, file extensions can be specified\nliterally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the\nWindows directory separator ('[/\\]' is not needed).\nThe number of files in the list is capped at `quick_open_max`.\nIf *filter* is `nil` and *paths* is ultimately a string, the filter from the\n`io.quick_open_filters` table is used. If that filter does not exist, `lfs.default_filter`\nis used.\n*opts* is an optional table of additional options for `ui.dialogs.filteredlist()`.\n@param paths Optional string directory path or table of directory paths to search. The\n default value is the current project's root directory, if available.\n@param filter Optional filter for files and directories to include and/or exclude. The\n default value is `lfs.default_filter` unless a filter for *paths* is defined in\n `io.quick_open_filters`.\n@param opts Optional table of additional options for `ui.dialogs.filteredlist()`.\n@usage io.quick_open(buffer.filename:match('^(.+)[/\\]')) -- list all files in the current\n file's directory, subject to the default filter\n@usage io.quick_open(io.get_current_project(), '.lua') -- list all Lua files in the current\n project\n@usage io.quick_open(io.get_current_project(), '!/build') -- list all files in the current\n project except those in the build directory\n@see io.quick_open_filters\n@see lfs.default_filter\n@see quick_open_max\n@see ui.dialogs.filteredlist quick_open_filters io.quick_open_filters (table)\nMap of directory paths to filters used by `io.quick_open()`.\n@see quick_open quick_open_max io.quick_open_max (number)\nThe maximum number of files listed in the quick open dialog.\nThe default value is `1000`. -quit _G.quit()\nEmits a `QUIT` event, and unless any handler returns `false`, quits\nTextadept.\n@see events.QUIT -range lexer.range(s, e, single_line, escapes, balanced)\nCreates and returns a pattern that matches a range of text bounded by strings\nor patterns *s* and *e*.\nThis is a convenience function for matching more complicated ranges like\nstrings with escape characters, balanced parentheses, and block comments\n(nested or not). *e* is optional and defaults to *s*. *single_line* indicates\nwhether or not the range must be on a single line; *escapes* indicates\nwhether or not to allow '\' as an escape character; and *balanced* indicates\nwhether or not to handle balanced ranges like parentheses, and requires *s*\nand *e* to be different.\n@param s String or pattern start of a range.\n@param e Optional string or pattern end of a range. The default value is *s*.\n@param single_line Optional flag indicating whether or not the range must be\n on a single line. The default value is `false`.\n@param escapes Optional flag indicating whether or not the range end may\n be escaped by a '\' character.\n The default value is `false` unless *s* and *e* are identical,\n single-character strings. In that case, the default value is `true`.\n@param balanced Optional flag indicating whether or not to match a balanced\n range, like the "%b" Lua pattern. This flag only applies if *s* and *e* are\n different.\n@usage local dq_str_escapes = lexer.range('"')\n@usage local dq_str_noescapes = lexer.range('"', false, false)\n@usage local unbalanced_parens = lexer.range('(', ')')\n@usage local balanced_parens = lexer.range('(', ')', false, false, true)\n@return pattern -read spawn_proc:read(arg)\nReads and returns stdout from process *spawn_proc*, according to string\nformat or number *arg*.\nSimilar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be\nrunning. If an error occurs while reading, returns `nil`, an error code, and\nan error message.\nEnsure any read operations read all stdout available, as the stdout callback\nfunction passed to `os.spawn()` will not be called until the stdout buffer is\nclear.\n@param arg Optional argument similar to those in Lua's `io.read()`, but "n"\n is not supported. The default value is "l", which reads a line.\n@return string of bytes read +quit _G.quit()\nEmits a `QUIT` event, and unless any handler returns `false`, quits Textadept.\n@see events.QUIT +range lexer.range(s, e, single_line, escapes, balanced)\nCreates and returns a pattern that matches a range of text bounded by strings or patterns *s*\nand *e*.\nThis is a convenience function for matching more complicated ranges like strings with escape\ncharacters, balanced parentheses, and block comments (nested or not). *e* is optional and\ndefaults to *s*. *single_line* indicates whether or not the range must be on a single line;\n*escapes* indicates whether or not to allow '\' as an escape character; and *balanced*\nindicates whether or not to handle balanced ranges like parentheses, and requires *s* and *e*\nto be different.\n@param s String or pattern start of a range.\n@param e Optional string or pattern end of a range. The default value is *s*.\n@param single_line Optional flag indicating whether or not the range must be on a single\n line. The default value is `false`.\n@param escapes Optional flag indicating whether or not the range end may be escaped by a '\'\n character. The default value is `false` unless *s* and *e* are identical, single-character\n strings. In that case, the default value is `true`.\n@param balanced Optional flag indicating whether or not to match a balanced range, like the\n "%b" Lua pattern. This flag only applies if *s* and *e* are different.\n@usage local dq_str_escapes = lexer.range('"')\n@usage local dq_str_noescapes = lexer.range('"', false, false)\n@usage local unbalanced_parens = lexer.range('(', ')')\n@usage local balanced_parens = lexer.range('(', ')', false, false, true)\n@return pattern +read spawn_proc:read(arg)\nReads and returns stdout from process *spawn_proc*, according to string format or number *arg*.\nSimilar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be running. If\nan error occurs while reading, returns `nil`, an error code, and an error message.\nEnsure any read operations read all stdout available, as the stdout callback function passed\nto `os.spawn()` will not be called until the stdout buffer is clear.\n@param arg Optional argument similar to those in Lua's `io.read()`, but "n" is not\n supported. The default value is "l", which reads a line.\n@return string of bytes read read_only buffer.read_only (bool)\nWhether or not the buffer is read-only.\nThe default value is `false`. recent_files io.recent_files (table)\nList of recently opened files, the most recent being towards the top. -record textadept.history.record(filename, line, column, soft)\nRecords the given location in the current view's history.\n@param filename Optional string filename, buffer type, or identifier of the\n buffer to store. If `nil`, uses the current buffer.\n@param line Optional Integer line number to store. If `nil`, uses the current\n line.\n@param column Optional integer column number on line *line* to store. If\n `nil`, uses the current column.\n@param soft Optional flag that indicates whether or not this record should be\n skipped when navigating backward towards it, and updated when navigating\n away from it. The default value is `false`. +record textadept.history.record(filename, line, column, soft)\nRecords the given location in the current view's history.\n@param filename Optional string filename, buffer type, or identifier of the buffer to store. If\n `nil`, uses the current buffer.\n@param line Optional Integer line number to store. If `nil`, uses the current line.\n@param column Optional integer column number on line *line* to store. If `nil`, uses the\n current column.\n@param soft Optional flag that indicates whether or not this record should be skipped when\n navigating backward towards it, and updated when navigating away from it. The default\n value is `false`. record textadept.macros.record()\nToggles between starting and stopping macro recording. rectangular_selection_anchor buffer.rectangular_selection_anchor (number)\nThe rectangular selection's anchor position. rectangular_selection_anchor_virtual_space buffer.rectangular_selection_anchor_virtual_space (number)\nThe amount of virtual space for the rectangular selection's anchor. rectangular_selection_caret buffer.rectangular_selection_caret (number)\nThe rectangular selection's caret position. rectangular_selection_caret_virtual_space buffer.rectangular_selection_caret_virtual_space (number)\nThe amount of virtual space for the rectangular selection's caret. -rectangular_selection_modifier view.rectangular_selection_modifier (number)\nThe modifier key used in combination with a mouse drag in order to create a\nrectangular selection.\n\n* `view.MOD_CTRL`\n The "Control" modifier key.\n* `view.MOD_ALT`\n The "Alt" modifier key.\n* `view.MOD_SUPER`\n The "Super" modifier key, usually defined as the left "Windows" or\n "Command" key.\n\nThe default value is `view.MOD_CTRL`. +rectangular_selection_modifier view.rectangular_selection_modifier (number)\nThe modifier key used in combination with a mouse drag in order to create a rectangular\nselection.\n\n* `view.MOD_CTRL`\n The "Control" modifier key.\n* `view.MOD_ALT`\n The "Alt" modifier key.\n* `view.MOD_SUPER`\n The "Super" modifier key, usually defined as the left "Windows" or\n "Command" key.\n\nThe default value is `view.MOD_CTRL`. redo buffer.redo(buffer)\nRedoes the next undone action.\n@param buffer A buffer. regex ui.find.regex (bool)\nInterpret search text as a Regular Expression.\nThe default value is `false`. regex_label_text ui.find.regex_label_text (string, Write-only)\nThe text of the "Regex" label.\nThis is primarily used for localization. -register args.register(short, long, narg, f, description)\nRegisters a command line option with short and long versions *short* and\n*long*, respectively. *narg* is the number of arguments the option accepts,\n*f* is the function called when the option is set, and *description* is\nthe option's description when displaying help.\n@param short The string short version of the option.\n@param long The string long version of the option.\n@param narg The number of expected parameters for the option.\n@param f The Lua function to run when the option is set. It is passed *narg*\n string arguments.\n@param description The string description of the option for command line\n help. -register_image view.register_image(view, type, xpm_data)\nRegisters XPM image *xpm_data* to type number *type* for use in\nautocompletion and user lists.\n@param view A view.\n@param type Integer type to register the image with.\n@param xpm_data The XPM data as described in `view.marker_define_pixmap()`. -register_rgba_image view.register_rgba_image(view, type, pixels)\nRegisters RGBA image *pixels* to type number *type* for use in autocompletion\nand user lists.\nThe dimensions for *pixels* (`view.rgba_image_width` and\n`view.rgba_image_height`) must have already been defined. *pixels* is a\nsequence of 4 byte pixel values (red, blue, green, and alpha) defining the\nimage line by line starting at the top-left pixel.\n@param view A view.\n@param type Integer type to register the image with.\n@param pixels The RGBA data as described in\n `view.marker_define_rgba_image()`. -reload buffer.reload(buffer)\nReloads the buffer's file contents, discarding any changes.\nEmits `FILE_BEFORE_RELOAD` and `FILE_AFTER_RELOAD` events if the buffer is\nthe current one.\n@param buffer A buffer. +register args.register(short, long, narg, f, description)\nRegisters a command line option with short and long versions *short* and *long*, respectively.\n*narg* is the number of arguments the option accepts, *f* is the function called when the\noption is set, and *description* is the option's description when displaying help.\n@param short The string short version of the option.\n@param long The string long version of the option.\n@param narg The number of expected parameters for the option.\n@param f The Lua function to run when the option is set. It is passed *narg* string arguments.\n@param description The string description of the option for command line help. +register_image view.register_image(view, type, xpm_data)\nRegisters XPM image *xpm_data* to type number *type* for use in autocompletion and user lists.\n@param view A view.\n@param type Integer type to register the image with.\n@param xpm_data The XPM data as described in `view.marker_define_pixmap()`. +register_rgba_image view.register_rgba_image(view, type, pixels)\nRegisters RGBA image *pixels* to type number *type* for use in autocompletion and user lists.\nThe dimensions for *pixels* (`view.rgba_image_width` and `view.rgba_image_height`) must\nhave already been defined. *pixels* is a sequence of 4 byte pixel values (red, blue, green,\nand alpha) defining the image line by line starting at the top-left pixel.\n@param view A view.\n@param type Integer type to register the image with.\n@param pixels The RGBA data as described in `view.marker_define_rgba_image()`. +reload buffer.reload(buffer)\nReloads the buffer's file contents, discarding any changes.\nEmits `FILE_BEFORE_RELOAD` and `FILE_AFTER_RELOAD` events if the buffer is the current one.\n@param buffer A buffer. replace ui.find.replace()\nMimics pressing the "Replace" button. replace_all ui.find.replace_all()\nMimics pressing the "Replace All" button. replace_all_button_text ui.find.replace_all_button_text (string, Write-only)\nThe text of the "Replace All" button.\nThis is primarily used for localization. replace_button_text ui.find.replace_button_text (string, Write-only)\nThe text of the "Replace" button.\nThis is primarily used for localization. -replace_entry_text ui.find.replace_entry_text (string)\nThe text in the "Replace" entry.\nWhen searching for text in a directory of files, this is the current file\nand directory filter. +replace_entry_text ui.find.replace_entry_text (string)\nThe text in the "Replace" entry.\nWhen searching for text in a directory of files, this is the current file and directory filter. replace_label_text ui.find.replace_label_text (string, Write-only)\nThe text of the "Replace" label.\nThis is primarily used for localization. replace_sel buffer.replace_sel(buffer, text)\nReplaces the selected text with string *text*, scrolling the caret into view.\n@param buffer A buffer.\n@param text The text to replace the selected text with. -replace_target buffer.replace_target(buffer, text)\nReplaces the text in the target range with string *text* sans modifying any\nselections or scrolling the view.\nSetting the target and calling this function with an empty string is another\nway to delete text.\n@param buffer A buffer.\n@param text The text to replace the target range with.\n@return number -replace_target_re buffer.replace_target_re(buffer, text)\nReplaces the text in the target range with string *text* but first replaces\nany "\d" sequences with the text of capture number *d* from the regular\nexpression (or the entire match for *d* = 0), and then returns the\nreplacement text's length.\n@param buffer A buffer.\n@param text The text to replace the target range with.\n@return number -representation view.representation (table)\nThe alternative string representations of characters.\nRepresentations are displayed in the same way control characters are. Use\nthe empty string for the '\0' character when assigning its representation.\nCharacters are strings, not numeric codes, and can be multi-byte\ncharacters.\nCall `view.clear_representation()` to remove a representation. -reset _G.reset()\nResets the Lua State by reloading all initialization scripts.\nLanguage modules for opened files are NOT reloaded. Re-opening the files that\nuse them will reload those modules instead.\nThis function is useful for modifying user scripts (such as\n*~/.textadept/init.lua* and *~/.textadept/modules/textadept/keys.lua*) on\nthe fly without having to restart Textadept. `arg` is set to `nil` when\nreinitializing the Lua State. Any scripts that need to differentiate between\nstartup and reset can test `arg`. -rgba_image_height view.rgba_image_height (number)\nThe height of the RGBA image to be defined using\n`view.marker_define_rgba_image()`. -rgba_image_scale view.rgba_image_scale (number)\nThe scale factor in percent of the RGBA image to be defined using\n`view.marker_define_rgba_image()`.\nThis is useful on macOS with a retina display where each display unit is 2\npixels: use a factor of `200` so that each image pixel is displayed using a\nscreen pixel. The default scale, `100`, will stretch each image pixel to\ncover 4 screen pixels on a retina display. -rgba_image_width view.rgba_image_width (number)\nThe width of the RGBA image to be defined using\n`view.marker_define_rgba_image()` and\n`view.register_rgba_image()`. +replace_target buffer.replace_target(buffer, text)\nReplaces the text in the target range with string *text* sans modifying any selections or\nscrolling the view.\nSetting the target and calling this function with an empty string is another way to delete text.\n@param buffer A buffer.\n@param text The text to replace the target range with.\n@return number +replace_target_re buffer.replace_target_re(buffer, text)\nReplaces the text in the target range with string *text* but first replaces any "\d" sequences\nwith the text of capture number *d* from the regular expression (or the entire match for *d*\n= 0), and then returns the replacement text's length.\n@param buffer A buffer.\n@param text The text to replace the target range with.\n@return number +representation view.representation (table)\nThe alternative string representations of characters.\nRepresentations are displayed in the same way control characters are. Use the empty\nstring for the '\0' character when assigning its representation. Characters are strings,\nnot numeric codes, and can be multi-byte characters.\nCall `view.clear_representation()` to remove a representation. +reset _G.reset()\nResets the Lua State by reloading all initialization scripts.\nLanguage modules for opened files are NOT reloaded. Re-opening the files that use them will\nreload those modules instead.\nThis function is useful for modifying user scripts (such as *~/.textadept/init.lua* and\n*~/.textadept/modules/textadept/keys.lua*) on the fly without having to restart Textadept. `arg`\nis set to `nil` when reinitializing the Lua State. Any scripts that need to differentiate\nbetween startup and reset can test `arg`. +rgba_image_height view.rgba_image_height (number)\nThe height of the RGBA image to be defined using `view.marker_define_rgba_image()`. +rgba_image_scale view.rgba_image_scale (number)\nThe scale factor in percent of the RGBA image to be defined using\n`view.marker_define_rgba_image()`.\nThis is useful on macOS with a retina display where each display unit is 2 pixels: use a\nfactor of `200` so that each image pixel is displayed using a screen pixel.\nThe default scale, `100`, will stretch each image pixel to cover 4 screen pixels on a\nretina display. +rgba_image_width view.rgba_image_width (number)\nThe width of the RGBA image to be defined using `view.marker_define_rgba_image()` and\n`view.register_rgba_image()`. rotate_selection buffer.rotate_selection(buffer)\nDesignates the next additional selection to be the main selection.\n@param buffer A buffer. -run textadept.run (module)\nCompile and run source code files with Textadept.\nLanguage modules may tweak the `compile_commands`,\n`run_commands`, and `error_patterns` tables for particular languages.\nThe user may tweak `build_commands` and `test_commands` for particular\nprojects. -run textadept.run.run(filename)\nRuns file *filename* or the current file using an appropriate shell command\nfrom the `run_commands` table.\nThe shell command is determined from the file's filename, extension, or\nlanguage in that order.\nEmits `RUN_OUTPUT` events.\n@param filename Optional path to the file to run. The default value is the\n current file's filename.\n@see run_commands\n@see _G.events -run ui.command_entry.run(f, keys, lang, height)\nOpens the command entry, subjecting it to any key bindings defined in table\n*keys*, highlighting text with lexer name *lang*, and displaying\n*height* number of lines at a time, and then when the `Enter` key is pressed,\ncloses the command entry and calls function *f* (if non-`nil`) with the\ncommand entry's text as an argument.\nBy default with no arguments given, opens a Lua command entry.\nThe command entry does not respond to Textadept's default key bindings, but\ninstead to the key bindings defined in *keys* and in\n`ui.command_entry.editing_keys`.\n@param f Optional function to call upon pressing `Enter` in the command\n entry, ending the mode. It should accept the command entry text as an\n argument.\n@param keys Optional table of key bindings to respond to. This is in\n addition to the basic editing and movement keys defined in\n `ui.command_entry.editing_keys`.\n `Esc` and `Enter` are automatically defined to cancel and finish the\n command entry, respectively.\n This parameter may be omitted completely.\n@param lang Optional string lexer name to use for command entry text. The\n default value is `'text'`.\n@param height Optional number of lines to display in the command entry. The\n default value is `1`.\n@usage ui.command_entry.run(ui.print)\n@see editing_keys -run_commands textadept.run.run_commands (table)\nMap of filenames, file extensions, and lexer names to their associated "run"\nshell command line strings or functions that return strings.\nCommand line strings may have the following macros:\n\n + `%f`: The file's name, including its extension.\n + `%e`: The file's name, excluding its extension.\n + `%d`: The file's directory path.\n + `%p`: The file's full path.\n\nFunctions may also return a working directory and process environment table\nto operate in. By default, the working directory is the current file's parent\ndirectory and the environment is Textadept's environment. -run_in_background textadept.run.run_in_background (bool)\nRun shell commands silently in the background.\nThis only applies when the message buffer is open, though it does not have\nto be visible.\nThe default value is `false`. +run textadept.run (module)\nCompile and run source code files with Textadept.\nLanguage modules may tweak the `compile_commands`, `run_commands`, and\n`error_patterns` tables for particular languages.\nThe user may tweak `build_commands` and `test_commands` for particular projects. +run textadept.run.run(filename)\nRuns file *filename* or the current file using an appropriate shell command from the\n`run_commands` table.\nThe shell command is determined from the file's filename, extension, or language in that order.\nEmits `RUN_OUTPUT` events.\n@param filename Optional path to the file to run. The default value is the current file's\n filename.\n@see run_commands\n@see _G.events +run ui.command_entry.run(f, keys, lang, height)\nOpens the command entry, subjecting it to any key bindings defined in table *keys*,\nhighlighting text with lexer name *lang*, and displaying *height* number of lines at a time,\nand then when the `Enter` key is pressed, closes the command entry and calls function *f*\n(if non-`nil`) with the command entry's text as an argument.\nBy default with no arguments given, opens a Lua command entry.\nThe command entry does not respond to Textadept's default key bindings, but instead to the\nkey bindings defined in *keys* and in `ui.command_entry.editing_keys`.\n@param f Optional function to call upon pressing `Enter` in the command entry, ending the mode.\n It should accept the command entry text as an argument.\n@param keys Optional table of key bindings to respond to. This is in addition to the\n basic editing and movement keys defined in `ui.command_entry.editing_keys`. `Esc` and\n `Enter` are automatically defined to cancel and finish the command entry, respectively.\n This parameter may be omitted completely.\n@param lang Optional string lexer name to use for command entry text. The default value is\n `'text'`.\n@param height Optional number of lines to display in the command entry. The default value is `1`.\n@usage ui.command_entry.run(ui.print)\n@see editing_keys +run_commands textadept.run.run_commands (table)\nMap of filenames, file extensions, and lexer names to their associated "run" shell command\nline strings or functions that return strings.\nCommand line strings may have the following macros:\n\n + `%f`: The file's name, including its extension.\n + `%e`: The file's name, excluding its extension.\n + `%d`: The file's directory path.\n + `%p`: The file's full path.\n\nFunctions may also return a working directory and process environment table to operate in. By\ndefault, the working directory is the current file's parent directory and the environment\nis Textadept's environment. +run_in_background textadept.run.run_in_background (bool)\nRun shell commands silently in the background.\nThis only applies when the message buffer is open, though it does not have to be visible.\nThe default value is `false`. save buffer.save(buffer)\nSaves the buffer to its file.\nIf the buffer does not have a file, the user is prompted for one.\nEmits `FILE_BEFORE_SAVE` and `FILE_AFTER_SAVE` events.\n@param buffer A buffer. -save textadept.macros.save(filename)\nSaves a recorded macro to file *filename* or the user-selected file.\n@param filename Optional filename to save the recorded macro to. If `nil`,\n the user is prompted for one. -save textadept.session.save(filename)\nSaves the session to file *filename* or the user-selected file.\nSaves split views, opened buffers, cursor information, recent files, and\nbookmarks.\nUpon quitting, the current session is saved to *filename* again, unless\n`textadept.session.save_on_quit` is `false`.\n@param filename Optional absolute path to the session file to save. If `nil`,\n the user is prompted for one.\n@usage textadept.session.save(filename) +save textadept.macros.save(filename)\nSaves a recorded macro to file *filename* or the user-selected file.\n@param filename Optional filename to save the recorded macro to. If `nil`, the user is\n prompted for one. +save textadept.session.save(filename)\nSaves the session to file *filename* or the user-selected file.\nSaves split views, opened buffers, cursor information, recent files, and bookmarks.\nUpon quitting, the current session is saved to *filename* again, unless\n`textadept.session.save_on_quit` is `false`.\n@param filename Optional absolute path to the session file to save. If `nil`, the user is\n prompted for one.\n@usage textadept.session.save(filename) save_all_files io.save_all_files()\nSaves all unsaved buffers to their respective files.\n@see buffer.save -save_as buffer.save_as(buffer, filename)\nSaves the buffer to file *filename* or the user-specified filename.\nEmits a `FILE_AFTER_SAVE` event.\n@param buffer A buffer.\n@param filename Optional new filepath to save the buffer to. If `nil`, the\n user is prompted for one. -save_on_quit textadept.session.save_on_quit (bool)\nSave the session when quitting.\nThe default value is `true` unless the user passed the command line switch\n`-n` or `--nosession` to Textadept. +save_as buffer.save_as(buffer, filename)\nSaves the buffer to file *filename* or the user-specified filename.\nEmits a `FILE_AFTER_SAVE` event.\n@param buffer A buffer.\n@param filename Optional new filepath to save the buffer to. If `nil`, the user is prompted\n for one. +save_on_quit textadept.session.save_on_quit (bool)\nSave the session when quitting.\nThe default value is `true` unless the user passed the command line switch `-n` or\n`--nosession` to Textadept. scroll_caret view.scroll_caret(view)\nScrolls the caret into view based on the policies previously defined in\n`view.set_x_caret_policy()` and `view.set_y_caret_policy()`.\n@param view A view.\n@see set_x_caret_policy\n@see set_y_caret_policy -scroll_range view.scroll_range(view, secondary_pos, primary_pos)\nScrolls into view the range of text between positions *primary_pos* and\n*secondary_pos*, with priority given to *primary_pos*.\nSimilar to `view.scroll_caret()`, but with *primary_pos* instead of\n`buffer.current_pos`.\nThis is useful for scrolling search results into view.\n@param view A view.\n@param secondary_pos The secondary range position to scroll into view.\n@param primary_pos The primary range position to scroll into view. +scroll_range view.scroll_range(view, secondary_pos, primary_pos)\nScrolls into view the range of text between positions *primary_pos* and *secondary_pos*,\nwith priority given to *primary_pos*.\nSimilar to `view.scroll_caret()`, but with *primary_pos* instead of `buffer.current_pos`.\nThis is useful for scrolling search results into view.\n@param view A view.\n@param secondary_pos The secondary range position to scroll into view.\n@param primary_pos The primary range position to scroll into view. scroll_to_end view.scroll_to_end(view)\nScrolls to the end of the buffer without moving the caret.\n@param view A view. scroll_to_start view.scroll_to_start(view)\nScrolls to the beginning of the buffer without moving the caret.\n@param view A view. -scroll_width view.scroll_width (number)\nThe horizontal scrolling pixel width.\nFor performance, the view does not measure the display width of the buffer\nto determine the properties of the horizontal scroll bar, but uses an\nassumed width instead. To ensure the width of the currently visible lines\ncan be scrolled use `view.scroll_width_tracking`.\nThe default value is `2000`. -scroll_width_tracking view.scroll_width_tracking (bool)\nContinuously update the horizontal scrolling width to match the maximum\nwidth of a displayed line beyond `view.scroll_width`.\nThe default value is `false`. -search_anchor buffer.search_anchor(buffer)\nAnchors the position that `buffer.search_next()` and `buffer.search_prev()`\nstart at to the beginning of the current selection or caret position.\n@param buffer A buffer. -search_flags buffer.search_flags (number)\nThe bit-mask of search flags used by `buffer.search_in_target()`.\n\n* `buffer.FIND_WHOLEWORD`\n Match search text only when it is surrounded by non-word characters.\n* `buffer.FIND_MATCHCASE`\n Match search text case sensitively.\n* `buffer.FIND_WORDSTART`\n Match search text only when the previous character is a non-word\n character.\n* `buffer.FIND_REGEXP`\n Interpret search text as a regular expression.\n\nThe default value is `0`. -search_in_target buffer.search_in_target(buffer, text)\nSearches for the first occurrence of string *text* in the target range\nbounded by `buffer.target_start` and `buffer.target_end` using search flags\n`buffer.search_flags` and, if found, sets the new target range to that\noccurrence, returning its position or `-1` if *text* was not found.\n@param buffer A buffer.\n@param text The text to search the target range for.\n@return number\n@see search_flags -search_next buffer.search_next(buffer, flags, text)\nSearches for and selects the first occurrence of string *text* starting at\nthe search anchor using search flags *flags*, returning that occurrence's\nposition or `-1` if *text* was not found.\nSelected text is not scrolled into view.\n@param buffer A buffer.\n@param flags The search flags to use. See `buffer.search_flags`.\n@param text The text to search for.\n@return number\n@see search_flags -search_prev buffer.search_prev(buffer, flags, text)\nSearches for and selects the last occurrence of string *text* before the\nsearch anchor using search flags *flags*, returning that occurrence's\nposition or `-1` if *text* was not found.\n@param buffer A buffer.\n@param flags The search flags to use. See `buffer.search_flags`.\n@param text The text to search for.\n@return number\n@see search_flags -secure_inputbox ui.dialogs.secure_inputbox(options)\nPrompts the user with a masked inputbox dialog defined by dialog options\ntable *options*, returning the selected button's index along with the user's\ninput text (the latter as a string or table, depending on the type of\n*options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the user's input text.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a\n table, the first table value is the main message text and any subsequent\n values are used as the labels for multiple entry boxes. Providing a\n single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the\n table values are used to populate the multiple entry boxes defined by\n `informative_text`.\n * `button1`: The right-most button's label. The default value is\n `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2`\n to be set.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@return selected button or exit code, input text -secure_standard_inputbox ui.dialogs.secure_standard_inputbox(options)\nPrompts the user with a masked inputbox dialog defined by dialog options\ntable *options* and with localized "Ok" and "Cancel" buttons, returning the\nselected button's index along with the user's input text (the latter as a\nstring or table, depending on the type of *options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the user's input text.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a\n table, the first table value is the main message text and any subsequent\n values are used as the labels for multiple entry boxes. Providing a\n single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the\n table values are used to populate the multiple entry boxes defined by\n `informative_text`.\n * `no_cancel`: Do not display the "Cancel" button. The default value is\n `false`.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@return selected button or exit code, input text -sel_alpha view.sel_alpha (number)\nThe selection's alpha value, ranging from `0` (transparent) to `255`\n(opaque).\nThe default value is `view.ALPHA_NOALPHA`, for no alpha. +scroll_width view.scroll_width (number)\nThe horizontal scrolling pixel width.\nFor performance, the view does not measure the display width of the buffer to determine\nthe properties of the horizontal scroll bar, but uses an assumed width instead. To ensure\nthe width of the currently visible lines can be scrolled use `view.scroll_width_tracking`.\nThe default value is `2000`. +scroll_width_tracking view.scroll_width_tracking (bool)\nContinuously update the horizontal scrolling width to match the maximum width of a displayed\nline beyond `view.scroll_width`.\nThe default value is `false`. +search_anchor buffer.search_anchor(buffer)\nAnchors the position that `buffer.search_next()` and `buffer.search_prev()` start at to the\nbeginning of the current selection or caret position.\n@param buffer A buffer. +search_flags buffer.search_flags (number)\nThe bit-mask of search flags used by `buffer.search_in_target()`.\n\n* `buffer.FIND_WHOLEWORD`\n Match search text only when it is surrounded by non-word characters.\n* `buffer.FIND_MATCHCASE`\n Match search text case sensitively.\n* `buffer.FIND_WORDSTART`\n Match search text only when the previous character is a non-word character.\n* `buffer.FIND_REGEXP`\n Interpret search text as a regular expression.\n\nThe default value is `0`. +search_in_target buffer.search_in_target(buffer, text)\nSearches for the first occurrence of string *text* in the target range bounded by\n`buffer.target_start` and `buffer.target_end` using search flags `buffer.search_flags`\nand, if found, sets the new target range to that occurrence, returning its position or `-1`\nif *text* was not found.\n@param buffer A buffer.\n@param text The text to search the target range for.\n@return number\n@see search_flags +search_next buffer.search_next(buffer, flags, text)\nSearches for and selects the first occurrence of string *text* starting at the search\nanchor using search flags *flags*, returning that occurrence's position or `-1` if *text*\nwas not found.\nSelected text is not scrolled into view.\n@param buffer A buffer.\n@param flags The search flags to use. See `buffer.search_flags`.\n@param text The text to search for.\n@return number\n@see search_flags +search_prev buffer.search_prev(buffer, flags, text)\nSearches for and selects the last occurrence of string *text* before the search anchor using\nsearch flags *flags*, returning that occurrence's position or `-1` if *text* was not found.\n@param buffer A buffer.\n@param flags The search flags to use. See `buffer.search_flags`.\n@param text The text to search for.\n@return number\n@see search_flags +secure_inputbox ui.dialogs.secure_inputbox(options)\nPrompts the user with a masked inputbox dialog defined by dialog options table *options*,\nreturning the selected button's index along with the user's input text (the latter as a\nstring or table, depending on the type of *options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\nuser's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled\nthe dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a table, the first\n table value is the main message text and any subsequent values are used as the labels\n for multiple entry boxes. Providing a single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the table values are\n used to populate the multiple entry boxes defined by `informative_text`.\n * `button1`: The right-most button's label. The default value is `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2` to be set.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@return selected button or exit code, input text +secure_standard_inputbox ui.dialogs.secure_standard_inputbox(options)\nPrompts the user with a masked inputbox dialog defined by dialog options table *options*\nand with localized "Ok" and "Cancel" buttons, returning the selected button's index along\nwith the user's input text (the latter as a string or table, depending on the type of\n*options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\nuser's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled\nthe dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a table, the first\n table value is the main message text and any subsequent values are used as the labels\n for multiple entry boxes. Providing a single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the table values are\n used to populate the multiple entry boxes defined by `informative_text`.\n * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@return selected button or exit code, input text +sel_alpha view.sel_alpha (number)\nThe selection's alpha value, ranging from `0` (transparent) to `255` (opaque).\nThe default value is `view.ALPHA_NOALPHA`, for no alpha. sel_eol_filled view.sel_eol_filled (bool)\nExtend the selection to the view's right margin.\nThe default value is `false`. -select textadept.snippets.select()\nPrompts the user to select a snippet to insert from a list of global and\nlanguage-specific snippets. +select textadept.snippets.select()\nPrompts the user to select a snippet to insert from a list of global and language-specific\nsnippets. select_all buffer.select_all(buffer)\nSelects all of the buffer's text without scrolling the view.\n@param buffer A buffer. select_command textadept.menu.select_command()\nPrompts the user to select a menu command to run. -select_enclosed textadept.editing.select_enclosed(left, right)\nSelects the text between strings *left* and *right* that enclose the caret.\nIf that range is already selected, toggles between selecting *left* and\n*right* as well.\nIf *left* and *right* are not provided, they are assumed to be one of the\ndelimiter pairs specified in `auto_pairs` and are inferred from the current\nposition or selection.\n@param left Optional left part of the enclosure.\n@param right Optional right part of the enclosure.\n@see auto_pairs +select_enclosed textadept.editing.select_enclosed(left, right)\nSelects the text between strings *left* and *right* that enclose the caret.\nIf that range is already selected, toggles between selecting *left* and *right* as well.\nIf *left* and *right* are not provided, they are assumed to be one of the delimiter pairs\nspecified in `auto_pairs` and are inferred from the current position or selection.\n@param left Optional left part of the enclosure.\n@param right Optional right part of the enclosure.\n@see auto_pairs select_lexer textadept.file_types.select_lexer()\nPrompts the user to select a lexer for the current buffer.\n@see buffer.set_lexer select_line textadept.editing.select_line()\nSelects the current line. select_paragraph textadept.editing.select_paragraph()\nSelects the current paragraph.\nParagraphs are surrounded by one or more blank lines. -select_word textadept.editing.select_word(all)\nSelects the current word or, if *all* is `true`, all occurrences of the\ncurrent word.\nIf a word is already selected, selects the next occurrence as a multiple\nselection.\n@param all Whether or not to select all occurrences of the current word.\n The default value is `false`.\n@see buffer.word_chars +select_word textadept.editing.select_word(all)\nSelects the current word or, if *all* is `true`, all occurrences of the current word.\nIf a word is already selected, selects the next occurrence as a multiple selection.\n@param all Whether or not to select all occurrences of the current word. The default value is\n `false`.\n@see buffer.word_chars selection_duplicate buffer.selection_duplicate(buffer)\nDuplicates the selected text to its right.\nIf no text is selected, duplicates the current line on a new line below.\n@param buffer A buffer. selection_empty buffer.selection_empty (bool, Read-only)\nWhether or not no text is selected. selection_end buffer.selection_end (number)\nThe position of the end of the selected text.\nWhen set, becomes the current position, but is not scrolled into view. selection_is_rectangle buffer.selection_is_rectangle (bool, Read-only)\nWhether or not the selection is a rectangular selection. -selection_mode buffer.selection_mode (number)\nThe selection mode.\n\n* `buffer.SEL_STREAM`\n Character selection.\n* `buffer.SEL_RECTANGLE`\n Rectangular selection.\n* `buffer.SEL_LINES`\n Line selection.\n* `buffer.SEL_THIN`\n Thin rectangular selection. This is the mode after a rectangular\n selection has been typed into and ensures that no characters are\n selected.\n\nWhen set, caret movement alters the selected text until this field is set\nagain to the same value or until `buffer.cancel()` is called. -selection_n_anchor buffer.selection_n_anchor (table)\nTable of positions at the beginning of existing selections numbered from\n`1`, the main selection. -selection_n_anchor_virtual_space buffer.selection_n_anchor_virtual_space (table)\nTable of positions at the beginning of virtual space selected in existing\nselections numbered from `1`, the main selection. -selection_n_caret buffer.selection_n_caret (table)\nTable of positions at the end of existing selections numbered from `1`,\nthe main selection. -selection_n_caret_virtual_space buffer.selection_n_caret_virtual_space (table)\nTable of positions at the end of virtual space selected in existing\nselections numbered from `1`, the main selection. -selection_n_end buffer.selection_n_end (table)\nTable of positions at the end of existing selections numbered from `1`,\nthe main selection. -selection_n_end_virtual_space buffer.selection_n_end_virtual_space (number, Read-only)\nTable of positions at the end of virtual space selected in existing\nselections numbered from `1`, the main selection. -selection_n_start buffer.selection_n_start (table)\nTable of positions at the beginning of existing selections numbered from\n`1`, the main selection. -selection_n_start_virtual_space buffer.selection_n_start_virtual_space (number, Read-only)\nTable of positions at the beginning of virtual space selected in existing\nselections numbered from `1`, the main selection. +selection_mode buffer.selection_mode (number)\nThe selection mode.\n\n* `buffer.SEL_STREAM`\n Character selection.\n* `buffer.SEL_RECTANGLE`\n Rectangular selection.\n* `buffer.SEL_LINES`\n Line selection.\n* `buffer.SEL_THIN`\n Thin rectangular selection. This is the mode after a rectangular selection has been\n typed into and ensures that no characters are selected.\n\nWhen set, caret movement alters the selected text until this field is set again to the\nsame value or until `buffer.cancel()` is called. +selection_n_anchor buffer.selection_n_anchor (table)\nTable of positions at the beginning of existing selections numbered from `1`, the main\nselection. +selection_n_anchor_virtual_space buffer.selection_n_anchor_virtual_space (table)\nTable of positions at the beginning of virtual space selected in existing selections\nnumbered from `1`, the main selection. +selection_n_caret buffer.selection_n_caret (table)\nTable of positions at the end of existing selections numbered from `1`, the main selection. +selection_n_caret_virtual_space buffer.selection_n_caret_virtual_space (table)\nTable of positions at the end of virtual space selected in existing selections numbered from\n`1`, the main selection. +selection_n_end buffer.selection_n_end (table)\nTable of positions at the end of existing selections numbered from `1`, the main selection. +selection_n_end_virtual_space buffer.selection_n_end_virtual_space (number, Read-only)\nTable of positions at the end of virtual space selected in existing selections numbered from\n`1`, the main selection. +selection_n_start buffer.selection_n_start (table)\nTable of positions at the beginning of existing selections numbered from `1`, the main\nselection. +selection_n_start_virtual_space buffer.selection_n_start_virtual_space (number, Read-only)\nTable of positions at the beginning of virtual space selected in existing selections\nnumbered from `1`, the main selection. selection_start buffer.selection_start (number)\nThe position of the beginning of the selected text.\nWhen set, becomes the anchor, but is not scrolled into view. selections buffer.selections (number, Read-only)\nThe number of active selections. There is always at least one selection. session textadept.session (module)\nSession support for Textadept. -set_arguments textadept.run.set_arguments(filename, run, compile)\nAppends the command line argument strings *run* and *compile* to their\nrespective run and compile commands for file *filename* or the current file.\nIf either is `nil`, prompts the user for missing the arguments. Each filename\nhas its own set of compile and run arguments.\n@param filename Optional path to the file to set run/compile arguments for.\n@param run Optional string run arguments to set. If `nil`, the user is\n prompted for them. Pass the empty string for no run arguments.\n@param compile Optional string compile arguments to set. If `nil`, the user\n is prompted for them. Pass the empty string for no compile arguments.\n@see run_commands\n@see compile_commands -set_chars_default buffer.set_chars_default(buffer)\nResets `buffer.word_chars`, `buffer.whitespace_chars`, and\n`buffer.punctuation_chars` to their respective defaults.\n@param buffer A buffer.\n@see word_chars\n@see whitespace_chars\n@see punctuation_chars +set_arguments textadept.run.set_arguments(filename, run, compile)\nAppends the command line argument strings *run* and *compile* to their respective run and\ncompile commands for file *filename* or the current file.\nIf either is `nil`, prompts the user for missing the arguments. Each filename has its own\nset of compile and run arguments.\n@param filename Optional path to the file to set run/compile arguments for.\n@param run Optional string run arguments to set. If `nil`, the user is prompted for them. Pass\n the empty string for no run arguments.\n@param compile Optional string compile arguments to set. If `nil`, the user is prompted\n for them. Pass the empty string for no compile arguments.\n@see run_commands\n@see compile_commands +set_chars_default buffer.set_chars_default(buffer)\nResets `buffer.word_chars`, `buffer.whitespace_chars`, and `buffer.punctuation_chars` to\ntheir respective defaults.\n@param buffer A buffer.\n@see word_chars\n@see whitespace_chars\n@see punctuation_chars set_default_fold_display_text view.set_default_fold_display_text(view, text)\nSets the default fold display text to string *text*.\n@param view A view.\n@param text The text to display by default next to folded lines.\n@see toggle_fold_show_text -set_empty_selection buffer.set_empty_selection(buffer, pos)\nMoves the caret to position *pos* without scrolling the view and removes any\nselections.\n@param buffer A buffer\n@param pos The position in *buffer* to move to. -set_encoding buffer.set_encoding(buffer, encoding)\nConverts the buffer's contents to encoding *encoding*.\n@param buffer A buffer.\n@param encoding The string encoding to set. Valid encodings are ones that GNU\n iconv accepts. If `nil`, assumes a binary encoding.\n@usage buffer:set_encoding('CP1252') -set_fold_margin_color view.set_fold_margin_color(view, use_setting, color)\nOverrides the fold margin's default color with color *color*, in "0xBBGGRR"\nformat,\nif *use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. -set_fold_margin_hi_color view.set_fold_margin_hi_color(view, use_setting, color)\nOverrides the fold margin's default highlight color with color *color*, in\n"0xBBGGRR" format, if *use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. -set_lexer buffer.set_lexer(buffer, name)\nAssociates string lexer name *name* or the auto-detected lexer name with the\nbuffer and then loads the appropriate language module if that module exists.\n@param buffer A buffer.\n@param name Optional string lexer name to set. If `nil`, attempts to\n auto-detect the buffer's lexer.\n@usage buffer:set_lexer('lexer_name') +set_empty_selection buffer.set_empty_selection(buffer, pos)\nMoves the caret to position *pos* without scrolling the view and removes any selections.\n@param buffer A buffer\n@param pos The position in *buffer* to move to. +set_encoding buffer.set_encoding(buffer, encoding)\nConverts the buffer's contents to encoding *encoding*.\n@param buffer A buffer.\n@param encoding The string encoding to set. Valid encodings are ones that GNU iconv accepts. If\n `nil`, assumes a binary encoding.\n@usage buffer:set_encoding('CP1252') +set_fold_margin_color view.set_fold_margin_color(view, use_setting, color)\nOverrides the fold margin's default color with color *color*, in "0xBBGGRR" format, if\n*use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. +set_fold_margin_hi_color view.set_fold_margin_hi_color(view, use_setting, color)\nOverrides the fold margin's default highlight color with color *color*, in "0xBBGGRR" format,\nif *use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. +set_lexer buffer.set_lexer(buffer, name)\nAssociates string lexer name *name* or the auto-detected lexer name with the buffer and then\nloads the appropriate language module if that module exists.\n@param buffer A buffer.\n@param name Optional string lexer name to set. If `nil`, attempts to auto-detect the\n buffer's lexer.\n@usage buffer:set_lexer('lexer_name') set_save_point buffer.set_save_point(buffer)\nIndicates the buffer has no unsaved changes.\n@param buffer A buffer. -set_sel buffer.set_sel(buffer, start_pos, end_pos)\nSelects the range of text between positions *start_pos* and *end_pos*,\nscrolling the selected text into view.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to\n select. If negative, it means the end of the buffer.\n@param end_pos The end position of the range of text in *buffer* to select.\n If negative, it means remove any selection (i.e. set the `anchor` to the\n same position as `current_pos`). -set_sel_back view.set_sel_back(view, use_setting, color)\nOverrides the selection's default background color with color *color*, in\n"0xBBGGRR" format, if *use_setting* is `true`.\nOverwrites any existing `view.additional_sel_back` color.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. -set_sel_fore view.set_sel_fore(view, use_setting, color)\nOverrides the selection's default foreground color with color *color*, in\n"0xBBGGRR" format, if *use_setting* is `true`.\nOverwrites any existing `view.additional_sel_fore` color.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. -set_selection buffer.set_selection(buffer, end_pos, start_pos)\nSelects the range of text between positions *start_pos* to *end_pos*,\nremoving all other selections.\n@param buffer A buffer.\n@param end_pos The caret position of the range of text to select in *buffer*.\n@param start_pos The anchor position of the range of text to select in\n *buffer*. -set_styling buffer.set_styling(buffer, length, style)\nAssigns style number *style*, in the range from `1` to `256`, to the next\n*length* characters, starting from the current styling position, and\nincrements the styling position by *length*.\n`buffer:start_styling` should be called before `buffer:set_styling()`.\n@param buffer A buffer.\n@param length The number of characters to style.\n@param style The style number to set. -set_target_range buffer.set_target_range(buffer, start_pos, end_pos)\nDefines the target range's beginning and end positions as *start_pos* and\n*end_pos*, respectively.\n@param buffer A buffer.\n@param start_pos The position of the beginning of the target range.\n@param end_pos The position of the end of the target range. +set_sel buffer.set_sel(buffer, start_pos, end_pos)\nSelects the range of text between positions *start_pos* and *end_pos*, scrolling the selected\ntext into view.\n@param buffer A buffer.\n@param start_pos The start position of the range of text in *buffer* to select. If negative,\n it means the end of the buffer.\n@param end_pos The end position of the range of text in *buffer* to select. If negative,\n it means remove any selection (i.e. set the `anchor` to the same position as `current_pos`). +set_sel_back view.set_sel_back(view, use_setting, color)\nOverrides the selection's default background color with color *color*, in "0xBBGGRR" format,\nif *use_setting* is `true`.\nOverwrites any existing `view.additional_sel_back` color.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. +set_sel_fore view.set_sel_fore(view, use_setting, color)\nOverrides the selection's default foreground color with color *color*, in "0xBBGGRR" format,\nif *use_setting* is `true`.\nOverwrites any existing `view.additional_sel_fore` color.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. +set_selection buffer.set_selection(buffer, end_pos, start_pos)\nSelects the range of text between positions *start_pos* to *end_pos*, removing all other\nselections.\n@param buffer A buffer.\n@param end_pos The caret position of the range of text to select in *buffer*.\n@param start_pos The anchor position of the range of text to select in *buffer*. +set_styling buffer.set_styling(buffer, length, style)\nAssigns style number *style*, in the range from `1` to `256`, to the next *length* characters,\nstarting from the current styling position, and increments the styling position by *length*.\n`buffer:start_styling` should be called before `buffer:set_styling()`.\n@param buffer A buffer.\n@param length The number of characters to style.\n@param style The style number to set. +set_target_range buffer.set_target_range(buffer, start_pos, end_pos)\nDefines the target range's beginning and end positions as *start_pos* and *end_pos*,\nrespectively.\n@param buffer A buffer.\n@param start_pos The position of the beginning of the target range.\n@param end_pos The position of the end of the target range. set_text buffer.set_text(buffer, text)\nReplaces the buffer's text with string *text*.\n@param buffer A buffer.\n@param text The text to set. -set_theme view.set_theme(view, name, env)\nSets the view's color theme to be string *name*, with the contents of table\n*env* available as global variables.\nUser themes override Textadept's default themes when they have the same name.\nIf *name* contains slashes, it is assumed to be an absolute path to a theme\ninstead of a theme name.\n@param view A view.\n@param name The name or absolute path of a theme to set.\n@param env Optional table of global variables themes can utilize to override\n default settings such as font and size.\n@usage view:set_theme('light', {font = 'Monospace', size = 12})\n@see _G.lexer.colors\n@see _G.lexer.styles -set_visible_policy view.set_visible_policy(view, policy, y)\nDefines scrolling policy bit-mask *policy* as the policy for keeping the\ncaret *y* number of lines away from the vertical margins as\n`view.ensure_visible_enforce_policy()` redisplays hidden or folded lines.\nIt is similar in operation to `view.set_y_caret_policy()`.\n@param view A view.\n@param policy The combination of `view.VISIBLE_SLOP` and\n `view.VISIBLE_STRICT` policy flags to set.\n@param y The number of lines from the vertical margins to keep the caret. -set_whitespace_back view.set_whitespace_back(view, use_setting, color)\nOverrides the background color of whitespace with color *color*, in\n"0xBBGGRR" format, if *use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. -set_whitespace_fore view.set_whitespace_fore(view, use_setting, color)\nOverrides the foreground color of whitespace with color *color*, in\n"0xBBGGRR" format, if *use_setting* is `true`.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. -set_x_caret_policy view.set_x_caret_policy(view, policy, x)\nDefines scrolling policy bit-mask *policy* as the policy for keeping the\ncaret *x* number of pixels away from the horizontal margins.\n@param view A view.\n@param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`,\n `view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set.\n@param x The number of pixels from the horizontal margins to keep the caret. -set_y_caret_policy view.set_y_caret_policy(view, policy, y)\nDefines scrolling policy bit-mask *policy* as the policy for keeping the\ncaret *y* number of lines away from the vertical margins.\n@param view A view.\n@param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`,\n `view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set.\n@param y The number of lines from the vertical margins to keep the caret. -show_documentation textadept.editing.show_documentation(pos, ignore_case)\nDisplays a call tip with documentation for the symbol under or directly\nbehind position *pos* or the caret position.\nDocumentation is read from API files in the `api_files` table.\nIf a call tip is already shown, cycles to the next one if it exists.\nSymbols are determined by using `buffer.word_chars`.\n@param pos Optional position of the symbol to show documentation for. If\n omitted, the caret position is used.\n@param ignore_case Optional flag that indicates whether or not to search\n API files case-insensitively for symbols. The default value is `false`.\n@see api_files\n@see buffer.word_chars -show_lines view.show_lines(view, start_line, end_line)\nShows the range of lines between line numbers *start_line* to *end_line*.\nThis has no effect on fold levels or fold flags and the first line cannot be\nhidden.\n@param view A view.\n@param start_line The start line of the range of lines in *view* to show.\n@param end_line The end line of the range of lines in *view* to show. -silent_print ui.silent_print (bool)\nWhether or not to print messages to buffers silently.\nThis is not guaranteed to be a constant value, as Textadept may change it\nfor the editor's own purposes. This flag should be used only in conjunction\nwith a group of `ui.print()` and `ui._print()` function calls.\nThe default value is `false`, and focuses buffers when messages are printed\nto them. +set_theme view.set_theme(view, name, env)\nSets the view's color theme to be string *name*, with the contents of table *env* available\nas global variables.\nUser themes override Textadept's default themes when they have the same name. If *name*\ncontains slashes, it is assumed to be an absolute path to a theme instead of a theme name.\n@param view A view.\n@param name The name or absolute path of a theme to set.\n@param env Optional table of global variables themes can utilize to override default settings\n such as font and size.\n@usage view:set_theme('light', {font = 'Monospace', size = 12})\n@see _G.lexer.colors\n@see _G.lexer.styles +set_visible_policy view.set_visible_policy(view, policy, y)\nDefines scrolling policy bit-mask *policy* as the policy for keeping the caret *y* number\nof lines away from the vertical margins as `view.ensure_visible_enforce_policy()` redisplays\nhidden or folded lines.\nIt is similar in operation to `view.set_y_caret_policy()`.\n@param view A view.\n@param policy The combination of `view.VISIBLE_SLOP` and `view.VISIBLE_STRICT` policy flags\n to set.\n@param y The number of lines from the vertical margins to keep the caret. +set_whitespace_back view.set_whitespace_back(view, use_setting, color)\nOverrides the background color of whitespace with color *color*, in "0xBBGGRR" format,\nif *use_setting* is `true`.\n@param view A view.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. +set_whitespace_fore view.set_whitespace_fore(view, use_setting, color)\nOverrides the foreground color of whitespace with color *color*, in "0xBBGGRR" format,\nif *use_setting* is `true`.\n@param use_setting Whether or not to use *color*.\n@param color The color in "0xBBGGRR" format. +set_x_caret_policy view.set_x_caret_policy(view, policy, x)\nDefines scrolling policy bit-mask *policy* as the policy for keeping the caret *x* number\nof pixels away from the horizontal margins.\n@param view A view.\n@param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, `view.CARET_EVEN`,\n and `view.CARET_JUMPS` policy flags to set.\n@param x The number of pixels from the horizontal margins to keep the caret. +set_y_caret_policy view.set_y_caret_policy(view, policy, y)\nDefines scrolling policy bit-mask *policy* as the policy for keeping the caret *y* number\nof lines away from the vertical margins.\n@param view A view.\n@param policy The combination of `view.CARET_SLOP`, `view.CARET_STRICT`, `view.CARET_EVEN`,\n and `view.CARET_JUMPS` policy flags to set.\n@param y The number of lines from the vertical margins to keep the caret. +show_documentation textadept.editing.show_documentation(pos, ignore_case)\nDisplays a call tip with documentation for the symbol under or directly behind position *pos*\nor the caret position.\nDocumentation is read from API files in the `api_files` table.\nIf a call tip is already shown, cycles to the next one if it exists.\nSymbols are determined by using `buffer.word_chars`.\n@param pos Optional position of the symbol to show documentation for. If omitted, the caret\n position is used.\n@param ignore_case Optional flag that indicates whether or not to search API files\n case-insensitively for symbols. The default value is `false`.\n@see api_files\n@see buffer.word_chars +show_lines view.show_lines(view, start_line, end_line)\nShows the range of lines between line numbers *start_line* to *end_line*.\nThis has no effect on fold levels or fold flags and the first line cannot be hidden.\n@param view A view.\n@param start_line The start line of the range of lines in *view* to show.\n@param end_line The end line of the range of lines in *view* to show. +silent_print ui.silent_print (bool)\nWhether or not to print messages to buffers silently.\nThis is not guaranteed to be a constant value, as Textadept may change it for the editor's\nown purposes. This flag should be used only in conjunction with a group of `ui.print()`\nand `ui._print()` function calls.\nThe default value is `false`, and focuses buffers when messages are printed to them. size ui.size (table)\nA table containing the width and height pixel values of Textadept's window. size view.size (number)\nThe split resizer's pixel position if the view is a split one. snippet textadept.editing.autocompleters.snippet (function)\nAutocompleter function for snippet trigger words. -snippets _G.snippets (table)\nMap of snippet triggers with their snippet text or functions that return such\ntext, with language-specific snippets tables assigned to a lexer name key. +snippets _G.snippets (table)\nMap of snippet triggers with their snippet text or functions that return such text, with\nlanguage-specific snippets tables assigned to a lexer name key. snippets textadept.snippets (module)\nSnippets for Textadept. -space lexer.space (pattern)\nA pattern that matches any whitespace character ('\t', '\v', '\f', '\\n',\n'\r', space). -spawn os.spawn(cmd, cwd, env, stdout_cb, stderr_cb, exit_cb)\nSpawns an interactive child process *cmd* in a separate thread, returning\na handle to that process.\nOn Windows, *cmd* is passed to `cmd.exe`: `%COMSPEC% /c [cmd]`.\nAt the moment, only the Windows terminal version spawns processes in the same\nthread.\n@param cmd A command line string that contains the program's name followed by\n arguments to pass to it. `PATH` is searched for program names.\n@param cwd Optional current working directory (cwd) for the child\n process. When omitted, the parent's cwd is used.\n@param env Optional map of environment variables for the child process.\n When omitted, Textadept's environment is used.\n@param stdout_cb Optional Lua function that accepts a string parameter for a\n block of standard output read from the child. Stdout is read asynchronously\n in 1KB or 0.5KB blocks (depending on the platform), or however much data is\n available at the time.\n At the moment, only the Win32 terminal version sends all output, whether it\n be stdout or stderr, to this callback after the process finishes.\n@param stderr_cb Optional Lua function that accepts a string parameter for a\n block of standard error read from the child. Stderr is read asynchronously\n in 1KB or 0.5kB blocks (depending on the platform), or however much data is\n available at the time.\n@param exit_cb Optional Lua function that is called when the child process\n finishes. The child's exit status is passed.\n@usage os.spawn('lua ' .. buffer.filename, print)\n@usage proc = os.spawn('lua -e "print(io.read())"', print)\n proc:write('foo\\n')\n@return proc or nil plus an error message on failure -split view.split(view, vertical)\nSplits the view into top and bottom views (unless *vertical* is `true`),\nfocuses the new view, and returns both the old and new views.\nIf *vertical* is `false`, splits the view vertically into left and\nright views.\nEmits a `VIEW_NEW` event.\n@param view The view to split.\n@param vertical Optional flag indicating whether or not to split the view\n vertically. The default value is `false`, for horizontal.\n@return old view and new view.\n@see events.VIEW_NEW -standard_dropdown ui.dialogs.standard_dropdown(options)\nPrompts the user with a drop-down item selection dialog defined by dialog\noptions table *options* and with localized "Ok" and "Cancel" buttons,\nreturning the selected button's index along with the selected item's index.\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the selected item's text.\nIf the dialog closed due to *options*.`exit_onchange`, returns `4` along with\neither the selected item's index or its text. If the dialog timed out,\nreturns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or\n`"delete"`.\n@param options Table of key-value option pairs for the drop-down dialog.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `items`: The list of string items to show in the drop-down.\n * `no_cancel`: Do not display the "Cancel" button. The default value is\n `false`.\n * `exit_onchange`: Close the dialog after selecting a new item. The default\n value is `false`.\n * `select`: The index of the initially selected list item. The default\n value is `1`.\n * `string_output`: Return the selected button's label (instead of its\n index) and the selected item's text (instead of its index). If no item\n was selected, returns the dialog's exit status (instead of its exit\n code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@return selected button or exit code, selected item -standard_inputbox ui.dialogs.standard_inputbox(options)\nPrompts the user with an inputbox dialog defined by dialog options table\n*options* and with localized "Ok" and "Cancel" buttons, returning the\nselected button's index along with the user's input text (the latter as a\nstring or table, depending on the type of *options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label\nalong with the user's input text.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a\n table, the first table value is the main message text and any subsequent\n values are used as the labels for multiple entry boxes. Providing a\n single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the\n table values are used to populate the multiple entry boxes defined by\n `informative_text`.\n * `no_cancel`: Do not display the "Cancel" button. The default value is\n `false`.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@return selected button or exit code, input text -start_styling buffer.start_styling(buffer, position, unused)\nBegins styling at position *position* with styling bit-mask *style_mask*.\n*style_mask* specifies which style bits can be set with\n`buffer.set_styling()`.\n@param buffer A buffer.\n@param position The position in *buffer* to start styling at.\n@param unused Unused number. `0` can be safely used.\n@usage buffer:start_styling(1, 0)\n@see set_styling -starts_line lexer.starts_line(patt)\nCreates and returns a pattern that matches pattern *patt* only at the\nbeginning of a line.\n@param patt The LPeg pattern to match on the beginning of a line.\n@usage local preproc = token(lexer.PREPROCESSOR,\n lexer.starts_line(lexer.to_eol('#')))\n@return pattern -status spawn_proc:status()\nReturns the status of process *spawn_proc*, which is either "running" or\n"terminated".\n@return "running" or "terminated" +space lexer.space (pattern)\nA pattern that matches any whitespace character ('\t', '\v', '\f', '\\n', '\r', space). +spawn os.spawn(cmd, cwd, env, stdout_cb, stderr_cb, exit_cb)\nSpawns an interactive child process *cmd* in a separate thread, returning a handle to that\nprocess.\nOn Windows, *cmd* is passed to `cmd.exe`: `%COMSPEC% /c [cmd]`.\nAt the moment, only the Windows terminal version spawns processes in the same thread.\n@param cmd A command line string that contains the program's name followed by arguments to\n pass to it. `PATH` is searched for program names.\n@param cwd Optional current working directory (cwd) for the child process. When omitted,\n the parent's cwd is used.\n@param env Optional map of environment variables for the child process. When omitted,\n Textadept's environment is used.\n@param stdout_cb Optional Lua function that accepts a string parameter for a block of standard\n output read from the child. Stdout is read asynchronously in 1KB or 0.5KB blocks (depending\n on the platform), or however much data is available at the time.\n At the moment, only the Win32 terminal version sends all output, whether it be stdout or\n stderr, to this callback after the process finishes.\n@param stderr_cb Optional Lua function that accepts a string parameter for a block of\n standard error read from the child. Stderr is read asynchronously in 1KB or 0.5kB blocks\n (depending on the platform), or however much data is available at the time.\n@param exit_cb Optional Lua function that is called when the child process finishes. The\n child's exit status is passed.\n@usage os.spawn('lua ' .. buffer.filename, print)\n@usage proc = os.spawn('lua -e "print(io.read())"', print)\n proc:write('foo\\n')\n@return proc or nil plus an error message on failure +split view.split(view, vertical)\nSplits the view into top and bottom views (unless *vertical* is `true`), focuses the new view,\nand returns both the old and new views.\nIf *vertical* is `false`, splits the view vertically into left and right views.\nEmits a `VIEW_NEW` event.\n@param view The view to split.\n@param vertical Optional flag indicating whether or not to split the view vertically. The\n default value is `false`, for horizontal.\n@return old view and new view.\n@see events.VIEW_NEW +standard_dropdown ui.dialogs.standard_dropdown(options)\nPrompts the user with a drop-down item selection dialog defined by dialog options table\n*options* and with localized "Ok" and "Cancel" buttons, returning the selected button's\nindex along with the selected item's index.\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\nselected item's text. If the dialog closed due to *options*.`exit_onchange`, returns `4`\nalong with either the selected item's index or its text. If the dialog timed out, returns\n`0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the drop-down dialog.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `items`: The list of string items to show in the drop-down.\n * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.\n * `exit_onchange`: Close the dialog after selecting a new item. The default value is `false`.\n * `select`: The index of the initially selected list item. The default value is `1`.\n * `string_output`: Return the selected button's label (instead of its index) and the selected\n item's text (instead of its index). If no item was selected, returns the dialog's exit\n status (instead of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@return selected button or exit code, selected item +standard_inputbox ui.dialogs.standard_inputbox(options)\nPrompts the user with an inputbox dialog defined by dialog options table *options* and\nwith localized "Ok" and "Cancel" buttons, returning the selected button's index along\nwith the user's input text (the latter as a string or table, depending on the type of\n*options*.`informative_text`).\nIf *options*.`string_output` is `true`, returns the selected button's label along with the\nuser's input text. If the dialog timed out, returns `0` or `"timeout"`. If the user canceled\nthe dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the inputbox.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text. If the value is a table, the first\n table value is the main message text and any subsequent values are used as the labels\n for multiple entry boxes. Providing a single label has no effect.\n * `text`: The dialog's initial input text. If the value is a table, the table values are\n used to populate the multiple entry boxes defined by `informative_text`.\n * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@return selected button or exit code, input text +start_styling buffer.start_styling(buffer, position, unused)\nBegins styling at position *position* with styling bit-mask *style_mask*.\n*style_mask* specifies which style bits can be set with `buffer.set_styling()`.\n@param buffer A buffer.\n@param position The position in *buffer* to start styling at.\n@param unused Unused number. `0` can be safely used.\n@usage buffer:start_styling(1, 0)\n@see set_styling +starts_line lexer.starts_line(patt)\nCreates and returns a pattern that matches pattern *patt* only at the beginning of a line.\n@param patt The LPeg pattern to match on the beginning of a line.\n@usage local preproc = token(lexer.PREPROCESSOR, lexer.starts_line(lexer.to_eol('#')))\n@return pattern +status spawn_proc:status()\nReturns the status of process *spawn_proc*, which is either "running" or "terminated".\n@return "running" or "terminated" statusbar_text ui.statusbar_text (string, Write-only)\nThe text displayed in the statusbar. stop textadept.run.stop()\nStops the currently running process, if any. string _G.string (module)\nExtends Lua's `string` library to provide character set conversions. -strip_trailing_spaces textadept.editing.strip_trailing_spaces (bool)\nStrip trailing whitespace before saving files. (Does not apply to binary\nfiles.)\nThe default value is `false`. -stuttered_page_down buffer.stuttered_page_down(buffer)\nMoves the caret to the bottom of the page or, if already there, down one\npage.\n@param buffer A buffer. -stuttered_page_down_extend buffer.stuttered_page_down_extend(buffer)\nLike `buffer.stuttered_page_down()`, but extends the selected text to the new\nposition.\n@param buffer A buffer. +strip_trailing_spaces textadept.editing.strip_trailing_spaces (bool)\nStrip trailing whitespace before saving files. (Does not apply to binary files.)\nThe default value is `false`. +stuttered_page_down buffer.stuttered_page_down(buffer)\nMoves the caret to the bottom of the page or, if already there, down one page.\n@param buffer A buffer. +stuttered_page_down_extend buffer.stuttered_page_down_extend(buffer)\nLike `buffer.stuttered_page_down()`, but extends the selected text to the new position.\n@param buffer A buffer. stuttered_page_up buffer.stuttered_page_up(buffer)\nMoves the caret to the top of the page or, if already there, up one page.\n@param buffer A buffer. -stuttered_page_up_extend buffer.stuttered_page_up_extend(buffer)\nLike `buffer.stuttered_page_up()`, but extends the selected text to the new\nposition.\n@param buffer A buffer. +stuttered_page_up_extend buffer.stuttered_page_up_extend(buffer)\nLike `buffer.stuttered_page_up()`, but extends the selected text to the new position.\n@param buffer A buffer. style_at buffer.style_at (table, Read-only)\nTable of style numbers per position. style_at lexer.style_at (table, Read-only)\nTable of style names at positions in the buffer starting from 1. -style_back view.style_back (table)\nTable of background colors, in "0xBBGGRR" format, of text for style numbers\nfrom `1` to `256`. -style_bold view.style_bold (table)\nTable of flags that indicate whether or not text is bold for style numbers\nfrom `1` to `256`.\nThe default values are `false`. +style_back view.style_back (table)\nTable of background colors, in "0xBBGGRR" format, of text for style numbers from `1` to `256`. +style_bold view.style_bold (table)\nTable of flags that indicate whether or not text is bold for style numbers from `1` to `256`.\nThe default values are `false`. style_case view.style_case (table)\nTable of letter case modes of text for style numbers from `1` to `256`.\n\n* `view.CASE_MIXED`\n Display text in normally.\n* `view.CASE_UPPER`\n Display text in upper case.\n* `view.CASE_LOWER`\n Display text in lower case.\n* `view.CASE_CAMEL`\n Display text in camel case.\n\nThe default values are `view.CASE_MIXED`. -style_changeable view.style_changeable (table)\nTable of flags that indicate whether or not text is changeable for style\nnumbers from `1` to `256`.\nThe default values are `true`.\nRead-only styles do not allow the caret into the range of text. +style_changeable view.style_changeable (table)\nTable of flags that indicate whether or not text is changeable for style numbers from `1`\nto `256`.\nThe default values are `true`.\nRead-only styles do not allow the caret into the range of text. style_clear_all view.style_clear_all(view)\nReverts all styles to having the same properties as `view.STYLE_DEFAULT`.\n@param view A view. -style_eol_filled view.style_eol_filled (table)\nTable of flags that indicate whether or not the background colors of styles\nwhose characters occur last on lines extend all the way to the view's right\nmargin for style numbers from `1` to `256`.\nThe default values are `false`. +style_eol_filled view.style_eol_filled (table)\nTable of flags that indicate whether or not the background colors of styles whose characters\noccur last on lines extend all the way to the view's right margin for style numbers from\n`1` to `256`.\nThe default values are `false`. style_font view.style_font (table)\nTable of string font names of text for style numbers from `1` to `256`. -style_fore view.style_fore (table)\nTable of foreground colors, in "0xBBGGRR" format, of text for style numbers\nfrom `1` to `256`. -style_italic view.style_italic (table)\nTable of flags that indicate whether or not text is italic for style\nnumbers from `1` to `256`.\nThe default values are `false`. -style_of_name buffer.style_of_name(buffer, style_name, string)\nReturns the style number associated with string *style_name*, or\n`view.STYLE_DEFAULT` if *style_name* is not in use.\n@param buffer A buffer.\n@param string The style name to get the number of.\n@return style number, between `1` and `256`.\n@see name_of_style +style_fore view.style_fore (table)\nTable of foreground colors, in "0xBBGGRR" format, of text for style numbers from `1` to `256`. +style_italic view.style_italic (table)\nTable of flags that indicate whether or not text is italic for style numbers from `1` to\n`256`.\nThe default values are `false`. +style_of_name buffer.style_of_name(buffer, style_name, string)\nReturns the style number associated with string *style_name*, or `view.STYLE_DEFAULT` if\n*style_name* is not in use.\n@param buffer A buffer.\n@param string The style name to get the number of.\n@return style number, between `1` and `256`.\n@see name_of_style style_reset_default view.style_reset_default(view)\nResets `view.STYLE_DEFAULT` to its initial state.\n@param view A view. style_size view.style_size (table)\nTable of font sizes of text for style numbers from `1` to `256`. -style_underline view.style_underline (table)\nTable of flags that indicate whether or not text is underlined for style\nnumbers from `1` to `256`.\nThe default values are `false`. -style_visible view.style_visible (table)\nTable of flags that indicate whether or not text is visible for style\nnumbers from `1` to `256`.\nThe default values are `true`. -styles lexer.styles (table)\nMap of style names to style definition tables.\n\nStyle names consist of the following default names as well as the token names\ndefined by lexers.\n\n* `default`: The default style all others are based on.\n* `line_number`: The line number margin style.\n* `control_char`: The style of control character blocks.\n* `indent_guide`: The style of indentation guides.\n* `call_tip`: The style of call tip text. Only the `font`, `size`, `fore`,\n and `back` style definition fields are supported.\n* `fold_display_text`: The style of text displayed next to folded lines.\n* `class`, `comment`, `constant`, `embedded`, `error`, `function`,\n `identifier`, `keyword`, `label`, `number`, `operator`, `preprocessor`,\n `regex`, `string`, `type`, `variable`, `whitespace`: Some token names used\n by lexers. Some lexers may define more token names, so this list is not\n exhaustive.\n* *`lang`*`_whitespace`: A special style for whitespace tokens in lexer name\n *lang*. It inherits from `whitespace`, and is used in place of it for all\n lexers.\n\nStyle definition tables may contain the following fields:\n\n* `font`: String font name.\n* `size`: Integer font size.\n* `bold`: Whether or not the font face is bold. The default value is `false`.\n* `weight`: Integer weight or boldness of a font, between 1 and 999.\n* `italics`: Whether or not the font face is italic. The default value is\n `false`.\n* `underlined`: Whether or not the font face is underlined. The default value\n is `false`.\n* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `eolfilled`: Whether or not the background color extends to the end of the\n line. The default value is `false`.\n* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal,\n mixed case. The default value is `'m'`.\n* `visible`: Whether or not the text is visible. The default value is `true`.\n* `changeable`: Whether the text is changeable instead of read-only. The\n default value is `true`. +style_underline view.style_underline (table)\nTable of flags that indicate whether or not text is underlined for style numbers from `1`\nto `256`.\nThe default values are `false`. +style_visible view.style_visible (table)\nTable of flags that indicate whether or not text is visible for style numbers from `1` to\n`256`.\nThe default values are `true`. +styles lexer.styles (table)\nMap of style names to style definition tables.\n\nStyle names consist of the following default names as well as the token names defined by lexers.\n\n* `default`: The default style all others are based on.\n* `line_number`: The line number margin style.\n* `control_char`: The style of control character blocks.\n* `indent_guide`: The style of indentation guides.\n* `call_tip`: The style of call tip text. Only the `font`, `size`, `fore`, and `back` style\n definition fields are supported.\n* `fold_display_text`: The style of text displayed next to folded lines.\n* `class`, `comment`, `constant`, `embedded`, `error`, `function`, `identifier`, `keyword`,\n `label`, `number`, `operator`, `preprocessor`, `regex`, `string`, `type`, `variable`,\n `whitespace`: Some token names used by lexers. Some lexers may define more token names,\n so this list is not exhaustive.\n* *`lang`*`_whitespace`: A special style for whitespace tokens in lexer name *lang*. It\n inherits from `whitespace`, and is used in place of it for all lexers.\n\nStyle definition tables may contain the following fields:\n\n* `font`: String font name.\n* `size`: Integer font size.\n* `bold`: Whether or not the font face is bold. The default value is `false`.\n* `weight`: Integer weight or boldness of a font, between 1 and 999.\n* `italics`: Whether or not the font face is italic. The default value is `false`.\n* `underlined`: Whether or not the font face is underlined. The default value is `false`.\n* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.\n* `eolfilled`: Whether or not the background color extends to the end of the line. The\n default value is `false`.\n* `case`: Font case: `'u'` for upper, `'l'` for lower, and `'m'` for normal, mixed case. The\n default value is `'m'`.\n* `visible`: Whether or not the text is visible. The default value is `true`.\n* `changeable`: Whether the text is changeable instead of read-only. The default value is\n `true`. swap_main_anchor_caret buffer.swap_main_anchor_caret(buffer)\nSwaps the main selection's beginning and end positions.\n@param buffer A buffer. -switch_buffer ui.switch_buffer(zorder)\nPrompts the user to select a buffer to switch to.\nBuffers are listed in the order they were opened unless `zorder` is `true`,\nin which case buffers are listed by their z-order (most recently viewed to\nleast recently viewed).\n@param zorder Flag that indicates whether or not to list buffers by their\n z-order. The default value is `false`. -tab buffer.tab(buffer)\nIndents the text on the selected lines or types a Tab character ("\t") at\nthe caret position.\n@param buffer A buffer. -tab_context_menu textadept.menu.tab_context_menu (table)\nThe default tabbar context menu.\nSubmenus, and menu items can be retrieved by name in addition to table index\nnumber. +switch_buffer ui.switch_buffer(zorder)\nPrompts the user to select a buffer to switch to.\nBuffers are listed in the order they were opened unless `zorder` is `true`, in which case\nbuffers are listed by their z-order (most recently viewed to least recently viewed).\n@param zorder Flag that indicates whether or not to list buffers by their z-order. The\n default value is `false`. +tab buffer.tab(buffer)\nIndents the text on the selected lines or types a Tab character ("\t") at the caret position.\n@param buffer A buffer. +tab_context_menu textadept.menu.tab_context_menu (table)\nThe default tabbar context menu.\nSubmenus, and menu items can be retrieved by name in addition to table index number. tab_context_menu ui.tab_context_menu (userdata)\nThe context menu for the buffer's tab, a `ui.menu()`.\nThis is a low-level field. You probably want to use the higher-level\n`textadept.menu.tab_context_menu`. tab_draw_mode view.tab_draw_mode (number)\nThe draw mode of visible tabs.\n\n* `view.TD_LONGARROW`\n An arrow that stretches until the tabstop.\n* `view.TD_STRIKEOUT`\n A horizontal line that stretches until the tabstop.\n\nThe default value is `view.TD_LONGARROW`. tab_indents buffer.tab_indents (bool)\nIndent text when tabbing within indentation.\nThe default value is `false`. tab_label buffer.tab_label (string)\nThe buffer's tab label in the tab bar. tab_width buffer.tab_width (number)\nThe number of space characters represented by a tab character.\nThe default value is `8`. -tabs ui.tabs (bool)\nWhether or not to display the tab bar when multiple buffers are open.\nThe default value is `true`.\nA third option, `ui.SHOW_ALL_TABS` may be used to always show the tab bar,\neven if only one buffer is open. +tabs ui.tabs (bool)\nWhether or not to display the tab bar when multiple buffers are open.\nThe default value is `true`.\nA third option, `ui.SHOW_ALL_TABS` may be used to always show the tab bar, even if only\none buffer is open. tag buffer.tag (table, Read-only)\nList of capture text for capture numbers from a regular expression search. -tags _M.ansi_c.tags (table)\nList of ctags files to use for autocompletion in addition to the current\nproject's top-level *tags* file or the current directory's *tags* file. -tags _M.lua.tags (table)\nList of "fake" ctags files (or functions that return such files) to use for\nautocompletion.\nThe kind 'm' is recognized as a module, 'f' as a function, 't' as a table and\n'F' as a module or table field.\nThe *modules/lua/tadoc.lua* script can generate *tags* and\n*api* files for Lua modules via LuaDoc. +tags _M.ansi_c.tags (table)\nList of ctags files to use for autocompletion in addition to the current project's top-level\n*tags* file or the current directory's *tags* file. +tags _M.lua.tags (table)\nList of "fake" ctags files (or functions that return such files) to use for autocompletion.\nThe kind 'm' is recognized as a module, 'f' as a function, 't' as a table and 'F' as a module\nor table field.\nThe *modules/lua/tadoc.lua* script can generate *tags* and *api*\nfiles for Lua modules via LuaDoc. target_end buffer.target_end (number)\nThe position of the end of the target range.\nThis is also set by a successful `buffer.search_in_target()`. -target_end_virtual_space buffer.target_end_virtual_space (number)\nThe position of the end of virtual space in the target range.\nThis is set to `1` when `buffer.target_start` or\n`buffer.target_end` is set, or when `buffer.set_target_range()` is\ncalled. -target_from_selection buffer.target_from_selection(buffer)\nDefines the target range's beginning and end positions as the beginning and\nend positions of the main selection, respectively.\n@param buffer A buffer. +target_end_virtual_space buffer.target_end_virtual_space (number)\nThe position of the end of virtual space in the target range.\nThis is set to `1` when `buffer.target_start` or `buffer.target_end` is set,\nor when `buffer.set_target_range()` is called. +target_from_selection buffer.target_from_selection(buffer)\nDefines the target range's beginning and end positions as the beginning and end positions\nof the main selection, respectively.\n@param buffer A buffer. target_start buffer.target_start (number)\nThe position of the beginning of the target range.\nThis is also set by a successful `buffer.search_in_target()`. -target_start_virtual_space buffer.target_start_virtual_space (number)\nThe position of the beginning of virtual space in the target range.\nThis is set to `1` when `buffer.target_start` or\n`buffer.target_end` is set, or when `buffer.set_target_range()` is\ncalled. +target_start_virtual_space buffer.target_start_virtual_space (number)\nThe position of the beginning of virtual space in the target range.\nThis is set to `1` when `buffer.target_start` or `buffer.target_end` is set,\nor when `buffer.set_target_range()` is called. target_text buffer.target_text (string, Read-only)\nThe text in the target range. -target_whole_document buffer.target_whole_document(buffer)\nDefines the target range's beginning and end positions as the beginning and\nend positions of the document, respectively.\n@param buffer A buffer. -test textadept.run.test(root_directory)\nRuns tests for the project whose root path is *root_directory* or the current\nproject using the shell command from the `test_commands` table.\nThe current project is determined by either the buffer's filename or the\ncurrent working directory.\nEmits `TEST_OUTPUT` events.\n@param root_directory The path to the project to run tests for. The default\n value is the current project.\n@see test_commands\n@see _G.events -test_commands textadept.run.test_commands (table)\nMap of project root paths to their associated "test" shell command line\nstrings or functions that return such strings.\nFunctions may also return a working directory and process environment table\nto operate in. By default, the working directory is the project's root\ndirectory and the environment is Textadept's environment. +target_whole_document buffer.target_whole_document(buffer)\nDefines the target range's beginning and end positions as the beginning and end positions\nof the document, respectively.\n@param buffer A buffer. +test textadept.run.test(root_directory)\nRuns tests for the project whose root path is *root_directory* or the current project using\nthe shell command from the `test_commands` table.\nThe current project is determined by either the buffer's filename or the current working\ndirectory.\nEmits `TEST_OUTPUT` events.\n@param root_directory The path to the project to run tests for. The default value is the\n current project.\n@see test_commands\n@see _G.events +test_commands textadept.run.test_commands (table)\nMap of project root paths to their associated "test" shell command line strings or functions\nthat return such strings.\nFunctions may also return a working directory and process environment table to operate\nin. By default, the working directory is the project's root directory and the environment\nis Textadept's environment. text_height view.text_height(view, line)\nReturns the pixel height of line number *line*.\n@param view A view.\n@param line The line number in *view* to get the pixel height of.\n@return number text_length buffer.text_length (number, Read-only)\nThe number of bytes in the buffer. text_range buffer.text_range(buffer, start_pos, end_pos)\nReturns the range of text between positions *start_pos* and *end_pos*.\n@param buffer A buffer.\n@param start_pos The start position of the range of text to get in *buffer*.\n@param end_pos The end position of the range of text to get in *buffer*. -text_width view.text_width(view, style_num, text)\nReturns the pixel width string *text* would have when styled with style\nnumber *style_num*, in the range of `1` to `256`.\n@param view A view.\n@param style_num The style number between `1` and `256` to use.\n@param text The text to measure the width of.\n@return number +text_width view.text_width(view, style_num, text)\nReturns the pixel width string *text* would have when styled with style number *style_num*,\nin the range of `1` to `256`.\n@param view A view.\n@param style_num The style number between `1` and `256` to use.\n@param text The text to measure the width of.\n@return number textadept _G.textadept (module)\nThe textadept module.\nIt provides utilities for editing text in Textadept. -textbox ui.dialogs.textbox(options)\nPrompts the user with a multiple-line textbox dialog defined by dialog\noptions table *options*, returning the selected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label.\nIf *options*.`editable` is `true`, also returns the textbox's text. If the\ndialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the dialog.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text.\n * `text`: The dialog's initial textbox text.\n * `text_from_file`: The filename whose contents are loaded into the\n textbox. This option has no effect when `text` is given.\n * `button1`: The right-most button's label. The default value is\n `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2`\n to be set.\n * `editable`: Allows the user to edit the textbox's text. The default value\n is `false`.\n * `focus_textbox`: Focus the textbox instead of the buttons. The default\n value is `false`.\n * `scroll_to`: Where to scroll the textbox's text.\n The available values are `"top"` and `"bottom"`. The default value is\n `"top"`.\n * `selected`: Select all of the textbox's text. The default value is\n `false`.\n * `monospaced_font`: Use a monospaced font in the textbox instead of a\n proportional one. The default value is `false`.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.textbox{title = 'License Agreement',\n informative_text = 'You agree to:', text_from_file = _HOME..'/LICENSE'}\n@return selected button or exit code, textbox text -timeout _G.timeout(interval, f, ...)\nCalls function *f* with the given arguments after *interval* seconds.\nIf *f* returns `true`, calls *f* repeatedly every *interval* seconds as long\nas *f* returns `true`. A `nil` or `false` return value stops repetition.\n@param interval The interval in seconds to call *f* after.\n@param f The function to call.\n@param ... Additional arguments to pass to *f*. +textbox ui.dialogs.textbox(options)\nPrompts the user with a multiple-line textbox dialog defined by dialog options table *options*,\nreturning the selected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label. If\n*options*.`editable` is `true`, also returns the textbox's text. If the dialog timed out,\nreturns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the dialog.\n\n * `title`: The dialog's title text.\n * `informative_text`: The dialog's main message text.\n * `text`: The dialog's initial textbox text.\n * `text_from_file`: The filename whose contents are loaded into the textbox. This option\n has no effect when `text` is given.\n * `button1`: The right-most button's label. The default value is `_L['OK']`.\n * `button2`: The middle button's label.\n * `button3`: The left-most button's label. This option requires `button2` to be set.\n * `editable`: Allows the user to edit the textbox's text. The default value is `false`.\n * `focus_textbox`: Focus the textbox instead of the buttons. The default value is `false`.\n * `scroll_to`: Where to scroll the textbox's text. The available values are `"top"` and\n `"bottom"`. The default value is `"top"`.\n * `selected`: Select all of the textbox's text. The default value is `false`.\n * `monospaced_font`: Use a monospaced font in the textbox instead of a proportional one. The\n default value is `false`.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@usage ui.dialogs.textbox{title = 'License Agreement', informative_text = 'You agree to:',\n text_from_file = _HOME..'/LICENSE'}\n@return selected button or exit code, textbox text +timeout _G.timeout(interval, f, ...)\nCalls function *f* with the given arguments after *interval* seconds.\nIf *f* returns `true`, calls *f* repeatedly every *interval* seconds as long as *f* returns\n`true`. A `nil` or `false` return value stops repetition.\n@param interval The interval in seconds to call *f* after.\n@param f The function to call.\n@param ... Additional arguments to pass to *f*. title ui.title (string, Write-only)\nThe title text of Textadept's window. -to_eol lexer.to_eol(prefix, escape)\nCreates and returns a pattern that matches from string or pattern *prefix*\nuntil the end of the line.\n*escape* indicates whether the end of the line can be escaped with a '\'\ncharacter.\n@param prefix String or pattern prefix to start matching at.\n@param escape Optional flag indicating whether or not newlines can be escaped\n by a '\' character. The default value is `false`.\n@usage local line_comment = lexer.to_eol('//')\n@usage local line_comment = lexer.to_eol(S('#;'))\n@return pattern +to_eol lexer.to_eol(prefix, escape)\nCreates and returns a pattern that matches from string or pattern *prefix* until the end of\nthe line.\n*escape* indicates whether the end of the line can be escaped with a '\' character.\n@param prefix String or pattern prefix to start matching at.\n@param escape Optional flag indicating whether or not newlines can be escaped by a '\'\n character. The default value is `false`.\n@usage local line_comment = lexer.to_eol('//')\n@usage local line_comment = lexer.to_eol(S('#;'))\n@return pattern toggle textadept.bookmarks.toggle()\nToggles a bookmark on the current line. -toggle_caret_sticky buffer.toggle_caret_sticky(buffer)\nCycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON`\nand `buffer.CARETSTICKY_OFF`.\n@param buffer A buffer.\n@see caret_sticky +toggle_caret_sticky buffer.toggle_caret_sticky(buffer)\nCycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON` and\n`buffer.CARETSTICKY_OFF`.\n@param buffer A buffer.\n@see caret_sticky toggle_comment textadept.editing.toggle_comment()\nComments or uncomments the selected lines based on the current language.\nAs long as any part of a line is selected, the entire line is eligible for\ncommenting/uncommenting.\n@see comment_string -toggle_fold view.toggle_fold(view, line)\nToggles the fold point on line number *line* between expanded (where all of\nits child lines are displayed) and contracted (where all of its child lines\nare hidden).\n@param view A view.\n@param line The line number in *view* to toggle the fold on.\n@see set_default_fold_display_text -toggle_fold_show_text view.toggle_fold_show_text(view, line, text)\nToggles a fold point on line number *line* between expanded (where all of\nits child lines are displayed) and contracted (where all of its child lines\nare hidden), and shows string *text* next to that line.\n*text* is drawn with style number `view.STYLE_FOLDDISPLAYTEXT`.\n@param view A view.\n@param line The line number in *view* to toggle the fold on and display\n *text* after.\n@param text The text to display after the line. -token lexer.token(name, patt)\nCreates and returns a token pattern with token name *name* and pattern\n*patt*.\nIf *name* is not a predefined token name, its style must be defined via\n`lexer.add_style()`.\n@param name The name of token. If this name is not a predefined token name,\n then a style needs to be assiciated with it via `lexer.add_style()`.\n@param patt The LPeg pattern associated with the token.\n@usage local ws = token(lexer.WHITESPACE, lexer.space^1)\n@usage local annotation = token('annotation', '@' * lexer.word)\n@return pattern -transpose_chars textadept.editing.transpose_chars()\nTransposes characters intelligently.\nIf the caret is at the end of a line, transposes the two characters before\nthe caret. Otherwise, the characters to the left and right are. -typeover_chars textadept.editing.typeover_chars (table)\nTable of characters to move over when typed.\nThe ASCII values of characters are keys and are assigned non-`nil` values.\nThe default characters are ')', ']', '}', ''', and '"'. +toggle_fold view.toggle_fold(view, line)\nToggles the fold point on line number *line* between expanded (where all of its child lines\nare displayed) and contracted (where all of its child lines are hidden).\n@param view A view.\n@param line The line number in *view* to toggle the fold on.\n@see set_default_fold_display_text +toggle_fold_show_text view.toggle_fold_show_text(view, line, text)\nToggles a fold point on line number *line* between expanded (where all of its child lines are\ndisplayed) and contracted (where all of its child lines are hidden), and shows string *text*\nnext to that line.\n*text* is drawn with style number `view.STYLE_FOLDDISPLAYTEXT`.\n@param view A view.\n@param line The line number in *view* to toggle the fold on and display *text* after.\n@param text The text to display after the line. +token lexer.token(name, patt)\nCreates and returns a token pattern with token name *name* and pattern *patt*.\nIf *name* is not a predefined token name, its style must be defined via `lexer.add_style()`.\n@param name The name of token. If this name is not a predefined token name, then a style\n needs to be assiciated with it via `lexer.add_style()`.\n@param patt The LPeg pattern associated with the token.\n@usage local ws = token(lexer.WHITESPACE, lexer.space^1)\n@usage local annotation = token('annotation', '@' * lexer.word)\n@return pattern +transpose_chars textadept.editing.transpose_chars()\nTransposes characters intelligently.\nIf the caret is at the end of a line, transposes the two characters before the caret. Otherwise,\nthe characters to the left and right are. +typeover_chars textadept.editing.typeover_chars (table)\nTable of characters to move over when typed.\nThe ASCII values of characters are keys and are assigned non-`nil` values. The default\ncharacters are ')', ']', '}', ''', and '"'. ui _G.ui (module)\nUtilities for interacting with Textadept's user interface. undo buffer.undo(buffer)\nUndoes the most recent action.\n@param buffer A buffer. unsplit view.unsplit(view)\nUnsplits the view if possible, returning `true` on success.\n@param view The view to unsplit.\n@return boolean if the view was unsplit or not. update ui.update()\nProcesses pending GTK events, including reading from spawned processes.\nThis function is primarily used in unit tests. upper lexer.upper (pattern)\nA pattern that matches any upper case character ('A'-'Z'). upper_case buffer.upper_case(buffer)\nConverts the selected text to upper case letters.\n@param buffer A buffer. -use_tabs buffer.use_tabs (bool)\nUse tabs instead of spaces in indentation. Changing the current setting\ndoes not convert any of the buffer's existing indentation. Use\n`textadept.editing.convert_indentation()` to do so.\nThe default value is `true`. -user_list_show buffer.user_list_show(buffer, id, items)\nDisplays a user list identified by list identifier number *id* and\nconstructed from string *items* (whose items are delimited by\n`buffer.auto_c_separator` characters).\nThe sorted order of *items* (`buffer.auto_c_order`) must have already been\ndefined. When the user selects an item, *id* is sent in a\n`USER_LIST_SELECTION` event along with the selection.\n@param buffer A buffer.\n@param id The list identifier number greater than zero to use.\n@param items The sorted string of words to show, separated by\n `buffer.auto_c_separator` characters (initially spaces).\n@see _SCINTILLA.next_user_list_type\n@see events.USER_LIST_SELECTION +use_tabs buffer.use_tabs (bool)\nUse tabs instead of spaces in indentation.\nChanging the current setting does not convert any of the buffer's existing indentation. Use\n`textadept.editing.convert_indentation()` to do so.\nThe default value is `true`. +user_list_show buffer.user_list_show(buffer, id, items)\nDisplays a user list identified by list identifier number *id* and constructed from string\n*items* (whose items are delimited by `buffer.auto_c_separator` characters).\nThe sorted order of *items* (`buffer.auto_c_order`) must have already been defined. When the\nuser selects an item, *id* is sent in a `USER_LIST_SELECTION` event along with the selection.\n@param buffer A buffer.\n@param id The list identifier number greater than zero to use.\n@param items The sorted string of words to show, separated by `buffer.auto_c_separator`\n characters (initially spaces).\n@see _SCINTILLA.next_user_list_type\n@see events.USER_LIST_SELECTION v_scroll_bar view.v_scroll_bar (bool)\nDisplay the vertical scroll bar.\nThe default value is `true`. -vc_home buffer.vc_home(buffer)\nMoves the caret to the first visible character on the current line or, if\nalready there, to the beginning of the current line.\n@param buffer A buffer. -vc_home_display buffer.vc_home_display(buffer)\nMoves the caret to the first visible character on the current wrapped line\nor, if already there, to the beginning of the current wrapped line.\n@param buffer A buffer. -vc_home_display_extend buffer.vc_home_display_extend(buffer)\nLike `buffer.vc_home_display()`, but extends the selected text to the new\nposition.\n@param buffer A buffer. +vc_home buffer.vc_home(buffer)\nMoves the caret to the first visible character on the current line or, if already there,\nto the beginning of the current line.\n@param buffer A buffer. +vc_home_display buffer.vc_home_display(buffer)\nMoves the caret to the first visible character on the current wrapped line or, if already\nthere, to the beginning of the current wrapped line.\n@param buffer A buffer. +vc_home_display_extend buffer.vc_home_display_extend(buffer)\nLike `buffer.vc_home_display()`, but extends the selected text to the new position.\n@param buffer A buffer. vc_home_extend buffer.vc_home_extend(buffer)\nLike `buffer.vc_home()`, but extends the selected text to the new position.\n@param buffer A buffer. -vc_home_rect_extend buffer.vc_home_rect_extend(buffer)\nLike `buffer.vc_home()`, but extends the rectangular selection to the new\nposition.\n@param buffer A buffer. -vc_home_wrap buffer.vc_home_wrap(buffer)\nMoves the caret to the first visible character on the current wrapped line\nor, if already there, to the beginning of the actual line.\n@param buffer A buffer. -vc_home_wrap_extend buffer.vc_home_wrap_extend(buffer)\nLike `buffer.vc_home_wrap()`, but extends the selected text to the new\nposition.\n@param buffer A buffer. +vc_home_rect_extend buffer.vc_home_rect_extend(buffer)\nLike `buffer.vc_home()`, but extends the rectangular selection to the new position.\n@param buffer A buffer. +vc_home_wrap buffer.vc_home_wrap(buffer)\nMoves the caret to the first visible character on the current wrapped line or, if already\nthere, to the beginning of the actual line.\n@param buffer A buffer. +vc_home_wrap_extend buffer.vc_home_wrap_extend(buffer)\nLike `buffer.vc_home_wrap()`, but extends the selected text to the new position.\n@param buffer A buffer. vertical_center_caret view.vertical_center_caret(view)\nCenters current line in the view.\n@param view A view. -view _G.view (module)\nA Textadept view object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual view instances, it is often useful to work\nwith just the global one.\nMany of these functions and fields are derived from view-specific\nfunctionality of the Scintilla editing component, and additional information\ncan be found on the\nScintilla website.\nNote that with regard to Scintilla-specific functionality, this API is a\n_suggestion_, not a hard requirement. All of that functionality also exists\nin `buffer`, even if undocumented.\nAny view fields set on startup (e.g. in *~/.textadept/init.lua*) will be the\ndefault, initial values for all views. +view _G.view (module)\nA Textadept view object.\nConstants are documented in the fields they apply to.\nWhile you can work with individual view instances, it is often useful to work with just the\nglobal one.\nMany of these functions and fields are derived from view-specific functionality of the\nScintilla editing component, and additional information can be found on the [Scintilla\nwebsite](https://scintilla.org/ScintillaDoc.html). Note that with regard to Scintilla-specific\nfunctionality, this API is a _suggestion_, not a hard requirement. All of that functionality\nalso exists in `buffer`, even if undocumented.\nAny view fields set on startup (e.g. in *~/.textadept/init.lua*) will be the default,\ninitial values for all views. view _G.view (table)\nThe current view. view_eol view.view_eol (bool)\nDisplay end of line characters.\nThe default value is `false`. view_ws view.view_ws (number)\nThe whitespace visibility mode.\n\n* `view.WS_INVISIBLE`\n Whitespace is invisible.\n* `view.WS_VISIBLEALWAYS`\n Display all space characters as dots and tab characters as arrows.\n* `view.WS_VISIBLEAFTERINDENT`\n Display only non-indentation spaces and tabs as dots and arrows.\n* `view.WS_VISIBLEONLYININDENT`\n Display only indentation spaces and tabs as dots and arrows.\n\nThe default value is `view.WS_INVISIBLE`. -virtual_space_options buffer.virtual_space_options (number)\nThe virtual space mode.\n\n* `buffer.VS_NONE`\n Disable virtual space.\n* `buffer.VS_RECTANGULARSELECTION`\n Enable virtual space only for rectangular selections.\n* `buffer.VS_USERACCESSIBLE`\n Enable virtual space.\n* `buffer.VS_NOWRAPLINESTART`\n Prevent the caret from wrapping to the previous line via\n `buffer:char_left()` and `buffer:char_left_extend()`. This option is not\n restricted to virtual space and should be added to any of the above\n options.\n\nWhen virtual space is enabled, the caret may move into the space past end\nof line characters.\nThe default value is `buffer.VS_NONE`. -visible_from_doc_line view.visible_from_doc_line(view, line)\nReturns the displayed line number of actual line number *line*, taking\nwrapped, annotated, and hidden lines into account, or `-1` if *line* is\noutside the range of lines in the buffer.\nLines can occupy more than one display line if they wrap.\n@param view A view.\n@param line The line number in *view* to use.\n@return number -wait spawn_proc:wait()\nBlocks until process *spawn_proc* finishes (if it has not already done so)\nand returns its status code.\n@return integer status code -walk lfs.walk(dir, filter, n, include_dirs)\nReturns an iterator that iterates over all files and sub-directories (up to\n*n* levels deep) in directory *dir* and yields each file found.\nString or list *filter* determines which files to yield, with the default\nfilter being `lfs.default_filter`. A filter consists of Lua patterns that\nmatch file and directory paths to include or exclude. Exclusive patterns\nbegin with a '!'. If no inclusive patterns are given, any path is initially\nconsidered. As a convenience, file extensions can be specified literally\ninstead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches\nthe Windows directory separator ('[/\\]' is not needed).\n@param dir The directory path to iterate over.\n@param filter Optional filter for files and directories to include and\n exclude. The default value is `lfs.default_filter`.\n@param n Optional maximum number of directory levels to descend into.\n The default value is `nil`, which indicates no limit.\n@param include_dirs Optional flag indicating whether or not to yield\n directory names too. Directory names are passed with a trailing '/' or '\',\n depending on the current platform.\n The default value is `false`.\n@see filter -whitespace_chars buffer.whitespace_chars (string)\nThe string set of characters recognized as whitespace characters.\nSet this only after setting `buffer.word_chars`.\nThe default value is a string that contains all non-newline characters less\nthan ASCII value 33. -whitespace_size view.whitespace_size (number)\nThe pixel size of the dots that represent space characters when whitespace\nis visible.\nThe default value is `1`. -whole_word ui.find.whole_word (bool)\nMatch search text only when it is surrounded by non-word characters in\nsearches.\nThe default value is `false`. +virtual_space_options buffer.virtual_space_options (number)\nThe virtual space mode.\n\n* `buffer.VS_NONE`\n Disable virtual space.\n* `buffer.VS_RECTANGULARSELECTION`\n Enable virtual space only for rectangular selections.\n* `buffer.VS_USERACCESSIBLE`\n Enable virtual space.\n* `buffer.VS_NOWRAPLINESTART`\n Prevent the caret from wrapping to the previous line via `buffer:char_left()` and\n `buffer:char_left_extend()`. This option is not restricted to virtual space and should\n be added to any of the above options.\n\nWhen virtual space is enabled, the caret may move into the space past end of line characters.\nThe default value is `buffer.VS_NONE`. +visible_from_doc_line view.visible_from_doc_line(view, line)\nReturns the displayed line number of actual line number *line*, taking wrapped, annotated,\nand hidden lines into account, or `-1` if *line* is outside the range of lines in the buffer.\nLines can occupy more than one display line if they wrap.\n@param view A view.\n@param line The line number in *view* to use.\n@return number +wait spawn_proc:wait()\nBlocks until process *spawn_proc* finishes (if it has not already done so) and returns its\nstatus code.\n@return integer status code +walk lfs.walk(dir, filter, n, include_dirs)\nReturns an iterator that iterates over all files and sub-directories (up to *n* levels deep)\nin directory *dir* and yields each file found.\nString or list *filter* determines which files to yield, with the default filter being\n`lfs.default_filter`. A filter consists of Lua patterns that match file and directory paths\nto include or exclude. Exclusive patterns begin with a '!'. If no inclusive patterns are\ngiven, any path is initially considered. As a convenience, file extensions can be specified\nliterally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the\nWindows directory separator ('[/\\]' is not needed).\n@param dir The directory path to iterate over.\n@param filter Optional filter for files and directories to include and exclude. The default\n value is `lfs.default_filter`.\n@param n Optional maximum number of directory levels to descend into. The default value is\n `nil`, which indicates no limit.\n@param include_dirs Optional flag indicating whether or not to yield directory names too.\n Directory names are passed with a trailing '/' or '\', depending on the current platform.\n The default value is `false`.\n@see filter +whitespace_chars buffer.whitespace_chars (string)\nThe string set of characters recognized as whitespace characters.\nSet this only after setting `buffer.word_chars`.\nThe default value is a string that contains all non-newline characters less than ASCII\nvalue 33. +whitespace_size view.whitespace_size (number)\nThe pixel size of the dots that represent space characters when whitespace is visible.\nThe default value is `1`. +whole_word ui.find.whole_word (bool)\nMatch search text only when it is surrounded by non-word characters in searches.\nThe default value is `false`. whole_word_label_text ui.find.whole_word_label_text (string, Write-only)\nThe text of the "Whole word" label.\nThis is primarily used for localization. -word lexer.word (pattern)\nA pattern that matches a typical word. Words begin with a letter or\nunderscore and consist of alphanumeric and underscore characters. -word_chars buffer.word_chars (string)\nThe string set of characters recognized as word characters.\nThe default value is a string that contains alphanumeric characters, an\nunderscore, and all characters greater than ASCII value 127. -word_end_position buffer.word_end_position(buffer, pos, only_word_chars)\nReturns the position of the end of the word at position *pos*.\n`buffer.word_chars` contains the set of characters that constitute words. If\n*pos* has a non-word character to its right and *only_word_chars* is `false`,\nreturns the first word character's position.\n@param buffer A buffer.\n@param pos The position in *buffer* of the word.\n@param only_word_chars If `true`, stops searching at the first non-word\n character in the search direction. Otherwise, the first character in the\n search direction sets the type of the search as word or non-word and the\n search stops at the first non-matching character. Searches are also\n terminated by the start or end of the buffer. +word lexer.word (pattern)\nA pattern that matches a typical word. Words begin with a letter or underscore and consist\nof alphanumeric and underscore characters. +word_chars buffer.word_chars (string)\nThe string set of characters recognized as word characters.\nThe default value is a string that contains alphanumeric characters, an underscore, and\nall characters greater than ASCII value 127. +word_end_position buffer.word_end_position(buffer, pos, only_word_chars)\nReturns the position of the end of the word at position *pos*.\n`buffer.word_chars` contains the set of characters that constitute words. If *pos* has a\nnon-word character to its right and *only_word_chars* is `false`, returns the first word\ncharacter's position.\n@param buffer A buffer.\n@param pos The position in *buffer* of the word.\n@param only_word_chars If `true`, stops searching at the first non-word character in\n the search direction. Otherwise, the first character in the search direction sets the\n type of the search as word or non-word and the search stops at the first non-matching\n character. Searches are also terminated by the start or end of the buffer. word_left buffer.word_left(buffer)\nMoves the caret left one word.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_left_end buffer.word_left_end(buffer)\nMoves the caret left one word, positioning it at the end of the previous\nword.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_left_end_extend buffer.word_left_end_extend(buffer)\nLike `buffer.word_left_end()`, but extends the selected text to the new\nposition.\n@param buffer A buffer. -word_left_extend buffer.word_left_extend(buffer)\nMoves the caret left one word, extending the selected text to the new\nposition.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_match lexer.word_match(words, case_insensitive, word_chars)\nCreates and returns a pattern that matches any single word in string *words*.\n*case_insensitive* indicates whether or not to ignore case when matching\nwords.\nThis is a convenience function for simplifying a set of ordered choice word\npatterns.\nIf *words* is a multi-line string, it may contain Lua line comments (`--`)\nthat will ultimately be ignored.\n@param words A string list of words separated by spaces.\n@param case_insensitive Optional boolean flag indicating whether or not the\n word match is case-insensitive. The default value is `false`.\n@param word_chars Unused legacy parameter.\n@usage local keyword = token(lexer.KEYWORD, word_match[[foo bar baz]])\n@usage local keyword = token(lexer.KEYWORD, word_match([[foo-bar foo-baz\n bar-foo bar-baz baz-foo baz-bar]], true))\n@return pattern -word_part_left buffer.word_part_left(buffer)\nMoves the caret to the previous part of the current word.\nWord parts are delimited by underscore characters or changes in\ncapitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_part_left_extend buffer.word_part_left_extend(buffer)\nMoves the caret to the previous part of the current word, extending the\nselected text to the new position.\nWord parts are delimited by underscore characters or changes in\ncapitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_part_right buffer.word_part_right(buffer)\nMoves the caret to the next part of the current word.\nWord parts are delimited by underscore characters or changes in\ncapitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_part_right_extend buffer.word_part_right_extend(buffer)\nMoves the caret to the next part of the current word, extending the selected\ntext to the new position.\nWord parts are delimited by underscore characters or changes in\ncapitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_left_end buffer.word_left_end(buffer)\nMoves the caret left one word, positioning it at the end of the previous word.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_left_end_extend buffer.word_left_end_extend(buffer)\nLike `buffer.word_left_end()`, but extends the selected text to the new position.\n@param buffer A buffer. +word_left_extend buffer.word_left_extend(buffer)\nMoves the caret left one word, extending the selected text to the new position.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_match lexer.word_match(word_list, case_insensitive, word_chars)\nCreates and returns a pattern that matches any single word in list or string *words*.\n*case_insensitive* indicates whether or not to ignore case when matching words.\nThis is a convenience function for simplifying a set of ordered choice word patterns.\n@param word_list A list of words or a string list of words separated by spaces.\n@param case_insensitive Optional boolean flag indicating whether or not the word match is\n case-insensitive. The default value is `false`.\n@param word_chars Unused legacy parameter.\n@usage local keyword = token(lexer.KEYWORD, word_match{'foo', 'bar', 'baz'})\n@usage local keyword = token(lexer.KEYWORD, word_match({'foo-bar', 'foo-baz', 'bar-foo',\n 'bar-baz', 'baz-foo', 'baz-bar'}, true))\n@usage local keyword = token(lexer.KEYWORD, word_match('foo bar baz'))\n@return pattern +word_part_left buffer.word_part_left(buffer)\nMoves the caret to the previous part of the current word.\nWord parts are delimited by underscore characters or changes in capitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_part_left_extend buffer.word_part_left_extend(buffer)\nMoves the caret to the previous part of the current word, extending the selected text to\nthe new position.\nWord parts are delimited by underscore characters or changes in capitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_part_right buffer.word_part_right(buffer)\nMoves the caret to the next part of the current word.\nWord parts are delimited by underscore characters or changes in capitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_part_right_extend buffer.word_part_right_extend(buffer)\nMoves the caret to the next part of the current word, extending the selected text to the\nnew position.\nWord parts are delimited by underscore characters or changes in capitalization.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. word_right buffer.word_right(buffer)\nMoves the caret right one word.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_right_end buffer.word_right_end(buffer)\nMoves the caret right one word, positioning it at the end of the current\nword.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_right_end_extend buffer.word_right_end_extend(buffer)\nLike `buffer.word_right_end()`, but extends the selected text to the new\nposition.\n@param buffer A buffer. -word_right_extend buffer.word_right_extend(buffer)\nMoves the caret right one word, extending the selected text to the new\nposition.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. -word_start_position buffer.word_start_position(buffer, pos, only_word_chars)\nReturns the position of the beginning of the word at position *pos*.\n`buffer.word_chars` contains the set of characters that constitute words. If\n*pos* has a non-word character to its left and *only_word_chars* is `false`,\nreturns the last word character's position.\n@param buffer A buffer.\n@param pos The position in *buffer* of the word.\n@param only_word_chars If `true`, stops searching at the first non-word\n character in the search direction. Otherwise, the first character in the\n search direction sets the type of the search as word or non-word and the\n search stops at the first non-matching character. Searches are also\n terminated by the start or end of the buffer. -wrap_count view.wrap_count(view, line)\nReturns the number of wrapped lines needed to fully display line number\n*line*.\n@param view A view.\n@param line The line number in *view* to use.\n@return number +word_right_end buffer.word_right_end(buffer)\nMoves the caret right one word, positioning it at the end of the current word.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_right_end_extend buffer.word_right_end_extend(buffer)\nLike `buffer.word_right_end()`, but extends the selected text to the new position.\n@param buffer A buffer. +word_right_extend buffer.word_right_extend(buffer)\nMoves the caret right one word, extending the selected text to the new position.\n`buffer.word_chars` contains the set of characters that constitute words.\n@param buffer A buffer. +word_start_position buffer.word_start_position(buffer, pos, only_word_chars)\nReturns the position of the beginning of the word at position *pos*.\n`buffer.word_chars` contains the set of characters that constitute words. If *pos* has\na non-word character to its left and *only_word_chars* is `false`, returns the last word\ncharacter's position.\n@param buffer A buffer.\n@param pos The position in *buffer* of the word.\n@param only_word_chars If `true`, stops searching at the first non-word character in\n the search direction. Otherwise, the first character in the search direction sets the\n type of the search as word or non-word and the search stops at the first non-matching\n character. Searches are also terminated by the start or end of the buffer. +wrap_count view.wrap_count(view, line)\nReturns the number of wrapped lines needed to fully display line number *line*.\n@param view A view.\n@param line The line number in *view* to use.\n@return number wrap_indent_mode view.wrap_indent_mode (number)\nThe wrapped line indent mode.\n\n* `view.WRAPINDENT_FIXED`\n Indent wrapped lines by `view.wrap_start_indent`.\n* `view.WRAPINDENT_SAME`\n Indent wrapped lines the same amount as the first line.\n* `view.WRAPINDENT_INDENT`\n Indent wrapped lines one more level than the level of the first line.\n* `view.WRAPINDENT_DEEPINDENT`\n Indent wrapped lines two more levels than the level of the first line.\n\nThe default value is `view.WRAPINDENT_FIXED`. wrap_mode view.wrap_mode (number)\nLong line wrap mode.\n\n* `view.WRAP_NONE`\n Long lines are not wrapped.\n* `view.WRAP_WORD`\n Wrap long lines at word (and style) boundaries.\n* `view.WRAP_CHAR`\n Wrap long lines at character boundaries.\n* `view.WRAP_WHITESPACE`\n Wrap long lines at word boundaries (ignoring style boundaries).\n\nThe default value is `view.WRAP_NONE`. wrap_start_indent view.wrap_start_indent (number)\nThe number of spaces of indentation to display wrapped lines with if\n`view.wrap_indent_mode` is `view.WRAPINDENT_FIXED`.\nThe default value is `0`. wrap_visual_flags view.wrap_visual_flags (number)\nThe wrapped line visual flag display mode.\n\n* `view.WRAPVISUALFLAG_NONE`\n No visual flags.\n* `view.WRAPVISUALFLAG_END`\n Show a visual flag at the end of a wrapped line.\n* `view.WRAPVISUALFLAG_START`\n Show a visual flag at the beginning of a sub-line.\n* `view.WRAPVISUALFLAG_MARGIN`\n Show a visual flag in the sub-line's line number margin.\n\nThe default value is `view.WRAPVISUALFLAG_NONE`. wrap_visual_flags_location view.wrap_visual_flags_location (number)\nThe wrapped line visual flag location.\n\n* `view.WRAPVISUALFLAGLOC_DEFAULT`\n Draw a visual flag near the view's right margin.\n* `view.WRAPVISUALFLAGLOC_END_BY_TEXT`\n Draw a visual flag near text at the end of a wrapped line.\n* `view.WRAPVISUALFLAGLOC_START_BY_TEXT`\n Draw a visual flag near text at the beginning of a subline.\n\nThe default value is `view.WRAPVISUALFLAGLOC_DEFAULT`. -write spawn_proc:write(...)\nWrites string input to the stdin of process *spawn_proc*.\nNote: On Linux, if more than 65536 bytes (64K) are to be written, it is\npossible those bytes need to be written in 65536-byte (64K) chunks, or the\nprocess may not receive all input. However, it is also possible that there is\na limit on how many bytes can be written in a short period of time, perhaps\n196608 bytes (192K).\n@param ... Standard input for *spawn_proc*. -x_offset view.x_offset (number)\nThe horizontal scroll pixel position.\nA value of `0` is the normal position with the first text column visible at\nthe left of the view. +write spawn_proc:write(...)\nWrites string input to the stdin of process *spawn_proc*.\nNote: On Linux, if more than 65536 bytes (64K) are to be written, it is possible those\nbytes need to be written in 65536-byte (64K) chunks, or the process may not receive all\ninput. However, it is also possible that there is a limit on how many bytes can be written\nin a short period of time, perhaps 196608 bytes (192K).\n@param ... Standard input for *spawn_proc*. +x_offset view.x_offset (number)\nThe horizontal scroll pixel position.\nA value of `0` is the normal position with the first text column visible at the left of\nthe view. xdigit lexer.xdigit (pattern)\nA pattern that matches any hexadecimal digit ('0'-'9', 'A'-'F', 'a'-'f'). -yesno_msgbox ui.dialogs.yesno_msgbox(options)\nPrompts the user with a generic message box dialog defined by dialog options\ntable *options* and with localized "Yes", "No", and "Cancel" buttons,\nreturning the selected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label.\nIf the dialog timed out, returns `0` or `"timeout"`. If the user canceled the\ndialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the message box.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `informative_text`: The dialog's extra informative text.\n * `icon`: The dialog's GTK stock icon name. Examples are\n "gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and\n "gtk-dialog-warning". The dialog does not display an icon by default.\n * `icon_file`: The dialog's icon file path. This option has no effect when\n `icon` is set.\n * `no_cancel`: Do not display the "Cancel" button. The default value is\n `false`.\n * `string_output`: Return the selected button's label (instead of its\n index) or the dialog's exit status instead of the button's index (instead\n of its exit code). The default value is `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value\n is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to\n select a button before timing out. Dialogs do not time out by default.\n@return selected button or exit code +yesno_msgbox ui.dialogs.yesno_msgbox(options)\nPrompts the user with a generic message box dialog defined by dialog options table *options*\nand with localized "Yes", "No", and "Cancel" buttons, returning the selected button's index.\nIf *options*.`string_output` is `true`, returns the selected button's label. If the dialog timed\nout, returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or `"delete"`.\n@param options Table of key-value option pairs for the message box.\n\n * `title`: The dialog's title text.\n * `text`: The dialog's main message text.\n * `informative_text`: The dialog's extra informative text.\n * `icon`: The dialog's GTK stock icon name. Examples are "gtk-dialog-error",\n "gtk-dialog-info", "gtk-dialog-question", and "gtk-dialog-warning". The dialog does not\n display an icon by default.\n * `icon_file`: The dialog's icon file path. This option has no effect when `icon` is set.\n * `no_cancel`: Do not display the "Cancel" button. The default value is `false`.\n * `string_output`: Return the selected button's label (instead of its index) or the dialog's\n exit status instead of the button's index (instead of its exit code). The default value is\n `false`.\n * `width`: The dialog's pixel width.\n * `height`: The dialog's pixel height.\n * `float`: Show the dialog on top of all desktop windows. The default value is `false`.\n * `timeout`: The integer number of seconds the dialog waits for the user to select a button\n before timing out. Dialogs do not time out by default.\n@return selected button or exit code zoom view.zoom (number)\nThe number of points to add to the size of all fonts.\nNegative values are allowed, down to `-10`.\nThe default value is `0`. zoom_in view.zoom_in(view)\nIncreases the size of all fonts by one point, up to 20.\n@param view A view. zoom_out view.zoom_out(view)\nDecreases the size of all fonts by one point, down to -10.\n@param view A view.
\ No newline at end of file diff --git a/modules/lua/ta_tags b/modules/lua/ta_tags index 3ba2dd81..09696545 100644 --- a/modules/lua/ta_tags +++ b/modules/lua/ta_tags @@ -301,14 +301,14 @@ _CHARSET _HOME/core/init.lua /^module('_G')]]$/;" F _G _HOME/core/init.lua /^module('_G')]]$/;" m _HOME _HOME/core/init.lua /^module('_G')]]$/;" F _L _HOME/core/locale.lua /^module('_L')]]$/;" m -_M _HOME/core/._M.luadoc /^module('_M')]]$/;" m +_M _HOME/core/._M.luadoc /^module('_M')$/;" m _M.ansi_c _HOME/modules/ansi_c/init.lua /^module('_M.ansi_c')]]$/;" m _M.lua _HOME/modules/lua/init.lua /^module('_M.lua')]]$/;" m _RELEASE _HOME/core/init.lua /^module('_G')]]$/;" F _SCINTILLA _HOME/core/iface.lua /^module('_SCINTILLA')]]$/;" m _USERHOME _HOME/core/init.lua /^module('_G')]]$/;" F _VIEWS _HOME/core/init.lua /^local _VIEWS$/;" t -_print _HOME/core/ui.lua /^function ui._print(buffer_type, ...)$/;" f class:ui +_print _HOME/core/ui.lua /^function ui._print(buffer_type, ...) _print(assert_type(buffer_type, 'string', 1), ...) end$/;" f class:ui abspath _HOME/core/lfs_ext.lua /^function lfs.abspath(filename, prefix)$/;" f class:lfs active _HOME/modules/textadept/command_entry.lua /^module('ui.command_entry')]]$/;" F class:ui.command_entry active _HOME/modules/textadept/find.lua /^module('ui.find')]]$/;" F class:ui.find @@ -335,7 +335,7 @@ annotation_text _HOME/core/.buffer.luadoc /^module('buffer')$/;" F class:buffer annotation_visible _HOME/core/.view.luadoc /^module('view')$/;" F class:view ansi_c _HOME/modules/ansi_c/init.lua /^module('_M.ansi_c')]]$/;" m class:_M any _HOME/lexers/lexer.lua /^module('lexer')]=]$/;" F class:lexer -api_files _HOME/modules/textadept/editing.lua /^M.api_files = setmetatable({}, {__index = function(t, k)$/;" t class:textadept.editing +api_files _HOME/modules/textadept/editing.lua /^M.api_files = setmetatable({}, {$/;" t class:textadept.editing append_history _HOME/modules/textadept/command_entry.lua /^function M.append_history(f, text)$/;" f class:ui.command_entry append_text _HOME/core/.buffer.luadoc /^function append_text(buffer, text) end$/;" f class:buffer arg _HOME/core/init.lua /^local arg$/;" t @@ -424,7 +424,7 @@ char_right_rect_extend _HOME/core/.buffer.luadoc /^function char_right_rect_exte choose_caret_x _HOME/core/.buffer.luadoc /^function choose_caret_x(buffer) end$/;" f class:buffer clear _HOME/core/.buffer.luadoc /^function clear(buffer) end$/;" f class:buffer clear _HOME/modules/textadept/bookmarks.lua /^function M.clear() buffer:marker_delete_all(M.MARK_BOOKMARK) end$/;" f class:textadept.bookmarks -clear _HOME/modules/textadept/history.lua /^function M.clear()$/;" f class:textadept.history +clear _HOME/modules/textadept/history.lua /^function M.clear() for view in pairs(view_history) do view_history[view] = {pos = 0} end end$/;" f class:textadept.history clear_all _HOME/core/.buffer.luadoc /^function clear_all(buffer) end$/;" f class:buffer clear_document_style _HOME/core/.buffer.luadoc /^function clear_document_style(buffer) end$/;" f class:buffer clear_registered_images _HOME/core/.view.luadoc /^function clear_registered_images(view) end$/;" f class:view @@ -1009,7 +1009,7 @@ word_left _HOME/core/.buffer.luadoc /^function word_left(buffer) end$/;" f class word_left_end _HOME/core/.buffer.luadoc /^function word_left_end(buffer) end$/;" f class:buffer word_left_end_extend _HOME/core/.buffer.luadoc /^function word_left_end_extend(buffer) end$/;" f class:buffer word_left_extend _HOME/core/.buffer.luadoc /^function word_left_extend(buffer) end$/;" f class:buffer -word_match _HOME/lexers/lexer.lua /^function M.word_match(words, case_insensitive, word_chars)$/;" f class:lexer +word_match _HOME/lexers/lexer.lua /^function M.word_match(word_list, case_insensitive, word_chars)$/;" f class:lexer word_part_left _HOME/core/.buffer.luadoc /^function word_part_left(buffer) end$/;" f class:buffer word_part_left_extend _HOME/core/.buffer.luadoc /^function word_part_left_extend(buffer) end$/;" f class:buffer word_part_right _HOME/core/.buffer.luadoc /^function word_part_right(buffer) end$/;" f class:buffer diff --git a/modules/lua/tadoc.lua b/modules/lua/tadoc.lua index f4ba1b93..8404364f 100644 --- a/modules/lua/tadoc.lua +++ b/modules/lua/tadoc.lua @@ -1,11 +1,10 @@ -- Copyright 2007-2021 Mitchell. See LICENSE. -- Textadept autocompletions and API documentation doclet for LuaDoc. --- This module is used by LuaDoc to create Lua autocompletion and API --- documentation files that Textadept can read. --- To preserve formatting, the included *luadoc.patch* file must be applied to --- your instance of LuaDoc. It will not affect the look of HTML web pages, only --- the look of plain-text output. +-- This module is used by LuaDoc to create Lua autocompletion and API documentation files that +-- Textadept can read. +-- To preserve formatting, the included *luadoc.patch* file must be applied to your instance +-- of LuaDoc. It will not affect the look of HTML web pages, only the look of plain-text output. -- Also requires LuaFileSystem (lfs) to be installed. -- @usage luadoc -d [output_path] -doclet path/to/tadoc [file(s)] local M = {} @@ -14,13 +13,16 @@ local CTAG = '%s\t%s\t/^%s$/;"\t%s\t%s' local string_format = string.format local lfs = require('lfs') --- As a special case for Textadept API tags, do not store the local path, but --- use a `_HOME` prefix that will be filled in by consumers. Do this by making --- use of a custom command line switch: --ta-home="path/to/ta/home". +-- As a special case for Textadept API tags, do not store the local path, but use a `_HOME` +-- prefix that will be filled in by consumers. Do this by making use of a custom command line +-- switch: --ta-home="path/to/ta/home". local _HOME for i = 1, #arg do _HOME = arg[i]:match('^%-%-ta%-home=(.+)$') - if _HOME then _HOME = _HOME:gsub('%p', '%%%0') break end + if _HOME then + _HOME = _HOME:gsub('%p', '%%%0') + break + end end -- Writes a ctag. @@ -28,8 +30,8 @@ end -- @param name The name of the tag. -- @param filename The filename the tag occurs in. -- @param code The line of code the tag occurs on. --- @param k The kind of ctag. The Lua module recognizes 4 kinds: m Module, f --- Function, t Table, and F Field. +-- @param k The kind of ctag. The Lua module recognizes 4 kinds: m Module, f Function, t Table, +-- and F Field. -- @param ext_fields The ext_fields for the ctag. local function write_tag(file, name, filename, code, k, ext_fields) if _HOME then filename = filename:gsub(_HOME, '_HOME') end @@ -37,16 +39,16 @@ local function write_tag(file, name, filename, code, k, ext_fields) file[#file + 1] = string_format(CTAG, name, filename, code, k, ext_fields) end --- Sanitizes Markdown from the given documentation string by stripping links and --- replacing HTML entities. +-- Sanitizes Markdown from the given documentation string by stripping links and replacing +-- HTML entities. -- @param s String to sanitize Markdown from. -- @return string local function sanitize_markdown(s) return s:gsub('%[([^%]\r\n]+)%]%b[]', '%1') -- [foo][] - :gsub('%[([^%]\r\n]+)%]%b()', '%1') -- [foo](bar) - :gsub('\r?\n\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar - :gsub('\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar - :gsub('&([%a]+);', {quot = '"', apos = "'"}) + :gsub('%[([^%]\r\n]+)%]%b()', '%1') -- [foo](bar) + :gsub('\r?\n\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar + :gsub('\r?\n%[([^%]\r\n]+)%]:[^\r\n]+', '') -- [foo]: bar + :gsub('&([%a]+);', {quot = '"', apos = "'"}) end -- Writes a function or field apidoc. @@ -63,8 +65,7 @@ local function write_apidoc(file, m, b) local class = b.class local header = name if class == 'function' then - header = header .. - (b.param and string.format('(%s)', table.concat(b.param, ', ')) or '') + header = header .. (b.param and string.format('(%s)', table.concat(b.param, ', ')) or '') elseif class == 'field' and b.description:find('^%s*%b()') then header = string.format('%s %s', header, b.description:match('^%s*(%b())')) elseif class == 'module' or class == 'table' then @@ -74,8 +75,8 @@ local function write_apidoc(file, m, b) -- Function or field description. local description = b.description if class == 'module' then - -- Modules usually have additional Markdown documentation so just grab the - -- documentation before a Markdown header. + -- Modules usually have additional Markdown documentation so just grab the documentation + -- before a Markdown header. description = description:match('^(.-)[\r\n]+#') or description elseif class == 'field' then -- Type information is already in the header; discard it in the description. @@ -83,17 +84,14 @@ local function write_apidoc(file, m, b) -- Strip consistent leading whitespace. local indent indent, description = description:match('^(%s*)(.*)$') - if indent ~= '' then - description = description:gsub('\n' .. indent, '\n') - end + if indent ~= '' then description = description:gsub('\n' .. indent, '\n') end end doc[#doc + 1] = sanitize_markdown(description) -- Function parameters (@param). if class == 'function' and b.param then for _, p in ipairs(b.param) do if b.param[p] and #b.param[p] > 0 then - doc[#doc + 1] = string.format( - '@param %s %s', p, sanitize_markdown(b.param[p])) + doc[#doc + 1] = string.format('@param %s %s', p, sanitize_markdown(b.param[p])) end end end @@ -141,9 +139,9 @@ end -- Called by LuaDoc to process a doc object. -- @param doc The LuaDoc doc object. function M.start(doc) --- require('luarocks.require') --- local profiler = require('profiler') --- profiler.start() + -- require('luarocks.require') + -- local profiler = require('profiler') + -- profiler.start() local modules, files = doc.modules, doc.files @@ -156,8 +154,7 @@ function M.start(doc) -- Add a module's fields to its LuaDoc. for _, filename in ipairs(files) do local module_doc = files[filename].doc[1] - if module_doc and module_doc.class == 'module' and - modules[module_doc.name] then + if module_doc and module_doc.class == 'module' and modules[module_doc.name] then modules[module_doc.name].fields = module_doc.field elseif module_doc then print(string.format('[WARN] %s has no module declaration', filename)) @@ -172,9 +169,7 @@ function M.start(doc) local module_name = func.name:match('^([^%.:]+)[%.:]') or '_G' if not modules[module_name] then modules[#modules + 1] = module_name - modules[module_name] = { - name = module_name, functions = {}, doc = {{code = func.code}} - } + modules[module_name] = {name = module_name, functions = {}, doc = {{code = func.code}}} files[modules[module_name].doc] = abspath(files[1]) -- For functions like file:read(), 'file' is not a module; fake it. if func.name:find(':') then modules[module_name].fake = true end @@ -206,8 +201,7 @@ function M.start(doc) if m.name:find('%.') then -- Tag the last part of the module as a table of the first part. local parent, child = m.name:match('^(.-)%.([^%.]+)$') - write_tag( - ctags, child, filename, m.doc[1].code[1], 'm', 'class:' .. parent) + write_tag(ctags, child, filename, m.doc[1].code[1], 'm', 'class:' .. parent) end m.class = 'module' write_apidoc(apidoc, {name = '_G'}, m) @@ -217,8 +211,7 @@ function M.start(doc) local module_name, name = function_name:match('^(.-)[%.:]?([^.:]+)$') if module_name == '' then module_name = m.name end local func = m.functions[function_name] - write_tag( - ctags, name, filename, func.code[1], 'f', 'class:' .. module_name) + write_tag(ctags, name, filename, func.code[1], 'f', 'class:' .. module_name) write_apidoc(apidoc, m, func) end if m.tables then @@ -234,21 +227,15 @@ function M.start(doc) module_name = '_G' -- _G.keys or _G.snippets end end - write_tag( - ctags, table_name, filename, table.code[1], 't', - 'class:' .. module_name) + write_tag(ctags, table_name, filename, table.code[1], 't', 'class:' .. module_name) write_apidoc(apidoc, m, table) if table.field then -- Tag and document the table's fields. table_name = string.format('%s.%s', module_name, table_name) for _, field_name in ipairs(table.field) do - write_tag( - ctags, field_name, filename, table.code[1], 'F', - 'class:' .. table_name) + write_tag(ctags, field_name, filename, table.code[1], 'F', 'class:' .. table_name) write_apidoc(apidoc, {name = table_name}, { - name = field_name, - description = table.field[field_name], - class = 'table' + name = field_name, description = table.field[field_name], class = 'table' }) end end @@ -265,12 +252,9 @@ function M.start(doc) print('[ERROR] Cannot determine module name for ' .. field.name) end end - write_tag( - ctags, field_name, filename, m.doc[1].code[1], 'F', - 'class:' .. module_name) + write_tag(ctags, field_name, filename, m.doc[1].code[1], 'F', 'class:' .. module_name) write_apidoc(apidoc, {name = field_name}, { - name = string.format('%s.%s', module_name, field_name), - description = field, + name = string.format('%s.%s', module_name, field_name), description = field, class = 'field' }) end @@ -285,7 +269,7 @@ function M.start(doc) f:write(table.concat(apidoc, '\n')) f:close() --- profiler.stop() + -- profiler.stop() end return M diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua index b790fd09..532d1427 100644 --- a/modules/textadept/bookmarks.lua +++ b/modules/textadept/bookmarks.lua @@ -35,13 +35,13 @@ local function bookmarks(buffer) end --- --- 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. --- @param 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. +-- 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. +-- @param 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. -- @name goto_mark function M.goto_mark(next) if next ~= nil then @@ -49,9 +49,7 @@ function M.goto_mark(next) local line = buffer:line_from_position(buffer.current_pos) local BOOKMARK_BIT = 1 << M.MARK_BOOKMARK - 1 line = f(buffer, line + (next and 1 or -1), BOOKMARK_BIT) - if line == -1 then - line = f(buffer, (next and 1 or buffer.line_count), BOOKMARK_BIT) - end + if line == -1 then line = f(buffer, (next and 1 or buffer.line_count), BOOKMARK_BIT) end if line >= 1 then textadept.editing.goto_line(line) end return end @@ -64,8 +62,8 @@ function M.goto_mark(next) if buffer.filename then filename = filename:iconv('UTF-8', _CHARSET) end local basename = buffer.filename and filename:match('[^/\\]+$') or filename for line in bookmarks(buffer) do - utf8_list[#utf8_list + 1] = string.format( - '%s:%d: %s', basename, line, buffer:get_line(line):match('^[^\r\n]*')) + utf8_list[#utf8_list + 1] = string.format('%s:%d: %s', basename, line, + buffer:get_line(line):match('^[^\r\n]*')) buffers[#buffers + 1] = buffer end ::continue:: @@ -83,9 +81,8 @@ end local lines = {} -- Save and restore bookmarks on buffer:reload(). -events.connect(events.FILE_BEFORE_RELOAD, function() - for line in bookmarks(buffer) do lines[#lines + 1] = line end -end) +events.connect(events.FILE_BEFORE_RELOAD, + function() for line in bookmarks(buffer) do lines[#lines + 1] = line end end) events.connect(events.FILE_AFTER_RELOAD, function() for _, line in ipairs(lines) do buffer:marker_add(line, M.MARK_BOOKMARK) end lines = {} -- clear diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua index 14e66a07..cecad02c 100644 --- a/modules/textadept/command_entry.lua +++ b/modules/textadept/command_entry.lua @@ -6,8 +6,8 @@ local M = ui.command_entry --[[ This comment is for LuaDoc. --- -- 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. -- @field height (number) -- The height in pixels of the command entry. -- @field active (boolean) @@ -18,16 +18,21 @@ module('ui.command_entry')]] -- The current mode is in the `mode` field. -- @class table -- @name history -local history = setmetatable({}, {__index = function(t, k) - if type(k) == 'function' then t[k] = {pos = 0} else return nil end - return t[k] -end}) +local history = setmetatable({}, { + __index = function(t, k) + if type(k) ~= 'function' then return nil end + t[k] = {pos = 0} + return t[k] + end +}) -- Cycles through command history for the current mode. --- @param prev Flag that indicates whether to cycle to the previous command or --- the next one. +-- @param prev Flag that indicates whether to cycle to the previous command or the next one. local function cycle_history(prev) - if M:auto_c_active() then M[prev and 'line_up' or 'line_down'](M) return end + if M:auto_c_active() then + M[prev and 'line_up' or 'line_down'](M) + return + end local mode_history = history[history.mode] if not mode_history or prev and mode_history.pos <= 1 then return end if not prev and mode_history.pos >= #mode_history then return end @@ -38,14 +43,12 @@ local function cycle_history(prev) end --- --- 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. --- @param 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. +-- 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. +-- @param 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. -- @param text String text to append to history. -- @name append_history function M.append_history(f, text) @@ -59,9 +62,8 @@ end --- -- 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 setmetatable(mode_keys, ui.command_entry.editing_keys) -- @class table -- @name editing_keys @@ -69,8 +71,7 @@ M.editing_keys = {__index = {}} -- Fill in default key bindings for Linux/Win32, macOS, Terminal. local bindings = { - -- Note: cannot use `M.cut`, `M.copy`, etc. since M is never considered the - -- global buffer. + -- Note: cannot use `M.cut`, `M.copy`, etc. since M is never considered the global buffer. [function() M:undo() end] = {'ctrl+z', 'cmd+z', 'ctrl+z'}, [function() M:undo() end] = {nil, nil, 'meta+z'}, [function() M:redo() end] = {'ctrl+y', 'cmd+Z', 'ctrl+y'}, @@ -80,7 +81,7 @@ local bindings = { [function() M:paste() end] = {'ctrl+v', 'cmd+v', 'ctrl+v'}, [function() M:select_all() end] = {'ctrl+a', 'cmd+a', 'meta+a'}, [function() cycle_history(true) end] = {'up', 'up', 'up'}, - [cycle_history] = {'down', 'down', 'down'}, + [cycle_history] = {'down', 'down', 'down'}, -- LuaFormatter -- Movement keys. [function() M:char_right() end] = {nil, 'ctrl+f', 'ctrl+f'}, [function() M:char_left() end] = {nil, 'ctrl+b', 'ctrl+b'}, @@ -104,25 +105,26 @@ local env = setmetatable({}, { return function(...) view[k](view, ...) end -- do not return a value end return buffer[k] or view[k] or ui[k] or _G[k] or textadept[k] - end, + end, -- LuaFormatter __newindex = function(self, k, v) local ok, value = pcall(function() return buffer[k] end) if ok and value ~= nil or not ok and value:find('write-only property') then buffer[k] = v -- buffer and view are interchangeable in this case - return + elseif view[k] ~= nil then + view[k] = v + elseif ui[k] ~= nil then + ui[k] = v + else + rawset(self, k, v) end - if view[k] ~= nil then view[k] = v return end - if ui[k] ~= nil then ui[k] = v return end - rawset(self, k, v) end }) --- Executes string *code* as Lua code that is subject to an "abbreviated" --- environment. --- In this environment, the contents of the `buffer`, `view`, `ui`, and --- `textadept` tables are also considered as global functions and fields. --- Prints the results of expressions like in the Lua prompt. Also invokes bare --- functions as commands. +-- Executes string *code* as Lua code that is subject to an "abbreviated" environment. +-- In this environment, the contents of the `buffer`, `view`, `ui`, and `textadept` tables are +-- also considered as global functions and fields. +-- Prints the results of expressions like in the Lua prompt. Also invokes bare functions as +-- commands. -- @param code The Lua code to execute. local function run_lua(code) local f, errmsg = load('return ' .. code, nil, 't', env) @@ -131,15 +133,12 @@ local function run_lua(code) if type(result) == 'function' then result = result() end if type(result) == 'table' then local items = {} - for k, v in pairs(result) do - items[#items + 1] = string.format('%s = %s', k, v) - end + for k, v in pairs(result) do items[#items + 1] = string.format('%s = %s', k, v) end table.sort(items) result = string.format('{%s}', table.concat(items, ', ')) if view.edge_column > 0 and #result > view.edge_column then local indent = string.rep(' ', buffer.tab_width) - result = string.format( - '{\n%s%s\n}', indent, table.concat(items, ',\n' .. indent)) + result = string.format('{\n%s%s\n}', indent, table.concat(items, ',\n' .. indent)) end end if result ~= nil or code:find('^return ') then ui.print(result) end @@ -147,15 +146,13 @@ local function run_lua(code) end args.register('-e', '--execute', 1, run_lua, 'Execute Lua code') --- Shows a set of Lua code completions for the entry's text, subject to an --- "abbreviated" environment where the contents of the `buffer`, `view`, and --- `ui` tables are also considered as globals. +-- Shows a set of Lua code completions for the entry's text, subject to an "abbreviated" +-- environment where the contents of the `buffer`, `view`, and `ui` tables are also considered +-- as globals. local function complete_lua() local line, pos = M:get_cur_line() - local symbol, op, part = line:sub(1, pos - 1):match( - '([%w_.]-)([%.:]?)([%w_]*)$') - local ok, result = pcall( - (load(string.format('return (%s)', symbol), nil, 't', env))) + local symbol, op, part = line:sub(1, pos - 1):match('([%w_.]-)([%.:]?)([%w_]*)$') + local ok, result = pcall((load(string.format('return (%s)', symbol), nil, 't', env))) if (not ok or type(result) ~= 'table') and symbol ~= '' then return end local cmpls = {} part = '^' .. part @@ -163,23 +160,20 @@ local function complete_lua() local sep = string.char(M.auto_c_type_separator) if not ok or symbol == 'buffer' or symbol == 'view' then local sci = _SCINTILLA - local global_envs = not ok and { - buffer, view, ui, _G, textadept, sci.functions, sci.properties, - sci.constants - } or op == ':' and {sci.functions} or {sci.properties, sci.constants} + local global_envs = not ok and + {buffer, view, ui, _G, textadept, sci.functions, sci.properties, sci.constants} or op == ':' and + {sci.functions} or {sci.properties, sci.constants} for _, env in ipairs(global_envs) do for k, v in pairs(env) do if type(k) ~= 'string' or not k:find(part) then goto continue end - local xpm = (type(v) == 'function' or env == sci.functions) and - XPM.METHOD or XPM.VARIABLE + local xpm = (type(v) == 'function' or env == sci.functions) and XPM.METHOD or XPM.VARIABLE cmpls[#cmpls + 1] = k .. sep .. xpm ::continue:: end end else for k, v in pairs(result) do - if type(k) == 'string' and k:find(part) and - (op == '.' or type(v) == 'function') then + if type(k) == 'string' and k:find(part) and (op == '.' or type(v) == 'function') then local xpm = type(v) == 'function' and XPM.METHOD or XPM.VARIABLE cmpls[#cmpls + 1] = k .. sep .. xpm end @@ -198,28 +192,22 @@ local lua_keys = {['\t'] = complete_lua} local prev_key_mode --- --- 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`. --- @param 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. --- @param 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. +-- 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`. +-- @param 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. +-- @param 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. --- @param lang Optional string lexer name to use for command entry text. The --- default value is `'text'`. --- @param height Optional number of lines to display in the command entry. The --- default value is `1`. +-- @param lang Optional string lexer name to use for command entry text. The default value is +-- `'text'`. +-- @param height Optional number of lines to display in the command entry. The default value is `1`. -- @see editing_keys -- @usage ui.command_entry.run(ui.print) -- @name run @@ -262,8 +250,8 @@ M.focus = function() end -- Configure the command entry's default properties. --- Also find the key binding for `textadept.editing.show_documentation` and use --- it to show Lua documentation in the Lua command entry. +-- Also find the key binding for `textadept.editing.show_documentation` and use it to show Lua +-- documentation in the Lua command entry. events.connect(events.INITIALIZED, function() M.h_scroll_bar, M.v_scroll_bar = false, false for i = 1, M.margins do M.margin_width_n[i] = 0 end @@ -271,8 +259,8 @@ events.connect(events.INITIALIZED, function() for key, f in pairs(keys) do if f ~= textadept.editing.show_documentation then goto continue end lua_keys[key] = function() - -- Temporarily change _G.buffer and _G.view since ui.command_entry is - -- the "active" buffer and view. + -- Temporarily change _G.buffer and _G.view since ui.command_entry is the "active" buffer + -- and view. local orig_buffer, orig_view = _G.buffer, _G.view _G.buffer, _G.view = ui.command_entry, ui.command_entry textadept.editing.show_documentation() diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua index 7ff771a2..1b4a51ba 100644 --- a/modules/textadept/editing.lua +++ b/modules/textadept/editing.lua @@ -9,8 +9,7 @@ local M = {} -- Match the previous line's indentation level after inserting a new line. -- The default value is `true`. -- @field 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`. -- @field autocomplete_all_words (bool) -- Autocomplete the current word using words from all open buffers. @@ -28,8 +27,8 @@ local M = {} -- -- The default value is `textadept.editing.HIGHLIGHT_NONE`. -- @field auto_enclose (bool) --- Whether or not to auto-enclose selected text when typing a punctuation --- character, taking [`textadept.editing.auto_pairs`]() into account. +-- Whether or not to auto-enclose selected text when typing a punctuation character, taking +-- [`textadept.editing.auto_pairs`]() into account. -- The default value is `false`. -- @field INDIC_BRACEMATCH (number) -- The matching brace highlight indicator number. @@ -46,6 +45,7 @@ M.auto_enclose = false M.INDIC_BRACEMATCH = _SCINTILLA.next_indic_number() M.INDIC_HIGHLIGHT = _SCINTILLA.next_indic_number() +-- LuaFormatter off --- -- Map of image names to registered image numbers. -- @field CLASS The image number for classes. @@ -59,6 +59,7 @@ M.INDIC_HIGHLIGHT = _SCINTILLA.next_indic_number() -- @class table -- @name XPM_IMAGES M.XPM_IMAGES = {not CURSES and '/* XPM */static char *class[] = {/* columns rows colors chars-per-pixel */"16 16 10 1 "," c #000000",". c #001CD0","X c #008080","o c #0080E8","O c #00C0C0","+ c #24D0FC","@ c #00FFFF","# c #A4E8FC","$ c #C0FFFF","% c None",/* pixels */"%%%%% %%%%%%%%%","%%%% ## %%%%%%%","%%% ###++ %%%%%%","%% +++++. %%%%","%% oo++.. $$ %%","%% ooo.. $$$@@ %","%% ooo. @@@@@X %","%%% . OO@@XX %","%%% ## OOOXXX %","%% ###++ OOXX %%","% +++++. OX %%%","% oo++.. % %%%%","% ooo... %%%%%%%","% ooo.. %%%%%%%%","%% o. %%%%%%%%%","%%%% %%%%%%%%%%"};' or '*',not CURSES and '/* XPM */static char *namespace[] = {/* columns rows colors chars-per-pixel */"16 16 7 1 "," c #000000",". c #1D1D1D","X c #393939","o c #555555","O c #A8A8A8","+ c #AAAAAA","@ c None",/* pixels */"@@@@@@@@@@@@@@@@","@@@@+@@@@@@@@@@@","@@@.o@@@@@@@@@@@","@@@ +@@@@@@@@@@@","@@@ +@@@@@@@@@@@","@@+.@@@@@@@+@@@@","@@+ @@@@@@@o.@@@","@@@ +@@@@@@+ @@@","@@@ +@@@@@@+ @@@","@@@.X@@@@@@@.+@@","@@@@+@@@@@@@ @@@","@@@@@@@@@@@+ @@@","@@@@@@@@@@@+ @@@","@@@@@@@@@@@X.@@@","@@@@@@@@@@@+@@@@","@@@@@@@@@@@@@@@@"};' or '@',not CURSES and '/* XPM */static char *method[] = {/* columns rows colors chars-per-pixel */"16 16 5 1 "," c #000000",". c #E0BC38","X c #F0DC5C","o c #FCFC80","O c None",/* pixels */"OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOO OOOO","OOOOOOOOO oo OO","OOOOOOOO ooooo O","OOOOOOO ooooo. O","OOOO O XXoo.. O","OOO oo XXX... O","OO ooooo XX.. OO","O ooooo. X. OOO","O XXoo.. O OOOO","O XXX... OOOOOOO","O XXX.. OOOOOOOO","OO X. OOOOOOOOO","OOOO OOOOOOOOOO"};' or '+',not CURSES and '/* XPM */static char *signal[] = {/* columns rows colors chars-per-pixel */"16 16 6 1 "," c #000000",". c #FF0000","X c #E0BC38","o c #F0DC5C","O c #FCFC80","+ c None",/* pixels */"++++++++++++++++","++++++++++++++++","++++++++++++++++","++++++++++ ++++","+++++++++ OO ++","++++++++ OOOOO +","+++++++ OOOOOX +","++++ + ooOOXX +","+++ OO oooXXX +","++ OOOOO ooXX ++","+ OOOOOX oX +++","+ ooOOXX + ++++","+ oooXXX +++++++","+ oooXX +++++..+","++ oX ++++++..+","++++ ++++++++++"};' or '~',not CURSES and '/* XPM */static char *slot[] = {/* columns rows colors chars-per-pixel */"16 16 5 1 "," c #000000",". c #E0BC38","X c #F0DC5C","o c #FCFC80","O c None",/* pixels */"OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOO OOOO","OOOOOOOOO oo OO","OOOOOOOO ooooo O","OOOOOOO ooooo. O","OOOO O XXoo.. O","OOO oo XXX... O","OO ooooo XX.. OO","O ooooo. X. OOO","O XXoo.. O OOOO","O XXX... OOOOOOO","O XXX.. OOOOO ","OO X. OOOOOO O ","OOOO OOOOOOO "};' or '-',not CURSES and '/* XPM */static char *variable[] = {/* columns rows colors chars-per-pixel */"16 16 5 1 "," c #000000",". c #8C748C","X c #9C94A4","o c #ACB4C0","O c None",/* pixels */"OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOOOOOOOOO","OOOOOOOOO OOOOO","OOOOOOOO oo OOO","OOOOOOO ooooo OO","OOOOOO ooooo. OO","OOOOOO XXoo.. OO","OOOOOO XXX... OO","OOOOOO XXX.. OOO","OOOOOOO X. OOOO","OOOOOOOOO OOOOO","OOOOOOOOOOOOOOOO"};' or '.',not CURSES and '/* XPM */static char *struct[] = {/* columns rows colors chars-per-pixel */"16 16 14 1 "," c #000000",". c #008000","X c #00C000","o c #00FF00","O c #808000","+ c #C0C000","@ c #FFFF00","# c #008080","$ c #00C0C0","% c #00FFFF","& c #C0FFC0","* c #FFFFC0","= c #C0FFFF","- c None",/* pixels */"----- ---------","---- && -------","--- &&&oo ------","-- ooooo. ----","-- XXoo.. == --","-- XXX.. ===%% -","-- XXX. %%%%%# -","--- . $$%%## -","--- ** $$$### -","-- ***@@ $$## --","- @@@@@O $# ---","- ++@@OO - ----","- +++OOO -------","- +++OO --------","-- +O ---------","---- ----------"};' or '}',not CURSES and '/* XPM */static char *typedef[] = {/* columns rows colors chars-per-pixel */"16 16 10 1 "," c #000000",". c #404040","X c #6D6D6D","o c #777777","O c #949494","+ c #ACACAC","@ c #BBBBBB","# c #DBDBDB","$ c #EEEEEE","% c None",/* pixels */"%%%%% %%%%%%%%%","%%%% ## %%%%%%%","%%% ###++ %%%%%%","%% +++++. %%%%","%% oo++.. $$ %%","%% ooo.. $$$@@ %","%% ooo. @@@@@X %","%%% . OO@@XX %","%%% ## OOOXXX %","%% ###++ OOXX %%","% +++++. OX %%%","% oo++.. % %%%%","% ooo... %%%%%%%","% ooo.. %%%%%%%%","%% o. %%%%%%%%%","%%%% %%%%%%%%%%"};' or ':',CLASS=1,NAMESPACE=2,METHOD=3,SIGNAL=4,SLOT=5,VARIABLE=6,STRUCT=7,TYPEDEF=8} +-- LuaFormatter on events.connect(events.VIEW_NEW, function() local view = buffer ~= ui.command_entry and view or ui.command_entry for name, i in pairs(M.XPM_IMAGES) do @@ -67,21 +68,23 @@ events.connect(events.VIEW_NEW, function() end) for _ = 1, #M.XPM_IMAGES do _SCINTILLA.next_image_type() end -- sync +-- LuaFormatter off --- --- 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. -- @class table -- @name comment_string -- @see toggle_comment M.comment_string = {actionscript='//',ada='--',apdl='!',ansi_c='/*|*/',antlr='//',apl='#',applescript='--',asp='\'',autoit=';',awk='#',b_lang='//',bash='#',batch=':',bibtex='%',boo='#',chuck='//',clojure=';',cmake='#',coffeescript='#',context='%',cpp='//',crystal='#',csharp='//',css='/*|*/',cuda='//',desktop='#',django='{#|#}',dmd='//',dockerfile='#',dot='//',eiffel='--',elixir='#',elm='--',erlang='%',fantom='//',faust='//',fennel=';',fish='#',forth='|\\',fortran='!',fsharp='//',fstab='#',gap='#',gettext='#',gherkin='#',glsl='//',gnuplot='#',go='//',groovy='//',gtkrc='#',haskell='--',html='<!--|-->',icon='#',idl='//',inform='!',ini='#',Io='#',java='//',javascript='//',jq='#',json='/*|*/',jsp='//',julia='#',latex='%',ledger='#',less='//',lilypond='%',lisp=';',logtalk='%',lua='--',makefile='#',matlab='#',meson='#',moonscript='--',myrddin='//',nemerle='//',networkd='#',nim='#',nsis='#',objective_c='//',pascal='//',perl='#',php='//',pico8='//',pike='//',pkgbuild='#',pony='//',prolog='%',props='#',protobuf='//',ps='%',pure='//',python='#',rails='#',rc='#',reason='//',rebol=';',rest='.. ',rexx='--',rhtml='<!--|-->',routeros='#',rstats='#',ruby='#',rust='//',sass='//',scala='//',scheme=';',smalltalk='"|"',sml='(*)',snobol4='#',spin="'",sql='--',systemd='#',tcl='#',tex='%',text='',toml='#',typescript='//',vala='//',vb='\'',vbscript='\'',verilog='//',vhdl='--',wsf='<!--|-->',xml='<!--|-->',xs='#',xtend='//',yaml='#',zig='//'} +-- LuaFormatter on --- -- 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 +-- """". -- @class table -- @name auto_pairs -- @usage textadept.editing.auto_pairs[60] = '>' -- pair '<' and '>' @@ -90,8 +93,8 @@ M.auto_pairs = {[40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"'} --- -- 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 '}'. -- @class table -- @name brace_matches -- @usage textadept.editing.brace_matches[60] = true -- '<' @@ -100,8 +103,8 @@ M.brace_matches = {[40] = 1, [41] = 1, [91] = 1, [93] = 1, [123] = 1, [125] = 1} --- -- 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 '"'. -- @class table -- @name typeover_chars -- @usage textadept.editing.typeover_chars[62] = true -- '>' @@ -109,12 +112,10 @@ M.typeover_chars = {[41] = 1, [93] = 1, [125] = 1, [39] = 1, [34] = 1} --- -- 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. -- @class table -- @name autocompleters -- @see autocomplete @@ -122,20 +123,20 @@ M.autocompleters = {} --- -- 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. -- @class table -- @name api_files -- @see show_documentation -M.api_files = setmetatable({}, {__index = function(t, k) - t[k] = {} - return t[k] -end}) +M.api_files = setmetatable({}, { + __index = function(t, k) + t[k] = {} + return t[k] + end +}) --- Matches characters specified in auto_pairs, taking multiple selections into --- account. +-- Matches characters specified in auto_pairs, taking multiple selections into account. events.connect(events.CHAR_ADDED, function(code) if not M.auto_pairs or not M.auto_pairs[code] then return end buffer:begin_undo_action() @@ -149,8 +150,7 @@ end) -- Removes matched chars on backspace, taking multiple selections into account. events.connect(events.KEYPRESS, function(code) - if M.auto_pairs and keys.KEYSYMS[code] == '\b' and - not ui.command_entry.active then + if M.auto_pairs and keys.KEYSYMS[code] == '\b' and not ui.command_entry.active then buffer:begin_undo_action() for i = 1, buffer.selections do local pos = buffer.selection_n_caret[i] @@ -206,17 +206,14 @@ events.connect(events.UPDATE_UI, function(updated) buffer.search_flags = buffer.FIND_MATCHCASE | buffer.FIND_WHOLEWORD buffer:target_whole_document() while buffer:search_in_target(word) ~= -1 do - buffer:indicator_fill_range( - buffer.target_start, buffer.target_end - buffer.target_start) + buffer:indicator_fill_range(buffer.target_start, buffer.target_end - buffer.target_start) buffer:set_target_range(buffer.target_end, buffer.length + 1) end end) --- Moves over typeover characters when typed, taking multiple selections into --- account. +-- Moves over typeover characters when typed, taking multiple selections into account. events.connect(events.KEYPRESS, function(code) - if M.typeover_chars and M.typeover_chars[code] and - not ui.command_entry.active then + if M.typeover_chars and M.typeover_chars[code] and not ui.command_entry.active then local handled = false for i = 1, buffer.selections do local s, e = buffer.selection_n_start[i], buffer.selection_n_end[i] @@ -234,7 +231,7 @@ events.connect(events.CHAR_ADDED, function(code) if not M.auto_indent or code ~= string.byte('\n') then return end local line = buffer:line_from_position(buffer.current_pos) if line > 1 and buffer:get_line(line - 1):find('^[\r\n]+$') and - buffer:get_line(line):find('^[^\r\n]') then + buffer:get_line(line):find('^[^\r\n]') then return -- do not auto-indent when pressing enter from start of previous line end local i = line - 1 @@ -245,8 +242,8 @@ events.connect(events.CHAR_ADDED, function(code) end end) --- Enables and disables bracketed paste mode in curses and disables auto-pair --- and auto-indent while pasting. +-- Enables and disables bracketed paste mode in curses and disables auto-pair and auto-indent +-- while pasting. if CURSES and not WIN32 then local function enable_br_paste() io.stdout:write('\x1b[?2004h'):flush() end local function disable_br_paste() io.stdout:write('\x1b[?2004l'):flush() end @@ -267,8 +264,8 @@ if CURSES and not WIN32 then end) end --- Prepares the buffer for saving to a file by stripping trailing whitespace, --- ensuring a final newline, and normalizing line endings. +-- Prepares the buffer for saving to a file by stripping trailing whitespace, ensuring a final +-- newline, and normalizing line endings. events.connect(events.FILE_BEFORE_SAVE, function() if not M.strip_trailing_spaces or not buffer.encoding then return end buffer:begin_undo_action() @@ -289,8 +286,8 @@ events.connect(events.FILE_BEFORE_SAVE, function() end) --- --- 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. -- @name paste_reindent function M.paste_reindent() local line = buffer:line_from_position(buffer.selection_start) @@ -307,31 +304,25 @@ function M.paste_reindent() text = text:gsub('\n([ \t]+)', function(indentation) if indentation:find('^\t') then return buffer.use_tabs and '\n' .. indentation or - '\n' .. indentation:gsub('\t', string.rep(' ', buffer.tab_width)) + ('\n' .. indentation:gsub('\t', string.rep(' ', buffer.tab_width))) else tab_width = math.min(tab_width, #indentation) local indent = math.floor(#indentation / tab_width) local spaces = string.rep(' ', math.fmod(#indentation, tab_width)) - return string.format( - '\n%s%s', buffer.use_tabs and string.rep('\t', indent) or + return string.format('\n%s%s', buffer.use_tabs and string.rep('\t', indent) or string.rep(' ', buffer.tab_width):rep(indent), spaces) end end) - -- Re-indent according to whichever of the current and preceding lines has the - -- higher indentation amount. However, if the preceding line is a fold header, - -- indent by an extra level. + -- Re-indent according to whichever of the current and preceding lines has the higher indentation + -- amount. However, if the preceding line is a fold header, indent by an extra level. local i = line - 1 while i >= 1 and buffer:get_line(i):find('^[\r\n]+$') do i = i - 1 end - if i < 1 or buffer.line_indentation[i] < buffer.line_indentation[line] then - i = line - end - local indentation = buffer:text_range( - buffer:position_from_line(i), buffer.line_indent_position[i]) - local fold_header = - i ~= line and buffer.fold_level[i] & buffer.FOLDLEVELHEADERFLAG > 0 + if i < 1 or buffer.line_indentation[i] < buffer.line_indentation[line] then i = line end + local indentation = + buffer:text_range(buffer:position_from_line(i), buffer.line_indent_position[i]) + local fold_header = i ~= line and buffer.fold_level[i] & buffer.FOLDLEVELHEADERFLAG > 0 if fold_header then - indentation = indentation .. - (buffer.use_tabs and '\t' or string.rep(' ', buffer.tab_width)) + indentation = indentation .. (buffer.use_tabs and '\t' or string.rep(' ', buffer.tab_width)) end text = text:gsub('\n', '\n' .. indentation) -- Paste the text and adjust first and last line indentation accordingly. @@ -374,9 +365,7 @@ function M.toggle_comment() local uncomment = buffer:text_range(p, p + #prefix) == prefix if not uncomment then buffer:insert_text(p, prefix) - if suffix ~= '' then - buffer:insert_text(buffer.line_end_position[line], suffix) - end + if suffix ~= '' then buffer:insert_text(buffer.line_end_position[line], suffix) end else buffer:delete_range(p, #prefix) if suffix ~= '' then @@ -392,20 +381,23 @@ function M.toggle_comment() -- Keep the anchor and caret on the first line as necessary. local start_pos = buffer:position_from_line(s) anchor, pos = math.max(anchor, start_pos), math.max(pos, start_pos) - if s ~= e then buffer:set_sel(anchor, pos) else buffer:goto_pos(pos) end + if s ~= e then + buffer:set_sel(anchor, pos) + else + buffer:goto_pos(pos) + end end --- --- Moves the caret to the beginning of line number *line* or the user-specified --- line, ensuring *line* is visible. --- @param line Optional line number to go to. If `nil`, the user is prompted for --- one. +-- Moves the caret to the beginning of line number *line* or the user-specified line, ensuring +-- *line* is visible. +-- @param line Optional line number to go to. If `nil`, the user is prompted for one. -- @name goto_line function M.goto_line(line) if not assert_type(line, 'number/nil', 1) then local button, value = ui.dialogs.inputbox{ - title = _L['Go To'], informative_text = _L['Line Number:'], - button1 = _L['OK'], button2 = _L['Cancel'] + title = _L['Go To'], informative_text = _L['Line Number:'], button1 = _L['OK'], + button2 = _L['Cancel'] } line = tonumber(value) if button ~= 1 or not line then return end @@ -413,14 +405,13 @@ function M.goto_line(line) view:ensure_visible_enforce_policy(line) buffer:goto_line(line) end -args.register('-l', '--line', 1, function(line) - M.goto_line(tonumber(line) or line) -end, 'Go to line') +args.register('-l', '--line', 1, function(line) M.goto_line(tonumber(line) or line) end, + 'Go to line') --- -- 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. -- @name transpose_chars function M.transpose_chars() local pos = buffer.current_pos @@ -434,10 +425,8 @@ function M.transpose_chars() end --- --- 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. -- @name join_lines function M.join_lines() buffer:target_from_selection() @@ -450,8 +439,8 @@ function M.join_lines() end --- --- 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. -- @param left The left part of the enclosure. -- @param right The right part of the enclosure. -- @name enclose @@ -475,8 +464,8 @@ end -- Enclose selected text in punctuation or auto-paired characters. events.connect(events.KEYPRESS, function(code, shift, ctrl, alt, cmd) - if M.auto_enclose and not buffer.selection_empty and code < 256 and - not ctrl and not alt and not cmd and not ui.command_entry.active then + if M.auto_enclose and not buffer.selection_empty and code < 256 and not ctrl and not alt and + not cmd and not ui.command_entry.active then local char = string.char(code) if char:find('^%P') then return end -- not punctuation M.enclose(char, M.auto_pairs[code] or char) @@ -486,11 +475,9 @@ end, 1) --- -- 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. -- @param left Optional left part of the enclosure. -- @param right Optional right part of the enclosure. -- @see auto_pairs @@ -511,7 +498,7 @@ function M.select_enclosed(left, right) e = buffer:brace_match(s, 0) break elseif M.brace_matches[buffer.char_at[s]] or - buffer.style_at[s] == buffer.style_at[buffer.selection_start] then + (buffer.style_at[s] == buffer.style_at[buffer.selection_start]) then buffer.search_flags = 0 buffer:set_target_range(s + 1, buffer.length + 1) if buffer:search_in_target(match) >= buffer.selection_end - 1 then @@ -529,19 +516,16 @@ function M.select_enclosed(left, right) end --- --- 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. --- @param all Whether or not to select all occurrences of the current word. --- The default value is `false`. +-- 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. +-- @param all Whether or not to select all occurrences of the current word. The default value is +-- `false`. -- @see buffer.word_chars -- @name select_word function M.select_word(all) buffer:target_whole_document() buffer.search_flags = buffer.FIND_MATCHCASE - if buffer.selection_empty or - buffer:is_range_word(buffer.selection_start, buffer.selection_end) then + if buffer.selection_empty or buffer:is_range_word(buffer.selection_start, buffer.selection_end) then buffer.search_flags = buffer.search_flags | buffer.FIND_WHOLEWORD if all then buffer:multiple_select_add_next() end -- select word first end @@ -568,9 +552,8 @@ end --- -- 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 buffer.use_tabs -- @name convert_indentation function M.convert_indentation() @@ -596,20 +579,19 @@ function M.convert_indentation() end --- --- 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. --- @param command The Linux, BSD, macOS, or Windows shell command to filter text --- through. May contain pipes. +-- 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. +-- @param command The Linux, BSD, macOS, or Windows shell command to filter text through. May +-- contain pipes. -- @name filter_through function M.filter_through(command) assert(not (WIN32 and CURSES), 'not implemented in this environment') @@ -627,12 +609,14 @@ function M.filter_through(command) end buffer:set_target_range(s, e) end + -- LuaFormatter off local commands = lpeg.match(lpeg.Ct(lpeg.P{ lpeg.C(lpeg.V('command')) * ('|' * lpeg.C(lpeg.V('command')))^0, command = (1 - lpeg.S('"\'|') + lpeg.V('str'))^1, str = '"' * (1 - lpeg.S('"\\') + lpeg.P('\\') * 1)^0 * lpeg.P('"')^-1 + - "'" * (1 - lpeg.S("'\\") + lpeg.P('\\') * 1)^0 * lpeg.P("'")^-1, + "'" * (1 - lpeg.S("'\\") + lpeg.P('\\') * 1)^0 * lpeg.P("'")^-1 }), command) + -- LuaFormatter on local output = buffer.target_text for i = 1, #commands do local p = assert(os.spawn(commands[i]:match('^%s*(.-)%s*$'))) @@ -640,21 +624,23 @@ function M.filter_through(command) p:close() output = p:read('a') or '' if p:wait() ~= 0 then - ui.statusbar_text = string.format( - '"%s" %s', commands[i], _L['returned non-zero status']) + ui.statusbar_text = string.format('"%s" %s', commands[i], _L['returned non-zero status']) return end end buffer:replace_target(output:iconv('UTF-8', _CHARSET)) - if s == e then buffer:goto_pos(s) return end + if s == e then + buffer:goto_pos(s) + return + end buffer:set_sel(buffer.target_start, buffer.target_end) end --- --- Displays an autocompletion list provided by the autocompleter function --- associated with string *name*, and returns `true` if completions were found. --- @param name The name of an autocompleter function in the `autocompleters` --- table to use for providing autocompletions. +-- Displays an autocompletion list provided by the autocompleter function associated with string +-- *name*, and returns `true` if completions were found. +-- @param name The name of an autocompleter function in the `autocompleters` table to use for +-- providing autocompletions. -- @name autocomplete -- @see autocompleters function M.autocomplete(name) @@ -662,14 +648,12 @@ function M.autocomplete(name) local len_entered, list = M.autocompleters[name]() if not len_entered or not list or #list == 0 then return end buffer.auto_c_order = buffer.ORDER_PERFORMSORT - buffer:auto_c_show( - len_entered, table.concat(list, string.char(buffer.auto_c_separator))) + buffer:auto_c_show(len_entered, table.concat(list, string.char(buffer.auto_c_separator))) return true end --- Returns for the word part behind the caret a list of whole word completions --- constructed from the current buffer or all open buffers (depending on --- `M.autocomplete_all_words`). +-- Returns for the word part behind the caret a list of whole word completions constructed from +-- the current buffer or all open buffers (depending on `M.autocomplete_all_words`). -- If `buffer.auto_c_ignore_case` is `true`, completions are not case-sensitive. -- @see buffer.word_chars -- @see autocomplete @@ -698,20 +682,23 @@ end local api_docs --- --- 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`. --- @param pos Optional position of the symbol to show documentation for. If --- omitted, the caret position is used. --- @param ignore_case Optional flag that indicates whether or not to search --- API files case-insensitively for symbols. The default value is `false`. +-- @param pos Optional position of the symbol to show documentation for. If omitted, the caret +-- position is used. +-- @param ignore_case Optional flag that indicates whether or not to search API files +-- case-insensitively for symbols. The default value is `false`. -- @name show_documentation -- @see api_files -- @see buffer.word_chars function M.show_documentation(pos, ignore_case) - if view:call_tip_active() then events.emit(events.CALL_TIP_CLICK) return end + if view:call_tip_active() then + events.emit(events.CALL_TIP_CLICK) + return + end local api_files = M.api_files[buffer:get_lexer(true)] if not api_files then return end if not assert_type(pos, 'number/nil', 1) then pos = buffer.current_pos end @@ -739,8 +726,8 @@ function M.show_documentation(pos, ignore_case) ::continue:: end end - -- Search backwards for an open function call and show API documentation for - -- that function as well. + -- Search backwards for an open function call and show API documentation for that function + -- as well. while s > 1 and buffer.char_at[s] ~= 40 do s = s - 1 end -- '(' e = buffer:brace_match(s, 0) if s > 1 and (e == -1 or e >= pos) then diff --git a/modules/textadept/file_types.lua b/modules/textadept/file_types.lua index bd5a8a04..ac9c88f9 100644 --- a/modules/textadept/file_types.lua +++ b/modules/textadept/file_types.lua @@ -7,8 +7,8 @@ local M = {} -- Handles file type detection for Textadept. -- @field _G.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. @@ -17,10 +17,11 @@ module('textadept.file_types')]] -- Events. events.LEXER_LOADED = 'lexer_loaded' +-- LuaFormatter off --- -- 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. -- @class table -- @name extensions M.extensions = {--[[Actionscript]]as='actionscript',asc='actionscript',--[[Ada]]adb='ada',ads='ada',--[[ANTLR]]g='antlr',g4='antlr',--[[APDL]]ans='apdl',inp='apdl',mac='apdl',--[[APL]]apl='apl',--[[Applescript]]applescript='applescript',--[[ASM]]asm='asm',ASM='asm',s='asm',S='asm',--[[ASP]]asa='asp',asp='asp',hta='asp',--[[AutoIt]]au3='autoit',a3x='autoit',--[[AWK]]awk='awk',--[[Batch]]bat='batch',cmd='batch',--[[BibTeX]]bib='bibtex',--[[Boo]]boo='boo',--[[C#]]cs='csharp',--[[C/C++]]c='ansi_c',cc='cpp',C='ansi_c',cpp='cpp',cxx='cpp',['c++']='cpp',h='cpp',hh='cpp',hpp='cpp',hxx='cpp',['h++']='cpp',--[[ChucK]]ck='chuck',--[[Clojure]]clj='clojure',cljs='clojure',cljc='clojure',edn='clojure',--[[CMake]]cmake='cmake',['cmake.in']='cmake',ctest='cmake',['ctest.in']='cmake',--[[CoffeeScript]]coffee='coffeescript',--[[Crystal]]cr='crystal',--[[CSS]]css='css',--[[CUDA]]cu='cuda',cuh='cuda',--[[D]]d='dmd',di='dmd',--[[Dart]]dart='dart',--[[Desktop]]desktop='desktop',--[[diff]]diff='diff',patch='diff',--[[Dockerfile]]Dockerfile='dockerfile',--[[dot]]dot='dot',--[[Eiffel]]e='eiffel',eif='eiffel',--[[Elixir]]ex='elixir',exs='elixir',--[[Elm]]elm='elm',--[[Erlang]]erl='erlang',hrl='erlang',--[[F#]]fs='fsharp',--[[Fantom]]fan='fantom',--[[Faust]]dsp='faust',--[[Fennel]]fnl='fennel',--[[Fish]]fish='fish',--[[Forth]]forth='forth',frt='forth',--[[Fortran]]f='fortran',['for']='fortran',ftn='fortran',fpp='fortran',f77='fortran',f90='fortran',f95='fortran',f03='fortran',f08='fortran',--[[fstab]]fstab='fstab',--[[Gap]]g='gap',gd='gap',gi='gap',gap='gap',--[[Gettext]]po='gettext',pot='gettext',--[[Gherkin]]feature='gherkin',--[[GLSL]]glslf='glsl',glslv='glsl',--[[GNUPlot]]dem='gnuplot',plt='gnuplot',--[[Go]]go='go',--[[Groovy]]groovy='groovy',gvy='groovy',--[[Gtkrc]]gtkrc='gtkrc',--[[Haskell]]hs='haskell',--[[HTML]]htm='html',html='html',shtm='html',shtml='html',xhtml='html',vue='html',--[[Icon]]icn='icon',--[[IDL]]idl='idl',odl='idl',--[[Inform]]inf='inform',ni='inform',--[[ini]]cfg='ini',cnf='ini',inf='ini',ini='ini',reg='ini',--[[Io]]io='io_lang',--[[Java]]bsh='java',java='java',--[[Javascript]]js='javascript',jsfl='javascript',--[[jq]]jq='jq',--[[JSON]]json='json',--[[JSP]]jsp='jsp',--[[Julia]]jl='julia',--[[LaTeX]]bbl='latex',dtx='latex',ins='latex',ltx='latex',tex='latex',sty='latex',--[[Ledger]]ledger='ledger',journal='ledger',--[[LESS]]less='less',--[[LilyPond]]lily='lilypond',ly='lilypond',--[[Lisp]]cl='lisp',el='lisp',lisp='lisp',lsp='lisp',--[[Literate Coffeescript]]litcoffee='litcoffee',--[[Logtalk]]lgt='logtalk',--[[Lua]]lua='lua',--[[Makefile]]GNUmakefile='makefile',iface='makefile',mak='makefile',makefile='makefile',Makefile='makefile',--[[Man]]['1']='man',['2']='man',['3']='man',['4']='man',['5']='man',['6']='man',['7']='man',['8']='man',['9']='man',['1x']='man',['2x']='man',['3x']='man',['4x']='man',['5x']='man',['6x']='man',['7x']='man',['8x']='man',['9x']='man',--[[Markdown]]md='markdown',--[[Meson]]['meson.build']='meson',--[[MoonScript]]moon='moonscript',--[[Myrddin]]myr='myrddin',--[[Nemerle]]n='nemerle',--[[Networkd]]link='networkd',network='networkd',netdev='networkd',--[[Nim]]nim='nim',--[[NSIS]]nsh='nsis',nsi='nsis',nsis='nsis',--[[Objective C]]m='objective_c',mm='objective_c',objc='objective_c',--[[OCaml]]caml='caml',ml='caml',mli='caml',mll='caml',mly='caml',--[[Pascal]]dpk='pascal',dpr='pascal',p='pascal',pas='pascal',--[[Perl]]al='perl',perl='perl',pl='perl',pm='perl',pod='perl',--[[PHP]]inc='php',php='php',php3='php',php4='php',phtml='php',--[[PICO-8]]p8='pico8',--[[Pike]]pike='pike',pmod='pike',--[[PKGBUILD]]PKGBUILD='pkgbuild',--[[Pony]]pony='pony',--[[Postscript]]eps='ps',ps='ps',--[[PowerShell]]ps1='powershell',--[[Prolog]]prolog='prolog',--[[Properties]]props='props',properties='props',--[[Protobuf]]proto='protobuf',--[[Pure]]pure='pure',--[[Python]]sc='python',py='python',pyw='python',--[[R]]R='rstats',Rout='rstats',Rhistory='rstats',Rt='rstats',['Rout.save']='rstats',['Rout.fail']='rstats',S='rstats',--[[Reason]]re='reason',--[[REBOL]]r='rebol',reb='rebol',--[[reST]]rst='rest',--[[Rexx]]orx='rexx',rex='rexx',--[[RHTML]]erb='rhtml',rhtml='rhtml',--[[RouterOS]]rsc='routeros',--[[Ruby]]Rakefile='ruby',rake='ruby',rb='ruby',rbw='ruby',--[[Rust]]rs='rust',--[[Sass CSS]]sass='sass',scss='sass',--[[Scala]]scala='scala',--[[Scheme]]sch='scheme',scm='scheme',--[[Shell]]bash='bash',bashrc='bash',bash_profile='bash',configure='bash',csh='bash',ksh='bash',mksh='bash',sh='bash',zsh='bash',--[[Smalltalk]]changes='smalltalk',st='smalltalk',sources='smalltalk',--[[SML]]sml='sml',fun='sml',sig='sml',--[[SNOBOL4]]sno='snobol4',SNO='snobol4',--[[Spin]]spin='spin',--[[SQL]]ddl='sql',sql='sql',--[[Systemd]]automount='systemd',device='systemd',mount='systemd',path='systemd',scope='systemd',service='systemd',slice='systemd',socket='systemd',swap='systemd',target='systemd',timer='systemd',--[[TaskPaper]]taskpaper='taskpaper',--[[Tcl]]tcl='tcl',tk='tcl',--[[Texinfo]]texi='texinfo',--[[TOML]]toml='toml',--[[Txt2tags]]t2t='txt2tags',--[[TypeScript]]ts='typescript',--[[Vala]]vala='vala',--[[vCard]]vcf='vcard',vcard='vcard',--[[Verilog]]v='verilog',ver='verilog',--[[VHDL]]vh='vhdl',vhd='vhdl',vhdl='vhdl',--[[Visual Basic]]asa='vb',bas='vb',cls='vb',ctl='vb',dob='vb',dsm='vb',dsr='vb',frm='vb',pag='vb',vb='vb',vba='vb',vbs='vb',--[[WSF]]wsf='wsf',--[[XML]]dtd='xml',svg='xml',xml='xml',xsd='xml',xsl='xml',xslt='xml',xul='xml',--[[Xs]]xs='xs',xsin='xs',xsrc='xs',--[[Xtend]]xtend='xtend',--[[YAML]]yaml='yaml',yml='yaml',--[[Zig]]zig='zig'} @@ -31,6 +32,7 @@ M.extensions = {--[[Actionscript]]as='actionscript',asc='actionscript',--[[Ada]] -- @class table -- @name patterns M.patterns = {['^#!.+[/ ][gm]?awk']='awk',['^#!.+[/ ]lua']='lua',['^#!.+[/ ]octave']='matlab',['^#!.+[/ ]perl']='perl',['^#!.+[/ ]php']='php',['^#!.+[/ ]python']='python',['^#!.+[/ ]ruby']='ruby',['^#!.+[/ ]bash']='bash',['^#!.+/m?ksh']='bash',['^#!.+/sh']='bash',['^%s*class%s+%S+%s*<%s*ApplicationController']='rails',['^%s*class%s+%S+%s*<%s*ActionController::Base']='rails',['^%s*class%s+%S+%s*<%s*ActiveRecord::Base']='rails',['^%s*class%s+%S+%s*<%s*ActiveRecord::Migration']='rails',['^%s*<%?xml%s']='xml',['^#cloud%-config']='yaml'} +-- LuaFormatter on local GETLEXERLANGUAGE = _SCINTILLA.properties.lexer_language[1] -- LuaDoc is in core/.buffer.luadoc. @@ -39,16 +41,13 @@ local function get_lexer(buffer, current) return current and name:match('[^/]+$') or name:match('^[^/]+') end --- Attempts to detect the language based on a buffer's first line of text or --- that buffer's filename. +-- Attempts to detect the language based on a buffer's first line of text or that buffer's filename. -- @param buffer The buffer to detect the language of. -- @return lexer name or nil local function detect_language(buffer) local line = buffer:get_line(1) -- Detect from first line. - for patt, lexer_name in pairs(M.patterns) do - if line:find(patt) then return lexer_name end - end + for patt, lexer_name in pairs(M.patterns) do if line:find(patt) then return lexer_name end end -- Detect from file extension. return buffer.filename and M.extensions[buffer.filename:match('[^/\\.]+$')] end @@ -75,18 +74,15 @@ local function set_lexer(buffer, name) end -- Gives new buffers lexer-specific functions. -events.connect(events.BUFFER_NEW, function() - buffer.get_lexer, buffer.set_lexer = get_lexer, set_lexer -end, 1) +events.connect(events.BUFFER_NEW, + function() buffer.get_lexer, buffer.set_lexer = get_lexer, set_lexer end, 1) -- Auto-detect lexer on file open or save as. events.connect(events.FILE_OPENED, function() buffer:set_lexer() end) -events.connect(events.FILE_AFTER_SAVE, function(_, saved_as) - if saved_as then buffer:set_lexer() end -end) +events.connect(events.FILE_AFTER_SAVE, + function(_, saved_as) if saved_as then buffer:set_lexer() end end) --- Restores the buffer's lexer, primarily for the side-effect of emitting --- `events.LEXER_LOADED`. +-- Restores the buffer's lexer, primarily for the side-effect of emitting `events.LEXER_LOADED`. local function restore_lexer() buffer:set_lexer(buffer._lexer) end events.connect(events.BUFFER_AFTER_SWITCH, restore_lexer, 1) events.connect(events.VIEW_AFTER_SWITCH, restore_lexer) @@ -100,9 +96,7 @@ local LEXERNAMES = _SCINTILLA.functions.property_names[1] -- @name select_lexer function M.select_lexer() local lexers = {} - for name in buffer:private_lexer_call(LEXERNAMES):gmatch('[^\n]+') do - lexers[#lexers + 1] = name - end + for name in buffer:private_lexer_call(LEXERNAMES):gmatch('[^\n]+') do lexers[#lexers + 1] = name end local button, i = ui.dialogs.filteredlist{ title = _L['Select Lexer'], columns = _L['Name'], items = lexers } diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua index 31624503..0d90885f 100644 --- a/modules/textadept/find.lua +++ b/modules/textadept/find.lua @@ -9,14 +9,12 @@ local M = ui.find -- The text in the "Find" entry. -- @field 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. -- @field match_case (bool) -- Match search text case sensitively. -- The default value is `false`. -- @field 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`. -- @field regex (bool) -- Interpret search text as a Regular Expression. @@ -60,23 +58,21 @@ local M = ui.find -- @field active (boolean) -- Whether or not the Find & Replace pane is active. -- @field 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`. -- @field INDIC_FIND (number) -- The find results highlight indicator number. -- @field _G.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. -- @field _G.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. module('ui.find')]] local _L = _L @@ -97,31 +93,29 @@ M.INDIC_FIND = _SCINTILLA.next_indic_number() local find_events = {'find_result_found', 'find_wrapped'} for _, v in ipairs(find_events) do events[v:upper()] = v end --- When finding in files, note the current view since results are shown in a --- split view. Jumping between results should be done in the original view. +-- When finding in files, note the current view since results are shown in a split view. Jumping +-- between results should be done in the original view. local preferred_view --- -- 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. -- @class table -- @name find_in_files_filters -- @see find_in_files M.find_in_files_filters = {} --- Keep track of find text and found text so that "replace all" works as --- expected during a find session ("replace all" with selected text normally --- does "replace in selection"). Also track find text for incremental find (if --- text has changed, the user is still typing; if text is the same, the user --- clicked "Find Next" or "Find Prev"). Keep track of repl_text for --- non-"In files" in order to restore it from filter text as necessary. +-- Keep track of find text and found text so that "replace all" works as expected during a find +-- session ("replace all" with selected text normally does "replace in selection"). Also track +-- find text for incremental find (if text has changed, the user is still typing; if text is +-- the same, the user clicked "Find Next" or "Find Prev"). Keep track of repl_text for non-"In +-- files" in order to restore it from filter text as necessary. local find_text, found_text, repl_text = nil, nil, ui.find.replace_entry_text -- Returns a reasonable initial directory for use with Find in Files. local function ff_dir() - return io.get_project_root() or (buffer.filename or ''):match('^.+[/\\]') or - lfs.currentdir() + return io.get_project_root() or (buffer.filename or ''):match('^.+[/\\]') or lfs.currentdir() end local orig_focus = M.focus @@ -139,22 +133,21 @@ function M.focus(options) if M.in_files then if not already_in_files then repl_text = M.replace_entry_text end -- save local filter = M.find_in_files_filters[ff_dir()] or lfs.default_filter - M.replace_entry_text = type(filter) == 'string' and filter or - table.concat(filter, ',') + M.replace_entry_text = type(filter) == 'string' and filter or table.concat(filter, ',') elseif M.replace_entry_text ~= repl_text then M.replace_entry_text = repl_text -- restore end orig_focus() end --- Returns a bit-mask of search flags to use in Scintilla search functions based --- on the checkboxes in the find box. +-- Returns a bit-mask of search flags to use in Scintilla search functions based on the checkboxes +-- in the find box. -- The "Find in Files" flag is unused by Scintilla, but used by Textadept. -- @return search flag bit-mask local function get_flags() return (M.match_case and buffer.FIND_MATCHCASE or 0) | - (M.whole_word and buffer.FIND_WHOLEWORD or 0) | - (M.regex and buffer.FIND_REGEXP or 0) | (M.in_files and 1 << 31 or 0) + (M.whole_word and buffer.FIND_WHOLEWORD or 0) | (M.regex and buffer.FIND_REGEXP or 0) | + (M.in_files and 1 << 31 or 0) end -- Returns whether or not the given buffer is a files found buffer. @@ -174,20 +167,22 @@ local incremental_orig_pos -- Finds and selects text in the current buffer. -- @param text The text to find. -- @param next Flag indicating whether or not the search direction is forward. --- @param flags Search flags. This is a bit-mask of 4 flags: --- `buffer.FIND_MATCHCASE`, `buffer.FIND_WHOLEWORD`, `buffer.FIND_REGEXP`, and --- 1 << 31 (in files), each joined with binary OR. --- If `nil`, this is determined based on the checkboxes in the find box. +-- @param flags Search flags. This is a bit-mask of 4 flags: `buffer.FIND_MATCHCASE`, +-- `buffer.FIND_WHOLEWORD`, `buffer.FIND_REGEXP`, and 1 << 31 (in files), each joined with +-- binary OR. If `nil`, this is determined based on the checkboxes in the find box. -- @param no_wrap Flag indicating whether or not the search will not wrap. --- @param wrapped Utility flag indicating whether or not the search has wrapped --- for displaying useful statusbar information. This flag is used and set --- internally, and should not be set otherwise. +-- @param wrapped Utility flag indicating whether or not the search has wrapped for displaying +-- useful statusbar information. This flag is used and set internally, and should not be +-- set otherwise. -- @return position of the found text or `-1` local function find(text, next, flags, no_wrap, wrapped) -- Note: cannot use assert_type(), as event errors are handled silently. if text == '' then return end if not flags then flags = get_flags() end - if flags >= 1 << 31 then M.find_in_files() return end -- not performed here + if flags >= 1 << 31 then + M.find_in_files() -- performed here + return + end local first_visible_line = view.first_visible_line -- for 'no results found' if not is_ff_buf(buffer) then clear_highlighted_matches() end @@ -205,8 +200,8 @@ local function find(text, next, flags, no_wrap, wrapped) incremental_orig_pos = nil end - -- If text is selected, assume it is from the current search and move the - -- caret appropriately for the next search. + -- If text is selected, assume it is from the current search and move the caret appropriately + -- for the next search. buffer:goto_pos(next and buffer.selection_end or buffer.selection_start) -- Scintilla search. @@ -256,45 +251,39 @@ events.connect(events.FIND_RESULT_FOUND, function(text) if s == buffer.current_pos then current = count end end ui.statusbar_text = string.format('%s %d/%d', _L['Match'], current, count) - -- For regex searches, `buffer.tag` was clobbered. It needs to be filled in - -- again for any subsequent replace operations that need it. + -- For regex searches, `buffer.tag` was clobbered. It needs to be filled in again for any + -- subsequent replace operations that need it. if ui.find.regex then buffer:set_target_range(buffer.selection_start, buffer.length + 1) buffer:search_in_target(text) end end) -events.connect( - events.FIND_WRAPPED, function() ui.statusbar_text = _L['Search wrapped'] end) +events.connect(events.FIND_WRAPPED, function() ui.statusbar_text = _L['Search wrapped'] end) --- --- 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. --- @param dir Optional directory path to search. If `nil`, the user is prompted --- for one. --- @param 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`. +-- `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. +-- @param dir Optional directory path to search. If `nil`, the user is prompted for one. +-- @param 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 find_in_files_filters -- @name find_in_files function M.find_in_files(dir, filter) if not assert_type(dir, 'string/nil', 1) then dir = ui.dialogs.fileselect{ - title = _L['Select Directory'], select_only_directories = true, - with_directory = ff_dir() + title = _L['Select Directory'], select_only_directories = true, with_directory = ff_dir() } if not dir then return end end @@ -310,10 +299,10 @@ function M.find_in_files(dir, filter) if buffer._type ~= _L['[Files Found Buffer]'] then preferred_view = view end ui.silent_print = false - ui._print(_L['[Files Found Buffer]'], string.format( - '%s %s\n%s %s\n%s %s', _L['Find:']:gsub('_', ''), M.find_entry_text, - _L['Directory:'], dir, _L['Filter:']:gsub('_', ''), - type(filter) == 'string' and filter or table.concat(filter, ','))) + ui._print(_L['[Files Found Buffer]'], + string.format('%s %s\n%s %s\n%s %s', _L['Find:']:gsub('_', ''), M.find_entry_text, + _L['Directory:'], dir, _L['Filter:']:gsub('_', ''), + type(filter) == 'string' and filter or table.concat(filter, ','))) buffer.indicator_current = M.INDIC_FIND -- Determine which files to search. @@ -342,18 +331,15 @@ function M.find_in_files(dir, filter) found = true if binary == nil then binary = buffer:text_range(1, 65536):find('\0') end if binary then - _G.buffer:add_text(string.format( - '%s:1:%s\n', utf8_filenames[i], _L['Binary file matches.'])) + _G.buffer:add_text(string.format('%s:1:%s\n', utf8_filenames[i], _L['Binary file matches.'])) break end local line_num = buffer:line_from_position(buffer.target_start) local line = buffer:get_line(line_num) - _G.buffer:add_text( - string.format('%s:%d:%s', utf8_filenames[i], line_num, line)) - local pos = _G.buffer.current_pos - #line + - buffer.target_start - buffer:position_from_line(line_num) - _G.buffer:indicator_fill_range( - pos, buffer.target_end - buffer.target_start) + _G.buffer:add_text(string.format('%s:%d:%s', utf8_filenames[i], line_num, line)) + local pos = _G.buffer.current_pos - #line + buffer.target_start - + buffer:position_from_line(line_num) + _G.buffer:indicator_fill_range(pos, buffer.target_end - buffer.target_start) if not line:find('\n$') then _G.buffer:add_text('\n') end buffer:set_target_range(buffer.target_end, buffer.length + 1) end @@ -365,36 +351,33 @@ function M.find_in_files(dir, filter) return i * 100 / #filenames, utf8_filenames[i] end) buffer:close(true) -- temporary buffer - ui._print( - _L['[Files Found Buffer]'], - stopped and _L['Find in Files aborted'] .. '\n' or - not found and _L['No results found'] .. '\n' or '') + local status = stopped and _L['Find in Files aborted'] or not found and _L['No results found'] + ui._print(_L['[Files Found Buffer]'], status and status .. '\n' or '') end local P, V, C, upper, lower = lpeg.P, lpeg.V, lpeg.C, string.upper, string.lower local esc = {b = '\b', f = '\f', n = '\n', r = '\r', t = '\t', v = '\v'} local re_patt = lpeg.Cs(P{ (V('text') + V('u') + V('l') + V('U') + V('L') + V('esc'))^1, - text = (1 - '\\' * lpeg.S('uUlLEbfnrtv'))^1, + text = (1 - '\\' * lpeg.S('uUlLEbfnrtv'))^1, -- LuaFormatter u = '\\u' * C(1) / upper, l = '\\l' * C(1) / lower, U = P('\\U') / '' * (V('text') / upper + V('u') + V('l'))^0 * V('E')^-1, - L = P('\\L') / '' * (V('text') / lower + V('u') + V('l'))^0 * V('E')^-1, + L = P('\\L') / '' * (V('text') / lower + V('u') + V('l'))^0 * V('E')^-1, -- LuaFormatter E = P('\\E') / '', esc = '\\' * C(1) / esc }) -- Returns string *text* with the following sequences unescaped: -- * "\uXXXX" sequences replaced with the equivalent UTF-8 character. --- * "\d" sequences replaced with the text of capture number *d* from the --- regular expression (or the entire match for *d* = 0). --- * "\U" and "\L" sequences convert everything up to the next "\U", "\L", or --- "\E" to uppercase and lowercase, respectively. --- * "\u" and "\l" sequences convert the next character to uppercase and --- lowercase, respectively. They may appear within "\U" and "\L" constructs. +-- * "\d" sequences replaced with the text of capture number *d* from the regular expression +-- (or the entire match for *d* = 0). +-- * "\U" and "\L" sequences convert everything up to the next "\U", "\L", or "\E" to uppercase +-- and lowercase, respectively. +-- * "\u" and "\l" sequences convert the next character to uppercase and lowercase, respectively. +-- They may appear within "\U" and "\L" constructs. -- @param text String text to unescape. -- @return unescaped text local function unescape(text) - text = text:gsub('%f[\\]\\u(%x%x%x%x)', function(code) - return utf8.char(tonumber(code, 16)) - end):gsub('\\0', buffer.target_text):gsub('\\(%d)', buffer.tag) + text = text:gsub('%f[\\]\\u(%x%x%x%x)', function(code) return utf8.char(tonumber(code, 16)) end) + :gsub('\\0', buffer.target_text):gsub('\\(%d)', buffer.tag) return re_patt:match(text) or text end @@ -408,14 +391,13 @@ end) local INDIC_REPLACE = _SCINTILLA.next_indic_number() -- Replaces all found text in the current buffer (ignores "Find in Files"). --- If any text is selected (other than text just found), only found text in that --- selection is replaced. +-- If any text is selected (other than text just found), only found text in that selection +-- is replaced. events.connect(events.REPLACE_ALL, function(ftext, rtext) if ftext == '' then return end local count = 0 local s, e = buffer.selection_start, buffer.selection_end - local replace_in_sel = - s ~= e and (ftext ~= find_text or buffer:get_sel_text() ~= found_text) + local replace_in_sel = s ~= e and (ftext ~= find_text or buffer:get_sel_text() ~= found_text) if replace_in_sel then buffer.indicator_current = INDIC_REPLACE buffer:indicator_fill_range(e, 1) @@ -427,8 +409,8 @@ events.connect(events.REPLACE_ALL, function(ftext, rtext) buffer:begin_undo_action() buffer.search_flags = get_flags() buffer:set_target_range(not replace_in_sel and 1 or s, buffer.length + 1) - while buffer:search_in_target(ftext) ~= -1 and (not replace_in_sel or - buffer.target_end <= buffer:indicator_end(INDIC_REPLACE, s) or EOF) do + while buffer:search_in_target(ftext) ~= -1 and + (not replace_in_sel or buffer.target_end <= buffer:indicator_end(INDIC_REPLACE, s) or EOF) do if buffer.target_start == buffer.target_end then break end -- prevent loops buffer:replace_target(not M.regex and rtext or unescape(rtext)) count = count + 1 @@ -446,30 +428,39 @@ events.connect(events.REPLACE_ALL, function(ftext, rtext) end) --- --- 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*. --- @param line_num Optional line number in the files found buffer that contains --- the search result to go to. This parameter may be omitted completely. --- @param next Optional flag indicating whether to go to the next search result --- or the previous one. Only applicable when *line_num* is `nil`. +-- 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*. +-- @param line_num Optional line number in the files found buffer that contains the search +-- result to go to. This parameter may be omitted completely. +-- @param next Optional flag indicating whether to go to the next search result or the previous +-- one. Only applicable when *line_num* is `nil`. -- @name goto_file_found function M.goto_file_found(line_num, next) if type(line_num) == 'boolean' then line_num, next = nil, line_num end local ff_view, ff_buf = nil, nil for i = 1, #_VIEWS do - if is_ff_buf(_VIEWS[i].buffer) then ff_view = _VIEWS[i] break end + if is_ff_buf(_VIEWS[i].buffer) then + ff_view = _VIEWS[i] + break + end end for i = 1, #_BUFFERS do - if is_ff_buf(_BUFFERS[i]) then ff_buf = _BUFFERS[i] break end + if is_ff_buf(_BUFFERS[i]) then + ff_buf = _BUFFERS[i] + break + end end if not ff_view and not ff_buf then return end - if ff_view then ui.goto_view(ff_view) else view:goto_buffer(ff_buf) end + if ff_view then + ui.goto_view(ff_view) + else + view:goto_buffer(ff_buf) + end - -- If no line number was given, find the next search result, wrapping as - -- necessary. + -- If no line number was given, find the next search result, wrapping as necessary. if not assert_type(line_num, 'number/nil', 1) and next ~= nil then - if next then buffer:line_end() else buffer:home() end + buffer[next and 'line_end' or 'home'](buffer) buffer:search_anchor() local f = next and buffer.search_next or buffer.search_prev local pos = f(buffer, buffer.FIND_REGEXP, '^.+:\\d+:.+$') @@ -487,7 +478,8 @@ function M.goto_file_found(line_num, next) local line = buffer:get_cur_line() local utf8_filename, pos utf8_filename, line_num, pos = line:match('^(.+):(%d+):()') - if not utf8_filename then return else line_num = tonumber(line_num) end + if not utf8_filename then return end + line_num = tonumber(line_num) textadept.editing.select_line() pos = buffer.selection_start + pos - 1 -- absolute pos of result text on line local s = buffer:indicator_end(M.INDIC_FIND, buffer.selection_start) @@ -508,9 +500,8 @@ events.connect(events.KEYPRESS, function(code) M.goto_file_found(buffer:line_from_position(buffer.current_pos)) return true end) -events.connect(events.DOUBLE_CLICK, function(_, line) - if is_ff_buf(buffer) then M.goto_file_found(line) end -end) +events.connect(events.DOUBLE_CLICK, + function(_, line) if is_ff_buf(buffer) then M.goto_file_found(line) end end) --[[ The functions below are Lua C functions. diff --git a/modules/textadept/history.lua b/modules/textadept/history.lua index 0c6113e4..da9f5885 100644 --- a/modules/textadept/history.lua +++ b/modules/textadept/history.lua @@ -4,14 +4,13 @@ local M = {} --[[ This comment is for LuaDoc. --- --- 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. -- @field minimum_line_distance (number) -- The minimum number of lines between distinct history records. -- The default value is `3`. @@ -24,14 +23,15 @@ M.minimum_line_distance = 3 M.maximum_history_size = 100 -- Map of views to their history records. --- Each record has a `pos` field that points to the current history position in --- the associated view. +-- Each record has a `pos` field that points to the current history position in the associated view. -- @class table -- @name view_history -local view_history = setmetatable({}, {__index = function(t, view) - t[view] = {pos = 0} - return t[view] -end}) +local view_history = setmetatable({}, { + __index = function(t, view) + t[view] = {pos = 0} + return t[view] + end +}) -- Listens for text insertion and deletion events and records their locations. events.connect(events.MODIFIED, function(position, mod, text, length) @@ -50,8 +50,7 @@ events.connect(events.MODIFIED, function(position, mod, text, length) M.record(nil, buffer:line_from_position(position), buffer.column[position]) end) --- Do not record positions during buffer switches when jumping backwards or --- forwards. +-- Do not record positions during buffer switches when jumping backwards or forwards. local jumping = false -- Jumps to the given record in the current view's history. @@ -64,8 +63,7 @@ local function jump(record) else for _, buffer in ipairs(_BUFFERS) do if buffer.filename == filename or buffer._type == filename or - not buffer.filename and not buffer._type and - filename == _L['Untitled'] then + (not buffer.filename and not buffer._type and filename == _L['Untitled']) then view:goto_buffer(buffer) break end @@ -84,12 +82,15 @@ function M.back() local record = history[history.pos] local line = buffer:line_from_position(buffer.current_pos) if buffer.filename ~= record.filename and buffer._type ~= record.filename or - math.abs(record.line - line) > M.minimum_line_distance then - -- When navigated away from the most recent record, and if that record is - -- not a soft record, jump back to it first, then navigate backwards. - if not record.soft then jump(record) return end - -- Otherwise, update the soft record with the current position and - -- immediately navigate backwards. + math.abs(record.line - line) > M.minimum_line_distance then + -- When navigated away from the most recent record, and if that record is not a soft record, + -- jump back to it first, then navigate backwards. + if not record.soft then + jump(record) + return + end + -- Otherwise, update the soft record with the current position and immediately navigate + -- backwards. M.record(record.filename, nil, nil, record.soft) end if history.pos > 1 then history.pos = history.pos - 1 end @@ -110,15 +111,14 @@ end --- -- Records the given location in the current view's history. --- @param filename Optional string filename, buffer type, or identifier of the --- buffer to store. If `nil`, uses the current buffer. --- @param line Optional Integer line number to store. If `nil`, uses the current --- line. --- @param column Optional integer column number on line *line* to store. If --- `nil`, uses the current column. --- @param 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`. +-- @param filename Optional string filename, buffer type, or identifier of the buffer to store. If +-- `nil`, uses the current buffer. +-- @param line Optional Integer line number to store. If `nil`, uses the current line. +-- @param column Optional integer column number on line *line* to store. If `nil`, uses the +-- current column. +-- @param 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`. -- @name record function M.record(filename, line, column, soft) if not assert_type(filename, 'string/nil', 1) then @@ -127,17 +127,14 @@ function M.record(filename, line, column, soft) if not assert_type(line, 'number/nil', 2) then line = buffer:line_from_position(buffer.current_pos) end - if not assert_type(column, 'number/nil', 3) then - column = buffer.column[buffer.current_pos] - end + if not assert_type(column, 'number/nil', 3) then column = buffer.column[buffer.current_pos] end local history = view_history[view] if #history > 0 then local record = history[history.pos] if filename == record.filename and - (math.abs(record.line - line) <= M.minimum_line_distance or - record.soft) then - -- If the most recent record is close enough (distance-wise), or if that - -- record is a soft record, update it instead of recording a new one. + (math.abs(record.line - line) <= M.minimum_line_distance or record.soft) then + -- If the most recent record is close enough (distance-wise), or if that record is a soft + -- record, update it instead of recording a new one. record.line, record.column = line, column record.soft = soft and record.soft return @@ -146,17 +143,13 @@ function M.record(filename, line, column, soft) if history.pos < #history then for i = history.pos + 1, #history do history[i] = nil end -- clear forward end - history[#history + 1] = { - filename = filename, line = line, column = column, soft = soft - } + history[#history + 1] = {filename = filename, line = line, column = column, soft = soft} if #history > M.maximum_history_size then table.remove(history, 1) end history.pos = #history end -- Softly record positions when switching between buffers. -local function record_switch() - if not jumping then M.record(nil, nil, nil, true) end -end +local function record_switch() if not jumping then M.record(nil, nil, nil, true) end end events.connect(events.BUFFER_BEFORE_SWITCH, record_switch) events.connect(events.BUFFER_AFTER_SWITCH, record_switch) events.connect(events.FILE_OPENED, record_switch) @@ -164,8 +157,6 @@ events.connect(events.FILE_OPENED, record_switch) --- -- Clears all view history. -- @name clear -function M.clear() - for view in pairs(view_history) do view_history[view] = {pos = 0} end -end +function M.clear() for view in pairs(view_history) do view_history[view] = {pos = 0} end end return M diff --git a/modules/textadept/init.lua b/modules/textadept/init.lua index 6ba747a0..d2bde80c 100644 --- a/modules/textadept/init.lua +++ b/modules/textadept/init.lua @@ -10,8 +10,8 @@ textadept = M -- forward declaration module('textadept')]] local modules = { - 'bookmarks', 'command_entry', 'editing', 'file_types', 'find', 'history', - 'macros', 'run', 'session', 'snippets', --[[need to be last]] 'menu', 'keys' + 'bookmarks', 'command_entry', 'editing', 'file_types', 'find', 'history', 'macros', 'run', + 'session', 'snippets', --[[need to be last]] 'menu', 'keys' } for _, name in ipairs(modules) do M[name] = require('textadept.' .. name) end M.command_entry, M.find = nil, nil -- ui.command_entry, ui.find diff --git a/modules/textadept/keys.lua b/modules/textadept/keys.lua index 5cae6988..b50503cb 100644 --- a/modules/textadept/keys.lua +++ b/modules/textadept/keys.lua @@ -5,214 +5,214 @@ local M = {} --[[ This comment is for LuaDoc. --- -- 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. -- @@ -251,13 +251,12 @@ module('textadept.keys')]] -- Key bindings available depend on your implementation of curses. -- -- For ncurses (Linux, macOS, BSD): --- * The only Control keys recognized are 'ctrl+a'-'ctrl+z', 'ctrl+ ', --- 'ctrl+\\', 'ctrl+]', 'ctrl+^', and 'ctrl+_'. +-- * The only Control keys recognized are 'ctrl+a'-'ctrl+z', 'ctrl+ ', 'ctrl+\\', 'ctrl+]', +-- 'ctrl+^', and 'ctrl+_'. -- * Control+Shift and Control+Meta+Shift keys are not recognized. -- * Modifiers for function keys F1-F12 are not recognized. -- For pdcurses (Win32): --- * Many Control+Symbol keys are not recognized, but most --- Control+Shift+Symbol keys are. +-- * Many Control+Symbol keys are not recognized, but most Control+Shift+Symbol keys are. -- * Ctrl+Meta+Symbol keys are not recognized. -- -- Unassigned keys (~ denotes keys reserved by the operating system): @@ -272,8 +271,7 @@ module('textadept.keys')]] -- Control, Meta, and 'a' = 'ctrl+meta+a' local _L = _L --- Returns the menu command associated with the '/'-separated string of menu --- labels. +-- Returns the menu command associated with the '/'-separated string of menu labels. -- Labels are automatically localized. -- @param labels Path to the menu command. -- @usage m('Edit/Select/Select in XML Tag') @@ -283,6 +281,7 @@ local function m(labels) return menu[2] end +-- LuaFormatter off -- Bindings for Linux/Win32, macOS, Terminal. local bindings = { -- File. @@ -311,15 +310,13 @@ local bindings = { [m('Edit/Delete Word')] = {'alt+del', 'ctrl+del', {'meta+del', 'meta+d'}}, [buffer.select_all] = {'ctrl+a', 'cmd+a', 'meta+a'}, [m('Edit/Match Brace')] = {'ctrl+m', 'ctrl+m', 'meta+m'}, - [m('Edit/Complete Word')] = - {'ctrl+\n', 'ctrl+esc', {'ctrl+meta+j', 'ctrl+\n'}}, + [m('Edit/Complete Word')] = {'ctrl+\n', 'ctrl+esc', {'ctrl+meta+j', 'ctrl+\n'}}, [textadept.editing.toggle_comment] = {'ctrl+/', 'ctrl+/', 'meta+/'}, [textadept.editing.transpose_chars] = {'ctrl+t', 'ctrl+t', 'ctrl+t'}, [textadept.editing.join_lines] = {'ctrl+J', 'ctrl+j', 'meta+j'}, [m('Edit/Filter Through')] = {'ctrl+|', 'cmd+|', 'ctrl+\\'}, -- Select. - [m('Edit/Select/Select between Matching Delimiters')] = - {'ctrl+M', 'ctrl+M', 'meta+M'}, + [m('Edit/Select/Select between Matching Delimiters')] = {'ctrl+M', 'ctrl+M', 'meta+M'}, [m('Edit/Select/Select between XML Tags')] = {'ctrl+<', 'cmd+<', 'meta+<'}, [m('Edit/Select/Select in XML Tag')] = {'ctrl+>', 'cmd+>', nil}, [textadept.editing.select_word] = {'ctrl+D', 'cmd+D', 'meta+W'}, @@ -335,10 +332,8 @@ local bindings = { [m('Edit/Selection/Enclose in Parentheses')] = {'alt+(', 'ctrl+(', 'meta+)'}, [m('Edit/Selection/Enclose in Brackets')] = {'alt+[', 'ctrl+[', 'meta+]'}, [m('Edit/Selection/Enclose in Braces')] = {'alt+{', 'ctrl+{', 'meta+}'}, - [buffer.move_selected_lines_up] = - {'ctrl+shift+up', 'ctrl+shift+up', 'ctrl+shift+up'}, - [buffer.move_selected_lines_down] = - {'ctrl+shift+down', 'ctrl+shift+down', 'ctrl+shift+down'}, + [buffer.move_selected_lines_up] = {'ctrl+shift+up', 'ctrl+shift+up', 'ctrl+shift+up'}, + [buffer.move_selected_lines_down] = {'ctrl+shift+down', 'ctrl+shift+down', 'ctrl+shift+down'}, -- History. [textadept.history.back] = {'alt+,', 'ctrl+,', 'meta+,'}, [textadept.history.forward] = {'alt+.', 'ctrl+.', 'meta+.'}, @@ -385,11 +380,9 @@ local bindings = { [textadept.macros.record] = {'f9', 'f9', 'f9'}, [textadept.macros.play] = {'shift+f9', 'shift+f9', 'f10'}, -- Quick Open. - [m('Tools/Quick Open/Quickly Open User Home')] = - {'ctrl+u', 'cmd+u', 'ctrl+u'}, + [m('Tools/Quick Open/Quickly Open User Home')] = {'ctrl+u', 'cmd+u', 'ctrl+u'}, -- TODO: m('Tools/Quickly Open Textadept Home') - [m('Tools/Quick Open/Quickly Open Current Directory')] = - {'ctrl+alt+O', 'ctrl+cmd+O', 'meta+O'}, + [m('Tools/Quick Open/Quickly Open Current Directory')] = {'ctrl+alt+O', 'ctrl+cmd+O', 'meta+O'}, [io.quick_open] = {'ctrl+alt+P', 'ctrl+cmd+P', 'ctrl+meta+p'}, -- Snippets. [textadept.snippets.select] = {'ctrl+K', 'shift+alt+\t', 'meta+K'}, @@ -399,8 +392,7 @@ local bindings = { [m('Tools/Snippets/Complete Trigger Word')] = {'ctrl+k', 'alt+\t', 'meta+k'}, -- Other. [m('Tools/Complete Symbol')] = {'ctrl+ ', 'alt+esc', 'ctrl+ '}, - [textadept.editing.show_documentation] = - {'ctrl+h', 'ctrl+h', {'meta+h', 'meta+H'}}, + [textadept.editing.show_documentation] = {'ctrl+h', 'ctrl+h', {'meta+h', 'meta+H'}}, [m('Tools/Show Style')] = {'ctrl+i', 'cmd+i', 'meta+I'}, -- Buffer. @@ -412,8 +404,7 @@ local bindings = { -- TODO: m('Buffer/Indentation/Tab width: 3') -- TODO: m('Buffer/Indentation/Tab width: 4') -- TODO: m('Buffer/Indentation/Tab width: 8') - [m('Buffer/Indentation/Toggle Use Tabs')] = - {'ctrl+alt+T', 'ctrl+T', {'meta+t', 'meta+T'}}, + [m('Buffer/Indentation/Toggle Use Tabs')] = {'ctrl+alt+T', 'ctrl+T', {'meta+t', 'meta+T'}}, [textadept.editing.convert_indentation] = {'ctrl+alt+i', 'ctrl+i', 'meta+i'}, -- EOL Mode. -- TODO: m('Buffer/EOL Mode/CRLF') @@ -430,13 +421,11 @@ local bindings = { -- View. [m('View/Next View')] = {'ctrl+alt+n', 'ctrl+alt+\t', nil}, [m('View/Previous View')] = {'ctrl+alt+p', 'ctrl+alt+shift+\t', nil}, - [m('View/Split View Horizontal')] = - {{'ctrl+alt+s', 'ctrl+alt+h'}, 'ctrl+s', nil}, + [m('View/Split View Horizontal')] = {{'ctrl+alt+s', 'ctrl+alt+h'}, 'ctrl+s', nil}, [m('View/Split View Vertical')] = {'ctrl+alt+v', 'ctrl+v', nil}, [m('View/Unsplit View')] = {'ctrl+alt+w', 'ctrl+w', nil}, [m('View/Unsplit All Views')] = {'ctrl+alt+W', 'ctrl+W', nil}, - [m('View/Grow View')] = - {{'ctrl+alt++', 'ctrl+alt+='}, {'ctrl++', 'ctrl+='}, nil}, + [m('View/Grow View')] = {{'ctrl+alt++', 'ctrl+alt+='}, {'ctrl++', 'ctrl+='}, nil}, [m('View/Shrink View')] = {'ctrl+alt+-', 'ctrl+-', nil}, [m('View/Toggle Current Fold')] = {'ctrl+*', 'cmd+*', 'meta+*'}, [m('View/Toggle Show Indent Guides')] = {'ctrl+alt+I', 'ctrl+I', nil}, @@ -450,34 +439,27 @@ local bindings = { [m('Help/Show LuaDoc')] = {'shift+f1', 'shift+f1', nil}, -- Movement commands. - -- Unbound keys are handled by Scintilla, but when playing back a macro, this - -- is not possible. Define some useful default key bindings so Scintilla does - -- not have to handle them. Note that Scintilla still will handle some keys. + -- Unbound keys are handled by Scintilla, but when playing back a macro, this is not possible. + -- Define some useful default key bindings so Scintilla does not have to handle them. Note + -- that Scintilla still will handle some keys. [buffer.line_down] = {'down', {'down', 'ctrl+n'}, {'down', 'ctrl+n'}}, - [buffer.line_down_extend] = - {'shift+down', {'shift+down', 'ctrl+N'}, 'shift+down'}, + [buffer.line_down_extend] = {'shift+down', {'shift+down', 'ctrl+N'}, 'shift+down'}, [buffer.line_up] = {'up', {'up', 'ctrl+p'}, {'up', 'ctrl+p'}}, [buffer.line_up_extend] = {'shift+up', {'shift+up', 'ctrl+P'}, 'shift+up'}, [buffer.char_left] = {'left', {'left', 'ctrl+b'}, {'left', 'ctrl+b'}}, - [buffer.char_left_extend] = - {'shift+left', {'shift+left', 'ctrl+B'}, 'shift+left'}, + [buffer.char_left_extend] = {'shift+left', {'shift+left', 'ctrl+B'}, 'shift+left'}, [buffer.word_left] = {'ctrl+left', {'alt+left', 'ctrl+cmd+b'}, 'ctrl+left'}, [buffer.word_left_extend] = {'ctrl+shift+left', {'ctrl+shift+left', 'ctrl+cmd+B'}, 'ctrl+shift+left'}, [buffer.char_right] = {'right', {'right', 'ctrl+f'}, {'right', 'ctrl+f'}}, - [buffer.char_right_extend] = - {'shift+right', {'shift+right', 'ctrl+F'}, 'shift+right'}, - [buffer.word_right] = - {'ctrl+right', {'alt+right', 'ctrl+cmd+f'}, 'ctrl+right'}, - [buffer.word_right_end_extend] = { - 'ctrl+shift+right', {'ctrl+shift+right', 'ctrl+cmd+F'}, 'ctrl+shift+right' - }, + [buffer.char_right_extend] = {'shift+right', {'shift+right', 'ctrl+F'}, 'shift+right'}, + [buffer.word_right] = {'ctrl+right', {'alt+right', 'ctrl+cmd+f'}, 'ctrl+right'}, + [buffer.word_right_end_extend] = + {'ctrl+shift+right', {'ctrl+shift+right', 'ctrl+cmd+F'}, 'ctrl+shift+right'}, [buffer.vc_home] = {'home', {'cmd+left', 'ctrl+a'}, {'home', 'ctrl+a'}}, - [buffer.vc_home_extend] = - {'shift+home', {'cmd+shift+left', 'ctrl+A'}, 'meta+A'}, + [buffer.vc_home_extend] = {'shift+home', {'cmd+shift+left', 'ctrl+A'}, 'meta+A'}, [buffer.line_end] = {'end', {'cmd+right', 'ctrl+e'}, {'end', 'ctrl+e'}}, - [buffer.line_end_extend] = - {'shift+end', {'cmd+shift+right', 'ctrl+E'}, 'meta+E'}, + [buffer.line_end_extend] = {'shift+end', {'cmd+shift+right', 'ctrl+E'}, 'meta+E'}, [view.vertical_center_caret] = {nil, 'ctrl+l', nil}, [buffer.page_up_extend] = {nil, nil, 'meta+U'}, [buffer.page_down_extend] = {nil, nil, 'meta+D'}, @@ -486,11 +468,10 @@ local bindings = { [function() buffer:line_end_extend() - if not buffer.selection_empty then buffer:cut() else buffer:clear() end + buffer[not buffer.selection_empty and 'cut' or 'clear'](buffer) end] = {nil, 'ctrl+k', 'ctrl+k'}, [buffer.del_word_right] = {'ctrl+del', 'cmd+del', 'ctrl+del'}, - [buffer.del_line_right] = - {'ctrl+shift+del', 'cmd+shift+del', 'ctrl+shift+del'}, + [buffer.del_line_right] = {'ctrl+shift+del', 'cmd+shift+del', 'ctrl+shift+del'}, [buffer.delete_back] = {'\b', '\b', {'\b', 'ctrl+h'}}, [buffer.del_word_left] = {'ctrl+\b', 'cmd+\b', nil}, [buffer.del_line_left] = {'ctrl+shift+\b', 'cmd+shift+\b', nil}, @@ -500,10 +481,10 @@ local bindings = { -- Other. -- UTF-8 input. [function() - ui.command_entry.run( - function(code) buffer:add_text(utf8.char(tonumber(code, 16))) end) + ui.command_entry.run(function(code) buffer:add_text(utf8.char(tonumber(code, 16))) end) end] = {nil, 'cmd+U', 'meta+u'} } +-- LuaFormatter on local keys, plat = keys, CURSES and 3 or OSX and 2 or 1 for f, plat_keys in pairs(bindings) do @@ -517,16 +498,14 @@ end if CURSES then keys['ctrl+meta+v'] = { - n = m('View/Next View'), p = m('View/Previous View'), - s = m('View/Split View Horizontal'), h = m('View/Split View Horizontal'), - v = m('View/Split View Vertical'), w = m('View/Unsplit View'), - W = m('View/Unsplit All Views'), ['+'] = m('View/Grow View'), + n = m('View/Next View'), p = m('View/Previous View'), s = m('View/Split View Horizontal'), + h = m('View/Split View Horizontal'), v = m('View/Split View Vertical'), + w = m('View/Unsplit View'), W = m('View/Unsplit All Views'), ['+'] = m('View/Grow View'), ['='] = m('View/Grow View'), ['-'] = m('View/Shrink View') } end --- GTK-OSX reports Fn-key as a single keycode which confuses Scintilla. Do --- not propagate it. +-- GTK-OSX reports Fn-key as a single keycode which confuses Scintilla. Do not propagate it. if OSX then keys.fn = function() return true end end return M diff --git a/modules/textadept/macros.lua b/modules/textadept/macros.lua index 90729335..9df07421 100644 --- a/modules/textadept/macros.lua +++ b/modules/textadept/macros.lua @@ -4,34 +4,30 @@ --- -- 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. module('textadept.macros')]] local M = {} local recording, macro --- List of commands bound to keys to ignore during macro recording, as the --- command(s) ultimately executed will be recorded in some form. +-- List of commands bound to keys to ignore during macro recording, as the command(s) ultimately +-- executed will be recorded in some form. local ignore events.connect(events.INITIALIZED, function() local m_tools = textadept.menu.menubar[_L['Tools']] ignore = { textadept.menu.menubar[_L['Search']][_L['Find']][2], textadept.menu.menubar[_L['Search']][_L['Find Incremental']][2], - m_tools[_L['Select Command']][2], - m_tools[_L['Macros']][_L['Start/Stop Recording']][2] + m_tools[_L['Select Command']][2], m_tools[_L['Macros']][_L['Start/Stop Recording']][2] } end) -- Event handlers for recording macro-able events. -local function event_recorder(event) - return function(...) macro[#macro + 1] = {event, ...} end -end +local function event_recorder(event) return function(...) macro[#macro + 1] = {event, ...} end end local event_recorders = { [events.KEYPRESS] = function(code, shift, control, alt, cmd) - -- Not every keypress should be recorded (e.g. toggling macro recording). - -- Use very basic key handling to try to identify key bindings to ignore. + -- Not every keypress should be recorded (e.g. toggling macro recording). Use very basic + -- key handling to try to identify key bindings to ignore. local key = code < 256 and string.char(code) or keys.KEYSYMS[code] if key then if shift and code >= 32 and code < 256 then shift = false end @@ -40,11 +36,11 @@ local event_recorders = { for i = 1, #ignore do if keys[key_seq] == ignore[i] then return end end end macro[#macro + 1] = {events.KEYPRESS, code, shift, control, alt, cmd} - end, + end, -- LuaFormatter [events.MENU_CLICKED] = event_recorder(events.MENU_CLICKED), [events.CHAR_ADDED] = event_recorder(events.CHAR_ADDED), - [events.FIND] = event_recorder(events.FIND), - [events.REPLACE] = event_recorder(events.REPLACE), + [events.FIND] = event_recorder(events.FIND), -- LuaFormatter + [events.REPLACE] = event_recorder(events.REPLACE), -- LuaFormatter [events.UPDATE_UI] = function() if #keys.keychain == 0 then ui.statusbar_text = _L['Macro recording'] end end @@ -71,9 +67,9 @@ end -- @name play function M.play() if recording or not macro then return end - -- If this function is run as a key command, `keys.keychain` cannot be cleared - -- until this function returns. Emit 'esc' to forcibly clear it so subsequent - -- keypress events can be properly handled. + -- If this function is run as a key command, `keys.keychain` cannot be cleared until this + -- function returns. Emit 'esc' to forcibly clear it so subsequent keypress events can be + -- properly handled. events.emit(events.KEYPRESS, not CURSES and 0xFF1B or 7) -- 'esc' for _, event in ipairs(macro) do if event[1] == events.CHAR_ADDED then @@ -86,8 +82,8 @@ end --- -- Saves a recorded macro to file *filename* or the user-selected file. --- @param filename Optional filename to save the recorded macro to. If `nil`, --- the user is prompted for one. +-- @param filename Optional filename to save the recorded macro to. If `nil`, the user is +-- prompted for one. -- @name save function M.save(filename) if recording or not macro then return end @@ -102,8 +98,7 @@ function M.save(filename) for _, event in ipairs(macro) do f:write(string.format('{%q,', event[1])) for i = 2, #event do - f:write(string.format( - type(event[i]) == 'string' and '%q,' or '%s,', event[i])) + f:write(string.format(type(event[i]) == 'string' and '%q,' or '%s,', event[i])) end f:write('},\n') end @@ -112,8 +107,7 @@ end --- -- Loads a macro from file *filename* or the user-selected file. --- @param filename Optional macro file to load. If `nil`, the user is prompted --- for one. +-- @param filename Optional macro file to load. If `nil`, the user is prompted for one. -- @name load function M.load(filename) if recording then return end diff --git a/modules/textadept/menu.lua b/modules/textadept/menu.lua index cd56cf73..54195bd9 100644 --- a/modules/textadept/menu.lua +++ b/modules/textadept/menu.lua @@ -6,19 +6,20 @@ local M = {} --[[ This comment is for LuaDoc. --- -- 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. module('textadept.menu')]] local _L, SEPARATOR = _L, {''} --- The following buffer and view functions need to be made constant in order for --- menu items to identify the key associated with the functions. +-- LuaFormatter off +-- The following buffer and view functions need to be made constant in order for menu items to +-- identify the key associated with the functions. local menu_buffer_functions = {'undo','redo','cut','copy','paste','line_duplicate','clear','select_all','upper_case','lower_case','move_selected_lines_up','move_selected_lines_down'} for _, f in ipairs(menu_buffer_functions) do buffer[f] = buffer[f] end view.zoom_in, view.zoom_out = view.zoom_in, view.zoom_out +-- LuaFormatter on -- Commonly used functions in menu commands. local sel_enc = textadept.editing.select_enclosed @@ -41,10 +42,11 @@ local function open_page(url) os.spawn(string.format('%s "%s"', cmd, not OSX and url or 'file://' .. url)) end +-- LuaFormatter off --- -- 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. -- @class table -- @name menubar -- @usage textadept.menu.menubar[_L['File']][_L['New']] @@ -89,9 +91,7 @@ local default_menubar = { local match_pos = buffer:brace_match(buffer.current_pos, 0) if match_pos ~= -1 then buffer:goto_pos(match_pos) end end}, - {_L['Complete Word'], function() - textadept.editing.autocomplete('word') - end}, + {_L['Complete Word'], function() textadept.editing.autocomplete('word') end}, {_L['Toggle Block Comment'], textadept.editing.toggle_comment}, {_L['Transpose Characters'], textadept.editing.transpose_chars}, {_L['Join Lines'], textadept.editing.join_lines}, @@ -156,9 +156,7 @@ local default_menubar = { SEPARATOR, {_L['Find in Files'], function() ui.find.focus{in_files = true} end}, {_L['Goto Next File Found'], function() ui.find.goto_file_found(true) end}, - {_L['Goto Previous File Found'], function() - ui.find.goto_file_found(false) - end}, + {_L['Goto Previous File Found'], function() ui.find.goto_file_found(false) end}, SEPARATOR, {_L['Jump to'], textadept.editing.goto_line} }, @@ -181,9 +179,7 @@ local default_menubar = { {_L['Toggle Bookmark'], textadept.bookmarks.toggle}, {_L['Clear Bookmarks'], textadept.bookmarks.clear}, {_L['Next Bookmark'], function() textadept.bookmarks.goto_mark(true) end}, - {_L['Previous Bookmark'], function() - textadept.bookmarks.goto_mark(false) - end}, + {_L['Previous Bookmark'], function() textadept.bookmarks.goto_mark(false) end}, {_L['Goto Bookmark...'], textadept.bookmarks.goto_mark}, }, { @@ -199,8 +195,7 @@ local default_menubar = { {_L['Quickly Open User Home'], function() io.quick_open(_USERHOME) end}, {_L['Quickly Open Textadept Home'], function() io.quick_open(_HOME) end}, {_L['Quickly Open Current Directory'], function() - if not buffer.filename then return end - io.quick_open(buffer.filename:match('^(.+)[/\\]')) + if buffer.filename then io.quick_open(buffer.filename:match('^(.+)[/\\]')) end end}, {_L['Quickly Open Current Project'], io.quick_open}, }, @@ -211,25 +206,18 @@ local default_menubar = { {_L['Previous Snippet Placeholder'], textadept.snippets.previous}, {_L['Cancel Snippet'], textadept.snippets.cancel_current}, SEPARATOR, - {_L['Complete Trigger Word'], function() - textadept.editing.autocomplete('snippets') - end} + {_L['Complete Trigger Word'], function() textadept.editing.autocomplete('snippets') end} }, SEPARATOR, - {_L['Complete Symbol'], function() - textadept.editing.autocomplete(buffer:get_lexer(true)) - end}, + {_L['Complete Symbol'], function() textadept.editing.autocomplete(buffer:get_lexer(true)) end}, {_L['Show Documentation'], textadept.editing.show_documentation}, {_L['Show Style'], function() - local char = buffer:text_range( - buffer.current_pos, buffer:position_after(buffer.current_pos)) + local char = buffer:text_range(buffer.current_pos, buffer:position_after(buffer.current_pos)) if char == '' then return end -- end of buffer local bytes = string.rep(' 0x%X', #char):format(char:byte(1, #char)) local style = buffer.style_at[buffer.current_pos] - local text = string.format( - "'%s' (U+%04X:%s)\n%s %s\n%s %s (%d)", char, utf8.codepoint(char), - bytes, _L['Lexer'], buffer:get_lexer(true), _L['Style'], - buffer:name_of_style(style), style) + local text = string.format("'%s' (U+%04X:%s)\n%s %s\n%s %s (%d)", char, utf8.codepoint(char), + bytes, _L['Lexer'], buffer:get_lexer(true), _L['Style'], buffer:name_of_style(style), style) view:call_tip_show(buffer.current_pos, text) end} }, @@ -299,12 +287,11 @@ local default_menubar = { end}, SEPARATOR, {_L['Toggle Show Indent Guides'], function() - view.indentation_guides = - view.indentation_guides == 0 and view.IV_LOOKBOTH or 0 + view.indentation_guides = view.indentation_guides == 0 and view.IV_LOOKBOTH or 0 end}, {_L['Toggle Virtual Space'], function() - buffer.virtual_space_options = - buffer.virtual_space_options == 0 and buffer.VS_USERACCESSIBLE or 0 + buffer.virtual_space_options = buffer.virtual_space_options == 0 and + buffer.VS_USERACCESSIBLE or 0 end}, SEPARATOR, {_L['Zoom In'], view.zoom_in}, @@ -327,8 +314,7 @@ local default_menubar = { --- -- 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. -- @class table -- @name context_menu -- @usage textadept.menu.context_menu[#textadept.menu.context_menu + 1] = {...} @@ -346,8 +332,7 @@ local default_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. -- @class table -- @name tab_context_menu local default_tab_context_menu = { @@ -358,6 +343,7 @@ local default_tab_context_menu = { SEPARATOR, {_L['Reload'], buffer.reload}, } +-- LuaFormatter on -- Table of proxy tables for menus. local proxies = {} @@ -378,7 +364,10 @@ local function get_gdk_key(key_seq) local code = string.byte(key) if #key > 1 or code < 32 then for i, s in pairs(keys.KEYSYMS) do - if s == key and i > 0xFE20 then code = i break end + if s == key and i > 0xFE20 then + code = i + break + end end end return code, modifiers @@ -387,8 +376,8 @@ end -- Creates a menu suitable for `ui.menu()` from the menu table format. -- Also assigns key bindings. -- @param menu The menu to create a GTK menu from. --- @param contextmenu Flag indicating whether or not the menu is a context menu. --- If so, menu_id offset is 1000. The default value is `false`. +-- @param contextmenu Flag indicating whether or not the menu is a context menu. If so, menu_id +-- offset is 1000. The default value is `false`. -- @return GTK menu that can be passed to `ui.menu()`. -- @see ui.menu local function read_menu_table(menu, contextmenu) @@ -397,8 +386,7 @@ local function read_menu_table(menu, contextmenu) if item.title then gtkmenu[#gtkmenu + 1] = read_menu_table(item, contextmenu) else -- item = {label, function} - local menu_id = - not contextmenu and #menu_items + 1 or #contextmenu_items + 1000 + 1 + local menu_id = not contextmenu and #menu_items + 1 or #contextmenu_items + 1000 + 1 local key, mods = get_gdk_key(key_shortcuts[tostring(item[2])]) gtkmenu[#gtkmenu + 1] = {item[1], menu_id, key, mods} if item[2] then @@ -410,13 +398,12 @@ local function read_menu_table(menu, contextmenu) return gtkmenu end --- Returns a proxy table for menu table *menu* such that when a menu item is --- changed or added, *update* is called to update the menu in the UI. +-- Returns a proxy table for menu table *menu* such that when a menu item is changed or added, +-- *update* is called to update the menu in the UI. -- @param menu The menu or table of menus to create a proxy for. --- @param update The function to call to update the menu in the UI when a menu --- item is changed or added. --- @param menubar Used internally to keep track of the top-level menu for --- calling *update* with. +-- @param update The function to call to update the menu in the UI when a menu item is changed +-- or added. +-- @param menubar Used internally to keep track of the top-level menu for calling *update* with. local function proxy_menu(menu, update, menubar) return setmetatable({}, { __index = function(_, k) @@ -425,60 +412,59 @@ local function proxy_menu(menu, update, menubar) v = menu[k] elseif type(k) == 'string' then for _, item in ipairs(menu) do - if item.title == k or item[1] == k then v = item break end + if item.title == k or item[1] == k then + v = item + break + end end end return type(v) == 'table' and proxy_menu(v, update, menubar or menu) or v - end, + end, -- LuaFormatter __newindex = function(_, k, v) menu[k] = getmetatable(v) and getmetatable(v).menu or v - -- After adding or removing menus or menu items, update the menubar or - -- context menu. When updating a menu item's function, do nothing extra. + -- After adding or removing menus or menu items, update the menubar or context menu. When + -- updating a menu item's function, do nothing extra. if type(v) ~= 'function' then update(menubar or menu) end - end, - __len = function() return #menu end, - menu = menu -- store existing menu for copying (e.g. m[#m + 1] = m[#m]) + end, __len = function() return #menu end, menu = menu -- store existing menu for copying (e.g. m[#m + 1] = m[#m]) }) end -- Sets `ui.menubar` from menu table *menubar*. --- Each menu is an ordered list of menu items and has a `title` key for the --- title text. Menu items are tables containing menu text and either a function --- to call or a table containing a function with its parameters to call when an --- item is clicked. Menu items may also be sub-menus, ordered lists of menu --- items with an additional `title` key for the sub-menu's title text. --- @param menubar The table of menu tables to create the menubar from. If `nil`, --- clears the menubar from view, but keeps it intact in order for --- `M.select_command()` to function properly. +-- Each menu is an ordered list of menu items and has a `title` key for the title text. Menu +-- items are tables containing menu text and either a function to call or a table containing a +-- function with its parameters to call when an item is clicked. Menu items may also be sub-menus, +-- ordered lists of menu items with an additional `title` key for the sub-menu's title text. +-- @param menubar The table of menu tables to create the menubar from. If `nil`, clears the +-- menubar from view, but keeps it intact in order for `M.select_command()` to function properly. -- @see ui.menubar -- @see ui.menu local function set_menubar(menubar) - if not menubar then ui.menubar = {} return end + if not menubar then + ui.menubar = {} + return + end key_shortcuts, menu_items = {}, {} -- reset for key, f in pairs(keys) do key_shortcuts[tostring(f)] = key end local _menubar = {} - for _, menu in ipairs(menubar) do - _menubar[#_menubar + 1] = ui.menu(read_menu_table(menu)) - end + for _, menu in ipairs(menubar) do _menubar[#_menubar + 1] = ui.menu(read_menu_table(menu)) end ui.menubar = _menubar proxies.menubar = proxy_menu(menubar, set_menubar) end events.connect(events.INITIALIZED, function() set_menubar(default_menubar) end) -- Define menu proxy for use by keys.lua and user scripts. --- Do not use an update function because this is expensive at startup, and --- `events.INITIALIZED` will create the first visible menubar and proper proxy. +-- Do not use an update function because this is expensive at startup, and `events.INITIALIZED` +-- will create the first visible menubar and proper proxy. proxies.menubar = proxy_menu(default_menubar, function() end) --- Sets `ui.context_menu` and `ui.tab_context_menu` from menu item lists --- *buffer_menu* and *tab_menu*, respectively. --- Menu items are tables containing menu text and either a function to call or --- a table containing a function with its parameters to call when an item is --- clicked. Menu items may also be sub-menus, ordered lists of menu items with --- an additional `title` key for the sub-menu's title text. --- @param buffer_menu Optional menu table to create the buffer context menu --- from. If `nil`, uses the default context menu. --- @param tab_menu Optional menu table to create the tabbar context menu from. --- If `nil`, uses the default tab context menu. +-- Sets `ui.context_menu` and `ui.tab_context_menu` from menu item lists *buffer_menu* and +-- *tab_menu*, respectively. +-- Menu items are tables containing menu text and either a function to call or a table containing a +-- function with its parameters to call when an item is clicked. Menu items may also be sub-menus, +-- ordered lists of menu items with an additional `title` key for the sub-menu's title text. +-- @param buffer_menu Optional menu table to create the buffer context menu from. If `nil`, +-- uses the default context menu. +-- @param tab_menu Optional menu table to create the tabbar context menu from. If `nil`, uses +-- the default tab context menu. -- @see ui.context_menu -- @see ui.tab_context_menu -- @see ui.menu @@ -497,9 +483,8 @@ local function set_contextmenus(buffer_menu, tab_menu) end events.connect(events.INITIALIZED, set_contextmenus) -- Define menu proxies for use by user scripts. --- Do not use an update function because this is expensive at startup, and --- `events.INITIALIZED` will create these visible menus and their proper --- proxies. +-- Do not use an update function because this is expensive at startup, and `events.INITIALIZED` +-- will create these visible menus and their proper proxies. proxies.context_menu = proxy_menu(default_context_menu, function() end) proxies.tab_context_menu = proxy_menu(default_tab_context_menu, function() end) @@ -522,8 +507,7 @@ function M.select_command() if item.title then build_command_tables(item) elseif item[1] ~= '' then -- item = {label, function} - local label = - menu.title and string.format('%s: %s', menu.title, item[1]) or item[1] + local label = menu.title and string.format('%s: %s', menu.title, item[1]) or item[1] items[#items + 1] = label:gsub('_([^_])', '%1') items[#items + 1] = key_shortcuts[tostring(item[2])] or '' end @@ -531,15 +515,13 @@ function M.select_command() end build_command_tables(getmetatable(M.menubar).menu) local button, i = ui.dialogs.filteredlist{ - title = _L['Run Command'], columns = {_L['Command'], _L['Key Binding']}, - items = items + title = _L['Run Command'], columns = {_L['Command'], _L['Key Binding']}, items = items } if button == 1 and i then events.emit(events.MENU_CLICKED, i) end end return setmetatable(M, { - __index = function(_, k) return proxies[k] or rawget(M, k) end, - __newindex = function(_, k, v) + __index = function(_, k) return proxies[k] or rawget(M, k) end, __newindex = function(_, k, v) if k == 'menubar' then set_menubar(v) elseif k == 'context_menu' then diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua index 3e0b4295..d39e7919 100644 --- a/modules/textadept/run.lua +++ b/modules/textadept/run.lua @@ -5,14 +5,12 @@ local M = {} --[[ This comment is for LuaDoc. --- -- 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. -- @field 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`. -- @field MARK_WARNING (number) -- The run or compile warning marker number. @@ -20,34 +18,32 @@ local M = {} -- The run or compile error marker number. -- @field _G.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. -- @field _G.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. -- @field _G.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. -- @field _G.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. @@ -59,26 +55,23 @@ M.MARK_WARNING = _SCINTILLA.next_marker_number() M.MARK_ERROR = _SCINTILLA.next_marker_number() -- Events. -local run_events = { - 'compile_output', 'run_output', 'build_output', 'test_output' -} +local run_events = {'compile_output', 'run_output', 'build_output', 'test_output'} for _, v in ipairs(run_events) do events[v:upper()] = v end --- Keep track of: the last process spawned in order to kill it if requested; the --- cwd of that process in order to jump to relative file paths in recognized --- warning or error messages; and the view the process was spawned from in order --- to jump to messages (which are displayed in a split view) in the original --- view. +-- Keep track of: the last process spawned in order to kill it if requested; the cwd of that +-- process in order to jump to relative file paths in recognized warning or error messages; +-- and the view the process was spawned from in order to jump to messages (which are displayed +-- in a split view) in the original view. local proc, cwd, preferred_view --- Scans the given message for a warning or error message and, if one is found, --- returns table of the warning/error's details. --- @param message The message to parse for warnings or errors. The message --- is assumed to be encoded in _CHARSET. --- @param ext_or_lexer Optional file extension or lexer name associated with the --- shell command that produced the warning/error. --- @return error details table with 'filename', 'line', 'column', and 'message' --- fields along with a 'warning' flag. +-- Scans the given message for a warning or error message and, if one is found, returns table +-- of the warning/error's details. +-- @param message The message to parse for warnings or errors. The message is assumed to be +-- encoded in _CHARSET. +-- @param ext_or_lexer Optional file extension or lexer name associated with the shell command +-- that produced the warning/error. +-- @return error details table with 'filename', 'line', 'column', and 'message' fields along +-- with a 'warning' flag. -- @see error_patterns local function scan_for_error(message, ext_or_lexer) for key, patterns in pairs(M.error_patterns) do @@ -99,15 +92,13 @@ local function scan_for_error(message, ext_or_lexer) i = i + 1 end local lower_message = message:lower() - detail.warning = - (lower_message:find('warning') or lower_message:find('note')) and + detail.warning = (lower_message:find('warning') or lower_message:find('note')) and not lower_message:find('error') - -- Compile and run commands specify the file extension or lexer name used - -- to determine the command, so the error patterns used are guaranteed to - -- be correct. Build and test commands have no such context and instead - -- iterate through all possible error patterns. Only consider the - -- error/warning valid if the extracted filename's extension or lexer name - -- matches the error pattern's extension or lexer name. + -- Compile and run commands specify the file extension or lexer name used to determine + -- the command, so the error patterns used are guaranteed to be correct. Build and + -- test commands have no such context and instead iterate through all possible error + -- patterns. Only consider the error/warning valid if the extracted filename's extension + -- or lexer name matches the error pattern's extension or lexer name. if ext_or_lexer then return detail end local ext = detail.filename:match('[^/\\.]+$') local lexer_name = textadept.file_types.extensions[ext] @@ -120,33 +111,30 @@ local function scan_for_error(message, ext_or_lexer) end -- Prints an output line from a compile, run, build, or test shell command. --- Assume output is UTF-8 unless there's a recognized warning or error message. --- In that case assume it is encoded in _CHARSET and mark it. +-- Assume output is UTF-8 unless there's a recognized warning or error message. In that case +-- assume it is encoded in _CHARSET and mark it. -- All stdout and stderr from the command is printed silently. -- @param line The output line to print. --- @param ext_or_lexer Optional file extension or lexer name associated with the --- executed command. This is used for better error detection in compile and --- run commands. +-- @param ext_or_lexer Optional file extension or lexer name associated with the executed command. +-- This is used for better error detection in compile and run commands. local function print_line(line, ext_or_lexer) local error = scan_for_error(line, ext_or_lexer) - ui.silent_print = M.run_in_background or ext_or_lexer or - not line:find('^> ') or line:find('^> exit') + ui.silent_print = M.run_in_background or ext_or_lexer or not line:find('^> ') or + line:find('^> exit') ui.print(not error and line or line:iconv('UTF-8', _CHARSET)) ui.silent_print = false if error then -- Current position is one line below the error due to ui.print()'s '\n'. - buffer:marker_add( - buffer.line_count - 1, error.warning and M.MARK_WARNING or M.MARK_ERROR) + buffer:marker_add(buffer.line_count - 1, error.warning and M.MARK_WARNING or M.MARK_ERROR) end end local output_buffer --- Prints the output from a compile, run, build, or test shell command as a --- series of lines, performing buffering as needed. +-- Prints the output from a compile, run, build, or test shell command as a series of lines, +-- performing buffering as needed. -- @param output The output to print, or `nil` to flush any buffered output. --- @param ext_or_lexer Optional file extension or lexer name associated with the --- executed command. This is used for better error detection in compile and --- run commands. +-- @param ext_or_lexer Optional file extension or lexer name associated with the executed command. +-- This is used for better error detection in compile and run commands. local function print_output(output, ext_or_lexer) if output then if output_buffer then output = output_buffer .. output end @@ -162,17 +150,15 @@ local function print_output(output, ext_or_lexer) end end --- Runs command *command* in working directory *dir*, emitting events of type --- *event* with any output received. --- @param command String command to run, or a function returning such a string --- and optional working directory and environment table. A returned working --- directory overrides *dir*. +-- Runs command *command* in working directory *dir*, emitting events of type *event* with any +-- output received. +-- @param command String command to run, or a function returning such a string and optional +-- working directory and environment table. A returned working directory overrides *dir*. -- @param dir String working directory to run *command* in. -- @param event String event name to emit command output with. -- @param macros Optional table of '%[char]' macros to expand within *command*. --- @param ext_or_lexer Optional file extension or lexer name associated with the --- executed command. This is used for better error detection in compile and --- run commands. +-- @param ext_or_lexer Optional file extension or lexer name associated with the executed command. +-- This is used for better error detection in compile and run commands. local function run_command(command, dir, event, macros, ext_or_lexer) local working_dir, env if type(command) == 'function' then command, working_dir, env = command() end @@ -183,10 +169,12 @@ local function run_command(command, dir, event, macros, ext_or_lexer) cwd = (working_dir or dir):gsub('[/\\]$', '') events.emit(event, string.format('> cd %s\n', cwd)) events.emit(event, string.format('> %s\n', command:iconv('UTF-8', _CHARSET))) - local args = {command, cwd, emit, emit, function(status) - emit() -- flush - events.emit(event, string.format('> exit status: %d\n', status)) - end} + local args = { + command, cwd, emit, emit, function(status) + emit() -- flush + events.emit(event, string.format('> exit status: %d\n', status)) + end + } if env then table.insert(args, 3, env) end proc = assert(os.spawn(table.unpack(args))) end @@ -204,21 +192,18 @@ local function compile_or_run(filename, commands) textadept.file_types.extensions[ext] local command = commands[filename] or commands[ext] or commands[lang] local dirname, basename = '', filename - if filename:find('[/\\]') then - dirname, basename = filename:match('^(.+)[/\\]([^/\\]+)$') - end - local event = commands == M.compile_commands and events.COMPILE_OUTPUT or - events.RUN_OUTPUT + if filename:find('[/\\]') then dirname, basename = filename:match('^(.+)[/\\]([^/\\]+)$') end + local event = commands == M.compile_commands and events.COMPILE_OUTPUT or events.RUN_OUTPUT local macros = { - ['%p'] = filename, ['%d'] = dirname, ['%f'] = basename, - ['%e'] = basename:match('^(.+)%.') -- no extension + ['%p'] = filename, ['%d'] = dirname, ['%f'] = basename, ['%e'] = basename:match('^(.+)%.') -- no extension } run_command(command, dirname, event, macros, commands[ext] and ext or lang) end +-- LuaFormatter off --- --- 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. @@ -226,21 +211,21 @@ end -- + `%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. -- @class table -- @name compile_commands M.compile_commands = {actionscript='mxmlc "%f"',ada='gnatmake "%f"',ansi_c='gcc -o "%e" "%f"',antlr='antlr4 "%f"',g='antlr3 "%f"',applescript='osacompile "%f" -o "%e.scpt"',asm='nasm "%f"'--[[ && ld "%e.o" -o "%e"']],boo='booc "%f"',caml='ocamlc -o "%e" "%f"',csharp=WIN32 and 'csc "%f"' or 'mcs "%f"',coffeescript='coffee -c "%f"',context='context --nonstopmode "%f"',cpp='g++ -o "%e" "%f"',cuda=WIN32 and 'nvcc -o "%e.exe" "%f"' or 'nvcc -o "%e" "%f"',dmd='dmd "%f"',dot='dot -Tps "%f" -o "%e.ps"',eiffel='se c "%f"',elixir='elixirc "%f"',erlang='erl -compile "%e"',faust='faust -o "%e.cpp" "%f"',fsharp=WIN32 and 'fsc.exe "%f"' or 'mono fsc.exe "%f"',fortran='gfortran -o "%e" "%f"',gap='gac -o "%e" "%f"',go='go build "%f"',groovy='groovyc "%f"',haskell=WIN32 and 'ghc -o "%e.exe" "%f"' or 'ghc -o "%e" "%f"',inform=function() return 'inform -c "'..buffer.filename:match('^(.+%.inform[/\\])Source')..'"' end,java='javac "%f"',ltx='pdflatex -file-line-error -halt-on-error "%f"',less='lessc --no-color "%f" "%e.css"',lilypond='lilypond "%f"',lisp='clisp -c "%f"',litcoffee='coffee -c "%f"',lua='luac -o "%e.luac" "%f"',moon='moonc "%f"',markdown='markdown "%f" > "%e.html"',myr='mbld -b "%e" "%f"',nemerle='ncc "%f" -out:"%e.exe"',nim='nim c "%f"',nsis='MakeNSIS "%f"',objective_c='gcc -o "%e" "%f"',pascal='fpc "%f"',perl='perl -c "%f"',php='php -l "%f"',pony='ponyc "%f"',prolog='gplc --no-top-level "%f"',python='python -m py_compile "%f"',ruby='ruby -c "%f"',rust='rustc "%f"',sass='sass "%f" "%e.css"',scala='scalac "%f"',sml='mlton "%f"',tex='pdflatex -file-line-error -halt-on-error "%f"',typescript='tsc "%f"',vala='valac "%f"',vb=WIN32 and 'vbc "%f"' or 'vbnc "%f"',zig='zig build-exe "%f"'} +-- LuaFormatter on --- --- 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. --- @param filename Optional path to the file to compile. The default value is --- the current file's filename. +-- @param filename Optional path to the file to compile. The default value is the current +-- file's filename. -- @see compile_commands -- @see _G.events -- @name compile @@ -251,9 +236,10 @@ function M.compile(filename) end events.connect(events.COMPILE_OUTPUT, print_output) +-- LuaFormatter off --- --- 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. @@ -261,21 +247,21 @@ events.connect(events.COMPILE_OUTPUT, print_output) -- + `%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. -- @class table -- @name run_commands M.run_commands = {actionscript=WIN32 and 'start "" "%e.swf"' or OSX and 'open "file://%e.swf"' or 'xdg-open "%e.swf"',ada=WIN32 and '"%e"' or './"%e"',ansi_c=WIN32 and '"%e"' or './"%e"',applescript='osascript "%f"',asm='./"%e"',awk='awk -f "%f"',batch='"%f"',boo='booi "%f"',caml='ocamlrun "%e"',csharp=WIN32 and '"%e"' or 'mono "%e.exe"',chuck='chuck "%f"',clojure='clj -M "%f"',cmake='cmake -P "%f"',coffeescript='coffee "%f"',context=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',cpp=WIN32 and '"%e"' or './"%e"',crystal='crystal "%f"',cuda=WIN32 and '"%e"' or './"%e"',dart='dart "%f"',dmd=WIN32 and '"%e"' or './"%e"',eiffel="./a.out",elixir='elixir "%f"',fsharp=WIN32 and '"%e"' or 'mono "%e.exe"',fantom='fan "%f"',fennel='fennel "%f"',forth='gforth "%f" -e bye',fortran=WIN32 and '"%e"' or './"%e"',gnuplot='gnuplot "%f"',go='go run "%f"',groovy='groovy "%f"',haskell=WIN32 and '"%e"' or './"%e"',html=WIN32 and 'start "" "%f"' or OSX and 'open "file://%f"' or 'xdg-open "%f"',icon='icont "%e" -x',idl='idl -batch "%f"',Io='io "%f"',java='java "%e"',javascript='node "%f"',jq='jq -f "%f"',julia='julia "%f"',ltx=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',less='lessc --no-color "%f"',lilypond=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',lisp='clisp "%f"',litcoffee='coffee "%f"',lua='lua -e "io.stdout:setvbuf(\'no\')" "%f"',makefile=WIN32 and 'nmake -f "%f"' or 'make -f "%f"',markdown='markdown "%f"',moon='moon "%f"',myr=WIN32 and '"%e"' or './"%e"',nemerle=WIN32 and '"%e"' or 'mono "%e.exe"',nim='nim c -r "%f"',objective_c=WIN32 and '"%e"' or './"%e"',pascal=WIN32 and '"%e"' or './"%e"',perl='perl "%f"',php='php "%f"',pike='pike "%f"',pkgbuild='makepkg -p "%f"',pony=WIN32 and '"%e"' or './"%e"',prolog=WIN32 and '"%e"' or './"%e"',pure='pure "%f"',python=function() return buffer:get_line(1):find('^#!.-python3') and 'python3 -u "%f"' or 'python -u "%f"' end,rstats=WIN32 and 'Rterm -f "%f"' or 'R -f "%f"',rebol='REBOL "%f"',rexx=WIN32 and 'rexx "%f"' or 'regina "%f"',ruby='ruby "%f"',rust=WIN32 and '"%e"' or './"%e"',sass='sass "%f"',scala='scala "%e"',bash='bash "%f"',csh='tcsh "%f"',ksh='ksh "%f"',mksh='mksh "%f"',sh='sh "%f"',zsh='zsh "%f"',rc='rc "%f"',smalltalk='gst "%f"',sml=WIN32 and '"%e"' or './"%e"',snobol4='snobol4 -b "%f"',tcl='tclsh "%f"',tex=WIN32 and 'start "" "%e.pdf"' or OSX and 'open "%e.pdf"' or 'xdg-open "%e.pdf"',vala=WIN32 and '"%e"' or './"%e"',vb=WIN32 and '"%e"' or 'mono "%e.exe"',xs='xs "%f"',zig=WIN32 and '"%e"' or './"%e"'} +-- LuaFormatter on --- --- 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. --- @param filename Optional path to the file to run. The default value is the --- current file's filename. +-- @param filename Optional path to the file to run. The default value is the current file's +-- filename. -- @see run_commands -- @see _G.events -- @name run @@ -287,15 +273,15 @@ end events.connect(events.RUN_OUTPUT, print_output) --- --- 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. -- @param filename Optional path to the file to set run/compile arguments for. --- @param run Optional string run arguments to set. If `nil`, the user is --- prompted for them. Pass the empty string for no run arguments. --- @param compile Optional string compile arguments to set. If `nil`, the user --- is prompted for them. Pass the empty string for no compile arguments. +-- @param run Optional string run arguments to set. If `nil`, the user is prompted for them. Pass +-- the empty string for no run arguments. +-- @param compile Optional string compile arguments to set. If `nil`, the user is prompted +-- for them. Pass the empty string for no compile arguments. -- @see run_commands -- @see compile_commands -- @name set_arguments @@ -308,52 +294,49 @@ function M.set_arguments(filename, run, compile) assert_type(compile, 'string/nil', 3) local base_commands, utf8_args = {}, {} for i, commands in ipairs{M.run_commands, M.compile_commands} do - -- Compare the base run/compile command with the one for the current - -- file. The difference is any additional arguments set previously. - base_commands[i] = commands[filename:match('[^.]+$')] or - commands[buffer:get_lexer()] or '' + -- Compare the base run/compile command with the one for the current file. The difference + -- is any additional arguments set previously. + base_commands[i] = commands[filename:match('[^.]+$')] or commands[buffer:get_lexer()] or '' local current_command = commands[filename] or '' - local args = (i == 1 and run or compile) or - current_command:sub(#base_commands[i] + 2) + local args = (i == 1 and run or compile) or current_command:sub(#base_commands[i] + 2) utf8_args[i] = args:iconv('UTF-8', _CHARSET) end if not run or not compile then local button button, utf8_args = ui.dialogs.inputbox{ - title = _L['Set Arguments...']:gsub('_', ''), informative_text = { - _L['Command line arguments'], _L['For Run:'], _L['For Compile:'] - }, text = utf8_args, width = not CURSES and 400 or nil + title = _L['Set Arguments...']:gsub('_', ''), + informative_text = {_L['Command line arguments'], _L['For Run:'], _L['For Compile:']}, + text = utf8_args, width = not CURSES and 400 or nil } if button ~= 1 then return end end for i, commands in ipairs{M.run_commands, M.compile_commands} do - -- Add the additional arguments to the base run/compile command and set - -- the new command to be the one used for the current file. + -- Add the additional arguments to the base run/compile command and set the new command to + -- be the one used for the current file. commands[filename] = string.format('%s %s', base_commands[i], utf8_args[i]:iconv(_CHARSET, 'UTF-8')) end end +-- LuaFormatter off --- --- 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. -- @class table -- @name build_commands M.build_commands = {--[[Ant]]['build.xml']='ant',--[[Dockerfile]]Dockerfile='docker build .',--[[Make]]Makefile='make',GNUmakefile='make',makefile='make',--[[Meson]]['meson.build']='meson compile',--[[Maven]]['pom.xml']='mvn',--[[Ruby]]Rakefile='rake'} +-- LuaFormatter on --- --- 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. --- @param root_directory The path to the project to build. The default value is --- the current project. +-- @param root_directory The path to the project to build. The default value is the current project. -- @see build_commands -- @see _G.events -- @name build @@ -368,8 +351,8 @@ function M.build(root_directory) for build_file, build_command in pairs(M.build_commands) do if lfs.attributes(string.format('%s/%s', root_directory, build_file)) then local button, utf8_command = ui.dialogs.inputbox{ - title = _L['Command'], informative_text = root_directory, - text = build_command, button1 = _L['OK'], button2 = _L['Cancel'] + title = _L['Command'], informative_text = root_directory, text = build_command, + button1 = _L['OK'], button2 = _L['Cancel'] } if button == 1 then command = utf8_command:iconv(_CHARSET, 'UTF-8') end break @@ -381,23 +364,23 @@ end events.connect(events.BUILD_OUTPUT, print_output) --- --- 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. -- @class table -- @name test_commands M.test_commands = {} --- --- 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. --- @param root_directory The path to the project to run tests for. The default --- value is the current project. +-- @param root_directory The path to the project to run tests for. The default value is the +-- current project. -- @see test_commands -- @see _G.events -- @name test @@ -407,8 +390,7 @@ function M.test(root_directory) if not root_directory then return end end for i = 1, #_BUFFERS do _BUFFERS[i]:annotation_clear_all() end - run_command( - M.test_commands[root_directory], root_directory, events.TEST_OUTPUT) + run_command(M.test_commands[root_directory], root_directory, events.TEST_OUTPUT) end events.connect(events.TEST_OUTPUT, print_output) @@ -422,56 +404,63 @@ local function is_msg_buf(buf) return buf._type == _L['[Message Buffer]'] end -- Send line as input to process stdin on return. events.connect(events.CHAR_ADDED, function(code) - if code == string.byte('\n') and proc and proc:status() == 'running' and - is_msg_buf(buffer) then + if code == string.byte('\n') and proc and proc:status() == 'running' and is_msg_buf(buffer) then local line_num = buffer:line_from_position(buffer.current_pos) - 1 proc:write(buffer:get_line(line_num)) end end) +-- LuaFormatter off --- --- 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. -- @class table -- @name error_patterns M.error_patterns = {actionscript={'^(.-)%((%d+)%): col: (%d+) (.+)$'},ada={'^(.-):(%d+):(%d+):%s*(.*)$','^[^:]+: (.-):(%d+) (.+)$'},ansi_c={'^(.-):(%d+):(%d+): (.+)$'},antlr={'^error%(%d+%): (.-):(%d+):(%d+): (.+)$','^warning%(%d+%): (.-):(%d+):(%d+): (.+)$'},--[[ANTLR]]g={'^error%(%d+%): (.-):(%d+):(%d+): (.+)$','^warning%(%d+%): (.-):(%d+):(%d+): (.+)$'},asm={'^(.-):(%d+): (.+)$'},awk={'^awk: (.-):(%d+): (.+)$'},boo={'^(.-)%((%d+),(%d+)%): (.+)$'},caml={'^%s*File "(.-)", line (%d+), characters (%d+)'},chuck={'^(.-)line%((%d+)%)%.char%((%d+)%): (.+)$'},clojure={' error .- at .-%((.-):(%d+)'},cmake={'^CMake Error at (.-):(%d+)','^(.-):(%d+):$'},coffeescript={'^(.-):(%d+):(%d+): (.+)$'},context={'error on line (%d+) in file (.-): (.+)$'},cpp={'^(.-):(%d+):(%d+): (.+)$'},csharp={'^(.-)%((%d+),(%d+)%): (.+)$'},cuda={'^(.-)%((%d+)%): (error.+)$'},dart={"^'(.-)': error: line (%d+) pos (%d+): (.+)$",'%(file://(.-):(%d+):(%d+)%)'},dmd={'^(.-)%((%d+)%): (Error.+)$'},dot={'^Warning: (.-): (.+) in line (%d+)'},eiffel={'^Line (%d+) columns? .- in .- %((.-)%):$','^line (%d+) column (%d+) file (.-)$'},elixir={'^(.-):(%d+): (.+)$','Error%) (.-):(%d+): (.+)$'},erlang={'^(.-):(%d+): (.+)$'},fantom={'^(.-)%((%d+),(%d+)%): (.+)$'},faust={'^(.-):(%d+):(.+)$'},fennel={'^%S+ error in (.-):(%d+)'},forth={'^(.-):(%d+): (.+)$'},fortran={'^(.-):(%d+)%D+(%d+):%s*(.*)$'},fsharp={'^(.-)%((%d+),(%d+)%): (.+)$'},gap={'^(.+) in (.-) line (%d+)$'},gnuplot={'^"(.-)", line (%d+): (.+)$'},go={'^(.-):(%d+):(%d+): (.+)$'},groovy={'^%s+at .-%((.-):(%d+)%)$','^(.-):(%d+): (.+)$'},haskell={'^(.-):(%d+):(%d+):%s*(.*)$'},icon={'^File (.-); Line (%d+) # (.+)$','^.-from line (%d+) in (.-)$'},java={'^%s+at .-%((.-):(%d+)%)$','^(.-):(%d+): (.+)$'},javascript={'^%s+at .-%((.-):(%d+):(%d+)%)$','^%s+at (.-):(%d+):(%d+)$','^(.-):(%d+):?$'},jq={'^jq: error: (.+) at (.-), line (%d+)'},julia={'^%s+%[%d+%].- at (.-):(%d+)$'},ltx={'^(.-):(%d+): (.+)$'},less={'^(.+) in (.-) on line (%d+), column (%d+):$'},lilypond={'^(.-):(%d+):(%d+):%s*(.*)$'},litcoffee={'^(.-):(%d+):(%d+): (.+)$'},lua={'^luac?: (.-):(%d+): (.+)$'},makefile={'^(.-):(%d+): (.+)$'},nemerle={'^(.-)%((%d+),(%d+)%): (.+)$'},nim={'^(.-)%((%d+), (%d+)%) (%w+:.+)$'},objective_c={'^(.-):(%d+):(%d+): (.+)$'},pascal={'^(.-)%((%d+),(%d+)%) (%w+:.+)$'},perl={'^(.+) at (.-) line (%d+)'},php={'^(.+) in (.-) on line (%d+)$'},pike={'^(.-):(%d+):(.+)$'},pony={'^(.-):(%d+):(%d+): (.+)$'},prolog={'^(.-):(%d+):(%d+): (.+)$','^(.-):(%d+): (.+)$'},pure={'^(.-), line (%d+): (.+)$'},python={'^%s*File "(.-)", line (%d+)'},rexx={'^Error %d+ running "(.-)", line (%d+): (.+)$'},ruby={'^%s+from (.-):(%d+):','^(.-):(%d+):%s*(.+)$'},rust={'^(.-):(%d+):(%d+): (.+)$',"panicked at '([^']+)', (.-):(%d+)"},sass={'^WARNING on line (%d+) of (.-):$','^%s+on line (%d+) of (.-)$'},scala={'^%s+at .-%((.-):(%d+)%)$','^(.-):(%d+): (.+)$'},sh={'^(.-): (%d+): %1: (.+)$'},bash={'^(.-): line (%d+): (.+)$'},zsh={'^(.-):(%d+): (.+)$'},smalltalk={'^(.-):(%d+): (.+)$','%((.-):(%d+)%)$'},snobol4={'^(.-):(%d+): (.+)$'},tcl={'^%s*%(file "(.-)" line (%d+)%)$'},tex={'^(.-):(%d+): (.+)$'},typescript={'^(.-):(%d+):(%d+) %- (.+)$'},vala={'^(.-):(%d+)%.(%d+)[%-%.%d]+: (.+)$','^(.-):(%d+):(%d+): (.+)$'},vb={'^(.-)%((%d+),(%d+)%): (.+)$'},xs={'^(.-):(%d+)%S* (.+)$'},zig={'^(.-):(%d+):(%d+): (.+)$'}} -- Note: APDL,IDL,REBOL,RouterOS,Spin,Verilog,VHDL are proprietary. -- Note: ASP,CSS,Desktop,diff,django,elm,fstab,gettext,Gtkrc,HTML,ini,JSON,JSP,Markdown,Networkd,Postscript,Properties,R,Reason,RHTML,Systemd,XML don't have parse-able errors. -- Note: Batch,BibTeX,ConTeXt,Dockerfile,GLSL,Inform,Io,Lisp,MoonScript,Scheme,SQL,TeX cannot be parsed for one reason or another. +-- LuaFormatter on --- --- 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. --- @param 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. --- @param next Optional flag indicating whether to go to the next recognized --- warning/error or the previous one. Only applicable when *line_num* is --- `nil`. +-- 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. +-- @param 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. +-- @param 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 error_patterns -- @name goto_error function M.goto_error(line_num, next) if type(line_num) == 'boolean' then line_num, next = nil, line_num end local msg_view, msg_buf = nil, nil for i = 1, #_VIEWS do - if is_msg_buf(_VIEWS[i].buffer) then msg_view = _VIEWS[i] break end + if is_msg_buf(_VIEWS[i].buffer) then + msg_view = _VIEWS[i] + break + end end for i = 1, #_BUFFERS do - if is_msg_buf(_BUFFERS[i]) then msg_buf = _BUFFERS[i] break end + if is_msg_buf(_BUFFERS[i]) then + msg_buf = _BUFFERS[i] + break + end end if not msg_view and not msg_buf then return end - if msg_view then ui.goto_view(msg_view) else view:goto_buffer(msg_buf) end + if msg_view then + ui.goto_view(msg_view) + else + view:goto_buffer(msg_buf) + end -- If no line number was given, find the next warning or error marker. if not assert_type(line_num, 'number/nil', 1) and next ~= nil then @@ -486,7 +475,11 @@ function M.goto_error(line_num, next) wline = f(buffer, next and 1 or buffer.line_count, WARN_BIT) eline = f(buffer, next and 1 or buffer.line_count, ERROR_BIT) elseif wline == -1 or eline == -1 then - if wline == -1 then wline = eline else eline = wline end + if wline == -1 then + wline = eline + else + eline = wline + end end line_num = (next and math.min or math.max)(wline, eline) if line_num == -1 and not wrapped then @@ -508,9 +501,7 @@ function M.goto_error(line_num, next) local sloppy = not detail.filename:find(not WIN32 and '^/' or '^%a:[/\\]') ui.goto_file(detail.filename, true, preferred_view, sloppy) textadept.editing.goto_line(detail.line) - if detail.column then - buffer:goto_pos(buffer:find_column(detail.line, detail.column)) - end + if detail.column then buffer:goto_pos(buffer:find_column(detail.line, detail.column)) end if not detail.message then return end buffer.annotation_text[detail.line] = detail.message if detail.warning then return end @@ -518,13 +509,12 @@ function M.goto_error(line_num, next) end events.connect(events.KEYPRESS, function(code) if keys.KEYSYMS[code] == '\n' and is_msg_buf(buffer) and - scan_for_error(buffer:get_cur_line():match('^[^\r\n]*')) then + scan_for_error(buffer:get_cur_line():match('^[^\r\n]*')) then M.goto_error(buffer:line_from_position(buffer.current_pos)) return true end end) -events.connect(events.DOUBLE_CLICK, function(_, line) - if is_msg_buf(buffer) then M.goto_error(line) end -end) +events.connect(events.DOUBLE_CLICK, + function(_, line) if is_msg_buf(buffer) then M.goto_error(line) end end) return M diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua index 96f6e969..bf19e78e 100644 --- a/modules/textadept/session.lua +++ b/modules/textadept/session.lua @@ -7,23 +7,21 @@ local M = {} -- Session support for Textadept. -- @field 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. -- @field _G.events.SESSION_SAVE (string) -- 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. -- @field _G.events.SESSION_LOAD (string) -- 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. module('textadept.session')]] M.save_on_quit = true @@ -35,12 +33,11 @@ for _, v in ipairs(session_events) do events[v:upper()] = v end local session_file = _USERHOME .. (not CURSES and '/session' or '/session_term') --- --- 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. --- @param filename Optional absolute path to the session file to load. If `nil`, --- the user is prompted for one. +-- 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. +-- @param filename Optional absolute path to the session file to load. If `nil`, the user is +-- prompted for one. -- @return `true` if the session file was opened and read; `nil` otherwise. -- @usage textadept.session.load(filename) -- @name load @@ -116,24 +113,18 @@ function M.load(filename) return true end -- Load session when no args are present. -local function load_default_session() - if M.save_on_quit then M.load(session_file) end -end +local function load_default_session() if M.save_on_quit then M.load(session_file) end end events.connect(events.ARG_NONE, load_default_session) -- Returns value *val* serialized as a string. -- This is a very simple implementation suitable for session saving only. --- Ignores function, userdata, and thread types, and does not handle circular --- tables. +-- Ignores function, userdata, and thread types, and does not handle circular tables. local function _tostring(val) if type(val) == 'table' then local t = {} - for k, v in pairs(val) do - t[#t + 1] = string.format('[%s]=%s,', _tostring(k), _tostring(v)) - end + for k, v in pairs(val) do t[#t + 1] = string.format('[%s]=%s,', _tostring(k), _tostring(v)) end return string.format('{%s}', table.concat(t)) - elseif type(val) == 'function' or type(val) == 'userdata' or - type(val) == 'thread' then + elseif type(val) == 'function' or type(val) == 'userdata' or type(val) == 'thread' then val = nil end return type(val) == 'string' and string.format('%q', val) or tostring(val) @@ -141,12 +132,11 @@ end --- -- 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`. --- @param filename Optional absolute path to the session file to save. If `nil`, --- the user is prompted for one. +-- @param filename Optional absolute path to the session file to save. If `nil`, the user is +-- prompted for one. -- @usage textadept.session.save(filename) -- @name save function M.save(filename) @@ -174,7 +164,7 @@ function M.save(filename) filename = buffer.filename or buffer._type, anchor = current and buffer.anchor or buffer._anchor or 1, current_pos = current and buffer.current_pos or buffer._current_pos or 1, - top_line = current and view.first_visible_line or buffer._top_line or 1, + top_line = current and view.first_visible_line or buffer._top_line or 1 } local bookmarks = {} local BOOKMARK_BIT = 1 << textadept.bookmarks.MARK_BOOKMARK - 1 @@ -193,13 +183,11 @@ function M.save(filename) -- Serialize views. local function serialize_split(split) return split.buffer and _BUFFERS[split.buffer] or { - serialize_split(split[1]), serialize_split(split[2]), - vertical = split.vertical, size = split.size + serialize_split(split[1]), serialize_split(split[2]), vertical = split.vertical, + size = split.size } end - session.views = { - serialize_split(ui.get_split_table()), current = _VIEWS[view] - } + session.views = {serialize_split(ui.get_split_table()), current = _VIEWS[view]} -- Serialize recent files. session.recent_files = io.recent_files @@ -209,19 +197,14 @@ function M.save(filename) session_file = filename end -- Saves session on quit. -events.connect(events.QUIT, function() - if M.save_on_quit then M.save(session_file) end -end, 1) +events.connect(events.QUIT, function() if M.save_on_quit then M.save(session_file) end end, 1) -- Does not save session on quit. -args.register('-n', '--nosession', 0, function() - M.save_on_quit = false -end, 'No session functionality') +args.register('-n', '--nosession', 0, function() M.save_on_quit = false end, + 'No session functionality') -- Loads the given session on startup. args.register('-s', '--session', 1, function(name) - if not lfs.attributes(name) then - name = string.format('%s/%s', _USERHOME, name) - end + if not lfs.attributes(name) then name = string.format('%s/%s', _USERHOME, name) end M.load(name) events.disconnect(events.ARG_NONE, load_default_session) end, 'Load session') diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua index 40d2febb..e900f2b4 100644 --- a/modules/textadept/snippets.lua +++ b/modules/textadept/snippets.lua @@ -8,57 +8,53 @@ local M = {} -- -- ### 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()`](), 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()`](), 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; @@ -71,29 +67,27 @@ local M = {} -- } -- ]] -- --- 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`]() and [`buffer.tab_width`]()). +-- A single unit of indentation based on the buffer's indentation settings ([`buffer.use_tabs`]() +-- and [`buffer.tab_width`]()). -- -- #### `\n` -- @@ -112,12 +106,12 @@ M.INDIC_PLACEHOLDER = _SCINTILLA.next_indic_number() --- -- 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. -- @class table -- @name paths M.paths = {} @@ -125,37 +119,35 @@ M.paths = {} local INDIC_SNIPPET = _SCINTILLA.next_indic_number() local INDIC_CURRENTPLACEHOLDER = _SCINTILLA.next_indic_number() - --- 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. +-- LuaFormatter off +-- 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. -- @class table -- @name snippets -- @see _G.snippets local snippets = {actionscript={},ada={},apdl={},ansi_c={},antlr={},apl={},applescript={},asp={},autoit={},awk={},b_lang={},bash={},batch={},bibtex={},boo={},chuck={},clojure={},cmake={},coffeescript={},context={},cpp={},crystal={},csharp={},css={},cuda={},desktop={},django={},dmd={},dockerfile={},dot={},eiffel={},elixir={},elm={},erlang={},fantom={},faust={},fennel={},fish={},forth={},fortran={},fsharp={},fstab={},gap={},gettext={},gherkin={},glsl={},gnuplot={},go={},groovy={},gtkrc={},haskell={},html={},icon={},idl={},inform={},ini={},Io={},java={},javascript={},jq={},json={},jsp={},julia={},latex={},ledger={},less={},lilypond={},lisp={},logtalk={},lua={},makefile={},matlab={},meson={},moonscript={},myrddin={},nemerle={},networkd={},nim={},nsis={},objective_c={},pascal={},perl={},php={},pico8={},pike={},pkgbuild={},pony={},prolog={},props={},protobuf={},ps={},pure={},python={},rails={},rc={},reason={},rebol={},rest={},rexx={},rhtml={},routeros={},rstats={},ruby={},rust={},sass={},scala={},scheme={},smalltalk={},sml={},snobol4={},spin={},sql={},systemd={},tcl={},tex={},text={},toml={},typescript={},vala={},vb={},vbscript={},verilog={},vhdl={},wsf={},xml={},xs={},xtend={},yaml={},zig={}} - --- Finds the snippet assigned to the trigger word behind the caret and returns --- the trigger word and snippet text. If *grep* is `true`, returns a table of --- snippets (trigger-text key-value pairs) that match the trigger word --- instead of snippet text. --- Snippets are searched for in the global snippets table followed by snippet --- directories. Lexer-specific snippets are preferred. --- @param grep Flag that indicates whether or not to return a table of snippets --- that match the trigger word. --- @param no_trigger Flag that indicates whether or not to ignore the trigger --- word and return all snippets. +-- LuaFormatter on + +-- Finds the snippet assigned to the trigger word behind the caret and returns the trigger word +-- and snippet text. +-- If *grep* is `true`, returns a table of snippets (trigger-text key-value pairs) that match +-- the trigger word instead of snippet text. Snippets are searched for in the global snippets +-- table followed by snippet directories. Lexer-specific snippets are preferred. +-- @param grep Flag that indicates whether or not to return a table of snippets that match the +-- trigger word. +-- @param no_trigger Flag that indicates whether or not to ignore the trigger word and return +-- all snippets. -- @return trigger word, snippet text or table of matching snippets local function find_snippet(grep, no_trigger) local matching_snippets = {} - local trigger = not no_trigger and buffer:text_range( - buffer:word_start_position(buffer.current_pos), buffer.current_pos) or '' + local trigger = not no_trigger and + buffer:text_range(buffer:word_start_position(buffer.current_pos), buffer.current_pos) or '' if no_trigger then grep = true end local lang = buffer:get_lexer(true) local name_patt = '^' .. trigger -- Search in the snippet tables. local snippet_tables = {snippets} - if type(snippets[lang]) == 'table' then - table.insert(snippet_tables, 1, snippets[lang]) - end + if type(snippets[lang]) == 'table' then table.insert(snippet_tables, 1, snippets[lang]) end for _, snippets in ipairs(snippet_tables) do if not grep and snippets[trigger] then return trigger, snippets[trigger] end if not grep then goto continue end @@ -169,14 +161,12 @@ local function find_snippet(grep, no_trigger) -- Search in snippet files. for i = 1, #M.paths do for basename in lfs.dir(M.paths[i]) do - -- Snippet files are either of the form "lexer.trigger.ext" or - -- "trigger.ext". Prefer "lexer."-prefixed snippets. + -- Snippet files are either of the form "lexer.trigger.ext" or "trigger.ext". Prefer + -- "lexer."-prefixed snippets. local p1, p2, p3 = basename:match('^([^.]+)%.?([^.]*)%.?([^.]*)$') - if not grep and - (p1 == lang and p2 == trigger or p1 == trigger and p3 == '') or - grep and - (p1 == lang and p2 and p2:find(name_patt) or - p1 and p1:find(name_patt) and p3 == '') then + if not grep and (p1 == lang and p2 == trigger or p1 == trigger and p3 == '') or + (grep and + (p1 == lang and p2 and p2:find(name_patt) or p1 and p1:find(name_patt) and p3 == '')) then local f = io.open(string.format('%s/%s', M.paths[i], basename)) text = f:read('a') f:close() @@ -185,26 +175,25 @@ local function find_snippet(grep, no_trigger) end end end - if not grep then return nil, nil else return trigger, matching_snippets end + if not grep then return nil, nil end + return trigger, matching_snippets end -- A snippet object. -- @field trigger The word that triggered this snippet. --- @field original_sel_text The text originally selected when this snippet was --- inserted. +-- @field original_sel_text The text originally selected when this snippet was inserted. -- @field start_pos This snippet's start position. --- @field end_pos This snippet's end position. This is a metafield that is --- computed based on the `INDIC_SNIPPET` sentinel. --- @field placeholder_pos The beginning of the current placeholder in this --- snippet. This is used by transforms to identify text to transform. This is --- a metafield that is computed based on `INDIC_CURRENTPLACEHOLDER`. +-- @field end_pos This snippet's end position. This is a metafield that is computed based on the +-- `INDIC_SNIPPET` sentinel. +-- @field placeholder_pos The beginning of the current placeholder in this snippet. This is used +-- by transforms to identify text to transform. This is a metafield that is computed based on +-- `INDIC_CURRENTPLACEHOLDER`. -- @field index This snippet's current placeholder index. -- @field max_index The number of different placeholders in this snippet. --- @field snapshots A record of this snippet's text over time. The snapshot for --- a given placeholder index contains the state of the snippet with all --- placeholders of that index filled in (prior to moving to the next --- placeholder index). Snippet state consists of a `text` string field and a --- `placeholders` table field. +-- @field snapshots A record of this snippet's text over time. The snapshot for a given +-- placeholder index contains the state of the snippet with all placeholders of that index +-- filled in (prior to moving to the next placeholder index). Snippet state consists of a +-- `text` string field and a `placeholders` table field. -- @class table -- @name snippet local snippet = {} @@ -218,8 +207,8 @@ local stack = {} function snippet.new(text, trigger) local snip = setmetatable({ trigger = trigger, original_sel_text = buffer:get_sel_text(), - start_pos = buffer.selection_start - (trigger and #trigger or 0), index = 0, - max_index = 0, snapshots = {} + start_pos = buffer.selection_start - (trigger and #trigger or 0), index = 0, max_index = 0, + snapshots = {} }, snippet) -- Convert and match indentation. @@ -246,10 +235,10 @@ function snippet.new(text, trigger) local C, Cp, Ct, Cg, Cc = lpeg.C, lpeg.Cp, lpeg.Ct, lpeg.Cg, lpeg.Cc local patt = P{ V('plain_text') * V('placeholder') * Cp() + V('plain_text') * -1, - plain_text = C(((P(1) - '%' + '%' * S('({'))^1 + '%%')^0), - placeholder = Ct( - '%' * (V('index')^-1 * (V('angles') + V('brackets') + V('braces')) * - V('transform') + V('index') * (V('parens') + V('simple')))), + plain_text = C(((P(1) - '%' + '%' * S('({'))^1 + '%%')^0), -- LuaFormatter + placeholder = Ct('%' * + (V('index')^-1 * (V('angles') + V('brackets') + V('braces')) * V('transform') + V('index') * + (V('parens') + V('simple')))), -- LuaFormatter index = Cg(R('09')^1 / tonumber, 'index'), parens = '(' * Cg((1 - S('()') + V('parens'))^0, 'default') * ')', simple = Cg(Cc(true), 'simple'), transform = Cg(Cc(true), 'transform'), @@ -259,22 +248,21 @@ function snippet.new(text, trigger) } -- A snippet placeholder. -- Each placeholder is stored in a snippet snapshot. - -- @field id This placeholder's unique ID. This field is used as an - -- indicator's value for identification purposes. + -- @field id This placeholder's unique ID. This field is used as an indicator's value for + -- identification purposes. -- @field index This placeholder's index. -- @field default This placeholder's default text, if any. - -- @field transform Whether or not this placeholder is a transform (containing - -- either Lua or Shell code). + -- @field transform Whether or not this placeholder is a transform (containing either Lua or + -- Shell code). -- @field lua_code The Lua code of this transform. -- @field sh_code The Shell code of this transform. -- @field choice A list of options to insert from an autocompletion list. - -- @field position This placeholder's initial position in its snapshot. This - -- field will not update until the next snapshot is taken. Use - -- `snippet:each_placeholder()` to determine a placeholder's current - -- position. - -- @field length This placeholder's initial length in its snapshot. This field - -- will never update. Use `buffer:indicator_end()` in conjunction with - -- `snippet:each_placeholder()` to determine a placeholder's current length. + -- @field position This placeholder's initial position in its snapshot. This field will not + -- update until the next snapshot is taken. Use `snippet:each_placeholder()` to determine + -- a placeholder's current position. + -- @field length This placeholder's initial length in its snapshot. This field will never + -- update. Use `buffer:indicator_end()` in conjunction with `snippet:each_placeholder()` + -- to determine a placeholder's current length. -- @class table -- @name placeholder local text_part, placeholder, e = patt:match(text) @@ -285,17 +273,14 @@ function snippet.new(text, trigger) placeholder.id = #snapshot.placeholders + 1 snapshot.placeholders[#snapshot.placeholders + 1] = placeholder end - if text_part ~= '' then - snapshot.text = snapshot.text .. text_part:gsub('%%(%p)', '%1') - end + if text_part ~= '' then snapshot.text = snapshot.text .. text_part:gsub('%%(%p)', '%1') end placeholder.position = #snapshot.text if placeholder.default then if placeholder.default:find('%%%d+') then - -- Parses out embedded placeholders, adding them to this snippet's - -- snapshot. + -- Parses out embedded placeholders, adding them to this snippet's snapshot. -- @param s The placeholder string to parse. - -- @param start_pos The absolute position in the snippet `s` starts - -- from. All computed positions are anchored from here. + -- @param start_pos The absolute position in the snippet `s` starts from. All computed + -- positions are anchored from here. -- @return plain text from `s` (i.e. no placeholder markup) local function process_placeholders(s, start_pos) -- Processes a placeholder capture from LPeg. @@ -306,8 +291,7 @@ function snippet.new(text, trigger) position = start_pos + position - 1 if default then -- Process sub-placeholders starting at the index after '%n('. - default = process_placeholders( - default:sub(2, -2), position + #index + 2) + default = process_placeholders(default:sub(2, -2), position + #index + 2) end index = tonumber(index) if index > snip.max_index then snip.max_index = index end @@ -323,8 +307,7 @@ function snippet.new(text, trigger) parens = '(' * (1 - S('()') + V('parens'))^0 * ')' }, s) end - placeholder.default = process_placeholders( - placeholder.default, placeholder.position) + placeholder.default = process_placeholders(placeholder.default, placeholder.position) end snapshot.text = snapshot.text .. placeholder.default elseif placeholder.transform and not placeholder.index then @@ -336,9 +319,7 @@ function snippet.new(text, trigger) placeholder.position = snip.start_pos + placeholder.position -- absolute text_part, placeholder, e = patt:match(text, e) end - if text_part ~= '' then - snapshot.text = snapshot.text .. text_part:gsub('%%(%p)', '%1') - end + if text_part ~= '' then snapshot.text = snapshot.text .. text_part:gsub('%%(%p)', '%1') end snip.snapshots[0] = snapshot -- Insert the snippet into the buffer and mark its end position. @@ -359,20 +340,19 @@ function snippet:__index(k) local end_pos = buffer:indicator_end(INDIC_SNIPPET, self.start_pos) return end_pos > self.start_pos and end_pos or self.start_pos elseif k == 'placeholder_pos' then - -- Normally the marker is one character behind the placeholder. However - -- it will not exist at all if the placeholder is at the beginning of the - -- snippet. Also account for the marker being at the beginning of the - -- snippet. (If so, pos will point to the correct position.) + -- Normally the marker is one character behind the placeholder. However it will not exist + -- at all if the placeholder is at the beginning of the snippet. Also account for the marker + -- being at the beginning of the snippet. (If so, pos will point to the correct position.) local pos = buffer:indicator_end(INDIC_CURRENTPLACEHOLDER, self.start_pos) if pos == 1 then pos = self.start_pos end - return buffer:indicator_all_on_for(pos) & - 1 << INDIC_CURRENTPLACEHOLDER - 1 > 0 and pos + 1 or pos + return buffer:indicator_all_on_for(pos) & 1 << INDIC_CURRENTPLACEHOLDER - 1 > 0 and pos + 1 or + pos end return getmetatable(self)[k] end --- Inserts the current snapshot (based on `self.index`) of this snippet into --- the buffer and marks placeholders. +-- Inserts the current snapshot (based on `self.index`) of this snippet into the buffer and +-- marks placeholders. function snippet:insert() buffer:set_target_range(self.start_pos, self.end_pos) buffer:replace_target(self.snapshots[self.index].text) @@ -383,22 +363,19 @@ function snippet:insert() end end --- Jumps to the next placeholder in this snippet and adds additional carets --- at mirrors. +-- Jumps to the next placeholder in this snippet and adds additional carets at mirrors. function snippet:next() if buffer:auto_c_active() then buffer:auto_c_complete() end - -- Take a snapshot of the current state in order to restore it later if - -- necessary. + -- Take a snapshot of the current state in order to restore it later if necessary. if self.index > 0 and self.start_pos < self.end_pos then local text = buffer:text_range(self.start_pos, self.end_pos) local placeholders = {} for pos, ph in self:each_placeholder() do - -- Only the position of placeholders changes between snapshots; save it - -- and keep all other existing properties. - -- Note that nested placeholders will return the same placeholder id - -- twice: once before a nested placeholder, and again after. (e.g. - -- [foo[bar]baz] will will return the '[foo' and 'baz]' portions of the - -- same placeholder.) Only process the first occurrence. + -- Only the position of placeholders changes between snapshots; save it and keep all + -- other existing properties. + -- Note that nested placeholders will return the same placeholder id twice: once before + -- a nested placeholder, and again after. (e.g. [foo[bar]baz] will will return the '[foo' + -- and 'baz]' portions of the same placeholder.) Only process the first occurrence. if placeholders[ph.id] then goto continue end placeholders[ph.id] = setmetatable({position = pos}, { __index = self.snapshots[self.index - 1].placeholders[ph.id] @@ -413,8 +390,11 @@ function snippet:next() local ph = select(2, self:each_placeholder(self.index, 'default')()) or select(2, self:each_placeholder(self.index, 'choice')()) or select(2, self:each_placeholder(self.index, 'simple')()) or - self.index == 0 and {position = self.end_pos, length = 0} - if not ph then self:next() return end -- try next placeholder + (self.index == 0 and {position = self.end_pos, length = 0}) + if not ph then + self:next() -- try next placeholder + return + end -- Mark the position of the placeholder so transforms can identify it. buffer.indicator_current = INDIC_CURRENTPLACEHOLDER @@ -461,10 +441,13 @@ function snippet:next() if self.index == 0 then self:finish() end end --- Jumps to the previous placeholder in this snippet and restores the state --- associated with that placeholder. +-- Jumps to the previous placeholder in this snippet and restores the state associated with +-- that placeholder. function snippet:previous() - if self.index < 2 then self:finish(true) return end + if self.index < 2 then + self:finish(true) + return + end self.index = self.index - 2 self:insert() self:next() @@ -472,8 +455,8 @@ end -- Finishes or cancels this snippet depending on boolean *canceling*. -- The snippet cleans up after itself regardless. --- @param canceling Whether or not to cancel inserting this snippet. When --- `true`, the buffer is restored to its state prior to snippet expansion. +-- @param canceling Whether or not to cancel inserting this snippet. When `true`, the buffer +-- is restored to its state prior to snippet expansion. function snippet:finish(canceling) local s, e = self.start_pos, self.end_pos if e ~= s then buffer:delete_range(e, 1) end -- clear initial padding space @@ -487,47 +470,42 @@ function snippet:finish(canceling) stack[#stack] = nil end --- Returns a generator that returns each placeholder's position and state for --- all placeholders in this snippet. --- DO NOT modify the buffer while this generator is running. Doing so will --- affect the generator's state and cause errors. Re-run the generator each --- time a buffer edit is made (e.g. via `goto`). +-- Returns a generator that returns each placeholder's position and state for all placeholders +-- in this snippet. +-- DO NOT modify the buffer while this generator is running. Doing so will affect the generator's +-- state and cause errors. Re-run the generator each time a buffer edit is made (e.g. via `goto`). -- @param index Optional placeholder index to constrain results to. -- @param type Optional placeholder type to constrain results to. function snippet:each_placeholder(index, type) - local snapshot = - self.snapshots[self.index > 0 and self.index - 1 or #self.snapshots] + local snapshot = self.snapshots[self.index > 0 and self.index - 1 or #self.snapshots] local i = self.start_pos return function() local s = buffer:indicator_end(M.INDIC_PLACEHOLDER, i) while s > 1 and s <= self.end_pos do if buffer:indicator_all_on_for(i) & 1 << M.INDIC_PLACEHOLDER - 1 > 0 then - -- This next indicator comes directly after the previous one; adjust - -- start and end positions to compensate. + -- This next indicator comes directly after the previous one; adjust start and end + -- positions to compensate. s, i = buffer:indicator_start(M.INDIC_PLACEHOLDER, i), s else i = buffer:indicator_end(M.INDIC_PLACEHOLDER, s) end local id = buffer:indicator_value_at(M.INDIC_PLACEHOLDER, s) local ph = snapshot.placeholders[id] - if ph and (not index or ph.index == index) and (not type or ph[type]) then - return s, ph - end + if ph and (not index or ph.index == index) and (not type or ph[type]) then return s, ph end s = buffer:indicator_end(M.INDIC_PLACEHOLDER, i) end end end --- Returns the result of executing Lua or Shell code, in placeholder table --- *placeholder*, in the context of this snippet. +-- Returns the result of executing Lua or Shell code, in placeholder table *placeholder*, +-- in the context of this snippet. -- @param placeholder The placeholder that contains code to execute. function snippet:execute_code(placeholder) local s, e = self.placeholder_pos, buffer.selection_end if s > e then s, e = e, s end local text = self.index and buffer:text_range(s, e) or '' -- %<...>, %[...] if placeholder.lua_code then - local env = setmetatable( - {text = text, selected_text = self.original_sel_text}, {__index = _G}) + local env = setmetatable({text = text, selected_text = self.original_sel_text}, {__index = _G}) local f, result = load('return ' .. placeholder.lua_code, nil, 't', env) return f and select(2, pcall(f)) or result or '' elseif placeholder.sh_code then @@ -571,13 +549,11 @@ function snippet:update_transforms() end --- --- 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. --- @param 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. +-- 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. +-- @param 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 `false` if no action was taken; `nil` otherwise. -- @see buffer.word_chars -- @name insert @@ -589,17 +565,18 @@ function M.insert(text) assert_type(text, 'string/nil', trigger or '?') end if text then snippet.new(text, trigger) end - if #stack > 0 then stack[#stack]:next() else return false end + if #stack == 0 then return false end + stack[#stack]:next() end --- --- 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 `false` if no snippet is active; `nil` otherwise. -- @name previous function M.previous() - if #stack > 0 then stack[#stack]:previous() else return false end + if #stack == 0 then return false end + stack[#stack]:previous() end --- @@ -608,12 +585,13 @@ end -- @return `false` if no snippet is active; `nil` otherwise. -- @name cancel_current function M.cancel_current() - if #stack > 0 then stack[#stack]:finish(true) else return false end + if #stack == 0 then return false end + stack[#stack]:finish(true) end --- --- 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. -- @name select function M.select() local all_snippets, items = {}, {} @@ -625,8 +603,7 @@ function M.select() items[#items + 1], items[#items + 2] = trigger, all_snippets[trigger] end local button, i = ui.dialogs.filteredlist{ - title = _L['Select Snippet'], columns = {_L['Trigger'], _L['Snippet Text']}, - items = items + title = _L['Select Snippet'], columns = {_L['Trigger'], _L['Snippet Text']}, items = items } if button == 1 and i then M.insert(items[i * 2]) end end @@ -634,9 +611,7 @@ end -- Update snippet transforms when text is added or deleted. events.connect(events.UPDATE_UI, function(updated) if #stack == 0 then return end - if updated & buffer.UPDATE_CONTENT > 0 then - stack[#stack]:update_transforms() - end + if updated & buffer.UPDATE_CONTENT > 0 then stack[#stack]:update_transforms() end if #keys.keychain == 0 then ui.statusbar_text = _L['Snippet active'] end end) @@ -645,8 +620,7 @@ events.connect(events.VIEW_NEW, function() view.indic_style[INDIC_CURRENTPLACEHOLDER] = view.INDIC_HIDDEN end) --- Returns for the word behind the caret a list of snippet trigger word --- completions. +-- Returns for the word behind the caret a list of snippet trigger word completions. -- @see textadept.editing.autocomplete textadept.editing.autocompleters.snippet = function() local list, trigger, snippets = {}, find_snippet(true) @@ -657,8 +631,8 @@ textadept.editing.autocompleters.snippet = function() end --- --- 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. -- @class table -- @name _G.snippets _G.snippets = snippets diff --git a/scripts/fill_layout.lua b/scripts/fill_layout.lua index a60584dc..a1b236cd 100755 --- a/scripts/fill_layout.lua +++ b/scripts/fill_layout.lua @@ -1,10 +1,9 @@ #!/usr/bin/lua --- Filters the given file through markdown, inserts it into the template --- specified by stdin by replacing simple {{ variable }} tags, and outputs the --- result to stdout. +-- Filters the given file through markdown, inserts it into the template specified by stdin by +-- replacing simple {{ variable }} tags, and outputs the result to stdout. --- Filter the file through markdown using TOC generation in order to get header --- anchors, but ignore the actual TOC. +-- Filter the file through markdown using TOC generation in order to get header anchors, but +-- ignore the actual TOC. local p = io.popen('markdown -f toc -T ' .. arg[1]) local html = p:read('*a'):match('^.-\n</ul>\n(.+)$') html = html:gsub('<h(%d) id="([^"]+)"', function(n, id) @@ -14,8 +13,5 @@ end) p:close() -- Fill in HTML layout (stdin) with markdown output and print the result. -local tags = { - ['page.title'] = html:match('<h%d.->([^<]+)'), - content = html:gsub('%%', '%%%%') -} -io.write(io.stdin:read('*a'):gsub('{{ (%S+) }}', tags)) +local tags = {['page.title'] = html:match('<h%d.->([^<]+)'), content = html} +io.write((io.stdin:read('*a'):gsub('{{ (%S+) }}', tags))) diff --git a/scripts/gen_iface.lua b/scripts/gen_iface.lua index 87844b47..28588cd8 100755 --- a/scripts/gen_iface.lua +++ b/scripts/gen_iface.lua @@ -6,37 +6,34 @@ local const_patt = '^val ([%w_]+)=([-%dx%x]+)' local event_patt = '^evt %a+ ([%w_]+)=(%d+)(%b())' local msg_patt = '^(%a+) (%a+) (%w+)=(%d+)%((%a*)%s*([^,]*),%s*(%a*)%s*([^)]*)' local types = { - [''] = 0, void = 0, int = 1, length = 2, index = 3, position = 3, line = 3, - colour = 4, bool = 5, keymod = 6, string = 7, stringresult = 8, cells = 9, - pointer = 1, textrange = 10, findtext = 11, formatrange = 12 + [''] = 0, void = 0, int = 1, length = 2, index = 3, position = 3, line = 3, colour = 4, bool = 5, + keymod = 6, string = 7, stringresult = 8, cells = 9, pointer = 1, textrange = 10, findtext = 11, + formatrange = 12 } local ignores = { -- constants to ignore - '^INDIC[012S]_', '^INVALID_POSITION', '^KEYWORDSET_MAX', '^SC_AC_', - '^SC_DOCUMENTOPTION_', '^SC_CACHE_', '^SC_CHARSET_', '^SC_EFF_', - '^SC_FONT_SIZE_MULTIPLIER', '^SC_INDIC', '^SC_LINE_END_TYPE_', '^SC_PHASES_', - '^SC_POPUP_', '^SC_PRINT_', '^SC_STATUS_', '^SC_TECHNOLOGY_', '^SC_TYPE_', - '^SC_WEIGHT_', '^SCE_', '^SCEN_', '^SCFIND_POSIX', '^SCI_', '^SCK_', - '^SCLEX_', '^UNDO_MAY_COALESCE' + '^INDIC[012S]_', '^INVALID_POSITION', '^KEYWORDSET_MAX', '^SC_AC_', '^SC_DOCUMENTOPTION_', + '^SC_CACHE_', '^SC_CHARSET_', '^SC_EFF_', '^SC_FONT_SIZE_MULTIPLIER', '^SC_INDIC', + '^SC_LINE_END_TYPE_', '^SC_PHASES_', '^SC_POPUP_', '^SC_PRINT_', '^SC_STATUS_', '^SC_TECHNOLOGY_', + '^SC_TYPE_', '^SC_WEIGHT_', '^SCE_', '^SCEN_', '^SCFIND_POSIX', '^SCI_', '^SCK_', '^SCLEX_', + '^UNDO_MAY_COALESCE' } local increments = { -- constants to increment by one '^MARKER_MAX', '^MARKNUM_', '^MAX_MARGIN', '^STYLE_', '^INDICATOR_' } local changed_setter = {} -- holds properties changed to setter functions local function to_en_us(name) - return name:gsub('([iIlL][oO])[uU]([rR])', '%1%2'): - gsub('ise$', 'ize'):gsub('([cC][eE][nN][tT])([rR])([eE])', '%1%3%2'): - gsub('CANCELLED', 'CANCELED') + return name:gsub('([iIlL][oO])[uU]([rR])', '%1%2'):gsub('ise$', 'ize'):gsub( + '([cC][eE][nN][tT])([rR])([eE])', '%1%3%2'):gsub('CANCELLED', 'CANCELED') end local function to_lua_name(camel_case) - return to_en_us(camel_case:gsub('([a-z])([A-Z])', '%1_%2'): - gsub('([A-Z])([A-Z][a-z])', '%1_%2'):lower()) -end -local function is_length(ptype, param) - return ptype == 'position' and param:find('^length') + return to_en_us(camel_case:gsub('([a-z])([A-Z])', '%1_%2'):gsub('([A-Z])([A-Z][a-z])', '%1_%2') + :lower()) end +local function is_length(ptype, param) return ptype == 'position' and param:find('^length') end local function is_index(ptype, param) - return ptype == 'int' and (param == 'style' or param == 'markerNumber' or - param == 'margin' or param == 'indicator' or param == 'selection') + return ptype == 'int' and + (param == 'style' or param == 'markerNumber' or param == 'margin' or param == 'indicator' or + param == 'selection') end for line in io.lines('../src/scintilla/include/Scintilla.iface') do @@ -92,15 +89,13 @@ for line in io.lines('../src/scintilla/include/Scintilla.iface') do functions[#functions + 1] = name functions[name] = {id, types[rtype], types[wtype], types[ltype]} elseif line:find('^get ') or line:find('^set ') then - local kind, rtype, name, id, wtype, param, ltype, param2 = - line:match(msg_patt) + local kind, rtype, name, id, wtype, param, ltype, param2 = line:match(msg_patt) if rtype:find('^%u') then rtype = 'int' end if wtype:find('^%u') then wtype = 'int' end if ltype:find('^%u') then ltype = 'int' end name = to_lua_name(name:gsub('[GS]et%f[%u]', '')) - if kind == 'get' and types[wtype] == types.int and - types[ltype] == types.int or wtype == 'bool' and ltype ~= '' or - changed_setter[name] then + if kind == 'get' and types[wtype] == types.int and types[ltype] == types.int or + (wtype == 'bool' and ltype ~= '') or changed_setter[name] then -- Special case getter/setter; handle as function. local fname = kind .. '_' .. name functions[#functions + 1] = fname @@ -121,9 +116,7 @@ for line in io.lines('../src/scintilla/include/Scintilla.iface') do if wtype ~= '' then prop[4] = types[wtype] end else prop[2] = id - if prop[1] == 0 then - prop[3] = types[wtype ~= '' and ltype == '' and wtype or ltype] - end + if prop[1] == 0 then prop[3] = types[wtype ~= '' and ltype == '' and wtype or ltype] end prop[4] = types[ltype ~= '' and wtype or ltype] end elseif line:find('cat Provisional') then @@ -136,8 +129,8 @@ end functions['auto_c_show'][3] = types.int -- was interpreted as 'length' functions['get_cur_line'][2] = types.position -- was interpreted as 'void' --- Manually adjust messages whose param or return types would be interpreted as --- 1-based numbers, but should not be, or vice-versa. +-- Manually adjust messages whose param or return types would be interpreted as 1-based numbers, +-- but should not be, or vice-versa. properties['length'][3] = types.int properties['style_at'][3] = types.index functions['marker_handle_from_line'][4] = types.index @@ -186,8 +179,7 @@ local M = {} --[[ This comment is for LuaDoc. --- -- 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. module('_SCINTILLA')]] ]=]) @@ -202,8 +194,8 @@ f:write(table.concat(constants, ',')) f:write('}\n\n') f:write([[ --- --- 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. @@ -218,14 +210,13 @@ f:write([[ -- @name functions M.functions = {]]) for _, func in ipairs(functions) do - f:write( - string.format('%s={%d,%d,%d,%d},', func, table.unpack(functions[func]))) + f:write(string.format('%s={%d,%d,%d,%d},', func, table.unpack(functions[func]))) end f:write('}\n\n') f:write([[ --- --- 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. -- @see functions @@ -233,8 +224,7 @@ f:write([[ -- @name properties M.properties = {]]) for _, property in ipairs(properties) do - f:write(string.format( - '%s={%d,%d,%d,%d},', property, table.unpack(properties[property]))) + f:write(string.format('%s={%d,%d,%d,%d},', property, table.unpack(properties[property]))) end f:write('}\n\n') f:write([[ @@ -243,17 +233,15 @@ f:write([[ -- @class table -- @name events M.events = {]]) -for _, event in ipairs(events) do - f:write(string.format('[%s]={%s},', event, events[event])) -end +for _, event in ipairs(events) do f:write(string.format('[%s]={%s},', event, events[event])) end f:write('}\n\n') f:write([[ local marker_number, indic_number, list_type, image_type = 0, 0, 0, 0 --- -- 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 local marknum = _SCINTILLA.next_marker_number() -- @see view.marker_define -- @name next_marker_number @@ -265,8 +253,8 @@ end --- -- 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 local indic_num = _SCINTILLA.next_indic_number() -- @see view.indic_style -- @name next_indic_number @@ -277,10 +265,9 @@ function M.next_indic_number() end --- --- 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 local list_type = _SCINTILLA.next_user_list_type() -- @see buffer.user_list_show -- @name next_user_list_type @@ -290,10 +277,10 @@ function M.next_user_list_type() end --- --- 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 local image_type = _SCINTILLA.next_image_type() -- @see view.register_image -- @see view.register_rgba_image diff --git a/scripts/gen_lua_c_api_tags.lua b/scripts/gen_lua_c_api_tags.lua index 1830652c..20c6dda3 100755 --- a/scripts/gen_lua_c_api_tags.lua +++ b/scripts/gen_lua_c_api_tags.lua @@ -4,10 +4,10 @@ local f = io.open('../modules/ansi_c/lua_tags', 'w') -- Lua header files define API functions in a way ctags cannot detect. -- For example: `LUA_API lua_State *(lua_newstate) (lua_Alloc f, void *ud);`. --- The function name enclosed in parenthesis is causing the problem. A regex --- must be used to capture those definitions. -local p = io.popen('ctags -o - --regex-c++="/\\(([a-zA-Z_]+)\\) +\\(/\\1/f/" '.. - '../src/lua/src/lua.h ../src/lua/src/lauxlib.h') +-- The function name enclosed in parenthesis is causing the problem. A regex must be used to +-- capture those definitions. +local p = io.popen('ctags -o - --regex-c++="/\\(([a-zA-Z_]+)\\) +\\(/\\1/f/" ' .. + '../src/lua/src/lua.h ../src/lua/src/lauxlib.h') for line in p:read('*a'):gmatch('[^\n]+') do -- Strip comment lines and replace file and ex_cmd fields with empty info. if not line:find('^!') then diff --git a/scripts/gen_plist.lua b/scripts/gen_plist.lua index ab6cee55..0ecabb68 100755 --- a/scripts/gen_plist.lua +++ b/scripts/gen_plist.lua @@ -19,6 +19,7 @@ for type in types:gmatch('(.-)[%],}]+') do end end +-- LuaFormatter off -- Generate and write the XML. local xml = {[[ <?xml version="1.0" encoding="UTF-8"?> @@ -51,13 +52,14 @@ xml[#xml + 1] = [[ <string>com.apple.xml-property-list</string> <string>com.netscape.javascript-source</string> <string>com.sun.java-source</string>]] +-- LuaFormatter on for i = 1, #languages do lang, exts = languages[i], extensions[languages[i]] if #exts > 0 then - xml[#xml + 1] = "\t\t\t\t<string>com.textadept."..lang:gsub(' ', '-').. - "-source</string>" + xml[#xml + 1] = "\t\t\t\t<string>com.textadept." .. lang:gsub(' ', '-') .. "-source</string>" end end +-- LuaFormatter off xml[#xml + 1] = [[ <string>net.daringfireball.markdown</string> <string>public.c-header</string> @@ -101,6 +103,7 @@ xml[#xml + 1] = [[ </array> <key>UTImportedTypeDeclarations</key> <array>]] +-- LuaFormatter on for i = 1, #languages do lang, exts = languages[i], extensions[languages[i]] if #exts > 0 then @@ -109,16 +112,13 @@ for i = 1, #languages do xml[#xml + 1] = "\t\t\t<dict>" xml[#xml + 1] = "\t\t\t\t<key>public.filename-extension</key>" xml[#xml + 1] = "\t\t\t\t<array>" - for j = 1, #exts do - xml[#xml + 1] = "\t\t\t\t\t<string>"..exts[j].."</string>" - end + for j = 1, #exts do xml[#xml + 1] = "\t\t\t\t\t<string>" .. exts[j] .. "</string>" end xml[#xml + 1] = "\t\t\t\t</array>" xml[#xml + 1] = "\t\t\t</dict>" xml[#xml + 1] = "\t\t\t<key>UTTypeDescription</key>" - xml[#xml + 1] = "\t\t\t<string>"..lang.." source</string>" + xml[#xml + 1] = "\t\t\t<string>" .. lang .. " source</string>" xml[#xml + 1] = "\t\t\t<key>UTTypeIdentifier</key>" - xml[#xml + 1] = "\t\t\t<string>com.textadept."..lang:gsub(' ', '-').. - "-source</string>" + xml[#xml + 1] = "\t\t\t<string>com.textadept." .. lang:gsub(' ', '-') .. "-source</string>" xml[#xml + 1] = "\t\t\t<key>UTTypeConformsTo</key>" xml[#xml + 1] = "\t\t\t<array>" xml[#xml + 1] = "\t\t\t\t<string>public.source-code</string>" @@ -126,6 +126,7 @@ for i = 1, #languages do xml[#xml + 1] = "\t\t</dict>" end end +-- LuaFormatter off xml[#xml + 1] = [[ </array> <key>CFBundleExecutable</key> @@ -151,6 +152,7 @@ xml[#xml + 1] = [[ </dict> </plist> ]] +-- LuaFormatter on f = io.open('../src/Info.plist', 'w') f:write(table.concat(xml, '\n')) f:close() diff --git a/scripts/gen_plots.sh b/scripts/gen_plots.sh index fcbe75c3..9cde1147 100755 --- a/scripts/gen_plots.sh +++ b/scripts/gen_plots.sh @@ -14,10 +14,8 @@ for rev in `hg tags | awk '{print $2}' | cut -d: -f1 | tac`; do date=`hg log -r $rev | grep ^date | cut -d: -f2- | tr + - | cut -d- -f1` hg update -r $rev -q timestamp=`date -d "$date" "+%s"` - counts=`cloc --force-lang=C,h --quiet --csv \ - --exclude-dir=doc,docs,scripts,themes,test,.github \ - --not-match-f=adeptsensedoc\\|tadoc . \ - | tail -n +3 | cut -d, -f2- | sort | tr '\n' ,` + counts=`cloc --force-lang=C,h --quiet --csv --exclude-dir=doc,docs,scripts,themes,test,.github \ + --not-match-f=adeptsensedoc\\|tadoc . | tail -n +3 | cut -d, -f2- | sort | tr '\n' ,` echo $timestamp,$counts done | lua -e " -- Filter counts from cloc into a data format readable by gnuplot. diff --git a/scripts/markdowndoc.lua b/scripts/markdowndoc.lua index 036f5082..bd0b4330 100644 --- a/scripts/markdowndoc.lua +++ b/scripts/markdowndoc.lua @@ -18,15 +18,15 @@ local SEE = '* [`%s`](#%s)\n' local TABLE = '<a id="%s"></a>\n#### `%s`\n\n' local TFIELD = '* `%s`: %s\n' local titles = { - [PARAM] = 'Parameters', [USAGE] = 'Usage', [RETURN] = 'Return', - [SEE] = 'See also', [TFIELD] = 'Fields' + [PARAM] = 'Parameters', [USAGE] = 'Usage', [RETURN] = 'Return', [SEE] = 'See also', + [TFIELD] = 'Fields' } -- Writes a LuaDoc description to the given file. -- @param f The markdown file being written to. -- @param description The description. --- @param name The name of the module the description belongs to. Used for --- headers in module descriptions. +-- @param name The name of the module the description belongs to. Used for headers in module +-- descriptions. local function write_description(f, description, name) -- Substitute custom [`code`]() link convention with [`code`](#code) links. local self_link = '(%[`([^`(]+)%(?%)?`%])%(%)' @@ -67,9 +67,7 @@ end local function write_hashmap(f, fmt, hashmap) if not hashmap or #hashmap == 0 then return end f:write(string.format(LIST_TITLE, titles[fmt])) - for _, name in ipairs(hashmap) do - f:write(string.format(fmt, name, hashmap[name] or '')) - end + for _, name in ipairs(hashmap) do f:write(string.format(fmt, name, hashmap[name] or '')) end f:write('\n') end @@ -81,13 +79,10 @@ function M.start(doc) f:write('## Textadept API Documentation\n\n') -- Create the table of contents. - for _, name in ipairs(modules) do - f:write(string.format(TOC, name, '#' .. name)) - end + for _, name in ipairs(modules) do f:write(string.format(TOC, name, '#' .. name)) end f:write('\n') - -- Create a map of doc objects to file names so their Markdown doc comments - -- can be extracted. + -- Create a map of doc objects to file names so their Markdown doc comments can be extracted. local filedocs = {} for _, name in ipairs(files) do filedocs[files[name].doc] = name end @@ -150,13 +145,12 @@ function M.start(doc) f:write('### Tables defined by `', name, '`\n\n') for _, tname in ipairs(tables) do local tbl = tables[tname] - if not tbl.name:find('%.') and - (name ~= '_G' or tbl.name == 'buffer' or tbl.name == 'view') then - tbl.name = name .. '.' .. tbl.name -- absolute name - elseif tbl.name ~= '_G.keys' and tbl.name ~= '_G.snippets' then - tbl.name = tbl.name:gsub('^_G%.', '') -- strip _G required for Luadoc + if not tname:find('%.') and (name ~= '_G' or tname == 'buffer' or tname == 'view') then + tname = name .. '.' .. tname -- absolute name + elseif tname ~= '_G.keys' and tname ~= '_G.snippets' then + tname = tname:gsub('^_G%.', '') -- strip _G required for Luadoc end - f:write(string.format(TABLE, tbl.name, tbl.name)) + f:write(string.format(TABLE, tname, tname)) write_description(f, tbl.description) write_hashmap(f, TFIELD, tbl.field) write_list(f, USAGE, tbl.usage) diff --git a/scripts/osx/textadept_osx b/scripts/osx/textadept_osx index e5cfc662..cea160ed 100755 --- a/scripts/osx/textadept_osx +++ b/scripts/osx/textadept_osx @@ -18,8 +18,8 @@ export CHARSETALIASDIR="$bundle_res/lib" # Strip out the argument added by macOS. if [ x`echo "x$1" | sed "s/^x-psn_.*//"` == x ]; then shift 1; fi -# Source '~/.textadept/osx_env.sh' to set variables like $PATH when opening -# Textadept.app from the Dock or the Finder. +# Source '~/.textadept/osx_env.sh' to set variables like $PATH when opening Textadept.app from +# the Dock or the Finder. if [ -f $HOME/.textadept/osx_env.sh ]; then . $HOME/.textadept/osx_env.sh; fi # Run Textadept. diff --git a/src/Makefile b/src/Makefile index 50c5ebbe..823de922 100644 --- a/src/Makefile +++ b/src/Makefile @@ -11,8 +11,7 @@ ifeq (win, $(findstring win, $(MAKECMDGOALS))) CFLAGS += -mms-bitfields CXXFLAGS += -mms-bitfields LUA_CFLAGS = -DLUA_BUILD_AS_DLL -DLUA_LIB - LDFLAGS = -static-libgcc -static-libstdc++ -Wl,--retain-symbols-file \ - -Wl,$(shell pwd)/lua.sym + LDFLAGS = -static-libgcc -static-libstdc++ -Wl,--retain-symbols-file -Wl,$(shell pwd)/lua.sym ifeq (, $(findstring curses, $(MAKECMDGOALS))) CXXFLAGS += -mwindows LDFLAGS += -liconv @@ -21,14 +20,11 @@ ifeq (win, $(findstring win, $(MAKECMDGOALS))) ifeq (, $(findstring curses, $(MAKECMDGOALS))) plat_flag = -DGTK GTK_CFLAGS = $(shell PKG_CONFIG_PATH=`pwd`/win32gtk/lib/pkgconfig \ - pkg-config --define-variable=prefix=win32gtk \ - --cflags gtk+-2.0) + pkg-config --define-variable=prefix=win32gtk --cflags gtk+-2.0) GTK_LIBS = $(shell PKG_CONFIG_PATH=`pwd`/win32gtk/lib/pkgconfig \ - pkg-config --define-variable=prefix=win32gtk \ - --libs gtk+-2.0 gmodule-2.0) + pkg-config --define-variable=prefix=win32gtk --libs gtk+-2.0 gmodule-2.0) GLIB_CFLAGS = $(shell PKG_CONFIG_PATH=`pwd`/win32gtk/lib/pkgconfig \ - pkg-config --define-variable=prefix=win32gtk \ - --cflags glib-2.0) + pkg-config --define-variable=prefix=win32gtk --cflags glib-2.0) else plat_flag = -DCURSES CURSES_CFLAGS = -DLIBICONV_STATIC -Iwin32curses/include @@ -46,15 +42,12 @@ else ifeq (osx, $(findstring osx, $(MAKECMDGOALS))) ifeq (, $(findstring curses, $(MAKECMDGOALS))) plat_flag = -DGTK GTK_CFLAGS = $(shell PKG_CONFIG_PATH=`pwd`/gtkosx/lib/pkgconfig \ - pkg-config --define-variable=prefix=gtkosx \ - --cflags gtk+-2.0) + pkg-config --define-variable=prefix=gtkosx --cflags gtk+-2.0) GTK_LIBS = $(shell PKG_CONFIG_PATH=`pwd`/gtkosx/lib/pkgconfig \ - pkg-config --define-variable=prefix=gtkosx \ - --libs gtk+-2.0 gmodule-2.0 gtk-mac-integration) \ - -framework Cocoa + pkg-config --define-variable=prefix=gtkosx --libs gtk+-2.0 gmodule-2.0 gtk-mac-integration) \ + -framework Cocoa GLIB_CFLAGS = $(shell PKG_CONFIG_PATH=`pwd`/gtkosx/lib/pkgconfig \ - pkg-config --define-variable=prefix=gtkosx \ - --cflags glib-2.0) + pkg-config --define-variable=prefix=gtkosx --cflags glib-2.0) else plat_flag = -DCURSES CURSES_LIBS = -lncurses @@ -83,8 +76,7 @@ else GTK_CFLAGS = $(shell pkg-config --cflags gtk+-2.0 gmodule-2.0) GTK_LIBS = $(shell pkg-config --libs gtk+-2.0 gmodule-2.0) else - GTK_CFLAGS = $(shell pkg-config --cflags gtk+-3.0 gmodule-2.0) \ - -Wno-deprecated-declarations + GTK_CFLAGS = $(shell pkg-config --cflags gtk+-3.0 gmodule-2.0) -Wno-deprecated-declarations GTK_LIBS = $(shell pkg-config --libs gtk+-3.0 gmodule-2.0) endif GLIB_CFLAGS = $(shell pkg-config --cflags glib-2.0) @@ -92,33 +84,27 @@ else else plat_flag = -DCURSES CURSES_CFLAGS = $(shell pkg-config --silence-errors --cflags ncursesw || \ - pkg-config --silence-errors --cflags ncurses || \ - pkg-config --silence-errors --cflags curses) + pkg-config --silence-errors --cflags ncurses || pkg-config --silence-errors --cflags curses) CURSES_LIBS = $(shell pkg-config --silence-errors --libs ncursesw || \ - pkg-config --silence-errors --libs ncurses || \ - pkg-config --silence-errors --libs curses || \ - echo -lncursesw) + pkg-config --silence-errors --libs ncurses || pkg-config --silence-errors --libs curses || \ + echo -lncursesw) install_targets = ../textadept-curses endif endif -version = $(shell grep -m 1 _RELEASE ../core/init.lua | cut -d ' ' -f4- | \ - tr ' ' '_' | tr -d "'") +version = $(shell grep -m 1 _RELEASE ../core/init.lua | cut -d ' ' -f4- | tr ' ' '_' | tr -d "'") WGET = wget -O $@ # Scintilla. -sci_flags = -pedantic $(plat_flag) -DSCI_LEXER -DNDEBUG -Iscintilla/include \ - -Iscintilla/src -Ilexilla/include -Ilexilla/lexlib -Wall - -sci_objs = AutoComplete.o CallTip.o CaseConvert.o CaseFolder.o CellBuffer.o \ - CharClassify.o ContractionState.o Decoration.o Document.o \ - EditModel.o Editor.o EditView.o Indicator.o KeyMap.o LineMarker.o \ - MarginView.o PerLine.o PositionCache.o RESearch.o RunStyles.o \ - ScintillaBase.o Selection.o Style.o UniConversion.o UniqueString.o \ - ViewStyle.o XPM.o -sci_lex_objs = Accessor.o CharacterCategory.o CharacterSet.o DefaultLexer.o \ - LexerBase.o LexerModule.o LexerNoExceptions.o LexerSimple.o \ - PropSetSimple.o StyleContext.o WordList.o +sci_flags = -pedantic $(plat_flag) -DSCI_LEXER -DNDEBUG -Iscintilla/include -Iscintilla/src \ + -Ilexilla/include -Ilexilla/lexlib -Wall + +sci_objs = AutoComplete.o CallTip.o CaseConvert.o CaseFolder.o CellBuffer.o CharClassify.o \ + ContractionState.o Decoration.o Document.o EditModel.o Editor.o EditView.o Indicator.o KeyMap.o \ + LineMarker.o MarginView.o PerLine.o PositionCache.o RESearch.o RunStyles.o ScintillaBase.o \ + Selection.o Style.o UniConversion.o UniqueString.o ViewStyle.o XPM.o +sci_lex_objs = Accessor.o CharacterCategory.o CharacterSet.o DefaultLexer.o LexerBase.o \ + LexerModule.o LexerNoExceptions.o LexerSimple.o PropSetSimple.o StyleContext.o WordList.o sci_lexer_objs = LexLPeg.o LexLPeg-curses.o sci_gtk_objs = PlatGTK.o ScintillaGTK.o ScintillaGTKAccessible.o sci_curses_objs = ScintillaCurses.o @@ -130,22 +116,19 @@ ta_flags = -std=c99 -pedantic $(plat_flag) -Iscintilla/include -Igtdialog -Wall textadept_gtk_objs = textadept.o textadept_curses_objs = textadept-curses.o textadept_objs = $(textadept_gtk_objs) $(textadept_curses_objs) -lua_objs = lapi.o lcode.o lctype.o ldebug.o ldo.o ldump.o lfunc.o lgc.o \ - linit.o llex.o lmem.o lobject.o lopcodes.o lparser.o lstate.o \ - lstring.o ltable.o ltm.o lundump.o lvm.o lzio.o \ - lauxlib.o lbaselib.o lcorolib.o ldblib.o liolib.o lmathlib.o \ - loadlib.o lstrlib.o ltablib.o lutf8lib.o +lua_objs = lapi.o lcode.o lctype.o ldebug.o ldo.o ldump.o lfunc.o lgc.o linit.o llex.o lmem.o \ + lobject.o lopcodes.o lparser.o lstate.o lstring.o ltable.o ltm.o lundump.o lvm.o lzio.o \ + lauxlib.o lbaselib.o lcorolib.o ldblib.o liolib.o lmathlib.o loadlib.o lstrlib.o ltablib.o \ + lutf8lib.o lua_oslib_objs = loslib.o loslib-curses.o lua_lib_objs = lpcap.o lpcode.o lpprint.o lptree.o lpvm.o lfs.o gtdialog_objs = gtdialog.o gtdialog-curses.o termkey_unix_objs = driver-ti.o driver-csi.o termkey_win32_objs = driver-win32-pdcurses.o termkey_objs = termkey.o $(termkey_unix_objs) $(termkey_win32_objs) -cdk_objs = $(addprefix cdk-, binding.o buttonbox.o cdk.o cdk_display.o \ - cdk_objs.o cdkscreen.o draw.o entry.o fselect.o \ - itemlist.o label.o mentry.o popup_label.o \ - scroll.o scroller.o select_file.o selection.o \ - slider.o traverse.o version.o) +cdk_objs = $(addprefix cdk-, binding.o buttonbox.o cdk.o cdk_display.o cdk_objs.o cdkscreen.o \ + draw.o entry.o fselect.o itemlist.o label.o mentry.o popup_label.o scroll.o scroller.o \ + select_file.o selection.o slider.o traverse.o version.o) # Add debugging symbols and disable optimizations when DEBUG=1. # Notes: @@ -176,8 +159,7 @@ $(sci_objs): %.o: scintilla/src/%.cxx $(sci_lex_objs): %.o: lexilla/lexlib/%.cxx $(CROSS)$(CXX) -c $(CXXFLAGS) $(sci_flags) $< -o $@ $(sci_lexer_objs): LexLPeg.cxx - $(CROSS)$(CXX) -c $(CXXFLAGS) $(LUA_CFLAGS) $(sci_flags) -DNO_SCITE -DNO_DLL \ - $< -o $@ + $(CROSS)$(CXX) -c $(CXXFLAGS) $(LUA_CFLAGS) $(sci_flags) -DNO_SCITE -DNO_DLL $< -o $@ $(sci_gtk_objs): %.o: scintilla/gtk/%.cxx $(CROSS)$(CXX) -c $(CXXFLAGS) $(sci_flags) $(GTK_CFLAGS) $< -o $@ scintilla-marshal.o: scintilla/gtk/scintilla-marshal.c @@ -193,11 +175,10 @@ $(lua_oslib_objs): lua/src/loslib.c $(lua_lib_objs): %.o: lua/src/lib/%.c $(CROSS)$(CC) -c $(CFLAGS) $(LUA_CFLAGS) $< -o $@ $(gtdialog_objs): gtdialog/gtdialog.c - $(CROSS)$(CC) -c $(CFLAGS) -std=c99 -pedantic $(plat_flag) -DNOHELP \ - -DLIBRARY $(gtdialog_flags) $< -o $@ + $(CROSS)$(CC) -c $(CFLAGS) -std=c99 -pedantic $(plat_flag) -DNOHELP -DLIBRARY $(gtdialog_flags) \ + $< -o $@ $(cdk_objs): cdk-%.o: cdk/%.c - $(CROSS)$(CC) -c $(CFLAGS) -D_GNU_SOURCE -Itermkey -Icdk $(CURSES_CFLAGS) $< \ - -o $@ + $(CROSS)$(CC) -c $(CFLAGS) -D_GNU_SOURCE -Itermkey -Icdk $(CURSES_CFLAGS) $< -o $@ $(termkey_objs): %.o: termkey/%.c $(CROSS)$(CC) -c $(CFLAGS) -std=c99 $(CURSES_CFLAGS) $< -o $@ textadept_rc.o: textadept.rc ; $(CROSS)$(WINDRES) $< $@ @@ -205,42 +186,35 @@ textadept_rc.o: textadept.rc ; $(CROSS)$(WINDRES) $< $@ # Target-specific variables. LexLPeg-curses.o: sci_flags += -DCURSES $(CURSES_CFLAGS) -lua_dep_objs = LexLPeg.o LexLPeg-curses.o textadept.o textadept-curses.o \ - $(lua_objs) $(lua_oslib_objs) $(lua_lib_objs) +lua_dep_objs = LexLPeg.o LexLPeg-curses.o textadept.o textadept-curses.o $(lua_objs) \ + $(lua_oslib_objs) $(lua_lib_objs) $(lua_dep_objs): LUA_CFLAGS += -Ilua/src $(textadept_gtk_objs): ta_flags += $(GTK_CFLAGS) -$(textadept_curses_objs): \ - ta_flags += -Iscintilla/curses -Itermkey -Icdk $(CURSES_CFLAGS) +$(textadept_curses_objs): ta_flags += -Iscintilla/curses -Itermkey -Icdk $(CURSES_CFLAGS) loslib.o: LUA_CFLAGS += -DGTK $(GLIB_CFLAGS) gtdialog.o: gtdialog_flags += $(GTK_CFLAGS) gtdialog-curses.o: gtdialog_flags += -I. -Icdk $(CURSES_CFLAGS) # Executables. -textadept: $(sci_objs) $(sci_lex_objs) LexLPeg.o $(sci_gtk_objs) \ - scintilla-marshal.o textadept.o $(lua_objs) loslib.o \ - $(lua_lib_objs) gtdialog.o +textadept: $(sci_objs) $(sci_lex_objs) LexLPeg.o $(sci_gtk_objs) scintilla-marshal.o textadept.o \ + $(lua_objs) loslib.o $(lua_lib_objs) gtdialog.o $(CROSS)$(CXX) $(CXXFLAGS) -o ../$@ $^ $(GTK_LIBS) $(LDFLAGS) -textadept-curses: $(sci_objs) $(sci_lex_objs) LexLPeg-curses.o \ - $(sci_curses_objs) textadept-curses.o $(lua_objs) \ - loslib-curses.o $(lua_lib_objs) gtdialog-curses.o termkey.o \ - $(termkey_unix_objs) $(cdk_objs) +textadept-curses: $(sci_objs) $(sci_lex_objs) LexLPeg-curses.o $(sci_curses_objs) \ + textadept-curses.o $(lua_objs) loslib-curses.o $(lua_lib_objs) gtdialog-curses.o termkey.o \ + $(termkey_unix_objs) $(cdk_objs) $(CROSS)$(CXX) $(CXXFLAGS) -o ../$@ $^ $(CURSES_LIBS) $(LDFLAGS) -textadept.exe: $(sci_objs) $(sci_lex_objs) LexLPeg.o $(sci_gtk_objs) \ - scintilla-marshal.o textadept.o textadept_rc.o $(lua_objs) \ - loslib.o $(lua_lib_objs) gtdialog.o +textadept.exe: $(sci_objs) $(sci_lex_objs) LexLPeg.o $(sci_gtk_objs) scintilla-marshal.o \ + textadept.o textadept_rc.o $(lua_objs) loslib.o $(lua_lib_objs) gtdialog.o $(CROSS)$(CXX) $(CXXFLAGS) -o ../$@ $^ $(GTK_LIBS) $(LDFLAGS) -textadept-curses.exe: $(sci_objs) $(sci_lex_objs) LexLPeg-curses.o \ - $(sci_curses_objs) textadept-curses.o textadept_rc.o \ - $(lua_objs) loslib-curses.o $(lua_lib_objs) \ - gtdialog-curses.o termkey.o $(termkey_win32_objs) \ - $(cdk_objs) +textadept-curses.exe: $(sci_objs) $(sci_lex_objs) LexLPeg-curses.o $(sci_curses_objs) \ + textadept-curses.o textadept_rc.o $(lua_objs) loslib-curses.o $(lua_lib_objs) gtdialog-curses.o \ + termkey.o $(termkey_win32_objs) $(cdk_objs) $(CROSS)$(CXX) $(CXXFLAGS) -o ../$@ $^ $(CURSES_LIBS) $(LDFLAGS) # Install/uninstall. -install: $(install_targets) | ../core ../docs ../init.lua ../lexers ../LICENSE \ - ../modules ../themes +install: $(install_targets) | ../core ../docs ../init.lua ../lexers ../LICENSE ../modules ../themes install -d $(DESTDIR)$(bin_dir) $(DESTDIR)$(data_dir) install $^ $(DESTDIR)$(data_dir) cp -rL $| $(DESTDIR)$(data_dir) @@ -252,14 +226,11 @@ install: $(install_targets) | ../core ../docs ../init.lua ../lexers ../LICENSE \ if [ -d "$(PIXMAPS_DIR)" ]; then \ install -d $(DESTDIR)$(PIXMAPS_DIR); \ ln -s $(data_dir)/core/images/textadept.svg $(DESTDIR)$(PIXMAPS_DIR); \ - ln -s $(data_dir)/core/images/ta_48x48.png \ - $(DESTDIR)$(PIXMAPS_DIR)/textadept.png; \ + ln -s $(data_dir)/core/images/ta_48x48.png $(DESTDIR)$(PIXMAPS_DIR)/textadept.png; \ fi uninstall: rm -r $(DESTDIR)$(bin_dir)/textadept* $(DESTDIR)$(data_dir) - if [ -d "$(XDG_DATA_DIR)" ]; then \ - rm $(DESTDIR)$(XDG_DATA_DIR)/textadept*.desktop; \ - fi + if [ -d "$(XDG_DATA_DIR)" ]; then rm $(DESTDIR)$(XDG_DATA_DIR)/textadept*.desktop; fi if [ -d "$(PIXMAPS_DIR)" ]; then rm $(DESTDIR)$(PIXMAPS_DIR)/textadept*; fi # Clean. @@ -277,12 +248,8 @@ ta_home = $(shell dirname `pwd`) docs: luadoc manual manual: ../docs/api.md $(wildcard ../docs/*.md) | ../docs/_layouts/default.html - for file in $(basename $^); do \ - cat $| | ../scripts/fill_layout.lua $$file.md > $$file.html; \ - done - sed -i \ - "s/\(\# Textadept\).\+\?\(Manual\|API\)/\1 $(subst _, ,$(version)) \2/;" \ - ../docs/*.md + for file in $(basename $^); do cat $| | ../scripts/fill_layout.lua $$file.md > $$file.html; done + sed -i "s/\(\# Textadept\).\+\?\(Manual\|API\)/\1 $(subst _, ,$(version)) \2/;" ../docs/*.md luadoc: ../core $(modules) ../lexers/lexer.lua | ../modules/lua/lua.luadoc cd ../scripts && luadoc --doclet markdowndoc $^ > ../docs/api.md cd ../modules && luadoc -d lua --doclet lua/tadoc $^ --ta-home=$(ta_home) @@ -299,16 +266,12 @@ endif osxapp = Textadept.app osxapp_bin = $(osxapp)/Contents/MacOS osxapp_res = $(osxapp)/Contents/Resources -osxapp_libs = libatk-1.0.0.dylib libcairo.2.dylib libexpat.1.dylib \ - libffi.6.dylib libfontconfig.1.dylib libfreetype.6.dylib \ - libgdk_pixbuf-2.0.0.dylib libgdk-quartz-2.0.0.dylib \ - libgio-2.0.0.dylib libglib-2.0.0.dylib libgmodule-2.0.0.dylib \ - libgobject-2.0.0.dylib libgthread-2.0.0.dylib \ - libgtkmacintegration.2.dylib libgtk-quartz-2.0.0.dylib \ - libharfbuzz.0.dylib libintl.8.dylib libpango-1.0.0.dylib \ - libpangocairo-1.0.0.dylib libpangoft2-1.0.0.dylib \ - libpixman-1.0.dylib libpng16.16.dylib charset.alias \ - gdk-pixbuf-2.0 gtk-2.0 +osxapp_libs = libatk-1.0.0.dylib libcairo.2.dylib libexpat.1.dylib libffi.6.dylib \ + libfontconfig.1.dylib libfreetype.6.dylib libgdk_pixbuf-2.0.0.dylib libgdk-quartz-2.0.0.dylib \ + libgio-2.0.0.dylib libglib-2.0.0.dylib libgmodule-2.0.0.dylib libgobject-2.0.0.dylib \ + libgthread-2.0.0.dylib libgtkmacintegration.2.dylib libgtk-quartz-2.0.0.dylib \ + libharfbuzz.0.dylib libintl.8.dylib libpango-1.0.0.dylib libpangocairo-1.0.0.dylib \ + libpangoft2-1.0.0.dylib libpixman-1.0.dylib libpng16.16.dylib charset.alias gdk-pixbuf-2.0 gtk-2.0 release-all: release win32-release osx-release #modules-release @@ -317,8 +280,8 @@ ifneq (, $(shell hg summary 2>/dev/null)) else archive = cd ../ && git archive HEAD --prefix src/$(1)/ | tar -xf - endif -modules = css ctags debugger export file_diff html lsp lua_repl open_file_mode \ - python rest ruby spellcheck yaml +modules = css ctags debugger export file_diff html lsp lua_repl open_file_mode python rest ruby \ + spellcheck yaml $(basedir).linux: ; $(call archive,$@) release: $(basedir).linux @@ -330,8 +293,7 @@ release: $(basedir).linux $(basedir).win32: ; $(call archive,$@) win32-release: $(basedir).win32 make -j4 clean win32-deps - cp win32gtk/bin/*.dll $< && cp -r win32gtk/etc \ - win32gtk/lib win32gtk/share $< + cp win32gtk/bin/*.dll $< && cp -r win32gtk/etc win32gtk/lib win32gtk/share $< rm -r $</lib/*.a $</lib/glib-2.0 $</lib/gtk-2.0/include $</lib/pkgconfig make -j4 win32 make -j4 win32-curses @@ -428,8 +390,7 @@ lua: lua.patch | $(lua_tgz) mkdir $@ && tar xzf $| -C $@ && mv $@/*/* $@ patch -d $@ -N -p1 < $< lualibs: lua/src/lib/lpeg lua/src/lib/lfs -lua/src/lib/lpeg: | $(lpeg_tgz) - mkdir -p $@ && tar xzf $| -C $@ && mv $@/*/*.c $@/*/*.h $(dir $@) +lua/src/lib/lpeg: | $(lpeg_tgz) ; mkdir -p $@ && tar xzf $| -C $@ && mv $@/*/*.c $@/*/*.h $(dir $@) lua/src/lib/lfs: | $(lfs_zip) if [ -d $@ ]; then rm -r $@; fi mkdir -p $@ && unzip -d $(dir $@) -j $| "*/src/*.c" "*/src/*.h" @@ -465,13 +426,12 @@ gtkosx: | $(gtkosx_tgz) ; mkdir $@ && tar xzf $| -C $@ && mv $@/*/* $@ $(cloc): ; $(WGET) http://prdownloads.sourceforge.net/cloc/$@ clean-deps: - rm -rf scintilla ../lexers lexilla $(LexLPeg) lua gtdialog cdk termkey \ - win32gtk win32curses gtkosx $(scinterm_zip) $(scintillua_zip) \ - $(gtdialog_zip) + rm -rf scintilla ../lexers lexilla $(LexLPeg) lua gtdialog cdk termkey win32gtk win32curses \ + gtkosx $(scinterm_zip) $(scintillua_zip) $(gtdialog_zip) # Count lines of code. -sources = ../core ../modules/ansi_c ../modules/lua ../modules/textadept \ - textadept.c Makefile ../init.lua +sources = ../core ../modules/ansi_c ../modules/lua ../modules/textadept textadept.c Makefile \ + ../init.lua count: $(cloc) ; perl $< $(sources) --not-match-f=tadoc.lua plots: ; ../scripts/gen_plots.sh diff --git a/src/textadept.c b/src/textadept.c index f2e4129e..dc671d3a 100644 --- a/src/textadept.c +++ b/src/textadept.c @@ -64,9 +64,8 @@ #if GTK typedef GtkWidget Scintilla; // Translate GTK 2.x API to GTK 3.0 for compatibility. -#if GTK_CHECK_VERSION(3,0,0) -#define gtk_combo_box_entry_new_with_model(m,_) \ - gtk_combo_box_new_with_model_and_entry(m) +#if GTK_CHECK_VERSION(3, 0, 0) +#define gtk_combo_box_entry_new_with_model(m, _) gtk_combo_box_new_with_model_and_entry(m) #define gtk_combo_box_entry_set_text_column gtk_combo_box_set_entry_text_column #define GTK_COMBO_BOX_ENTRY GTK_COMBO_BOX #endif @@ -75,21 +74,19 @@ typedef GtkWidget Scintilla; #else #define ID "\\\\.\\pipe\\textadept.editor" // Win32 single-instance functionality. -#define g_application_command_line_get_arguments(_,__) \ - g_strsplit(buf, "\n", 0); argc = g_strv_length(argv) +#define g_application_command_line_get_arguments(_, __) \ + g_strsplit(buf, "\n", 0); \ + argc = g_strv_length(argv) #define g_application_command_line_get_cwd(_) argv[0] -#define g_application_register(_,__,___) true -#define g_application_get_is_remote(_) \ - (WaitNamedPipe(ID, NMPWAIT_WAIT_FOREVER) != 0) +#define g_application_register(_, __, ___) true +#define g_application_get_is_remote(_) (WaitNamedPipe(ID, NMPWAIT_WAIT_FOREVER) != 0) #define gtk_main() \ HANDLE pipe = NULL, thread = NULL; \ if (!g_application_get_is_remote(app)) \ - pipe = CreateNamedPipe( \ - ID, PIPE_ACCESS_INBOUND, PIPE_WAIT, 1, 0, 0, INFINITE, NULL), \ - thread = CreateThread(NULL, 0, &pipe_listener, pipe, 0, NULL); \ + pipe = CreateNamedPipe(ID, PIPE_ACCESS_INBOUND, PIPE_WAIT, 1, 0, 0, INFINITE, NULL), \ + thread = CreateThread(NULL, 0, &pipe_listener, pipe, 0, NULL); \ gtk_main(); \ - if (pipe && thread) \ - TerminateThread(thread, 0), CloseHandle(thread), CloseHandle(pipe); + if (pipe && thread) TerminateThread(thread, 0), CloseHandle(thread), CloseHandle(pipe); #endif #elif CURSES typedef void Scintilla; @@ -102,8 +99,7 @@ typedef void Scintilla; static char *textadept_home, *platform; -// User interface objects and related macros for GTK and curses -// interoperability. +// User interface objects and related macros for GTK and curses interoperability. static Scintilla *focused_view, *dummy_view, *command_entry; #if GTK // GTK window. @@ -120,8 +116,8 @@ typedef GtkWidget Pane; static GtkWidget *findbox, *find_entry, *repl_entry, *find_label, *repl_label; #define find_text gtk_entry_get_text(GTK_ENTRY(find_entry)) #define repl_text gtk_entry_get_text(GTK_ENTRY(repl_entry)) -#define set_entry_text(entry, text) gtk_entry_set_text( \ - GTK_ENTRY(entry == find_text ? find_entry : repl_entry), text) +#define set_entry_text(entry, text) \ + gtk_entry_set_text(GTK_ENTRY(entry == find_text ? find_entry : repl_entry), text) typedef GtkWidget *FindButton; static FindButton find_next, find_prev, replace, replace_all; static GtkWidget *match_case, *whole_word, *regex, *in_files; @@ -139,7 +135,7 @@ static ListStore *find_history, *repl_history; // curses window. typedef struct Pane { int y, x, rows, cols, split_size; // dimensions - enum {SINGLE, VSPLIT, HSPLIT} type; // pane type + enum { SINGLE, VSPLIT, HSPLIT } type; // pane type WINDOW *win; // either the Scintilla curses window or the split bar's window Scintilla *view; // Scintilla view for a non-split view struct Pane *child1, *child2; // each pane in a split view @@ -147,37 +143,37 @@ typedef struct Pane { static Pane *pane; TermKey *ta_tk; // global for CDK use #define SS(view, msg, w, l) scintilla_send_message(view, msg, w, l) -#define focus_view(view) ( \ - focused_view ? SS(focused_view, SCI_SETFOCUS, 0, 0) : 0, \ - SS(view, SCI_SETFOCUS, 1, 0)) +#define focus_view(view) \ + (focused_view ? SS(focused_view, SCI_SETFOCUS, 0, 0) : 0, SS(view, SCI_SETFOCUS, 1, 0)) // curses find & replace pane. static CDKSCREEN *findbox; static CDKENTRY *find_entry, *repl_entry, *focused_entry; static char *find_text, *repl_text, *find_label, *repl_label; #define set_entry_text(entry, text) copyfree(&entry, text) -typedef enum {find_next, replace, find_prev, replace_all} FindButton; -static bool find_options[4], *match_case = &find_options[0], - *whole_word = &find_options[1], *regex = &find_options[2], - *in_files = &find_options[3]; +typedef enum { find_next, replace, find_prev, replace_all } FindButton; +static bool find_options[4], *match_case = &find_options[0], *whole_word = &find_options[1], + *regex = &find_options[2], *in_files = &find_options[3]; static char *button_labels[4], *option_labels[4]; typedef char *ListStore; static ListStore find_history[10], repl_history[10]; #define checked(find_option) *find_option // Use pointer arithmetic to highlight/unhighlight options as necessary. -#define toggle(o, on) do { \ - if (*o != on) *o = on, option_labels[o - match_case] += *o ? -4 : 4; \ -} while (false) +#define toggle(o, on) \ + do { \ + if (*o != on) *o = on, option_labels[o - match_case] += *o ? -4 : 4; \ + } while (false) #define set_label_text(label, text) copyfree(&label, text) #define set_button_label(button, label) copyfree(&button_labels[button], label) -// Prepend "</R>" to each option label because pointer arithmetic will be used -// to make the "</R>" visible or invisible (thus highlighting or unhighlighting -// the label) depending on whether or not the option is enabled by the user. -#define set_option_label(option, i, label) do { \ - lua_pushstring(L, "</R>"), lua_pushstring(L, label), lua_concat(L, 2); \ - if (option_labels[i] && !*option) option_labels[i] -= 4; \ - copyfree(&option_labels[i], lua_tostring(L, -1)); \ - if (!*option) option_labels[i] += 4; \ -} while (false) +// Prepend "</R>" to each option label because pointer arithmetic will be used to make the +// "</R>" visible or invisible (thus highlighting or unhighlighting the label) depending on +// whether or not the option is enabled by the user. +#define set_option_label(option, i, label) \ + do { \ + lua_pushstring(L, "</R>"), lua_pushstring(L, label), lua_concat(L, 2); \ + if (option_labels[i] && !*option) option_labels[i] -= 4; \ + copyfree(&option_labels[i], lua_tostring(L, -1)); \ + if (!*option) option_labels[i] += 4; \ + } while (false) #define find_active(w) (w != NULL) // Curses command entry and statusbar. static bool command_entry_active; @@ -192,7 +188,7 @@ static bool quitting; static bool initing, closing, tab_sync, dialog_active; static int tabs = 1; // int for more options than true/false #define show_tabs(condition) tabs && (condition || tabs > 1) -enum {SVOID, SINT, SLEN, SINDEX, SCOLOR, SBOOL, SKEYMOD, SSTRING, SSTRINGRET}; +enum { SVOID, SINT, SLEN, SINDEX, SCOLOR, SBOOL, SKEYMOD, SSTRING, SSTRINGRET }; // Forward declarations. static void new_buffer(sptr_t); @@ -205,13 +201,11 @@ LUALIB_API int os_spawn_pushfds(lua_State *), os_spawn_readfds(lua_State *); * Emits an event. * @param L The Lua state. * @param name The event name. - * @param ... Arguments to pass with the event. Each pair of arguments should be - * a Lua type followed by the data value itself. For LUA_TLIGHTUSERDATA and - * LUA_TTABLE types, push the data values to the stack and give the value - * returned by luaL_ref(); luaL_unref() will be called appropriately. The list - * must be terminated with a -1. - * @return true or false depending on the boolean value returned by the event - * handler, if any. + * @param ... Arguments to pass with the event. Each pair of arguments should be a Lua type + * followed by the data value itself. For LUA_TLIGHTUSERDATA and LUA_TTABLE types, push the + * data values to the stack and give the value returned by luaL_ref(); luaL_unref() will be + * called appropriately. The list must be terminated with a -1. + * @return true or false depending on the boolean value returned by the event handler, if any. */ static bool emit(lua_State *L, const char *name, ...) { bool ret = false; @@ -221,17 +215,18 @@ static bool emit(lua_State *L, const char *name, ...) { int n = 1; va_list ap; va_start(ap, name); - for (int type = va_arg(ap, int); type != -1; type = va_arg(ap, int), n++) - switch (type) { - case LUA_TBOOLEAN: lua_pushboolean(L, va_arg(ap, int)); break; - case LUA_TNUMBER: lua_pushinteger(L, va_arg(ap, int)); break; - case LUA_TSTRING: lua_pushstring(L, va_arg(ap, char *)); break; - case LUA_TLIGHTUSERDATA: case LUA_TTABLE: { - sptr_t arg = va_arg(ap, sptr_t); - lua_rawgeti(L, LUA_REGISTRYINDEX, arg); - luaL_unref(L, LUA_REGISTRYINDEX, arg); - break; - } default: lua_pushnil(L); + sptr_t arg; + for (int type = va_arg(ap, int); type != -1; type = va_arg(ap, int), n++) switch (type) { + case LUA_TBOOLEAN: lua_pushboolean(L, va_arg(ap, int)); break; + case LUA_TNUMBER: lua_pushinteger(L, va_arg(ap, int)); break; + case LUA_TSTRING: lua_pushstring(L, va_arg(ap, char *)); break; + case LUA_TLIGHTUSERDATA: + case LUA_TTABLE: + arg = va_arg(ap, sptr_t); + lua_rawgeti(L, LUA_REGISTRYINDEX, arg); + luaL_unref(L, LUA_REGISTRYINDEX, arg); + break; + default: lua_pushnil(L); } va_end(ap); if (lua_pcall(L, n, 1, 0) != LUA_OK) { @@ -239,7 +234,8 @@ static bool emit(lua_State *L, const char *name, ...) { const char *argv[] = {"--title", "Error", "--text", lua_tostring(L, -1)}; free(gtdialog(GTDIALOG_TEXTBOX, 4, argv)); return (lua_pop(L, 2), ret); // result, events - } else ret = lua_toboolean(L, -1); + } else + ret = lua_toboolean(L, -1); return (lua_pop(L, 2), ret); // result, events } @@ -251,8 +247,7 @@ static int process(GApplication *_, GApplicationCommandLine *line, void *buf) { char **argv = g_application_command_line_get_arguments(line, &argc); if (argc > 1) { lua_newtable(lua); - lua_pushstring(lua, g_application_command_line_get_cwd(line)), - lua_rawseti(lua, -2, -1); + lua_pushstring(lua, g_application_command_line_get_cwd(line)), lua_rawseti(lua, -2, -1); while (--argc) lua_pushstring(lua, argv[argc]), lua_rawseti(lua, -2, argc); emit(lua, "command_line", LUA_TTABLE, luaL_ref(lua, LUA_REGISTRYINDEX), -1); } @@ -263,8 +258,7 @@ static int process(GApplication *_, GApplicationCommandLine *line, void *buf) { #if CURSES /** - * Copies the given value to the given string after freeing that string's - * existing value (if any). + * Copies the given value to the given string after freeing that string's existing value (if any). * The given string must be freed when finished. * @param s The address of the string to copy value to. * @param value String value to copy. It may be freed immediately. @@ -280,12 +274,12 @@ static void copyfree(char **s, const char *value) { * @param store The ListStore to add the text to. * @param text The text to add. */ -static void add_to_history(ListStore* store, const char *text) { +static void add_to_history(ListStore *store, const char *text) { #if GTK - // Note: GtkComboBoxEntry key navigation behaves contrary to command line - // history navigation. Down cycles from newer to older, and up cycles from - // older to newer. In order to mimic traditional command line history - // navigation, append to the list instead of prepending to it. + // Note: GtkComboBoxEntry key navigation behaves contrary to command line history + // navigation. Down cycles from newer to older, and up cycles from older to newer. In order to + // mimic traditional command line history navigation, append to the list instead of prepending + // to it. int n = gtk_tree_model_iter_n_children(GTK_TREE_MODEL(store), NULL); GtkTreeIter iter; if (n > 9) @@ -296,8 +290,7 @@ static void add_to_history(ListStore* store, const char *text) { gtk_tree_model_iter_nth_child(GTK_TREE_MODEL(store), &iter, NULL, n - 1), gtk_tree_model_get(GTK_TREE_MODEL(store), &iter, 0, &last_text, -1); if (!last_text || strcmp(text, last_text) != 0) - gtk_list_store_append(store, &iter), - gtk_list_store_set(store, &iter, 0, text, -1); + gtk_list_store_append(store, &iter), gtk_list_store_set(store, &iter, 0, text, -1); g_free(last_text); #elif CURSES if (!text || (store[0] && strcmp(text, store[0]) == 0)) return; @@ -315,8 +308,7 @@ static void find_clicked(FindButton button, void *L) { else add_to_history(repl_history, repl_text); if (button == find_next || button == find_prev) - emit( - L, "find", LUA_TSTRING, find_text, LUA_TBOOLEAN, button == find_next, -1); + emit(L, "find", LUA_TSTRING, find_text, LUA_TBOOLEAN, button == find_next, -1); else if (button == replace) { emit(L, "replace", LUA_TSTRING, repl_text, -1); emit(L, "find", LUA_TSTRING, find_text, LUA_TBOOLEAN, true, -1); @@ -325,24 +317,16 @@ static void find_clicked(FindButton button, void *L) { } /** `find.find_next()` Lua function. */ -static int click_find_next(lua_State *L) { - return (find_clicked(find_next, L), 0); -} +static int click_find_next(lua_State *L) { return (find_clicked(find_next, L), 0); } /** `find.find_prev()` Lua function. */ -static int click_find_prev(lua_State *L) { - return (find_clicked(find_prev, L), 0); -} +static int click_find_prev(lua_State *L) { return (find_clicked(find_prev, L), 0); } /** `find.replace()` Lua function. */ -static int click_replace(lua_State *L) { - return (find_clicked(replace, L), 0); -} +static int click_replace(lua_State *L) { return (find_clicked(replace, L), 0); } /** `find.replace_all()` Lua function. */ -static int click_replace_all(lua_State *L) { - return (find_clicked(replace_all, L), 0); -} +static int click_replace_all(lua_State *L) { return (find_clicked(replace_all, L), 0); } #if CURSES /** @@ -356,7 +340,8 @@ static void refresh_pane(Pane *pane) { } else if (pane->type == HSPLIT) { mvwhline(pane->win, 0, 0, 0, pane->cols), wrefresh(pane->win); refresh_pane(pane->child1), refresh_pane(pane->child2); - } else scintilla_noutrefresh(pane->view); + } else + scintilla_noutrefresh(pane->view); } /** Refreshes the entire screen. */ @@ -389,10 +374,10 @@ static int find_keypress(EObjectType _, void *object, void *data, chtype key) { } else if (key == CDK_PREV || key == CDK_NEXT) { ListStore *store = entry == find_entry ? find_history : repl_history; int i; - for (i = 9; i >= 0; i--) if (store[i] && strcmp(store[i], text) == 0) break; + for (i = 9; i >= 0; i--) + if (store[i] && strcmp(store[i], text) == 0) break; key == CDK_PREV ? i++ : i--; - if (i >= 0 && i <= 9 && store[i]) - setCDKEntryValue(entry, store[i]), drawCDKEntry(entry, false); + if (i >= 0 && i <= 9 && store[i]) setCDKEntryValue(entry, store[i]), drawCDKEntry(entry, false); } else if (key >= KEY_F(1) && key <= KEY_F(4)) { toggle(&find_options[key - KEY_F(1)], !find_options[key - KEY_F(1)]); // Redraw the optionbox. @@ -400,8 +385,7 @@ static int find_keypress(EObjectType _, void *object, void *data, chtype key) { int width = (*optionbox)->boxWidth - 1; destroyCDKButtonbox(*optionbox); *optionbox = newCDKButtonbox( - findbox, RIGHT, TOP, 2, width, NULL, 2, 2, option_labels, 4, A_NORMAL, - false, false); + findbox, RIGHT, TOP, 2, width, NULL, 2, 2, option_labels, 4, A_NORMAL, false, false); drawCDKButtonbox(*optionbox, false); } else if (key == KEY_UP || key == KEY_DOWN) { focused_entry = entry == find_entry ? repl_entry : find_entry; @@ -433,21 +417,18 @@ static int focus_find(lua_State *L) { fmax(strlen(option_labels[2]), strlen(option_labels[3])) + 3; int l_width = fmax(strlen(find_label), strlen(repl_label)); int e_width = COLS - o_width - b_width - l_width - 1; - find_entry = newCDKEntry( - findbox, l_width - strlen(find_label), TOP, NULL, find_label, A_NORMAL, '_', - vMIXED, e_width, 0, 1024, false, false); - repl_entry = newCDKEntry( - findbox, l_width - strlen(repl_label), BOTTOM, NULL, repl_label, A_NORMAL, + find_entry = newCDKEntry(findbox, l_width - strlen(find_label), TOP, NULL, find_label, A_NORMAL, '_', vMIXED, e_width, 0, 1024, false, false); + repl_entry = newCDKEntry(findbox, l_width - strlen(repl_label), BOTTOM, NULL, repl_label, + A_NORMAL, '_', vMIXED, e_width, 0, 1024, false, false); CDKBUTTONBOX *buttonbox, *optionbox; - buttonbox = newCDKButtonbox( - findbox, COLS - o_width - b_width, TOP, 2, b_width, NULL, 2, 2, + buttonbox = newCDKButtonbox(findbox, COLS - o_width - b_width, TOP, 2, b_width, NULL, 2, 2, button_labels, 4, A_REVERSE, false, false); optionbox = newCDKButtonbox( - findbox, RIGHT, TOP, 2, o_width, NULL, 2, 2, option_labels, 4, A_NORMAL, - false, false); - // TODO: ideally no #define here. - #define bind(k, d) (bindCDKObject(vENTRY, find_entry, k, find_keypress, d), \ + findbox, RIGHT, TOP, 2, o_width, NULL, 2, 2, option_labels, 4, A_NORMAL, false, false); +// TODO: ideally no #define here. +#define bind(k, d) \ + (bindCDKObject(vENTRY, find_entry, k, find_keypress, d), \ bindCDKObject(vENTRY, repl_entry, k, find_keypress, d)) bind(KEY_TAB, buttonbox), bind(CDK_NEXT, NULL), bind(CDK_PREV, NULL); for (int i = 1; i <= 4; i++) bind(KEY_F(i), &optionbox); @@ -458,8 +439,7 @@ static int focus_find(lua_State *L) { char *clipboard = scintilla_get_clipboard(focused_view, NULL); GPasteBuffer = copyChar(clipboard); // set the CDK paste buffer refreshCDKScreen(findbox), activateCDKEntry(focused_entry = find_entry, NULL); - while (focused_entry->exitType == vNORMAL || - focused_entry->exitType == vNEVER_ACTIVATED) { + while (focused_entry->exitType == vNORMAL || focused_entry->exitType == vNEVER_ACTIVATED) { copyfree(&find_text, getCDKEntryValue(find_entry)); copyfree(&repl_text, getCDKEntryValue(repl_entry)); if (focused_entry->exitType == vNORMAL) @@ -568,7 +548,8 @@ static char *work(void *L) { lua_concat(L, 4); // "num str\n" char *input = strcpy(malloc(lua_rawlen(L, -1) + 1), lua_tostring(L, -1)); return (lua_pop(L, 1), input); // will be freed by gtdialog - } else lua_pop(L, 2), lua_pushliteral(L, "invalid return values"); + } else + lua_pop(L, 2), lua_pushliteral(L, "invalid return values"); } emit(L, "error", LUA_TSTRING, lua_tostring(L, -1), -1); return (lua_pop(L, 1), NULL); @@ -590,7 +571,8 @@ static int dialog(lua_State *L) { else if (lua_isfunction(L, j) && type == GTDIALOG_PROGRESSBAR) { lua_pushvalue(L, j), lua_setfield(L, LUA_REGISTRYINDEX, "ta_workf"); gtdialog_set_progressbar_callback(work, L); - } else argv[i++] = luaL_checkstring(L, j); + } else + argv[i++] = luaL_checkstring(L, j); argv[argc] = NULL; char *out; dialog_active = true, out = gtdialog(type, argc, argv), dialog_active = false; @@ -605,8 +587,8 @@ static int dialog(lua_State *L) { * @see add_view */ static void lua_pushview(lua_State *L, Scintilla *view) { - lua_getfield(L, LUA_REGISTRYINDEX, "ta_views"), - lua_pushlightuserdata(L, view), lua_gettable(L, -2), lua_replace(L, -2); + lua_getfield(L, LUA_REGISTRYINDEX, "ta_views"), lua_pushlightuserdata(L, view), + lua_gettable(L, -2), lua_replace(L, -2); } /** @@ -622,10 +604,11 @@ static void lua_pushsplit(lua_State *L, Pane *pane) { lua_pushsplit(L, gtk_paned_get_child1(p)), lua_rawseti(L, -2, 1); lua_pushsplit(L, gtk_paned_get_child2(p)), lua_rawseti(L, -2, 2); lua_pushboolean( - L, gtk_orientable_get_orientation(GTK_ORIENTABLE(pane)) == - GTK_ORIENTATION_HORIZONTAL), lua_setfield(L, -2, "vertical"); + L, gtk_orientable_get_orientation(GTK_ORIENTABLE(pane)) == GTK_ORIENTATION_HORIZONTAL), + lua_setfield(L, -2, "vertical"); lua_pushinteger(L, gtk_paned_get_position(p)), lua_setfield(L, -2, "size"); - } else lua_pushview(L, pane); + } else + lua_pushview(L, pane); #elif CURSES if (pane->type != SINGLE) { lua_newtable(L); @@ -633,7 +616,8 @@ static void lua_pushsplit(lua_State *L, Pane *pane) { lua_pushsplit(L, pane->child2), lua_rawseti(L, -2, 2); lua_pushboolean(L, pane->type == VSPLIT), lua_setfield(L, -2, "vertical"); lua_pushinteger(L, pane->split_size), lua_setfield(L, -2, "size"); - } else lua_pushview(L, pane->view); + } else + lua_pushview(L, pane->view); #endif } @@ -641,8 +625,7 @@ static void lua_pushsplit(lua_State *L, Pane *pane) { static int get_split_table(lua_State *L) { #if GTK GtkWidget *pane = focused_view; - while (GTK_IS_PANED(gtk_widget_get_parent(pane))) - pane = gtk_widget_get_parent(pane); + while (GTK_IS_PANED(gtk_widget_get_parent(pane))) pane = gtk_widget_get_parent(pane); #endif return (lua_pushsplit(L, pane), 1); } @@ -654,8 +637,7 @@ static int get_split_table(lua_State *L) { * @return Scintilla view */ static Scintilla *lua_toview(lua_State *L, int index) { - Scintilla *view = (lua_getfield(L, index, "widget_pointer"), - lua_touserdata(L, -1)); + Scintilla *view = (lua_getfield(L, index, "widget_pointer"), lua_touserdata(L, -1)); return (lua_pop(L, 1), view); // widget pointer } @@ -667,9 +649,8 @@ static Scintilla *lua_toview(lua_State *L, int index) { * @see add_doc */ static void lua_pushdoc(lua_State *L, sptr_t doc) { - lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), - lua_pushlightuserdata(L, (sptr_t *)doc), lua_gettable(L, -2), - lua_replace(L, -2); + lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_pushlightuserdata(L, (sptr_t *)doc), + lua_gettable(L, -2), lua_replace(L, -2); } /** @@ -678,13 +659,13 @@ static void lua_pushdoc(lua_State *L, sptr_t doc) { static void sync_tabbar() { #if GTK int i = (lua_getfield(lua, LUA_REGISTRYINDEX, "ta_buffers"), - lua_pushdoc(lua, SS(focused_view, SCI_GETDOCPOINTER, 0, 0)), - lua_gettable(lua, -2), lua_tointeger(lua, -1) - 1); + lua_pushdoc(lua, SS(focused_view, SCI_GETDOCPOINTER, 0, 0)), lua_gettable(lua, -2), + lua_tointeger(lua, -1) - 1); lua_pop(lua, 2); // index and buffers GtkNotebook *notebook = GTK_NOTEBOOK(tabbar); tab_sync = true, gtk_notebook_set_current_page(notebook, i), tab_sync = false; //#elif CURSES - // TODO: tabs +// TODO: tabs #endif } @@ -702,8 +683,8 @@ static bool is_type(lua_State *L, int index, const char *tname) { } /** - * Checks whether the function argument arg is a Scintilla view and returns - * this view cast to a Scintilla. + * Checks whether the function argument arg is a Scintilla view and returns this view cast to + * a Scintilla. * @param L The Lua state. * @param arg The stack index of the Scintilla view. * @return Scintilla view @@ -729,9 +710,9 @@ static void view_focused(Scintilla *view, lua_State *L) { /** `ui.goto_view()` Lua function. */ static int goto_view(lua_State *L) { if (lua_isnumber(L, 1)) { - int n = (lua_getfield(L, LUA_REGISTRYINDEX, "ta_views"), - lua_pushview(L, focused_view), lua_gettable(L, -2), - lua_tointeger(L, -1)) + lua_tointeger(L, 1); + lua_getfield(L, LUA_REGISTRYINDEX, "ta_views"); + int n = (lua_pushview(L, focused_view), lua_gettable(L, -2), lua_tointeger(L, -1)) + + lua_tointeger(L, 1); if (n > (int)lua_rawlen(L, -2)) n = 1; else if (n < 1) @@ -749,8 +730,7 @@ static int goto_view(lua_State *L) { } /** - * Returns the value t[n] as an integer where t is the value at the given valid - * index. + * Returns the value t[n] as an integer where t is the value at the given valid index. * The access is raw; that is, it does not invoke metamethods. * @param L The Lua state. * @param index The stack index of the table. @@ -791,14 +771,12 @@ static void lua_pushmenu(lua_State *L, int index, GCallback f, bool submenu) { const char *label = (lua_rawgeti(L, -1, 1), lua_tostring(L, -1)); if (lua_pop(L, 1), !label) continue; // Menu item table is of the form {label, id, key, modifiers}. - GtkWidget *menu_item = *label ? - gtk_menu_item_new_with_mnemonic(label) : gtk_separator_menu_item_new(); + GtkWidget *menu_item = + *label ? gtk_menu_item_new_with_mnemonic(label) : gtk_separator_menu_item_new(); if (*label && get_int_field(L, -1, 3) > 0) - gtk_widget_add_accelerator( - menu_item, "activate", accel, get_int_field(L, -1, 3), + gtk_widget_add_accelerator(menu_item, "activate", accel, get_int_field(L, -1, 3), get_int_field(L, -1, 4), GTK_ACCEL_VISIBLE); - g_signal_connect( - menu_item, "activate", f, (void*)(long)get_int_field(L, -1, 2)); + g_signal_connect(menu_item, "activate", f, (void *)(long)get_int_field(L, -1, 2)); gtk_menu_shell_append(GTK_MENU_SHELL(menu), menu_item); } lua_pushlightuserdata(L, !submenu_root ? menu : submenu_root); @@ -839,8 +817,7 @@ static int ui_index(lua_State *L) { const char *key = lua_tostring(L, 2); if (strcmp(key, "clipboard_text") == 0) { #if GTK - char *text = gtk_clipboard_wait_for_text( - gtk_clipboard_get(GDK_SELECTION_CLIPBOARD)); + char *text = gtk_clipboard_wait_for_text(gtk_clipboard_get(GDK_SELECTION_CLIPBOARD)); text ? lua_pushstring(L, text) : lua_pushliteral(L, ""); g_free(text); #elif CURSES @@ -898,20 +875,17 @@ static int ui_newindex(lua_State *L) { } else if (strcmp(key, "clipboard_text") == 0) { const char *text = luaL_checkstring(L, 3); SS(focused_view, SCI_COPYTEXT, lua_rawlen(L, 3), (sptr_t)text); - } else if (strcmp(key, "statusbar_text") == 0 || - strcmp(key, "buffer_statusbar_text") == 0) + } else if (strcmp(key, "statusbar_text") == 0 || strcmp(key, "buffer_statusbar_text") == 0) set_statusbar_text(lua_tostring(L, 3), *key == 's' ? 0 : 1); else if (strcmp(key, "menubar") == 0) { #if GTK luaL_argcheck(L, lua_istable(L, 3), 3, "table of menus expected"); for (size_t i = 1; i <= lua_rawlen(L, 3); lua_pop(L, 1), i++) - luaL_argcheck( - L, lua_rawgeti(L, 3, i) == LUA_TLIGHTUSERDATA, 3, + luaL_argcheck(L, lua_rawgeti(L, 3, i) == LUA_TLIGHTUSERDATA, 3, "table of menus expected"); // popped on loop GtkWidget *new_menubar = gtk_menu_bar_new(); for (size_t i = 1; i <= lua_rawlen(L, 3); lua_pop(L, 1), i++) - gtk_menu_shell_append( - GTK_MENU_SHELL(new_menubar), + gtk_menu_shell_append(GTK_MENU_SHELL(new_menubar), (lua_rawgeti(L, 3, i), lua_touserdata(L, -1))); // popped on loop GtkWidget *vbox = gtk_widget_get_parent(menubar); gtk_container_remove(GTK_CONTAINER(vbox), menubar); @@ -923,30 +897,29 @@ static int ui_newindex(lua_State *L) { gtk_widget_hide(new_menubar); // hide in window #endif //#elif CURSES - // TODO: menus +// TODO: menus #endif } else if (strcmp(key, "maximized") == 0) { #if GTK - lua_toboolean(L, 3) ? gtk_window_maximize( - GTK_WINDOW(window)) : gtk_window_unmaximize(GTK_WINDOW(window)); + lua_toboolean(L, 3) ? gtk_window_maximize(GTK_WINDOW(window)) : + gtk_window_unmaximize(GTK_WINDOW(window)); #endif } else if (strcmp(key, "size") == 0) { #if GTK luaL_argcheck( - L, lua_istable(L, 3) && lua_rawlen(L, 3) == 2, 3, - "{width, height} table expected"); + L, lua_istable(L, 3) && lua_rawlen(L, 3) == 2, 3, "{width, height} table expected"); int w = get_int_field(L, 3, 1), h = get_int_field(L, 3, 2); if (w > 0 && h > 0) gtk_window_resize(GTK_WINDOW(window), w, h); #endif } else if (strcmp(key, "tabs") == 0) { tabs = !lua_isinteger(L, 3) ? lua_toboolean(L, 3) : lua_tointeger(L, 3); #if GTK - gtk_widget_set_visible( - tabbar, show_tabs(gtk_notebook_get_n_pages(GTK_NOTEBOOK(tabbar)) > 1)); + gtk_widget_set_visible(tabbar, show_tabs(gtk_notebook_get_n_pages(GTK_NOTEBOOK(tabbar)) > 1)); //#elif CURSES - // TODO: tabs +// TODO: tabs #endif - } else lua_rawset(L, 1); + } else + lua_rawset(L, 1); return 0; } @@ -957,29 +930,27 @@ static int ui_newindex(lua_State *L) { * @return Scintilla document */ static sptr_t lua_todoc(lua_State *L, int index) { - sptr_t doc = (lua_getfield(L, index, "doc_pointer"), - (sptr_t)lua_touserdata(L, -1)); + sptr_t doc = (lua_getfield(L, index, "doc_pointer"), (sptr_t)lua_touserdata(L, -1)); return (lua_pop(L, 1), doc); // doc_pointer } /** - * Returns for the Scintilla document at the given index a suitable Scintilla - * view that can operate on it. - * For non-global, non-command entry documents, loads that document in - * `dummy_view` for non-global document use (unless it is already loaded). - * Raises and error if the value is not a Scintilla document or if the document - * no longer exists. + * Returns for the Scintilla document at the given index a suitable Scintilla view that can + * operate on it. + * For non-global, non-command entry documents, loads that document in `dummy_view` for non-global + * document use (unless it is already loaded). Raises and error if the value is not a Scintilla + * document or if the document no longer exists. * @param L The Lua state. * @param index The stack index of the Scintilla document. */ static Scintilla *view_for_doc(lua_State *L, int index) { - luaL_argcheck( - L, is_type(L, index, "ta_buffer"), index, "Buffer expected"); + luaL_argcheck(L, is_type(L, index, "ta_buffer"), index, "Buffer expected"); sptr_t doc = lua_todoc(L, index); if (doc == SS(focused_view, SCI_GETDOCPOINTER, 0, 0)) return focused_view; - luaL_argcheck( - L, (lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_pushdoc(L, doc), - lua_gettable(L, -2) != LUA_TNIL), index, "this Buffer does not exist"); + luaL_argcheck(L, + (lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_pushdoc(L, doc), + lua_gettable(L, -2) != LUA_TNIL), + index, "this Buffer does not exist"); lua_pop(L, 2); // buffer, ta_buffers if (doc == SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) return command_entry; if (doc == SS(dummy_view, SCI_GETDOCPOINTER, 0, 0)) return dummy_view; @@ -990,22 +961,23 @@ static Scintilla *view_for_doc(lua_State *L, int index) { * Switches to a document in the given view. * @param L The Lua state. * @param view The Scintilla view. - * @param n Relative or absolute index of the document to switch to. An absolute - * n of -1 represents the last document. + * @param n Relative or absolute index of the document to switch to. An absolute n of -1 + * represents the last document. * @param relative Flag indicating whether or not n is relative. */ static void goto_doc(lua_State *L, Scintilla *view, int n, bool relative) { if (relative && n == 0) return; lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"); if (relative) { - n = (lua_pushdoc(L, SS(view, SCI_GETDOCPOINTER, 0, 0)), lua_gettable(L, -2), - lua_tointeger(L, -1)) + n; + lua_pushdoc(L, SS(view, SCI_GETDOCPOINTER, 0, 0)); + n = (lua_gettable(L, -2), lua_tointeger(L, -1)) + n; if (n > (int)lua_rawlen(L, -2)) n = 1; else if (n < 1) n = lua_rawlen(L, -2); lua_rawgeti(L, -2, n), lua_replace(L, -2); // index - } else lua_rawgeti(L, -1, n > 0 ? n : (int)lua_rawlen(L, -1)); + } else + lua_rawgeti(L, -1, n > 0 ? n : (int)lua_rawlen(L, -1)); luaL_argcheck(L, !lua_isnil(L, -1), 2, "no Buffer exists at that index"); sptr_t doc = lua_todoc(L, -1); SS(view, SCI_SETDOCPOINTER, 0, doc), sync_tabbar(); @@ -1013,20 +985,15 @@ static void goto_doc(lua_State *L, Scintilla *view, int n, bool relative) { lua_pop(L, 1); // buffers } -/** - * Adds the command entry's buffer to the 'buffers' registry table at a constant - * index (0). - */ +/** Adds the command entry's buffer to the 'buffers' registry table at a constant index (0). */ static void register_command_entry_doc() { sptr_t doc = SS(command_entry, SCI_GETDOCPOINTER, 0, 0); lua_getfield(lua, LUA_REGISTRYINDEX, "ta_buffers"); - lua_getglobal(lua, "ui"), lua_getfield(lua, -1, "command_entry"), - lua_replace(lua, -2); + lua_getglobal(lua, "ui"), lua_getfield(lua, -1, "command_entry"), lua_replace(lua, -2); lua_pushstring(lua, "doc_pointer"), lua_pushlightuserdata(lua, (sptr_t *)doc), lua_rawset(lua, -3); // t[doc_pointer] = command_entry, t[0] = command_entry, t[command_entry] = 0 - lua_pushlightuserdata(lua, (sptr_t *)doc), lua_pushvalue(lua, -2), - lua_settable(lua, -4); + lua_pushlightuserdata(lua, (sptr_t *)doc), lua_pushvalue(lua, -2), lua_settable(lua, -4); lua_pushvalue(lua, -1), lua_rawseti(lua, -3, 0); lua_pushinteger(lua, 0), lua_settable(lua, -3); lua_pop(lua, 1); // buffers @@ -1035,8 +1002,8 @@ static void register_command_entry_doc() { /** * Removes the Scintilla document from the 'buffers' registry table. * The document must have been previously added with add_doc. - * It is removed from any other views showing it first. Therefore, ensure the - * length of 'buffers' is more than one unless quitting the application. + * It is removed from any other views showing it first. Therefore, ensure the length of 'buffers' + * is more than one unless quitting the application. * @param L The Lua state. * @param doc The Scintilla document to remove. * @see add_doc @@ -1053,8 +1020,7 @@ static void remove_doc(lua_State *L, sptr_t doc) { for (size_t i = 1; i <= lua_rawlen(L, -1); i++) if (doc != (lua_rawgeti(L, -1, i), lua_todoc(L, -1))) { // t[doc_pointer] = buffer, t[#t + 1] = buffer, t[buffer] = #t - lua_getfield(L, -1, "doc_pointer"), lua_pushvalue(L, -2), - lua_settable(L, -5); + lua_getfield(L, -1, "doc_pointer"), lua_pushvalue(L, -2), lua_settable(L, -5); lua_pushvalue(L, -1), lua_rawseti(L, -4, lua_rawlen(L, -4) + 1); lua_pushinteger(L, lua_rawlen(L, -3)), lua_settable(L, -4); } else { @@ -1063,7 +1029,7 @@ static void remove_doc(lua_State *L, sptr_t doc) { gtk_notebook_remove_page(GTK_NOTEBOOK(tabbar), i - 1); gtk_widget_set_visible(tabbar, show_tabs(lua_rawlen(L, -2) > 2)); //#elif CURSES - // TODO: tabs +// TODO: tabs #endif lua_pop(L, 1); // buffer } @@ -1088,8 +1054,7 @@ static int delete_buffer_lua(lua_State *L) { Scintilla *view = view_for_doc(L, 1); luaL_argcheck(L, view != command_entry, 1, "cannot delete command entry"); sptr_t doc = SS(view, SCI_GETDOCPOINTER, 0, 0); - if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_rawlen(L, -1) == 1) - new_buffer(0); + if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_rawlen(L, -1) == 1) new_buffer(0); if (view == focused_view) goto_doc(L, focused_view, -1, true); delete_buffer(doc), emit(L, "buffer_deleted", -1); if (view == focused_view) emit(L, "buffer_after_switch", -1); @@ -1100,13 +1065,13 @@ static int delete_buffer_lua(lua_State *L) { static int new_buffer_lua(lua_State *L) { if (initing) luaL_error(L, "cannot create buffers during initialization"); new_buffer(0); - return (lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), - lua_rawgeti(L, -1, lua_rawlen(L, -1)), 1); + return ( + lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_rawgeti(L, -1, lua_rawlen(L, -1)), 1); } /** - * Checks whether the function argument arg is the given Scintilla parameter - * type and returns it cast to the proper type. + * Checks whether the function argument arg is the given Scintilla parameter type and returns + * it cast to the proper type. * @param L The Lua state. * @param arg The stack index of the Scintilla parameter. * @param type The Scintilla type to convert to. @@ -1131,33 +1096,30 @@ static sptr_t luaL_checkscintilla(lua_State *L, int *arg, int type) { * @param wtype The type of Scintilla wParam. * @param ltype The type of Scintilla lParam. * @param rtype The type of the Scintilla return. - * @param arg The stack index of the first Scintilla parameter. Subsequent - * elements will also be passed to Scintilla as needed. + * @param arg The stack index of the first Scintilla parameter. Subsequent elements will also + * be passed to Scintilla as needed. * @return number of results pushed onto the stack. * @see luaL_checkscintilla */ static int call_scintilla( - lua_State *L, Scintilla *view, int msg, int wtype, int ltype, int rtype, - int arg) -{ + lua_State *L, Scintilla *view, int msg, int wtype, int ltype, int rtype, int arg) { uptr_t wparam = 0; sptr_t lparam = 0, len = 0; int params_needed = 2, nresults = 0; bool string_return = false; char *text = NULL; - // Even though the SCI_PRIVATELEXERCALL interface has ltype int, the LPeg - // lexer API uses different types depending on wparam. Modify ltype - // appropriately. See the LPeg lexer API for more information. - if (msg == SCI_PRIVATELEXERCALL) - switch (luaL_checkinteger(L, arg)) { - case SCI_GETDIRECTFUNCTION: case SCI_SETDOCPOINTER: - case SCI_CHANGELEXERSTATE: - ltype = SINT; break; - case SCI_SETLEXERLANGUAGE: case SCI_LOADLEXERLIBRARY: - ltype = SSTRING; break; - case SCI_GETNAMEDSTYLES: ltype = SSTRING, rtype = SINDEX; break; - default: ltype = SSTRINGRET; + // Even though the SCI_PRIVATELEXERCALL interface has ltype int, the LPeg lexer API uses + // different types depending on wparam. Modify ltype appropriately. See the LPeg lexer API + // for more information. + if (msg == SCI_PRIVATELEXERCALL) switch (luaL_checkinteger(L, arg)) { + case SCI_GETDIRECTFUNCTION: + case SCI_SETDOCPOINTER: + case SCI_CHANGELEXERSTATE: ltype = SINT; break; + case SCI_SETLEXERLANGUAGE: + case SCI_LOADLEXERLIBRARY: ltype = SSTRING; break; + case SCI_GETNAMEDSTYLES: ltype = SSTRING, rtype = SINDEX; break; + default: ltype = SSTRINGRET; } // Set wParam and lParam appropriately for Scintilla based on wtype and ltype. @@ -1198,10 +1160,8 @@ static int call_scintilla_lua(lua_State *L) { else if (is_type(L, 1, "ta_view")) view = lua_toview(L, 1); // Interface table is of the form {msg, rtype, wtype, ltype}. - return call_scintilla( - L, view, get_int_field(L, lua_upvalueindex(1), 1), - get_int_field(L, lua_upvalueindex(1), 3), - get_int_field(L, lua_upvalueindex(1), 4), + return call_scintilla(L, view, get_int_field(L, lua_upvalueindex(1), 1), + get_int_field(L, lua_upvalueindex(1), 3), get_int_field(L, lua_upvalueindex(1), 4), get_int_field(L, lua_upvalueindex(1), 2), lua_istable(L, 1) ? 2 : 1); } @@ -1217,12 +1177,12 @@ static void show_context_menu(lua_State *L, GdkEventButton *event, char *k) { if (lua_getfield(L, -1, k) == LUA_TLIGHTUSERDATA) { GtkWidget *menu = lua_touserdata(L, -1); gtk_widget_show_all(menu); - gtk_menu_popup( - GTK_MENU(menu), NULL, NULL, NULL, NULL, event ? event->button : 0, + gtk_menu_popup(GTK_MENU(menu), NULL, NULL, NULL, NULL, event ? event->button : 0, gdk_event_get_time((GdkEvent *)event)); } lua_pop(L, 2); // ui context menu field, ui - } else lua_pop(L, 1); // non-table + } else + lua_pop(L, 1); // non-table } /** Signal for a tab label mouse click. */ @@ -1231,12 +1191,9 @@ static bool tab_clicked(GtkWidget *label, GdkEventButton *event, void *L) { for (int i = 0; i < gtk_notebook_get_n_pages(notebook); i++) { GtkWidget *page = gtk_notebook_get_nth_page(notebook, i); if (label != gtk_notebook_get_tab_label(notebook, page)) continue; - emit( - L, "tab_clicked", LUA_TNUMBER, i + 1, LUA_TNUMBER, event->button, - LUA_TBOOLEAN, event->state & GDK_SHIFT_MASK, - LUA_TBOOLEAN, event->state & GDK_CONTROL_MASK, - LUA_TBOOLEAN, event->state & GDK_MOD1_MASK, - LUA_TBOOLEAN, event->state & GDK_META_MASK, -1); + emit(L, "tab_clicked", LUA_TNUMBER, i + 1, LUA_TNUMBER, event->button, LUA_TBOOLEAN, + event->state & GDK_SHIFT_MASK, LUA_TBOOLEAN, event->state & GDK_CONTROL_MASK, LUA_TBOOLEAN, + event->state & GDK_MOD1_MASK, LUA_TBOOLEAN, event->state & GDK_META_MASK, -1); if (event->button == 3) show_context_menu(L, event, "tab_context_menu"); break; } @@ -1247,10 +1204,11 @@ static bool tab_clicked(GtkWidget *label, GdkEventButton *event, void *L) { /** `buffer[k].__index` metamethod. */ static int property_index(lua_State *L) { Scintilla *view = (lua_getfield(L, 1, "_self"), !is_type(L, -1, "ta_view")) ? - view_for_doc(L, -1) : lua_toview(L, -1); + view_for_doc(L, -1) : + lua_toview(L, -1); lua_getfield(L, 1, "_iface"); // {get_id, set_id, rtype, wtype}. - int msg = get_int_field(L, -1, 1), wtype = get_int_field(L, -1, 4), - ltype = SVOID, rtype = get_int_field(L, -1, 3); + int msg = get_int_field(L, -1, 1), wtype = get_int_field(L, -1, 4), ltype = SVOID, + rtype = get_int_field(L, -1, 3); luaL_argcheck(L, msg, 2, "write-only property"); return (call_scintilla(L, view, msg, wtype, ltype, rtype, 2), 1); } @@ -1258,43 +1216,41 @@ static int property_index(lua_State *L) { /** `buffer[k].__newindex` metamethod. */ static int property_newindex(lua_State *L) { Scintilla *view = (lua_getfield(L, 1, "_self"), !is_type(L, -1, "ta_view")) ? - view_for_doc(L, -1) : lua_toview(L, -1); + view_for_doc(L, -1) : + lua_toview(L, -1); lua_getfield(L, 1, "_iface"); // {get_id, set_id, rtype, wtype}. int msg = get_int_field(L, -1, 2), wtype = get_int_field(L, -1, 4), - ltype = get_int_field(L, -1, 3), rtype = SVOID; + ltype = get_int_field(L, -1, 3), rtype = SVOID; luaL_argcheck(L, msg, 3, "read-only property"); if (ltype == SSTRINGRET) ltype = SSTRING; return (call_scintilla(L, view, msg, wtype, ltype, rtype, 2), 0); } -// Helper function for `buffer_index()` and `view_index()` that gets Scintilla -// properties. +// Helper function for `buffer_index()` and `view_index()` that gets Scintilla properties. static void get_property(lua_State *L) { - Scintilla *view = is_type(L, 1, "ta_buffer") ? view_for_doc(L, 1) : - lua_toview(L, 1); + Scintilla *view = is_type(L, 1, "ta_buffer") ? view_for_doc(L, 1) : lua_toview(L, 1); // Interface table is of the form {get_id, set_id, rtype, wtype}. - int msg = get_int_field(L, -1, 1), wtype = get_int_field(L, -1, 4), - ltype = SVOID, rtype = get_int_field(L, -1, 3); + int msg = get_int_field(L, -1, 1), wtype = get_int_field(L, -1, 4), ltype = SVOID, + rtype = get_int_field(L, -1, 3); luaL_argcheck(L, msg || wtype != SVOID, 2, "write-only property"); if (wtype != SVOID) { // indexible property lua_createtable(L, 2, 0); lua_pushvalue(L, 1), lua_setfield(L, -2, "_self"); lua_pushvalue(L, -2), lua_setfield(L, -2, "_iface"); set_metatable(L, -1, "ta_property", property_index, property_newindex); - } else call_scintilla(L, view, msg, wtype, ltype, rtype, 2); + } else + call_scintilla(L, view, msg, wtype, ltype, rtype, 2); } -// Helper function for `buffer_newindex()` and `view_newindex()` that sets -// Scintilla properties. +// Helper function for `buffer_newindex()` and `view_newindex()` that sets Scintilla properties. static void set_property(lua_State *L) { - Scintilla *view = is_type(L, 1, "ta_buffer") ? view_for_doc(L, 1) : - lua_toview(L, 1); + Scintilla *view = is_type(L, 1, "ta_buffer") ? view_for_doc(L, 1) : lua_toview(L, 1); // Interface table is of the form {get_id, set_id, rtype, wtype}. int msg = get_int_field(L, -1, 2), wtype = get_int_field(L, -1, 3), - ltype = get_int_field(L, -1, 4), rtype = SVOID, temp; + ltype = get_int_field(L, -1, 4), rtype = SVOID, temp; luaL_argcheck(L, msg && ltype == SVOID, 3, "read-only property"); - if (wtype == SSTRING || wtype == SSTRINGRET || - msg == SCI_SETMARGINLEFT || msg == SCI_SETMARGINRIGHT) + if (wtype == SSTRING || wtype == SSTRINGRET || msg == SCI_SETMARGINLEFT || + msg == SCI_SETMARGINRIGHT) temp = wtype != SSTRINGRET ? wtype : SSTRING, wtype = ltype, ltype = temp; call_scintilla(L, view, msg, wtype, ltype, rtype, 3); } @@ -1302,34 +1258,32 @@ static void set_property(lua_State *L) { /** `buffer.__index` metamethod. */ static int buffer_index(lua_State *L) { if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_functions"), lua_pushvalue(L, 2), - lua_rawget(L, -2) == LUA_TTABLE) + lua_rawget(L, -2) == LUA_TTABLE) // If the key is a Scintilla function, return a callable closure. lua_pushcclosure(L, call_scintilla_lua, 1); - else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_properties"), - lua_pushvalue(L, 2), lua_rawget(L, -2) == LUA_TTABLE) - // If the key is a Scintilla property, determine if it is an indexible one - // or not. If so, return a table with the appropriate metatable; otherwise - // call Scintilla to get the property's value. + else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_properties"), lua_pushvalue(L, 2), + lua_rawget(L, -2) == LUA_TTABLE) + // If the key is a Scintilla property, determine if it is an indexible one or not. If so, + // return a table with the appropriate metatable; otherwise call Scintilla to get the + // property's value. get_property(L); - else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_constants"), - lua_pushvalue(L, 2), lua_rawget(L, -2) == LUA_TNUMBER); // pushed + else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_constants"), lua_pushvalue(L, 2), + lua_rawget(L, -2) == LUA_TNUMBER) { // pushed // If the key is a Scintilla constant, return its value. - else if (strcmp(lua_tostring(L, 2), "tab_label") == 0 && - lua_todoc(L, 1) != SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { + } else if (strcmp(lua_tostring(L, 2), "tab_label") == 0 && + lua_todoc(L, 1) != SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { // Return the buffer's tab label. lua_getfield(L, 1, "tab_pointer"); #if GTK - lua_pushstring( - L, gtk_notebook_get_tab_label_text(GTK_NOTEBOOK(tabbar), - lua_touserdata(L, -1))); + lua_pushstring(L, gtk_notebook_get_tab_label_text(GTK_NOTEBOOK(tabbar), lua_touserdata(L, -1))); //#elif CURSES - // TODO: tabs +// TODO: tabs #endif } else if (strcmp(lua_tostring(L, 2), "active") == 0 && - lua_todoc(L, 1) == SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) + lua_todoc(L, 1) == SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) lua_pushboolean(L, command_entry_active); else if (strcmp(lua_tostring(L, 2), "height") == 0 && - lua_todoc(L, 1) == SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { + lua_todoc(L, 1) == SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { // Return the command entry's pixel height. #if GTK GtkAllocation allocation; @@ -1338,19 +1292,20 @@ static int buffer_index(lua_State *L) { #elif CURSES lua_pushinteger(L, getmaxy(scintilla_get_window(command_entry))); #endif - } else lua_settop(L, 2), lua_rawget(L, 1); + } else + lua_settop(L, 2), lua_rawget(L, 1); return 1; } /** `buffer.__newindex` metamethod. */ static int buffer_newindex(lua_State *L) { if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_properties"), lua_pushvalue(L, 2), - lua_rawget(L, -2) == LUA_TTABLE) + lua_rawget(L, -2) == LUA_TTABLE) // If the key is a Scintilla property, call Scintilla to set its value. // Interface table is of the form {get_id, set_id, rtype, wtype}. set_property(L); else if (strcmp(lua_tostring(L, 2), "tab_label") == 0 && - lua_todoc(L, 1) != SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { + lua_todoc(L, 1) != SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { // Update the buffer's tab label. lua_getfield(L, 1, "tab_pointer"); #if GTK @@ -1358,17 +1313,15 @@ static int buffer_newindex(lua_State *L) { gtk_event_box_set_visible_window(GTK_EVENT_BOX(box), false); GtkWidget *label = gtk_label_new(luaL_checkstring(L, 3)); gtk_container_add(GTK_CONTAINER(box), label), gtk_widget_show(label); - gtk_notebook_set_tab_label( - GTK_NOTEBOOK(tabbar), lua_touserdata(L, -1), box); + gtk_notebook_set_tab_label(GTK_NOTEBOOK(tabbar), lua_touserdata(L, -1), box); g_signal_connect(box, "button-press-event", G_CALLBACK(tab_clicked), L); //#elif CURSES - // TODO: tabs +// TODO: tabs #endif } else if (strcmp(lua_tostring(L, 2), "height") == 0 && - lua_todoc(L, 1) == SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { + lua_todoc(L, 1) == SS(command_entry, SCI_GETDOCPOINTER, 0, 0)) { // Set the command entry's pixel height. - int height = fmax( - luaL_checkinteger(L, 3), SS(command_entry, SCI_TEXTHEIGHT, 0, 0)); + int height = fmax(luaL_checkinteger(L, 3), SS(command_entry, SCI_TEXTHEIGHT, 0, 0)); #if GTK GtkWidget *paned = gtk_widget_get_parent(command_entry); GtkAllocation allocation; @@ -1379,7 +1332,8 @@ static int buffer_newindex(lua_State *L) { WINDOW *win = scintilla_get_window(command_entry); wresize(win, height, COLS), mvwin(win, LINES - 1 - height, 0); #endif - } else lua_settop(L, 3), lua_rawset(L, 1); + } else + lua_settop(L, 3), lua_rawset(L, 1); return 0; } @@ -1396,10 +1350,10 @@ static void add_doc(lua_State *L, sptr_t doc) { GtkWidget *tab = gtk_vbox_new(false, 0); // placeholder in GtkNotebook lua_pushlightuserdata(L, tab), lua_setfield(L, -2, "tab_pointer"); //#elif CURSES - // TODO: tabs +// TODO: tabs #endif lua_pushcfunction(L, delete_buffer_lua), lua_setfield(L, -2, "delete"); - lua_pushcfunction(L, new_buffer_lua) , lua_setfield(L, -2, "new"); + lua_pushcfunction(L, new_buffer_lua), lua_setfield(L, -2, "new"); set_metatable(L, -1, "ta_buffer", buffer_index, buffer_newindex); // t[doc_pointer] = buffer, t[#t + 1] = buffer, t[buffer] = #t lua_getfield(L, -1, "doc_pointer"), lua_pushvalue(L, -2), lua_settable(L, -4); @@ -1411,9 +1365,8 @@ static void add_doc(lua_State *L, sptr_t doc) { /** * Creates a new Scintilla document and adds it to the Lua state. * Generates 'buffer_before_switch' and 'buffer_new' events. - * @param doc Almost always zero, except for the first Scintilla view created, - * in which its doc pointer would be given here since it already has a - * pre-created buffer. + * @param doc Almost always zero, except for the first Scintilla view created, in which its + * doc pointer would be given here since it already has a pre-created buffer. * @see add_doc */ static void new_buffer(sptr_t doc) { @@ -1421,7 +1374,8 @@ static void new_buffer(sptr_t doc) { emit(lua, "buffer_before_switch", -1); add_doc(lua, doc = SS(focused_view, SCI_CREATEDOCUMENT, 0, 0)); goto_doc(lua, focused_view, -1, false); - } else add_doc(lua, doc), SS(focused_view, SCI_ADDREFDOCUMENT, 0, doc); + } else + add_doc(lua, doc), SS(focused_view, SCI_ADDREFDOCUMENT, 0, doc); #if GTK // Add a tab to the tabbar. GtkWidget *tab = (lua_pushdoc(lua, SS(focused_view, SCI_GETDOCPOINTER, 0, 0)), @@ -1433,7 +1387,7 @@ static void new_buffer(sptr_t doc) { tab_sync = false; lua_pop(lua, 2); // tab_pointer and buffer //#elif CURSES - // TODO: tabs +// TODO: tabs #endif SS(focused_view, SCI_SETILEXER, 0, (sptr_t)CreateLexer(NULL)); lua_pushdoc(lua, doc), lua_setglobal(lua, "buffer"); @@ -1462,9 +1416,7 @@ static bool run_file(lua_State *L, const char *filename) { sprintf(file, "%s/%s", textadept_home, filename); bool ok = luaL_dofile(L, file) == LUA_OK; if (!ok) { - const char *argv[] = { - "--title", "Initialization Error", "--text", lua_tostring(L, -1) - }; + const char *argv[] = {"--title", "Initialization Error", "--text", lua_tostring(L, -1)}; free(gtdialog(GTDIALOG_TEXTBOX, 4, argv)); lua_settop(L, 0); } @@ -1478,8 +1430,7 @@ static int reset(lua_State *L) { emit(L, "reset_before", LUA_TTABLE, luaL_ref(L, LUA_REGISTRYINDEX), -1); init_lua(L, 0, NULL, true); lua_pushview(L, focused_view), lua_setglobal(L, "view"); - lua_pushdoc(L, SS(focused_view, SCI_GETDOCPOINTER, 0, 0)), - lua_setglobal(L, "buffer"); + lua_pushdoc(L, SS(focused_view, SCI_GETDOCPOINTER, 0, 0)), lua_setglobal(L, "buffer"); lua_pushnil(L), lua_setglobal(L, "arg"); run_file(L, "init.lua"), emit(L, "initialized", -1); lua_getfield(L, LUA_REGISTRYINDEX, "ta_arg"), lua_setglobal(L, "arg"); @@ -1507,8 +1458,7 @@ static int add_timeout(lua_State *L) { luaL_argcheck(L, interval > 0, 1, "interval must be > 0"); luaL_argcheck(L, lua_isfunction(L, 2), 2, "function expected"); int n = lua_gettop(L), *refs = (int *)calloc(n, sizeof(int)); - for (int i = 2; i <= n; i++) - lua_pushvalue(L, i), refs[i - 2] = luaL_ref(L, LUA_REGISTRYINDEX); + for (int i = 2; i <= n; i++) lua_pushvalue(L, i), refs[i - 2] = luaL_ref(L, LUA_REGISTRYINDEX); return (g_timeout_add(interval * 1000, timed_out, refs), 0); #elif CURSES return luaL_error(L, "not implemented in this environment"); @@ -1522,19 +1472,19 @@ static int iconv_lua(lua_State *L) { const char *to = luaL_checkstring(L, 2), *from = luaL_checkstring(L, 3); iconv_t cd = iconv_open(to, from); if (cd == (iconv_t)-1) luaL_error(L, "invalid encoding(s)"); - // Ensure the minimum buffer size can hold a potential output BOM and one - // multibyte character. + // Ensure the minimum buffer size can hold a potential output BOM and one multibyte character. size_t bufsiz = 4 + (inbytesleft > MB_LEN_MAX ? inbytesleft : MB_LEN_MAX); char *outbuf = malloc(bufsiz + 1), *p = outbuf; size_t outbytesleft = bufsiz; int n = 1; // concat this many converted strings while (iconv(cd, &inbuf, &inbytesleft, &p, &outbytesleft) == (size_t)-1) if (errno == E2BIG && p - outbuf > 0) { - // Buffer was too small to store converted string. Push the partially - // converted string for later concatenation. + // Buffer was too small to store converted string. Push the partially converted string + // for later concatenation. lua_checkstack(L, 2), lua_pushlstring(L, outbuf, p - outbuf), n++; p = outbuf, outbytesleft = bufsiz; - } else free(outbuf), iconv_close(cd), luaL_error(L, "conversion failed"); + } else + free(outbuf), iconv_close(cd), luaL_error(L, "conversion failed"); lua_pushlstring(L, outbuf, p - outbuf); free(outbuf), iconv_close(cd); return (lua_concat(L, n), 1); @@ -1542,8 +1492,7 @@ static int iconv_lua(lua_State *L) { /** * Initializes or re-initializes the Lua state. - * Populates the state with global variables and functions, then runs the - * 'core/init.lua' script. + * Populates the state with global variables and functions, then runs the 'core/init.lua' script. * @param L The Lua state. * @param argc The number of command line parameters. * @param argv The array of command line parameters. @@ -1553,8 +1502,7 @@ static int iconv_lua(lua_State *L) { static bool init_lua(lua_State *L, int argc, char **argv, bool reinit) { if (!reinit) { lua_newtable(L); - for (int i = 0; i < argc; i++) - lua_pushstring(L, argv[i]), lua_rawseti(L, -2, i); + for (int i = 0; i < argc; i++) lua_pushstring(L, argv[i]), lua_rawseti(L, -2, i); lua_setfield(L, LUA_REGISTRYINDEX, "ta_arg"); lua_newtable(L), lua_setfield(L, LUA_REGISTRYINDEX, "ta_buffers"); lua_newtable(L), lua_setfield(L, LUA_REGISTRYINDEX, "ta_views"); @@ -1602,12 +1550,11 @@ static bool init_lua(lua_State *L, int argc, char **argv, bool reinit) { lua_pushcfunction(L, reset), lua_setglobal(L, "reset"); lua_pushcfunction(L, add_timeout), lua_setglobal(L, "timeout"); - lua_getglobal(L, "string"), lua_pushcfunction(L, iconv_lua), - lua_setfield(L, -2, "iconv"), lua_pop(L, 1); + lua_getglobal(L, "string"), lua_pushcfunction(L, iconv_lua), lua_setfield(L, -2, "iconv"), + lua_pop(L, 1); lua_getfield(L, LUA_REGISTRYINDEX, "ta_arg"), lua_setglobal(L, "arg"); - lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), - lua_setglobal(L, "_BUFFERS"); + lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_setglobal(L, "_BUFFERS"); lua_getfield(L, LUA_REGISTRYINDEX, "ta_views"), lua_setglobal(L, "_VIEWS"); lua_pushstring(L, textadept_home), lua_setglobal(L, "_HOME"); if (platform) lua_pushboolean(L, true), lua_setglobal(L, platform); @@ -1633,12 +1580,9 @@ static bool init_lua(lua_State *L, int argc, char **argv, bool reinit) { if (!run_file(L, "core/init.lua")) return (lua_close(L), false); lua_getglobal(L, "_SCINTILLA"); - lua_getfield(L, -1, "constants"), - lua_setfield(L, LUA_REGISTRYINDEX, "ta_constants"); - lua_getfield(L, -1, "functions"), - lua_setfield(L, LUA_REGISTRYINDEX, "ta_functions"); - lua_getfield(L, -1, "properties"), - lua_setfield(L, LUA_REGISTRYINDEX, "ta_properties"); + lua_getfield(L, -1, "constants"), lua_setfield(L, LUA_REGISTRYINDEX, "ta_constants"); + lua_getfield(L, -1, "functions"), lua_setfield(L, LUA_REGISTRYINDEX, "ta_functions"); + lua_getfield(L, -1, "properties"), lua_setfield(L, LUA_REGISTRYINDEX, "ta_properties"); lua_pop(L, 1); // _SCINTILLA return true; } @@ -1653,7 +1597,7 @@ static bool window_focused(GtkWidget *_, GdkEventFocus *__, void *L) { /** Signal for a Textadept keypress. */ static bool window_keypress(GtkWidget *_, GdkEventKey *event, void *__) { if (event->keyval != GDK_KEY_Escape || !gtk_widget_get_visible(findbox) || - gtk_widget_has_focus(command_entry)) + gtk_widget_has_focus(command_entry)) return false; return (gtk_widget_hide(findbox), gtk_widget_grab_focus(focused_view), true); } @@ -1672,11 +1616,11 @@ static void remove_view(lua_State *L, Scintilla *view) { for (size_t i = 1; i <= lua_rawlen(L, -1); i++) { if (view != (lua_rawgeti(L, -1, i), lua_toview(L, -1))) { // t[widget_pointer] = view, t[#t + 1] = view, t[view] = #t - lua_getfield(L, -1, "widget_pointer"), lua_pushvalue(L, -2), - lua_settable(L, -5); + lua_getfield(L, -1, "widget_pointer"), lua_pushvalue(L, -2), lua_settable(L, -5); lua_pushvalue(L, -1), lua_rawseti(L, -4, lua_rawlen(L, -4) + 1); lua_pushinteger(L, lua_rawlen(L, -3)), lua_settable(L, -4); - } else lua_pop(L, 1); // view + } else + lua_pop(L, 1); // view } lua_pop(L, 1); // views lua_pushvalue(L, -1), lua_setfield(L, LUA_REGISTRYINDEX, "ta_views"); @@ -1688,27 +1632,26 @@ static void remove_view(lua_State *L, Scintilla *view) { * @param view The Scintilla view to remove. * @see remove_view */ -static void delete_view(Scintilla *view) { - remove_view(lua, view), scintilla_delete(view); -} +static void delete_view(Scintilla *view) { remove_view(lua, view), scintilla_delete(view); } /** - * Removes all Scintilla views from the given pane and deletes them along with - * the child panes themselves. + * Removes all Scintilla views from the given pane and deletes them along with the child panes + * themselves. * @param pane The pane to remove Scintilla views from. * @see delete_view */ static void remove_views_from_pane(Pane *pane) { #if GTK GtkWidget *child1 = gtk_paned_get_child1(GTK_PANED(pane)), - *child2 = gtk_paned_get_child2(GTK_PANED(pane)); + *child2 = gtk_paned_get_child2(GTK_PANED(pane)); GTK_IS_PANED(child1) ? remove_views_from_pane(child1) : delete_view(child1); GTK_IS_PANED(child2) ? remove_views_from_pane(child2) : delete_view(child2); #elif CURSES if (pane->type == VSPLIT || pane->type == HSPLIT) { remove_views_from_pane(pane->child1), remove_views_from_pane(pane->child2); delwin(pane->win), pane->win = NULL; // delete split bar - } else delete_view(pane->view); + } else + delete_view(pane->view); free(pane); #endif } @@ -1737,7 +1680,8 @@ static void resize_pane(Pane *pane, int rows, int cols, int y, int x) { resize_pane(pane->child1, ssize, cols, y, x); resize_pane(pane->child2, rows - ssize - 1, cols, y + ssize + 1, x); wresize(pane->win, 1, cols), mvwin(pane->win, y + ssize, x); // split bar - } else wresize(pane->win, rows, cols), mvwin(pane->win, y, x); + } else + wresize(pane->win, rows, cols), mvwin(pane->win, y, x); pane->rows = rows, pane->cols = cols, pane->y = y, pane->x = x; } @@ -1751,11 +1695,9 @@ static void resize_pane(Pane *pane, int rows, int cols, int y, int x) { */ static bool unsplit_pane(Pane *pane, Scintilla *view, Pane *parent) { if (pane->type != SINGLE) - return unsplit_pane(pane->child1, view, pane) || - unsplit_pane(pane->child2, view, pane); + return unsplit_pane(pane->child1, view, pane) || unsplit_pane(pane->child2, view, pane); if (pane->view != view) return false; - remove_views_from_pane( - pane == parent->child1 ? parent->child2 : parent->child1); + remove_views_from_pane(pane == parent->child1 ? parent->child2 : parent->child1); delwin(parent->win); // delete split bar // Inherit child's properties. parent->type = pane->type, parent->split_size = pane->split_size; @@ -1790,12 +1732,11 @@ static bool unsplit_view(Scintilla *view) { GtkWidget *parent = gtk_widget_get_parent(pane); gtk_container_remove(GTK_CONTAINER(parent), pane); if (GTK_IS_PANED(parent)) - !gtk_paned_get_child1(GTK_PANED(parent)) ? - gtk_paned_add1(GTK_PANED(parent), view) : - gtk_paned_add2(GTK_PANED(parent), view); + !gtk_paned_get_child1(GTK_PANED(parent)) ? gtk_paned_add1(GTK_PANED(parent), view) : + gtk_paned_add2(GTK_PANED(parent), view); else gtk_container_add(GTK_CONTAINER(parent), view); - //gtk_widget_show_all(parent); + // gtk_widget_show_all(parent); gtk_widget_grab_focus(GTK_WIDGET(view)); g_object_unref(view), g_object_unref(other); #elif CURSES @@ -1813,7 +1754,7 @@ static bool unsplit_view(Scintilla *view) { */ static void close_lua(lua_State *L) { closing = true; - while (unsplit_view(focused_view)) ; // need space to fix compiler warning + while (unsplit_view(focused_view)) {} lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"); for (size_t i = 1; i <= lua_rawlen(L, -1); i++) lua_rawgeti(L, -1, i), delete_buffer(lua_todoc(L, -1)), lua_pop(L, 1); @@ -1842,7 +1783,7 @@ static bool exiting(GtkWidget *_, GdkEventAny *__, void *L) { * Signal for opening files from macOS. * Generates an 'appleevent_odoc' event for each document sent. */ -static bool open_file(GtkosxApplication*_, char *path, void *L) { +static bool open_file(GtkosxApplication *_, char *path, void *L) { return (emit(L, "appleevent_odoc", LUA_TSTRING, path, -1), true); } @@ -1850,9 +1791,7 @@ static bool open_file(GtkosxApplication*_, char *path, void *L) { * Signal for block terminating Textadept from macOS. * Generates a 'quit' event. */ -static bool terminating(GtkosxApplication *_, void *L) { - return emit(L, "quit", -1); -} +static bool terminating(GtkosxApplication *_, void *L) { return emit(L, "quit", -1); } /** * Signal for terminating Textadept from macOS. @@ -1869,13 +1808,12 @@ static void terminate(GtkosxApplication *_, void *L) { /** * Signal for switching buffer tabs. - * When triggered by the user (i.e. not synchronizing the tabbar), switches to - * the specified buffer. + * When triggered by the user (i.e. not synchronizing the tabbar), switches to the specified + * buffer. * Generates 'buffer_before_switch' and 'buffer_after_switch' events. */ static void tab_changed(GtkNotebook *_, GtkWidget *__, int tab_num, void *L) { - if (!tab_sync) - emit(L, "tab_clicked", LUA_TNUMBER, tab_num + 1, LUA_TNUMBER, 1, -1); + if (!tab_sync) emit(L, "tab_clicked", LUA_TNUMBER, tab_num + 1, LUA_TNUMBER, 1, -1); } #endif // if GTK @@ -1891,32 +1829,27 @@ static void emit_notification(lua_State *L, SCNotification *n) { lua_pushinteger(L, n->position + 1), lua_setfield(L, -2, "position"); lua_pushinteger(L, n->ch), lua_setfield(L, -2, "ch"); lua_pushinteger(L, n->modifiers), lua_setfield(L, -2, "modifiers"); - lua_pushinteger(L, n->modificationType), - lua_setfield(L, -2, "modification_type"); + lua_pushinteger(L, n->modificationType), lua_setfield(L, -2, "modification_type"); if (n->text) lua_pushlstring(L, n->text, n->length ? n->length : strlen(n->text)), lua_setfield(L, -2, "text"); lua_pushinteger(L, n->length), lua_setfield(L, -2, "length"); lua_pushinteger(L, n->linesAdded), lua_setfield(L, -2, "lines_added"); - //lua_pushinteger(L, n->message), lua_setfield(L, -2, "message"); - //lua_pushinteger(L, n->wParam), lua_setfield(L, -2, "wParam"); - //lua_pushinteger(L, n->lParam), lua_setfield(L, -2, "lParam"); + // lua_pushinteger(L, n->message), lua_setfield(L, -2, "message"); + // lua_pushinteger(L, n->wParam), lua_setfield(L, -2, "wParam"); + // lua_pushinteger(L, n->lParam), lua_setfield(L, -2, "lParam"); lua_pushinteger(L, n->line + 1), lua_setfield(L, -2, "line"); - //lua_pushinteger(L, n->foldLevelNow), lua_setfield(L, -2, "fold_level_now"); - //lua_pushinteger(L, n->foldLevelPrev), - // lua_setfield(L, -2, "fold_level_prev"); + // lua_pushinteger(L, n->foldLevelNow), lua_setfield(L, -2, "fold_level_now"); + // lua_pushinteger(L, n->foldLevelPrev), lua_setfield(L, -2, "fold_level_prev"); lua_pushinteger(L, n->margin + 1), lua_setfield(L, -2, "margin"); lua_pushinteger(L, n->listType), lua_setfield(L, -2, "list_type"); lua_pushinteger(L, n->x), lua_setfield(L, -2, "x"); lua_pushinteger(L, n->y), lua_setfield(L, -2, "y"); - //lua_pushinteger(L, n->token), lua_setfield(L, -2, "token"); - //lua_pushinteger(L, n->annotationLinesAdded), - // lua_setfield(L, -2, "annotation_lines_added"); + // lua_pushinteger(L, n->token), lua_setfield(L, -2, "token"); + // lua_pushinteger(L, n->annotationLinesAdded), lua_setfield(L, -2, "annotation_lines_added"); lua_pushinteger(L, n->updated), lua_setfield(L, -2, "updated"); - //lua_pushinteger(L, n->listCompletionMethod), - // lua_setfield(L, -2, "list_completion_method"); - //lua_pushinteger(L, n->characterSource), - // lua_setfield(L, -2, "character_source"); + // lua_pushinteger(L, n->listCompletionMethod), lua_setfield(L, -2, "list_completion_method"); + // lua_pushinteger(L, n->characterSource), lua_setfield(L, -2, "character_source"); emit(L, "SCN", LUA_TTABLE, luaL_ref(L, LUA_REGISTRYINDEX), -1); } @@ -1924,7 +1857,7 @@ static void emit_notification(lua_State *L, SCNotification *n) { static void notified(Scintilla *view, int _, SCNotification *n, void *L) { if (view == command_entry) { if (n->nmhdr.code == SCN_MODIFIED && - (n->modificationType & (SC_MOD_INSERTTEXT | SC_MOD_DELETETEXT))) + (n->modificationType & (SC_MOD_INSERTTEXT | SC_MOD_DELETETEXT))) emit(L, "command_text_changed", -1); } else if (view == focused_view || n->nmhdr.code == SCN_URIDROPPED) { if (view != focused_view) view_focused(view, L); @@ -1939,13 +1872,10 @@ static void notified(Scintilla *view, int _, SCNotification *n, void *L) { * Note: cannot use bool return value due to modern i686-w64-mingw32-gcc issue. */ static int keypress(GtkWidget *_, GdkEventKey *event, void *L) { - return emit( - L, "keypress", LUA_TNUMBER, event->keyval, - LUA_TBOOLEAN, event->state & GDK_SHIFT_MASK, - LUA_TBOOLEAN, event->state & GDK_CONTROL_MASK, - LUA_TBOOLEAN, event->state & GDK_MOD1_MASK, - LUA_TBOOLEAN, event->state & GDK_META_MASK, - LUA_TBOOLEAN, event->state & GDK_LOCK_MASK, -1); + return emit(L, "keypress", LUA_TNUMBER, event->keyval, LUA_TBOOLEAN, + event->state & GDK_SHIFT_MASK, LUA_TBOOLEAN, event->state & GDK_CONTROL_MASK, LUA_TBOOLEAN, + event->state & GDK_MOD1_MASK, LUA_TBOOLEAN, event->state & GDK_META_MASK, LUA_TBOOLEAN, + event->state & GDK_LOCK_MASK, -1); } /** Signal for a Scintilla mouse click. */ @@ -1960,13 +1890,12 @@ static int goto_doc_lua(lua_State *L) { Scintilla *view = luaL_checkview(L, 1), *prev_view = focused_view; bool relative = lua_isnumber(L, 2); if (!relative) { - lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_pushvalue(L, 2), - lua_gettable(L, -2), lua_replace(L, 2); - luaL_argcheck( - L, lua_isnumber(L, 2), 2, "Buffer or relative index expected"); + lua_getfield(L, LUA_REGISTRYINDEX, "ta_buffers"), lua_pushvalue(L, 2), lua_gettable(L, -2), + lua_replace(L, 2); + luaL_argcheck(L, lua_isnumber(L, 2), 2, "Buffer or relative index expected"); } - // If the indexed view is not currently focused, temporarily focus it so - // `_G.buffer` in handlers is accurate. + // If the indexed view is not currently focused, temporarily focus it so `_G.buffer` in + // handlers is accurate. if (view != focused_view) focus_view(view); if (!initing) emit(L, "buffer_before_switch", -1); goto_doc(L, view, lua_tointeger(L, 2), relative); @@ -1995,9 +1924,7 @@ static Pane *new_pane(Scintilla *view) { * @param view2 The second Scintilla view to place in the split view. * @see split_view */ -static bool split_pane( - Pane *pane, bool vertical, Scintilla *view, Scintilla *view2) -{ +static bool split_pane(Pane *pane, bool vertical, Scintilla *view, Scintilla *view2) { if (pane->type != SINGLE) return split_pane(pane->child1, vertical, view, view2) || split_pane(pane->child2, vertical, view, view2); @@ -2009,15 +1936,13 @@ static bool split_pane( if (vertical) { pane->split_size = pane->cols / 2; resize_pane(child1, pane->rows, pane->split_size, pane->y, pane->x); - resize_pane( - child2, pane->rows, pane->cols - pane->split_size - 1, pane->y, + resize_pane(child2, pane->rows, pane->cols - pane->split_size - 1, pane->y, pane->x + pane->split_size + 1); pane->win = newwin(pane->rows, 1, pane->y, pane->x + pane->split_size); } else { pane->split_size = pane->rows / 2; resize_pane(child1, pane->split_size, pane->cols, pane->y, pane->x); - resize_pane( - child2, pane->rows - pane->split_size - 1, pane->cols, + resize_pane(child2, pane->rows - pane->split_size - 1, pane->cols, pane->y + pane->split_size + 1, pane->x); pane->win = newwin(1, pane->cols, pane->y + pane->split_size, pane->x); } @@ -2029,15 +1954,13 @@ static bool split_pane( * Splits the given Scintilla view into two views. * The new view shows the same document as the original one. * @param view The Scintilla view to split. - * @param vertical Flag indicating whether to split the view vertically or - * horozontally. + * @param vertical Flag indicating whether to split the view vertically or horozontally. */ static void split_view(Scintilla *view, bool vertical) { sptr_t curdoc = SS(view, SCI_GETDOCPOINTER, 0, 0); int first_line = SS(view, SCI_GETFIRSTVISIBLELINE, 0, 0), - x_offset = SS(view, SCI_GETXOFFSET, 0, 0), - current_pos = SS(view, SCI_GETCURRENTPOS, 0, 0), - anchor = SS(view, SCI_GETANCHOR, 0, 0); + x_offset = SS(view, SCI_GETXOFFSET, 0, 0), current_pos = SS(view, SCI_GETCURRENTPOS, 0, 0), + anchor = SS(view, SCI_GETANCHOR, 0, 0); #if GTK GtkAllocation allocation; @@ -2064,8 +1987,7 @@ static void split_view(Scintilla *view, bool vertical) { focus_view(view2); SS(view2, SCI_SETSEL, anchor, current_pos); - SS(view2, SCI_LINESCROLL, first_line - SS( - view2, SCI_GETFIRSTVISIBLELINE, 0, 0), 0); + SS(view2, SCI_LINESCROLL, first_line - SS(view2, SCI_GETFIRSTVISIBLELINE, 0, 0), 0); SS(view2, SCI_SETXOFFSET, x_offset, 0); } @@ -2105,23 +2027,22 @@ static int view_index(lua_State *L) { if (GTK_IS_PANED(p = gtk_widget_get_parent(lua_toview(L, 1)))) lua_pushinteger(L, gtk_paned_get_position(GTK_PANED(p))); #elif CURSES - if ((p = get_parent_pane(pane, lua_toview(L, 1)))) - lua_pushinteger(L, p->split_size); + if ((p = get_parent_pane(pane, lua_toview(L, 1)))) lua_pushinteger(L, p->split_size); #endif - } else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_functions"), - lua_pushvalue(L, 2), lua_rawget(L, -2) == LUA_TTABLE) + } else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_functions"), lua_pushvalue(L, 2), + lua_rawget(L, -2) == LUA_TTABLE) // If the key is a Scintilla function, return a callable closure. lua_pushcclosure(L, call_scintilla_lua, 1); - else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_properties"), - lua_pushvalue(L, 2), lua_rawget(L, -2) == LUA_TTABLE) - // If the key is a Scintilla property, determine if it is an indexible one - // or not. If so, return a table with the appropriate metatable; otherwise - // call Scintilla to get the property's value. + else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_properties"), lua_pushvalue(L, 2), + lua_rawget(L, -2) == LUA_TTABLE) + // If the key is a Scintilla property, determine if it is an indexible one or not. If so, + // return a table with the appropriate metatable; otherwise call Scintilla to get the + // property's value. get_property(L); - else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_constants"), - lua_pushvalue(L, 2), lua_rawget(L, -2) == LUA_TNUMBER); // pushed + else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_constants"), lua_pushvalue(L, 2), + lua_rawget(L, -2) == LUA_TNUMBER) { // pushed // If the key is a Scintilla constant, return its value. - else + } else lua_settop(L, 2), lua_rawget(L, 1); return 1; } @@ -2138,10 +2059,10 @@ static int view_newindex(lua_State *L) { #elif CURSES if ((p = get_parent_pane(pane, lua_toview(L, 1)))) p->split_size = fmax(luaL_checkinteger(L, 3), 0), - resize_pane(p, p->rows, p->cols, p->y, p->x); + resize_pane(p, p->rows, p->cols, p->y, p->x); #endif - } else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_properties"), - lua_pushvalue(L, 2), lua_rawget(L, -2) == LUA_TTABLE) + } else if (lua_getfield(L, LUA_REGISTRYINDEX, "ta_properties"), lua_pushvalue(L, 2), + lua_rawget(L, -2) == LUA_TTABLE) set_property(L); else lua_settop(L, 3), lua_rawset(L, 1); @@ -2162,8 +2083,7 @@ static void add_view(lua_State *L, Scintilla *view) { lua_pushcfunction(L, unsplit_view_lua), lua_setfield(L, -2, "unsplit"); set_metatable(L, -1, "ta_view", view_index, view_newindex); // t[widget_pointer] = view, t[#t + 1] = view, t[view] = #t - lua_getfield(L, -1, "widget_pointer"), lua_pushvalue(L, -2), - lua_settable(L, -4); + lua_getfield(L, -1, "widget_pointer"), lua_pushvalue(L, -2), lua_settable(L, -4); lua_pushvalue(L, -1), lua_rawseti(L, -3, lua_rawlen(L, -3) + 1); lua_pushinteger(L, lua_rawlen(L, -2)), lua_settable(L, -3); lua_pop(L, 1); // views @@ -2172,8 +2092,8 @@ static void add_view(lua_State *L, Scintilla *view) { /** * Creates a new Scintilla view. * Generates a 'view_new' event. - * @param doc The document to load in the new view. Almost never zero, except - * for the first Scintilla view created, in which there is no doc pointer. + * @param doc The document to load in the new view. Almost never zero, except for the first + * Scintilla view created, in which there is no doc pointer. * @return Scintilla view * @see add_view */ @@ -2208,16 +2128,13 @@ static bool find_keypress(GtkWidget *widget, GdkEventKey *event, void *L) { } /** - * Creates and returns for the findbox a new GtkComboBoxEntry, storing its - * GtkLabel, GtkEntry, and GtkListStore in the given pointers. + * Creates and returns for the findbox a new GtkComboBoxEntry, storing its GtkLabel, GtkEntry, + * and GtkListStore in the given pointers. */ -static GtkWidget *new_combo( - GtkWidget **label, GtkWidget **entry, ListStore **history) -{ +static GtkWidget *new_combo(GtkWidget **label, GtkWidget **entry, ListStore **history) { *label = gtk_label_new(""); // localized label text set later via Lua *history = gtk_list_store_new(1, G_TYPE_STRING); - GtkWidget *combo = gtk_combo_box_entry_new_with_model( - GTK_TREE_MODEL(*history), 0); + GtkWidget *combo = gtk_combo_box_entry_new_with_model(GTK_TREE_MODEL(*history), 0); g_object_unref(*history); gtk_combo_box_entry_set_text_column(GTK_COMBO_BOX_ENTRY(combo), 0); gtk_combo_box_set_focus_on_click(GTK_COMBO_BOX(combo), false); @@ -2234,9 +2151,7 @@ static GtkWidget *new_combo( } /** Signal for a Find entry keypress. */ -static void find_changed(GtkEditable *_, void *L) { - emit(L, "find_text_changed", -1); -} +static void find_changed(GtkEditable *_, void *L) { emit(L, "find_text_changed", -1); } /** Creates and returns a new button for the findbox. */ static GtkWidget *new_button() { @@ -2258,12 +2173,11 @@ static GtkWidget *new_findbox() { findbox = gtk_table_new(2, 6, false); GtkWidget *find_combo = new_combo(&find_label, &find_entry, &find_history), - *replace_combo = new_combo(&repl_label, &repl_entry, &repl_history); - g_signal_connect( - GTK_EDITABLE(find_entry), "changed", G_CALLBACK(find_changed), lua); + *replace_combo = new_combo(&repl_label, &repl_entry, &repl_history); + g_signal_connect(GTK_EDITABLE(find_entry), "changed", G_CALLBACK(find_changed), lua); find_next = new_button(), find_prev = new_button(), replace = new_button(), - replace_all = new_button(), match_case = new_option(), - whole_word = new_option(), regex = new_option(), in_files = new_option(); + replace_all = new_button(), match_case = new_option(), whole_word = new_option(), + regex = new_option(), in_files = new_option(); GtkTable *table = GTK_TABLE(findbox); int expand = GTK_FILL | GTK_EXPAND, shrink = GTK_FILL | GTK_SHRINK; @@ -2285,8 +2199,8 @@ static GtkWidget *new_findbox() { /** * Signal for window or command entry focus loss. - * Emit "Escape" key for the command entry on focus lost unless the window is - * losing focus or the application is quitting. + * Emit "Escape" key for the command entry on focus lost unless the window is losing focus or + * the application is quitting. */ static bool focus_lost(GtkWidget *widget, GdkEvent *_, void *L) { if (widget == window) { @@ -2300,9 +2214,8 @@ static bool focus_lost(GtkWidget *widget, GdkEvent *_, void *L) { /** * Creates the Textadept window. - * The window contains a menubar, frame for Scintilla views, hidden find box, - * hidden command entry, and two status bars: one for notifications and the - * other for buffer status. + * The window contains a menubar, frame for Scintilla views, hidden find box, hidden command + * entry, and two status bars: one for notifications and the other for buffer status. */ static void new_window() { #if GTK @@ -2324,18 +2237,15 @@ static void new_window() { g_signal_connect(window, "delete-event", G_CALLBACK(exiting), lua); g_signal_connect(window, "focus-in-event", G_CALLBACK(window_focused), lua); g_signal_connect(window, "focus-out-event", G_CALLBACK(focus_lost), lua); - g_signal_connect( - window, "key-press-event", G_CALLBACK(window_keypress), NULL); + g_signal_connect(window, "key-press-event", G_CALLBACK(window_keypress), NULL); gtdialog_set_parent(GTK_WINDOW(window)); accel = gtk_accel_group_new(); #if (__APPLE__ && !CURSES) gtkosx_application_set_use_quartz_accelerators(osxapp, false); g_signal_connect(osxapp, "NSApplicationOpenFile", G_CALLBACK(open_file), lua); - g_signal_connect( - osxapp, "NSApplicationBlockTermination", G_CALLBACK(terminating), lua); - g_signal_connect( - osxapp, "NSApplicationWillTerminate", G_CALLBACK(terminate), lua); + g_signal_connect(osxapp, "NSApplicationBlockTermination", G_CALLBACK(terminating), lua); + g_signal_connect(osxapp, "NSApplicationWillTerminate", G_CALLBACK(terminate), lua); #endif GtkWidget *vbox = gtk_vbox_new(false, 0); @@ -2368,11 +2278,9 @@ static void new_window() { gtk_widget_set_size_request(command_entry, 1, 1); g_signal_connect(command_entry, SCINTILLA_NOTIFY, G_CALLBACK(notified), lua); g_signal_connect(command_entry, "key-press-event", G_CALLBACK(keypress), lua); - g_signal_connect( - command_entry, "focus-out-event", G_CALLBACK(focus_lost), lua); + g_signal_connect(command_entry, "focus-out-event", G_CALLBACK(focus_lost), lua); gtk_paned_add2(GTK_PANED(paned), command_entry); - gtk_container_child_set( - GTK_CONTAINER(paned), command_entry, "shrink", false, NULL); + gtk_container_child_set(GTK_CONTAINER(paned), command_entry, "shrink", false, NULL); GtkWidget *hboxs = gtk_hbox_new(false, 0); gtk_box_pack_start(GTK_BOX(vbox), hboxs, false, false, 1); @@ -2384,8 +2292,8 @@ static void new_window() { gtk_misc_set_alignment(GTK_MISC(statusbar[1]), 1, 0); gtk_widget_show_all(window); - gtk_widget_hide(menubar), gtk_widget_hide(tabbar), - gtk_widget_hide(findbox), gtk_widget_hide(command_entry); // hide initially + gtk_widget_hide(menubar), gtk_widget_hide(tabbar), gtk_widget_hide(findbox), + gtk_widget_hide(command_entry); // hide initially dummy_view = scintilla_new(); #elif CURSES @@ -2405,7 +2313,8 @@ static bool read_pipe(GIOChannel *source, GIOCondition _, HANDLE pipe) { char *buf; size_t len; g_io_channel_read_to_end(source, &buf, &len, NULL); - for (char *p = buf; p < buf + len - 2; p++) if (!*p) *p = '\n'; // '\0\0' end + for (char *p = buf; p < buf + len - 2; p++) + if (!*p) *p = '\n'; // '\0\0' end process(NULL, NULL, buf); return (g_free(buf), DisconnectNamedPipe(pipe), false); } @@ -2414,10 +2323,8 @@ static bool read_pipe(GIOChannel *source, GIOCondition _, HANDLE pipe) { static DWORD WINAPI pipe_listener(HANDLE pipe) { while (true) if (pipe != INVALID_HANDLE_VALUE && ConnectNamedPipe(pipe, NULL)) { - GIOChannel *channel = g_io_channel_win32_new_fd( - _open_osfhandle((intptr_t)pipe, _O_RDONLY)); - g_io_add_watch(channel, G_IO_IN, read_pipe, pipe), - g_io_channel_unref(channel); + GIOChannel *channel = g_io_channel_win32_new_fd(_open_osfhandle((intptr_t)pipe, _O_RDONLY)); + g_io_add_watch(channel, G_IO_IN, read_pipe, pipe), g_io_channel_unref(channel); } return 0; } @@ -2439,8 +2346,7 @@ int g_application_run(GApplication *_, int __, char **___) { #if !_WIN32 /** * Signal for a terminal suspend, continue, and resize. - * libtermkey has been patched to enable suspend as well as enable/disable mouse - * mode (1002). + * libtermkey has been patched to enable suspend as well as enable/disable mouse mode (1002). */ static void signalled(int signal) { if (signal != SIGTSTP) { @@ -2464,8 +2370,7 @@ static TermKeyResult textadept_waitkey(TermKey *tk, TermKeyKey *key) { bool force = false; struct timeval timeout = {0, termkey_get_waittime(tk)}; while (true) { - TermKeyResult res = !force ? - termkey_getkey(tk, key) : termkey_getkey_force(tk, key); + TermKeyResult res = !force ? termkey_getkey(tk, key) : termkey_getkey_force(tk, key); if (res != TERMKEY_RES_AGAIN && res != TERMKEY_RES_NONE) return res; if (res == TERMKEY_RES_AGAIN) force = true; // Wait for input. @@ -2490,10 +2395,8 @@ static TermKeyResult textadept_waitkey(TermKey *tk, TermKeyKey *key) { /** * Runs Textadept. - * Initializes the Lua state, creates the user interface, and then runs - * `core/init.lua` followed by `init.lua`. - * On Windows, creates a pipe and thread for communication with remote - * instances. + * Initializes the Lua state, creates the user interface, and then runs `core/init.lua` followed + * by `init.lua`. On Windows, creates a pipe and thread for communication with remote instances. * @param argc The number of command line params. * @param argv The array of command line params. */ @@ -2554,36 +2457,34 @@ int main(int argc, char **argv) { if (!registered || !g_application_get_is_remote(app) || force) { #endif - setlocale(LC_COLLATE, "C"), setlocale(LC_NUMERIC, "C"); // for Lua - if (lua = luaL_newstate(), !init_lua(lua, argc, argv, false)) return 1; - initing = true, new_window(), run_file(lua, "init.lua"), initing = false; - emit(lua, "buffer_new", -1), emit(lua, "view_new", -1); // first ones - lua_pushdoc(lua, SS(command_entry, SCI_GETDOCPOINTER, 0, 0)), - lua_setglobal(lua, "buffer"); - emit(lua, "buffer_new", -1), emit(lua, "view_new", -1); // command entry - lua_pushdoc(lua, SS(focused_view, SCI_GETDOCPOINTER, 0, 0)), - lua_setglobal(lua, "buffer"); - emit(lua, "initialized", -1); // ready + setlocale(LC_COLLATE, "C"), setlocale(LC_NUMERIC, "C"); // for Lua + if (lua = luaL_newstate(), !init_lua(lua, argc, argv, false)) return 1; + initing = true, new_window(), run_file(lua, "init.lua"), initing = false; + emit(lua, "buffer_new", -1), emit(lua, "view_new", -1); // first ones + lua_pushdoc(lua, SS(command_entry, SCI_GETDOCPOINTER, 0, 0)), lua_setglobal(lua, "buffer"); + emit(lua, "buffer_new", -1), emit(lua, "view_new", -1); // command entry + lua_pushdoc(lua, SS(focused_view, SCI_GETDOCPOINTER, 0, 0)), lua_setglobal(lua, "buffer"); + emit(lua, "initialized", -1); // ready #if (__APPLE__ && !CURSES) - gtkosx_application_ready(osxapp); + gtkosx_application_ready(osxapp); #endif #if GTK gtk_main(); - } else g_application_run(app, argc, argv); + } else + g_application_run(app, argc, argv); g_object_unref(app); #elif CURSES refresh_all(); #if !_WIN32 freopen("/dev/null", "w", stderr); // redirect stderr - // Set terminal suspend, resume, and resize handlers, preventing any signals - // in them from causing interrupts. + // Set terminal suspend, resume, and resize handlers, preventing any signals in them from + // causing interrupts. struct sigaction act; memset(&act, 0, sizeof(struct sigaction)); act.sa_handler = signalled, sigfillset(&act.sa_mask); - sigaction(SIGTSTP, &act, NULL), sigaction(SIGCONT, &act, NULL), - sigaction(SIGWINCH, &act, NULL); + sigaction(SIGTSTP, &act, NULL), sigaction(SIGCONT, &act, NULL), sigaction(SIGWINCH, &act, NULL); #else freopen("NUL", "w", stdout), freopen("NUL", "w", stderr); // redirect #endif @@ -2592,15 +2493,17 @@ int main(int argc, char **argv) { int ch = 0, event = 0, button = 0, y = 0, x = 0, millis = 0; TermKeyResult res; TermKeyKey key; + // clang-format off int keysyms[] = {0,SCK_BACK,SCK_TAB,SCK_RETURN,SCK_ESCAPE,0,SCK_BACK,SCK_UP,SCK_DOWN,SCK_LEFT,SCK_RIGHT,0,0,SCK_INSERT,SCK_DELETE,0,SCK_PRIOR,SCK_NEXT,SCK_HOME,SCK_END}; + // clang-format on while ((ch = 0, res = textadept_waitkey(ta_tk, &key)) != TERMKEY_RES_EOF) { if (res == TERMKEY_RES_ERROR) continue; if (key.type == TERMKEY_TYPE_UNICODE) ch = key.code.codepoint; else if (key.type == TERMKEY_TYPE_FUNCTION) ch = 0xFFBD + key.code.number; // use GDK keysym values for now - else if (key.type == TERMKEY_TYPE_KEYSYM && - key.code.sym >= 0 && key.code.sym <= TERMKEY_SYM_END) + else if (key.type == TERMKEY_TYPE_KEYSYM && key.code.sym >= 0 && + key.code.sym <= TERMKEY_SYM_END) ch = keysyms[key.code.sym]; else if (key.type == TERMKEY_TYPE_UNKNOWN_CSI) { long args[16]; @@ -2608,13 +2511,10 @@ int main(int argc, char **argv) { unsigned long cmd; termkey_interpret_csi(ta_tk, &key, args, &nargs, &cmd); lua_newtable(lua); - for (size_t i = 0; i < nargs; i++) - lua_pushinteger(lua, args[i]), lua_rawseti(lua, -2, i + 1); - emit(lua, "csi", LUA_TNUMBER, cmd, LUA_TTABLE, luaL_ref( - lua, LUA_REGISTRYINDEX), -1); + for (size_t i = 0; i < nargs; i++) lua_pushinteger(lua, args[i]), lua_rawseti(lua, -2, i + 1); + emit(lua, "csi", LUA_TNUMBER, cmd, LUA_TTABLE, luaL_ref(lua, LUA_REGISTRYINDEX), -1); } else if (key.type == TERMKEY_TYPE_MOUSE) { - termkey_interpret_mouse( - ta_tk, &key, (TermKeyMouseEvent*)&event, &button, &y, &x), y--, x--; + termkey_interpret_mouse(ta_tk, &key, (TermKeyMouseEvent *)&event, &button, &y, &x), y--, x--; #if !_WIN32 struct timeval time = {0, 0}; gettimeofday(&time, NULL); @@ -2626,23 +2526,20 @@ int main(int argc, char **argv) { ticks.LowPart = time.dwLowDateTime, ticks.HighPart = time.dwHighDateTime; millis = ticks.QuadPart / 10000; // each tick is a 100-nanosecond interval #endif - } else continue; // skip unknown types + } else + continue; // skip unknown types bool shift = key.modifiers & TERMKEY_KEYMOD_SHIFT; bool ctrl = key.modifiers & TERMKEY_KEYMOD_CTRL; bool alt = key.modifiers & TERMKEY_KEYMOD_ALT; - if (ch && !emit( - lua, "keypress", LUA_TNUMBER, ch, LUA_TBOOLEAN, shift, - LUA_TBOOLEAN, ctrl, LUA_TBOOLEAN, alt, -1)) + if (ch && + !emit(lua, "keypress", LUA_TNUMBER, ch, LUA_TBOOLEAN, shift, LUA_TBOOLEAN, ctrl, LUA_TBOOLEAN, + alt, -1)) scintilla_send_key(view, ch, shift, ctrl, alt); - else if (!ch && !scintilla_send_mouse( - view, event, millis, button, y, x, shift, ctrl, alt) && - !emit( - lua, "mouse", LUA_TNUMBER, event, LUA_TNUMBER, button, - LUA_TNUMBER, y, LUA_TNUMBER, x, LUA_TBOOLEAN, shift, - LUA_TBOOLEAN, ctrl, LUA_TBOOLEAN, alt, -1)) + else if (!ch && !scintilla_send_mouse(view, event, millis, button, y, x, shift, ctrl, alt) && + !emit(lua, "mouse", LUA_TNUMBER, event, LUA_TNUMBER, button, LUA_TNUMBER, y, LUA_TNUMBER, x, + LUA_TBOOLEAN, shift, LUA_TBOOLEAN, ctrl, LUA_TBOOLEAN, alt, -1)) // Try again with possibly another view. - scintilla_send_mouse( - focused_view, event, millis, button, y, x, shift, ctrl, alt); + scintilla_send_mouse(focused_view, event, millis, button, y, x, shift, ctrl, alt); if (quitting) { close_lua(lua); // Free some memory. diff --git a/test/test.lua b/test/test.lua index b35ae0f1..e9c6bf75 100644 --- a/test/test.lua +++ b/test/test.lua @@ -29,18 +29,14 @@ function assert_equal(v1, v2) error(string.format('%s ~= %s', v1, v2), 2) end - --- Asserts that function *f* raises an error whose error message contains string --- *expected_errmsg*. +-- Asserts that function *f* raises an error whose error message contains string *expected_errmsg*. -- @param f Function to call. -- @param expected_errmsg String the error message should contain. function assert_raises(f, expected_errmsg) local ok, errmsg = pcall(f) if ok then error('error expected', 2) end - if expected_errmsg ~= errmsg and - not tostring(errmsg):find(expected_errmsg, 1, true) then - error(string.format( - 'error message %q expected, was %q', expected_errmsg, errmsg), 2) + if expected_errmsg ~= errmsg and not tostring(errmsg):find(expected_errmsg, 1, true) then + error(string.format('error message %q expected, was %q', expected_errmsg, errmsg), 2) end end @@ -67,11 +63,14 @@ function test_assert_types() end assert_equal(foo('bar'), 'bar') assert_raises(function() foo(1) end, "bad argument #1 to 'foo' (string expected, got number") - assert_raises(function() foo('bar', 'baz') end, "bad argument #2 to 'foo' (boolean/nil expected, got string") - assert_raises(function() foo('bar', true, 1) end, "bad argument #3 to 'foo' (string/table/nil expected, got number") + assert_raises(function() foo('bar', 'baz') end, + "bad argument #2 to 'foo' (boolean/nil expected, got string") + assert_raises(function() foo('bar', true, 1) end, + "bad argument #3 to 'foo' (string/table/nil expected, got number") function foo(bar) assert_type(bar, string) end - assert_raises(function() foo(1) end, "bad argument #2 to 'assert_type' (string expected, got table") + assert_raises(function() foo(1) end, + "bad argument #2 to 'assert_type' (string expected, got table") function foo(bar) assert_type(bar, 'string') end assert_raises(function() foo(1) end, "bad argument #3 to 'assert_type' (value expected, got nil") end @@ -167,17 +166,14 @@ local function load_locale(locale_conf) for line in io.lines(locale_conf) do if not line:find('^%s*[^%w_%[]') then local id, str = line:match('^(.-)%s*=%s*(.+)$') - if id and str and assert(not L[id], 'duplicate locale id "%s"', id) then - L[id] = str - end + if id and str and assert(not L[id], 'duplicate locale id "%s"', id) then L[id] = str end end end locales[locale_conf] = L return L end --- Looks for use of localization in the given Lua file and verifies that each --- use is okay. +-- Looks for use of localization in the given Lua file and verifies that each use is okay. -- @param filename String filename of the Lua file to check. -- @param L Table of localizations to read from. local function check_localizations(filename, L) @@ -193,8 +189,7 @@ local function check_localizations(filename, L) end local loaded_extra = {} --- Records localization assignments in the given Lua file for use in subsequent --- checks. +-- Records localization assignments in the given Lua file for use in subsequent checks. -- @param L Table of localizations to add to. local function load_extra_localizations(filename, L) if loaded_extra[filename] then return end @@ -229,46 +224,36 @@ function test_locale_use_core() local ta_dirs = {'core', 'modules/ansi_c', 'modules/lua', 'modules/textadept'} for _, dir in ipairs(ta_dirs) do dir = _HOME .. '/' .. dir - for filename in lfs.walk(dir, '.lua') do - check_localizations(filename, L) - end + for filename in lfs.walk(dir, '.lua') do check_localizations(filename, L) end end check_localizations(_HOME .. '/init.lua', L) end function test_locale_use_extra() local L = load_locale(LOCALE_CONF) - for filename in lfs.walk(_HOME, '.lua') do - load_extra_localizations(filename, L) - end - for filename in lfs.walk(_HOME, '.lua') do - check_localizations(filename, L) - end + for filename in lfs.walk(_HOME, '.lua') do load_extra_localizations(filename, L) end + for filename in lfs.walk(_HOME, '.lua') do check_localizations(filename, L) end end function test_locale_use_userhome() local L = load_locale(LOCALE_CONF) - for filename in lfs.walk(_HOME, '.lua') do - load_extra_localizations(filename, L) - end - for filename in lfs.walk(_USERHOME, '.lua') do - load_extra_localizations(filename, L) - end + for filename in lfs.walk(_HOME, '.lua') do load_extra_localizations(filename, L) end + for filename in lfs.walk(_USERHOME, '.lua') do load_extra_localizations(filename, L) end L['%1'] = true -- snippet - for filename in lfs.walk(_USERHOME, '.lua') do - check_localizations(filename, L) - end + for filename in lfs.walk(_USERHOME, '.lua') do check_localizations(filename, L) end end function test_file_io_open_file_detect_encoding() io.recent_files = {} -- clear local recent_files = {} + -- LuaFormatter off local files = { [_HOME .. '/test/file_io/utf8'] = 'UTF-8', [_HOME .. '/test/file_io/cp1252'] = 'CP1252', [_HOME .. '/test/file_io/utf16'] = 'UTF-16', - [_HOME .. '/test/file_io/binary'] = '', + [_HOME .. '/test/file_io/binary'] = '' } + -- LuaFormatter on for filename, encoding in pairs(files) do print(string.format('Opening file %s', filename)) io.open_file(filename) @@ -277,7 +262,7 @@ function test_file_io_open_file_detect_encoding() local contents = f:read('a') f:close() if encoding ~= '' then - --assert_equal(buffer:get_text():iconv(encoding, 'UTF-8'), contents) + -- assert_equal(buffer:get_text():iconv(encoding, 'UTF-8'), contents) assert_equal(buffer.encoding, encoding) assert_equal(buffer.code_page, buffer.CP_UTF8) else @@ -291,15 +276,18 @@ function test_file_io_open_file_detect_encoding() assert_equal(io.recent_files, recent_files) assert_raises(function() io.open_file(1) end, 'string/table/nil expected, got number') - assert_raises(function() io.open_file('/tmp/foo', true) end, 'string/table/nil expected, got boolean') + assert_raises(function() io.open_file('/tmp/foo', true) end, + 'string/table/nil expected, got boolean') -- TODO: encoding failure end function test_file_io_open_file_detect_newlines() + -- LuaFormatter off local files = { [_HOME .. '/test/file_io/lf'] = buffer.EOL_LF, - [_HOME .. '/test/file_io/crlf'] = buffer.EOL_CRLF, + [_HOME .. '/test/file_io/crlf'] = buffer.EOL_CRLF } + -- LuaFormatter on for filename, mode in pairs(files) do io.open_file(filename) assert_equal(buffer.eol_mode, mode) @@ -309,11 +297,13 @@ end function test_file_io_open_file_with_encoding() local num_buffers = #_BUFFERS + -- LuaFormatter off local files = { _HOME .. '/test/file_io/utf8', _HOME .. '/test/file_io/cp1252', _HOME .. '/test/file_io/utf16' } + -- LuaFormatter on local encodings = {nil, 'CP1252', 'UTF-16'} io.open_file(files, encodings) assert_equal(#_BUFFERS, num_buffers + #files) @@ -346,7 +336,8 @@ end function test_file_io_open_file_errors() if LINUX then - assert_raises(function() io.open_file('/etc/group-') end, 'cannot open /etc/group-: Permission denied') + assert_raises(function() io.open_file('/etc/group-') end, + 'cannot open /etc/group-: Permission denied') end -- TODO: find a case where the file can be opened, but not read end @@ -485,12 +476,14 @@ end function test_file_io_recent_files() io.recent_files = {} -- clear local recent_files = {} + -- LuaFormatter off local files = { _HOME .. '/test/file_io/utf8', _HOME .. '/test/file_io/cp1252', _HOME .. '/test/file_io/utf16', _HOME .. '/test/file_io/binary' } + -- LuaFormatter on for _, filename in ipairs(files) do io.open_file(filename) buffer:close() @@ -619,11 +612,13 @@ function test_keys_modes() buffer.new() local foo, bar = false, false keys.a = function() foo = true end - keys.test_mode = {a = function() - bar = true - keys.mode = nil - return false -- propagate - end} + keys.test_mode = { + a = function() + bar = true + keys.mode = nil + return false -- propagate + end + } keys.cpp.a = function() keys.mode = 'test_mode' end events.emit(events.KEYPRESS, string.byte('a')) assert(foo, 'foo not set') @@ -691,7 +686,8 @@ expected_failure(test_lfs_ext_walk_filter_dir) function test_lfs_ext_walk_filter_mixed() local count = 0 for filename in lfs.walk(_HOME .. '/core', {'!/locales', '.lua'}) do - assert(not filename:find('/locales/') and filename:find('%.lua$'), '"%s" should not match', filename) + assert(not filename:find('/locales/') and filename:find('%.lua$'), '"%s" should not match', + filename) count = count + 1 end assert(count > 0, 'no matching files found') @@ -754,7 +750,9 @@ function test_lfs_ext_walk_symlinks() files[#files + 1] = filename end table.sort(files) - local expected_files = {dir .. '/1/foo', dir .. '/1/bar/baz', dir .. '/1/2/foobar', dir .. '/1/2/foobaz'} + local expected_files = { + dir .. '/1/foo', dir .. '/1/bar/baz', dir .. '/1/2/foobar', dir .. '/1/2/foobaz' + } table.sort(expected_files) assert_equal(files, expected_files) os.execute('rm -r ' .. dir) @@ -867,13 +865,14 @@ function test_ui_dialogs_colorselect_interactive() local color = ui.dialogs.colorselect{title = 'Blue', color = 0xFF0000} assert_equal(color, 0xFF0000) color = ui.dialogs.colorselect{ - title = 'Red', color = '#FF0000', palette = {'#FF0000', 0x00FF00}, - string_output = true + title = 'Red', color = '#FF0000', palette = {'#FF0000', 0x00FF00}, string_output = true } assert_equal(color, '#FF0000') - assert_raises(function() ui.dialogs.colorselect{title = function() end} end, "bad argument #title to 'colorselect' (string/number/table/boolean expected, got function") - assert_raises(function() ui.dialogs.colorselect{palette = {true}} end, "bad argument #palette[1] to 'colorselect' (string/number expected, got boolean") + assert_raises(function() ui.dialogs.colorselect{title = function() end} end, + "bad argument #title to 'colorselect' (string/number/table/boolean expected, got function") + assert_raises(function() ui.dialogs.colorselect{palette = {true}} end, + "bad argument #palette[1] to 'colorselect' (string/number expected, got boolean") end function test_ui_dialogs_dropdown_interactive() @@ -884,70 +883,62 @@ function test_ui_dialogs_dropdown_interactive() assert_equal(type(button), 'number') assert_equal(i, 1) button, i = ui.dialogs[dropdown]{ - text = 'foo', items = {'bar', 'baz', 'quux'}, select = 2, - no_cancel = true, width = 400, height = 400 + text = 'foo', items = {'bar', 'baz', 'quux'}, select = 2, no_cancel = true, width = 400, + height = 400 } assert_equal(i, 2) end - assert_raises(function() ui.dialogs.dropdown{items = {'foo', 'bar', 'baz'}, select = true} end, "bad argument #select to 'dropdown' (number expected, got boolean") - assert_raises(function() ui.dialogs.dropdown{items = {'foo', 'bar', 'baz', true}} end, "bad argument #items[4] to 'dropdown' (string/number expected, got boolean") + assert_raises(function() ui.dialogs.dropdown{items = {'foo', 'bar', 'baz'}, select = true} end, + "bad argument #select to 'dropdown' (number expected, got boolean") + assert_raises(function() ui.dialogs.dropdown{items = {'foo', 'bar', 'baz', true}} end, + "bad argument #items[4] to 'dropdown' (string/number expected, got boolean") end function test_ui_dialogs_filesave_fileselect_interactive() local test_filename = _HOME .. '/test/ui/empty' local test_dir, test_file = test_filename:match('^(.+[/\\])([^/\\]+)$') local filename = ui.dialogs.filesave{ - with_directory = test_dir, with_file = test_file, - no_create_directories = true + with_directory = test_dir, with_file = test_file, no_create_directories = true } assert_equal(filename, test_filename) filename = ui.dialogs.fileselect{ with_directory = test_dir, with_file = test_file, select_multiple = true } assert_equal(filename, {test_filename}) - filename = ui.dialogs.fileselect{ - with_directory = test_dir, select_only_directories = true - } + filename = ui.dialogs.fileselect{with_directory = test_dir, select_only_directories = true} assert_equal(filename, test_dir:match('^(.+)/$')) end function test_ui_dialogs_filteredlist_interactive() local _, i = ui.dialogs.filteredlist{ - informative_text = 'foo', columns = '1', items = {'bar', 'baz', 'quux'}, - text = 'b z' + informative_text = 'foo', columns = '1', items = {'bar', 'baz', 'quux'}, text = 'b z' } assert_equal(i, 2) local _, text = ui.dialogs.filteredlist{ - columns = {'1', '2'}, - items = {'foo', 'foobar', 'bar', 'barbaz', 'baz', 'bazfoo'}, + columns = {'1', '2'}, items = {'foo', 'foobar', 'bar', 'barbaz', 'baz', 'bazfoo'}, search_column = 2, text = 'baz', output_column = 2, string_output = true, - select_multiple = true, button1 = _L['OK'], button2 = _L['Cancel'], - button3 = 'Other', width = ui.size[1] / 2 + select_multiple = true, button1 = _L['OK'], button2 = _L['Cancel'], button3 = 'Other', + width = ui.size[1] / 2 } assert_equal(text, {'barbaz'}) end function test_ui_dialogs_fontselect_interactive() - local font = ui.dialogs.fontselect{ - font_name = 'Monospace', font_size = 14, font_style = 'Bold' - } + local font = ui.dialogs.fontselect{font_name = 'Monospace', font_size = 14, font_style = 'Bold'} assert_equal(font, 'Monospace Bold 14') end function test_ui_dialogs_inputbox_interactive() local inputboxes = { - 'inputbox', 'secure_inputbox', 'standard_inputbox', - 'secure_standard_inputbox' + 'inputbox', 'secure_inputbox', 'standard_inputbox', 'secure_standard_inputbox' } for _, inputbox in ipairs(inputboxes) do print('Running ' .. inputbox) local button, text = ui.dialogs[inputbox]{text = 'foo'} assert_equal(type(button), 'number') assert_equal(text, 'foo') - button, text = ui.dialogs[inputbox]{ - text = 'foo', string_output = true, no_cancel = true - } + button, text = ui.dialogs[inputbox]{text = 'foo', string_output = true, no_cancel = true} assert_equal(type(button), 'string') assert_equal(text, 'foo') end @@ -958,8 +949,7 @@ function test_ui_dialogs_inputbox_interactive() assert_equal(type(button), 'number') assert_equal(text, {'bar', 'quux'}) button = ui.dialogs.inputbox{ - informative_text = {'info', 'foo', 'baz'}, text = {'bar', 'quux'}, - string_output = true + informative_text = {'info', 'foo', 'baz'}, text = {'bar', 'quux'}, string_output = true } assert_equal(type(button), 'string') end @@ -972,8 +962,7 @@ function test_ui_dialogs_msgbox_interactive() local button = ui.dialogs[msgbox]{icon = icons[i]} assert_equal(type(button), 'number') button = ui.dialogs[msgbox]{ - icon_file = _HOME .. '/core/images/ta_32x32.png', string_output = true, - no_cancel = true + icon_file = _HOME .. '/core/images/ta_32x32.png', string_output = true, no_cancel = true } assert_equal(type(button), 'string') end @@ -987,7 +976,9 @@ function test_ui_dialogs_optionselect_interactive() } assert_equal(selected, {'foo', 'baz'}) - assert_raises(function() ui.dialogs.optionselect{items = {'foo', 'bar', 'baz'}, select = {1, 'bar'}} end, "bad argument #select[2] to 'optionselect' (number expected, got string") + assert_raises(function() + ui.dialogs.optionselect{items = {'foo', 'bar', 'baz'}, select = {1, 'bar'}} + end, "bad argument #select[2] to 'optionselect' (number expected, got string") end function test_ui_dialogs_progressbar_interactive() @@ -999,12 +990,11 @@ function test_ui_dialogs_progressbar_interactive() return i, i .. '%' end) - local stopped = ui.dialogs.progressbar({ - title = 'foo', indeterminite = true, stoppable = true - }, function() - os.execute('sleep 0.1') - return 50 - end) + local stopped = ui.dialogs.progressbar({title = 'foo', indeterminite = true, stoppable = true}, + function() + os.execute('sleep 0.1') + return 50 + end) assert(stopped, 'progressbar not stopped') ui.update() -- allow GTK to remove callback for previous function @@ -1030,9 +1020,7 @@ function test_ui_dialogs_progressbar_interactive() end function test_ui_dialogs_textbox_interactive() - ui.dialogs.textbox{ - text = 'foo', editable = true, selected = true, monospaced_font = true - } + ui.dialogs.textbox{text = 'foo', editable = true, selected = true, monospaced_font = true} ui.dialogs.textbox{text_from_file = _HOME .. '/LICENSE', scroll_to = 'bottom'} end @@ -1100,8 +1088,7 @@ function test_ui_buffer_switch_save_restore_properties() local filename = _HOME .. '/test/ui/test.lua' io.open_file(filename) buffer:goto_pos(10) - view:fold_line( - buffer:line_from_position(buffer.current_pos), view.FOLDACTION_CONTRACT) + view:fold_line(buffer:line_from_position(buffer.current_pos), view.FOLDACTION_CONTRACT) view.margin_width_n[1] = 0 -- hide line numbers view:goto_buffer(-1) assert(view.margin_width_n[1] > 0, 'line numbers are still hidden') @@ -1257,9 +1244,8 @@ end function test_command_entry_run() local command_run, tab_pressed = false, false - ui.command_entry.run(function(command) command_run = command end, { - ['\t'] = function() tab_pressed = true end - }, nil, 2) + ui.command_entry.run(function(command) command_run = command end, + {['\t'] = function() tab_pressed = true end}, nil, 2) ui.update() -- redraw command entry assert_equal(ui.command_entry.active, true) assert_equal(ui.command_entry:get_lexer(), 'text') @@ -1271,10 +1257,14 @@ function test_command_entry_run() assert(tab_pressed, '\\t not registered') assert_equal(ui.command_entry.active, false) - assert_raises(function() ui.command_entry.run(function() end, 1) end, 'table/string/nil expected, got number') - assert_raises(function() ui.command_entry.run(function() end, {}, 1) end, 'string/nil expected, got number') - assert_raises(function() ui.command_entry.run(function() end, {}, 'lua', true) end, 'number/nil expected, got boolean') - assert_raises(function() ui.command_entry.run(function() end, 'lua', true) end, 'number/nil expected, got boolean') + assert_raises(function() ui.command_entry.run(function() end, 1) end, + 'table/string/nil expected, got number') + assert_raises(function() ui.command_entry.run(function() end, {}, 1) end, + 'string/nil expected, got number') + assert_raises(function() ui.command_entry.run(function() end, {}, 'lua', true) end, + 'number/nil expected, got boolean') + assert_raises(function() ui.command_entry.run(function() end, 'lua', true) end, + 'number/nil expected, got boolean') end local function run_lua_command(command) @@ -1323,7 +1313,8 @@ function test_command_entry_run_lua_abbreviated_env() run_lua_command('editing') assert(buffer:get_text():find('%b{}%s*$'), 'textadept.editing result not a table') run_lua_command('editing.select_paragraph') - assert(buffer.selection_start ~= buffer.selection_end, 'textadept.editing.select_paragraph() did not select paragraph') + assert(buffer.selection_start ~= buffer.selection_end, + 'textadept.editing.select_paragraph() did not select paragraph') buffer:close() end @@ -1442,8 +1433,10 @@ function test_command_entry_history_append() events.emit(events.KEYPRESS, not CURSES and 0xFF0D or 343) -- \n assert_raises(function() ui.command_entry.append_history(1) end, 'string expected, got number') - assert_raises(function() ui.command_entry:append_history('text') end, 'function expected, got table') - assert_raises(function() ui.command_entry.append_history(function() end, true) end, 'string/nil expected, got boolean') + assert_raises(function() ui.command_entry:append_history('text') end, + 'function expected, got table') + assert_raises(function() ui.command_entry.append_history(function() end, true) end, + 'string/nil expected, got boolean') end function test_command_entry_mode_restore() @@ -1533,20 +1526,24 @@ function test_editing_strip_trailing_spaces() local strip = textadept.editing.strip_trailing_spaces textadept.editing.strip_trailing_spaces = true buffer.new() + -- LuaFormatter off local text = table.concat({ 'foo ', ' bar\t\r', 'baz\t ' }, '\n') + -- LuaFormatter on buffer:set_text(text) buffer:goto_pos(buffer.line_end_position[2]) events.emit(events.FILE_BEFORE_SAVE) + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ 'foo', ' bar', 'baz', '' }, '\n')) + -- LuaFormatter on assert_equal(buffer.current_pos, buffer.line_end_position[2]) buffer:undo() assert_equal(buffer:get_text(), text) @@ -1558,16 +1555,19 @@ function test_editing_strip_trailing_spaces() end function test_editing_paste_reindent_tabs_to_tabs() + -- LuaFormatter off ui.clipboard_text = table.concat({ '\tfoo', '', '\t\tbar', '\tbaz' }, '\n') + -- LuaFormatter on buffer.new() buffer.use_tabs, buffer.eol_mode = true, buffer.EOL_CRLF buffer:add_text('quux\r\n') textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ 'quux', 'foo', @@ -1575,11 +1575,13 @@ function test_editing_paste_reindent_tabs_to_tabs() '\tbar', 'baz' }, '\r\n')) + -- LuaFormatter on buffer:clear_all() buffer:add_text('\t\tquux\r\n\r\n') -- no auto-indent assert_equal(buffer.line_indentation[2], 0) assert_equal(buffer.line_indentation[3], 0) textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '\t\tquux', '', @@ -1588,12 +1590,14 @@ function test_editing_paste_reindent_tabs_to_tabs() '\t\t\tbar', '\t\tbaz' }, '\r\n')) + -- LuaFormatter on buffer:clear_all() buffer:add_text('\t\tquux\r\n') assert_equal(buffer.line_indentation[2], 0) buffer:new_line() -- auto-indent assert_equal(buffer.line_indentation[3], 2 * buffer.tab_width) textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '\t\tquux', '', @@ -1602,11 +1606,13 @@ function test_editing_paste_reindent_tabs_to_tabs() '\t\t\tbar', '\t\tbaz' }, '\r\n')) + -- LuaFormatter on buffer:close(true) end expected_failure(test_editing_paste_reindent_tabs_to_tabs) function test_editing_paste_reindent_spaces_to_spaces() + -- LuaFormatter off ui.clipboard_text = table.concat({ ' foo', '', @@ -1614,10 +1620,12 @@ function test_editing_paste_reindent_spaces_to_spaces() ' baz', ' quux' }, '\n') + -- LuaFormatter on buffer.new() buffer.use_tabs, buffer.tab_width = false, 2 buffer:add_text('foobar\n') textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ 'foobar', 'foo', @@ -1626,11 +1634,13 @@ function test_editing_paste_reindent_spaces_to_spaces() ' baz', 'quux' }, '\n')) + -- LuaFormatter on buffer:clear_all() buffer:add_text(' foobar\n\n') -- no auto-indent assert_equal(buffer.line_indentation[2], 0) assert_equal(buffer.line_indentation[3], 0) textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ ' foobar', '', @@ -1640,12 +1650,14 @@ function test_editing_paste_reindent_spaces_to_spaces() ' baz', ' quux' }, '\n')) + -- LuaFormatter on buffer:clear_all() buffer:add_text(' foobar\n') assert_equal(buffer.line_indentation[2], 0) buffer:new_line() -- auto-indent assert_equal(buffer.line_indentation[3], 4) textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ ' foobar', '', @@ -1655,31 +1667,37 @@ function test_editing_paste_reindent_spaces_to_spaces() ' baz', ' quux' }, '\n')) + -- LuaFormatter on buffer:close(true) end expected_failure(test_editing_paste_reindent_spaces_to_spaces) function test_editing_paste_reindent_spaces_to_tabs() + -- LuaFormatter off ui.clipboard_text = table.concat({ ' foo', ' bar', ' baz' }, '\n') + -- LuaFormatter on buffer.new() buffer.use_tabs, buffer.tab_width = true, 4 buffer:add_text('\tquux') buffer:new_line() textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '\tquux', '\tfoo', '\t\tbar', '\tbaz' }, '\n')) + -- LuaFormatter on buffer:close(true) end function test_editing_paste_reindent_tabs_to_spaces() + -- LuaFormatter off ui.clipboard_text = table.concat({ '\tif foo and', '\t bar then', @@ -1687,6 +1705,7 @@ function test_editing_paste_reindent_tabs_to_spaces() '\tend', '' }, '\n') + -- LuaFormatter on buffer.new() buffer.use_tabs, buffer.tab_width = false, 2 buffer:set_lexer('lua') @@ -1695,6 +1714,7 @@ function test_editing_paste_reindent_tabs_to_spaces() buffer:insert_text(-1, 'end') buffer:colorize(1, -1) -- first line should be a fold header textadept.editing.paste_reindent() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ 'function quux()', ' if foo and', @@ -1703,6 +1723,7 @@ function test_editing_paste_reindent_tabs_to_spaces() ' end', 'end' }, '\n')) + -- LuaFormatter on buffer:close(true) end expected_failure(test_editing_paste_reindent_tabs_to_spaces) @@ -1713,21 +1734,25 @@ function test_editing_toggle_comment_lines() textadept.editing.toggle_comment() assert_equal(buffer:get_text(), 'foo') buffer:set_lexer('lua') + -- LuaFormatter off local text = table.concat({ '', 'local foo = "bar"', ' local baz = "quux"', '' }, '\n') + -- LuaFormatter on buffer:set_text(text) buffer:goto_pos(buffer:position_from_line(2)) textadept.editing.toggle_comment() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '', '--local foo = "bar"', ' local baz = "quux"', '' }, '\n')) + -- LuaFormatter on assert_equal(buffer.current_pos, buffer:position_from_line(2) + 2) textadept.editing.toggle_comment() -- uncomment assert_equal(buffer:get_line(2), 'local foo = "bar"\n') @@ -1735,21 +1760,25 @@ function test_editing_toggle_comment_lines() local offset = 5 buffer:set_sel(buffer:position_from_line(2) + offset, buffer:position_from_line(4) - offset) textadept.editing.toggle_comment() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '', '--local foo = "bar"', '-- local baz = "quux"', '' }, '\n')) + -- LuaFormatter on assert_equal(buffer.selection_start, buffer:position_from_line(2) + offset + 2) assert_equal(buffer.selection_end, buffer:position_from_line(4) - offset) textadept.editing.toggle_comment() -- uncomment + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '', 'local foo = "bar"', ' local baz = "quux"', '' }, '\n')) + -- LuaFormatter on assert_equal(buffer.selection_start, buffer:position_from_line(2) + offset) assert_equal(buffer.selection_end, buffer:position_from_line(4) - offset) buffer:undo() -- comment @@ -1761,29 +1790,35 @@ end function test_editing_toggle_comment() buffer.new() buffer:set_lexer('ansi_c') + -- LuaFormatter off buffer:set_text(table.concat({ '', ' const char *foo = "bar";', 'const char *baz = "quux";', '' }, '\n')) + -- LuaFormatter on buffer:set_sel(buffer:position_from_line(2), buffer:position_from_line(4)) textadept.editing.toggle_comment() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '', ' /*const char *foo = "bar";*/', '/*const char *baz = "quux";*/', '' }, '\n')) + -- LuaFormatter on assert_equal(buffer.selection_start, buffer:position_from_line(2) + 2) assert_equal(buffer.selection_end, buffer:position_from_line(4)) textadept.editing.toggle_comment() -- uncomment + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '', ' const char *foo = "bar";', 'const char *baz = "quux";', '' }, '\n')) + -- LuaFormatter on assert_equal(buffer.selection_start, buffer:position_from_line(2)) assert_equal(buffer.selection_end, buffer:position_from_line(4)) buffer:close(true) @@ -1915,6 +1950,7 @@ expected_failure(test_editing_select_enclosed) function test_editing_select_word() buffer.new() + -- LuaFormatter off buffer:append_text(table.concat({ 'foo', 'foobar', @@ -1923,6 +1959,7 @@ function test_editing_select_word() 'fooquux', 'foo' }, '\n')) + -- LuaFormatter on textadept.editing.select_word() assert_equal(buffer:get_sel_text(), 'foo') textadept.editing.select_word() @@ -1950,6 +1987,7 @@ end function test_editing_select_paragraph() buffer.new() + -- LuaFormatter off buffer:set_text(table.concat({ 'foo', '', @@ -1958,6 +1996,7 @@ function test_editing_select_paragraph() '', 'quux' }, '\n')) + -- LuaFormatter on buffer:goto_pos(buffer:position_from_line(3)) textadept.editing.select_paragraph() assert_equal(buffer:get_sel_text(), 'bar\nbaz\n\n') @@ -1966,31 +2005,37 @@ end function test_editing_convert_indentation() buffer.new() + -- LuaFormatter off local text = table.concat({ '\tfoo', ' bar', '\t baz', ' \tquux' }, '\n') + -- LuaFormatter on buffer:set_text(text) buffer.use_tabs, buffer.tab_width = true, 4 textadept.editing.convert_indentation() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '\tfoo', ' bar', '\t\tbaz', '\t\tquux' }, '\n')) + -- LuaFormatter on buffer:undo() assert_equal(buffer:get_text(), text) -- verify atomic undo buffer.use_tabs, buffer.tab_width = false, 2 textadept.editing.convert_indentation() + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ ' foo', ' bar', ' baz', ' quux' }, '\n')) + -- LuaFormatter on buffer:close(true) end @@ -2010,6 +2055,7 @@ function test_editing_highlight_word() local highlight = textadept.editing.highlight_words textadept.editing.highlight_words = textadept.editing.HIGHLIGHT_SELECTED buffer.new() + -- LuaFormatter off buffer:append_text(table.concat({ 'foo', 'foobar', @@ -2018,13 +2064,16 @@ function test_editing_highlight_word() 'fooquux', 'foo' }, '\n')) + -- LuaFormatter on local function verify_foo() + -- LuaFormatter off verify{ buffer:position_from_line(1), buffer:position_from_line(3) + 5, buffer:position_from_line(4) + 4, buffer:position_from_line(6) } + -- LuaFormatter on end textadept.editing.select_word() update() @@ -2165,17 +2214,20 @@ function test_editing_show_documentation() buffer:close(true) textadept.editing.api_files['text'] = nil - assert_raises(function() textadept.editing.show_documentation(true) end, 'number/nil expected, got boolean') + assert_raises(function() textadept.editing.show_documentation(true) end, + 'number/nil expected, got boolean') end function test_file_types_get_lexer() buffer.new() buffer:set_lexer('html') + -- LuaFormatter off buffer:set_text(table.concat({ '<html><head><style type="text/css">', 'h1 {}', '</style></head></html>' }, '\n')) + -- LuaFormatter on buffer:colorize(1, -1) buffer:goto_pos(buffer:position_from_line(2)) assert_equal(buffer:get_lexer(), 'html') @@ -2247,12 +2299,14 @@ function test_ui_find_find_text() local wrapped = false local handler = function() wrapped = true end buffer.new() + -- LuaFormatter off buffer:set_text(table.concat({ ' foo', 'foofoo', 'FOObar', - 'foo bar baz', + 'foo bar baz' }, '\n')) + -- LuaFormatter on ui.find.find_entry_text = 'foo' ui.find.find_next() assert_equal(buffer.selection_start, 1 + 1) @@ -2304,6 +2358,7 @@ function test_ui_find_highlight_results() local highlight_all_matches = ui.find.highlight_all_matches ui.find.highlight_all_matches = true buffer.new() + -- LuaFormatter off buffer:append_text(table.concat({ 'foo', 'foobar', @@ -2312,25 +2367,30 @@ function test_ui_find_highlight_results() 'fooquux', 'foo' }, '\n')) + -- LuaFormatter on -- Normal search. ui.find.find_entry_text = 'foo' ui.find.find_next() + -- LuaFormatter off assert_indics{ buffer:position_from_line(1), buffer:position_from_line(3) + 4, buffer:position_from_line(4) + 4, buffer:position_from_line(6) } + -- LuaFormatter on -- Regex search. ui.find.find_entry_text = 'ba.' ui.find.regex = true ui.find.find_next() + -- LuaFormatter off assert_indics{ buffer:position_from_line(2) + 3, buffer:position_from_line(3), buffer:position_from_line(4), buffer:position_from_line(4) + 8, } + -- LuaFormatter on ui.find.regex = false -- Do not highlight short searches (potential performance issue). ui.find.find_entry_text = 'f' @@ -2350,12 +2410,14 @@ end function test_ui_find_incremental() buffer.new() + -- LuaFormatter off buffer:set_text(table.concat({ ' foo', 'foobar', 'FOObaz', 'FOOquux' }, '\n')) + -- LuaFormatter on assert_equal(buffer.current_pos, 1) ui.find.incremental = true ui.find.find_entry_text = 'f' -- simulate 'f' keypress @@ -2403,12 +2465,14 @@ function test_ui_find_incremental_highlight() local highlight_all_matches = ui.find.highlight_all_matches ui.find.highlight_all_matches = true buffer.new() + -- LuaFormatter off buffer:set_text(table.concat({ ' foo', 'foobar', 'FOObaz', 'FOOquux' }, '\n')) + -- LuaFormatter on ui.find.incremental = true ui.find.find_entry_text = 'f' -- simulate 'f' keypress if CURSES then events.emit(events.FIND_TEXT_CHANGED) end -- simulate @@ -2416,12 +2480,14 @@ function test_ui_find_incremental_highlight() assert_equal(pos, 1) -- too short ui.find.find_entry_text = 'fo' -- simulate 'o' keypress if CURSES then events.emit(events.FIND_TEXT_CHANGED) end -- simulate + -- LuaFormatter off local indics = { buffer:position_from_line(1) + 1, buffer:position_from_line(2), buffer:position_from_line(3), buffer:position_from_line(4) } + -- LuaFormatter on local bit = 1 << ui.find.INDIC_FIND - 1 for _, pos in ipairs(indics) do local mask = buffer:indicator_all_on_for(pos) @@ -2602,12 +2668,14 @@ end function test_ui_find_replace_all() buffer.new() + -- LuaFormatter off local text = table.concat({ 'foo', 'foobar', 'foobaz', 'foofoo' }, '\n') + -- LuaFormatter on buffer:set_text(text) ui.find.find_entry_text, ui.find.replace_entry_text = 'foo', 'bar' ui.find.replace_all() @@ -2636,6 +2704,7 @@ function test_find_replace_regex_transforms() buffer:set_text('foObaRbaz') ui.find.find_entry_text = 'f([oO]+)ba(..)' ui.find.regex = true + -- LuaFormatter off local replacements = { ['f\\1ba\\2'] = 'foObaRbaz', ['f\\u\\1ba\\l\\2'] = 'fOObarbaz', @@ -2656,6 +2725,7 @@ function test_find_replace_regex_transforms() ['\\0'] = 'foObaRbaz', ['\\r\\n\\t'] = '\r\n\taz' } + -- LuaFormatter on for regex, replacement in pairs(replacements) do ui.find.replace_entry_text = regex ui.find.find_next() @@ -2763,8 +2833,10 @@ function test_history() buffer:close(true) assert_raises(function() textadept.history.record(1) end, 'string/nil expected, got number') - assert_raises(function() textadept.history.record('', true) end, 'number/nil expected, got boolean') - assert_raises(function() textadept.history.record('', 1, '') end, 'number/nil expected, got string') + assert_raises(function() textadept.history.record('', true) end, + 'number/nil expected, got boolean') + assert_raises(function() textadept.history.record('', 1, '') end, + 'number/nil expected, got string') end function test_history_soft_records() @@ -3050,7 +3122,8 @@ function test_run_compile_run() ui.goto_view(1) -- message buffer assert_equal(buffer._type, _L['[Message Buffer]']) assert(buffer:get_sel_text():find("'end' expected"), 'compile error not selected') - assert(buffer:marker_get(buffer:line_from_position(buffer.current_pos)) & 1 << textadept.run.MARK_ERROR - 1 > 0) + local markers = buffer:marker_get(buffer:line_from_position(buffer.current_pos)) + assert(markers & 1 << textadept.run.MARK_ERROR - 1 > 0) events.emit(events.KEYPRESS, not CURSES and 0xFF0D or 343) -- \n assert_equal(buffer.filename, compile_file) ui.goto_view(1) -- message buffer @@ -3079,7 +3152,8 @@ function test_run_compile_run() assert_equal(buffer.filename, run_file) assert_equal(buffer:line_from_position(buffer.current_pos), 1) ui.goto_view(1) - assert(buffer:marker_get(buffer:line_from_position(buffer.current_pos)) & 1 << textadept.run.MARK_WARNING - 1 > 0) + markers = buffer:marker_get(buffer:line_from_position(buffer.current_pos)) + assert(markers & 1 << textadept.run.MARK_WARNING - 1 > 0) ui.goto_view(-1) textadept.run.goto_error(false) assert_equal(buffer.filename, compile_file) @@ -3107,8 +3181,10 @@ function test_run_set_arguments() buffer:close(true) assert_raises(function() textadept.run.set_arguments(1) end, 'string/nil expected, got number') - assert_raises(function() textadept.run.set_arguments('', true) end, 'string/nil expected, got boolean') - assert_raises(function() textadept.run.set_arguments('', '', {}) end, 'string/nil expected, got table') + assert_raises(function() textadept.run.set_arguments('', true) end, + 'string/nil expected, got boolean') + assert_raises(function() textadept.run.set_arguments('', '', {}) end, + 'string/nil expected, got table') end function test_run_set_arguments_interactive() @@ -3160,7 +3236,8 @@ function test_run_test() end function test_run_goto_internal_lua_error() - xpcall(error, function(message) events.emit(events.ERROR, debug.traceback(message)) end, 'internal error', 2) + xpcall(error, function(message) events.emit(events.ERROR, debug.traceback(message)) end, + 'internal error', 2) if #_VIEWS > 1 then view:unsplit() end textadept.run.goto_error(1) assert(buffer.filename:find('/test/test%.lua$'), 'did not detect internal Lua error') @@ -3298,12 +3375,14 @@ end function test_snippets_match_indentation() local snippet = '\t foo' + -- LuaFormatter off local multiline_snippet = table.concat({ 'foo', '\tbar', '\t baz', 'quux' }, '\n') + -- LuaFormatter on buffer.new() buffer.use_tabs, buffer.tab_width, buffer.eol_mode = true, 4, buffer.EOL_CRLF @@ -3316,12 +3395,14 @@ function test_snippets_match_indentation() buffer:clear_all() buffer:add_text('\t') textadept.snippets.insert(multiline_snippet) + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ '\tfoo', '\t\tbar', '\t\t\tbaz', '\tquux' }, '\r\n')) + -- LuaFormatter on buffer:clear_all() buffer.use_tabs, buffer.tab_width, buffer.eol_mode = false, 2, buffer.EOL_LF @@ -3334,12 +3415,14 @@ function test_snippets_match_indentation() buffer:clear_all() buffer:add_text(' ') textadept.snippets.insert(multiline_snippet) + -- LuaFormatter off assert_equal(buffer:get_text(), table.concat({ ' foo', ' bar', ' baz', ' quux' }, '\n')) + -- LuaFormatter on buffer:close(true) assert_raises(function() textadept.snippets.insert(true) end, 'string/nil expected, got boolean') @@ -3351,6 +3434,7 @@ function test_snippets_placeholders() local p = io.popen('date') local shell_date = p:read() p:close() + -- LuaFormatter off textadept.snippets.insert(table.concat({ '%0placeholder: %1(foo) %2(bar)', 'choice: %3{baz,quux}', @@ -3359,6 +3443,7 @@ function test_snippets_placeholders() 'Shell: %[date] %1[echo %]', 'escape: %%1 %4%( %4%{', }, '\n')) + -- LuaFormatter off assert_equal(buffer.selections, 1) assert_equal(buffer.selection_start, 1 + 14) assert_equal(buffer.selection_end, buffer.selection_start + 3) @@ -3391,6 +3476,7 @@ function test_snippets_placeholders() textadept.snippets.insert() assert_equal(buffer.selection_start, buffer.selection_end) -- no default placeholder (escaped) textadept.snippets.insert() + -- LuaFormatter off assert_equal(buffer:get_text(), string.format(table.concat({ 'placeholder: baz bar', 'choice: quux', @@ -3399,6 +3485,7 @@ function test_snippets_placeholders() 'Shell: %s baz', 'escape: %%1 ( {' }, '\n'), lua_date, shell_date)) + -- LuaFormatter on assert_equal(buffer.selection_start, 1) assert_equal(buffer.selection_start, 1) buffer:close(true) @@ -3619,6 +3706,7 @@ end function test_lexer_api() buffer.new() buffer.use_tabs, buffer.tab_width = true, 4 + -- LuaFormatter off buffer:set_text(table.concat({ 'if foo then', '\tbar', @@ -3626,6 +3714,7 @@ function test_lexer_api() 'end', 'baz' }, '\n')) + -- LuaFormatter on buffer:set_lexer('lua') buffer:colorize(1, -1) local lexer = require('lexer') @@ -3657,7 +3746,7 @@ function test_lexer_api() assert_raises(function() lexer.property = nil end, 'read-only') assert_raises(function() lexer.property_int = nil end, 'read-only') assert_raises(function() lexer.property_int['foo'] = 1 end, 'read-only') - --TODO: assert_raises(function() lexer.property_expanded = nil end, 'read-only') + -- TODO: assert_raises(function() lexer.property_expanded = nil end, 'read-only') assert_raises(function() lexer.property_expanded['foo'] = 'bar' end, 'read-only') assert_raises(function() lexer.style_at = nil end, 'read-only') assert_raises(function() lexer.style_at[1] = 0 end, 'read-only') @@ -3677,8 +3766,8 @@ function test_ui_maximized() ui.maximized = not maximized local not_maximized = ui.maximized ui.maximized = maximized -- reset - -- For some reason, the following fails, even though the window maximized - -- status is toggled. `ui.update()` does not seem to help. + -- For some reason, the following fails, even though the window maximized status is toggled. + -- `ui.update()` does not seem to help. assert_equal(not_maximized, not maximized) end expected_failure(test_ui_maximized) @@ -3712,8 +3801,8 @@ function test_reset() _persist = persist -- store end) reset() - -- events.RESET_AFTER has already been run, but there was no opportunity to - -- connect to it in this test, so connect and simulate the event again. + -- events.RESET_AFTER has already been run, but there was no opportunity to connect to it in + -- this test, so connect and simulate the event again. events.connect(events.RESET_AFTER, function(persist) _G.foo = persist.foo end) events.emit(events.RESET_AFTER, _persist) assert_equal(_G.foo, 'bar') @@ -3795,7 +3884,8 @@ function test_set_theme() io.open_file(_HOME .. '/src/textadept.c') _VIEWS[2]:set_theme('dark') _VIEWS[3]:set_theme('light') - assert(_VIEWS[2].style_fore[view.STYLE_DEFAULT] ~= _VIEWS[3].style_fore[view.STYLE_DEFAULT], 'same default styles') + assert(_VIEWS[2].style_fore[view.STYLE_DEFAULT] ~= _VIEWS[3].style_fore[view.STYLE_DEFAULT], + 'same default styles') buffer:close(true) buffer:close(true) ui.goto_view(_VIEWS[1]) @@ -3810,7 +3900,8 @@ function test_set_lexer_style() local style = buffer:style_of_name('function') assert_equal(buffer.style_at[1], style) local default_fore = view.style_fore[view.STYLE_DEFAULT] - assert(view.style_fore[style] ~= default_fore, 'function name style_fore same as default style_fore') + assert(view.style_fore[style] ~= default_fore, + 'function name style_fore same as default style_fore') view.style_fore[style] = view.style_fore[view.STYLE_DEFAULT] assert_equal(view.style_fore[style], default_fore) local color = lexer.colors[not CURSES and 'orange' or 'blue'] @@ -3820,8 +3911,7 @@ function test_set_lexer_style() buffer:close(true) -- Defined in Lua lexer, which is not currently loaded. assert(buffer:style_of_name('library'), view.STYLE_DEFAULT) - -- Emulate a theme setting to trigger an LPeg lexer style refresh, but without - -- a token defined. + -- Emulate a theme setting to trigger an LPeg lexer style refresh, but without a token defined. view.property['style.library'] = view.property['style.library'] end @@ -3906,7 +3996,8 @@ function test_ctags() local f = io.open(dir .. '/api') local contents = f:read('a') f:close() - assert(contents:find('main int main(int argc, char **argv) {', 1, true), 'did not properly generate api') + assert(contents:find('main int main(int argc, char **argv) {', 1, true), + 'did not properly generate api') -- Test `ctags.goto_tag()`. ctags.goto_tag('main') @@ -3936,7 +4027,8 @@ function test_ctags() ctags.ctags_flags[dir] = '-R ' .. dir -- for writing absolute paths textadept.menu.menubar[_L['Search']][_L['Ctags']][_L['Generate Project Tags and API']][2]() os.execute(string.format('mv %s/tags %s/src', dir, dir)) - assert(not lfs.attributes(dir .. '/tags') and lfs.attributes(dir .. '/src/tags'), 'did not move tags file') + assert(not lfs.attributes(dir .. '/tags') and lfs.attributes(dir .. '/src/tags'), + 'did not move tags file') ctags[dir] = dir .. '/src/tags' ctags.goto_tag('main') assert_equal(buffer.filename, foo_c) @@ -4054,9 +4146,8 @@ function test_debugger_ansi_c() assert_equal(buffer:line_from_position(buffer.current_pos), 9) assert(buffer:marker_get(9) > 0, 'current line marker not set') assert_equal(buffer:marker_get(8), 0) -- current line marker cleared - -- TODO: gdb does not print program stdout to its stdout until the end when - -- using the mi interface. - --assert(msg_buf:get_text():find('^start\n'), 'process stdout not captured') + -- TODO: gdb does not print program stdout to its stdout until the end when using the mi interface. + -- assert(msg_buf:get_text():find('^start\n'), 'process stdout not captured') debugger.step_over() wait() assert_equal(buffer:line_from_position(buffer.current_pos), 10) @@ -4081,7 +4172,7 @@ function test_debugger_ansi_c() assert(buffer:call_tip_active(), 'no call tip active') debugger.step_out() wait() - --assert(msg_buf:get_text():find('\nfoo 0\n'), 'process stdout not captured') + -- assert(msg_buf:get_text():find('\nfoo 0\n'), 'process stdout not captured') assert_equal(buffer:line_from_position(buffer.current_pos), 9) debugger.set_watch('i') debugger.continue() @@ -4095,14 +4186,14 @@ function test_debugger_ansi_c() debugger.continue() wait() assert_equal(buffer:line_from_position(buffer.current_pos), 10) - --assert(msg_buf:get_text():find('\nfoo 1\n'), 'set breakpoint failed') + -- assert(msg_buf:get_text():find('\nfoo 1\n'), 'set breakpoint failed') assert(not msg_buf:get_text():find('\nfoo 2\n'), 'set breakpoint failed') events.emit(events.MARGIN_CLICK, 2, buffer.current_pos, 0) -- simulate breakpoint margin click; clear debugger.continue() wait() - --assert(msg_buf:get_text():find('\nfoo 2\n'), 'process stdout not captured') - --assert(msg_buf:get_text():find('\nfoo 3\n'), 'process stdout not captured') - --assert(msg_buf:get_text():find('\nend\n'), 'process stdout not captured') + -- assert(msg_buf:get_text():find('\nfoo 2\n'), 'process stdout not captured') + -- assert(msg_buf:get_text():find('\nfoo 3\n'), 'process stdout not captured') + -- assert(msg_buf:get_text():find('\nend\n'), 'process stdout not captured') for i = 1, buffer.line_count do assert_equal(buffer:marker_get(i), 0) end ui.goto_view(1) buffer:close(true) @@ -4167,12 +4258,12 @@ function test_debugger_lua() wait() assert_equal(buffer:line_from_position(buffer.current_pos), 2) -- TODO: set_frame is not implemented in the Lua debugger. - --debugger.set_frame(2) - --wait() - --assert_equal(buffer:line_from_position(buffer.current_pos), 7) - --debugger.set_frame(1) - --wait() - --assert_equal(buffer:line_from_position(buffer.current_pos), 2) + -- debugger.set_frame(2) + -- wait() + -- assert_equal(buffer:line_from_position(buffer.current_pos), 7) + -- debugger.set_frame(1) + -- wait() + -- assert_equal(buffer:line_from_position(buffer.current_pos), 2) buffer:search_anchor() local pos = buffer:search_next(buffer.FIND_MATCHCASE | buffer.FIND_WHOLEWORD, 'i') assert(pos > 0, "'i' not found") @@ -4263,6 +4354,7 @@ function test_file_diff() end end + -- LuaFormatter off -- Verify line markers. verify(buffer1, { [1] = diff.MARK_MODIFICATION, @@ -4313,9 +4405,9 @@ function test_file_diff() ['have'] = diff.INDIC_ADDITION, ['d'] = diff.INDIC_ADDITION }, {[17] = ' '}) + -- LuaFormatter on - -- Stop comparing, verify the buffers are restored to normal, and then start - -- comparing again. + -- Stop comparing, verify the buffers are restored to normal, and then start comparing again. textadept.menu.menubar[_L['Tools']][_L['Compare Files']][_L['Stop Comparing']][2]() verify(buffer1, {}, {}, {}) verify(buffer2, {}, {}, {}) @@ -4370,6 +4462,7 @@ function test_file_diff() assert(buffer1:get_line(1):find('^that'), 'did not merge from right to left') local function verify_first_merge() for i = 1, 7 do assert_equal(buffer1:get_line(i), buffer2:get_line(i)) end + -- LuaFormatter off verify(buffer1, { [12] = diff.MARK_MODIFICATION, [14] = diff.MARK_MODIFICATION, @@ -4387,6 +4480,7 @@ function test_file_diff() ['have'] = diff.INDIC_ADDITION, ['d'] = diff.INDIC_ADDITION }, {[17] = ' '}) + -- LuaFormatter on end verify_first_merge() -- Undo, merge left to right, and verify. @@ -4406,6 +4500,7 @@ function test_file_diff() diff.merge(true) assert(buffer1:get_line(12):find('^%('), 'did not merge from right to left') for i = 12, 13 do assert_equal(buffer1:get_line(i), buffer2:get_line(i)) end + -- LuaFormatter off verify(buffer1, { [14] = diff.MARK_MODIFICATION, [16] = diff.MARK_MODIFICATION, @@ -4421,12 +4516,14 @@ function test_file_diff() ['have'] = diff.INDIC_ADDITION, ['d'] = diff.INDIC_ADDITION }, {[17] = ' '}) + -- LuaFormatter on -- Undo, merge left to right, and verify. buffer1:undo() buffer1:goto_line(11) assert_equal(buffer1:line_from_position(buffer1.current_pos), 11) diff.merge() assert(buffer2:get_line(12):find('^be changed'), 'did not merge from left to right') + -- LuaFormatter off verify(buffer1, { [12] = diff.MARK_MODIFICATION, [14] = diff.MARK_MODIFICATION, @@ -4442,14 +4539,15 @@ function test_file_diff() ['have'] = diff.INDIC_ADDITION, ['d'] = diff.INDIC_ADDITION }, {[15] = ' '}) + -- LuaFormatter on - -- Already on next difference; merge third block from right to left, and - -- verify. + -- Already on next difference; merge third block from right to left, and verify. assert_equal(buffer1:line_from_position(buffer1.current_pos), 12) diff.merge(true) assert(buffer1:get_line(12):find('into four'), 'did not merge from right to left') assert_equal(buffer1:get_line(12), buffer2:get_line(12)) local function verify_third_merge() + -- LuaFormatter off verify(buffer1, { [14] = diff.MARK_MODIFICATION, [15] = diff.MARK_MODIFICATION, @@ -4459,6 +4557,7 @@ function test_file_diff() [14] = diff.MARK_MODIFICATION, [15] = diff.MARK_MODIFICATION }, {['have'] = diff.INDIC_ADDITION, ['d'] = diff.INDIC_ADDITION}, {[15] = ' '}) + -- LuaFormatter on end verify_third_merge() -- Undo, merge left to right, and verify. @@ -4495,9 +4594,7 @@ function test_file_diff() assert(buffer1:get_line(16):find('^\n'), 'did not merge from right to left') local function verify_fifth_merge() assert_equal(buffer1.length, buffer2.length) - for i = 1, buffer1.length do - assert_equal(buffer1:get_line(i), buffer2:get_line(i)) - end + for i = 1, buffer1.length do assert_equal(buffer1:get_line(i), buffer2:get_line(i)) end verify(buffer1, {}, {}, {}) verify(buffer2, {}, {}, {}) end @@ -4605,8 +4702,7 @@ function test_spellcheck_encodings() events.emit(events.INDICATOR_CLICK, 8) assert_equal(buffer.auto_c_current_text, 'mulțumesc') ui.update() - events.emit( - events.USER_LIST_SELECTION, SPELLING_ID, buffer.auto_c_current_text, + events.emit(events.USER_LIST_SELECTION, SPELLING_ID, buffer.auto_c_current_text, buffer.current_pos) assert_equal(buffer:get_text(), ' mulțumesc') assert_equal(buffer.current_pos, 9) @@ -4620,10 +4716,10 @@ function test_spellcheck_encodings() spellcheck.load('de_DE') spellcheck.check_spelling(true) assert_equal(buffer.auto_c_current_text, 'schön') - events.emit( - events.USER_LIST_SELECTION, SPELLING_ID, buffer.auto_c_current_text, + events.emit(events.USER_LIST_SELECTION, SPELLING_ID, buffer.auto_c_current_text, buffer.current_pos) - assert_equal(buffer:get_text():iconv(encoding, 'UTF-8'), string.iconv('schön', encoding, 'UTF-8')) + assert_equal(buffer:get_text():iconv(encoding, 'UTF-8'), + string.iconv('schön', encoding, 'UTF-8')) ui.update() spellcheck.check_spelling() assert_equal(buffer:indicator_end(spellcheck.INDIC_SPELLING, 1), 1) @@ -4657,7 +4753,9 @@ local function check_property_usage(filename, buffer_props, view_props) local line_num, count = 1, 0 for line in io.lines(filename) do for pos, id, prop in line:gmatch('()([%w_]+)[.:]([%w_]+)') do - if id == 'M' or id == 'f' or id == 'p' or id == 'lexer' or id == 'spawn_proc' then goto continue end + if id == 'M' or id == 'f' or id == 'p' or id == 'lexer' or id == 'spawn_proc' then + goto continue + end if id == 'textadept' and prop == 'MARK_BOOKMARK' then goto continue end if (id == 'ui' or id == 'split') and prop == 'size' then goto continue end if id == 'keys' and prop == 'home' then goto continue end @@ -4667,14 +4765,11 @@ local function check_property_usage(filename, buffer_props, view_props) if id == 'client' and prop == 'close' then goto continue end if (id == 'Foo' or id == 'Array' or id == 'Server') and prop == 'new' then goto continue end if buffer_props[prop] then - assert( - id == 'buffer' or id == 'buf' or id == 'buffer1' or id == 'buffer2', + assert(id == 'buffer' or id == 'buf' or id == 'buffer1' or id == 'buffer2', 'line %d:%d: "%s" should be a buffer property', line_num, pos, prop) count = count + 1 elseif view_props[prop] then - assert( - id == 'view', 'line %d:%d: "%s" should be a view property', line_num, - pos, prop) + assert(id == 'view', 'line %d:%d: "%s" should be a view property', line_num, pos, prop) count = count + 1 end ::continue:: @@ -4687,9 +4782,8 @@ end function test_buffer_view_usage() local buffer_props, view_props = load_buffer_view_props() local filter = { - '.lua', '.luadoc', '!/lexers', '!/modules/lsp/dkjson.lua', - '!/modules/lua/lua.luadoc', '!/modules/debugger/lua/mobdebug.lua', - '!/modules/yaml/lyaml.lua', '!/scripts', '!/src' + '.lua', '.luadoc', '!/lexers', '!/modules/lsp/dkjson.lua', '!/modules/lua/lua.luadoc', + '!/modules/debugger/lua/mobdebug.lua', '!/modules/yaml/lyaml.lua', '!/scripts', '!/src' } for filename in lfs.walk(_HOME, filter) do check_property_usage(filename, buffer_props, view_props) @@ -4713,13 +4807,12 @@ end -- Determines whether or not to run the test whose name is string *name*. -- If no arg patterns are provided, returns true. --- If only inclusive arg patterns are provided, returns true if *name* matches --- at least one of those patterns. --- If only exclusive arg patterns are provided ('-' prefix), returns true if --- *name* does not match any of them. --- If both inclusive and exclusive arg patterns are provided, returns true if --- *name* matches at least one of the inclusive ones, but not any of the --- exclusive ones. +-- If only inclusive arg patterns are provided, returns true if *name* matches at least one of +-- those patterns. +-- If only exclusive arg patterns are provided ('-' prefix), returns true if *name* does not +-- match any of them. +-- If both inclusive and exclusive arg patterns are provided, returns true if *name* matches +-- at least one of the inclusive ones, but not any of the exclusive ones. -- @param name Name of the test to check for inclusion. -- @return true or false local function include_test(name) @@ -4738,11 +4831,7 @@ local function include_test(name) end local tests = {} -for k in pairs(_ENV) do - if k:find('^test_') and include_test(k) then - tests[#tests + 1] = k - end -end +for k in pairs(_ENV) do if k:find('^test_') and include_test(k) then tests[#tests + 1] = k end end table.sort(tests) print('Starting test suite') @@ -4778,17 +4867,16 @@ for i = 1, #tests do tests_run = tests_run + 1 if not ok then tests_failed = tests_failed + 1 - if expected_failures[f] then - tests_failed_expected = tests_failed_expected + 1 - end + if expected_failures[f] then tests_failed_expected = tests_failed_expected + 1 end end end -print(string.format('%d tests run, %d unexpected failures, %d expected failures', tests_run, tests_failed - tests_failed_expected, tests_failed_expected)) +print(string.format('%d tests run, %d unexpected failures, %d expected failures', tests_run, + tests_failed - tests_failed_expected, tests_failed_expected)) -- Note: stock luacov crashes on hook.lua lines 51 and 58 every other run. --- `file.max` and `file.max_hits` are both `nil`, so change comparisons to be --- `(file.max or 0)` and `(file.max_hits or 0)`, respectively. +-- `file.max` and `file.max_hits` are both `nil`, so change comparisons to be `(file.max or 0)` +-- and `(file.max_hits or 0)`, respectively. if package.loaded['luacov'] then require('luacov').save_stats() os.execute('luacov') diff --git a/themes/dark.lua b/themes/dark.lua index 0cc92dd1..0177a2a6 100644 --- a/themes/dark.lua +++ b/themes/dark.lua @@ -52,17 +52,14 @@ colors.light_blue = 0xFFCC80 -- Default font. if not font then - font = WIN32 and 'Courier New' or OSX and 'Monaco' or - 'Bitstream Vera Sans Mono' + font = WIN32 and 'Courier New' or OSX and 'Monaco' or 'Bitstream Vera Sans Mono' end if not size then size = not OSX and 10 or 12 end -- Predefined styles. -styles.default = { - font = font, size = size, fore = colors.light_grey, back = colors.black -} +styles.default = {font = font, size = size, fore = colors.light_grey, back = colors.black} styles.line_number = {fore = colors.dark_grey, back = colors.black} ---styles.control_char = +-- styles.control_char = styles.indent_guide = {fore = colors.light_black} styles.call_tip = {fore = colors.light_grey, back = colors.light_black} styles.fold_display_text = {fore = colors.dark_grey} @@ -87,29 +84,29 @@ styles.variable = {fore = colors.light_blue} styles.whitespace = {} -- Multiple Selection and Virtual Space ---view.additional_sel_alpha = ---view.additional_sel_fore = ---view.additional_sel_back = ---view.additional_caret_fore = +-- view.additional_sel_alpha = +-- view.additional_sel_fore = +-- view.additional_sel_back = +-- view.additional_caret_fore = -- Caret and Selection Styles. view:set_sel_fore(true, colors.light_black) view:set_sel_back(true, colors.grey) ---view.sel_alpha = +-- view.sel_alpha = view.caret_fore = colors.grey view.caret_line_back = colors.light_black ---view.caret_line_back_alpha = +-- view.caret_line_back_alpha = -- Fold Margin. view:set_fold_margin_color(true, colors.black) view:set_fold_margin_hi_color(true, colors.black) -- Markers. ---view.marker_fore[textadept.bookmarks.MARK_BOOKMARK] = colors.black +-- view.marker_fore[textadept.bookmarks.MARK_BOOKMARK] = colors.black view.marker_back[textadept.bookmarks.MARK_BOOKMARK] = colors.dark_blue ---view.marker_fore[textadept.run.MARK_WARNING] = colors.black +-- view.marker_fore[textadept.run.MARK_WARNING] = colors.black view.marker_back[textadept.run.MARK_WARNING] = colors.yellow ---view.marker_fore[textadept.run.MARK_ERROR] = colors.black +-- view.marker_fore[textadept.run.MARK_ERROR] = colors.black view.marker_back[textadept.run.MARK_ERROR] = colors.red for i = buffer.MARKNUM_FOLDEREND, buffer.MARKNUM_FOLDEROPEN do -- fold margin view.marker_fore[i] = colors.black diff --git a/themes/light.lua b/themes/light.lua index f1ad15d0..5779903e 100644 --- a/themes/light.lua +++ b/themes/light.lua @@ -52,17 +52,14 @@ colors.light_blue = 0xFFCC80 -- Default font. if not font then - font = WIN32 and 'Courier New' or OSX and 'Monaco' or - 'Bitstream Vera Sans Mono' + font = WIN32 and 'Courier New' or OSX and 'Monaco' or 'Bitstream Vera Sans Mono' end if not size then size = not OSX and 10 or 12 end -- Predefined styles. -styles.default = { - font = font, size = size, fore = colors.light_black, back = colors.white -} +styles.default = {font = font, size = size, fore = colors.light_black, back = colors.white} styles.line_number = {fore = colors.grey, back = colors.white} ---styles.control_char = {} +-- styles.control_char = {} styles.indent_guide = {fore = colors.dark_white} styles.call_tip = {fore = colors.light_black, back = colors.dark_white} styles.fold_display_text = {fore = colors.grey} @@ -87,29 +84,29 @@ styles.variable = {fore = colors.dark_lavender} styles.whitespace = {} -- Multiple Selection and Virtual Space ---view.additional_sel_alpha = ---view.additional_sel_fore = ---view.additional_sel_back = ---view.additional_caret_fore = +-- view.additional_sel_alpha = +-- view.additional_sel_fore = +-- view.additional_sel_back = +-- view.additional_caret_fore = -- Caret and Selection Styles. view:set_sel_fore(true, colors.light_black) view:set_sel_back(true, colors.light_grey) ---view.sel_alpha = +-- view.sel_alpha = view.caret_fore = colors.grey_black view.caret_line_back = colors.dark_white ---view.caret_line_back_alpha = +-- view.caret_line_back_alpha = -- Fold Margin. view:set_fold_margin_color(true, colors.white) view:set_fold_margin_hi_color(true, colors.white) -- Markers. ---view.marker_fore[textadept.bookmarks.MARK_BOOKMARK] = colors.white +-- view.marker_fore[textadept.bookmarks.MARK_BOOKMARK] = colors.white view.marker_back[textadept.bookmarks.MARK_BOOKMARK] = colors.dark_blue ---view.marker_fore[textadept.run.MARK_WARNING] = colors.white +-- view.marker_fore[textadept.run.MARK_WARNING] = colors.white view.marker_back[textadept.run.MARK_WARNING] = colors.light_yellow ---view.marker_fore[textadept.run.MARK_ERROR] = colors.white +-- view.marker_fore[textadept.run.MARK_ERROR] = colors.white view.marker_back[textadept.run.MARK_ERROR] = colors.light_red for i = buffer.MARKNUM_FOLDEREND, buffer.MARKNUM_FOLDEROPEN do -- fold margin view.marker_fore[i] = colors.white diff --git a/themes/term.lua b/themes/term.lua index 804bcc18..705799d1 100644 --- a/themes/term.lua +++ b/themes/term.lua @@ -30,8 +30,8 @@ colors.light_white = 0xFFFFFF styles.default = {fore = colors.white, back = colors.black} styles.line_number = {fore = colors.black, bold = true} styles.brace_light = {fore = colors.yellow, bold = true} ---styles.control_char = ---styles.indent_guide = +-- styles.control_char = +-- styles.indent_guide = styles.call_tip = {fore = colors.white, back = colors.black} styles.fold_display_text = {fore = colors.black, bold = true} @@ -55,19 +55,19 @@ styles.variable = {fore = colors.blue, bold = true} styles.whitespace = {} -- Multiple Selection and Virtual Space ---view.additional_sel_fore = ---view.additional_sel_back = ---view.additional_caret_fore = +-- view.additional_sel_fore = +-- view.additional_sel_back = +-- view.additional_caret_fore = -- Caret and Selection Styles. ---view:set_sel_fore(true, colors.white) ---view:set_sel_back(true, colors.black) ---view.caret_fore = colors.black ---view.caret_line_back = +-- view:set_sel_fore(true, colors.white) +-- view:set_sel_back(true, colors.black) +-- view.caret_fore = colors.black +-- view.caret_line_back = -- Fold Margin. ---view:set_fold_margin_color(true, colors.white) ---view:set_fold_margin_hi_color(true, colors.white) +-- view:set_fold_margin_color(true, colors.white) +-- view:set_fold_margin_hi_color(true, colors.white) -- Markers. view.marker_back[textadept.bookmarks.MARK_BOOKMARK] = colors.blue |