From 033416a15fe60fe10387119e0e63bb9ed9e8aedd Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Sat, 25 Jul 2009 23:34:13 -0400 Subject: Documentation overhaul. --- modules/textadept/bookmarks.lua | 21 +++-- modules/textadept/editing.lua | 25 ++++++ modules/textadept/lsnippets.lua | 182 +++++++++++++++++++++++++--------------- modules/textadept/mlines.lua | 28 ++++--- modules/textadept/run.lua | 2 +- modules/textadept/session.lua | 11 ++- 6 files changed, 180 insertions(+), 89 deletions(-) (limited to 'modules') diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua index 3fdca987..a94c56db 100644 --- a/modules/textadept/bookmarks.lua +++ b/modules/textadept/bookmarks.lua @@ -5,15 +5,22 @@ local locale = _G.locale --- -- Bookmarks for the textadept module. --- There are several option variables used: --- MARK_BOOKMARK: The integer mark used to identify a bookmarked line. --- MARK_BOOKMARK_COLOR: The Scintilla color used for a bookmarked line. module('_m.textadept.bookmarks', package.seeall) --- options -local MARK_BOOKMARK = 1 -local MARK_BOOKMARK_COLOR = 0xC08040 --- end options +-- Markdown: +-- ## Settings +-- +-- * `MARK_BOOKMARK`: The unique integer mark used to identify a bookmarked +-- line. +-- * `MARK_BOOKMARK_COLOR`: The [Scintilla color][scintilla_color] used for a +-- bookmarked line. +-- +-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour + +-- settings +MARK_BOOKMARK = 1 +MARK_BOOKMARK_COLOR = 0xC08040 +-- end settings --- -- Adds a bookmark to the current line. diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua index d1d2c4a2..97ac9baa 100644 --- a/modules/textadept/editing.lua +++ b/modules/textadept/editing.lua @@ -7,6 +7,25 @@ local locale = _G.locale -- Editing commands for the textadept module. module('_m.textadept.editing', package.seeall) +-- Markdown: +-- ## Settings +-- +-- * `AUTOPAIR`: Flag indicating whether or not when an opening `(`, `[`, `[`, +-- `"`, or `'` is typed, its closing complement character is automatically +-- inserted. +-- * `HIGHLIGHT_BRACES`: Flag indicating whether or not when the caret is over a +-- brace character (any of the following: `()[]{}<>`), its matching complement +-- brace is highlighted. +-- * `AUTOINDENT`: Flag indicating whether or not when the enter key is pressed, +-- the inserted line has is indented to match the level of indentation of the +-- previous line. + +-- settings +AUTOPAIR = true +HIGHLIGHT_BRACES = true +AUTOINDENT = true +-- end settings + -- The kill-ring. -- @field maxn The maximum size of the kill-ring. local kill_ring = { pos = 1, maxn = 10 } @@ -53,11 +72,14 @@ local comment_strings = { ruby = '#~', } +if AUTOPAIR then textadept.events.add_handler('char_added', function(c) -- matches characters specified in char_matches if char_matches[c] then buffer:insert_text(-1, char_matches[c]) end end) +end +if HIGHLIGHT_BRACES then textadept.events.add_handler('update_ui', function() -- highlights matching braces local buffer = buffer @@ -74,7 +96,9 @@ textadept.events.add_handler('update_ui', buffer:brace_bad_light(-1) end end) +end +if AUTOINDENT then textadept.events.add_handler('char_added', function(char) -- auto-indent on return if char ~= 10 then return end @@ -101,6 +125,7 @@ textadept.events.add_handler('char_added', buffer:set_sel(anchor, caret) end end) +end -- local functions local insert_into_kill_ring, scroll_kill_ring diff --git a/modules/textadept/lsnippets.lua b/modules/textadept/lsnippets.lua index 3d4c73fa..5eeb14e1 100644 --- a/modules/textadept/lsnippets.lua +++ b/modules/textadept/lsnippets.lua @@ -5,80 +5,130 @@ local locale = _G.locale --- -- Provides Lua-centric snippets for Textadept. --- Snippets are basically pieces of text inserted into a document, but can --- execute code, contain placeholders a user can enter in dynamic text for, and --- make transformations on that text. This is much more powerful than standard --- text templating. --- There are several option variables used: --- MARK_SNIPPET: The integer mark used to identify the line that marks the --- end of a snippet. --- MARK_SNIPPET_COLOR: The Scintilla color used for the line --- that marks the end of the snippet. --- module('_m.textadept.lsnippets', package.seeall) --- Usage: --- Snippets are defined in the global table 'snippets'. Keys in that table are --- snippet trigger words, and values are the snippet's text to insert. The --- exceptions are language names and style names. Language names have table --- values of either snippets or style keys with table values of snippets. --- See /lexers/lexer.lua for some default style names. Each lexer's 'add_style' --- function adds additional styles, the string argument being the style's name. --- For example: --- snippets = { --- file = '%(buffer.filename)', --- lua = { --- f = 'function %1(name)(%2(args))\n %0\nend', --- string = { [string-specific snippets here] } +-- Markdown: +-- ## Settings +-- +-- * `MARK_SNIPPET`: The unique integer mark used to identify the line that +-- marks the end of a snippet. +-- * `MARK_SNIPPET_COLOR`: The [Scintilla color][scintilla_color] used for the +-- line that marks the end of the snippet. +-- +-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour +-- +-- ## Overview +-- +-- Snippets are basically pieces of text inserted into a document, but can +-- execute code, contain placeholders you can enter dynamic text for, and +-- perform transformations on that text. This is much more powerful than +-- standard text templating. +-- +-- Snippets are defined in the global table `snippets`. Each key-value pair in +-- `snippets` consist of either: +-- +-- * A string snippet trigger word and its expanded text. +-- * A string language name and its associated `snippets`-like table. +-- * A string style name and its associated `snippets`-like table. +-- +-- Language names are the names of the lexer files in `lexers/` such as `cpp` +-- and `lua`. Style names are different lexer styles, most of which are in +-- `lexers/lexer.lua`; examples are `whitespace`, `comment`, and `string`. +-- +-- ## Snippet Precedence +-- +-- When searching for a snippet to expand in the `snippets` table, snippets in +-- the current style have priority, followed by the ones in the current lexer, +-- and finally the ones in the global table. +-- +-- ## 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 `%` and `. +-- These are special characters and must be "escaped" by prefixing one with a +-- `%`. As an example, `%%` inserts a single `%` in the snippet. +-- +-- #### Lua and Shell Code +-- +-- %(lua_code) +-- `shell_code` +-- +-- The code is executed the moment the snippet is inserted. +-- +-- For Lua code, the global Lua state is available as well as a `selected_text` +-- variable (containing the current selection in the buffer) for convenience. +-- Only the return value of the code execution is inserted, not standard out. +-- Therefore any `print()` statements are meaningless. +-- +-- Shell code is run via Lua's [`io.popen()`][io_popen]. +-- +-- [io_popen]: http://www.lua.org/manual/5.1/manual.html#pdf-io.popen +-- +-- #### Tab Stops and Mirrors +-- +-- %num +-- +-- These are visited in numeric order (1, 2, 3, etc.) with %0 being the final +-- position of the caret, or the end of the snippet if %0 is not specified. If +-- there is a placeholder (described below) with the specified `num`, its text +-- is mirrored here. +-- +-- #### Placeholders +-- +-- %num(text) +-- +-- These are also visited in numeric order, but have precedence over tab stops, +-- and insert the specified `text` at the current position upon entry. `text` +-- can contain Lua code executed at run-time: +-- +-- %num(#(lua_code)) +-- +-- The global Lua state is available as well as a `selected_text` variable +-- (containing the current selection in the buffer) for convenience. +-- +-- `#`'s will have to be escaped with `%` for plain text. Any mis-matched `)`'s +-- must also be escaped, but balanced `()`'s need not be. +-- +-- #### Transformations +-- +-- %num(pattern|replacement) +-- +-- These act like mirrors, but transform the text that would be inserted using +-- a given [Lua pattern][lua_pattern] and replacement. Like in placeholders, +-- `replacement` can contain Lua code executed at run-time as well as the +-- standard Lua capture sequences: `%n` where 1 <= `n` <= 9. +-- +-- [lua_pattern]: http://www.lua.org/manual/5.1/manual.html#5.4.1 +-- +-- Any `|`'s after the first one do not need to be escaped. +-- +-- ## Example +-- +-- snippets = { +-- file = '%(buffer.filename)', +-- lua = { +-- f = 'function %1(name)(%2(args))\n %0\nend', +-- string = { [string-specific snippets here] } +-- } -- } --- } --- Style and lexer insensitive snippets should be placed in the lexer and --- snippets tables respectively. --- --- When searching for a snippet to expand in the snippets table, snippets in the --- current style have priority, then the ones in the current lexer, and finally --- the ones in the global table. --- --- As mentioned, snippets are key-value pairs, the key being the trigger word --- and the value being the snippet text: ['trigger'] = 'text'. --- Snippet text however can contain more than just text. --- --- Insert-time Lua and shell code: %(lua_code), `shell_code` --- The code is executed the moment the snippet is inserted. For Lua code, the --- result of the code execution is inserted, so print statements are useless. --- All global variables and a 'selected_text' variable are available. --- --- Tab stops/Mirrors: %num --- These are visited in numeric order with %0 being the final position of the --- caret, the end of the snippet if not specified. If there is a placeholder --- (described below) with the specified num, its text is mirrored here. --- --- Placeholders: %num(text) --- These are also visited in numeric order, having precedence over tab stops, --- and inserting the specified text. If no placeholder is available, the tab --- stop is visited instead. The specified text can contain Lua code executed --- at run-time: #(lua_code). --- --- Transformations: %num(pattern|replacement) --- These act like mirrors, but transform the text that would be inserted using --- a given Lua pattern and replacement. The replacement can contain Lua code --- executed at run-time: #(lua_code), as well as the standard Lua capture --- sequences: %n where 1 <= n <= 9. --- See the Lua documentation for using patterns and replacements. --- --- To escape any of the special characters '%', '`', ')', '|', or '#', prepend --- the standard Lua escape character '%'. Note: --- * Only '`' needs to be escaped in shell code. --- * '|'s after the first in transformations do not need to be escaped. --- * Only unmatched ')'s need to be escaped. Nested ()s are ignored. +-- +-- The first snippet is global and runs the Lua code to determine the current +-- buffer's filename and inserts it. The other snippets apply only in the `lua` +-- lexer. Any snippets in the `string` table are available only when the current +-- style is `string` in the `lua` lexer. -local MARK_SNIPPET = 4 -local MARK_SNIPPET_COLOR = 0x4D9999 +-- settings +MARK_SNIPPET = 4 +MARK_SNIPPET_COLOR = 0x4D9999 +-- end settings --- -- Global container that holds all snippet definitions. -- @class table --- @name snippets +-- @name _G.snippets _G.snippets = {} _G.snippets.file = "%(buffer.filename)" diff --git a/modules/textadept/mlines.lua b/modules/textadept/mlines.lua index daddf4b5..6d4d866b 100644 --- a/modules/textadept/mlines.lua +++ b/modules/textadept/mlines.lua @@ -5,21 +5,25 @@ local locale = _G.locale --- -- Multiple line editing for the textadept module. --- There are several option variables used: --- MARK_MLINE: The integer mark used to identify an MLine marked line. --- MARK_MLINE_COLOR: The Scintilla color used for an MLine marked line. module('_m.textadept.mlines', package.seeall) --- options -local MARK_MLINE = 2 -local MARK_MLINE_COLOR = 0x4D994D --- end options +-- Markdown: +-- ## Settings +-- +-- * `MARK_MLINE`: The unique integer mark used to identify an MLine marked +-- line. +-- * `MARK_MLINE_COLOR`: The [Scintilla color][scintilla_color] used for an +-- MLine marked line. +-- +-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour ---- --- [Local table] Contains all MLine marked lines with the column index to edit --- with respect to for each specific line. --- @class table --- @name mlines +-- settings +MARK_MLINE = 2 +MARK_MLINE_COLOR = 0x4D994D +-- end settings + +-- Contains all MLine marked lines with the column index to edit with respect to +-- for each specific line. local mlines = {} local mlines_most_recent diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua index d6fa0a24..fcdb6a43 100644 --- a/modules/textadept/run.lua +++ b/modules/textadept/run.lua @@ -20,7 +20,7 @@ function execute(command) local filedir, filename = filepath:match('^(.+[/\\])([^/\\]+)$') local filename_noext = filename:match('^(.+)%.') command = command:gsub('%%%b()', { - ['%(filepath)'] = filepath, _CHARSET, 'UTF-8', + ['%(filepath)'] = filepath, ['%(filedir)'] = filedir, ['%(filename)'] = filename, ['%(filename_noext)'] = filename_noext, diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua index a464da68..ba98a728 100644 --- a/modules/textadept/session.lua +++ b/modules/textadept/session.lua @@ -5,11 +5,16 @@ local locale = _G.locale --- -- Session support for the textadept module. --- There are several option variables used: --- DEFAULT_SESSION: The path to the default session file. module('_m.textadept.session', package.seeall) -local DEFAULT_SESSION = _USERHOME..'/session' +-- Markdown: +-- ## Settings +-- +-- * `DEFAULT_SESSION`: The path to the default session file. + +-- settings +DEFAULT_SESSION = _USERHOME..'/session' +-- end settings --- -- Loads a Textadept session file. -- cgit v1.2.3