diff options
Diffstat (limited to 'modules')
| -rw-r--r-- | modules/cpp/init.lua | 10 | ||||
| -rw-r--r-- | modules/lua/init.lua | 18 | ||||
| -rw-r--r-- | modules/textadept/adeptsense.lua | 153 | ||||
| -rw-r--r-- | modules/textadept/bookmarks.lua | 15 | ||||
| -rw-r--r-- | modules/textadept/command_entry.lua | 6 | ||||
| -rw-r--r-- | modules/textadept/editing.lua | 122 | ||||
| -rw-r--r-- | modules/textadept/filter_through.lua | 5 | ||||
| -rw-r--r-- | modules/textadept/find.lua | 31 | ||||
| -rw-r--r-- | modules/textadept/keys.lua | 12 | ||||
| -rw-r--r-- | modules/textadept/menu.lua | 45 | ||||
| -rw-r--r-- | modules/textadept/mime_types.lua | 17 | ||||
| -rw-r--r-- | modules/textadept/run.lua | 59 | ||||
| -rw-r--r-- | modules/textadept/session.lua | 26 | ||||
| -rw-r--r-- | modules/textadept/snapopen.lua | 4 | ||||
| -rw-r--r-- | modules/textadept/snippets.lua | 21 |
15 files changed, 282 insertions, 262 deletions
diff --git a/modules/cpp/init.lua b/modules/cpp/init.lua index e1c6dc67..45b6cf5d 100644 --- a/modules/cpp/init.lua +++ b/modules/cpp/init.lua @@ -12,11 +12,9 @@ local M = {} -- + `Ctrl+L, M` (`⌘L, M` on Mac OSX | `M-L, M` in ncurses) -- Open this module for editing. -- + `.` --- When to the right of a known symbol, show an autocompletion list of fields --- and functions. +-- Show an autocompletion list of members for the symbol behind the caret. -- + `->` --- When to the right of a known symbol, show an autocompletion list of fields --- and functions. +-- Show an autocompletion list of members for the symbol behind the caret. -- + `Shift+Enter` (`⇧↩` | `S-Enter`) -- Add ';' to the end of the current line and insert a newline. -- @field sense @@ -74,7 +72,7 @@ end -- Commands. --- --- Container for C/C++-specific key bindings. +-- Table of C/C++-specific key bindings. -- @class table -- @name _G.keys.cpp keys.cpp = { @@ -92,7 +90,7 @@ keys.cpp = { -- Snippets. --- --- Container for C/C++-specific snippets. +-- Table of C/C++-specific snippets. -- @class table -- @name _G.snippets.cpp if type(snippets) == 'table' then diff --git a/modules/lua/init.lua b/modules/lua/init.lua index 5ea32fd2..b9a2ed80 100644 --- a/modules/lua/init.lua +++ b/modules/lua/init.lua @@ -11,15 +11,13 @@ local M = {} -- -- + `Ctrl+L, M` (`⌘L, M` on Mac OSX | `M-L, M` in ncurses) -- Open this module for editing. --- + `Shift+Enter` (`⇧↩` | `S-Enter`) --- Try to autocomplete an `if`, `while`, `for`, etc. control structures with --- `end`. -- + `.` --- When to the right of a known symbol, show an autocompletion list of fields --- and functions. +-- Show an autocompletion list of fields for the symbol behind the caret. -- + `:` --- When to the right of a known symbol, show an autocompletion list of --- functions only. +-- Show an autocompletion list of functions for the symbol behind the caret. +-- + `Shift+Enter` (`⇧↩` | `S-Enter`) +-- Autocomplete an `if`, `while`, `for`, etc. control structure with the `end` +-- keyword. -- @field sense -- The Lua [Adeptsense](_M.textadept.adeptsense.html). -- It loads user tags from *`_USERHOME`/modules/lua/tags* and user apidocs @@ -96,7 +94,7 @@ end -- Commands. --- --- Patterns for auto `end` completion for control structures. +-- List of patterns for auto-`end` completion for control structures. -- @class table -- @name control_structure_patterns -- @see try_to_autocomplete_end @@ -106,8 +104,8 @@ local control_structure_patterns = { } --- --- Tries to autocomplete Lua's `end` keyword for control structures like `if`, --- `while`, `for`, etc. +-- Tries to autocomplete control structures like `if`, `while`, `for`, etc. with +-- the `end` keyword. -- @see control_structure_patterns -- @name try_to_autocomplete_end function M.try_to_autocomplete_end() diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua index 6f19163e..5f42fcdc 100644 --- a/modules/textadept/adeptsense.lua +++ b/modules/textadept/adeptsense.lua @@ -194,7 +194,7 @@ local M = {} -- -- ### Summary -- --- The above method of setting syntax options, ctags kinds, and trigger +-- The above method of setting syntax options, Ctags kinds, and trigger -- characters for an Adeptsense is sufficient for most static and some dynamic -- languages. The rest of this document is devoted to more complex techniques. -- @@ -367,7 +367,7 @@ local M = {} -- @field always_show_globals (bool) -- Include globals in the list of completions offered. -- Globals are classes, functions, and fields that do not belong to another --- class. They are contained in `completions['']`. +-- class. They are contained in `sense.completions['']`. -- The default value is `true`. -- @field FUNCTIONS (string) -- XPM image for Adeptsense functions. @@ -393,7 +393,8 @@ M.FIELD = 'fields' --- -- Returns a full symbol (if any) and current symbol part (if any) behind the -- caret. --- For example: `buffer.cur` would return `'buffer'` and `'cur'`. +-- For example: `buffer.cur` would return `'buffer'` and `'cur'`. Returns empty +-- strings instead of `nil`. -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @return symbol or `''` -- @return part or `''` @@ -408,11 +409,11 @@ function M.get_symbol(sense) end --- --- Returns the class name for a given symbol. --- If the symbol is `sense.syntax.self` and a class definition using the --- `sense.syntax.class_definition` keyword is found, that class is returned. --- Otherwise the buffer is searched backwards for a type declaration of the --- symbol according to the patterns in `sense.syntax.type_declarations`. +-- Returns the class name for *symbol* name. +-- If *symbol* is `sense.syntax.self` and inside a class definition matching +-- `sense.syntax.class_definition`, that class is returned. Otherwise the +-- buffer is searched backwards for a type declaration of *symbol* according to +-- the patterns in `sense.syntax.type_declarations`. -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @param symbol The symbol to get the class of. -- @return class or `nil` @@ -504,13 +505,14 @@ local function add_inherited(sense, class, only_fields, only_funcs, c, added) end --- --- Returns a list of completions for the given symbol. +-- Returns a list of function (unless *only_fields* is `true`) and field (unless +-- *only_funcs* is `true`) completions for *symbol* name. -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @param symbol The symbol to get completions for. --- @param only_fields If `true`, returns list of only fields. The default value --- is `false`. --- @param only_functions If `true`, returns list of only functions. The default --- value is `false`. +-- @param only_fields Optional flag indicating whether or not to return a list +-- of only fields. The default value is `false`. +-- @param only_functions Optional flag indicating whether or not to return a +-- list of only functions. The default value is `false`. -- @return completion_list or `nil` -- @name get_completions function M.get_completions(sense, symbol, only_fields, only_functions) @@ -560,13 +562,15 @@ function M.get_completions(sense, symbol, only_fields, only_functions) end --- --- Shows an autocompletion list for the symbol behind the caret. +-- Shows an autocompletion list of functions (unless *only_fields* is `true`) +-- and fields (unless *only_funcs* is `true`) for the symbol behind the caret, +-- returning `true` on success. -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses -- the current language's Adeptsense (if it exists). --- @param only_fields If `true`, returns list of only fields. The default value --- is `false`. --- @param only_functions If `true`, returns list of only functions. The default --- value is `false`. +-- @param only_fields Optional flag indicating whether or not to return a list +-- of only fields. The default value is `false`. +-- @param only_functions Optional flag indicating whether or not to return a +-- list of only functions. The default value is `false`. -- @return `true` on success or `false`. -- @see get_symbol -- @see get_completions @@ -592,14 +596,16 @@ function M.complete(sense, only_fields, only_functions) end --- --- Sets the trigger for autocompletion. +-- Sets the trigger character(s) *c* for autocompletion. +-- If *only_fields* is `true`, the trigger only completes fields. If +-- *only_functions* is `true`, the trigger only completes functions. -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @param c The character(s) that triggers the autocompletion. You can have up -- to two characters. --- @param only_fields If `true`, this trigger only completes fields. The default --- value is `false`. --- @param only_functions If `true`, this trigger only completes functions. --- The default value is `false`. +-- @param only_fields Optional flag indicating whether or not this trigger only +-- completes fields. The default value is `false`. +-- @param only_functions Optional flag indicating whether or not this trigger +-- only completes functions. The default value is `false`. -- @usage sense:add_trigger('.') -- @usage sense:add_trigger(':', false, true) -- only functions -- @usage sense:add_trigger('->') @@ -617,9 +623,8 @@ function M.add_trigger(sense, c, only_fields, only_functions) end --- --- Returns a list of apidocs for the given symbol. --- If there are multiple apidocs, the index of one to display is the value of --- the `pos` key in the returned list. +-- Returns a list of apidocs for *symbol* name. +-- The list contains a `pos` key with the index of the apidoc to show. -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @param symbol The symbol to get apidocs for. -- @return apidoc_list or `nil` @@ -656,7 +661,7 @@ end local apidocs = nil --- --- Shows a calltip with API documentation for the symbol behind the caret. +-- Shows a call tip with API documentation for the symbol behind the caret. -- If documentation is already being shown, cycles through multiple definitions. -- @param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses -- the current language's Adeptsense (if it exists). @@ -705,14 +710,16 @@ events.connect(events.CALL_TIP_CLICK, function(position) end) --- --- Loads the given ctags file for autocompletion. --- It is recommended to pass `-n` to ctags in order to use line numbers instead --- of text patterns to locate tags. This will greatly reduce memory usage for a --- large number of symbols if `nolocations` is not `true`. +-- Loads the Ctags file *tag_file* for autocompletions. +-- If *nolocations* is `true`, `sense:goto_ctag()` cannot be used with this set +-- of tags. It is recommended to pass `-n` to `ctags` in order to use line +-- numbers instead of text patterns to locate tags. This will greatly reduce +-- memory usage for a large number of symbols if `nolocations` is `false`. -- @param sense The Adeptsense returned by `adeptsense.new()`. --- @param tag_file The path of the ctags file to load. --- @param nolocations If `true`, does not store the locations of the tags for --- use by `goto_ctag()`. The default value is `false`. +-- @param tag_file The path of the Ctags file to load. +-- @param nolocations Optional flag indicating whether or not to discard the +-- locations of the tags for use by `sense:goto_ctag()`. The default value is +-- `false`. -- @name load_ctags function M.load_ctags(sense, tag_file, nolocations) local ctags_kinds = sense.ctags_kinds @@ -785,21 +792,21 @@ function M.load_ctags(sense, tag_file, nolocations) end --- --- Displays a filtered list dialog of all known symbols of the given kind --- (classes, functions, fields, etc.) and jumps to the source of the selected --- one. +-- Prompts the user to select a symbol to jump to from a list of all known +-- symbols of kind *kind* (classes, functions, fields, etc.) shown in a filtered +-- list dialog whose title text is *title*. -- @param sense The Adeptsense returned by `adeptsense.new()`. --- @param k The ctag character kind (e.g. `'f'` for a Lua function). +-- @param kind The Ctag character kind (e.g. `'f'` for a Lua function). -- @param title The title for the filtered list dialog. -- @name goto_ctag -function M.goto_ctag(sense, k, title) - if not sense.locations[k] then return end -- no ctags loaded +function M.goto_ctag(sense, kind, title) + if not sense.locations[kind] then return end -- no Ctags loaded local items = {} - local kind = sense.ctags_kinds[k] - for k, v in pairs(sense.locations[k]) do - items[#items + 1] = k:match('[^#]+$') -- symbol name + local kind = sense.ctags_kinds[kind] + for kind, v in pairs(sense.locations[kind]) do + items[#items + 1] = kind:match('[^#]+$') -- symbol name if kind == M.FUNCTION or kind == M.FIELD then - items[#items + 1] = k:match('^[^#]+') -- class name + items[#items + 1] = kind:match('^[^#]+') -- class name end items[#items + 1] = v[1]..':'..v[2] end @@ -825,21 +832,21 @@ function M.goto_ctag(sense, k, title) end --- --- Called by `load_ctags()` when a ctag kind is not recognized. --- This method should be replaced with your own that is specific to the --- language. +-- Called by `load_ctags()` when a Ctag kind is not recognized. +-- The parameters are extracted from Ctags' [tag format][]. This method should +-- be replaced with your own that is specific to the language. +-- +-- [tag format]: http://ctags.sourceforge.net/ctags.html#TAG%20FILE%20FORMAT -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @param tag_name The tag name. -- @param file_name The name of the file the tag belongs to. --- @param ex_cmd The `ex_cmd` returned by ctags. --- @param ext_fields The `ext_fields` returned by ctags. +-- @param ex_cmd The `ex_cmd` returned by Ctags. +-- @param ext_fields The `ext_fields` returned by Ctags. -- @name handle_ctag function M.handle_ctag(sense, tag_name, file_name, ex_cmd, ext_fields) end --- --- Clears an Adeptsense. --- This is necessary for loading a new ctags file or completions from a --- different project. +-- Clears the Adeptsense for loading new Ctags or project files. -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @name clear function M.clear(sense) @@ -851,7 +858,7 @@ function M.clear(sense) end --- --- Called when clearing an Adeptsense. +-- Called when clearing the Adeptsense. -- This function should be replaced with your own if you have any persistant -- objects that need to be deleted. -- @param sense The Adeptsense returned by `adeptsense.new()`. @@ -859,7 +866,7 @@ end function M.handle_clear(sense) end --- --- Creates a new Adeptsense for the given lexer language. +-- Creates and returns a new Adeptsense for *lang* name. -- Only one sense can exist per language. -- @param lang The lexer language to create an Adeptsense for. -- @return adeptsense @@ -883,7 +890,7 @@ function M.new(lang) always_show_globals = true, --- --- Contains a map of ctags kinds to Adeptsense kinds. +-- A map of Ctags kinds to Adeptsense kinds. -- Recognized kinds are `FUNCTION`, `FIELD`, and `CLASS`. Classes are quite -- simply containers for functions and fields so Lua modules would count as -- classes. Any other kinds will be passed to `handle_ctag()` for user-defined @@ -901,13 +908,14 @@ function M.new(lang) ctags_kinds = {}, --- --- Contains a map of classes and a list of their inherited classes. +-- A map of classes and a list of their inherited classes, normally populated by +-- `load_ctags()`. -- @class table -- @name inherited_classes inherited_classes = {}, --- --- Contains lists of possible completions for known symbols. +-- A list containing lists of possible completions for known symbols. -- Each symbol key has a table value that contains a list of field completions -- with a `fields` key and a list of functions completions with a `functions` -- key. This table is normally populated by `load_ctags()`, but can also be set @@ -917,14 +925,14 @@ inherited_classes = {}, completions = {}, --- --- Contains the locations of known symbols. --- This table is populated by `load_ctags()`. +-- A list of the locations of known symbols, normally populated by +-- `load_ctags()`. -- @class table -- @name locations locations = {}, --- --- Contains a list of api files used by `show_apidoc()`. +-- A list of api files used by `show_apidoc()`. -- Each line in the api file contains a symbol name (not the full symbol) -- followed by a space character and then the symbol's documentation. Since -- there may be many duplicate symbol names, it is recommended to put the full @@ -937,35 +945,36 @@ locations = {}, api_files = {}, --- --- Contains syntax-specific values for the language. --- @field self The language's syntax-equivalent of `self`. Default is `'self'`. +-- Map of language-specific syntax settings. +-- @field self The language's syntax-equivalent of `self`. The default value is +-- `'self'`. -- @field class_definition A Lua pattern representing the language's class -- definition syntax. The first capture returned must be the class name. A -- second, optional capture contains the class' superclass (if any). If no -- completions are found for the class name, completions for the superclass -- are shown (if any). Completions will not be shown for both a class and --- superclass unless defined in a previously loaded ctags file. Also, multiple --- superclasses cannot be recognized by this pattern; use a ctags file +-- superclass unless defined in a previously loaded Ctags file. Also, multiple +-- superclasses cannot be recognized by this pattern; use a Ctags file -- instead. The default value is `'class%s+([%w_]+)'`. -- @field word_chars A Lua pattern of characters allowed in a word. --- The default is `'%w_'`. +-- The default value is `'%w_'`. -- @field symbol_chars A Lua pattern of characters allowed in a symbol, -- including member operators. The pattern should be a character set. --- The default is `'[%w_%.]'`. +-- The default value is `'[%w_%.]'`. -- @field type_declarations A list of Lua patterns used for determining the -- class type of a symbol. The first capture returned must be the class name. -- Use `%_` to match the symbol. -- The default value is `'(%u[%w_%.]+)%s+%_'`. -- @field type_declarations_exclude A table of types to exclude, even if they --- match a type_declaration pattern. Each excluded type is a table key and has --- a `true` boolean value. For example, `{Foo = true}` excludes any type whose --- name is `Foo`. +-- match a `type_declarations` pattern. Each excluded type is a table key and +-- has a `true` boolean value. For example, `{Foo = true}` excludes any type +-- whose name is `Foo`. -- The default value is `{}`. -- @field type_assignments A map of Lua patterns to class types for variable --- assignments. This is typically used for dynamically typed languages. For --- example, `sense.type_assignments['^"'] = 'string'` would recognize string +-- assignments, typically used for dynamically typed languages. For example, +-- `sense.syntax.type_assignments['^"'] = 'string'` would recognize string -- assignments in Lua so the `foo` in `foo = "bar"` would be recognized as --- type `string`. The class type value can contain pattern captures. +-- type `string`. The class type value may contain `%n` pattern captures. -- @class table -- @name syntax -- @see get_class diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua index 1b568357..e7b7a3b4 100644 --- a/modules/textadept/bookmarks.lua +++ b/modules/textadept/bookmarks.lua @@ -6,7 +6,7 @@ local M = {} --- -- Bookmarks for Textadept. -- @field MARK_BOOKMARK_COLOR (number) --- The color used for a bookmarked line in "0xBBGGRR" format. +-- The color, in "0xBBGGRR" format, used for a bookmarked line. module('_M.textadept.bookmarks')]] M.MARK_BOOKMARK_COLOR = not NCURSES and 0xB3661A or 0xFF0000 @@ -14,9 +14,10 @@ M.MARK_BOOKMARK_COLOR = not NCURSES and 0xB3661A or 0xFF0000 local MARK_BOOKMARK = _SCINTILLA.next_marker_number() --- --- Toggles a bookmark on the current line. --- @param on If `true`, adds a bookmark to the current line. If `false`, removes --- the bookmark on the current line. Otherwise, toggles a bookmark. +-- Toggles the bookmark on the current line unless *on* is given. +-- If *on* is `true` or `false`, adds or removes the bookmark, respectively. +-- @param on Optional flag indicating whether to add or remove a bookmark on the +-- current line. The default value is `nil`, toggling a bookmark. -- @name toggle function M.toggle(on) local buffer = buffer @@ -52,21 +53,21 @@ local function goto_mark(f, increment, wrap_start) end --- --- Goes to the next bookmark in the current buffer. +-- Goes to the next bookmarked line in the current buffer. -- @name goto_next function M.goto_next() goto_mark(buffer.marker_next, 1, 0) end --- --- Goes to the previous bookmark in the current buffer. +-- Goes to the previous bookmarked line in the current buffer. -- @name goto_prev function M.goto_prev() goto_mark(buffer.marker_previous, -1, buffer.line_count) end --- --- Goes to selected bookmark from a filtered list. +-- Prompts the user to select a bookmarked line to go to. -- @name goto_bookmark function M.goto_bookmark() local buffer = buffer diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua index 6226ff6c..149c37c8 100644 --- a/modules/textadept/command_entry.lua +++ b/modules/textadept/command_entry.lua @@ -96,9 +96,9 @@ end) local focus --- --- Shows the given list of completions for the current word prefix. --- On selection, the current word prefix is replaced with the completion. Word --- prefix characters are alphanumerics and underscores. +-- Shows the completion list *completions* for the current word prefix. +-- Word prefix characters are alphanumerics and underscores. On selection, the +-- word prefix is replaced with the completion. -- @param completions The table of completions to show. Non-string values are -- ignored. -- @class function diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua index c7f7b755..c7c6b381 100644 --- a/modules/textadept/editing.lua +++ b/modules/textadept/editing.lua @@ -6,31 +6,30 @@ local M = {} --- -- Editing features for Textadept. -- @field AUTOPAIR (bool) --- Opening '(', '[', '{', '"', or ''' characters are automatically --- closed. +-- Automatically close opening '(', '[', '{', '"', or ''' +-- characters. -- The default value is `true`. -- Auto-paired characters are defined in the [`char_matches`](#char_matches) -- table. -- @field HIGHLIGHT_BRACES (bool) --- Highlight matching "()[]{}" characters. +-- Highlight matching brace characters like "()[]{}". -- The default value is `true`. -- Matching braces are defined in the [`braces`](#braces) table. -- @field AUTOINDENT (bool) --- Match the indentation level of the previous line when pressing the `Enter` --- (`↩` on Mac OSX | `Enter` in ncurses) key. +-- Match the indentation level of the previous line when inserting a new line. -- The default value is `true`. -- @field STRIP_WHITESPACE_ON_SAVE (bool) -- Strip trailing whitespace on file save. -- The default value is `true`. -- @field MARK_HIGHLIGHT_BACK (number) --- The background color used for a line containing a --- [highlighted word](#highlight_word) in "0xBBGGRR" format. +-- The background color, in "0xBBGGRR" format, used for a line containing the +-- [highlighted word](#highlight_word). -- @field INDIC_HIGHLIGHT_BACK (number) --- The color used for an indicator for a [highlighted word](#highlight_word) --- in "0xBBGGRR" format. +-- The color, in "0xBBGGRR" format, used for an indicator for the +-- [highlighted word](#highlight_word). -- @field INDIC_HIGHLIGHT_ALPHA (number) --- The alpha transparency value between `0` (transparent) and `255` (opaque) --- used for an indicator for a [highlighted word](#highlight_word). +-- The alpha value, ranging from `0` (transparent) to `255` (opaque) used for +-- an indicator for the [highlighted word](#highlight_word). -- The default value is `100`. module('_M.textadept.editing')]] @@ -44,10 +43,10 @@ M.INDIC_HIGHLIGHT_BACK = 0x4D99E6 M.INDIC_HIGHLIGHT_ALPHA = 100 --- --- Comment strings for various lexer languages. --- Used by the `block_comment()` function. Keys are lexer language names and --- values are the line comment delimiters for the language. This table is --- typically populated by [language-specific modules][]. +-- Map of lexer names to line comment prefix strings for programming languages, +-- used by the `block_comment()` function. +-- Keys are lexer names and values are the line comment prefixes for the +-- language. This table is typically populated by [language-specific modules][]. -- -- [language-specific modules]: _M.html#Block.Comment -- @class table @@ -56,12 +55,12 @@ M.INDIC_HIGHLIGHT_ALPHA = 100 M.comment_string = {} --- --- Auto-matched characters. --- Used for auto-matching parentheses, brackets, braces, quotes, etc. Keys are --- lexer language names and values are tables of character match pairs. A pair's --- key is an ASCII value and the value is the string character match. The --- defaults are "()", "[]", "{}", "''", and """". --- This table can be populated by language-specific modules. +-- Map of auto-paired characters like parentheses, brackets, braces, and quotes, +-- with language-specific auto-paired character maps assigned to a lexer name +-- key. +-- The ASCII values of opening characters are assigned to strings containing +-- complement characters. The default auto-paired characters are "()", "[]", +-- "{}", "''", and """". -- @class table -- @name char_matches -- @usage _M.textadept.editing.char_matches.hypertext = {..., [60] = '>'} @@ -69,11 +68,10 @@ M.comment_string = {} M.char_matches = {[40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"'} --- --- Highlighted brace characters. --- Keys are lexer language names and values are tables of character ASCII values --- that count as brace characters. The defaults are '(', ')', '[', ']', '{', and --- '}'. --- This table can be populated by language-specific modules. +-- Table of brace characters to highlight, with language-specific brace +-- character tables assigned to a lexer name key. +-- The ASCII values of brace characters are keys and are assigned non-`nil` +-- values. The default brace characters are '(', ')', '[', ']', '{', and '}'. -- @class table -- @name braces -- @usage _M.textadept.editing.braces.hypertext = {..., [60] = 1, [62] = 1} @@ -182,8 +180,10 @@ events_connect(events.FILE_BEFORE_SAVE, function() end) --- --- Goes to a matching brace position, selecting the text inside if specified to. --- @param select If `true`, selects the text between matching braces. +-- Goes to the current character's matching brace, selecting the text in-between +-- if *select* is `true`. +-- @param select Optional flag indicating whether or not to select the text +-- between matching braces. The default value is `false`. -- @name match_brace function M.match_brace(select) local buffer = buffer @@ -200,8 +200,10 @@ function M.match_brace(select) end --- --- Pops up an autocompletion list for the current word based on other words in --- the document. +-- Displays an autocompletion list, built from the set of *default_words* and +-- existing words in the buffer, for the word behind the caret, returning `true` +-- if completions were found. +-- *word_chars* contains a set of word characters. -- @param word_chars String of characters considered to be part of words. Since -- this string is used in a Lua pattern character set, character classes and -- ranges may be used. @@ -260,17 +262,20 @@ function M.autocomplete_word(word_chars, default_words) end --- --- Block comments or uncomments code with a given comment string. --- If none is specified, uses the `comment_string` table. --- @param comment The comment string inserted or removed from the beginning of --- each line in the selection. +-- Comments or uncomments the selected lines with line comment prefix string +-- *prefix* or the prefix from the `comment_string` table for the current lexer. +-- As long as any part of a line is selected, the entire line is eligible for +-- commenting/uncommenting. +-- @param prefix Optional prefix string inserted or removed from the beginning +-- of each line in the selection. The default value is the prefix in the +-- `comment_string` table for the current lexer. -- @see comment_string -- @name block_comment -function M.block_comment(comment) +function M.block_comment(prefix) local buffer = buffer - if not comment then - comment = M.comment_string[buffer:get_lexer(true)] - if not comment then return end + if not prefix then + prefix = M.comment_string[buffer:get_lexer(true)] + if not prefix then return end end local anchor, caret = buffer.selection_start, buffer.selection_end local s = buffer:line_from_position(anchor) @@ -280,13 +285,13 @@ function M.block_comment(comment) buffer:begin_undo_action() for line = s, e do local pos = buffer:position_from_line(line) - if buffer:text_range(pos, pos + #comment) == comment then - buffer:set_sel(pos, pos + #comment) + if buffer:text_range(pos, pos + #prefix) == prefix then + buffer:set_sel(pos, pos + #prefix) buffer:replace_sel('') - caret = caret - #comment + caret = caret - #prefix else - buffer:insert_text(pos, comment) - caret = caret + #comment + buffer:insert_text(pos, prefix) + caret = caret + #prefix end end buffer:end_undo_action() @@ -294,7 +299,7 @@ function M.block_comment(comment) end --- --- Goes to the requested line. +-- Goes to line number *line* or the user-specified line in the buffer. -- @param line Optional line number to go to. If `nil`, the user is prompted for -- one. -- @name goto_line @@ -328,10 +333,10 @@ function M.transpose_chars() end --- --- Joins the currently selected lines. +-- Joins the currently selected lines or the current line with the line below +-- it. -- As long as any part of a line is selected, the entire line is eligible for --- joining. If no lines are selected, joins the current line with the line --- below. +-- joining. -- @name join_lines function M.join_lines() local buffer = buffer @@ -345,9 +350,8 @@ function M.join_lines() end --- --- Encloses text within a given pair of strings. --- If text is selected, it is enclosed. Otherwise, the previous word is --- enclosed. +-- Encloses the selected text or the word behind the caret within strings *left* +-- and *right*. -- @param left The left part of the enclosure. -- @param right The right part of the enclosure. -- @name enclose @@ -361,7 +365,7 @@ function M.enclose(left, right) end --- --- Selects text between a given pair of strings. +-- Selects the text in-between strings *left* and *right* containing the caret. -- @param left The left part of the enclosure. -- @param right The right part of the enclosure. -- @name select_enclosed @@ -373,7 +377,7 @@ function M.select_enclosed(left, right) end --- --- Grows the selection by the given number of characters on either end. +-- Grows the selected text by *amount* number of characters on either end. -- @param amount The number of characters to grow the selection by on either -- end. -- @name grow_selection @@ -415,7 +419,7 @@ function M.select_paragraph() end --- --- Selects indented blocks intelligently. +-- Selects indented text blocks intelligently. -- If no block of text is selected, all text with the current level of -- indentation is selected. If a block of text is selected and the lines -- immediately above and below it are one indentation level lower, they are @@ -440,9 +444,11 @@ function M.select_indented_block() end --- --- Converts indentation between tabs and spaces. --- If `buffer.use_tabs` is `true`, all indenting spaces are converted to tabs. --- Otherwise, all indenting tabs are converted to spaces. +-- Converts indentation between tabs and spaces depending on the buffer's +-- indentation settings. +-- If `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are +-- converted to tabs. Otherwise, all indenting tabs are converted to +-- `buffer.tab_width` spaces. -- @see buffer.use_tabs -- @name convert_indentation function M.convert_indentation() @@ -483,8 +489,8 @@ events_connect(events.KEYPRESS, function(code) end) --- --- Highlights all occurances of either the selected text or the word under the --- caret and adds markers to the lines they are on. +-- Highlights all occurrences of the selected text or the word under the caret +-- and adds markers to the lines they are on. -- @see buffer.word_chars -- @name highlight_word function M.highlight_word() diff --git a/modules/textadept/filter_through.lua b/modules/textadept/filter_through.lua index e31de61f..07ef3aea 100644 --- a/modules/textadept/filter_through.lua +++ b/modules/textadept/filter_through.lua @@ -12,9 +12,8 @@ local tmpfile = _USERHOME..'/.ft' local filter_through_active = false --- --- Prompts for a Linux, BSD, Mac OSX, or Windows shell command to filter text --- through. --- The standard input (stdin) for shell commands is determined as follows: +-- Prompts the user for a Linux, BSD, Mac OSX, or Windows shell command to +-- filter text through with standard input (stdin) as follows: -- -- 1. If text is selected and spans multiple lines, all text on the lines -- containing the selection is used. However, if the end of the selection is at diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua index 63faf80c..65ea70ef 100644 --- a/modules/textadept/find.lua +++ b/modules/textadept/find.lua @@ -11,12 +11,16 @@ local find = gui.find -- The text in the replace entry. -- @field match_case (bool) -- Searches are case-sensitive. +-- The default value is `false`. -- @field whole_word (bool) --- Only whole-word matches are allowed in searches. +-- Match only whole-words in searches. +-- The default value is `false`. -- @field lua (bool) --- The search text is interpreted as a Lua pattern. +-- Interpret search text as a Lua pattern. +-- The default value is `false`. -- @field in_files (bool) -- Search for the text in a list of files. +-- The default value is `false`. -- @field find_label_text (string, Write-only) -- The text of the "Find" label. -- This is primarily used for localization. @@ -85,12 +89,12 @@ local escapes = { } --- --- Searches the given directory for files that match search text and options and --- prints the results to a buffer. +-- Searches the *utf8_dir* or user-specified directory for files that match +-- search text and options and prints the results to a buffer. -- Use the `find_text`, `match_case`, `whole_word`, and `lua` fields to set the -- search text and option flags, respectively. --- @param utf8_dir UTF-8 encoded directory name. If `nil`, the user is prompted --- for one. +-- @param utf8_dir Optional UTF-8 encoded directory name to search. If `nil`, +-- the user is prompted for one. -- @name find_in_files function find.find_in_files(utf8_dir) if not utf8_dir then @@ -383,9 +387,10 @@ end events_connect(events.DOUBLE_CLICK, goto_file) --- --- Goes to the next or previous file found relative to the file on the current --- line in the results list. --- @param next Flag indicating whether or not to go to the next file. +-- If *next* is `true`, goes to the next file found, relative to the file on the +-- current line in the results list. Otherwise goes to the previous file found. +-- @param next Optional flag indicating whether or not to go to the next file. +-- The default value is `false`. -- @name goto_file_in_list function find.goto_file_in_list(next) local orig_view = _VIEWS[view] @@ -428,25 +433,25 @@ end) local focus --- --- Mimicks a press of the "Find Next" button. +-- Mimics pressing the "Find Next" button. -- @class function -- @name find_next local find_next --- --- Mimicks a press of the "Find Prev" button. +-- Mimics pressing the "Find Prev" button. -- @class function -- @name find_prev local find_prev --- --- Mimicks a press of the "Replace" button. +-- Mimics pressing the "Replace" button. -- @class function -- @name replace local replace --- --- Mimicks a press of the "Replace All" button. +-- Mimics pressing the "Replace All" button. -- @class function -- @name replace_all local replace_all diff --git a/modules/textadept/keys.lua b/modules/textadept/keys.lua index c6263f16..7f4bf8b7 100644 --- a/modules/textadept/keys.lua +++ b/modules/textadept/keys.lua @@ -5,8 +5,9 @@ local M = {} --[[ This comment is for LuaDoc. --- -- Defines key commands for Textadept. --- This set of key commands is pretty standard among other text editors. --- This module should be `require`d last, but before `_M.textadept.menu`. +-- This set of key commands is pretty standard among other text editors. If +-- applicable, load this module second to last in your *~/.textadept/init.lua*, +-- before `_M.textadept.menu`. -- -- ## Key Bindings -- @@ -25,7 +26,7 @@ local M = {} -- None |None |None |Load session... -- Ctrl+Q |⌘Q |^Q |Quit -- **Edit** | | | --- Ctrl+Z<br/>Alt+Backspace|⌘Z |^Z |Undo +-- Ctrl+Z<br/>Alt+Bksp |⌘Z |^Z |Undo -- Ctrl+Y<br/>Ctrl+Shift+Z |⌘⇧Z |^Y |Redo -- Ctrl+X<br/>Shift+Del |⌘X<br/>⇧⌦|^X |Cut -- Ctrl+C<br/>Ctrl+Ins |⌘C |^C |Copy @@ -113,14 +114,15 @@ local M = {} -- None |None |None |UTF-8 encoding -- None |None |None |ASCII encoding -- None |None |None |ISO-8859-1 encoding +-- None |None |None |MacRoman encoding -- None |None |None |UTF-16 encoding -- Ctrl+Shift+L |⌘⇧L |M-S-L |Select lexer... -- F5 |F5 |^L<br/>F5 |Refresh syntax highlighting -- **View** | | | -- Ctrl+Alt+N |^⌥⇥ |N/A |Next view -- Ctrl+Alt+P |^⌥⇧⇥ |N/A |Previous view --- Ctrl+Alt+S<br/>Ctrl+Alt+H|^S |N/A |Split view horizontal --- Ctrl+Alt+V |^V |N/A |Split view vertical +-- Ctrl+Alt+S<br/>Ctrl+Alt+H|^S |N/A |Split view horizontally +-- Ctrl+Alt+V |^V |N/A |Split view vertically -- Ctrl+Alt+W |^W |N/A |Unsplit view -- Ctrl+Alt+Shift+W |^⇧W |N/A |Unsplit all views -- Ctrl+Alt++<br/>Ctrl+Alt+=|^+<br/>^=|N/A |Grow view diff --git a/modules/textadept/menu.lua b/modules/textadept/menu.lua index f02c27a2..e224ca82 100644 --- a/modules/textadept/menu.lua +++ b/modules/textadept/menu.lua @@ -5,9 +5,10 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Provides dynamic menus for Textadept. --- This module should be `require`d last, after `_M.textadept.keys` since it --- looks up defined key commands to show them in menus. +-- Defines the menus used by Textadept. +-- If applicable, load this module last in your *~/.textadept/init.lua*, after +-- `_M.textadept.keys` since it looks up defined key commands to show them in +-- menus. module('_M.textadept.menu')]] -- Get a string uniquely identifying a key binding. @@ -30,7 +31,8 @@ local utils = m_textadept.keys.utils local SEPARATOR, c = {''}, _SCINTILLA.constants --- --- Contains the main menubar. +-- Defines the default main menubar. +-- Changing this field does not change the menubar. Use `set_menubar()` instead. -- @see set_menubar -- @class table -- @name menubar @@ -218,7 +220,9 @@ M.menubar = { } --- --- Contains the default right-click context menu. +-- Defines the default right-click context menu. +-- Changing this field does not change the context menu. Use `set_contextmenu()` +-- instead. -- @see set_contextmenu -- @class table -- @name context_menu @@ -287,12 +291,13 @@ local function build_command_tables(menu, title, items, commands) end --- --- Sets `gui.menubar` from the given table of menus. --- @param menubar The table of menus to create the menubar from. Each menu is --- an ordered list of menu entries and has a `title` key for the menu/submenu --- title. Menu entries are either submenus of the same form as menus, or --- tables containing menu text and either a function to call or a table --- containing the function to call with its parameters. +-- Sets `gui.menubar` from *menubar*, a table of menus. +-- Each menu is an ordered list of menu items and has a `title` key for the +-- title text. Menu items are tables containing menu text and either a function +-- to call or a table containing a function with its parameters to call when an +-- item is clicked. Menu items may also be sub-menus, ordered lists of menu +-- items with an additional `title` key for the sub-menu's title text. +-- @param menubar The table of menus to create the menubar from. -- @see gui.menubar -- @see gui.menu -- @name set_menubar @@ -311,24 +316,24 @@ end M.set_menubar(M.menubar) --- --- Sets `gui.context_menu` from the given menu table. --- @param menu_table The menu table to create the context menu from. The menu is --- an ordered list of menu entries and, if applicable, has a `title` key for --- the submenu title. Menu entries are either submenus of the same form as --- menus, or tables containing menu text and either a function to call or a --- table containing the function to call with its parameters. +-- Sets `gui.context_menu` from *menu*, an ordered list of menu items. +-- Menu items are tables containing menu text and either a function to call or +-- a table containing a function with its parameters to call when an item is +-- clicked. Menu items may also be sub-menus, ordered lists of menu items with +-- an additional `title` key for the sub-menu's title text. +-- @param menu The menu to create the context menu from. -- @see gui.context_menu -- @see gui.menu -- @name set_contextmenu -function M.set_contextmenu(menu_table) +function M.set_contextmenu(menu) contextmenu_actions = {} - gui.context_menu = gui.menu(read_menu_table(menu_table, true)) + gui.context_menu = gui.menu(read_menu_table(menu, true)) end if not NCURSES then M.set_contextmenu(M.context_menu) end local columns = {_L['Command'], _L['Key Command']} --- --- Prompts the user with a filtered list dialog to run menu commands. +-- Prompts the user to select a menu command to run. -- @name select_command function M.select_command() local i = gui.filteredlist(_L['Run Command'], columns, items, true, diff --git a/modules/textadept/mime_types.lua b/modules/textadept/mime_types.lua index 2675b9fc..2e07a3a4 100644 --- a/modules/textadept/mime_types.lua +++ b/modules/textadept/mime_types.lua @@ -4,14 +4,14 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Handles file type detection. +-- Handles file type detection for Textadept. -- @field _G.events.LANGUAGE_MODULE_LOADED (string) -- Called after loading a language-specific module. -- This is useful for overriding a language-specific module's key bindings -- or other properties since the module is not loaded when Textadept starts. -- Arguments: -- --- * `lang`: The language lexer name. +-- * *`lang`*: The language lexer name. module('_M.textadept.mime_types')]] -- Events. @@ -19,7 +19,8 @@ local events, events_connect = events, events.connect events.LANGUAGE_MODULE_LOADED = 'language_module_loaded' --- --- Table of file extensions with their associated lexers. +-- Map of file extensions (excluding the leading '.') to their associated +-- lexers. -- If the file type is not recognized by shebang words or first-line patterns, -- each file extension is matched against the file's extension. -- @class table @@ -27,7 +28,7 @@ events.LANGUAGE_MODULE_LOADED = 'language_module_loaded' M.extensions = {} --- --- Table of shebang words and their associated lexers. +-- Map of shebang words to their associated lexers. -- If the file has a shebang line, a line that starts with "#!" and is the first -- line in the file, each shebang word is matched against that line. -- @class table @@ -35,7 +36,7 @@ M.extensions = {} M.shebangs = {} --- --- Table of first-line patterns and their associated lexers. +-- Map of first-line patterns to their associated lexers. -- If a file type is not recognized by shebang words, each pattern is matched -- against the first line in the file. -- @class table @@ -69,8 +70,7 @@ for line in mime_types:gmatch('[^\r\n]+') do end --- --- List of detected lexers. --- Lexers are read from *lexers/* and *~/.textadept/lexers/*. +-- List of detected lexers are read from *lexers/* and *~/.textadept/lexers/*. -- @class table -- @name lexers M.lexers = {} @@ -93,8 +93,7 @@ for lexer in pairs(lexers_found) do M.lexers[#M.lexers + 1] = lexer end table.sort(M.lexers) --- --- Prompts the user to select a lexer from a filtered list for the current --- buffer. +-- Prompts the user to select a lexer for the current buffer. -- @see buffer.set_lexer -- @name select_lexer function M.select_lexer() diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua index 149c6738..a4089e5a 100644 --- a/modules/textadept/run.lua +++ b/modules/textadept/run.lua @@ -11,21 +11,21 @@ local M = {} -- -- [language-specific modules]: _M.html#Compile.and.Run -- @field _G.events.COMPILE_OUTPUT (string) --- Called after a compile command is executed. +-- Called after executing a language's compile command. -- By default, compiler output is printed to the message buffer. To override -- this behavior, connect to the event with an index of `1` and return `true`. -- Arguments: -- --- * `lexer`: The lexer language. --- * `output`: The output from the command. +-- * `lexer`: The lexer language name. +-- * `output`: The string output from the command. -- @field _G.events.RUN_OUTPUT (string) --- Called after a run command is executed. +-- Called after executing a language's run command. -- By default, output is printed to the message buffer. To override this -- behavior, connect to the event with an index of `1` and return `true`. -- Arguments: -- --- * `lexer`: The lexer language. --- * `output`: The output from the command. +-- * `lexer`: The lexer language name. +-- * `output`: The string output from the command. module('_M.textadept.run')]] -- Events. @@ -110,15 +110,14 @@ local function print_output(lexer, output) end --- --- File extensions and their associated "compile" shell commands. --- Each key is a file extension whose value is a either a command line string to --- execute or a function returning one. The command string can have the --- following macros: +-- Map of file extensions (excluding the leading '.') to their associated +-- "compile" shell command line strings or functions returning such strings. +-- Command line strings may have the following macros: -- -- + `%(filepath)`: The full path of the current file. -- + `%(filedir)`: The current file's directory path. --- + `%(filename)`: The name of the file including extension. --- + `%(filename_noext)`: The name of the file excluding extension. +-- + `%(filename)`: The name of the file, including its extension. +-- + `%(filename_noext)`: The name of the file, excluding its extension. -- -- This table is typically populated by [language-specific modules][]. -- @@ -138,15 +137,14 @@ function M.compile() command(M.compile_command, true) end events_connect(events.COMPILE_OUTPUT, print_output) --- --- File extensions and their associated "run" shell commands. --- Each key is a file extension whose value is either a command line string to --- execute or a function returning one. The command string can have the --- following macros: +-- Map of file extensions (excluding the leading '.') to their associated +-- "run" shell command line strings or functions returning such strings. +-- Command line strings may have the following macros: -- -- + `%(filepath)`: The full path of the current file. -- + `%(filedir)`: The current file's directory path. --- + `%(filename)`: The name of the file including extension. --- + `%(filename_noext)`: The name of the file excluding extension. +-- + `%(filename)`: The name of the file, including its extension. +-- + `%(filename_noext)`: The name of the file, excluding its extension. -- -- This table is typically populated by [language-specific modules][]. -- @@ -166,17 +164,17 @@ function M.run() command(M.run_command) end events_connect(events.RUN_OUTPUT, print_output) --- --- A table of error string details for different programming languages. --- Each key is a lexer name whose value is a table with the following fields: +-- Map of lexer names to their error string details, tables containing the +-- following fields: -- --- + `pattern`: The Lua pattern that matches a specific error string with --- captures for the filename the error occurs in, the line number the error --- occurred on, and an optional error message. --- + `filename`: The index of the Lua capture that contains the filename the --- error occured in. --- + `line`: The index of the Lua capture that contains the line number the --- error occured on. --- + `message`: (Optional) The index of the Lua capture that contains the +-- + `pattern`: A Lua pattern that matches the language's error string, +-- capturing the filename the error occurs in, the line number the error +-- occurred on, and optionally the error message. +-- + `filename`: The numeric index of the Lua capture containing the filename +-- the error occurred in. +-- + `line`: The numeric index of the Lua capture containing the line number +-- the error occurred on. +-- + `message`: (Optional) The numeric index of the Lua capture containing the -- error's message. An annotation will be displayed if a message was -- captured. -- @@ -190,8 +188,9 @@ events_connect(events.RUN_OUTPUT, print_output) M.error_detail = {} --- --- Goes to the line in the file an error occured at based on the error message --- at the given position and displays an annotation with the error message. +-- Goes to line number *line_num* in the file an error occurred at based on the +-- error message at position *pos* in the buffer and displays an annotation with +-- the error message. -- This is typically called by an event handler for when the user double-clicks -- on an error message. -- @param pos The position of the caret. diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua index 80122183..82f5415b 100644 --- a/modules/textadept/session.lua +++ b/modules/textadept/session.lua @@ -6,18 +6,17 @@ local M = {} --- -- Session support for Textadept. -- @field DEFAULT_SESSION (string) --- The path to the default session file. --- The default value is *`_USERHOME`/session*, or *`_USERHOME`/session_term* --- if [`_G.NCURSES`][] is `true`. +-- The path to the default session file, *`_USERHOME`/session*, or +-- *`_USERHOME`/session_term* if [`_G.NCURSES`][] is `true`. -- -- [`_G.NCURSES`]: _G.html#NCURSES -- @field SAVE_ON_QUIT (bool) -- Save the session when quitting. --- The default value is `true`, but can be disabled by passing the command --- line switch `-n` or `--nosession` to Textadept. +-- The default value is `true`, but is disabled when passing the command line +-- switch `-n` or `--nosession` to Textadept. -- @field MAX_RECENT_FILES (number) --- The maximum number of files from [`io.recent_files`][] to save to the --- session. +-- The maximum number of recent files to save to the session. +-- Recent files are stored in [`io.recent_files`][]. -- The default value is `10`. -- -- [`io.recent_files`]: io.html#recent_files @@ -28,11 +27,12 @@ M.SAVE_ON_QUIT = true M.MAX_RECENT_FILES = 10 --- --- Loads a Textadept session file. +-- Loads the Textadept session file *filename* or prompts the user to select +-- one, returning `true` if the session file was opened and read. -- Textadept restores split views, opened buffers, cursor information, and -- recent files. --- @param filename The absolute path to the session file to load. If `nil`, the --- user is prompted for one. +-- @param filename Optional absolute path to the session file to load. If `nil`, +-- the user is prompted for one. -- @return `true` if the session file was opened and read; `false` otherwise. -- @usage _M.textadept.session.load(filename) -- @see DEFAULT_SESSION @@ -122,10 +122,10 @@ events.connect('arg_none', function() end) --- --- Saves a Textadept session to a file. +-- Saves a Textadept session to file *filename* or a user-selected file. -- Saves split views, opened buffers, cursor information, and recent files. --- @param filename The absolute path to the session file to save. If `nil`, the --- user is prompted for one. +-- @param filename Optional absolute path to the session file to save. If `nil`, +-- the user is prompted for one. -- @usage _M.textadept.session.save(filename) -- @see DEFAULT_SESSION -- @name save diff --git a/modules/textadept/snapopen.lua b/modules/textadept/snapopen.lua index 0e91966b..48ad2783 100644 --- a/modules/textadept/snapopen.lua +++ b/modules/textadept/snapopen.lua @@ -6,10 +6,10 @@ local M = {} --- -- Quickly open files in a set of directories using a filtered list dialog. -- @field DEFAULT_DEPTH (number) --- Maximum directory depth to search. +-- The maximum directory depth to search. -- The default value is `99`. -- @field MAX (number) --- Maximum number of files to list. +-- The maximum number of files to list. -- The default value is `1000`. module('_M.textadept.snapopen')]] diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua index 9654a7c2..0d85f314 100644 --- a/modules/textadept/snippets.lua +++ b/modules/textadept/snippets.lua @@ -130,10 +130,11 @@ local function new_snippet(text, trigger) end --- --- Inserts a new snippet or goes to the next placeholder of the active snippet. +-- Inserts snippet text *text* or the snippet associated with the trigger behind +-- the caret as a snippet, or goes to the next placeholder of the active +-- snippet, ultimately only returning `false` if no action was taken. -- @param text Optional snippet text. If `nil`, attempts to insert a new snippet --- based on the trigger, the word to the left of the caret, and the current --- lexer. +-- based on the trigger, the word behind caret, and the current lexer. -- @return `false` if no action was taken; `nil` otherwise. -- @see buffer.word_chars -- @name _insert @@ -157,7 +158,7 @@ end --- -- Goes back to the previous snippet placeholder, reverting any changes from the --- current one. +-- current one, but returns `false` only if no snippet is active. -- @return `false` if no snippet is active; `nil` otherwise. -- @name _previous function M._previous() @@ -166,16 +167,15 @@ function M._previous() end --- --- Cancels the active snippet, reverting to the state before its activation, and --- restores the previously running snippet (if any). +-- Cancels insertion of the active snippet. -- @name _cancel_current function M._cancel_current() if #snippet_stack > 0 then snippet_stack[#snippet_stack]:cancel() end end --- --- Prompts the user to select a snippet to insert from a filtered list dialog. --- Global snippets and snippets in the current lexer are shown. +-- Prompts the user for a snippet to insert from a list of global and +-- language-specific snippets. -- @name _select function M._select() local list = {} @@ -387,9 +387,8 @@ events.connect(events.VIEW_NEW, function() buffer.indic_style[INDIC_SNIPPET] = INDIC_HIDDEN end) --- --- Table of snippet triggers with their snippet text. --- Language-specific snippets are in another table value whose key is the --- language's lexer name. +-- Map of snippet triggers with their snippet text, with language-specific +-- snippets tables assigned to a lexer name key. -- This table also contains the `_M.textadept.snippets` module. -- @class table -- @name _G.snippets |