From de3a745e1af2e441de868c2aa4849102d376acb5 Mon Sep 17 00:00:00 2001 From: mitchell <70453897+orbitalquark@users.noreply.github.com> Date: Sun, 11 Apr 2021 09:34:17 -0400 Subject: Initial pass reformatting all code. Use clang-format, LuaFormatter, and 100 character limit on lines. --- docs/manual.md | 2294 ++++++++++++++++++++++++++------------------------------ 1 file changed, 1055 insertions(+), 1239 deletions(-) (limited to 'docs/manual.md') diff --git a/docs/manual.md b/docs/manual.md index 11bb53ed..aa67283c 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -14,45 +14,40 @@ 10. [Compiling](#compiling) 11. [Appendix](#appendix) --------------------------------------------------------------------------------- +--- ### Introduction --------------------------------------------------------------------------------- +--- #### Overview ![Textadept](images/textadept.png) -Textadept is a fast, minimalist, and remarkably extensible cross-platform text -editor for programmers. Written in a combination of C and [Lua][] and -relentlessly optimized for speed and minimalism over the last 12+ years, -Textadept is an ideal editor for programmers who want endless extensibility -without sacrificing speed and disk space, and without succumbing to code bloat -and a superabundance of features. The application has both a graphical user -interface (GUI) version that runs in a desktop environment, and a terminal -version that runs within a terminal emulator. +Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor for +programmers. Written in a combination of C and [Lua][] and relentlessly optimized for speed and +minimalism over the last 12+ years, Textadept is an ideal editor for programmers who want endless +extensibility without sacrificing speed and disk space, and without succumbing to code bloat and +a superabundance of features. The application has both a graphical user interface (GUI) version +that runs in a desktop environment, and a terminal version that runs within a terminal emulator. [Lua]: https://www.lua.org -Textadept is _fast_. It starts up instantly and has a very responsive user -interface. C code is about as fast as you can get, and Lua is widely regarded as -being one of the fastest scripting languages available. +Textadept is _fast_. It starts up instantly and has a very responsive user interface. C code is +about as fast as you can get, and Lua is widely regarded as being one of the fastest scripting +languages available. -Textadept is minimalist. Not only is this evident in the editor's appearance, -but its C core is limited to around 2000 lines of code and its Lua extension -code tries to avoid going beyond 4000 lines. After more than 12 years of -development, Textadept contains [roughly the same amount of code][] since its -inception while significantly improving year after year. +Textadept is minimalist. Not only is this evident in the editor's appearance, but its C core +is limited to around 2000 lines of code and its Lua extension code tries to avoid going beyond +4000 lines. After more than 12 years of development, Textadept contains [roughly the same amount +of code][] since its inception while significantly improving year after year. [roughly the same amount of code]: index.html#plots -Textadept is remarkably extensible. It was designed to be that way from the -beginning; the editor's features came later. Most of Textadept's internals are -written in Lua: syntax highlighting, opening and saving files, and search and -replace, to name a few. Textadept gives you nearly complete control over the -entire application using Lua. Capabilities like navigating within the editor, -changing menus and key bindings on the fly, handling core events, and -highlighting the syntax of new programming languages are possible. The editor's -potential is seemingly limitless. +Textadept is remarkably extensible. It was designed to be that way from the beginning; the editor's +features came later. Most of Textadept's internals are written in Lua: syntax highlighting, +opening and saving files, and search and replace, to name a few. Textadept gives you nearly +complete control over the entire application using Lua. Capabilities like navigating within the +editor, changing menus and key bindings on the fly, handling core events, and highlighting the +syntax of new programming languages are possible. The editor's potential is seemingly limitless. ![Split Views](images/splitviews.png) @@ -61,62 +56,55 @@ potential is seemingly limitless. This manual uses the following typographical conventions: * *Italic*: Used for filenames. -* `Constant width`: Used for environment variables, command line arguments, - shell code, key bindings, and Lua code, including functions, tables, and - variables. +* `Constant width`: Used for environment variables, command line arguments, shell code, key + bindings, and Lua code, including functions, tables, and variables. Key bindings use the following modifier key representations: -Modifier|Windows, Linux, BSD|macOS|Terminal| ---------|-------------------|-----|--------| -Control |`Ctrl` |`^` |`^` | -Alt |`Alt` |`⌥` |`M-` | -Command |N/A |`⌘` |N/A | -Shift |`Shift` |`⇧` |`S-` | +Modifier | Windows, Linux, BSD | macOS | Terminal +-|-|-|- +Control | `Ctrl` | `^` | `^` +Alt | `Alt` | `⌥` | `M-` +Command | N/A | `⌘` | N/A +Shift | `Shift` | `⇧` | `S-` This manual uses the following terminology: -* *buffer*: An object that contains editable text. Some other applications call - this object a document or file. -* *view*: An object that displays a single buffer. Some other applications call - this object a window. -* *caret*: The visual that represents the text insertion point. It is usually a - blinking line. +* *buffer*: An object that contains editable text. Some other applications call this object a + document or file. +* *view*: An object that displays a single buffer. Some other applications call this object + a window. +* *caret*: The visual that represents the text insertion point. It is usually a blinking line. * *module*: A package of Lua code that provides functionality for Textadept. -* *lexer*: A Lua module that highlights the syntax of source code written in a - particular programming language. Textadept refers to a programming language by - its lexer's name. +* *lexer*: A Lua module that highlights the syntax of source code written in a particular + programming language. Textadept refers to a programming language by its lexer's name. -Finally, this manual assumes you are familiar enough with the [Lua][] -programming language that you can understand the simple code samples spread -throughout the manual's contents. If you would like to quickly get up to speed, -or need a refresher, the excerpt from [Lua Quick Reference][] may be of help. +Finally, this manual assumes you are familiar enough with the [Lua][] programming language that +you can understand the simple code samples spread throughout the manual's contents. If you would +like to quickly get up to speed, or need a refresher, the excerpt from [Lua Quick Reference][] +may be of help. [Lua Quick Reference]: https://orbitalquark.github.io/lua-quick-reference #### ~/.textadept -Textadept stores all settings and user data in a local user directory that -varies, depending on the platform. This directory can also be configured using -command line arguments. On Windows systems, the default user directory is -*C:\Users\username\.textadept\\* or -*C:\Documents and Settings\username\.textadept\\*; on macOS, the default user -directory is */Users/username/.textadept/*; and on Linux and BSD, it is -*/home/username/.textadept/*. (Substitute *username* for your actual user name.) -From this point forward, the manual will use *~/.textadept/* in place of any -platform-specific user data directory. - -There is a special file, *~/.textadept/init.lua*, that Textadept will create for -you if it does not already exist. This file is what you use to configure -Textadept, specify your preferences, and customize what the application does -when it starts. For example, you can use this file to set a color theme, specify -default buffer and view settings, change the settings of existing modules, load -custom modules, configure key bindings, extend menus, enhance support for file -types and programming languages, and run arbitrary Lua code. These topics will -be covered throughout the manual. Textadept's comprehensive [Lua API][] lists, -among other things, all configurable settings for buffers, views, and modules. -You can open your *~/.textadept/init.lua* file via `Ctrl+P` on Windows, Linux, -and BSD, `⌘,` on macOS, and `M-~` in the terminal version. +Textadept stores all settings and user data in a local user directory that varies, depending +on the platform. This directory can also be configured using command line arguments. On +Windows systems, the default user directory is *C:\Users\username\.textadept\\* +or *C:\Documents and Settings\username\.textadept\\*; on macOS, the default +user directory is */Users/username/.textadept/*; and on Linux and BSD, it is +*/home/username/.textadept/*. (Substitute *username* for your actual user name.) From this point +forward, the manual will use *~/.textadept/* in place of any platform-specific user data directory. + +There is a special file, *~/.textadept/init.lua*, that Textadept will create for you if it does +not already exist. This file is what you use to configure Textadept, specify your preferences, +and customize what the application does when it starts. For example, you can use this file to set +a color theme, specify default buffer and view settings, change the settings of existing modules, +load custom modules, configure key bindings, extend menus, enhance support for file types and +programming languages, and run arbitrary Lua code. These topics will be covered throughout +the manual. Textadept's comprehensive [Lua API][] lists, among other things, all configurable +settings for buffers, views, and modules. You can open your *~/.textadept/init.lua* file via +`Ctrl+P` on Windows, Linux, and BSD, `⌘,` on macOS, and `M-~` in the terminal version. Here is a simple *~/.textadept/init.lua* for illustration: @@ -153,78 +141,72 @@ Here is a simple *~/.textadept/init.lua* for illustration: buffer.tab_width = 4 end) -**Note:** *~/.textadept/init.lua* must not call any functions that create -buffers and views (e.g. `ui.print()`, `io.open_file()`, and `buffer.new()`) at -file-level scope. Buffers and views can only be created within functions -assigned to keys, associated with menu items, or connected to events. +**Note:** *~/.textadept/init.lua* must not call any functions that create buffers and views +(e.g. `ui.print()`, `io.open_file()`, and `buffer.new()`) at file-level scope. Buffers and +views can only be created within functions assigned to keys, associated with menu items, or +connected to events. [Lua API]: api.html --------------------------------------------------------------------------------- +--- ### Getting Started --------------------------------------------------------------------------------- +--- #### Requirements -In its bid for minimalism, Textadept depends on very little to run. On Windows -and macOS, it has no external dependencies. On Linux and BSD, the GUI version -depends only on [GTK][] (a cross-platform GUI toolkit) version 2.24 or later -(circa early 2011), and the terminal version depends only on a wide-character -implementation of curses like [ncurses][](w). Most Linux and BSD systems either -already have these dependencies installed, or they are readily available from a -package manager. +In its bid for minimalism, Textadept depends on very little to run. On Windows and macOS, +it has no external dependencies. On Linux and BSD, the GUI version depends only on [GTK][] +(a cross-platform GUI toolkit) version 2.24 or later (circa early 2011), and the terminal +version depends only on a wide-character implementation of curses like [ncurses][](w). Most +Linux and BSD systems either already have these dependencies installed, or they are readily +available from a package manager. -Windows XP and Mac OSX 10.7 (Lion) are the minimum required operating systems. -Linux and BSD have no defined minimum. +Windows XP and Mac OSX 10.7 (Lion) are the minimum required operating systems. Linux and BSD +have no defined minimum. [GTK]: https://gtk.org [ncurses]: https://invisible-island.net/ncurses/ncurses.html #### Download -Textadept releases can be found [here][1]. Select the appropriate package for -your platform. A comprehensive list of changes between releases can be found -[here][2]. You can also download a separate set of modules that provide extra -features and functionality to the core application. +Textadept releases can be found [here][1]. Select the appropriate package for your platform. A +comprehensive list of changes between releases can be found [here][2]. You can also download +a separate set of modules that provide extra features and functionality to the core application. -**Windows Note:** antivirus software may flag the Windows package as containing -a virus or malware. This is a false-positive, likely due to Textadept's terminal -version executable, which is a console application. +**Windows Note:** antivirus software may flag the Windows package as containing a virus or +malware. This is a false-positive, likely due to Textadept's terminal version executable, +which is a console application. -The following table lists Textadept's approximate download and installation size -for each platform. +The following table lists Textadept's approximate download and installation size for each platform. -Platform|Download Size|Installed Size ---------|-------------|-------------- -Linux |4 MB |11 MB -macOS |11 MB |35 MB (12 MB without bundled GTK Runtime) -Windows |16 MB |41 MB (23 MB without bundled GTK Runtime) +Platform | Download Size | Installed Size +-|-|- +Linux | 4 MB | 11 MB +macOS | 11 MB | 35 MB (12 MB without bundled GTK Runtime) +Windows | 16 MB |41 MB (23 MB without bundled GTK Runtime) -**Note:** each platform package contains two executables, one for the GUI -version of Textadept, and one for the terminal version. +**Note:** each platform package contains two executables, one for the GUI version of Textadept, +and one for the terminal version. [1]: https://github.com/orbitalquark/textadept/releases [2]: changelog.html #### Installation -Installing Textadept is simple and easy. You do not need administrator -privileges. On Windows, Linux, and BSD, simply unpack the archive anywhere. On -macOS, unpack the archive and move *Textadept.app* to your user or system -*Applications/* directory like any other macOS application. The macOS archive -also contains a *ta* script for launching Textadept from the command line. You -can put this script somewhere in your `$PATH` (e.g. */usr/local/bin/*), but this -is completely optional. +Installing Textadept is simple and easy. You do not need administrator privileges. On Windows, +Linux, and BSD, simply unpack the archive anywhere. On macOS, unpack the archive and move +*Textadept.app* to your user or system *Applications/* directory like any other macOS +application. The macOS archive also contains a *ta* script for launching Textadept from the +command line. You can put this script somewhere in your `$PATH` (e.g. */usr/local/bin/*), +but this is completely optional. -If you downloaded Textadept's extra set of modules, you can unpack its contents -into Textadept's directory (thus merging the *modules/* directories) on Windows, -Linux, and BSD. On macOS, it is recommended to create a *~/.textadept/* -directory (if it does not already exist) and unpack the modules there (thus -creating or merging the *modules/* directory). +If you downloaded Textadept's extra set of modules, you can unpack its contents into Textadept's +directory (thus merging the *modules/* directories) on Windows, Linux, and BSD. On macOS, it +is recommended to create a *~/.textadept/* directory (if it does not already exist) and unpack +the modules there (thus creating or merging the *modules/* directory). -**Note:** Textadept generally does not auto-load [modules](#modules), so you -will need to load at least some of those extra modules manually. For example, in -your *~/.textadept/init.lua*: +**Note:** Textadept generally does not auto-load [modules](#modules), so you will need to load +at least some of those extra modules manually. For example, in your *~/.textadept/init.lua*: require('ctags') require('file_diff') @@ -232,11 +214,10 @@ your *~/.textadept/init.lua*: #### Updating -Textadept releases typically occur on the first day of the month every 1-2 -months. There is no auto-update process. (Textadept does not connect to the -internet; it's just a text editor.) Simply download the new version and copy its -contents into your current installation, overwriting any existing files and -directories. +Textadept releases typically occur on the first day of the month every 1-2 months. There is no +auto-update process. (Textadept does not connect to the internet; it's just a text editor.) Simply +download the new version and copy its contents into your current installation, overwriting any +existing files and directories. #### Running @@ -248,36 +229,33 @@ directories.    ![curses](images/ncurses.png) -Run Textadept on Windows by double-clicking *textadept.exe* or -*textadept-curses.exe*. On macOS, double-click *Textadept.app* or invoke the -*ta* script from the command line. On Linux and BSD, invoke *textadept* or -*textadept-curses* from a file browser, run dialog, terminal, etc. - -For convenience, you can create shortcuts to the executables on the Windows -Desktop, Start Menu, Quick Launch toolbar, etc. On macOS, you can pin the app to -your dock. On Linux and BSD, you can create a symbolic link to the executables -from somewhere in your `$PATH` (e.g. */usr/local/bin/*) or make a GNOME, KDE, -XFCE, etc. button or menu launcher. Textadept's *src/textadept.desktop* and -*src/textadept-curses.desktop* files may be of help. - -Textadept accepts a variety of command line arguments, which are listed in the -table below. - -Option |Arguments|Description --------------------|:-------:|----------- -`-e`, `--execute` | 1 |Run the given Lua code -`-f`, `--force` | 0 |Forces unique instance -`-h`, `--help` | 0 |Shows thisa -`-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 infoa +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 thisa +`-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 infoa aThe 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: : cannot open shared object - file: No such file or directory` + * `error while loading shared libraries: : cannot open shared object file: No such file + or directory` * `//libc.so.6: version 'GLIBC_' not found` -you will need to [compile](#compiling) Textadept manually for your system, which -is a very straightforward and easy process. +you will need to [compile](#compiling) Textadept manually for your system, which is a very +straightforward and easy process. --------------------------------------------------------------------------------- +--- ### User Interface --------------------------------------------------------------------------------- +--- ![UI](images/ui.png) -Textadept's user interface is sleek and simple. It consists of a menu bar, tab -bar, editor view, and statusbar. There is also a find & replace pane and a -command entry, though Textadept initially hides them both. +Textadept's user interface is sleek and simple. It consists of a menu bar, tab bar, editor +view, and statusbar. There is also a find & replace pane and a command entry, though Textadept +initially hides them both. -Textadept's titlebar shows the name and path of the current, active buffer. A -'\*' character, if present, indicates there are unsaved changes in that buffer. +Textadept's titlebar shows the name and path of the current, active buffer. A '\*' character, +if present, indicates there are unsaved changes in that buffer. #### Menu -The GUI version of Textadept has a completely customizable menu that provides -access to nearly all of the application's editing features. - -**Tip:** Textadept is largely a keyboard-driven application, so nearly every -menu item has a key binding. For at least the GUI version in the English locale -on Windows, Linux, and BSD, each menu and menu item also has a unique mnemonic -that can be used to activate it. For example, `Alt+E` accesses the "Edit" menu, -`S` opens the "Select" sub-menu, and `L` invokes the menu item that selects the -current line. - -Textadept's menu is also accessible in the form of a searchable dialog via -`Ctrl+Shift+E` on Windows, Linux, and BSD, `⌘⇧E` on macOS, and `M-S-C` in the -terminal version. (Despite the fact that the terminal version does not have a -menu, it does have this dialog.) Typing part of the name of any command in the -dialog filters the list, with spaces being wildcards. The arrow keys move the -selection up and down. Pressing `Enter`, selecting `OK`, or double-clicking on a -command invokes it. (The terminal requires pressing `Enter`.) This feature is an -alternative to navigating the menus or remembering key bindings. It can also be -used to quickly look up key bindings for particular commands. - -**Note:** for commands that have more than one key binding, only one of those -bindings is shown in the menu and dialog, and that binding is randomly chosen. - -You can extend Textadept's menu with your own menus, sub-menus, and menu items -by modifying the [`textadept.menu.menubar`][] table. Any modifications will show -up in the selection dialog mentioned previously, even in the terminal version. -For example, in your *~/.textadept/init.lua*: +The GUI version of Textadept has a completely customizable menu that provides access to nearly +all of the application's editing features. + +**Tip:** Textadept is largely a keyboard-driven application, so nearly every menu item has a key +binding. For at least the GUI version in the English locale on Windows, Linux, and BSD, each +menu and menu item also has a unique mnemonic that can be used to activate it. For example, +`Alt+E` accesses the "Edit" menu, `S` opens the "Select" sub-menu, and `L` invokes the menu +item that selects the current line. + +Textadept's menu is also accessible in the form of a searchable dialog via `Ctrl+Shift+E` on +Windows, Linux, and BSD, `⌘⇧E` on macOS, and `M-S-C` in the terminal version. (Despite the +fact that the terminal version does not have a menu, it does have this dialog.) Typing part of +the name of any command in the dialog filters the list, with spaces being wildcards. The arrow +keys move the selection up and down. Pressing `Enter`, selecting `OK`, or double-clicking on a +command invokes it. (The terminal requires pressing `Enter`.) This feature is an alternative +to navigating the menus or remembering key bindings. It can also be used to quickly look up +key bindings for particular commands. + +**Note:** for commands that have more than one key binding, only one of those bindings is shown +in the menu and dialog, and that binding is randomly chosen. + +You can extend Textadept's menu with your own menus, sub-menus, and menu items by modifying +the [`textadept.menu.menubar`][] table. Any modifications will show up in the selection dialog +mentioned previously, even in the terminal version. For example, in your *~/.textadept/init.lua*: local tools = textadept.menu.menubar[_L['Tools']] tools[#tools + 1] = {''} -- separator @@ -415,88 +380,75 @@ For example, in your *~/.textadept/init.lua*: #### Tab Bar -The GUI version of Textadept has a tab bar that displays all of Textadept's open -buffers by name, though it is only visible when two or more buffers are open. A -'\*' character, if present, indicates there are unsaved changes in the marked -buffer. There is only one tab bar for the entire application, even if there are -multiple split views. When two or more views are open, the state of the tab bar -applies only to the active view, and using the tab bar to switch between files -also applies only to that view. Right-clicking on the tab bar brings up a -configurable context menu that is defined by -[`textadept.menu.tab_context_menu`][]. You can turn off the tab bar by setting -[`ui.tabs`][]. For example, in your *~/.textadept/init.lua*: +The GUI version of Textadept has a tab bar that displays all of Textadept's open buffers by name, +though it is only visible when two or more buffers are open. A '\*' character, if present, +indicates there are unsaved changes in the marked buffer. There is only one tab bar for the +entire application, even if there are multiple split views. When two or more views are open, the +state of the tab bar applies only to the active view, and using the tab bar to switch between +files also applies only to that view. Right-clicking on the tab bar brings up a configurable +context menu that is defined by [`textadept.menu.tab_context_menu`][]. You can turn off the +tab bar by setting [`ui.tabs`][]. For example, in your *~/.textadept/init.lua*: ui.tabs = false [`textadept.menu.tab_context_menu`]: api.html#textadept.menu.tab_context_menu [`ui.tabs`]: api.html#ui.tabs -Cycle to the next buffer via `Ctrl+Tab` on Windows, Linux, and BSD, `^⇥` on -macOS, and `M-N` in the terminal version. Cycle to the previous buffer via -`Ctrl+Shift+Tab`, `^⇧⇥`, and `M-P`. +Cycle to the next buffer via `Ctrl+Tab` on Windows, Linux, and BSD, `^⇥` on macOS, and `M-N` +in the terminal version. Cycle to the previous buffer via `Ctrl+Shift+Tab`, `^⇧⇥`, and `M-P`. -**Note:** Textadept does not currently support rearranging tabs (e.g. via drag -and drop). +**Note:** Textadept does not currently support rearranging tabs (e.g. via drag and drop). -The tab bar is also accessible in the form of a searchable dialog via `Ctrl+B` -on Windows, Linux, and BSD, `⌘B` on macOS, and `M-B` or `M-S-B` in the terminal -version. (Despite the fact that the terminal version does not have a tab bar, it -does have this dialog.) The dialog displays a list of currently open buffers. -Typing part of any filename filters the list, with spaces being wildcards. The -arrow keys move the selection up and down. Pressing `Enter`, selecting `OK`, or -double-clicking on a buffer switches to it. (The terminal requires pressing -`Enter`.) This feature is particularly useful when many files are open, and -navigating through the tab bar is tedious. +The tab bar is also accessible in the form of a searchable dialog via `Ctrl+B` on Windows, +Linux, and BSD, `⌘B` on macOS, and `M-B` or `M-S-B` in the terminal version. (Despite the +fact that the terminal version does not have a tab bar, it does have this dialog.) The dialog +displays a list of currently open buffers. Typing part of any filename filters the list, +with spaces being wildcards. The arrow keys move the selection up and down. Pressing `Enter`, +selecting `OK`, or double-clicking on a buffer switches to it. (The terminal requires pressing +`Enter`.) This feature is particularly useful when many files are open, and navigating through +the tab bar is tedious. ![Buffer Browser](images/bufferbrowser.png)    ![Buffer Browser Filtered](images/bufferbrowserfiltered.png) -By default, the list shows buffers in the same order as the tab bar (the most -recently opened buffers are shown towards the bottom). You can configure the -list to show the most recently viewed buffers first by changing the key binding. -For example, in your *~/.textadept/init.lua*: +By default, the list shows buffers in the same order as the tab bar (the most recently opened +buffers are shown towards the bottom). You can configure the list to show the most recently +viewed buffers first by changing the key binding. For example, in your *~/.textadept/init.lua*: keys['ctrl+b'] = function() ui.switch_buffer(true) end #### Editor View -The editor view is where you will spend most of your time in Textadept. You can -split it vertically and horizontally as many times as you like, and you can view -the same buffer in two or more separate views. Lua also has near complete -control over all views. The [`buffer`][] and [`view`][] documentation lists -everything you can do with buffers and views directly. Right-clicking inside a -view brings up a configurable context menu that is defined by -[`textadept.menu.context_menu`][]. - -Split views can be dynamically resized by clicking and dragging on the splitter -bar that separates them. The following key bindings apply for split views: - -* Split a view horizontally into top and bottom views via `Ctrl+Alt+S` or - `Ctrl+Alt+H` on Windows, Linux, and BSD, `^S` on macOS, and `M-^V S` in the - terminal version. -* Split a view vertically into side-by-side views via `Ctrl+Alt+V` on Windows, - Linux, and BSD, `^V` on macOS, and `M-^V V` in the terminal version. -* Cycle to the next split view via `Ctrl+Alt+N` on Windows, Linux, and BSD, - `^⌥⇥` on macOS, and `M-^V N` in the terminal version. -* Cycle to the previous split view via `Ctrl+Alt+P` on Windows, Linux, and BSD, - `^⌥⇧⇥` on macOS, and `M-^V P` in the terminal version. -* Grow or shrink a view via `Ctrl+Alt++` or `Ctrl+Alt+-`, respectively, on - Windows, Linux, and BSD; `^+` or `^-`, respectively, on macOS; and `M-^V +` or - `M-^V -` in the terminal version. -* Unsplit the current view by removing its complement view(s) via `Ctrl+Alt+W` - on Windows, Linux, and BSD, `^W` on macOS, and `M-^V W` in the terminal - version. -* Unsplit the current view by removing all other views via `Ctrl+Alt+Shift+W` on - Windows, Linux, and BSD, `^⇧W` on macOS, and `M-^V S-W` in the terminal - version. - -**Note:** depending on the split sequence, the order when cycling between views -may not be linear. - -**Terminal version note:** `M-^V` is the key chain prefix for split views. Press -and release the prefix, and then type the next key in the chain by itself in -order to perform the split view action. +The editor view is where you will spend most of your time in Textadept. You can split it vertically +and horizontally as many times as you like, and you can view the same buffer in two or more +separate views. Lua also has near complete control over all views. The [`buffer`][] and [`view`][] +documentation lists everything you can do with buffers and views directly. Right-clicking inside +a view brings up a configurable context menu that is defined by [`textadept.menu.context_menu`][]. + +Split views can be dynamically resized by clicking and dragging on the splitter bar that +separates them. The following key bindings apply for split views: + +* Split a view horizontally into top and bottom views via `Ctrl+Alt+S` or `Ctrl+Alt+H` on Windows, + Linux, and BSD, `^S` on macOS, and `M-^V S` in the terminal version. +* Split a view vertically into side-by-side views via `Ctrl+Alt+V` on Windows, Linux, and BSD, + `^V` on macOS, and `M-^V V` in the terminal version. +* Cycle to the next split view via `Ctrl+Alt+N` on Windows, Linux, and BSD, `^⌥⇥` on macOS, + and `M-^V N` in the terminal version. +* Cycle to the previous split view via `Ctrl+Alt+P` on Windows, Linux, and BSD, `^⌥⇧⇥` + on macOS, and `M-^V P` in the terminal version. +* Grow or shrink a view via `Ctrl+Alt++` or `Ctrl+Alt+-`, respectively, on Windows, Linux, + and BSD; `^+` or `^-`, respectively, on macOS; and `M-^V +` or `M-^V -` in the terminal version. +* Unsplit the current view by removing its complement view(s) via `Ctrl+Alt+W` on Windows, + Linux, and BSD, `^W` on macOS, and `M-^V W` in the terminal version. +* Unsplit the current view by removing all other views via `Ctrl+Alt+Shift+W` on Windows, Linux, + and BSD, `^⇧W` on macOS, and `M-^V S-W` in the terminal version. + +**Note:** depending on the split sequence, the order when cycling between views may not be linear. + +**Terminal version note:** `M-^V` is the key chain prefix for split views. Press and release +the prefix, and then type the next key in the chain by itself in order to perform the split +view action. [`buffer`]: api.html#buffer [`view`]: api.html#view @@ -504,19 +456,16 @@ order to perform the split view action. #### Find & Replace Pane -The find & replace pane is a compact, full-featured pane that allows you to -quickly search through files and directories. The pane is available only when -you need it and quickly gets out of your way when you do not, minimizing -distractions. +The find & replace pane is a compact, full-featured pane that allows you to quickly search +through files and directories. The pane is available only when you need it and quickly gets +out of your way when you do not, minimizing distractions. -You can summon the find & replace pane via `Ctrl+F` on Windows, Linux and BSD, -`⌘F` on macOS, and `M-F` or `M-S-F` in the terminal version. It has the usual -find and replace functionality you would expect, along with "Match Case", -"Whole Word", "[Regex](#regex-and-lua-pattern-syntax)", and "In Files" options. -The pane also stores find and replace history, up to 10 entries for each. As you -search, Textadept can automatically highlight all instances of found text in the -current buffer by setting [`ui.find.highlight_all_matches`][]. For example, in -your *~/.textadept/init.lua*: +You can summon the find & replace pane via `Ctrl+F` on Windows, Linux and BSD, `⌘F` on macOS, +and `M-F` or `M-S-F` in the terminal version. It has the usual find and replace functionality you +would expect, along with "Match Case", "Whole Word", "[Regex](#regex-and-lua-pattern-syntax)", and +"In Files" options. The pane also stores find and replace history, up to 10 entries for each. As +you search, Textadept can automatically highlight all instances of found text in the current buffer +by setting [`ui.find.highlight_all_matches`][]. For example, in your *~/.textadept/init.lua*: ui.find.highlight_all_matches = true @@ -524,27 +473,26 @@ your *~/.textadept/init.lua*: While the pane is open in the GUI, the following key bindings apply: -* Perform "Find Next" and "Find Prev" in the "Find" entry via `Enter` and - `Shift+Enter`, respectively. -* Perform "Replace" and "Replace All" in the "Replace" entry via `Enter` and - `Shift+Enter`, respectively. When the "Regex" find option is enabled, - - + `\`*`n`* in the "Replace" entry represents the *n*th captured matching - region's text, and `\0` represents all matched text. - + `\U` and `\L` converts everything up to the next `\L`, `\U`, or `\E` to - uppercase and lowercase, respectively. (`\E` turns off conversion.) - + `\u` and `\l` converts the next character to uppercase and lowercase, - respectively. These may appear within `\U` and `\L` constructs. - -* For at least the English locale, toggle the find options using their button - mnemonics: `Alt+M`, `Alt+W`, `Alt+X`, `Alt+I` on Windows, Linux, and BSD, and - `⌘M`, `⌘W`, `⌘X`, and `⌘I`, respectively, on macOS. -* Cycle through find/replace history via `Up` and `Down` on Windows, Linux, BSD, - and the terminal version, and `⇡` and `⇣` on macOS. +* Perform "Find Next" and "Find Prev" in the "Find" entry via `Enter` and `Shift+Enter`, + respectively. +* Perform "Replace" and "Replace All" in the "Replace" entry via `Enter` and `Shift+Enter`, + respectively. When the "Regex" find option is enabled, + + + `\`*`n`* in the "Replace" entry represents the *n*th captured matching region's text, and + `\0` represents all matched text. + + `\U` and `\L` converts everything up to the next `\L`, `\U`, or `\E` to uppercase and + lowercase, respectively. (`\E` turns off conversion.) + + `\u` and `\l` converts the next character to uppercase and lowercase, respectively. These + may appear within `\U` and `\L` constructs. + +* For at least the English locale, toggle the find options using their button mnemonics: `Alt+M`, + `Alt+W`, `Alt+X`, `Alt+I` on Windows, Linux, and BSD, and `⌘M`, `⌘W`, `⌘X`, and `⌘I`, + respectively, on macOS. +* Cycle through find/replace history via `Up` and `Down` on Windows, Linux, BSD, and the terminal + version, and `⇡` and `⇣` on macOS. * Hide the pane via `Esc`. -While the pane is open in the terminal version, the following key bindings -apply: +While the pane is open in the terminal version, the following key bindings apply: * Switch between "Find" and "Replace" entries via `Down` and `Up`. * Toggle between "Find Next" and "Find Prev" in the "Find" entry via `Tab`. @@ -555,51 +503,44 @@ apply: * Erase the contents of the focused entry via `^U`. * Hide the pane via `Esc`. -When the pane is closed, you can quickly perform "Find Next", "Find Prev", -"Replace", and "Replace All" via `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, and -`Ctrl+Alt+Shift+R`, respectively, on Windows, Linux, and BSD; `⌘G`, `⌘⇧G`, `^R`, -and `^⇧R`, respectively, on macOS; and `M-G`, `M-S-G`, `M-R`, and `M-S-R` in the -terminal version. +When the pane is closed, you can quickly perform "Find Next", "Find Prev", "Replace", and +"Replace All" via `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, and `Ctrl+Alt+Shift+R`, respectively, +on Windows, Linux, and BSD; `⌘G`, `⌘⇧G`, `^R`, and `^⇧R`, respectively, on macOS; and +`M-G`, `M-S-G`, `M-R`, and `M-S-R` in the terminal version. -**Tip:** by default, "Replace All" replaces all text in the buffer. Selecting a -contiguous block of text and then performing "Replace All" replaces all text -in that selection only. Textadept does not currently support "Replace All" -within non-contiguous selections (e.g. multiple selections). +**Tip:** by default, "Replace All" replaces all text in the buffer. Selecting a contiguous block +of text and then performing "Replace All" replaces all text in that selection only. Textadept does +not currently support "Replace All" within non-contiguous selections (e.g. multiple selections). [`ui.find.highlight_all_matches`]: api.html#ui.find.highlight_all_matches ##### Find in Files -Textadept can search for text within multiple files and directories via -`Ctrl+Shift+F` on Windows, Linux, and BSD, and `⌘⇧F` on macOS. (The terminal -version does not have a default key binding for finding in files.) Invoking -"Find Next" prompts you for a directory to search in. The "Replace" entry has -been substituted for a "Filter" entry that contains files and directories to -include or exclude from the search. - -A filter consists of a comma-separated list of -[Lua patterns](#regex-and-lua-pattern-syntax) that match filenames and -directories to include or exclude. Patterns are inclusive by default. Exclusive -patterns begin with a '!'. If no inclusive patterns are given, any filename is -initially considered. As a convenience, file extensions can be specified -literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also -matches the Windows directory separator ('[/\\]' is not needed). The default -filter excludes many common binary files and version control directories from -searches. - -**Tip:** Textadept keeps track of filters set per-directory. You can also set -per-directory filters in Lua by modifying [`ui.find_in_files_filters`][]. For -example, in your *~/.textadept/init.lua*: +Textadept can search for text within multiple files and directories via `Ctrl+Shift+F` on +Windows, Linux, and BSD, and `⌘⇧F` on macOS. (The terminal version does not have a default +key binding for finding in files.) Invoking "Find Next" prompts you for a directory to search +in. The "Replace" entry has been substituted for a "Filter" entry that contains files and +directories to include or exclude from the search. + +A filter consists of a comma-separated list of [Lua patterns](#regex-and-lua-pattern-syntax) +that match filenames and directories to include or exclude. Patterns are inclusive by +default. Exclusive patterns begin with a '!'. If no inclusive patterns are given, any filename +is initially considered. As a convenience, file extensions can be specified literally instead +of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the Windows directory +separator ('[/\\]' is not needed). The default filter excludes many common binary files and +version control directories from searches. + +**Tip:** Textadept keeps track of filters set per-directory. You can also set per-directory filters +in Lua by modifying [`ui.find_in_files_filters`][]. For example, in your *~/.textadept/init.lua*: -- Only search in certain source directories. ui.find.find_in_files_filters['/path/to/project'] = {'/include', '/src'} -After performing a "Find in Files" search, a temporary buffer lists the search -results. You can use the arrow keys to navigate within the list and press -`Enter` to jump to a result's location in its respective file. You can also -double-click on results or jump to the next or previous result via `Ctrl+Alt+G` -or `Ctrl+Alt+Shift+G`, respectively, on Windows, Linux, and BSD; and `^⌘G` or -`^⌘⇧G`, respectively, on macOS. (The terminal version does not have default key +After performing a "Find in Files" search, a temporary buffer lists the search results. You can +use the arrow keys to navigate within the list and press `Enter` to jump to a result's location +in its respective file. You can also double-click on results or jump to the next or previous +result via `Ctrl+Alt+G` or `Ctrl+Alt+Shift+G`, respectively, on Windows, Linux, and BSD; and +`^⌘G` or `^⌘⇧G`, respectively, on macOS. (The terminal version does not have default key bindings for these actions.) ![Find in Files](images/findinfiles.png) @@ -608,20 +549,18 @@ bindings for these actions.) ##### Incremental Find -Textadept searches for text incrementally as you type when you summon the find & -replace pane via `Ctrl+Alt+F` on Windows, Linux, and BSD, `^⌘F` on macOS, and -`M-^F` in the terminal version. All of the find options apply except for -"In Files". +Textadept searches for text incrementally as you type when you summon the find & replace pane +via `Ctrl+Alt+F` on Windows, Linux, and BSD, `^⌘F` on macOS, and `M-^F` in the terminal +version. All of the find options apply except for "In Files". #### Command Entry -The versatile command entry has many different roles. Its primary role is to -execute Lua commands and interact with Textadept's internal Lua state. In -another context it filters text through shell commands. [Lua extensions][] allow -it to do even more. Like the find & replace pane, the command entry pops in and -out as you wish. Each role has its own history that can be cycled through via -the `Up` and `Down` key bindings on Windows, Linux, BSD, and the terminal -version, and `⇡` and `⇣` on macOS. +The versatile command entry has many different roles. Its primary role is to execute Lua commands +and interact with Textadept's internal Lua state. In another context it filters text through +shell commands. [Lua extensions][] allow it to do even more. Like the find & replace pane, +the command entry pops in and out as you wish. Each role has its own history that can be cycled +through via the `Up` and `Down` key bindings on Windows, Linux, BSD, and the terminal version, +and `⇡` and `⇣` on macOS. [Lua extensions]: api.html#ui.command_entry @@ -629,46 +568,41 @@ version, and `⇡` and `⇣` on macOS. ![Command Entry](images/commandentry.png) -You can open the Lua command entry via `Ctrl+E` on Windows, Linux, and BSD, -`⌘E` on macOS, and `M-C` in the terminal version. It acts very similarly to -Lua's interactive prompt. Type in the Lua command or code to run and press -`Enter` to invoke or run it. Textadept's [Lua API][] contains all of the -application's built-in commands. For convenience, the contents of the -[`buffer`][], [`view`][], [`ui`][], and [`textadept`][] tables are considered to -be global variables, the first parameter to `buffer` and `view` functions may be -omitted, and function call parentheses can also be omitted. For example, instead -of entering `buffer:append_text('foo')`, you can enter `append_text('foo')`. -Instead of `view:split()`, you can simply use `split`. These convenience -facilities are not available in normally executed Lua code, such as code in +You can open the Lua command entry via `Ctrl+E` on Windows, Linux, and BSD, `⌘E` on macOS, and +`M-C` in the terminal version. It acts very similarly to Lua's interactive prompt. Type in the Lua +command or code to run and press `Enter` to invoke or run it. Textadept's [Lua API][] contains +all of the application's built-in commands. For convenience, the contents of the [`buffer`][], +[`view`][], [`ui`][], and [`textadept`][] tables are considered to be global variables, the +first parameter to `buffer` and `view` functions may be omitted, and function call parentheses +can also be omitted. For example, instead of entering `buffer:append_text('foo')`, you can +enter `append_text('foo')`. Instead of `view:split()`, you can simply use `split`. These +convenience facilities are not available in normally executed Lua code, such as code in *~/.textadept/init.lua*. -**Warning:** if you try to cause instability of Textadept's Lua state, you will -probably succeed, so be careful. +**Warning:** if you try to cause instability of Textadept's Lua state, you will probably succeed, +so be careful. The following key bindings apply in the Lua command entry: -* Show a documentation popup for the command under or behind the caret via - `Ctrl+H` on Windows, Linux, and BSD, `^H` on macOS, and `M-H` or `M-S-H` in - the terminal version. -* Show completion candidates for Lua variables, tables, functions, and fields - via `Tab` on Windows, Linux, BSD, and the terminal version, and `⇥` on macOS. - Use the arrow keys to make a selection and press `Enter` to insert it. +* Show a documentation popup for the command under or behind the caret via `Ctrl+H` on Windows, + Linux, and BSD, `^H` on macOS, and `M-H` or `M-S-H` in the terminal version. +* Show completion candidates for Lua variables, tables, functions, and fields via `Tab` on + Windows, Linux, BSD, and the terminal version, and `⇥` on macOS. Use the arrow keys to + make a selection and press `Enter` to insert it. ![Command Completion](images/commandentrycompletion.png) -You can specify on the command line Lua commands and code to run on startup -using the `-e` and `--execute` command line argument. This is useful when you -want to run dynamic commands that do not belong in *~/.textadept/init.lua*. +You can specify on the command line Lua commands and code to run on startup using the `-e` and +`--execute` command line argument. This is useful when you want to run dynamic commands that +do not belong in *~/.textadept/init.lua*. -**Tip:** a side-effect of single-instance functionality in the GUI version of -Textadept is that you can remotely control the original instance of Textadept. -For example: +**Tip:** a side-effect of single-instance functionality in the GUI version of Textadept is that +you can remotely control the original instance of Textadept. For example: ta ~/.textadept/init.lua & ta -e "events.emit(events.FIND, 'require')" -This will search for the first instance of the word "require" in the current -file. +This will search for the first instance of the word "require" in the current file. [Lua API]: api.html [`buffer`]: api.html#buffer @@ -678,161 +612,141 @@ file. ##### Shell Command Entry and Filtering Text -You can filter text through shell commands via `Ctrl+|` on Windows, Linux, and -BSD, `⌘|` on macOS, and `^\` in the terminal version. An example would be -running the shell command `sort`, which accepts lines in a buffer as standard -input (stdin), sorts those lines, and then emits them to standard output -(stdout), which Textadept replaces the original input text with. -[`textadept.editing.filter_through()`][] describes how this feature determines -stdin. +You can filter text through shell commands via `Ctrl+|` on Windows, Linux, and BSD, `⌘|` +on macOS, and `^\` in the terminal version. An example would be running the shell command +`sort`, which accepts lines in a buffer as standard input (stdin), sorts those lines, and then +emits them to standard output (stdout), which Textadept replaces the original input text with. +[`textadept.editing.filter_through()`][] describes how this feature determines stdin. [`textadept.editing.filter_through()`]: api.html#textadept.editing.filter_through #### Statusbar -The statusbar consists of two sections. The left section displays temporary -status messages, while the right section shows buffer status information. Buffer -status information includes: +The statusbar consists of two sections. The left section displays temporary status messages, +while the right section shows buffer status information. Buffer status information includes: * The current line and column number. * The lexer language name. -* The line ending mode, or EOL mode, which is either CRLF ("\r\n") or LF ('\n'). - Line endings are the characters that separate lines. -* The indentation settings, which are a combination of an indentation character - (either a tab or a space) and an indentation size (a measure of how many space - characters are in one level of indentation). If tabs are used for indentation, - then the indentation size is the number of space characters to draw for each - tab character. -* The buffer's encoding. File and buffer encoding specifies how to interpret - text bytes for display. +* The line ending mode, or EOL mode, which is either CRLF ("\r\n") or LF ('\n'). Line endings + are the characters that separate lines. +* The indentation settings, which are a combination of an indentation character (either a tab + or a space) and an indentation size (a measure of how many space characters are in one level + of indentation). If tabs are used for indentation, then the indentation size is the number + of space characters to draw for each tab character. +* The buffer's encoding. File and buffer encoding specifies how to interpret text bytes for + display. ![Document Statusbar](images/docstatusbar.png) --------------------------------------------------------------------------------- +--- ### Working with Files and Projects --------------------------------------------------------------------------------- +--- Textadept allows you to open files using a variety of methods: -* Open, using a standard file chooser dialog, one or more files in a single - directory via `Ctrl+O` on Windows, Linux, and BSD, `⌘O` on macOS, and `^O` in - the terminal version. -* Open, using a quick open dialog, one or more files in the current project or - Textadept's current working directory via `Ctrl+Alt+Shift+P` on Windows, - Linux, and BSD, `^⌘⇧P` on macOS, and `M-^P` in the terminal version. Typing - part of any filename filters the list, with spaces being wildcards. The arrow - keys move the selection up and down. Holding down `Shift` while pressing the - arrow keys selects multiple files, as does holding down `Ctrl` while clicking. - Pressing `Enter` or selecting `OK` opens all selected files. Double-clicking +* Open, using a standard file chooser dialog, one or more files in a single directory via + `Ctrl+O` on Windows, Linux, and BSD, `⌘O` on macOS, and `^O` in the terminal version. +* Open, using a quick open dialog, one or more files in the current project or Textadept's + current working directory via `Ctrl+Alt+Shift+P` on Windows, Linux, and BSD, `^⌘⇧P` on + macOS, and `M-^P` in the terminal version. Typing part of any filename filters the list, + with spaces being wildcards. The arrow keys move the selection up and down. Holding down + `Shift` while pressing the arrow keys selects multiple files, as does holding down `Ctrl` + while clicking. Pressing `Enter` or selecting `OK` opens all selected files. Double-clicking on a single file opens it. (The terminal requires pressing `Enter`.) -* Open, using a quick open dialog, one or more files in the directory of the - currently opened file via `Ctrl+Alt+Shift+O` on Windows, Linux, and BSD, - `^⌘⇧O` on macOS, and `M-S-O` in the terminal version. -* Open a file by dragging it from a file manager and dropping it into one of - Textadept's views. -* Open a recently opened file from a list of recent files via `Ctrl+Alt+O` on - Windows, Linux, and BSD, `^⌘O` on macOS, and `M-^O` in the terminal version. -* Open, using a quick open dialog, one or more files in *~/.textadept/* via - `Ctrl+U` on Windows, Linux, and BSD, `⌘U` on macOS, and `^U` in the terminal - version. -* Reopen the currently opened file, discarding any unsaved changes, via - `Ctrl+Shift+O` on Windows, Linux, and BSD, `⌘⇧O` on macOS, and `M-O` in the - terminal version. Textadept will prompt you to reload a file if the editor - detects it has been modified externally. +* Open, using a quick open dialog, one or more files in the directory of the currently opened + file via `Ctrl+Alt+Shift+O` on Windows, Linux, and BSD, `^⌘⇧O` on macOS, and `M-S-O` + in the terminal version. +* Open a file by dragging it from a file manager and dropping it into one of Textadept's views. +* Open a recently opened file from a list of recent files via `Ctrl+Alt+O` on Windows, Linux, + and BSD, `^⌘O` on macOS, and `M-^O` in the terminal version. +* Open, using a quick open dialog, one or more files in *~/.textadept/* via `Ctrl+U` on Windows, + Linux, and BSD, `⌘U` on macOS, and `^U` in the terminal version. +* Reopen the currently opened file, discarding any unsaved changes, via `Ctrl+Shift+O` on Windows, + Linux, and BSD, `⌘⇧O` on macOS, and `M-O` in the terminal version. Textadept will prompt + you to reload a file if the editor detects it has been modified externally. ![Quick Open](images/snapopen.png) -When it comes to projects, Textadept's only concept of a project is a parent -directory under a recognized form of version control (Git, Mercurial, SVN, -Bazaar, and Fossil). There is no "Open Project" action. Textadept can work with -multiple projects at once, since the current project depends largely on context. -The current project is determined as follows: - -1. If the current buffer is a file, its parent directory is searched for a - version control directory. If none is found, that directory's parent - directory is searched next, and so on. If a version control directory is - found, its parent directory is the current project. -2. If Textadept's current working directory (cwd) contains a version control - directory, that cwd is the current project. Otherwise, the cwd's parent - directory is searched, just like in step 1. +When it comes to projects, Textadept's only concept of a project is a parent directory under +a recognized form of version control (Git, Mercurial, SVN, Bazaar, and Fossil). There is no +"Open Project" action. Textadept can work with multiple projects at once, since the current +project depends largely on context. The current project is determined as follows: + +1. If the current buffer is a file, its parent directory is searched for a version control + directory. If none is found, that directory's parent directory is searched next, and so + on. If a version control directory is found, its parent directory is the current project. +2. If Textadept's current working directory (cwd) contains a version control directory, that cwd + is the current project. Otherwise, the cwd's parent directory is searched, just like in step 1. 3. If no version control directory is found, there is no current project. -**Tip:** you can specify Textadept's current working directory by passing it on -the command line when running the application. This effectively starts Textadept -with a "default project". +**Tip:** you can specify Textadept's current working directory by passing it on the command +line when running the application. This effectively starts Textadept with a "default project". -By default, Textadept's quick open dialog displays nearly all types of files, -and only the first 1000 files it finds. You can assign a project or -directory-specific filter that indicates which files to display for that project -or directory by modifying [`io.quick_open_filters`][], and you can specify a -different maximum file list size that applies to all projects and directories by -setting [`io.quick_open_max`][]. For example, in your *~/.textadept/init.lua*: +By default, Textadept's quick open dialog displays nearly all types of files, and only the first +1000 files it finds. You can assign a project or directory-specific filter that indicates which +files to display for that project or directory by modifying [`io.quick_open_filters`][], and +you can specify a different maximum file list size that applies to all projects and directories +by setting [`io.quick_open_max`][]. For example, in your *~/.textadept/init.lua*: io.quick_open_filters['/path/to/project'] = {'/include', '/src'} io.quick_open_max = 10000 -- support huge projects -A filter consists of a comma-separated list of -[Lua patterns](#regex-and-lua-pattern-syntax) that match filenames and -directories to include or exclude. Patterns are inclusive by default. Exclusive -patterns begin with a '!'. If no inclusive patterns are given, any filename is -initially considered. As a convenience, file extensions can be specified -literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also -matches the Windows directory separator ('[/\\]' is not needed). The default -filter excludes many common binary files and version control directories from -searches. - -You can mimic a more traditional approach to projects by saving and loading -project-specific sessions via the "File > Save Session..." and -"File > Load Session..." menu items, respectively. A session can be loaded on -startup using the `-s` or `--session` command line argument. +A filter consists of a comma-separated list of [Lua patterns](#regex-and-lua-pattern-syntax) +that match filenames and directories to include or exclude. Patterns are inclusive by +default. Exclusive patterns begin with a '!'. If no inclusive patterns are given, any filename +is initially considered. As a convenience, file extensions can be specified literally instead +of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches the Windows directory +separator ('[/\\]' is not needed). The default filter excludes many common binary files and +version control directories from searches. + +You can mimic a more traditional approach to projects by saving and loading project-specific +sessions via the "File > Save Session..." and "File > Load Session..." menu items, respectively. A +session can be loaded on startup using the `-s` or `--session` command line argument. [`io.quick_open_filters`]: api.html#io.quick_open_filters [`io.quick_open_max`]: api.html#io.quick_open_max ##### Language -When Textadept opens a file, it automatically attempts to identify the -programming language associated with that file and assigns a lexer to perform -syntax highlighting of the file's contents. The identification process is as -follows: +When Textadept opens a file, it automatically attempts to identify the programming language +associated with that file and assigns a lexer to perform syntax highlighting of the file's +contents. The identification process is as follows: 1. The first line of the file is checked against any Lua patterns in - [`textadept.file_types.patterns`][]. If there is a match, the lexer - associated with that matching pattern is used. + [`textadept.file_types.patterns`][]. If there is a match, the lexer associated with that + matching pattern is used. 2. The file's extension is checked against any of the extensions in - [`textadept.file_types.extensions`][]. If there is a match, the lexer - associated with that matching extension is used. If the file does not have - an extension, the entire file name is used in the check. + [`textadept.file_types.extensions`][]. If there is a match, the lexer associated with that + matching extension is used. If the file does not have an extension, the entire file name is + used in the check. -You can associate first line patterns, file extensions, and file names with -lexers by modifying [`textadept.file_types.patterns`][] and -[`textadept.file_types.extensions`][]. For example, in your -*~/.textadept/init.lua*: +You can associate first line patterns, file extensions, and file names with lexers by modifying +[`textadept.file_types.patterns`][] and [`textadept.file_types.extensions`][]. For example, +in your *~/.textadept/init.lua*: textadept.file_types.patterns['^#!.+/zsh'] = 'bash' textadept.file_types.extensions.luadoc = 'lua' -Textadept has lexers for more than 100 different programming languages and -recognizes hundreds of file types. In the event that your programming language -is not understood, you can write a [lexer][] for it, place that lexer in your -*~/.textadept/lexers/* directory, and add an extension and/or pattern for it. +Textadept has lexers for more than 100 different programming languages and recognizes hundreds +of file types. In the event that your programming language is not understood, you can write a +[lexer][] for it, place that lexer in your *~/.textadept/lexers/* directory, and add an extension +and/or pattern for it. -For a given lexer name, Textadept attempts to find, in order, that lexer from -the following locations: +For a given lexer name, Textadept attempts to find, in order, that lexer from the following +locations: 1. Your *~/.textadept/lexers/* directory. 2. Textadept's *lexers/* directory. -**Tip:** placing lexers in your user data directory avoids the possibility of -you overwriting them when you update Textadept. These lexers also take -precedence over the ones installed with Textadept. +**Tip:** placing lexers in your user data directory avoids the possibility of you overwriting +them when you update Textadept. These lexers also take precedence over the ones installed +with Textadept. -You can manually change a buffer's lexer via `Ctrl+Shift+L` on Windows, Linux, -and BSD, `⌘⇧L` on macOS, and `M-S-L` in the terminal version. Typing part of a -lexer name in the dialog filters the list, with spaces being wildcards. The -arrow keys move the selection up and down. Pressing `Enter`, selecting `OK`, or -double-clicking on a lexer assigns it to the current buffer. (The terminal -requires pressing `Enter`.) +You can manually change a buffer's lexer via `Ctrl+Shift+L` on Windows, Linux, and BSD, `⌘⇧L` +on macOS, and `M-S-L` in the terminal version. Typing part of a lexer name in the dialog filters +the list, with spaces being wildcards. The arrow keys move the selection up and down. Pressing +`Enter`, selecting `OK`, or double-clicking on a lexer assigns it to the current buffer. (The +terminal requires pressing `Enter`.) [`textadept.file_types.patterns`]: api.html#textadept.file_types.patterns [`textadept.file_types.extensions`]: api.html#textadept.file_types.extensions @@ -840,41 +754,37 @@ requires pressing `Enter`.) ##### Encoding -Textadept has the ability to work with files encoded in one of many different -encodings, but by default it only attempts to read UTF-8, ASCII, CP1252, and -UTF-16 files, in that order. If you work with files that have other encodings, -you will need to add them to [`io.encodings`][], Textadept's known encoding -list, before attempting to open one. For example, in your -*~/.textadept/init.lua*: +Textadept has the ability to work with files encoded in one of many different encodings, but by +default it only attempts to read UTF-8, ASCII, CP1252, and UTF-16 files, in that order. If you work +with files that have other encodings, you will need to add them to [`io.encodings`][], Textadept's +known encoding list, before attempting to open one. For example, in your *~/.textadept/init.lua*: io.encodings[#io.encodings + 1] = 'UTF-32' table.insert(io.encodings, 3, 'Macintosh') -- before CP1252 You can convert a buffer's encoding using the "Buffer > Encoding" menu or -[`buffer.set_encoding()`][]. You can extend the menu to include more encodings. -For example, in your *~/.textadept/init.lua*: +[`buffer.set_encoding()`][]. You can extend the menu to include more encodings. For example, +in your *~/.textadept/init.lua*: local menu = textadept.menu.menubar[_L['Buffer']][_L['Encoding']] local encoding = 'UTF-32' menu[#menu + 1] = {encoding, function() buffer:set_encoding(encoding) end} -The default encoding for new buffers is UTF-8, due to its wide support in other -text editors and all modern operating systems. +The default encoding for new buffers is UTF-8, due to its wide support in other text editors +and all modern operating systems. [`io.encodings`]: api.html#io.encodings [`buffer.set_encoding()`]: api.html#buffer.set_encoding ##### Buffer Settings -Textadept attempts to auto-detect a file's line end mode (EOL mode), falling -back on CRLF ("\r\n") by default on Windows, and LF ('\n') on all other -platforms. You can manually change the line ending mode using the -"Buffer > EOL Mode" menu. +Textadept attempts to auto-detect a file's line end mode (EOL mode), falling back on CRLF +("\r\n") by default on Windows, and LF ('\n') on all other platforms. You can manually change +the line ending mode using the "Buffer > EOL Mode" menu. -Textadept does not attempt to auto-detect a file's indentation. The default -indentation setting is two spaces, but you can specify your preferred -indentation settings globally, and on a language-specific basis. For example, -in your *~/.textadept/init.lua*: +Textadept does not attempt to auto-detect a file's indentation. The default indentation setting +is two spaces, but you can specify your preferred indentation settings globally, and on a +language-specific basis. For example, in your *~/.textadept/init.lua*: -- Default indentation settings for all buffers. buffer.use_tabs = true @@ -893,75 +803,65 @@ in your *~/.textadept/init.lua*: You can manually change a buffer's indentation using the following process: -1. Toggle between using tabs and spaces via `Ctrl+Alt+Shift+T` on Windows, - Linux, and BSD, `^⇧T` on macOS, and `M-T` or `M-S-T` in the terminal version. +1. Toggle between using tabs and spaces via `Ctrl+Alt+Shift+T` on Windows, Linux, and BSD, + `^⇧T` on macOS, and `M-T` or `M-S-T` in the terminal version. 2. Set the indentation size via the "Buffer > Indentation" menu. -3. Optionally convert existing indentation to the new indentation settings via - `Ctrl+Alt+I` on Windows, Linux, and BSD, `^I` on macOS, and `M-I` in the - terminal version. +3. Optionally convert existing indentation to the new indentation settings via `Ctrl+Alt+I` + on Windows, Linux, and BSD, `^I` on macOS, and `M-I` in the terminal version. ##### View Settings -Textadept normally does not wrap long lines into view, nor does it show -whitespace characters. You can toggle line wrapping for the current buffer via -`Ctrl+Alt+\` on Windows, Linux, and BSD, and `^\` on macOS. You can toggle -whitespace visibility for the current buffer via `Ctrl+Alt+Shift+S` on Windows, -Linux, and BSD, and `^⇧S` on macOS. Visible spaces are represented by dots, and -visible tabs are represented by arrows. (The terminal version does not have -default key bindings for either of these actions.) - -The GUI version of Textadept can show small guiding lines based on indentation -level, and does so by default. You can toggle the visibility of these guides for -the current view via `Ctrl+Alt+Shift+I` on Windows, Linux, and BSD, and `^⇧I` on -macOS. - -The GUI version of Textadept also allows you to temporarily increase or decrease -the font size in the current view. The following key bindings apply for this -feature: - -* Increase the view's font size via `Ctrl+=` on Windows, Linux, and BSD, and - `⌘=` on macOS. -* Decrease the view's font size via `Ctrl+-` on Windows, Linux, and BSD, and - `⌘-` on macOS. -* Reset the view's font size to its normal value via `Ctrl+0` on Windows, Linux, - and BSD, and `⌘0` on macOS. - --------------------------------------------------------------------------------- +Textadept normally does not wrap long lines into view, nor does it show whitespace characters. You +can toggle line wrapping for the current buffer via `Ctrl+Alt+\` on Windows, Linux, and BSD, and +`^\` on macOS. You can toggle whitespace visibility for the current buffer via `Ctrl+Alt+Shift+S` +on Windows, Linux, and BSD, and `^⇧S` on macOS. Visible spaces are represented by dots, +and visible tabs are represented by arrows. (The terminal version does not have default key +bindings for either of these actions.) + +The GUI version of Textadept can show small guiding lines based on indentation level, and +does so by default. You can toggle the visibility of these guides for the current view via +`Ctrl+Alt+Shift+I` on Windows, Linux, and BSD, and `^⇧I` on macOS. + +The GUI version of Textadept also allows you to temporarily increase or decrease the font size +in the current view. The following key bindings apply for this feature: + +* Increase the view's font size via `Ctrl+=` on Windows, Linux, and BSD, and `⌘=` on macOS. +* Decrease the view's font size via `Ctrl+-` on Windows, Linux, and BSD, and `⌘-` on macOS. +* Reset the view's font size to its normal value via `Ctrl+0` on Windows, Linux, and BSD, and + `⌘0` on macOS. + +--- ### Adept Editing --------------------------------------------------------------------------------- +--- -Textadept implements most of the customary key bindings for navigating text -fields on each platform, including Bash-style bindings on macOS and in the -terminal version. The editor also implements most of the usual basic editing -key bindings (e.g. undo, redo, cut, copy, paste, etc.). All of Textadept's -navigation-related key bindings are listed in the "Movement" section of the -[key bindings list][]. Textadept's basic editing key bindings are listed in the -"Edit" section of that list. (They are also shown in the "Edit" menu.) +Textadept implements most of the customary key bindings for navigating text fields on each +platform, including Bash-style bindings on macOS and in the terminal version. The editor also +implements most of the usual basic editing key bindings (e.g. undo, redo, cut, copy, paste, +etc.). All of Textadept's navigation-related key bindings are listed in the "Movement" section +of the [key bindings list][]. Textadept's basic editing key bindings are listed in the "Edit" +section of that list. (They are also shown in the "Edit" menu.) [key bindings list]: api.html#textadept.keys #### Brace Matching, Auto-pair, and Typeover -Textadept automatically highlights matching brace characters when the caret is -over one of them: '(', ')', '[', ']', '{', or '}'. You can jump to the current -character's complement via `Ctrl+M` on Windows, Linux, and BSD, `^M` on macOS, -and `M-M` in the terminal version. You can add highlighting for '<' and '>' by -modifying [`textadept.editing.brace_matches`][]. For example, in your -*~/.textadept/init.lua*: +Textadept automatically highlights matching brace characters when the caret is over one of them: +'(', ')', '[', ']', '{', or '}'. You can jump to the current character's complement via `Ctrl+M` +on Windows, Linux, and BSD, `^M` on macOS, and `M-M` in the terminal version. You can add +highlighting for '<' and '>' by modifying [`textadept.editing.brace_matches`][]. For example, +in your *~/.textadept/init.lua*: textadept.editing.brace_matches[string.byte('<')] = true textadept.editing.brace_matches[string.byte('>')] = true ![Matching Braces](images/matchingbrace.png) -Since braces often go together in pairs, Textadept automatically inserts the -complement of opening brace characters you type, deletes that complement if you -press `Backspace`, and moves over the complement if you type it (as opposed to -inserting it again). Textadept also exhibits this behavior for single and double -quote characters (''' and '"'). You can configure or disable this -behavior by modifying [`textadept.editing.auto_pairs`][] and -[`textadept.editing.typeover_chars`][]. For example, in your -*~/.textadept/init.lua*: +Since braces often go together in pairs, Textadept automatically inserts the complement of +opening brace characters you type, deletes that complement if you press `Backspace`, and +moves over the complement if you type it (as opposed to inserting it again). Textadept also +exhibits this behavior for single and double quote characters (''' and '"'). You +can configure or disable this behavior by modifying [`textadept.editing.auto_pairs`][] and +[`textadept.editing.typeover_chars`][]. For example, in your *~/.textadept/init.lua*: -- Auto-pair and typeover '<' and '>'. textadept.editing.auto_pairs[string.byte('<')] = '>' @@ -977,18 +877,17 @@ behavior by modifying [`textadept.editing.auto_pairs`][] and #### Word Highlight -Textadept can be configured to automatically highlight all occurrences of the -word under the caret, or all occurrences of the selected word (e.g. a variable -name), by setting [`textadept.editing.highlight_words`][]. For example, in your -*~/.textadept/init.lua*: +Textadept can be configured to automatically highlight all occurrences of the word under +the caret, or all occurrences of the selected word (e.g. a variable name), by setting +[`textadept.editing.highlight_words`][]. For example, in your *~/.textadept/init.lua*: -- Highlight all occurrences of the current word. textadept.editing.highlight_words = textadept.editing.HIGHLIGHT_CURRENT -- Highlight all occurrences of the selected word. textadept.editing.highlight_words = textadept.editing.HIGHLIGHT_SELECTED -Pressing `Esc` clears highlighting. By default, Textadept does not perform any -automatic highlighting. +Pressing `Esc` clears highlighting. By default, Textadept does not perform any automatic +highlighting. ![Word Highlight](images/wordhighlight.png) @@ -996,42 +895,38 @@ automatic highlighting. #### Autocompletion and Documentation -Textadept provides buffer-based word completion. It can also autocomplete -symbols for programming languages and display documentation for functions and -other symbols. - -You can show word completion candidates for partially-typed words via -`Ctrl+Enter` on Windows, Linux, and BSD, `^Esc` on macOS, and `M-Enter` in the -terminal version. Continuing to type changes the suggested completion. Use the -arrow keys to navigate within the list and press `Enter` to insert the rest of -the selected word. By default, the list of completions comes from the current -buffer. You can configure Textadept to look in all open buffers by setting -[`textadept.editing.autocomplete_all_words`][]. For example, in -*~/.textadept/init.lua*: +Textadept provides buffer-based word completion. It can also autocomplete symbols for programming +languages and display documentation for functions and other symbols. + +You can show word completion candidates for partially-typed words via `Ctrl+Enter` on Windows, +Linux, and BSD, `^Esc` on macOS, and `M-Enter` in the terminal version. Continuing to type +changes the suggested completion. Use the arrow keys to navigate within the list and press +`Enter` to insert the rest of the selected word. By default, the list of completions comes +from the current buffer. You can configure Textadept to look in all open buffers by setting +[`textadept.editing.autocomplete_all_words`][]. For example, in *~/.textadept/init.lua*: textadept.editing.autocomplete_all_words = true ![Word Completion](images/wordcompletion.png) -For languages that support it, you can show symbol completion candidates at the -current position via `Ctrl+Space` on Windows, Linux, and BSD, `⌥Esc` on macOS, -and `^Space` in the terminal version. +For languages that support it, you can show symbol completion candidates at the current position +via `Ctrl+Space` on Windows, Linux, and BSD, `⌥Esc` on macOS, and `^Space` in the terminal +version. ![Autocomplete Lua](images/adeptsense_lua.png)      ![Autocomplete Lua String](images/adeptsense_string.png) -Also for languages that support it, you can show any known documentation for the -current symbol via `Ctrl+H` on Windows, Linux, and BSD, `^H` on macOS, and `M-H` -or `M-S-H` in the terminal version. Textadept has built-in autocompletion and -documentation support for Lua and C, including for its own Lua API. +Also for languages that support it, you can show any known documentation for the current symbol +via `Ctrl+H` on Windows, Linux, and BSD, `^H` on macOS, and `M-H` or `M-S-H` in the terminal +version. Textadept has built-in autocompletion and documentation support for Lua and C, including +for its own Lua API. ![Documentation](images/adeptsense_doc.png) -Textadept's framework for providing symbol autocompletion and documentation -relies on [autocompleter][] functions and [API files][], which are often -supplied by [language][] [modules](#modules). You can use this framework to -write your own autocompletion routines. +Textadept's framework for providing symbol autocompletion and documentation relies on +[autocompleter][] functions and [API files][], which are often supplied by [language][] +[modules](#modules). You can use this framework to write your own autocompletion routines. [`textadept.editing.autocomplete_all_words`]: api.html#textadept.editing.autocomplete_all_words [autocompleter]: api.html#textadept.editing.autocompleters @@ -1040,69 +935,58 @@ write your own autocompletion routines. #### Text Selections -Textadept has three kinds of text selections: contiguous, multiple, and -rectangular. +Textadept has three kinds of text selections: contiguous, multiple, and rectangular. You can create contiguous selections as follows: -* Make an arbitrary selection anchored at the caret by pressing the arrow keys, - home/end, page up/down, etc. while holding down the `Shift` key, or by simply - clicking and dragging the mouse. -* The terminal version can also make an arbitrary selection by entering - selection mode via `^^` and using normal movement keys. This feature is - available since some terminals do not recognize `Shift` with movement keys. - While in selection mode, swap the start and end positions via `^]` in order to - alter the selection from its opposite side. Exit selection mode by typing - text, deleting text, performing an action that changes text, or by - pressing `^^` again. -* Select the current word via `Ctrl+Shift+D` on Windows, Linux, and BSD, `⌘⇧D` - on macOS, and `M-S-W` in the terminal version. Repeated use of this action - selects subsequent occurrences of that word as additional (multiple) - selections. -* Select the current line via `Ctrl+Shift+N` on Windows, Linux, and BSD, `⌘⇧N` - on macOS, and `M-S-N` in the terminal version. +* Make an arbitrary selection anchored at the caret by pressing the arrow keys, home/end, page + up/down, etc. while holding down the `Shift` key, or by simply clicking and dragging the mouse. +* The terminal version can also make an arbitrary selection by entering selection mode via `^^` + and using normal movement keys. This feature is available since some terminals do not recognize + `Shift` with movement keys. While in selection mode, swap the start and end positions via + `^]` in order to alter the selection from its opposite side. Exit selection mode by typing + text, deleting text, performing an action that changes text, or by pressing `^^` again. +* Select the current word via `Ctrl+Shift+D` on Windows, Linux, and BSD, `⌘⇧D` on macOS, and + `M-S-W` in the terminal version. Repeated use of this action selects subsequent occurrences + of that word as additional (multiple) selections. +* Select the current line via `Ctrl+Shift+N` on Windows, Linux, and BSD, `⌘⇧N` on macOS, + and `M-S-N` in the terminal version. * Double click to select a word, and triple-click to select a line. * Click and optionally drag within the line number margin to select whole lines. -* Select the current paragraph via `Ctrl+Shift+P` on Windows, Linux, and BSD, - `⌘⇧P` on macOS, and `M-S-P` in the terminal version. Paragraphs are surrounded - by one or more blank lines. -* Select all buffer text via `Ctrl+A` on Windows, Linux, and BSD, `⌘A` on macOS, - and `M-A` in the terminal version. -* Select text between matching delimiters (parentheses, brackets, braces, single - quotes, double-quotes, and back quotes) via `Ctrl+Shift+M` on Windows, Linux, - and BSD, `^⇧M` on macOS, and `M-S-M` in the terminal version. Repeated use of - this action toggles the selection of the delimiters themselves. -* Select between HTML/XML tags via `Ctrl+<` on Windows, Linux, and BSD, `⌘<` on - macOS, and `M-<` in the terminal version. -* Select an HTML/XML tag via `Ctrl+>` on Windows, Linux, and BSD, and `⌘>` on - macOS. +* Select the current paragraph via `Ctrl+Shift+P` on Windows, Linux, and BSD, `⌘⇧P` on macOS, + and `M-S-P` in the terminal version. Paragraphs are surrounded by one or more blank lines. +* Select all buffer text via `Ctrl+A` on Windows, Linux, and BSD, `⌘A` on macOS, and `M-A` + in the terminal version. +* Select text between matching delimiters (parentheses, brackets, braces, single quotes, + double-quotes, and back quotes) via `Ctrl+Shift+M` on Windows, Linux, and BSD, `^⇧M` on + macOS, and `M-S-M` in the terminal version. Repeated use of this action toggles the selection + of the delimiters themselves. +* Select between HTML/XML tags via `Ctrl+<` on Windows, Linux, and BSD, `⌘<` on macOS, and + `M-<` in the terminal version. +* Select an HTML/XML tag via `Ctrl+>` on Windows, Linux, and BSD, and `⌘>` on macOS. You can create multiple selections as follows: -* Add another selection by holding down `Ctrl`, clicking, and optionally - dragging the mouse over a range of text. -* Select as an additional selection the next occurrence of the current word via - `Ctrl+Shift+D` on Windows, Linux, and BSD, `⌘⇧D` on macOS, and `M-S-W` in the - terminal version. +* Add another selection by holding down `Ctrl`, clicking, and optionally dragging the mouse + over a range of text. +* Select as an additional selection the next occurrence of the current word via `Ctrl+Shift+D` + on Windows, Linux, and BSD, `⌘⇧D` on macOS, and `M-S-W` in the terminal version. Textadept mirrors any typed text at each selection. You can create a rectangular selection as follows: -* Press the arrow keys, home/end, or page up/down, while holding down - `Alt+Shift` on Windows, Linux, and BSD, `⌥⇧` on macOS, and `M-S-` in the - terminal version. -* Click and drag the mouse while holding down the `Alt` key on Windows, Linux, - and BSD, and `⌥` on macOS. -* Click and drag the mouse without holding down any modifiers (thus making a - normal, multi-line selection), press and hold down the `Alt` key on Windows, - Linux, and BSD, `⌥` on macOS, and `M-` in the terminal version, and then - continue dragging the mouse. This feature is available because some window - managers in Linux consume `Alt+Shift` + arrow keys and `Alt` + mouse drag. - -You are permitted to create a zero-width rectangular selection that spans -multiple lines, and for this kind of selection, Textadept mirrors any typed text -on all of those lines. +* Press the arrow keys, home/end, or page up/down, while holding down `Alt+Shift` on Windows, + Linux, and BSD, `⌥⇧` on macOS, and `M-S-` in the terminal version. +* Click and drag the mouse while holding down the `Alt` key on Windows, Linux, and BSD, and + `⌥` on macOS. +* Click and drag the mouse without holding down any modifiers (thus making a normal, multi-line + selection), press and hold down the `Alt` key on Windows, Linux, and BSD, `⌥` on macOS, and + `M-` in the terminal version, and then continue dragging the mouse. This feature is available + because some window managers in Linux consume `Alt+Shift` + arrow keys and `Alt` + mouse drag. + +You are permitted to create a zero-width rectangular selection that spans multiple lines, +and for this kind of selection, Textadept mirrors any typed text on all of those lines. ![Rectangular Selection](images/rectangularselection.png)      @@ -1110,31 +994,29 @@ on all of those lines. #### Text Transformations -Textadept can apply many different transformations to the current word, line, -and selected text. - -* Enclose the current word or selected text within delimiters like parentheses, - braces, brackets, single quotes, double quotes, or HTML/XML tags using the key - bindings listed in the "Edit > Selection" submenu. -* Convert the selected text to upper or lower case via `Ctrl+Alt+U` or - `Ctrl+Alt+Shift+U`, respectively, on Windows, Linux, and BSD; `^U` or `^⇧U`, - respectively, on macOS; and `M-^U` or `M-^L` in the terminal version. -* Increase or decrease the indentation of the selected lines via `Tab` or - `Shift+Tab`, respectively, on Windows, Linux, and BSD; `⇥` or `⇧⇥`, - respectively on macOS; and `Tab` or `S-Tab` in the terminal version. You do - not have to select whole lines; selecting any part of a line is sufficient. -* Move the current or selected line(s) up or down via `Ctrl+Shift+Up` or - `Ctrl+Shift+Down`, respectively, on Windows, Linux, and BSD; `^⇧⇡` or `^⇧⇣`, - respectively, on macOS; and `S-^Up` or `S-^Down` in the terminal version. You - do not have to select whole lines; selecting any part of a line is sufficient. -* Comment out code on the current or selected line(s) via `Ctrl+/` on Windows, - Linux, and BSD, `⌘/` on macOS, and `M-/` in the terminal version. You do not - have to select whole lines; selecting any part of a line is sufficient. - -You can auto-enclose selected text between any typed punctuation character -(taking into account [`textadept.editing.auto_pairs`][]) by setting -[`textadept.editing.auto_enclose`][]. For example, in your -*~/.textadept/init.lua*: +Textadept can apply many different transformations to the current word, line, and selected text. + +* Enclose the current word or selected text within delimiters like parentheses, braces, brackets, + single quotes, double quotes, or HTML/XML tags using the key bindings listed in the "Edit > + Selection" submenu. +* Convert the selected text to upper or lower case via `Ctrl+Alt+U` or `Ctrl+Alt+Shift+U`, + respectively, on Windows, Linux, and BSD; `^U` or `^⇧U`, respectively, on macOS; and `M-^U` + or `M-^L` in the terminal version. +* Increase or decrease the indentation of the selected lines via `Tab` or `Shift+Tab`, + respectively, on Windows, Linux, and BSD; `⇥` or `⇧⇥`, respectively on macOS; and `Tab` + or `S-Tab` in the terminal version. You do not have to select whole lines; selecting any part + of a line is sufficient. +* Move the current or selected line(s) up or down via `Ctrl+Shift+Up` or `Ctrl+Shift+Down`, + respectively, on Windows, Linux, and BSD; `^⇧⇡` or `^⇧⇣`, respectively, on macOS; + and `S-^Up` or `S-^Down` in the terminal version. You do not have to select whole lines; + selecting any part of a line is sufficient. +* Comment out code on the current or selected line(s) via `Ctrl+/` on Windows, Linux, and BSD, + `⌘/` on macOS, and `M-/` in the terminal version. You do not have to select whole lines; + selecting any part of a line is sufficient. + +You can auto-enclose selected text between any typed punctuation character (taking into account +[`textadept.editing.auto_pairs`][]) by setting [`textadept.editing.auto_enclose`][]. For example, +in your *~/.textadept/init.lua*: textadept.editing.auto_enclose = true @@ -1143,92 +1025,86 @@ You can auto-enclose selected text between any typed punctuation character #### Navigate Through History -Textadept records buffer positions within views over time and allows for -navigating through that history. Navigate backward or forward via `Alt+,` or -`Alt+.`, respectively, on Windows, Linux, and BSD; `^,` or `^.`, respectively, -on macOS; and `M-,` or `M-.`, respectively, in the terminal version. +Textadept records buffer positions within views over time and allows for navigating through +that history. Navigate backward or forward via `Alt+,` or `Alt+.`, respectively, on Windows, +Linux, and BSD; `^,` or `^.`, respectively, on macOS; and `M-,` or `M-.`, respectively, in the +terminal version. #### Goto Line -You can jump to a specific line in the current buffer via `Ctrl+J` on Windows, -Linux, and BSD, `⌘J` on macOS, and `^J` in the terminal version. Enter the line -number to jump to in the prompt, and press `Enter` or click `OK`. +You can jump to a specific line in the current buffer via `Ctrl+J` on Windows, Linux, and BSD, +`⌘J` on macOS, and `^J` in the terminal version. Enter the line number to jump to in the +prompt, and press `Enter` or click `OK`. #### Bookmarks -Bookmarks are markers attached to lines of interest. They move in sync with the -lines they were added to as buffer text is inserted and deleted. Bookmarks show -up in the left-hand margin after line numbers. Textadept allows you to bookmark -lines and jump back to them later. The following key bindings apply for -bookmarks: +Bookmarks are markers attached to lines of interest. They move in sync with the lines they were +added to as buffer text is inserted and deleted. Bookmarks show up in the left-hand margin +after line numbers. Textadept allows you to bookmark lines and jump back to them later. The +following key bindings apply for bookmarks: -* Toggle a bookmark on the current line via `Ctrl+F2` on Windows, Linux, and - BSD, `⌘F2` on macOS, and `F1` in the terminal version. +* Toggle a bookmark on the current line via `Ctrl+F2` on Windows, Linux, and BSD, `⌘F2` + on macOS, and `F1` in the terminal version. * Jump to the next bookmarked line via `F2`. -* Jump to the previously bookmarked line via `Shift+F2` on Windows, Linux, and - BSD, `⇧F2` on macOS, and `F3` in the terminal version. -* Jump to the bookmarked line selected from a list via `Alt+F2` on Windows, - Linux, and BSD, `⌥F2` on macOS, and `F4` in the terminal version. -* Clear all bookmarks in the current buffer via `Ctrl+Shift+F2` on Windows, - Linux, and BSD, `⌘⇧F2` on macOS, and `F6` in the terminal version. +* Jump to the previously bookmarked line via `Shift+F2` on Windows, Linux, and BSD, `⇧F2` + on macOS, and `F3` in the terminal version. +* Jump to the bookmarked line selected from a list via `Alt+F2` on Windows, Linux, and BSD, + `⌥F2` on macOS, and `F4` in the terminal version. +* Clear all bookmarks in the current buffer via `Ctrl+Shift+F2` on Windows, Linux, and BSD, + `⌘⇧F2` on macOS, and `F6` in the terminal version. #### Macros -Macros allow you to quickly record a series of edits and play them back without -having to write a custom Lua script. The following key bindings apply for -macros: +Macros allow you to quickly record a series of edits and play them back without having to write +a custom Lua script. The following key bindings apply for macros: * Start recording a macro via `F9`. -* Stop recording a macro via `Shift+F9` on Windows, Linux, and BSD, `⇧F9` on - macOS, and `F10` in the terminal version. -* Play back the most recently recorded macro via `Alt+F9` on Windows, Linux, and - BSD, `⌥F9` on macOS, and `F12` in the terminal version. +* Stop recording a macro via `Shift+F9` on Windows, Linux, and BSD, `⇧F9` on macOS, and `F10` + in the terminal version. +* Play back the most recently recorded macro via `Alt+F9` on Windows, Linux, and BSD, `⌥F9` + on macOS, and `F12` in the terminal version. -You can use the "Tools > Macros" menu to save the most recently recorded macro -to a file, and to load one for playback on demand. +You can use the "Tools > Macros" menu to save the most recently recorded macro to a file, +and to load one for playback on demand. #### Snippets -Snippets are dynamic text templates that can be inserted into the buffer on -demand. They are composed of any combination of plain text, placeholders for -interactive input, mirrors and transforms for interactive input, and arbitrary -Lua and Shell code. Snippets eliminate the need for typing repetitive code -constructs like class definitions, getters and setters, control structures, API -calls, and more. +Snippets are dynamic text templates that can be inserted into the buffer on demand. They +are composed of any combination of plain text, placeholders for interactive input, mirrors +and transforms for interactive input, and arbitrary Lua and Shell code. Snippets eliminate +the need for typing repetitive code constructs like class definitions, getters and setters, +control structures, API calls, and more. ![Snippet](images/snippet.png)      ![Snippet Expanded](images/snippet2.png) A snippet has a trigger word associated with snippet text in the [`snippets`][] -table. Language-specific snippets are in a subtable assigned to their language's -lexer name, and are often supplied by [language][] [modules](#modules). Snippets -may also be the contents of files in a snippet directory, with file names being -the trigger word. The [snippets documentation][] describes snippets and their -contents in more detail. +table. Language-specific snippets are in a subtable assigned to their language's lexer name, and +are often supplied by [language][] [modules](#modules). Snippets may also be the contents of files +in a snippet directory, with file names being the trigger word. The [snippets documentation][] +describes snippets and their contents in more detail. The following key bindings apply for snippets: -* Insert a snippet from a list of available snippets via `Ctrl+Shift+K` on - Windows, Linux, and BSD, `⌥⇧⇥` on macOS, and `M-S-K` in the terminal version. - Typing part of a snippet trigger in the dialog filters the list, with spaces - being wildcards. The arrow keys move the selection up and down. Pressing - `Enter`, selecting `OK`, or double-clicking on a snippet inserts it into the - current buffer. (The terminal requires pressing `Enter`.) -* Show completion candidates for a partially-typed snippet trigger word via - `Ctrl+K` on Windows, Linux, and BSD, `⌥⇥` on macOS, and `M-K` in the terminal - version. Continuing to type changes the suggested completion. Use the arrow - keys to navigate within the list and press `Enter` to insert the rest of the - trigger word. -* Insert a snippet based on the trigger word behind the caret via `Tab` on - Windows, Linux, BSD, and in the terminal version, and `⇥` on macOS. You can - insert another snippet within an active snippet. A previously active snippet - will pick up where it left off after a nested snippet finishes. -* Navigate to the next placeholder in the current snippet via `Tab` on Windows, - Linux, BSD, and in the terminal version, and `⇥` on macOS. -* Navigate to the previous placeholder in the current snippet via `Shift+Tab` on - Windows, Linux, and BSD, `⇧⇥` on macOS, and `S-Tab` in the terminal version. - If there is no previous placeholder, the current snippet is canceled. +* Insert a snippet from a list of available snippets via `Ctrl+Shift+K` on Windows, Linux, and + BSD, `⌥⇧⇥` on macOS, and `M-S-K` in the terminal version. Typing part of a snippet + trigger in the dialog filters the list, with spaces being wildcards. The arrow keys move + the selection up and down. Pressing `Enter`, selecting `OK`, or double-clicking on a snippet + inserts it into the current buffer. (The terminal requires pressing `Enter`.) +* Show completion candidates for a partially-typed snippet trigger word via `Ctrl+K` on Windows, + Linux, and BSD, `⌥⇥` on macOS, and `M-K` in the terminal version. Continuing to type + changes the suggested completion. Use the arrow keys to navigate within the list and press + `Enter` to insert the rest of the trigger word. +* Insert a snippet based on the trigger word behind the caret via `Tab` on Windows, Linux, + BSD, and in the terminal version, and `⇥` on macOS. You can insert another snippet within + an active snippet. A previously active snippet will pick up where it left off after a nested + snippet finishes. +* Navigate to the next placeholder in the current snippet via `Tab` on Windows, Linux, BSD, + and in the terminal version, and `⇥` on macOS. +* Navigate to the previous placeholder in the current snippet via `Shift+Tab` on Windows, Linux, + and BSD, `⇧⇥` on macOS, and `S-Tab` in the terminal version. If there is no previous + placeholder, the current snippet is canceled. * Cancel the current snippet via `Esc`. [`snippets`]: api.html#_G.snippets @@ -1237,93 +1113,83 @@ The following key bindings apply for snippets: #### Code Folding -Textadept can temporarily hide blocks of code in supported languages. Markers in -the margin to the left of code denote fold points. Clicking on those markers -toggles folding. You can toggle folding for the current block via `Ctrl+*` on -Windows, Linux, and BSD, `⌘*` on macOS, and `M-*` in the terminal version. +Textadept can temporarily hide blocks of code in supported languages. Markers in the margin to +the left of code denote fold points. Clicking on those markers toggles folding. You can toggle +folding for the current block via `Ctrl+*` on Windows, Linux, and BSD, `⌘*` on macOS, and +`M-*` in the terminal version. ![Folding](images/folding.png) #### Virtual Space -Textadept normally constrains the caret to remain within text lines. Enabling -virtual space allows you to move the caret into the space beyond the ends of -lines. Toggle virtual space via `Ctrl+Alt+Shift+V` on Windows, Linux, and BSD, -and `^⇧V` in macOS. (The terminal version does not have a default key binding -for toggling virtual space.) +Textadept normally constrains the caret to remain within text lines. Enabling virtual space +allows you to move the caret into the space beyond the ends of lines. Toggle virtual space via +`Ctrl+Alt+Shift+V` on Windows, Linux, and BSD, and `^⇧V` in macOS. (The terminal version does +not have a default key binding for toggling virtual space.) #### Key Bindings -Key bindings are simply commands (Lua functions) assigned to key sequences in -the [`keys`][] table. Key sequences are composed of an ordered combination of -modifier keys followed by either the key's inserted character or, if no such -character exists, the string representation of the key according to -[`keys.KEYSYMS`][]. Language-specific keys are in a subtable assigned to their -language's lexer name, and are often supplied by [language][] -[modules](#modules). Key sequences can also be assigned tables of key bindings -to create key chains (e.g. Emacs `C-x` prefix). Key bindings can be grouped into -modes such that while a mode is active, Textadept ignores all key bindings -outside that mode until the mode is unset (e.g. Vim-style modal editing). The -[keys documentation][] describes all of this in more detail. +Key bindings are simply commands (Lua functions) assigned to key sequences in the [`keys`][] +table. Key sequences are composed of an ordered combination of modifier keys followed by either +the key's inserted character or, if no such character exists, the string representation of +the key according to [`keys.KEYSYMS`][]. Language-specific keys are in a subtable assigned to +their language's lexer name, and are often supplied by [language][] [modules](#modules). Key +sequences can also be assigned tables of key bindings to create key chains (e.g. Emacs `C-x` +prefix). Key bindings can be grouped into modes such that while a mode is active, Textadept +ignores all key bindings outside that mode until the mode is unset (e.g. Vim-style modal +editing). The [keys documentation][] describes all of this in more detail. [`keys`]: api.html#keys [`keys.KEYSYMS`]: api.html#keys.KEYSYMS [language]: api.html#_M [keys documentation]: api.html#keys --------------------------------------------------------------------------------- +--- ### Compile, Run, Build, and Test --------------------------------------------------------------------------------- - -Textadept knows most of the commands that compile and/or run code in source -files. It also knows some of the commands that build projects, and you can tell -the editor how to run your project's test suite. Textadept recognizes many of -the warning and error messages emitted by those commands and marks them as they -occur in compile/run/build/test output. Double-clicking on a line with a warning -or error jumps to its source. - -The following key bindings apply for compiling and running source files, and -for building projects and running tests: - -* Compile the current file via `Ctrl+Shift+R` on Windows, Linux, and BSD, `⌘⇧R` - on macOS, and `M-^R` in the terminal version. -* Run the current file via `Ctrl+R` on Windows, Linux, and BSD, `⌘R` on macOS, - and `^R` in the terminal version. -* Set, using an interactive dialog, the command line arguments for the current - file's compile and run commands via `Ctrl+Shift+A` on Windows, Linux, and BSD, - and `⌘⇧A` on macOS. (The terminal version does not have a default key binding - for setting command line arguments.) Enter the command line arguments for each - command and press `Enter` or click `OK`. -* Build the current project via `Ctrl+Shift+B` on Windows, Linux, and BSD, `⌘⇧B` - on macOS, and `M-^B` in the terminal version. -* Run tests for the current project via `Ctrl+Shift+T` on Windows, Linux, and - BSD, `⌘⇧T` on macOS, and `M-^T` in the terminal version. -* Stop the currently running compile, run, build, or test process via - `Ctrl+Shift+X` on Windows, Linux, and BSD, `⌘⇧X` on macOS, and `M-^X` in the - terminal version. -* Jump to the source of the next recognized warning or error via `Ctrl+Alt+E` on - Windows, Linux, and BSD, `^⌘E` on macOS, and `M-X` in the terminal version. -* Jump to the source of the previously recognized warning or error via - `Ctrl+Alt+Shift+E` on Windows, Linux, and BSD, `^⌘⇧E` on macOS, and `M-S-X` in - the terminal version. -* Jump to the source of the recognized warning or error on the current line via - `Enter`. +--- + +Textadept knows most of the commands that compile and/or run code in source files. It also +knows some of the commands that build projects, and you can tell the editor how to run your +project's test suite. Textadept recognizes many of the warning and error messages emitted by +those commands and marks them as they occur in compile/run/build/test output. Double-clicking +on a line with a warning or error jumps to its source. + +The following key bindings apply for compiling and running source files, and for building +projects and running tests: + +* Compile the current file via `Ctrl+Shift+R` on Windows, Linux, and BSD, `⌘⇧R` on macOS, + and `M-^R` in the terminal version. +* Run the current file via `Ctrl+R` on Windows, Linux, and BSD, `⌘R` on macOS, and `^R` + in the terminal version. +* Set, using an interactive dialog, the command line arguments for the current file's compile + and run commands via `Ctrl+Shift+A` on Windows, Linux, and BSD, and `⌘⇧A` on macOS. (The + terminal version does not have a default key binding for setting command line arguments.) Enter + the command line arguments for each command and press `Enter` or click `OK`. +* Build the current project via `Ctrl+Shift+B` on Windows, Linux, and BSD, `⌘⇧B` on macOS, + and `M-^B` in the terminal version. +* Run tests for the current project via `Ctrl+Shift+T` on Windows, Linux, and BSD, `⌘⇧T` + on macOS, and `M-^T` in the terminal version. +* Stop the currently running compile, run, build, or test process via `Ctrl+Shift+X` on Windows, + Linux, and BSD, `⌘⇧X` on macOS, and `M-^X` in the terminal version. +* Jump to the source of the next recognized warning or error via `Ctrl+Alt+E` on Windows, Linux, + and BSD, `^⌘E` on macOS, and `M-X` in the terminal version. +* Jump to the source of the previously recognized warning or error via `Ctrl+Alt+Shift+E` + on Windows, Linux, and BSD, `^⌘⇧E` on macOS, and `M-S-X` in the terminal version. +* Jump to the source of the recognized warning or error on the current line via `Enter`. ![Runtime Error](images/runerror.png) -When you execute a compile, run, build, or test command, that command's output -is printed to a temporary buffer in real-time. You can configure Textadept to -print output in the background by setting [`textadept.run.run_in_background`][]. -For example, in your *~/.textadept/init.lua*: +When you execute a compile, run, build, or test command, that command's output is printed to +a temporary buffer in real-time. You can configure Textadept to print output in the background +by setting [`textadept.run.run_in_background`][]. For example, in your *~/.textadept/init.lua*: textadept.run.run_in_background = true -You can change or add compile, run, build, and test commands by modifying the -[`textadept.run.compile_commands`][], [`textadept.run.run_commands`][], -[`textadept.run.build_commands`][], and [`textadept.run.test_commands`][] -tables, respectively. You can add Lua patterns that recognize warning and error -output by modifying the [`textadept.run.error_patterns`][] table. For example, -in your *~/.textadept/init.lua*: +You can change or add compile, run, build, and test commands by modifying +the [`textadept.run.compile_commands`][], [`textadept.run.run_commands`][], +[`textadept.run.build_commands`][], and [`textadept.run.test_commands`][] tables, +respectively. You can add Lua patterns that recognize warning and error output by modifying the +[`textadept.run.error_patterns`][] table. For example, in your *~/.textadept/init.lua*: textadept.run.compile_commands.foo = 'foo "%f"' textadept.run.run_commands.foo = './"%e"' @@ -1332,9 +1198,8 @@ in your *~/.textadept/init.lua*: textadept.run.build_commands['/path/to/project'] = 'make -C src -j4' textadept.run.test_commands['/path/to/project'] = 'lua tests.lua' -**Tip:** you can set compile and run commands on a per-filename basis, and these -commands can contain arguments so that you do not have to invoke -"Tools > Set Arguments..." +**Tip:** you can set compile and run commands on a per-filename basis, and these commands can +contain arguments so that you do not have to invoke "Tools > Set Arguments..." [`textadept.run.run_in_background`]: api.html#textadept.run.run_in_background [`textadept.run.compile_commands`]: api.html#textadept.run.compile_commands @@ -1343,23 +1208,22 @@ commands can contain arguments so that you do not have to invoke [`textadept.run.test_commands`]: api.html#textadept.run.test_commands [`textadept.run.error_patterns`]: api.html#textadept.run.error_patterns --------------------------------------------------------------------------------- +--- ### Modules --------------------------------------------------------------------------------- +--- -Modules are packages of Lua code that provide functionality for Textadept. Most -of the editor's features come from individual modules (see Textadept's *core/* -and *modules/* directories). Textadept can load modules when the application -starts up, or it can load modules on-demand in response to events. Once a module -is loaded, it persists in memory and is never unloaded. Textadept attempts to -load, in order, a given module from the following locations: +Modules are packages of Lua code that provide functionality for Textadept. Most of the +editor's features come from individual modules (see Textadept's *core/* and *modules/* +directories). Textadept can load modules when the application starts up, or it can load modules +on-demand in response to events. Once a module is loaded, it persists in memory and is never +unloaded. Textadept attempts to load, in order, a given module from the following locations: 1. Your *~/.textadept/modules/* directory. 2. Textadept's *modules/* directory. -**Tip:** placing modules in your user data directory avoids the possibility of -you overwriting them when you update Textadept. These modules also take -precedence over the ones installed with Textadept. +**Tip:** placing modules in your user data directory avoids the possibility of you overwriting +them when you update Textadept. These modules also take precedence over the ones installed +with Textadept. Textadept will only load modules it is explicitly told to load (e.g. from your *~/.textadept/init.lua*). For example, in your *~/.textadept/init.lua*: @@ -1371,39 +1235,34 @@ Textadept will only load modules it is explicitly told to load (e.g. from your if name == 'lua' then require('lua.extras') end end) -The only exception to this auto-loading prohibition is modules that have the -same name as a lexer language. These so-called "[language modules][]" will be -automatically loaded when an appropriate source file is opened, or when the -module's associated lexer is loaded for a buffer. +The only exception to this auto-loading prohibition is modules that have the same name as a +lexer language. These so-called "[language modules][]" will be automatically loaded when an +appropriate source file is opened, or when the module's associated lexer is loaded for a buffer. **Note:** lexer language names are typically the names of lexer files in your *~/.textadept/lexers/* directory and Textadept's *lexers/* directory. #### Developing Modules -Modules follow the Lua package model: a module is either a single Lua file or -a group of Lua files in a directory that contains an *init.lua* file (which is -the module's entry point). The name of the module is its file name or directory -name, respectively. Here are some basic guidelines for developing modules and -some things to keep in mind: - -* Modules should return a table of functions and fields that are defined - locally, rather than globally. (This is standard Lua practice.) That way, the - construct `local foo = require('foo')` behaves as expected. -* Modules should not define global variables, as all modules share the same Lua - state. +Modules follow the Lua package model: a module is either a single Lua file or a group of Lua files +in a directory that contains an *init.lua* file (which is the module's entry point). The name +of the module is its file name or directory name, respectively. Here are some basic guidelines +for developing modules and some things to keep in mind: + +* Modules should return a table of functions and fields that are defined locally, rather than + globally. (This is standard Lua practice.) That way, the construct `local foo = require('foo')` + behaves as expected. +* Modules should not define global variables, as all modules share the same Lua state. * Only [language modules][] should be named after lexer languages. -* Modules must not call any functions that create buffers and views (e.g. - `ui.print()`, `io.open_file()`, and `buffer.new()`) at file-level scope. - Buffers and views can only be created within functions assigned to keys, - associated with menu items, or connected to events. -* Additional documentation on creating language modules can be found in the - the [language modules][] documentation. - -**Tip:** you do not need to have a language module in order to have -language-specific editing features. You can simply put language-specific -features inside an [`events.LEXER_LOADED`][] event handler. For example, in your -*~/.textadept/init.lua*: +* Modules must not call any functions that create buffers and views (e.g. `ui.print()`, + `io.open_file()`, and `buffer.new()`) at file-level scope. Buffers and views can only be + created within functions assigned to keys, associated with menu items, or connected to events. +* Additional documentation on creating language modules can be found in the the [language + modules][] documentation. + +**Tip:** you do not need to have a language module in order to have language-specific editing +features. You can simply put language-specific features inside an [`events.LEXER_LOADED`][] +event handler. For example, in your *~/.textadept/init.lua*: -- Auto-pair and brace-match '<' and '>' only in HTML and XML files. events.connect(events.LEXER_LOADED, function(name) @@ -1416,13 +1275,13 @@ features inside an [`events.LEXER_LOADED`][] event handler. For example, in your [language modules]: api.html#_M [`events.LEXER_LOADED`]: api.html#events.LEXER_LOADED --------------------------------------------------------------------------------- +--- ### Themes --------------------------------------------------------------------------------- +--- -Themes customize Textadept's look and feel. The editor comes with three built-in -themes: "light", "dark", and "term". The default theme for the GUI and terminal -versions is "light" and "term", respectively. +Themes customize Textadept's look and feel. The editor comes with three built-in themes: +"light", "dark", and "term". The default theme for the GUI and terminal versions is "light" +and "term", respectively. @@ -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 `//libstdc++.so.6: version 'GLIBCXX_' 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 +`//libstdc++.so.6: version 'GLIBCXX_' 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 -`//libc.so.6: version 'GLIBC_' not found`, then you will have to -compile Textadept manually without Docker. +If you still get an error, this time like `//libc.so.6: version 'GLIBC_' 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 texta -\\*x* |%*x* |Non-alphanumeric character *x*, ignoring special meaning - -aIn 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 texta +\\*x* | %*x* | Non-alphanumeric character *x*, ignoring special meaning + +aIn 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()][]a -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/Ab -**textadept.find** | | -find\_incremental() |Replaced|[incremental][]c -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_d +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()][]a +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/Ab +**textadept.find**|| +find\_incremental() | Replaced | [incremental][]c +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_d aReturns prefix and function, instead of just function.
bUse `for name in buffer:private_lexer_call(_SCINTILLA.functions.property_names[1]):gmatch('[^\n]+') do ... end`.
cUse `textadept.menu.menubar[_L['Search']][_L['Find Incremental']][2]`.
-dMost buffer functions and fields are available in views now. See -section below. +dMost 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.*`: 
 (\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
@@ -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.
-- 
cgit v1.2.3