From 9dc8ce16a1efc6482db6f1d5456d42958e79a06c Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Wed, 12 Sep 2012 11:24:11 -0400 Subject: Documentation overhaul. Rewrote most of the manual and Lua API to complement each other. Key bindings reference moved from Appendix to modules/textadept/keys.lua LuaDoc. --- modules/textadept/adeptsense.lua | 96 +++++++++++-------- modules/textadept/bookmarks.lua | 2 +- modules/textadept/command_entry.lua | 5 +- modules/textadept/editing.lua | 76 +++++++++------ modules/textadept/filter_through.lua | 4 +- modules/textadept/find.lua | 33 ++++--- modules/textadept/keys.lua | 181 ++++++++++++++++++++++++++++++++++- modules/textadept/menu.lua | 32 ++++--- modules/textadept/mime_types.lua | 21 ++-- modules/textadept/run.lua | 67 +++++++------ modules/textadept/session.lua | 14 ++- modules/textadept/snapopen.lua | 50 ++++------ modules/textadept/snippets.lua | 156 ++++++++++++------------------ 13 files changed, 471 insertions(+), 266 deletions(-) (limited to 'modules/textadept') diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua index 627d885e..245dc23f 100644 --- a/modules/textadept/adeptsense.lua +++ b/modules/textadept/adeptsense.lua @@ -4,17 +4,16 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Language autocompletion support for the textadept module. +-- Code autocompletion and documentation support for programming languages. -- -- ## Overview -- -- Adeptsense is a form of autocompletion for programming. It has the means to -- supply a list of potential completions for classes, member functions and --- fields, packages, etc. Adeptsense can also display documentation for such --- entities in the form of a calltip. This document provides the information --- necessary in order to write a new Adeptsense for a language. For illustrative --- purposes, an Adeptsense for Lua will be created. More advanced techniques --- are covered later. +-- fields, packages, etc and display their documentation in the form of a +-- calltip. This document provides the information necessary in order to write a +-- new Adeptsense for a language. For illustrative purposes, an Adeptsense for +-- Lua will be created. More advanced techniques are covered later. -- -- ## Creating an Adeptsense -- @@ -32,11 +31,11 @@ local M = {} -- -- Not all languages have "classes", "functions", and "fields" in the full sense -- of the word. Normally classes are referred to as objects in Object Oriented --- Programming (OOP), functions are class or instance methods a class can have, --- and fields are class or instance properties. For example an "Apple" class may --- have a "color" field and an "eat" function. To Adeptsense, the term "class" --- is simply a container for "function" and "field" completions. "functions" and --- "fields" are only distinguished by an icon in the completion list. +-- Programming (OOP), functions are class or instance methods,and fields are +-- class or instance properties. For example a "Cat" class may have a "color" +-- field and a "meow" function. To Adeptsense, the term "class" is simply a +-- container for "function" and "field" completions. "functions" and "fields" +-- are only distinguished by an icon in the completion list. -- -- For Lua, consider modules and tables as "classes", functions as "functions", -- and module/table keys as "fields". @@ -146,10 +145,10 @@ local M = {} -- `'F'`, should be fields; and modules, `'m'`, should be classes: -- -- sense.ctags_kinds = { --- f = 'functions', --- F = 'fields', --- m = 'classes', --- t = 'fields', +-- f = _M.textadept.adeptsense.FUNCTION, +-- F = _M.textadept.adeptsense.FIELD, +-- m = _M.textadept.adeptsense.CLASS, +-- t = _M.textadept.adeptsense.FIELD, -- } -- -- To load a default set of Ctags, use [`load_ctags()`](#load_ctags). @@ -306,7 +305,7 @@ local M = {} -- additional list of completions. -- -- Finally since an `imports` table was created, it should be cleared when the --- Adeptsense is cleared to free up memory. When this happens, +-- Adeptsense is cleared to free up memory immediately. When this happens, -- [`handle_clear()`](#handle_clear) is called. -- -- function sense:handle_clear() @@ -368,12 +367,18 @@ 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['']`. The default value is --- `true`. +-- class. They are contained in `completions['']`. +-- The default value is `true`. -- @field FUNCTIONS (string) -- XPM image for Adeptsense functions. -- @field FIELDS (string) -- XPM image for Adeptsense fields. +-- @field CLASS (string) +-- Ctags kind for Adeptsense classes. +-- @field FUNCTION (string) +-- Ctags kind for Adeptsense functions. +-- @field FIELD (string) +-- Ctags kind for Adeptsense fields. module('_M.textadept.adeptsense')]] local senses = {} @@ -381,6 +386,10 @@ local senses = {} M.FUNCTIONS = not NCURSES and '/* XPM */\nstatic char *function[] = {\n/* columns rows colors chars-per-pixel */\n"16 16 5 1",\n" c #000000",\n". c #E0BC38",\n"X c #F0DC5C",\n"o c #FCFC80",\n"O c None",\n/* pixels */\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOO OOOO",\n"OOOOOOOOO oo OO",\n"OOOOOOOO ooooo O",\n"OOOOOOO ooooo. O",\n"OOOO O XXoo.. O",\n"OOO oo XXX... O",\n"OO ooooo XX.. OO",\n"O ooooo. X. OOO",\n"O XXoo.. O OOOO",\n"O XXX... OOOOOOO",\n"O XXX.. OOOOOOOO",\n"OO X. OOOOOOOOO",\n"OOOO OOOOOOOOOO"\n};' or '*' M.FIELDS = not NCURSES and '/* XPM */\nstatic char *field[] = {\n/* columns rows colors chars-per-pixel */\n"16 16 5 1",\n" c #000000",\n". c #8C748C",\n"X c #9C94A4",\n"o c #ACB4C0",\n"O c None",\n/* pixels */\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOO OOOOO",\n"OOOOOOOO oo OOO",\n"OOOOOOO ooooo OO",\n"OOOOOO ooooo. OO",\n"OOOOOO XXoo.. OO",\n"OOOOOO XXX... OO",\n"OOOOOO XXX.. OOO",\n"OOOOOOO X. OOOO",\n"OOOOOOOOO OOOOO",\n"OOOOOOOOOOOOOOOO"\n};' or '+' +M.CLASS = 'classes' +M.FUNCTION = 'functions' +M.FIELD = 'fields' + --- -- Returns a full symbol (if any) and current symbol part (if any) behind the -- caret. @@ -716,7 +725,7 @@ function M.load_ctags(sense, tag_file, nolocations) if tag_name then local k = ext_fields:sub(1, 1) local kind = ctags_kinds[k] - if kind == 'functions' or kind == 'fields' then + if kind == M.FUNCTION or kind == M.FIELD then -- Update completions. -- If no class structure is found, the global namespace is used. for _, key in ipairs{ 'class', 'interface', 'struct', 'union', '' } do @@ -726,7 +735,7 @@ function M.load_ctags(sense, tag_file, nolocations) completions[class] = { fields = {}, functions = {} } end local t = completions[class][kind] - t[#t + 1] = tag_name..(kind == 'fields' and '?1' or '?2') + t[#t + 1] = tag_name..(kind == M.FIELD and '?1' or '?2') -- Update locations. if not nolocations then if not locations[k] then locations[k] = {} end @@ -735,7 +744,7 @@ function M.load_ctags(sense, tag_file, nolocations) break end end - elseif kind == 'classes' then + elseif kind == M.CLASS then -- Update class list. local inherits = ext_fields:match('inherits:(%S+)') if not inherits then inherits = ext_fields:match('struct:(%S+)') end @@ -776,11 +785,12 @@ function M.load_ctags(sense, tag_file, nolocations) end --- --- Displays a filteredlist of all known symbols of the given kind (classes, --- functions, fields, etc.) and jumps to the source of the selected one. +-- 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. -- @param sense The Adeptsense returned by `adeptsense.new()`. -- @param k The ctag character kind (e.g. `'f'` for a Lua function). --- @param title The title for the filteredlist dialog. +-- @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 @@ -788,13 +798,13 @@ function M.goto_ctag(sense, k, title) local kind = sense.ctags_kinds[k] for k, v in pairs(sense.locations[k]) do items[#items + 1] = k:match('[^#]+$') -- symbol name - if kind == 'functions' or kind == 'fields' then + if kind == M.FUNCTION or kind == M.FIELD then items[#items + 1] = k:match('^[^#]+') -- class name end items[#items + 1] = v[1]..':'..v[2] end local columns = { 'Name', 'Location' } - if kind == 'functions' or kind == 'fields' then + if kind == M.FUNCTION or kind == M.FIELD then table.insert(columns, 2, 'Class') end local location = gui.filteredlist(title, columns, items, false, @@ -874,15 +884,17 @@ function M.new(lang) --- -- Contains a map of ctags kinds to Adeptsense kinds. --- Recognized kinds are `'functions'`, `'fields'`, and `'classes'`. 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 handling. --- @usage luasense.ctags_kinds = { 'f' = 'functions' } --- @usage csense.ctags_kinds = { 'm' = 'fields', 'f' = 'functions', --- c = 'classes', s = 'classes' } --- @usage javasense.ctags_kinds = { 'f' = 'fields', 'm' = 'functions', --- c = 'classes', i = 'classes' } +-- 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 +-- handling. +-- @usage luasense.ctags_kinds = { f = _M.textadept.adeptsense.FUNCTION } +-- @usage csense.ctags_kinds = { m = _M.textadept.adeptsense.FIELD, +-- f = _M.textadept.adeptsense.FUNCTION, c = _M.textadept.adeptsense.CLASS, +-- s = _M.textadept.adeptsense.CLASS } +-- @usage javasense.ctags_kinds = { f = _M.textadept.adeptsense.FIELD, +-- m = _M.textadept.adeptsense.FUNCTION, c = _M.textadept.adeptsense.CLASS, +-- i = _M.textadept.adeptsense.CLASS } -- @class table -- @name ctags_kinds -- @see handle_ctag @@ -935,18 +947,20 @@ api_files = {}, -- 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_'`. +-- @field word_chars A Lua pattern of characters allowed in a word. +-- The default 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_%.]'`. +-- including member operators. The pattern should be a character set. +-- The default 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+%_'`. +-- 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`. The default value is `{}`. +-- 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 diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua index 75f36872..4ba836ca 100644 --- a/modules/textadept/bookmarks.lua +++ b/modules/textadept/bookmarks.lua @@ -4,7 +4,7 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Bookmarks for the textadept module. +-- Bookmarks for Textadept. -- @field MARK_BOOKMARK_COLOR (number) -- The color used for a bookmarked line in `0xBBGGRR` format. module('_M.textadept.bookmarks')]] diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua index c00df5db..262444d6 100644 --- a/modules/textadept/command_entry.lua +++ b/modules/textadept/command_entry.lua @@ -3,7 +3,7 @@ --[[ This comment is for LuaDoc. --- --- Textadept's Command entry. +-- Textadept's Command Entry. -- @field entry_text (string) -- The text in the entry. module('gui.command_entry')]] @@ -98,7 +98,8 @@ local focus --- -- Shows the given list of completions for the current word prefix. --- On selection, the current word prefix is replaced with the completion. +-- On selection, the current word prefix is replaced with the completion. Word +-- prefix characters are alphanumerics and underscores. -- @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 c702d297..e0eb4693 100644 --- a/modules/textadept/editing.lua +++ b/modules/textadept/editing.lua @@ -4,29 +4,32 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Editing commands for the textadept module. +-- Editing features for Textadept. -- @field AUTOPAIR (bool) --- Opening `(`, `[`, `[`, `"`, or `'` characters are automatically closed. +-- Opening `(`, `[`, `{`, `"`, or `'` characters are automatically closed. -- The default value is `true`. +-- Auto-paired characters are defined in the [`char_matches`](#char_matches) +-- table. -- @field HIGHLIGHT_BRACES (bool) -- Highlight matching `()[]{}` characters. -- 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 --- key. +-- Match the indentation level of the previous line when pressing the `Enter` +-- (`↩` on Mac OSX | `Enter` in ncurses) key. -- 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 in --- `0xBBGGRR` format. +-- The background color used for a line containing a +-- [highlighted word](#highlight_word) in `0xBBGGRR` format. -- @field INDIC_HIGHLIGHT_BACK (number) --- The color used for an indicator for a highlighted word in `0xBBGGRR` --- format. +-- The color used for an indicator for a [highlighted word](#highlight_word) +-- in `0xBBGGRR` format. -- @field INDIC_HIGHLIGHT_ALPHA (number) -- The alpha transparency value between `0` (transparent) and `255` (opaque) --- used for an indicator for a highlighted word. +-- used for an indicator for a [highlighted word](#highlight_word). -- The default value is `100`. module('_M.textadept.editing')]] @@ -43,7 +46,9 @@ 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. +-- typically populated by [language-specific modules][]. +-- +-- [language-specific modules]: _M.html#Block.Comment -- @class table -- @name comment_string -- @see block_comment @@ -52,9 +57,10 @@ 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. This --- table can be populated by language-specific modules. The defaults are '()', --- '[]', '{}', '''', and '""'. +-- 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. -- @class table -- @name char_matches -- @usage _M.textadept.editing.char_matches.hypertext = { ..., [60] = '>' } @@ -63,9 +69,10 @@ M.char_matches = { [40] = ')', [91] = ']', [123] = '}', [39] = "'", [34] = '"' } --- -- Highlighted brace characters. --- Keys are lexer language names and values are tables of characters that count --- as brace characters. This table can be populated by language-specific --- modules. The defaults are '(', ')', '[', ']', '{', and '}'. +-- 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. -- @class table -- @name braces -- @usage _M.textadept.editing.braces.hypertext = { ..., [60] = 1, [62] = 1 } @@ -204,10 +211,15 @@ end --- -- Pops up an autocompletion list for the current word based on other words in -- the document. --- @param word_chars String of chars considered to be part of words. +-- @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. -- @param default_words Optional list of words considered to be in the document, --- even if they are not. Words may contain registered images. +-- even if they are not. Words may contain [registered images][]. +-- +-- [registered images]: buffer.html#register_image -- @return `true` if there were completions to show; `false` otherwise. +-- @usage _M.textadept.editing.autocomplete_word('%w_') -- @name autocomplete_word function M.autocomplete_word(word_chars, default_words) local buffer = buffer @@ -326,7 +338,9 @@ end --- -- Joins the currently selected lines. --- If no lines are selected, joins the current line with the line below. +-- 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. -- @name join_lines function M.join_lines() local buffer = buffer @@ -368,8 +382,9 @@ function M.select_enclosed(left, right) end --- --- Grows the selection by a character amount on either end. --- @param amount The amount to grow the selection on either end. +-- Grows the selection by the given number of characters on either end. +-- @param amount The number of characters to grow the selection by on either +-- end. -- @name grow_selection function M.grow_selection(amount) local buffer = buffer @@ -383,6 +398,7 @@ end --- -- Selects the current word under the caret. +-- @see buffer.word_chars -- @name select_word function M.select_word() local buffer = buffer @@ -400,7 +416,7 @@ end --- -- Selects the current paragraph. --- Paragraphs are delimited by two or more consecutive newlines. +-- Paragraphs are surrounded by one or more blank lines. -- @name select_paragraph function M.select_paragraph() buffer:para_up() @@ -410,10 +426,10 @@ end --- -- Selects indented 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 to the --- top and bottom of it are one indentation level lower, they are added to the --- selection. In all other cases, the behavior is the same as if no text is --- selected. +-- 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 +-- added to the selection. In all other cases, the behavior is the same as if no +-- text is selected. -- @name select_indented_block function M.select_indented_block() local buffer = buffer @@ -434,6 +450,9 @@ 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. +-- @see buffer.use_tabs -- @name convert_indentation function M.convert_indentation() local buffer = buffer @@ -473,8 +492,9 @@ events_connect(events.KEYPRESS, function(code) end) --- --- Highlights all occurances of the word under the caret and adds markers to the --- lines they are on. +-- Highlights all occurances of either 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() clear_highlighted_words() diff --git a/modules/textadept/filter_through.lua b/modules/textadept/filter_through.lua index 0e6a0fc0..e31de61f 100644 --- a/modules/textadept/filter_through.lua +++ b/modules/textadept/filter_through.lua @@ -4,7 +4,7 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Filter-Through for the textadept module. +-- Filters text through shell commands. module('_M.textadept.filter_through')]] local cat = not WIN32 and 'cat' or 'type' @@ -12,7 +12,7 @@ local tmpfile = _USERHOME..'/.ft' local filter_through_active = false --- --- Prompts for a Linux, Mac OSX, or Windows shell command to filter text +-- 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: -- diff --git a/modules/textadept/find.lua b/modules/textadept/find.lua index 3bd90597..279a7adb 100644 --- a/modules/textadept/find.lua +++ b/modules/textadept/find.lua @@ -4,7 +4,7 @@ local find = gui.find --[[ This comment is for LuaDoc. --- --- Textadept's integrated find/replace dialog. +-- Textadept's Find & Replace pane. -- @field find_entry_text (string) -- The text in the find entry. -- @field replace_entry_text (string) @@ -75,10 +75,12 @@ local escapes = { } --- --- Performs a find in files with the given directory. --- Use the `gui.find` fields to set the text to find and option flags. --- @param utf8_dir UTF-8 encoded directory name. If none is provided, the user --- is prompted for one. +-- Searches the given 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. -- @name find_in_files function find.find_in_files(utf8_dir) if not utf8_dir then @@ -219,9 +221,10 @@ local function find_incremental(text) end --- --- Begins an incremental find using the Lua command entry. --- Lua command functionality will be unavailable until the search is finished --- (pressing 'Escape' by default). +-- Begins an incremental find using the command entry. +-- Only the `match_case` find option is recognized. Normal command entry +-- functionality will be unavailable until the search is finished by pressing +-- `Esc` (`⎋` on Mac OSX | `Esc` in ncurses). -- @name find_incremental function find.find_incremental() find.incremental, find.incremental_start = true, buffer.current_pos @@ -373,8 +376,8 @@ end events_connect(events.DOUBLE_CLICK, goto_file) --- --- Goes to the next or previous file found relative to the file --- on the current line. +-- 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. -- @name goto_file_in_list function find.goto_file_in_list(next) @@ -412,31 +415,31 @@ end) --[[ The functions below are Lua C functions. --- --- Displays and focuses the find/replace dialog. +-- Displays and focuses the Find & Replace pane. -- @class function -- @name focus local focus --- --- Mimicks a press of the 'Find Next' button in the Find box. +-- Mimicks a press of the 'Find Next' button. -- @class function -- @name find_next local find_next --- --- Mimicks a press of the 'Find Prev' button in the Find box. +-- Mimicks a press of the 'Find Prev' button. -- @class function -- @name find_prev local find_prev --- --- Mimicks a press of the 'Replace' button in the Find box. +-- Mimicks a press of the 'Replace' button. -- @class function -- @name replace local replace --- --- Mimicks a press of the 'Replace All' button in the Find box. +-- Mimicks a press of 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 6ec061e0..c5d632ec 100644 --- a/modules/textadept/keys.lua +++ b/modules/textadept/keys.lua @@ -6,7 +6,186 @@ local M = {} --- -- 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 module should be `require`d last, but before `_M.textadept.menu`. +-- +-- ## Key Bindings +-- +-- Linux / Win32 | Mac OSX | Terminal | Command +-- --------------|---------|----------|-------- +-- **File** | | | +-- Ctrl+N |⌘N |M-^N |New file +-- Ctrl+O |⌘O |^O |Open file +-- Ctrl+Alt+O |^⌘O |M-^O |Open recent file... +-- Ctrl+Shift+O |⌘⇧O |M-O |Reload file +-- Ctrl+S |⌘S |^S |Save file +-- Ctrl+Shift+S |⌘⇧S |M-^S |Save file as.. +-- Ctrl+W |⌘W |^W |Close file +-- Ctrl+Shift+W |⌘⇧W |M-^W |Close all files +-- None |None |None |Load session... +-- None |None |None |Load session... +-- Ctrl+Q |⌘Q |^Q |Quit +-- **Edit** | | | +-- Ctrl+Z
Alt+Backspace|⌘Z |^Z |Undo +-- Ctrl+Y
Ctrl+Shift+Z |⌘⇧Z |^Y |Redo +-- Ctrl+X
Shift+Del |⌘X
⇧⌦|^X |Cut +-- Ctrl+C
Ctrl+Ins |⌘C |^C |Copy +-- Ctrl+V
Shift+Ins |⌘V |^V |Paste +-- Ctrl+D |⌘D |None |Duplicate line +-- Del |⌦
^D |Del
^D |Delete +-- Alt+Del |^⌦ |M-Del
M-D|Delete word +-- Ctrl+A |⌘A |M-A |Select all +-- Ctrl+M |^M |M-M |Match brace +-- Ctrl+Enter |^⎋ |M-Enter |Complete word +-- Ctrl+Alt+Shift+H |⌘⇧H |None |Highlight word +-- Ctrl+/ |^/ |M-/ |Toggle block comment +-- Ctrl+T |^T |^T |Transpose characters +-- Ctrl+Shift+J |^J |M-J |Join lines +-- Ctrl+Shift+M |^⇧M |M-S-M |Select to matching brace +-- Ctrl+< |⌘< |M-< |Select between XML tags +-- Ctrl+> |⌘> |None |Select in XML tag +-- Ctrl+" |⌘" |M-" |Select in double quotes +-- Ctrl+' |⌘' |M-' |Select in single quotes +-- Ctrl+( |⌘( |M-( |Select in parentheses +-- Ctrl+[ |⌘[ |M-[ |Select in brackets +-- Ctrl+{ |⌘{ |M-{ |Select in braces +-- Ctrl+Shift+D |⌘⇧D |M-S-W |Select word +-- Ctrl+Shift+N |⌘⇧N |M-S-N |Select line +-- Ctrl+Shift+P |⌘⇧P |M-S-P |Select paragraph +-- Ctrl+Shift+I |⌘⇧I |M-S-I |Select indented block +-- Ctrl+Alt+U |^U |M-^U |Upper case selection +-- Ctrl+Alt+Shift+U |^⇧U |M-^L |Lower case selection +-- Alt+< |^< |M-> |Enclose as XML tags +-- Alt+> |^> |None |Enclose as single XML tag +-- Alt+" |^" |None |Enclose in double quotes +-- Alt+' |^' |None |Enclose in single quotes +-- Alt+( |^( |M-) |Enclose in parentheses +-- Alt+[ |^[ |M-] |Enclose in brackets +-- Alt+{ |^{ |M-} |Enclose in braces +-- Ctrl++ |⌘+ |M-+ |Grow selection bounds by 1 +-- Ctrl+\_ |⌘\_ |M-\_ |Shrink selection bounds by 1 +-- Ctrl+Shift+Up |^⇧⇡ |S-^Up |Move selected lines up +-- Ctrl+Shift+Down |^⇧⇣ |S-^Down |Move selected lines down +-- **Search** | | | +-- Ctrl+F |⌘F |M-F
M-S-F|Find +-- Ctrl+G
F3 |⌘G |M-G |Find next +-- Ctrl+Shift+G
Shift+F3|⌘⇧G |M-S-G |Find previous +-- Ctrl+Alt+R |^R |M-R |Replace +-- Ctrl+Alt+Shift+R |^⇧R |M-S-R |Replace all +-- Ctrl+Alt+F |^⌘F |M-^F |Find incremental +-- Ctrl+Shift+F |⌘⇧F |None |Find in files +-- Ctrl+Alt+G |^⌘G |None |Goto next file found +-- Ctrl+Alt+Shift+G |^⌘⇧G|None |Goto previous file found +-- Ctrl+J |⌘J |^J |Jump to line +-- **Tools** | | | +-- Ctrl+E |⌘E |M-C |Command entry +-- Ctrl+Shift+E |⌘⇧E |M-S-C |Select command +-- Ctrl+R |⌘R |^R |Run +-- Ctrl+Shift+R |⌘⇧R |M-^R |Compile +-- Ctrl+| |⌘||^\ |Filter text through +-- Ctrl+Space |⌥⎋ |^Space |Complete symbol +-- Ctrl+H |^H |M-H
M-S-H|Show documentation +-- Tab |⇥ |Tab |Expand snippet or next placeholder +-- Ctrl+K |⌥⇥ |M-K |Insert snippet... +-- Shift+Tab |⇧⇥ |S-Tab |Previous snippet placeholder +-- Ctrl+Shift+K |⌥⇧⇥ |M-S-K |Cancel snippet +-- Ctrl+F2 |⌘F2 |None |Toggle bookmark +-- Ctrl+Shift+F2 |⌘⇧F2 |None |Clear bookmarks +-- F2 |F2 |None |Next bookmark +-- Shift+F2 |⇧F2 |None |Previous bookmark +-- Alt+F2 |⌥F2 |None |Goto bookmark... +-- Ctrl+U |⌘U |^U |Snapopen `_USERHOME` +-- None |None |None |Snapopen `_HOME` +-- Ctrl+Alt+Shift+O|^⌘⇧O |M-S-O |Snapopen current directory +-- Ctrl+I |⌘I |None |Show style +-- **Buffer** | | | +-- Ctrl+Tab |^⇥ |M-N |Next buffer +-- Ctrl+Shift+Tab |^⇧⇥ |M-P |Previous buffer +-- Ctrl+B |⌘B |M-B
M-S-B|Switch to buffer... +-- None |None |None |Tab width: 2 +-- None |None |None |Tab width: 3 +-- None |None |None |Tab width: 4 +-- None |None |None |Tab width: 8 +-- Ctrl+Alt+Shift+T|^⇧T |M-T
M-S-T|Toggle use tabs +-- Ctrl+Alt+I |^I |M-I |Convert indentation +-- None |None |None |`CRLF` EOL mode +-- None |None |None |`CR` EOL mode +-- None |None |None |`LF` EOL mode +-- None |None |None |`UTF-8` encoding +-- None |None |None |`ASCII` encoding +-- None |None |None |`ISO-8859-1` encoding +-- None |None |None |`UTF-16` encoding +-- Ctrl+Shift+L |⌘⇧L |M-S-L |Select lexer... +-- F5 |F5 |^L
F5 |Refresh syntax highlighting +-- **View** | | | +-- Ctrl+Alt+N |^⌥⇥ |N/A |Next view +-- Ctrl+Alt+P |^⌥⇧⇥ |N/A |Previous view +-- Ctrl+Alt+S
Ctrl+Alt+H|^S |N/A |Split view horizontal +-- Ctrl+Alt+V |^V |N/A |Split view vertical +-- Ctrl+Alt+W |^W |N/A |Unsplit view +-- Ctrl+Alt+Shift+W |^⇧W |N/A |Unsplit all views +-- Ctrl+Alt++
Ctrl+Alt+=|^+
^=|N/A |Grow view +-- Ctrl+Alt+- |^- |N/A |Shrink view +-- None |None |None |Toggle current fold +-- Ctrl+Alt+Enter |^↩ |None |Toggle view EOL +-- Ctrl+Alt+\\ |^\\ |None |Toggle wrap mode +-- Ctrl+Alt+Shift+I |^⇧I |N/A |Toggle show indent guides +-- Ctrl+Alt+Shift+S |^⇧S |None |Toggle view whitespace +-- Ctrl+Alt+Shift+V |^⇧V |None |Toggle virtual space +-- Ctrl+= |⌘= |N/A |Zoom in +-- Ctrl+- |⌘- |N/A |Zoom out +-- Ctrl+0 |⌘0 |N/A |Reset zoom +-- Ctrl+Shift+T |⌘⇧T |None |Select theme... +-- **Help**| | | +-- F1 |F1 |None|Open manual +-- Shift+F1|⇧F1 |None|Open LuaDoc +-- None |None|None|About +-- **Movement** | | | +-- Down |⇣
^N |^N
Down |Line down +-- Shift+Down |⇧⇣
^⇧N |S-Down |Line down extend selection +-- Ctrl+Down |^⇣ |^Down |Scroll line down +-- Alt+Shift+Down |⌥⇧⇣ |M-S-Down |Line down extend rect. selection +-- Up |⇡
^P |^P
Up |Line up +-- Shift+Up |⇧⇡
^⇧P |S-Up |Line up extend selection +-- Ctrl+Up |^⇡ |^Up |Scroll line up +-- Alt+Shift+Up |⌥⇧⇡ |M-S-Up |Line up extend rect. selection +-- Left |⇠
^B |^B
Left |Char left +-- Shift+Left |⇧⇠
^⇧B |S-Left |Char left extend selection +-- Ctrl+Left |^⇠
^⌘B |^Left |Word left +-- Ctrl+Shift+Left |^⇧⇠
^⌘⇧B|S-^Left |Word left extend selection +-- Alt+Shift+Left |⌥⇧⇠ |M-S-Left |Char left extend rect. selection +-- Right |⇢
^F |^F
Right|Char right +-- Shift+Right |⇧⇢
^⇧F |S-Right |Char right extend selection +-- Ctrl+Right |^⇢
^⌘F |^Right |Word right +-- Ctrl+Shift+Right|^⇧⇢
^⌘⇧F|S-^Right |Word right extend selection +-- Alt+Shift+Right |⌥⇧⇢ |M-S-Right |Char right extend rect. selection +-- Home |⌘⇠
^A |^A
Home |Line start +-- Shift+Home |⌘⇧⇠
^⇧A |M-S-A |Line start extend selection +-- Ctrl+Home |⌘⇡
⌘↖ |M-^A |Document start +-- Ctrl+Shift+Home |⌘⇧⇡
⌘⇧↖ |None |Document start extend selection +-- Alt+Shift+Home |⌥⇧↖ |None |Line start extend rect. selection +-- End |⌘⇢
^E |^E
End |Line end +-- Shift+End |⌘⇧⇢
^⇧E |M-S-E |Line end extend selection +-- Ctrl+End |⌘⇣
⌘↘ |M-^E |Document end +-- Ctrl+Shift+End |⌘⇧⇣
⌘⇧↘ |None |Document end extend selection +-- Alt+Shift+End |⌥⇧↘ |None |Line end extend rect. selection +-- PgUp |⇞ |PgUp |Page up +-- Shift+PgUp |⇧⇞ |M-S-U |Page up extend selection +-- Alt+Shift+PgUp |⌥⇧⇞ |None |Page up extend rect. selection +-- PgDn |⇟ |PgDn |Page down +-- Shift+PgDn |⇧⇟ |M-S-D |Page down extend selection +-- Alt+Shift+PgDn |⌥⇧⇟ |None |Page down extend rect. selection +-- Ctrl+Del |⌘⌦ |^Del |Delete word right +-- Ctrl+Shift+Del |⌘⇧⌦ |S-^Del |Delete line right +-- Ins |Ins |Ins |Toggle overtype +-- Bksp |⌫
⇧⌫ |^H
Bksp |Delete back +-- Ctrl+Bksp |⌘⌫ |None |Delete word left +-- Ctrl+Shift+Bksp |⌘⇧⌫ |None |Delete line left +-- Tab |⇥ |Tab |Insert tab or indent +-- Shift+Tab |⇧⇥ |S-Tab |Dedent +-- None |^K |^K |Cut to line end +-- None |^L |None |Center line vertically +-- **Other** | | | +-- Ctrl+Shift+U, xxxx, Enter|None|None|Input Unicode character U-xxxx. module('_M.textadept.keys')]] -- Utility functions. diff --git a/modules/textadept/menu.lua b/modules/textadept/menu.lua index e45992f3..234ad62e 100644 --- a/modules/textadept/menu.lua +++ b/modules/textadept/menu.lua @@ -10,8 +10,8 @@ local M = {} -- looks up defined key commands to show them in menus. module('_M.textadept.menu')]] --- Get a string uniquely identifying a key command. --- This is used to match menu items with key commands to show the key shortcut. +-- Get a string uniquely identifying a key binding. +-- This is used to match menu items with key bindings to show the key shortcut. -- @param f A value in the `keys` table. local function get_id(f) local id = '' @@ -31,6 +31,7 @@ local SEPARATOR, c = { '' }, _SCINTILLA.constants --- -- Contains the main menubar. +-- @see set_menubar -- @class table -- @name menubar M.menubar = { @@ -224,6 +225,7 @@ M.menubar = { --- -- Contains the default right-click context menu. +-- @see set_contextmenu -- @class table -- @name context_menu M.context_menu = { @@ -243,10 +245,10 @@ local menu_actions, contextmenu_actions = {}, {} -- Creates a menu suitable for `gui.menu()` from the menu table format. -- Also assigns key commands. --- @param menu The menu to create a GTK menu from. +-- @param menu The menu to create a GTK+ menu from. -- @param contextmenu Flag indicating whether or not the menu is a context menu. -- If so, menu_id offset is 1000. The default value is `false`. --- @return GTK menu that can be passed to `gui.menu()`. +-- @return GTK+ menu that can be passed to `gui.menu()`. -- @see gui.menu local function read_menu_table(menu, contextmenu) local gtkmenu = {} @@ -271,7 +273,7 @@ end local items, commands --- Builds the item and commands tables for the filteredlist dialog. +-- Builds the item and commands tables for the filtered list dialog. -- @param menu The menu to read from. -- @param title The title of the menu. -- @param items The current list of items. @@ -292,9 +294,13 @@ end --- -- Sets `gui.menubar` from the given table of menus. --- @param menubar The table of menus to create the menubar from. +-- @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. +-- @see gui.menubar -- @see gui.menu --- @see rebuild_command_tables -- @name set_menubar function M.set_menubar(menubar) key_shortcuts = {} @@ -313,9 +319,13 @@ 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. Each table --- entry is either a submenu or menu text and a function or action table. --- @see set_menubar +-- @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. +-- @see gui.context_menu +-- @see gui.menu -- @name set_contextmenu function M.set_contextmenu(menu_table) contextmenu_actions = {} @@ -325,7 +335,7 @@ if not NCURSES then M.set_contextmenu(M.context_menu) end local columns = { _L['Command'], _L['Key Command'] } --- --- Prompts the user with a filteredlist to run menu commands. +-- Prompts the user with a filtered list dialog to run menu commands. -- @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 00791efd..0d8a869c 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-specific settings. +-- Handles file type detection. -- -- ## Mime-type Events -- -- * `_G.events.LANGUAGE_MODULE_LOADED` --- Called when loading a language-specific module. --- This is useful for overriding its key commands since they are not available --- when Textadept starts. +-- 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. module('_M.textadept.mime_types')]] @@ -21,19 +21,25 @@ local events, events_connect = events, events.connect events.LANGUAGE_MODULE_LOADED = 'language_module_loaded' --- --- File extensions with their associated lexers. +-- Table of file extensions with 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 -- @name extensions M.extensions = {} --- --- Shebang words and their associated lexers. +-- Table of shebang words and 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 -- @name shebangs M.shebangs = {} --- --- First-line patterns and their associated lexers. +-- Table of first-line patterns and 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 -- @name patterns M.patterns = {} @@ -91,6 +97,7 @@ table.sort(M.lexers) --- -- Prompts the user to select a lexer from a filtered list for the current -- buffer. +-- @see buffer.set_lexer -- @name select_lexer function M.select_lexer() local lexer = gui.filteredlist(_L['Select Lexer'], _L['Name'], M.lexers) diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua index f2afd14d..56fb06c1 100644 --- a/modules/textadept/run.lua +++ b/modules/textadept/run.lua @@ -4,28 +4,26 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Module for running/executing source files. --- Typically, language-specific modules populate the `compile_command`, +-- Compile and run/execute source files with Textadept. +-- Typically, [language-specific modules][] populate the `compile_command`, -- `run_command`, and `error_detail` tables for a particular language's file -- extension. -- +-- [language-specific modules]: _M.html#Compile.and.Run +-- -- ## Run Events -- -- * `_G.events.COMPILE_OUTPUT` -- Called after a compile command is executed. --- When connecting to this event (typically from a language-specific module), --- connect with an index of `1` and return `true` if the event was handled and --- you want to override the default handler that prints the output to a new --- view. +-- 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. -- * `_G.events.RUN_OUTPUT` -- Called after a run command is executed. --- When connecting to this event (typically from a language-specific module), --- connect with an index of `1` and return `true` if the event was handled and --- you want to override the default handler that prints the output to a new --- view. +-- 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. @@ -38,7 +36,8 @@ events.COMPILE_OUTPUT, events.RUN_OUTPUT = 'compile_output', 'run_output' local preferred_view --- --- Executes the command line parameter and prints the output to Textadept. +-- Executes the command line parameter. +-- Emits a `COMPILE_OUTPUT` or `RUN_OUTPUT` event based on the `compiling` flag. -- @param command The command line string. -- It can have the following macros: -- + `%(filepath)`: The full path of the current file. @@ -125,64 +124,74 @@ local function print_output(lexer, output) end --- --- File extensions and their associated 'compile' actions. +-- 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. --- This table is typically populated by language-specific modules. +-- This table is typically populated by [language-specific modules][]. +-- +-- [language-specific modules]: _M.html#Compile.and.Run -- @class table -- @name compile_command M.compile_command = {} --- --- Compiles the file as specified by its extension in the `compile_command` --- table. +-- Compiles the file based on its extension using the command from the +-- `compile_command` table. -- @see compile_command -- @name compile function M.compile() command(M.compile_command, true) end events_connect(events.COMPILE_OUTPUT, print_output) --- --- File extensions and their associated 'go' actions. +-- 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. --- This table is typically populated by language-specific modules. +-- This table is typically populated by [language-specific modules][]. +-- +-- [language-specific modules]: _M.html#Compile.and.Run -- @class table -- @name run_command M.run_command = {} --- --- Runs/executes the file as specified by its extension in the `run_command` --- table. +-- Runs/executes the file based on its extension using the command from the +-- `run_command` table. -- @see run_command -- @name run function M.run() command(M.run_command) end events_connect(events.RUN_OUTPUT, print_output) --- --- A table of error string details. --- Each entry is a table with the following fields: +-- 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: -- --- + `pattern`: The Lua pattern that matches a specific error string. +-- + `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 --- error's message. A call tip will be displayed if a message was captured. +-- + `message`: (Optional) The index of the Lua capture that contains the +-- error's message. An annotation will be displayed if a message was +-- captured. -- -- When an error message is double-clicked, the user is taken to the point of -- error. --- This table is usually populated by language-specific modules. +-- This table is usually populated by [language-specific modules][]. +-- +-- [language-specific modules]: _M.html#Compile.and.Run -- @class table -- @name error_detail M.error_detail = {} --- --- Goes to the line in the file an error occured at and displays a calltip with --- the error message. --- This is typically called when the user double-clicks an error message, +-- 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. +-- 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. --- @param line_num The line the error occurs on. +-- @param line_num The line number the caret is on with the error message. -- @see error_detail function goto_error(pos, line_num) if buffer._type ~= _L['[Message Buffer]'] and diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua index cee879c4..24554e35 100644 --- a/modules/textadept/session.lua +++ b/modules/textadept/session.lua @@ -4,17 +4,23 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Session support for the textadept module. +-- 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`. +-- +-- [`_G.NCURSES`]: _G.html#NCURSES -- @field SAVE_ON_QUIT (bool) -- Save the session when quitting. --- The default value is `true` and can be disabled by passing the command line --- switch `-n` or `--nosession` to Textadept. +-- The default value is `true`, but can be disabled by passing the command +-- line switch `-n` or `--nosession` to Textadept. -- @field MAX_RECENT_FILES (number) --- The maximum number of files from the recent files list to save to the +-- The maximum number of files from [`io.recent_files`][] to save to the -- session. -- The default value is `10`. +-- +-- [`io.recent_files`]: io.html#recent_files module('_M.textadept.session')]] M.DEFAULT_SESSION = _USERHOME..(not NCURSES and '/session' or '/session_term') diff --git a/modules/textadept/snapopen.lua b/modules/textadept/snapopen.lua index fa14941c..c677ba66 100644 --- a/modules/textadept/snapopen.lua +++ b/modules/textadept/snapopen.lua @@ -4,30 +4,13 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Snapopen for the textadept module. --- --- ## Examples --- --- local snapopen = _M.textadept.snapopen.open --- --- -- Show all files in PATHS. --- snapopen() --- --- -- Show all files in the current file's directory. --- snapopen(buffer.filename:match('^(.+)[/\\]'), nil, true) --- --- -- Show all Lua files in PATHS. --- snapopen(nil, '!%.lua$') --- --- -- Ignore the project's 'images' folder and HTML pages. --- snapopen('/path/to/project', { --- folders = { 'images' }, --- extensions = { 'html' } --- }, true) +-- Quickly open files in a set of directories using a filtered list dialog. -- @field DEFAULT_DEPTH (number) --- Maximum directory depth to search. The default value is `99`. +-- Maximum directory depth to search. +-- The default value is `99`. -- @field MAX (number) --- Maximum number of files to list. The default value is `1000`. +-- Maximum number of files to list. +-- The default value is `1000`. module('_M.textadept.snapopen')]] --- @@ -37,6 +20,7 @@ module('_M.textadept.snapopen')]] M.PATHS = {} --- -- Default file and directory filters. +-- Contains common binary file extensions and version control folders. -- @class table -- @name FILTER M.FILTER = { @@ -97,15 +81,16 @@ local function add_directory(utf8_dir, list, depth, filter) end --- --- Quickly open a file in set of directories. +-- Quickly open files in set of directories using a filtered list dialog. +-- The number of files in the list is capped at `MAX`. -- @param utf8_paths A UTF-8 string directory path or table of UTF-8 directory -- paths to search. -- @param filter A filter for files and folders to exclude. The filter may be -- a string or table. Each filter is a Lua pattern. Any files matching a -- filter are excluded. Prefix a pattern with `!` to exclude any files that --- do not match the filter. File extensions can be more efficiently excluded --- by adding the extension text to a table assigned to an `extensions` key in --- the filter table instead of using individual filters. Directories can be +-- do not match a filter. File extensions can be more efficiently excluded by +-- adding the extension text to a table assigned to an `extensions` key in the +-- filter table instead of using individual filters. Directories can be -- excluded by adding filters to a table assigned to a `folders` key in the -- filter table. All strings should be UTF-8 encoded. -- @param exclude_PATHS Flag indicating whether or not to exclude `PATHS` in the @@ -115,10 +100,17 @@ end -- The default value is `false`. -- @param depth Number of directories to recurse into for finding files. -- The default value is `DEFAULT_DEPTH`. --- @usage _M.textadept.snapopen.open() +-- @usage _M.textadept.snapopen.open() -- list all files in PATHS -- @usage _M.textadept.snapopen.open(buffer.filename:match('^.+/'), nil, true) --- @usage _M.textadept.snapopen.open(nil, '!%.lua$') --- @usage _M.textadept.snapopen.open(nil, { folders = { '%.hg' } }) +-- -- list all files in the current file's directory +-- @usage _M.textadept.snapopen.open(nil, '!%.lua$') -- list all Lua files in +-- PATHS +-- @usage _M.textadept.snapopen.open('/project', { folders = { 'secret' } }, +-- true) -- list all project files except those in a secret folder +-- @see PATHS +-- @see FILTER +-- @see DEFAULT_DEPTH +-- @see MAX -- @name open function M.open(utf8_paths, filter, exclude_PATHS, exclude_FILTER, depth) -- Convert utf8_paths to a table from nil or string arguments. diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua index 5f08895e..254eb9de 100644 --- a/modules/textadept/snippets.lua +++ b/modules/textadept/snippets.lua @@ -4,117 +4,76 @@ local M = {} --[=[ This comment is for LuaDoc. --- --- Provides Lua-style snippets for Textadept. +-- Snippets for Textadept. -- -- ## Overview -- --- Snippets are dynamic pieces of text inserted into a document that contain --- placeholders for further input, mirror or transform that input, and execute --- code. --- -- Snippets are defined in the global table `snippets`. Each key-value pair in --- `snippets` consists of either: --- --- * A string snippet trigger word and its expanded text. --- * A string lexer language name and its associated `snippets`-like table. --- --- Language names are the names of the lexer files in `lexers/` such as `cpp` --- and `lua`. --- --- By default, the `Tab` key expands a snippet and tabs through placeholders --- while `Shift+Tab` tabs backwards through them. Snippets can also be expanded --- inside one another. --- --- ## Snippet Precedence --- --- When searching for a snippet to expand in the `snippets` table, snippets in --- the current lexer have priority, followed by the ones in the global table. +-- `snippets` consists of either a string trigger word and its snippet text, or +-- a string lexer language (from the `lexers/` directory) with a table of +-- trigger words and snippet texts. When searching for a snippet to insert based +-- on a trigger word, snippets in the current lexer have priority, followed by +-- the ones in the global table. This means if there are two snippets with the +-- same trigger word, the one specific to the current lexer is inserted, not the +-- global one. -- -- ## Snippet Syntax -- --- A snippet to insert may contain any of the following: --- --- ### Plain Text --- --- Any plain text characters may be used with the exception of `%` followed --- immediately by a digit (`0`-`9`), `(`, `)`, `>`, or `]` character. These are --- "escape sequences" for the more complicated features of snippets. If you want --- to use `%` followed by one of the before-mentioned characters, prepend --- another `%` to the first `%`. For example, `%%>` in the snippet inserts a --- literal `%>` into the document. +-- Any plain text characters may be used with the exception of `%`. Just like in +-- Lua patterns, `%` is an escape character. The sequence `%%` stands for a +-- single `%`. Also, it is recommended to use `\t` characters for indentation +-- because they can be converted to spaces based on the current indentation +-- settings. In addition to plain text, snippets can contain placeholders for +-- further user input, can mirror or transform those user inputs, and/or execute +-- arbitrary code. -- -- ### Placeholders -- --- Textadept's snippets provide a number of different placeholders. The simplest --- ones are of the form +-- `%`_`n`_`(`_`text`_`)` sequences are called placeholders, where _`n`_ is an +-- integer and _`text`_ is the default text inserted into the placeholder. +-- Placeholders are visited in numeric order each time [`_insert()`](#_insert) +-- is called with an active snippet. When no more placeholders are left, the +-- caret is placed at the `%0` placeholder (if it exists), or at the end of the +-- snippet. Examples are -- --- %num +-- snippets['foo'] = 'foobar%1(baz)' +-- snippets['bar'] = 'start\n\t%0\nend' -- --- where `num` is a number. Placeholders are visited in numeric order (1, 2, 3, --- etc.) with the `Tab` key after the snippet is inserted and can be used to --- enter in additional text. When no more placeholders are left, the caret is --- placed at either the end of the snippet or the `%0` placeholder if it exists. +-- ### Mirrors -- --- A placeholder can specify default text. It is of the form +-- `%`_`n`_ sequences are called 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 -- --- %num(default text) +-- snippets['foo'] = '%1(mirror), %1, on the wall' +-- snippets['q'] = '"%1"' -- --- where, again, `num` is a number. These kinds of placeholders take precedence --- over the simpler placeholders described above. If a snippet contains more --- than one placeholder with the same `num`, the one containing default text is --- visited first and the others become _mirrors_. Mirrors simply mirror the text --- typed into the current placeholder. +-- ### Transforms -- --- The last kind of placeholder executes either Lua or Shell code. +-- `%`_`n`_`<`_`Lua code`_`>` and `%`_`n`_`[`_`Shell code`_`]` sequences are +-- called transforms, where _`n`_ is an integer, _`Lua code`_ is arbitrary Lua +-- code, and _`Shell code`_ is arbitrary Shell code. The _`n`_ is optional, and +-- for transforms that omit it, their code is executed the moment the snippet is +-- inserted. Otherwise, the code is executed as placeholders are visited. -- --- % --- %num --- %[shell_code] --- %num[shell_code] +-- Lua code is run in Textadept's Lua State with with an additional +-- `selected_text` global variable that contains the current selection in the +-- buffer. The transform is replaced with the return value of the executed code. +-- An example is -- --- For placeholders that omit `num`, their code is executed the moment the --- snippet is inserted. Otherwise the code is executed as placeholders are --- visited. +-- snippets['foo'] = [[ +-- %2<('%1'):gsub('^.', function(c) +-- return c:upper() -- capitalize the word +-- end)>, %1(mirror) on the wall.]] -- --- For Lua code, the global Lua state is available as well as a `selected_text` --- variable (containing the current selection in the buffer). After execution, --- the placeholder contains the return value of the code that was run. +-- Shell code is executed using Lua's [`io.popen()`][]. The transform is +-- replaced with the process' standard output (stdout). An example is -- --- Shell code is executed using Lua's [`io.popen()`][] which reads from the --- process' standard output (STDOUT). After execution, the placeholder will --- contain the STDOUT of the process. +-- snippets['foo'] = '$%1(HOME) = %2[echo $%1]' -- -- [`io.popen()`]: http://www.lua.org/manual/5.2/manual.html#pdf-io.popen --- --- These kinds of placeholders can be used to transform mirrored text. For --- example, `%2<([[%1]]):gsub('^.', function(c) return c:upper() end)>` will --- capitalize a mirrored `%1` placeholder. --- --- #### Important Note --- --- It is very important that any `%`, `(`, `)`, `>`, or `]` characters --- **within** placeholders be escaped with a `%` as necessary. Otherwise, --- unexpected results will occur. `%`s only need to be escaped if they are --- proceeded by a digit, `(`s and `)`s only need to be escaped directly after a --- %num sequence or inside default text placeholders **if and only if** there is --- no matching parenthesis (thus, nested parentheses do not need to be escaped), --- `]`s only need to be escaped inside Shell code placeholders, and `>`s only --- need to be escaped inside Lua code placeholders. --- --- ## Example --- --- snippets.snippet = 'snippets.%1 = \'%0\'' --- snippets.file = '%' --- snippets.lua = { --- f = 'function %1(name)(%2(args))\n\t%0\nend' --- } --- --- The first two snippets are global. The first is quite simple to understand. --- The second runs Lua code to determine the current buffer's filename and --- inserts it. The last snippet expands only when editing Lua code. --- --- It is recommended to use tab characters instead of spaces like in the last --- example. Tabs will be converted to spaces as necessary. module('_M.textadept.snippets')]=] -- The stack of currently running snippets. @@ -171,10 +130,12 @@ local function new_snippet(text, trigger) end --- --- Inserts a snippet. --- @param text Optional snippet text. If none is specified, the snippet text --- is determined from the trigger and lexer. --- @return `false` if no snippet was expanded; `true` otherwise. +-- Inserts a new snippet or goes to the next placeholder of the active snippet. +-- @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. +-- @return `false` if no action was taken; `nil` otherwise. +-- @see buffer.word_chars -- @name _insert function M._insert(text) local buffer = buffer @@ -195,8 +156,8 @@ function M._insert(text) end --- --- Goes back to the previous placeholder, reverting any changes from the current --- one. +-- Goes back to the previous snippet placeholder, reverting any changes from the +-- current one. -- @return `false` if no snippet is active; `nil` otherwise. -- @name _previous function M._previous() @@ -426,7 +387,10 @@ events.connect(events.VIEW_NEW, function() buffer.indic_style[INDIC_SNIPPET] = INDIC_HIDDEN end) --- --- Provides access to snippets from `_G`. +-- Table of snippet triggers with their snippet text. +-- Language-specific snippets are in another table value whose key is the +-- language's lexer name. +-- This table also contains the `_M.textadept.snippets` module. -- @class table -- @name _G.snippets _G.snippets = M -- cgit v1.2.3