diff options
| -rw-r--r-- | core/._M.luadoc | 49 | ||||
| -rw-r--r-- | core/keys.lua | 28 | ||||
| -rw-r--r-- | doc/07_Modules.md | 3 | ||||
| -rw-r--r-- | doc/09_Themes.md | 6 | ||||
| -rw-r--r-- | modules/textadept/snippets.lua | 57 |
5 files changed, 65 insertions, 78 deletions
diff --git a/core/._M.luadoc b/core/._M.luadoc index fada7185..89c0cb57 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -4,13 +4,13 @@ --[[ This comment is for LuaDoc. --- --- A table of loaded modules. +-- A table of loaded Lua modules used by Textadept. -- -- ## Module Guidelines -- --- At the very least, modules consist of a single directory with an *init.lua* --- script. However, the script may load additional Lua files present in the --- directory. (For an example, see *modules/textadept/init.lua*.) +-- Textadept modules are identical to Lua modules and behave in the same way. +-- Modules consist of a single directory with an *init.lua* script and any +-- necessary support files. (For an example, see *modules/textadept/init.lua*.) -- -- Loaded modules, even language modules, persist in Textadept's Lua State; -- Textadept never unloads them. Therefore, modules should define functions or @@ -19,22 +19,9 @@ -- ### Language Modules -- -- To fully take advantage of Textadept's features, language modules should have --- at a minimum: a block comment string, run and/or compile commands, an event --- handler for setting buffer properties like indentation, and if possible, an --- Adeptsense. Optional features are extra snippets and commands and a context --- menu. --- --- #### Block Comment --- --- The `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in curses) key binding toggles code --- comments. In order for this to work for your language, the --- [`_M.textadept.editing.comment_string`][] table must have a key with the --- language's lexer name assigned to a comment prefix string. For Lua, it would --- look like --- --- _M.textadept.editing.comment_string.lua = '--' --- --- [`_M.textadept.editing.comment_string`]: _M.textadept.editing.html#comment_string +-- at a minimum: run and/or compile commands, an event handler for setting +-- buffer properties like indentation, and if possible, an Adeptsense. Optional +-- features are extra snippets and commands and a context menu. -- -- #### Compile and Run -- @@ -127,17 +114,17 @@ -- For Lua this might look like -- -- M.context_menu = { --- { _L['_Undo'], buffer.undo }, --- { _L['_Redo'], buffer.redo }, --- { '' }, --- { _L['Cu_t'], buffer.cut }, --- { _L['_Copy'], buffer.copy }, --- { _L['_Paste'], buffer.paste }, --- { _L['_Delete'], buffer.clear }, --- { '' }, --- { _L['Select _All'], buffer.select_all }, --- { '' }, --- { 'Autocomplete "end"', M.try_to_autocomplete_end } +-- {_L['_Undo'], buffer.undo}, +-- {_L['_Redo'], buffer.redo}, +-- {''}, +-- {_L['Cu_t'], buffer.cut}, +-- {_L['_Copy'], buffer.copy}, +-- {_L['_Paste'], buffer.paste}, +-- {_L['_Delete'], buffer.clear}, +-- {''}, +-- {_L['Select _All'], buffer.select_all}, +-- {''}, +-- {'Autocomplete "end"', M.try_to_autocomplete_end} -- } -- -- [context menus]: _M.textadept.menu.html#set_contextmenu diff --git a/core/keys.lua b/core/keys.lua index 50ad2948..1f7a023a 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -26,18 +26,18 @@ local M = {} -- -- ## Key Sequences -- --- Key sequences are strings built from a combination of modifier keys and the --- key itself. Modifier keys are "Control", "Shift", and "Alt" on Windows, --- Linux, BSD, and in curses. On Mac OSX they are "Command" (`⌘`), "Alt/Option" --- (`⌥`), "Control" (`^`), and "Shift" (`⇧`). These modifiers have the following --- string representations: +-- Key sequences are strings built from an ordered combination of modifier keys +-- and the key itself. Modifier keys are "Control", "Shift", and "Alt" on +-- Windows, Linux, BSD, and in curses. On Mac OSX they are "Control" (`^`), +-- "Alt/Option" (`⌥`), "Command" (`⌘`), and "Shift" (`⇧`). These modifiers have +-- the following string representations: -- --- Modifier | Linux / Win32 | Mac OSX | Terminal | +-- Modifier | Linux / Win32 | Mac OSX | curses | -- ---------|---------------|---------|----------| --- Control | `'c'` | `'m'` | `'c'` | +-- Control | `'c'` | `'c'` | `'c'` | -- Alt | `'a'` | `'a'` | `'m'` | +-- Command | N/A | `'m'` | N/A | -- Shift | `'s'` | `'s'` | `'s'` | --- Command | N/A | `'c'` | N/A | -- -- The string representation of key values less than 255 is the character that -- Textadept would normally insert if the "Control", "Alt", and "Command" @@ -55,25 +55,23 @@ local M = {} -- ## Commands -- -- A command bound to a key sequence is either a Lua function or a table --- containing a Lua function with a set of arguments to pass. Examples are: +-- containing a Lua function with a set of arguments to pass. They are +-- functionally equivalent; you can use either. Examples are: -- -- keys['cn'] = buffer.new -- keys['cs'] = buffer.save -- keys['a('] = {_M.textadept.editing.enclose, '(', ')'} -- keys['cu'] = function() io.snapopen(_USERHOME) end -- --- (The function and function table syntax are functionally equivalent. You can --- use either.) --- -- Textadept handles [`buffer`][] references properly in static contexts. -- -- [`buffer`]: buffer.html -- -- ## Modes -- --- You can group together sets of key bindings into modes. When a key --- [mode](#MODE) is active, Textadept ignores all key bindings defined outside --- the mode until the mode is unset. Here is a simple vi mode example: +-- Modes are groups of key bindings such that when a key [mode](#MODE) is +-- active, Textadept ignores all key bindings defined outside the mode until the +-- mode is unset. Here is a simple vi mode example: -- -- keys.command_mode = { -- ['h'] = buffer.char_left, diff --git a/doc/07_Modules.md b/doc/07_Modules.md index 02b6bf0c..10f086ef 100644 --- a/doc/07_Modules.md +++ b/doc/07_Modules.md @@ -7,7 +7,8 @@ functionality (find & replace, key bindings, menus, snippets, etc.) See the startup. Textadept also recognizes a special kind of module: a language module. Language -modules provide functionality specific their respective programming languages. +modules provide functionality specific to their respective programming +languages. [textadept module]: api/_M.textadept.html [preferences]: 08_Preferences.html#Loading.Modules diff --git a/doc/09_Themes.md b/doc/09_Themes.md index 5777d896..70159710 100644 --- a/doc/09_Themes.md +++ b/doc/09_Themes.md @@ -12,9 +12,9 @@ terminal version uses "term".  -Each theme is a single Lua file. It contains color definitions and definitions -for how to highlight (or "style") syntactic elements like comments, strings, and -keywords in programming languages. These [definitions][] apply universally to +Each theme is a single Lua file. It contains color and style definitions for +displaying syntactic elements like comments, strings, and keywords in +programming language source files. These [definitions][] apply universally to all programming language elements, resulting in a single, unified theme. Themes also set view-related editor properties like caret and selection colors. diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua index 00e46f47..1ab6d03a 100644 --- a/modules/textadept/snippets.lua +++ b/modules/textadept/snippets.lua @@ -17,46 +17,34 @@ local M = {} -- snippets with the same trigger word, Textadept inserts the one specific to -- the current lexer, not the global one. -- --- ## Snippet Syntax +-- ## Special Sequences -- --- You may use any plain text characters except '%' in snippet text. Just like --- in Lua patterns, '%' is an escape character. The sequence "%%" stands for a --- single '%'. Also, try to use "\t" characters for indentation so Textadept can --- make the necessary conversions to respect the user's indentation preference. --- Using the '%' sequences described below, you can define placeholders, --- mirrors, and transforms for user input. +-- ### `%`*n*`(`*text*`)` -- --- ### Placeholders --- --- Textadept calls `%`_`n`_`(`_`text`_`)` sequences, where _`n`_ is an integer, --- placeholders. The editor visits placeholders in numeric order each time it --- calls [`_insert()`](#_insert) and inserts the default text _`text`_ into the --- placeholder. When there are no more placeholders left, Textadept places the --- caret at either the `%0` placeholder if it exists or at the end of the --- snippet. Examples are +-- Represents a placeholder, where *n* is an integer and *text* is default +-- placeholder text. Textadept moves the caret to placeholders in numeric order +-- each time it calls [`_insert()`](#_insert), finishing at either the "%0" +-- placeholder if it exists or at the end of the snippet. Examples are -- -- snippets['foo'] = 'foobar%1(baz)' -- snippets['bar'] = 'start\n\t%0\nend' -- --- ### Mirrors +-- ### `%`*n* -- --- Textadept calls `%`_`n`_ sequences, where _`n`_ is an integer, mirrors. --- Mirrors with the same _`n`_ as a placeholder mirror any user input in the --- placeholder. If no placeholder exists for _`n`_, the first occurrence of that --- mirror in the snippet becomes the placeholder, but with no default text. --- Examples are +-- Represents a mirrors, where *n* is an integer. Mirrors with the same *n* as a +-- placeholder mirror any user input in the placeholder. If no placeholder +-- exists for *n*, the first occurrence of that mirror in the snippet becomes +-- the placeholder, but with no default text. Examples are -- -- snippets['foo'] = '%1(mirror), %1, on the wall' -- snippets['q'] = '"%1"' -- --- ### Transforms +-- ### `%`*n*`<`*Lua code*`>`<br/>`%`*n*`[`*Shell code*`]` -- --- Textadept calls `%`_`n`_`<`_`Lua code`_`>` and `%`_`n`_`[`_`Shell code`_`]` --- sequences, where _`n`_ is an integer, transforms. _`Lua code`_ is arbitrary --- Lua code and _`Shell code`_ is arbitrary Shell code. Textadept executes the --- code when the editor visits placeholder _`n`_. If the transform omits _`n`_, --- Textadept executes the transform's code the moment the editor inserts the --- snippet. +-- Represents a transforms, where *n* is an integer, *Lua code* is arbitrary Lua +-- code, and *Shell code* is arbitrary Shell code. Textadept executes the code +-- when the editor visits placeholder *n*. If the transform omits *n*, Textadept +-- executes the transform's code the moment the editor inserts the snippet. -- -- Textadept runs Lua code in its Lua State and replaces the transform with the -- code's return text. The code may use a temporary `selected_text` global @@ -72,6 +60,19 @@ local M = {} -- -- snippets['foo'] = '$%1(HOME) = %2[echo $%1]' -- +-- ### `%%` +-- +-- Stands for a single '%' since '%' by itself has a special meaning in +-- snippets. +-- +-- ### `\t` +-- +-- A single unit of indentation based on the user's indentation settings. +-- +-- ### `\n` +-- +-- A single set of line ending delimiters based on the user's end of line mode. +-- -- [`io.popen()`]: http://www.lua.org/manual/5.2/manual.html#pdf-io.popen module('_M.textadept.snippets')]=] |