diff options
| author |  mitchell <70453897+667e-11@users.noreply.github.com> | 2012-09-12 11:24:11 -0400 |
|---|---|---|
| committer | mitchell <70453897+667e-11@users.noreply.github.com> | 2012-09-12 11:24:11 -0400 |
| commit | 9dc8ce16a1efc6482db6f1d5456d42958e79a06c (patch) | |
| tree | e26ff636143fc74f92a6a3359a73e93194da6bc3 | |
| parent | 4305f32ac153b7a45a1c001da2fcd412af905168 (diff) | |
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.
53 files changed, 2446 insertions, 2066 deletions
@@ -11,7 +11,7 @@ library versions installed vary widely from distribution to distribution. For example, `libpng14` has been available for many distributions since late 2009 while the latest 2012 Ubuntu still uses `libpng12`. Unfortunately in these cases, the best idea is to compile Textadept. This process is actually very -simple though. See the [compiling][] page. Only the GTK development libraries +simple though. See the [compiling][] page. Only the GTK+ development libraries are needed for the GUI version. (The ncurses development library is required for the terminal version.) @@ -5,8 +5,8 @@ Textadept is a fast, minimalist, and ridiculously extensible cross-platform text editor for programmers. Written in a combination of C and [Lua][] and relentlessly optimized for speed and minimalism over the years, Textadept is an -ideal editor for programmers who want endless extensibility options without -sacrificing speed or succumbing to code bloat and featuritis. +ideal editor for programmers who want endless extensibility without sacrificing +speed or succumbing to code bloat and featuritis. [Lua]: http://lua.org @@ -23,8 +23,8 @@ sacrificing speed or succumbing to code bloat and featuritis. ## Requirements In its bid for minimalism, Textadept has no dependencies on Windows and Mac OSX -operating systems and depends only on [GTK+ 2.0][] version 2.16 or greater on -Linux. Lua is pre-compiled into Textadept on all platforms and a GTK runtime is +operating systems and depends only on [GTK+ 2.0][] version 2.18 or greater on +Linux. Lua is pre-compiled into Textadept on all platforms and a GTK+ runtime is included on Windows and Mac OSX. The _experimental_ version of Textadept for the terminal requires only diff --git a/core/._M.luadoc b/core/._M.luadoc index b73e9000..ea969647 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -6,92 +6,149 @@ --- -- A table of loaded modules. -- --- ## Overview +-- ## Module Guidelines -- --- Note that while language-specific modules can only be used by files of that --- language, they persist in Textadept's Lua state. Because of this, it is not --- recommended to set global functions or variables and depend on them, as they --- may be inadvertantly overwritten. Keep them inside the module. +-- At the very least, modules consist of a single directory with an `init.lua` +-- script. However, the script can load additional Lua files present in the +-- directory. (For an example, see `modules/textadept/init.lua`.) -- --- ## Structure +-- Once modules are loaded, regardless of whether they are generic or +-- language-specific, they persist in Textadept's Lua State; they are never +-- unloaded. Therefore, modules should not set global functions or variables in +-- order to avoid polluting the global environment. All functions and variables +-- should be contained within the module. -- --- Each module should have an `init.lua` that `require`s all submodules it --- needs. For an example, see `modules/textadept/init.lua`. +-- ### Language-Specific -- --- ## Language-Specific Modules +-- To fully take advantage of Textadept's features, language-specific modules +-- should have at a minimum: a block comment string, run and/or compile +-- commands, a buffer property setter function, and if possible, an Adeptsense. +-- Optional features are extra snippets and commands and a context menu. -- --- The following is a list of recommended features for Language-Specific --- modules. They are all entirely optional. +-- #### Block Comment -- --- ### Snippets +-- The `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in ncurses) key binding toggles code +-- comments. In order for this to work for your language, the +-- [`_M.textadept.editing.comment_string`][] table must have a key with the +-- language's lexer name assigned to a comment prefix string. For Lua, it would +-- look like -- --- [Snippets][] for common code constructs. +-- _M.textadept.editing.comment_string.lua = '--' -- --- [Snippets]: _M.textadept.snippets.html +-- [`_M.textadept.editing.comment_string`]: _M.textadept.editing.html#comment_string -- --- ### Commands +-- #### Compile and Run -- --- #### Run +-- The `Ctrl+Shift+R` and `Ctrl+R` (`⌘⇧R` and `⌘R` on Mac OSX | `M-^R` and `^R` +-- in ncurses) key bindings compile and run code, respectively. In order for +-- these to work for your language, the [`_M.textadept.run.compile_command`][] +-- and [`_M.textadept.run.run_command`][] tables must have keys with the +-- language's lexer name assigned to compile and run shell commands, +-- respectively. Commands may contain [macros][]. For Lua, it would look like -- --- If the code can be run by an interpreter or other executable, create a [run --- command][] for it as well as an [error format][] for the ability to jump to --- the position in a file where the error occured. +-- _M.textadept.run.compile_command.lua = 'luac %(filename)' +-- _M.textadept.run.run_command = 'lua %(filename)' -- --- For example: +-- The module should also define error details in +-- [`_M.textadept.run.error_detail`][] so double-clicking on compile or runtime +-- errors will jump to the error's location. The format for Lua errors looks +-- like -- --- _M.textadept.run.run_command.lua = 'lua %(filename)' +-- _M.textadept.run.error_detail.lua = { +-- pattern = '^lua: (.-):(%d+): (.+)$', +-- filename = 1, line = 2, message = 3 +-- } -- --- [run command]: _M.textadept.run.html#run_command --- [error format]: _M.textadept.run.html#error_detail +-- [`_M.textadept.run.compile_command`]: _M.textadept.run.html#compile_command +-- [`_M.textadept.run.run_command`]: _M.textadept.run.html#run_command +-- [macros]: _M.textadept.run.html#execute +-- [`_M.textadept.run.error_detail`]: _M.textadept.run.html#error_detail -- --- #### Compile +-- #### Buffer Properties -- --- If the code can be compiled by an executable, create a [compile command][] --- for it. +-- By default, Textadept uses 2 spaces as indentation. If your language has +-- different indentation guidelines, change them in a `set_buffer_properties()` +-- function. Using tabs of width 8 would look like -- --- For example: +-- function M.set_buffer_properties() +-- buffer.tab_width = 8 +-- buffer.use_tabs = true +-- end -- --- _M.textadept.run.compile_command.lua = 'luac %(filename)' +-- This function is called automatically to set the properties for the +-- language's source files. -- --- [compile command]: _M.textadept.run.html#compile_command +-- #### Adeptsense -- --- #### Block Comment +-- The `Ctrl+Space` and `Ctrl+H` (`⌥⎋` and `^H` on Mac OSX | `^Space` and `M-H` +-- or `M-S-H` in ncurses) key bindings autocomplete symbols and show API +-- documentation, respectively, when editing code. In order for these to work +-- for your language, you must create an [Adeptsense][]. -- --- Create a [comment prefix][] for it so code can be easily commented and --- uncommented. +-- [Adeptsense]: _M.textadept.adeptsense.html -- --- [comment prefix]: _M.textadept.editing.html#comment_string +-- #### Snippets -- --- For example: +-- [Snippets][] for common language constructs can be useful. Some snippets for +-- common Lua control structures look like -- --- _M.textadept.editing.comment_string.lua = '--' --- --- [comment prefix]: _M.textadept.editing.html#comment_string +-- snippets.lua = { +-- f = "function %1(name)(%2(args))\n\t%0\nend", +-- ['for'] = "for i = %1(1), %2(10)%3(, -1) do\n\t%0\nend", +-- fori = "for %1(i), %2(val) in ipairs(%3(table)) do\n\t%0\nend", +-- forp = "for %1(k), %2(v) in pairs(%3(table)) do\n\t%0\nend", +-- } -- --- ### Buffer Properties +-- [Snippets]: _M.textadept.snippets.html -- --- Add a `set_buffer_properties` function with default buffer properties for --- code like tab and indentation settings. +-- #### Commands -- --- For example: +-- Additional editing features for the language can be useful. For example, the +-- [Lua][] module has a feature to autocomplete the `end` keyword in a control +-- structure and the [C/C++][] module has a feature to add a `;` to the end of +-- the current line and insert a new line. Both are bound to the `Shift+Enter` +-- (`⇧↩` on Mac OSX | `S-Enter` in ncurses) key for easy access. -- --- function set_buffer_properties() --- local buffer = buffer --- buffer.use_tabs = false --- buffer.tab_width = 2 --- buffer.indent = 2 +-- function M.try_to_autocomplete_end() +-- ... -- end -- --- ### Context Menu +-- keys.lua = { +-- ['s\n'] = M.try_to_autocomplete_end +-- } -- --- Language-specific context menus, accessible by right-clicking inside the --- view, can be defined as: +-- --- -- --- context_menu = { --- { 'label1', action1 }, --- { 'label2', action2 }, --- ... +-- keys.cpp = { +-- ['s\n'] = function() +-- buffer:line_end() +-- buffer:add_text(';') +-- buffer:new_line() +-- end +-- } +-- +-- [Lua]: _M.lua.html +-- [C/C++]: _M.cpp.html +-- +-- #### Context Menu +-- +-- Language-specific [context menus][], accessible by right-clicking inside the +-- view, can be useful for accessing module features without using key bindings. +-- For Lua this may look like +-- +-- M.context_menu = { +-- { _L['_Undo'], buffer.undo }, +-- { _L['_Redo'], buffer.redo }, +-- { '' }, +-- { _L['Cu_t'], buffer.cut }, +-- { _L['_Copy'], buffer.copy }, +-- { _L['_Paste'], buffer.paste }, +-- { _L['_Delete'], buffer.clear }, +-- { '' }, +-- { _L['Select _All'], buffer.select_all }, +-- { '' }, +-- { 'Autocomplete "end"', M.try_to_autocomplete_end } -- } -- --- See `modules/textadept/menu.lua` for examples on how to define menus. +-- [context menus]: _M.textadept.menu.html#set_contextmenu module('_M')]] diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index 5686df1d..c224cac5 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -3,8 +3,12 @@ -- global buffer table. --- --- The current buffer in the current view. --- It also represents the structure of any buffer table in `_G._BUFFER`. +-- A Textadept buffer object. +-- Be careful when storing references to a buffer object because if you attempt +-- call a buffer function with a non-global buffer, you will get an error. See +-- [`check_global()`](#check_global) for more information. +-- +-- [buffer]: _G.html#buffer -- @field additional_caret_fore (number) -- The foreground color of additional carets in `0xBBGGRR` format. -- @field additional_carets_blink (bool) @@ -893,7 +897,7 @@ module('buffer') -- @param buffer The global buffer. -- @param caret The caret. -- @param anchor The anchor. -function buffer.add_selection(buffer, caret, anchor) end +function add_selection(buffer, caret, anchor) end --- -- Add text to the document at current position. @@ -901,19 +905,19 @@ function buffer.add_selection(buffer, caret, anchor) end -- scrolled into view. -- @param buffer The global buffer. -- @param text The text to add. -function buffer.add_text(buffer, text) end +function add_text(buffer, text) end --- -- Enlarge the document to a particular size of text bytes. -- The document will not be made smaller than its current contents. -- @param buffer The global buffer. -- @param bytes -function buffer.allocate(buffer, bytes) end +function allocate(buffer, bytes) end --- -- Clear the annotations from all lines. -- @param buffer The global buffer. -function buffer.annotation_clear_all(buffer) end +function annotation_clear_all(buffer) end --- -- Append a string to the end of the document without changing the selection. @@ -921,33 +925,33 @@ function buffer.annotation_clear_all(buffer) end -- view. -- @param buffer The global buffer. -- @param text The text. -function buffer.append_text(buffer, text) end +function append_text(buffer, text) end --- -- Is there an auto-completion list visible? -- @param buffer -- @return bool -function buffer.auto_c_active(buffer) end +function auto_c_active(buffer) end --- -- Remove the auto-completion list from the screen. -- A set of characters that will cancel autocompletion can be specified with -- `buffer:auto_c_stops()`. -- @param buffer The global buffer. -function buffer.auto_c_cancel(buffer) end +function auto_c_cancel(buffer) end --- -- User has selected an item so remove the list and insert the selection. -- This has the same effect as the tab key. -- @param buffer The global buffer. -function buffer.auto_c_complete(buffer) end +function auto_c_complete(buffer) end --- -- Retrieve the position of the caret when the auto-completion list was -- displayed. -- @param buffer The global buffer. -- @return number -function buffer.auto_c_pos_start(buffer) end +function auto_c_pos_start(buffer) end --- -- Select the item in the auto-completion list that starts with a string. @@ -955,7 +959,7 @@ function buffer.auto_c_pos_start(buffer) end -- `buffer.auto_c_ignore_case`. -- @param buffer The global buffer. -- @param string -function buffer.auto_c_select(buffer, string) end +function auto_c_select(buffer, string) end --- -- Display an auto-completion list. @@ -963,30 +967,30 @@ function buffer.auto_c_select(buffer, string) end -- the context. -- @param item_list List of words separated by separator characters (initially -- spaces). The list of words should be in sorted order. -function buffer.auto_c_show(buffer, len_entered, item_list) end +function auto_c_show(buffer, len_entered, item_list) end --- -- Define a set of characters that when typed cancel the auto-completion list. -- @param buffer The global buffer. -- @param chars String list of characters. This list is empty by default. -function buffer.auto_c_stops(buffer, chars) end +function auto_c_stops(buffer, chars) end --- -- Dedent the selected lines. -- @param buffer The global buffer. -function buffer.back_tab(buffer) end +function back_tab(buffer) end --- -- Start a sequence of actions that is undone and redone as a unit. -- May be nested. -- @param buffer The global buffer. -function buffer.begin_undo_action(buffer) end +function begin_undo_action(buffer) end --- -- Highlight the character at a position indicating there is no matching brace. -- @param buffer The global buffer. -- @param pos The position or -1 to remove the highlight. -function buffer.brace_bad_light(buffer, pos) end +function brace_bad_light(buffer, pos) end --- -- Use specified indicator to highlight non matching brace instead of changing @@ -994,7 +998,7 @@ function buffer.brace_bad_light(buffer, pos) end -- @param buffer The global buffer. -- @param use_indicator Use an indicator. -- @param indic_num The indicator number. -function buffer.brace_bad_light_indicator(buffer, use_indicator, indic_num) end +function brace_bad_light_indicator(buffer, use_indicator, indic_num) end --- -- Highlight the characters at two positions. @@ -1004,7 +1008,7 @@ function buffer.brace_bad_light_indicator(buffer, use_indicator, indic_num) end -- @param buffer The global buffer. -- @param pos1 The first position. -- @param pos2 The second position. -function buffer.brace_highlight(buffer, pos1, pos2) end +function brace_highlight(buffer, pos1, pos2) end --- -- Use specified indicator to highlight matching braces instead of changing @@ -1012,7 +1016,7 @@ function buffer.brace_highlight(buffer, pos1, pos2) end -- @param buffer The global buffer. -- @param use_indicator Use an indicator. -- @param indic_num The indicator number. -function buffer.brace_highlight_indicator(buffer, use_indicator, indic_num) end +function brace_highlight_indicator(buffer, use_indicator, indic_num) end --- -- Find the position of a matching brace or `-1` if no match. @@ -1024,33 +1028,33 @@ function buffer.brace_highlight_indicator(buffer, use_indicator, indic_num) end -- @param buffer The global buffer. -- @param pos The position. -- @return number. -function buffer.brace_match(buffer, pos) end +function brace_match(buffer, pos) end --- -- Is there an active call tip? -- @param buffer The global buffer. -- @return bool -function buffer.call_tip_active(buffer) end +function call_tip_active(buffer) end --- -- Remove the call tip from the screen. -- Call tips are also removed if any keyboard commands that are not compatible -- with editing the argument list of a function are used. -- @param buffer The global buffer. -function buffer.call_tip_cancel(buffer) end +function call_tip_cancel(buffer) end --- -- Retrieve the position where the caret was before displaying the call tip. -- @param buffer The global buffer. -- @return number -function buffer.call_tip_pos_start(buffer) end +function call_tip_pos_start(buffer) end --- -- Highlights a segment of a call tip. -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position. -function buffer.call_tip_set_hlt(buffer, start_pos, end_pos) end +function call_tip_set_hlt(buffer, start_pos, end_pos) end --- -- Show a call tip containing a definition near position pos. @@ -1061,30 +1065,30 @@ function buffer.call_tip_set_hlt(buffer, start_pos, end_pos) end -- @param buffer The global buffer. -- @param pos The position. -- @param text The text. -function buffer.call_tip_show(buffer, pos, text) end +function call_tip_show(buffer, pos, text) end --- -- Will a paste succeed? -- @param buffer The global buffer. -- @return bool -function buffer.can_paste(buffer) end +function can_paste(buffer) end --- -- Are there any redoable actions in the undo history? -- @param buffer The global buffer. -- @return bool -function buffer.can_redo(buffer) end +function can_redo(buffer) end --- -- Are there any undoable actions in the undo history? -- @param buffer The global buffer. -- @return bool -function buffer.can_undo(buffer) end +function can_undo(buffer) end --- -- Cancel any modes such as call tip or auto-completion list display. -- @param buffer The global buffer. -function buffer.cancel(buffer) end +function cancel(buffer) end --- -- Indicate that the internal state of a lexer has changed over a range and @@ -1092,23 +1096,23 @@ function buffer.cancel(buffer) end -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position. -function buffer.change_lexer_state(buffer, start_pos, end_pos) end +function change_lexer_state(buffer, start_pos, end_pos) end --- -- Move caret left one character. -- @param buffer The global buffer. -function buffer.char_left(buffer) end +function char_left(buffer) end --- -- Move caret left one character extending selection to new caret position. -- @param buffer The global buffer. -function buffer.char_left_extend(buffer) end +function char_left_extend(buffer) end --- -- Move caret left one character, extending rectangular selection to new caret -- position. -- @param buffer The global buffer. -function buffer.char_left_rect_extend(buffer) end +function char_left_rect_extend(buffer) end --- -- Find the position of a character from a point within the window. @@ -1116,7 +1120,7 @@ function buffer.char_left_rect_extend(buffer) end -- @param x -- @param y -- @return number -function buffer.char_position_from_point(buffer, x, y) end +function char_position_from_point(buffer, x, y) end --- -- Find the position of a character from a point within the window. @@ -1125,23 +1129,23 @@ function buffer.char_position_from_point(buffer, x, y) end -- @param x -- @param y -- @return number -function buffer.char_position_from_point_close(buffer, x, y) end +function char_position_from_point_close(buffer, x, y) end --- -- Move caret right one character. -- @param buffer The global buffer. -function buffer.char_right(buffer) end +function char_right(buffer) end --- -- Move caret right one character extending selection to new caret position. -- @param buffer The global buffer. -function buffer.char_right_extend(buffer) end +function char_right_extend(buffer) end --- -- Move caret right one character, extending rectangular selection to new caret -- position. -- @param buffer The global buffer. -function buffer.char_right_rect_extend(buffer) end +function char_right_rect_extend(buffer) end --- -- Set the last x chosen value to be the caret x position. @@ -1150,37 +1154,37 @@ function buffer.char_right_rect_extend(buffer) end -- such as by using the up and down keys. This function sets the current x -- position of the caret as the remembered value. -- @param buffer The global buffer. -function buffer.choose_caret_x(buffer) end +function choose_caret_x(buffer) end --- -- Clear the selection. -- @param buffer The global buffer. -function buffer.clear(buffer) end +function clear(buffer) end --- -- Delete all text in the document. -- @param buffer The global buffer. -function buffer.clear_all(buffer) end +function clear_all(buffer) end --- -- Drop all key mappings. -- @param buffer The global buffer. -function buffer.clear_all_cmd_keys(buffer) end +function clear_all_cmd_keys(buffer) end --- -- Set all style bytes to `0`, remove all folding information. -- @param buffer The global buffer. -function buffer.clear_document_style(buffer) end +function clear_document_style(buffer) end --- -- Clear all the registered XPM images. -- @param buffer The global buffer. -function buffer.clear_registered_images(buffer) end +function clear_registered_images(buffer) end --- -- Clear selections to a single empty stream selection. -- @param buffer The global buffer. -function buffer.clear_selections(buffer) end +function clear_selections(buffer) end --- -- Colorise a segment of the document using the current lexing language. @@ -1188,7 +1192,7 @@ function buffer.clear_selections(buffer) end -- @param start_pos The start position. -- @param end_pos The end position or `-1` to style from `start_pos` to the end -- of the document. -function buffer.colourise(buffer, start_pos, end_pos) end +function colourise(buffer, start_pos, end_pos) end --- -- Find the next line at or after line_start that is a contracted fold header @@ -1197,7 +1201,7 @@ function buffer.colourise(buffer, start_pos, end_pos) end -- @param buffer The global buffer. -- @param line_start The start line number. -- @return number -function buffer.contracted_fold_next(buffer, line_start) end +function contracted_fold_next(buffer, line_start) end --- -- Converts all line endings in the document to one mode. @@ -1206,17 +1210,17 @@ function buffer.contracted_fold_next(buffer, line_start) end -- `_SCINTILLA.constants.SC_EOL_CRLF` (0), -- `_SCINTILLA.constants.SC_EOL_CR (1)`, or -- `_SCINTILLA.constants.SC_EOL_LF (2)`. -function buffer.convert_eo_ls(buffer, mode) end +function convert_eo_ls(buffer, mode) end --- -- Copy the selection to the clipboard. -- @param buffer The buffer -function buffer.copy(buffer) end +function copy(buffer) end --- -- Copy the selection, if selection empty copy the line with the caret. -- @param buffer The global buffer. -function buffer.copy_allow_line(buffer) end +function copy_allow_line(buffer) end --- -- Copy a range of text to the clipboard. Positions are clipped into the @@ -1224,107 +1228,107 @@ function buffer.copy_allow_line(buffer) end -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position. -function buffer.copy_range(buffer, start_pos, end_pos) end +function copy_range(buffer, start_pos, end_pos) end --- -- Copy argument text to the clipboard. -- @param buffer The global buffer. -- @param text The text. -function buffer.copy_text(buffer, text) end +function copy_text(buffer, text) end --- -- Count characters between two positions. -- @param start_pos -- @param end_pos -- @return number -function buffer.count_characters(buffer, start_pos, end_pos) end +function count_characters(buffer, start_pos, end_pos) end --- -- Cut the selection to the clipboard. -- @param buffer The global buffer. -function buffer.cut(buffer) end +function cut(buffer) end --- -- Delete back from the current position to the start of the line. -- @param buffer The global buffer. -function buffer.del_line_left(buffer) end +function del_line_left(buffer) end --- -- Delete forwards from the current position to the end of the line. -- @param buffer The global buffer. -function buffer.del_line_right(buffer) end +function del_line_right(buffer) end --- -- Delete the word to the left of the caret. -- @param buffer The global buffer. -function buffer.del_word_left(buffer) end +function del_word_left(buffer) end --- -- Delete the word to the right of the caret. -- @param buffer The global buffer. -function buffer.del_word_right(buffer) end +function del_word_right(buffer) end --- -- Delete the word to the right of the caret, but not the trailing non-word -- characters. -- @param buffer The global buffer. -function buffer.del_word_right_end(buffer) end +function del_word_right_end(buffer) end --- -- Delete the selection or if no selection, the character before the caret. -- @param buffer The global buffer. -function buffer.delete_back(buffer) end +function delete_back(buffer) end --- -- Delete the selection or if no selection, the character before the caret. -- Will not delete the character before at the start of a line. -function buffer.delete_back_not_line(buffer) end +function delete_back_not_line(buffer) end --- -- Delete a range of text in the document. -- @param pos The start position of the range to delete. -- @param length The length of the range to delete. -function buffer.delete_range(buffer, pos, length) end +function delete_range(buffer, pos, length) end --- -- Find the document line of a display line taking hidden lines into account. -- @param buffer The global buffer. -- @return number -function buffer.doc_line_from_visible(buffer) end +function doc_line_from_visible(buffer) end --- -- Move caret to last position in document. -- @param buffer The global buffer. -function buffer.document_end(buffer) end +function document_end(buffer) end --- -- Move caret to last position in document extending selection to new caret -- position. -- @param buffer The global buffer. -function buffer.document_end_extend(buffer) end +function document_end_extend(buffer) end --- -- Move caret to first position in document. -- @param buffer The global buffer. -function buffer.document_start(buffer) end +function document_start(buffer) end --- -- Move caret to first position in document extending selection to new caret -- position. -- @param buffer The global buffer. -function buffer.document_start_extend(buffer) end +function document_start_extend(buffer) end --- -- Switch from insert to overtype mode or the reverse. -- @param buffer The global buffer. -function buffer.edit_toggle_overtype(buffer) end +function edit_toggle_overtype(buffer) end --- -- Delete the undo history. -- It also sets the save point to the start of the undo buffer, so the document -- will appear to be unmodified. -- @param buffer The global buffer. -function buffer.empty_undo_buffer(buffer) end +function empty_undo_buffer(buffer) end --- -- Translates a UTF8 string into the document encoding. @@ -1332,25 +1336,25 @@ function buffer.empty_undo_buffer(buffer) end -- @param buffer The global buffer. -- @param string The string. -- @return number -function buffer.encoded_from_utf8(buffer, string) end +function encoded_from_utf8(buffer, string) end --- -- End a sequence of actions that is undone and redone as a unit. -- @param buffer The global buffer. -function buffer.end_undo_action(buffer) end +function end_undo_action(buffer) end --- -- Ensure a particular line is visible by expanding any header line hiding it. -- @param buffer The global buffer. -- @param line The line number. -function buffer.ensure_visible(buffer, line) end +function ensure_visible(buffer, line) end --- -- Ensure a particular line is visible by expanding any header line hiding it. -- Use the currently set visibility policy to determine which range to display. -- @param buffer The global buffer. -- @param line The line number. -function buffer.ensure_visible_enforce_policy(buffer, line) end +function ensure_visible_enforce_policy(buffer, line) end --- -- Find the position of a column on a line taking into account tabs and @@ -1359,38 +1363,38 @@ function buffer.ensure_visible_enforce_policy(buffer, line) end -- @param buffer The global buffer. -- @param line The line number. -- @param column The column number. -function buffer.find_column(buffer, line, column) end +function find_column(buffer, line, column) end --- -- Insert a Form Feed character. -- @param buffer The global buffer. -function buffer.form_feed(buffer) end +function form_feed(buffer) end --- -- Retrieve the text of the line containing the caret. -- Also returns the index of the caret on the line. -- @param buffer The global buffer. -- @return string, number -function buffer.get_cur_line(buffer) end +function get_cur_line(buffer) end --- -- Get the back color for active hotspots in 0xBBGGRR format. -- @param buffer The global buffer. -- @return number -function buffer.get_hotspot_active_back(buffer) end +function get_hotspot_active_back(buffer) end --- -- Get the fore color for active hotspots. -- @param buffer The global buffer. -- @return number -function buffer.get_hotspot_active_fore(buffer) end +function get_hotspot_active_fore(buffer) end --- -- Find the last child line of a header line. -- @param buffer The global buffer. -- @param header_line The line number of a header line. -- @param level The level or `-1` for the level of header_line. -function buffer.get_last_child(buffer, header_line, level) end +function get_last_child(buffer, header_line, level) end --- -- Retrieve the contents of a line. @@ -1398,21 +1402,21 @@ function buffer.get_last_child(buffer, header_line, level) end -- @param buffer The global buffer. -- @param line The line number. -- @return string, number -function buffer.get_line(buffer, line) end +function get_line(buffer, line) end --- -- Retrieve the position of the end of the selection at the given line (`-1` if -- no selection on this line). -- @param buffer The global buffer. -- @param line The line number. -function buffer.get_line_sel_end_position(buffer, line) end +function get_line_sel_end_position(buffer, line) end --- -- Retrieve the position of the start of the selection at the given line (`-1` -- if no selection on this line). -- @param buffer The global buffer. -- @param line The line number. -function buffer.get_line_sel_start_position(buffer, line) end +function get_line_sel_start_position(buffer, line) end --- -- Return a read-only pointer to a range of characters in the document. @@ -1421,38 +1425,38 @@ function buffer.get_line_sel_start_position(buffer, line) end -- The gap is not moved unless it is within the requested range so this call can -- be faster than `SCI_GETCHARACTERPOINTER`. This can be used by application -- code that is able to act on blocks of text or ranges of lines. -function buffer.get_range_pointer(buffer, position, range_length) end +function get_range_pointer(buffer, position, range_length) end --- -- Retrieve the selected text. -- Also returns the length of the text. -- @param buffer The global buffer. -- @return string, number -function buffer.get_sel_text(buffer) end +function get_sel_text(buffer) end --- -- Retrieve all the text in the document. -- Also returns number of characters retrieved. -- @param buffer The global buffer. -function buffer.get_text(buffer) end +function get_text(buffer) end --- -- Set caret to start of a line and ensure it is visible. -- @param buffer The global buffer. -- @param line The line number. -function buffer.goto_line(buffer, line) end +function goto_line(buffer, line) end --- -- Set caret to a position and ensure it is visible. -- The anchor position is set the same as the current position. -- @param buffer The global buffer. -- @param pos The position. -function buffer.goto_pos(buffer, pos) end +function goto_pos(buffer, pos) end --- -- Set the focus to this view. -- @param buffer The global buffer. -function buffer.grab_focus(buffer) end +function grab_focus(buffer) end --- -- Make a range of lines invisible. @@ -1461,52 +1465,52 @@ function buffer.grab_focus(buffer) end -- @param buffer The global buffer. -- @param start_line The start line. -- @param end_line The end line. -function buffer.hide_lines(buffer, start_line, end_line) end +function hide_lines(buffer, start_line, end_line) end --- -- Draw the selection in normal style or with selection highlighted. -- @param buffer The global buffer. -- @param normal Draw normal selection. -function buffer.hide_selection(buffer, normal) end +function hide_selection(buffer, normal) end --- -- Move caret to first position on line. -- @param buffer The global buffer. -function buffer.home(buffer) end +function home(buffer) end --- -- Move caret to first position on display line. -- @param buffer The global buffer. -function buffer.home_display(buffer) end +function home_display(buffer) end --- -- Move caret to first position on display line extending selection to new caret -- position. -- @param buffer The global buffer. -function buffer.home_display_extend(buffer) end +function home_display_extend(buffer) end --- -- Move caret to first position on line extending selection to new caret -- position. -- @param buffer The global buffer. -function buffer.home_extend(buffer) end +function home_extend(buffer) end --- -- Move caret to first position on line, extending rectangular selection to new -- caret position. -- @param buffer The global buffer. -function buffer.home_rect_extend(buffer) end +function home_rect_extend(buffer) end --- -- Move caret to the start of the display line when word-wrap is enabled. -- If already there, go to the start of the document line. -- @param buffer The global buffer. -function buffer.home_wrap(buffer) end +function home_wrap(buffer) end --- -- Like `buffer:home_wrap()` but extending selection to new caret position. -- @param buffer The global buffer. -function buffer.home_wrap_extend(buffer) end +function home_wrap_extend(buffer) end --- -- Retrieve a bitmap value representing which indicators are non-zero at a @@ -1515,21 +1519,21 @@ function buffer.home_wrap_extend(buffer) end -- @param buffer The global buffer. -- @param pos The position. -- @return number -function buffer.indicator_all_on_for(buffer, pos) end +function indicator_all_on_for(buffer, pos) end --- -- Turn a indicator off over a range. -- @param buffer The global buffer. -- @param pos The start position. -- @param clear_length The length. -function buffer.indicator_clear_range(buffer, pos, clear_length) end +function indicator_clear_range(buffer, pos, clear_length) end --- -- Find the position where a particular indicator ends. -- @param buffer The global buffer. -- @param indicator An indicator number in the range of `0` to `31`. -- @param pos The position of the indicator. -function buffer.indicator_end(buffer, indicator, pos) end +function indicator_end(buffer, indicator, pos) end --- -- Turn a indicator on over a range. @@ -1537,14 +1541,14 @@ function buffer.indicator_end(buffer, indicator, pos) end -- @param buffer The global buffer. -- @param pos the start position. -- @param fill_length The length. -function buffer.indicator_fill_range(buffer, pos, fill_length) end +function indicator_fill_range(buffer, pos, fill_length) end --- -- Find the position where a particular indicator starts. -- @param buffer The global buffer. -- @param indicator An indicator number in the range of `0` to `31`. -- @param pos The position of the indicator. -function buffer.indicator_start(buffer, indicator, pos) end +function indicator_start(buffer, indicator, pos) end --- -- Retrieve the value of a particular indicator at a position. @@ -1553,7 +1557,7 @@ function buffer.indicator_start(buffer, indicator, pos) end -- @param indicator The indicator number in the range of `0` to `31`. -- @param pos The position. -- @return number -function buffer.indicator_value_at(buffer, indicator, pos) end +function indicator_value_at(buffer, indicator, pos) end --- -- Insert string at a position. @@ -1562,89 +1566,89 @@ function buffer.indicator_value_at(buffer, indicator, pos) end -- @param buffer The global buffer. -- @param pos The position to insert text at or `-1` for the current position. -- @param text The text to insert. -function buffer.insert_text(buffer, pos, text) end +function insert_text(buffer, pos, text) end --- -- Copy the line containing the caret. -- @param buffer The global buffer. -function buffer.line_copy(buffer) end +function line_copy(buffer) end --- -- Cut the line containing the caret. -- @param buffer The global buffer. -function buffer.line_cut(buffer) end +function line_cut(buffer) end --- -- Delete the line containing the caret. -- @param buffer The global buffer. -function buffer.line_delete(buffer) end +function line_delete(buffer) end --- -- Move caret down one line. -- @param buffer The global buffer. -function buffer.line_down(buffer) end +function line_down(buffer) end --- -- Move caret down one line extending selection to new caret position. -- @param buffer The global buffer. -function buffer.line_down_extend(buffer) end +function line_down_extend(buffer) end --- -- Move caret down one line, extending rectangular selection to new caret -- position. -- @param buffer The global buffer. -function buffer.line_down_rect_extend(buffer) end +function line_down_rect_extend(buffer) end --- -- Duplicate the current line. -- @param buffer The global buffer. -function buffer.line_duplicate(buffer) end +function line_duplicate(buffer) end --- -- Move caret to last position on line. -- @param buffer The global buffer. -function buffer.line_end(buffer) end +function line_end(buffer) end --- -- Move caret to last position on display line. -- @param buffer The global buffer. -function buffer.line_end_display(buffer) end +function line_end_display(buffer) end --- -- Move caret to last position on display line extending selection to new caret -- position. -- @param buffer The global buffer. -function buffer.line_end_display_extend(buffer) end +function line_end_display_extend(buffer) end --- -- Move caret to last position on line extending selection to new caret -- position. -- @param buffer The global buffer. -function buffer.line_end_extend(buffer) end +function line_end_extend(buffer) end --- -- Move caret to last position on line, extending rectangular selection to new -- caret position. -- @param buffer The global buffer. -function buffer.line_end_rect_extend(buffer) end +function line_end_rect_extend(buffer) end --- -- Move caret to the end of the display line when word-wrap is enabled. -- If already there, go to the end of the document line. -- @param buffer The global buffer. -function buffer.line_end_wrap(buffer) end +function line_end_wrap(buffer) end --- -- Like `buffer:line_end_wrap()` but extending selection to new caret position. -- @param buffer The global buffer. -function buffer.line_end_wrap_extend(buffer) end +function line_end_wrap_extend(buffer) end --- -- Retrieve the line containing a position. -- @param buffer The global buffer. -- @param pos The position. -- @return number -function buffer.line_from_position(buffer, pos) end +function line_from_position(buffer, pos) end --- -- Returns how many characters are on a line, including end of line characters. @@ -1653,68 +1657,68 @@ function buffer.line_from_position(buffer, pos) end -- @param buffer The global buffer. -- @param line The line number. -- @return number -function buffer.line_length(buffer, line) end +function line_length(buffer, line) end --- -- Scroll horizontally and vertically. -- @param buffer The global buffer. -- @param columns The number of columns to scroll horizontally. -- @param lines The number of lines to scroll vertically. -function buffer.line_scroll(buffer, columns, lines) end +function line_scroll(buffer, columns, lines) end --- -- Scroll the document down, keeping the caret visible. -- @param buffer The global buffer. -function buffer.line_scroll_down(buffer) end +function line_scroll_down(buffer) end --- -- Scroll the document up, keeping the caret visible. -- @param buffer The global buffer. -function buffer.line_scroll_up(buffer) end +function line_scroll_up(buffer) end --- -- Switch the current line with the previous. -- @param buffer The global buffer. -function buffer.line_transpose(buffer) end +function line_transpose(buffer) end --- -- Move caret up one line. -- @param buffer The global buffer. -function buffer.line_up(buffer) end +function line_up(buffer) end --- -- Move caret up one line extending selection to new caret position. -- @param buffer The global buffer. -function buffer.line_up_extend(buffer) end +function line_up_extend(buffer) end --- -- Move caret up one line, extending rectangular selection to new caret -- position. -- @param buffer The global buffer. -function buffer.line_up_rect_extend(buffer) end +function line_up_rect_extend(buffer) end --- -- Join the lines in the target. -- Where this would lead to no space between words, an extra space is inserted. -- @param buffer The global buffer. -function buffer.lines_join(buffer) end +function lines_join(buffer) end --- -- Split the lines in the target into lines that are less wide than -- `pixel_width` where possible. -- @param buffer The global buffer. -- @param pixel_width The pixel width. When `0`, the width of the view is used. -function buffer.lines_split(buffer, pixel_width) end +function lines_split(buffer, pixel_width) end --- -- Transform the selection to lower case. -- @param buffer The global buffer. -function buffer.lower_case(buffer) end +function lower_case(buffer) end --- -- Clear the margin text on all lines. -- @param buffer The global buffer. -function buffer.margin_text_clear_all(buffer) end +function margin_text_clear_all(buffer) end --- -- Add a marker to a line, returning an ID which can be used to find or delete @@ -1724,7 +1728,7 @@ function buffer.margin_text_clear_all(buffer) end -- @param line The line number. -- @param marker_num A marker number in the range of `0` to `31`. -- @return number -function buffer.marker_add(buffer, line, marker_num) end +function marker_add(buffer, line, marker_num) end --- -- Add a set of markers to a line. @@ -1732,7 +1736,7 @@ function buffer.marker_add(buffer, line, marker_num) end -- @param line The line number. -- @param marker_mask A mask of markers to set. Set bit 0 to set marker 0, bit -- 1 for marker 1 and so on. -function buffer.marker_add_set(buffer, line, marker_mask) end +function marker_add_set(buffer, line, marker_mask) end --- -- Set the symbol used for a particular marker number. @@ -1740,14 +1744,14 @@ function buffer.marker_add_set(buffer, line, marker_mask) end -- @param marker_num A marker number in the range of `0` to `31`. -- @param marker_symbol A marker symbol: `_SCINTILLA.constants.SC_MARK_*`. -- @see _SCINTILLA.next_marker_number -function buffer.marker_define(buffer, marker_num, marker_symbol) end +function marker_define(buffer, marker_num, marker_symbol) end --- -- Define a marker from a pixmap. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31`. -- @param pixmap `NULL`-terminated pixmap data. -function buffer.marker_define_pixmap(buffer, marker_num, pixmap) end +function marker_define_pixmap(buffer, marker_num, pixmap) end --- -- Define a marker from RGBA data. @@ -1762,7 +1766,7 @@ function buffer.marker_define_pixmap(buffer, marker_num, pixmap) end -- byte and an alpha byte. The colour bytes are not premultiplied by the alpha -- value. That is, a fully red pixel that is 25% opaque will be `[FF, 00, 00, -- 3F]`. -function buffer.marker_define_rgba_image(buffer, marker_num, pixels) end +function marker_define_rgba_image(buffer, marker_num, pixels) end --- -- Delete a marker from a line. @@ -1770,27 +1774,27 @@ function buffer.marker_define_rgba_image(buffer, marker_num, pixels) end -- @param line The line number. -- @param marker_num A marker number in the range of `0` to `31` or `-1` to -- delete all markers from the line. -function buffer.marker_delete(buffer, line, marker_num) end +function marker_delete(buffer, line, marker_num) end --- -- Delete all markers with a particular number from all lines. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31` or `-1` to -- delete all markers from the line. -function buffer.marker_delete_all(buffer, marker_num) end +function marker_delete_all(buffer, marker_num) end --- -- Delete a marker. -- @param buffer The global buffer. -- @param handle The identifier of a marker returned by `buffer:marker_add()`. -function buffer.marker_delete_handle(buffer, handle) end +function marker_delete_handle(buffer, handle) end --- -- Enable/disable highlight for current folding block (smallest one that -- contains the caret) -- @param buffer The global buffer. -- @param enabled -function buffer.marker_enable_highlight(buffer, enabled) end +function marker_enable_highlight(buffer, enabled) end --- -- Get a bit mask of all the markers set on a line. @@ -1798,7 +1802,7 @@ function buffer.marker_enable_highlight(buffer, enabled) end -- @param buffer The global buffer. -- @param line The line number. -- @return number. -function buffer.marker_get(buffer, line) end +function marker_get(buffer, line) end --- -- Retrieve the line number at which a particular marker is located. @@ -1806,7 +1810,7 @@ function buffer.marker_get(buffer, line) end -- @param buffer The global buffer. -- @param handle The identifier of a marker returned by `buffer:marker_add()`. -- @return number -function buffer.marker_line_from_handle(buffer, handle) end +function marker_line_from_handle(buffer, handle) end --- -- Find the next line at or after start_line that includes a marker in mask. @@ -1816,7 +1820,7 @@ function buffer.marker_line_from_handle(buffer, handle) end -- @param marker_mask A mask of markers to find. Set bit 0 to find marker 0, bit -- 1 for marker 1 and so on. -- @return number -function buffer.marker_next(buffer, start_line, marker_mask) end +function marker_next(buffer, start_line, marker_mask) end --- -- Find the previous line before `start_line` that includes a marker in mask. @@ -1825,20 +1829,20 @@ function buffer.marker_next(buffer, start_line, marker_mask) end -- @param marker_mask A mask of markers to find. Set bit 0 to find marker 0, bit -- 1 for marker 1 and so on. -- @return number -function buffer.marker_previous(buffer, start_line, marker_mask) end +function marker_previous(buffer, start_line, marker_mask) end --- -- Return the symbol defined for marker_num with `buffer:marker_define()`. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31`. -- @return number -function buffer.marker_symbol_defined(buffer, marker_num) end +function marker_symbol_defined(buffer, marker_num) end --- -- Move the caret inside current view if it is not there already. -- Any selection is lost. -- @param buffer The global buffer. -function buffer.move_caret_inside_view(buffer) end +function move_caret_inside_view(buffer) end --- -- Move the selected lines down one line, shifting the line below before the @@ -1847,7 +1851,7 @@ function buffer.move_caret_inside_view(buffer) end -- selection's first line and the end of the seletion's last line. If nothing -- was selected, the line the cursor is currently at will be selected. -- @param buffer The global buffer. -function buffer.move_selected_lines_down(buffer) end +function move_selected_lines_down(buffer) end --- -- Move the selected lines up one line, shifting the line above after the @@ -1856,79 +1860,79 @@ function buffer.move_selected_lines_down(buffer) end -- selection's first line and the end of the seletion's last line. If nothing -- was selected, the line the cursor is currently at will be selected. -- @param buffer The global buffer. -function buffer.move_selected_lines_up(buffer) end +function move_selected_lines_up(buffer) end --- -- Insert a new line, may use a CRLF, CR or LF depending on EOL mode. -- @param buffer The global buffer. -function buffer.new_line(buffer) end +function new_line(buffer) end --- -- Move caret one page down. -- @param buffer The global buffer. -function buffer.page_down(buffer) end +function page_down(buffer) end --- -- Move caret one page down extending selection to new caret position. -- @param buffer The global buffer. -function buffer.page_down_extend(buffer) end +function page_down_extend(buffer) end --- -- Move caret one page down, extending rectangular selection to new caret -- position. -- @param buffer The global buffer. -function buffer.page_down_rect_extend(buffer) end +function page_down_rect_extend(buffer) end --- -- Move caret one page up. -- @param buffer The global buffer. -function buffer.page_up(buffer) end +function page_up(buffer) end --- -- Move caret one page up extending selection to new caret position. -- @param buffer The global buffer. -function buffer.page_up_extend(buffer) end +function page_up_extend(buffer) end --- -- Move caret one page up, extending rectangular selection to new caret -- position. -- @param buffer The global buffer. -function buffer.page_up_rect_extend(buffer) end +function page_up_rect_extend(buffer) end --- -- Move caret one paragraph down (delimited by empty lines). -- @param buffer The global buffer. -function buffer.para_down(buffer) end +function para_down(buffer) end --- -- Move caret one paragraph down (delimited by empty lines) extending selection -- to new caret position. -- @param buffer The global buffer. -function buffer.para_down_extend(buffer) end +function para_down_extend(buffer) end --- -- Move caret one paragraph up (delimited by empty lines). -- @param buffer The global buffer. -function buffer.para_up(buffer) end +function para_up(buffer) end --- -- Move caret one paragraph up (delimited by empty lines) extending selection to -- new caret position. -- @param buffer The global buffer. -function buffer.para_up_extend(buffer) end +function para_up_extend(buffer) end --- -- Paste the contents of the clipboard into the document replacing the -- selection. -- @param buffer The global buffer. -function buffer.paste(buffer) end +function paste(buffer) end --- -- For private communication between an application and a known lexer. -- @param buffer The global buffer. -- @param operation An operation number. -- @param data Number data. -function buffer.private_lexer_call(buffer, operation, data) end +function private_lexer_call(buffer, operation, data) end --- -- Retrieve the x value of the point in the window where a position is @@ -1936,7 +1940,7 @@ function buffer.private_lexer_call(buffer, operation, data) end -- @param buffer The global buffer. -- @param pos The position. -- @return number -function buffer.point_x_from_position(buffer, pos) end +function point_x_from_position(buffer, pos) end --- -- Retrieve the y value of the point in the window where a position is @@ -1944,14 +1948,14 @@ function buffer.point_x_from_position(buffer, pos) end -- @param buffer The global buffer. -- @param pos The position. -- @return number -function buffer.point_y_from_position(buffer, pos) end +function point_y_from_position(buffer, pos) end --- -- Given a valid document position, return the next position taking code page -- into account. Maximum value returned is the last position in the document. -- @param buffer The global buffer. -- @param pos The position. -function buffer.position_after(buffer, pos) end +function position_after(buffer, pos) end --- -- Given a valid document position, return the previous position taking code @@ -1959,7 +1963,7 @@ function buffer.position_after(buffer, pos) end -- @param buffer The global buffer. -- @param pos The position. -- @return number -function buffer.position_before(buffer, pos) end +function position_before(buffer, pos) end --- -- Retrieve the position at the start of a line. @@ -1967,7 +1971,7 @@ function buffer.position_before(buffer, pos) end -- @param buffer The global buffer. -- @param line The line. -- @return number -function buffer.position_from_line(buffer, line) end +function position_from_line(buffer, line) end --- -- Find the position from a point within the window. @@ -1975,7 +1979,7 @@ function buffer.position_from_line(buffer, line) end -- @param x -- @param y -- @return number -function buffer.position_from_point(buffer, x, y) end +function position_from_point(buffer, x, y) end --- -- Returns the position from a point within the window, but return `-1` if not @@ -1984,19 +1988,19 @@ function buffer.position_from_point(buffer, x, y) end -- @param x -- @param y -- @return number -function buffer.position_from_point_close(buffer, x, y) end +function position_from_point_close(buffer, x, y) end --- -- Redoes the next action on the undo history. -- @param buffer The global buffer. -function buffer.redo(buffer) end +function redo(buffer) end --- -- Register an XPM image for use in autocompletion lists. -- @param buffer The global buffer. -- @param type Integer type to register the image with. -- @param xpm_data XPM data as is described for `buffer:marker_define_pixmap()`. -function buffer.register_image(buffer, type, xpm_data) end +function register_image(buffer, type, xpm_data) end --- -- Register an RGBA image for use in autocompletion lists. @@ -2006,7 +2010,7 @@ function buffer.register_image(buffer, type, xpm_data) end -- @param type Integer type to register the image with. -- @param pixels RGBA data as is described for -- `buffer:marker_define_rgba_image()`. -function buffer.register_rgba_image(buffer, type, pixels) end +function register_rgba_image(buffer, type, pixels) end --- -- Replace the selected text with the argument text. @@ -2014,7 +2018,7 @@ function buffer.register_rgba_image(buffer, type, pixels) end -- into view. -- @param buffer The global buffer. -- @param text The text. -function buffer.replace_sel(buffer, text) end +function replace_sel(buffer, text) end --- -- Replace the target text with the argument text. @@ -2023,7 +2027,7 @@ function buffer.replace_sel(buffer, text) end -- @param buffer The global buffer. -- @param text The text (can contain NULs). -- @return number -function buffer.replace_target(buffer, text) end +function replace_target(buffer, text) end --- -- Replace the target text with the argument text after `\d` processing. @@ -2034,34 +2038,34 @@ function buffer.replace_target(buffer, text) end -- @param buffer The global buffer. -- @param text The text (can contain NULs). -- @return number -function buffer.replace_target_re(buffer, text) end +function replace_target_re(buffer, text) end --- -- Set the main selection to the next selection. -- @param buffer The global buffer. -function buffer.rotate_selection(buffer) end +function rotate_selection(buffer) end --- -- Ensure the caret is visible. -- @param buffer The global buffer. -function buffer.scroll_caret(buffer) end +function scroll_caret(buffer) end --- -- Scroll to end of document. -- @param buffer The global buffer. -function buffer.scroll_to_end(buffer) end +function scroll_to_end(buffer) end --- -- Scroll to start of document. -- @param buffer The global buffer. -function buffer.scroll_to_start(buffer) end +function scroll_to_start(buffer) end --- -- Sets the current caret position to be the search anchor. -- Always call this before calling either of `buffer:search_next()` or -- `buffer:search_prev()`. -- @param buffer The global buffer. -function buffer.search_anchor(buffer) end +function search_anchor(buffer) end --- -- Search for a counted string in the target and set the target to the found @@ -2071,7 +2075,7 @@ function buffer.search_anchor(buffer) end -- @param buffer The global buffer. -- @param text The text (can contain NULs). -- @return number -function buffer.search_in_target(buffer, text) end +function search_in_target(buffer, text) end --- -- Find some text starting at the search anchor. @@ -2082,7 +2086,7 @@ function buffer.search_in_target(buffer, text) end -- @param flags Search flags. See `buffer.search_flags`. -- @param text The text. -- @return number -function buffer.search_next(buffer, flags, text) end +function search_next(buffer, flags, text) end --- -- Find some text starting at the search anchor and moving backwards. @@ -2093,19 +2097,19 @@ function buffer.search_next(buffer, flags, text) end -- @param flags Search flags. See `buffer.search_flags`. -- @param text The text. -- @return number -function buffer.search_prev(buffer, flags, text) end +function search_prev(buffer, flags, text) end --- -- Select all the text in the document. -- The current position is not scrolled into view. -- @param buffer The global buffer. -function buffer.select_all(buffer) end +function select_all(buffer) end --- -- Duplicate the selection. -- If selection empty duplicate the line containing the caret. -- @param buffer The global buffer. -function buffer.selection_duplicate(buffer) end +function selection_duplicate(buffer) end --- -- Reset the set of characters for whitespace and word characters to the @@ -2113,54 +2117,54 @@ function buffer.selection_duplicate(buffer) end -- This sets whitespace to space, tab and other characters with codes less than -- `0x20`, with word characters set to alphanumeric and `'_'`. -- @param buffer The global buffer. -function buffer.set_chars_default(buffer) end +function set_chars_default(buffer) end --- -- Set caret to a position, while removing any existing selection. -- The caret is not scrolled into view. -- @param buffer The buffer -- @param pos The position to move to. -function buffer.set_empty_selection(buffer, pos) end +function set_empty_selection(buffer, pos) end --- -- Set the colors used as a chequerboard pattern in the fold margin. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_fold_margin_colour(buffer, use_setting, color) end +function set_fold_margin_colour(buffer, use_setting, color) end --- -- Set the colors used as a checkerboard pattern in the fold margin. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_fold_margin_hi_colour(buffer, use_setting, color) end +function set_fold_margin_hi_colour(buffer, use_setting, color) end --- -- Set a back color for active hotspots. -- @param buffer The global buffer. -- @param use_setting Enable the color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_hotspot_active_back(buffer, use_setting, color) end +function set_hotspot_active_back(buffer, use_setting, color) end --- -- Set a fore color for active hotspots. -- @param buffer The global buffer. -- @param use_setting Enable the color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_hotspot_active_fore(buffer, use_setting, color) end +function set_hotspot_active_fore(buffer, use_setting, color) end --- -- Set the length of the utf8 argument for calling `buffer:encoded_from_utf8()`. -- @param buffer The global buffer. -- @param bytes Bytes or `-1` for measuring to first NUL. -function buffer.set_length_for_encode(buffer, bytes) end +function set_length_for_encode(buffer, bytes) end --- -- Remember the current position in the undo history as the position at which -- the document was saved. -- @param buffer The global buffer. -function buffer.set_save_point(buffer) end +function set_save_point(buffer) end --- -- Select a range of text. @@ -2170,7 +2174,7 @@ function buffer.set_save_point(buffer) end -- document. -- @param end_pos End position. If negative, it means remove any selection (i.e. -- set the `anchor` to the same position as `current_pos`). -function buffer.set_sel(buffer, start_pos, end_pos) end +function set_sel(buffer, start_pos, end_pos) end --- -- Set the background color of the main and additional selections and whether to @@ -2178,7 +2182,7 @@ function buffer.set_sel(buffer, start_pos, end_pos) end -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_sel_back(buffer, use_setting, color) end +function set_sel_back(buffer, use_setting, color) end --- -- Set the foreground color of the main and additional selections and whether @@ -2186,14 +2190,14 @@ function buffer.set_sel_back(buffer, use_setting, color) end -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_sel_fore(buffer, use_setting, color) end +function set_sel_fore(buffer, use_setting, color) end --- -- Set a simple selection from anchor to caret. -- @param buffer The global buffer. -- @param caret The caret. -- @param anchor The anchor. -function buffer.set_selection(buffer, caret, anchor) end +function set_selection(buffer, caret, anchor) end --- -- Change style from current styling position for length characters to a style @@ -2201,13 +2205,13 @@ function buffer.set_selection(buffer, caret, anchor) end -- @param buffer The global buffer. -- @param length The length to style. -- @param style The style number to set. -function buffer.set_styling(buffer, length, style) end +function set_styling(buffer, length, style) end --- -- Replace the contents of the document with the argument text. -- @param buffer The global buffer. -- @param text The text. -function buffer.set_text(buffer, text) end +function set_text(buffer, text) end --- -- Set the way the display area is determined when a particular line is to be @@ -2217,21 +2221,21 @@ function buffer.set_text(buffer, text) end -- @param visible_policy A combination of `_SCINTILLA.constants.VISIBLE_SLOP`, -- (0x01) and `_SCINTILLA.constants.VISIBLE_STRICT` (0x04). -- @param visible_slop The slop value. -function buffer.set_visible_policy(buffer, visible_policy, visible_slop) end +function set_visible_policy(buffer, visible_policy, visible_slop) end --- -- Set the background color of all whitespace and whether to use this setting. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_whitespace_back(buffer, use_setting, color) end +function set_whitespace_back(buffer, use_setting, color) end --- -- Set the foreground color of all whitespace and whether to use this setting. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in `0xBBGGRR` format. -function buffer.set_whitespace_fore(buffer, use_setting, color) end +function set_whitespace_fore(buffer, use_setting, color) end --- -- Set the way the caret is kept visible when going sideways. @@ -2242,7 +2246,7 @@ function buffer.set_whitespace_fore(buffer, use_setting, color) end -- `_SCINTILLA.constants.CARET_JUMPS` (0x10), and -- `_SCINTILLA.constants.CARET_EVEN` (0x08). -- @param caret_slop A slop value. -function buffer.set_x_caret_policy(buffer, caret_policy, caret_slop) end +function set_x_caret_policy(buffer, caret_policy, caret_slop) end --- -- Set the way the line the caret is on is kept visible. @@ -2252,7 +2256,7 @@ function buffer.set_x_caret_policy(buffer, caret_policy, caret_slop) end -- `_SCINTILLA.constants.CARET_JUMPS` (0x10), and -- `_SCINTILLA.constants.CARET_EVEN` (0x08). -- @param caret_slop A slop value. -function buffer.set_y_caret_policy(buffer, caret_policy, caret_slop) end +function set_y_caret_policy(buffer, caret_policy, caret_slop) end --- -- Make a range of lines visible. @@ -2261,12 +2265,12 @@ function buffer.set_y_caret_policy(buffer, caret_policy, caret_slop) end -- @param buffer The global buffer. -- @param start_line The start line. -- @param end_line The end line. -function buffer.show_lines(buffer, start_line, end_line) end +function show_lines(buffer, start_line, end_line) end --- -- Start notifying the container of all key presses and commands. -- @param buffer The global buffer. -function buffer.start_record(buffer) end +function start_record(buffer) end --- -- Set the current styling position to pos and the styling mask to mask. @@ -2275,73 +2279,73 @@ function buffer.start_record(buffer) end -- @param buffer The global buffer. -- @param position The styling position. -- @param mask The bit mask of the style bytes that can be set. -function buffer.start_styling(buffer, position, mask) end +function start_styling(buffer, position, mask) end --- -- Stop notifying the container of all key presses and commands. -- @param buffer The global buffer. -function buffer.stop_record(buffer) end +function stop_record(buffer) end --- -- Move caret to bottom of page, or one page down if already at bottom of page. -- @param buffer The global buffer. -function buffer.stuttered_page_down(buffer) end +function stuttered_page_down(buffer) end --- -- Move caret to bottom of page, or one page down if already at bottom of page, -- extending selection to new caret position. -- @param buffer The global buffer. -function buffer.stuttered_page_down_extend(buffer) end +function stuttered_page_down_extend(buffer) end --- -- Move caret to top of page, or one page up if already at top of page. -- @param buffer The global buffer. -function buffer.stuttered_page_up(buffer) end +function stuttered_page_up(buffer) end --- -- Move caret to top of page, or one page up if already at top of page, -- extending selection to new caret position. -- @param buffer The global buffer. -function buffer.stuttered_page_up_extend(buffer) end +function stuttered_page_up_extend(buffer) end --- -- Clear all the styles and make equivalent to the global default style. -- @param buffer The global buffer. -function buffer.style_clear_all(buffer) end +function style_clear_all(buffer) end --- -- Reset the default style to its state at startup. -- @param buffer The global buffer. -function buffer.style_reset_default(buffer) end +function style_reset_default(buffer) end --- -- Swap that caret and anchor of the main selection. -- @param buffer The global buffer. -function buffer.swap_main_anchor_caret(buffer) end +function swap_main_anchor_caret(buffer) end --- -- If selection is empty or all on one line replace the selection with a tab -- character, or if more than one line selected, indent the lines. -- @param buffer The global buffer. -function buffer.tab(buffer) end +function tab(buffer) end --- -- Returns the target converted to UTF8. -- @param buffer The global buffer. -function buffer.target_as_utf8(buffer) end +function target_as_utf8(buffer) end --- -- Make the target range start and end be the same as the selection range start -- and end. -- @param buffer The global buffer. -function buffer.target_from_selection(buffer) end +function target_from_selection(buffer) end --- -- Retrieve the height of a particular line of text in pixels. -- @param buffer The global buffer. -- @param line The line number. -- @return number -function buffer.text_height(buffer, line) end +function text_height(buffer, line) end --- -- Measure the pixel width of some text in a particular style. @@ -2350,36 +2354,36 @@ function buffer.text_height(buffer, line) end -- @param style_num The style number between `0` and `255`. -- @param text The text. -- @return number -function buffer.text_width(buffer, style_num, text) end +function text_width(buffer, style_num, text) end --- -- Switch between sticky and non-sticky: meant to be bound to a key. -- See `buffer.caret_sticky`. -- @param buffer The global buffer. -function buffer.toggle_caret_sticky(buffer) end +function toggle_caret_sticky(buffer) end --- -- Switch a header line between expanded and contracted. -- @param buffer The global buffer. -- @param line The line number. -function buffer.toggle_fold(buffer, line) end +function toggle_fold(buffer, line) end --- -- Undo one action in the undo history. -- @param buffer The global buffer. -function buffer.undo(buffer) end +function undo(buffer) end --- -- Transform the selection to upper case. -- @param buffer The global buffer. -function buffer.upper_case(buffer) end +function upper_case(buffer) end --- -- Sets whether a pop up menu is displayed automatically when the user presses -- the wrong mouse button. -- @param buffer The global buffer. -- @param allow_popup Allow popup menu. -function buffer.use_pop_up(buffer, allow_popup) end +function use_pop_up(buffer, allow_popup) end --- -- Display a list of strings and send notification when user chooses one. @@ -2388,54 +2392,54 @@ function buffer.use_pop_up(buffer, allow_popup) end -- @param item_list List of words separated by separator characters (initially -- spaces). -- @see _SCINTILLA.next_user_list_type -function buffer.user_list_show(buffer, list_type, item_list) end +function user_list_show(buffer, list_type, item_list) end --- -- Move caret to before first visible character on line. -- If already there move to first character on line. -- @param buffer The global buffer. -function buffer.vc_home(buffer) end +function vc_home(buffer) end --- -- Move caret to before first visible character on display line. -- If already there move to first character on display line. -- @param buffer The global buffer. -function buffer.vc_home_display(buffer) end +function vc_home_display(buffer) end --- -- Like `buffer:vc_home_display()` but extending selection to new caret -- position. -- @param buffer The global buffer. -function buffer.vc_home_display_extend(buffer) end +function vc_home_display_extend(buffer) end --- -- Like `buffer:vc_home()` but extending selection to new caret position. -- @param buffer The global buffer. -function buffer.vc_home_extend(buffer) end +function vc_home_extend(buffer) end --- -- Move caret to before first visible character on line. -- If already there move to first character on line. In either case, extend -- rectangular selection to new caret position. -- @param buffer The global buffer. -function buffer.vc_home_rect_extend(buffer) end +function vc_home_rect_extend(buffer) end --- -- Move caret to before first visible character on display line when word-wrap -- is enabled. -- If already there, go to first character on display line. -- @param buffer The global buffer. -function buffer.vc_home_wrap(buffer) end +function vc_home_wrap(buffer) end --- -- Like `buffer:vc_home_wrap()` but extending selection to new caret position. -- @param buffer The global buffer. -function buffer.vc_home_wrap_extend(buffer) end +function vc_home_wrap_extend(buffer) end --- -- Center current line in window. -- @param buffer The global buffer. -function buffer.vertical_centre_caret(buffer) end +function vertical_centre_caret(buffer) end --- -- Find the display line of a document line taking hidden lines into account. @@ -2444,7 +2448,7 @@ function buffer.vertical_centre_caret(buffer) end -- @param buffer The global buffer. -- @param line The line number. -- @return number -function buffer.visible_from_doc_line(buffer, line) end +function visible_from_doc_line(buffer, line) end --- -- Get position of end of word. @@ -2455,71 +2459,71 @@ function buffer.visible_from_doc_line(buffer, line) end -- search direction sets the type of the search as word or non-word and the -- search stops at the first non-matching character. Searches are also -- terminated by the start or end of the document. -function buffer.word_end_position(buffer, pos, only_word_chars) end +function word_end_position(buffer, pos, only_word_chars) end --- -- Move caret left one word. -- @param buffer The global buffer. -function buffer.word_left(buffer) end +function word_left(buffer) end --- -- Move caret left one word, position cursor at end of word. -- @param buffer The global buffer. -function buffer.word_left_end(buffer) end +function word_left_end(buffer) end --- -- Move caret left one word, position cursor at end of word, extending selection -- to new caret position. -- @param buffer The global buffer. -function buffer.word_left_end_extend(buffer) end +function word_left_end_extend(buffer) end --- -- Move caret left one word extending selection to new caret position. -- @param buffer The global buffer. -function buffer.word_left_extend(buffer) end +function word_left_extend(buffer) end --- -- Move to the previous change in capitalisation or underscores. -- @param buffer The global buffer. -function buffer.word_part_left(buffer) end +function word_part_left(buffer) end --- -- Move to the previous change in capitalisation or underscores extending -- selection to new caret position. -- @param buffer The global buffer. -function buffer.word_part_left_extend(buffer) end +function word_part_left_extend(buffer) end --- -- Move to the next change in capitalisation or underscores. -- @param buffer The global buffer. -function buffer.word_part_right(buffer) end +function word_part_right(buffer) end --- -- Move to the next change in capitalisation or underscores extending selection -- to new caret position. -- @param buffer The global buffer. -function buffer.word_part_right_extend(buffer) end +function word_part_right_extend(buffer) end --- -- Move caret right one word. -- @param buffer The global buffer. -function buffer.word_right(buffer) end +function word_right(buffer) end --- -- Move caret right one word, position cursor at end of word. -- @param buffer The global buffer. -function buffer.word_right_end(buffer) end +function word_right_end(buffer) end --- -- Move caret right one word, position cursor at end of word, extending -- selection to new caret position. -- @param buffer The global buffer. -function buffer.word_right_end_extend(buffer) end +function word_right_end_extend(buffer) end --- -- Move caret right one word extending selection to new caret position. -- @param buffer The global buffer. -function buffer.word_right_extend(buffer) end +function word_right_extend(buffer) end --- -- Get position of start of word. @@ -2530,26 +2534,26 @@ function buffer.word_right_extend(buffer) end -- search direction sets the type of the search as word or non-word and the -- search stops at the first non-matching character. Searches are also -- terminated by the start or end of the document. -function buffer.word_start_position(buffer, pos, only_word_chars) end +function word_start_position(buffer, pos, only_word_chars) end --- -- Returns the number of display lines needed to wrap a document line. -- @param buffer The global buffer. -- @param line The line number. -- @return number -function buffer.wrap_count(buffer, line) end +function wrap_count(buffer, line) end --- -- Magnify the displayed text by increasing the sizes by 1 point if the current -- zoom factor is less than 20 points. -- @param buffer The global buffer. -function buffer.zoom_in(buffer) end +function zoom_in(buffer) end --- -- Make the displayed text smaller by decreasing the sizes by 1 point if the -- current zoom factor is greater than -10 points. -- @param buffer The global buffer. -function buffer.zoom_out(buffer) end +function zoom_out(buffer) end -- External functions. @@ -2559,54 +2563,61 @@ function buffer.zoom_out(buffer) end -- top of all buffer functions to avoid unexpected behavior since most buffer -- functions operate on `_G.buffer`, which is not necessarily the given one. -- @param buffer The buffer to check. -function buffer.check_global(buffer) end +-- @see _G._G.buffer +function check_global(buffer) end --- -- Deletes the current buffer. -- WARNING: this function should NOT be called via scripts. Use `buffer:close()` --- instead, which prompts for confirmation if necessary. Generates a +-- instead, which prompts for confirmation if necessary. Emits a -- `BUFFER_DELETED` event. -- @param buffer The global buffer. -function buffer.delete(buffer) end +-- @see events.BUFFER_DELETED +function delete(buffer) end --- -- Gets a range of text from the current buffer. -- @param buffer The global buffer. -- @param start_pos The beginning position of the range of text to get. -- @param end_pos The end position of the range of text to get. -function buffer.text_range(buffer, start_pos, end_pos) end +function text_range(buffer, start_pos, end_pos) end --- -- Reloads the file in a given buffer. -- @param buffer The global buffer. -function buffer.reload(buffer) end +function reload(buffer) end --- -- Sets the encoding for the buffer, converting its contents in the process. -- @param buffer The global buffer. --- @param encoding The encoding to set. Valid encodings are ones that GTK's --- `g_convert()` function accepts (typically GNU iconv's encodings). +-- @param encoding The encoding to set. Valid encodings are ones that GNU iconv +-- accepts. -- @usage buffer.set_encoding(buffer, 'ASCII') -function buffer.set_encoding(buffer, encoding) end +function set_encoding(buffer, encoding) end --- -- Saves the current buffer to a file. +-- Emits `FILE_BEFORE_SAVE` and `FILE_AFTER_SAVE` events. -- @param buffer The global buffer. -function buffer.save(buffer) end +-- @see _G.events +function save(buffer) end --- -- Saves the current buffer to a file different than its filename property. +-- Emits a `FILE_SAVED_AS` event. -- @param buffer The global buffer. -- @param utf8_filename The new filepath to save the buffer to. Must be UTF-8 -- encoded. -function buffer.save_as(buffer, utf8_filename) end +-- @see _G.events +function save_as(buffer, utf8_filename) end --- -- Closes the current buffer. -- @param buffer The global buffer. -- If the buffer is dirty, the user is prompted to continue. The buffer is not -- saved automatically. It must be done manually. -function buffer.close(buffer) end +-- @return `true` if the buffer was closed; `nil` otherwise. +function close(buffer) end --- -- Replacement for `buffer.lexer_language =`. @@ -2618,21 +2629,21 @@ function buffer.close(buffer) end -- @param buffer The global buffer. -- @param lang The string language to set. -- @usage buffer.set_lexer(buffer, 'language_name') -function buffer.set_lexer(buffer, lang) end +function set_lexer(buffer, lang) end --- -- Replacement for `buffer.lexer_language`. -- @param buffer The global buffer. -- @param current Whether to get the lexer at the current caret position in -- multi-language lexers. The default is `false` and returns the parent lexer. -function buffer.get_lexer(buffer, current) end +function get_lexer(buffer, current) end --- -- Returns the name of the style associated with a style number. -- @param buffer The global buffer. -- @param style_num A style number from `0` to `255`. -- @see buffer.style_at -function buffer.get_style_name(buffer, style_num) end +function get_style_name(buffer, style_num) end -- Unused Fields. -- * use_palette diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc index eb761d56..fcf199ca 100644 --- a/core/.iconv.luadoc +++ b/core/.iconv.luadoc @@ -2,12 +2,14 @@ -- This is a DUMMY FILE used for making LuaDoc for built-in functions in the -- string table. ---- Extends Lua's string package to provide character set conversions. +--- Extends Lua's `string` package to provide character set conversions. module('string') --- -- Converts a string from one character set to another using iconv. --- Valid character sets are GNU iconv's character sets. +-- Valid character sets are [GNU iconv's character sets][]. +-- +-- [GNU iconv's character sets]: http://www.gnu.org/software/libiconv/ -- @param text The text to convert. -- @param to The character set to convert to. -- @param from The character set to convert from. diff --git a/core/.view.luadoc b/core/.view.luadoc index bea8efb8..c658ddfb 100644 --- a/core/.view.luadoc +++ b/core/.view.luadoc @@ -3,35 +3,42 @@ -- global view table. --- --- The currently focused view. --- It also represents the structure of any view table in `_G._VIEWS`. +-- A Textadept view object. -- @field size (number) -- The position of the split resizer (if this view is part of a split view). module('view') --- --- The buffer this view contains. (Read-only) +-- The [buffer](buffer.html) the view contains. (Read-only) -- @class table -- @name buffer local buffer --- --- Splits the indexed view vertically or horizontally and focuses the new view. +-- Splits the given view vertically or horizontally and focuses the new view. +-- Emits a `VIEW_NEW` event. +-- @param view The view to split. -- @param vertical Flag indicating a vertical split. The default value is -- `false` for horizontal. --- @return old view and new view tables. -function view:split(vertical) end +-- @return old view and new view. +-- @see events.VIEW_NEW +function split(view, vertical) end --- --- Unsplits the indexed view if possible. +-- Unsplits the given view if possible. +-- @param view The view to unsplit. -- @return boolean if the view was unsplit or not. -function view:unsplit() end +function view.unsplit(view) end --- --- Goes to the specified buffer in the indexed view. --- Generates `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events. --- @param n A relative or absolute buffer index. An absolute index of `-1` goes --- to the last buffer. +-- Goes to the specified buffer in the given view. +-- Emits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events. +-- @param view The view to switch buffers in. +-- @param n A relative or absolute buffer index in `_G._BUFFERS`. An absolute +-- index of `-1` goes to the last buffer. -- @param relative Flag indicating if `n` is a relative index or not. The -- default value is `false`. -function view:goto_buffer(n, relative) end +-- @see _G._G._BUFFERS +-- @see events.BUFFER_BEFORE_SWITCH +-- @see events.BUFFER_AFTER_SWITCH +function goto_buffer(view, n, relative) end diff --git a/core/args.lua b/core/args.lua index 687735ce..a7c56c90 100644 --- a/core/args.lua +++ b/core/args.lua @@ -9,7 +9,7 @@ local M = {} -- ## Arg Events -- -- + `'arg_none'` --- Called when no command line arguments are passed to Textadept on init. +-- Called when no command line arguments are passed to Textadept on startup. module('args')]] local arg = arg @@ -25,7 +25,7 @@ local switches = {} -- @param switch2 String switch (long version). -- @param narg The number of expected parameters for the switch. -- @param f The Lua function to run when the switch is tripped. --- @param description Description of the switch. +-- @param description Description of the switch for command line help. -- @name register function M.register(switch1, switch2, narg, f, description) local t = { f, narg, description } @@ -36,9 +36,10 @@ end -- Processes command line arguments. -- Add command line switches with `args.register()`. Any unrecognized arguments -- are treated as filepaths and opened. --- Generates an `'arg_none'` event when no args are present. +-- Emits an `'arg_none'` event when no args are present. -- @param arg Argument table. -- @see register +-- @see events -- @name process function M.process(arg) local no_args = true @@ -94,7 +95,7 @@ if not lfs.attributes(userhome) then lfs.mkdir(userhome) end if not lfs.attributes(userhome..'/init.lua') then local f = io.open(userhome..'/init.lua', 'w') if f then - f:write("require 'textadept'\n") + f:write("_M.textadept = require 'textadept'\n") f:close() end end diff --git a/core/events.lua b/core/events.lua index fabd52e5..3ee2e333 100644 --- a/core/events.lua +++ b/core/events.lua @@ -8,244 +8,262 @@ local M = {} -- -- ## Overview -- --- Textadept is very event-driven. Most of its functionality comes through event --- handlers. Events occur when you create a new buffer, press a key, click on a --- menu, etc. You can even make an event occur with Lua code. Instead of having --- a single event handler however, each event can have a set of handlers. These --- handlers are simply Lua functions that are called in the order they were --- added to an event. This enables dynamically loaded modules to add their own --- handlers to events. +-- Events occur when you do things like create a new buffer, press a key, click +-- on a menu, etc. You can even emit events yourself using Lua. Each event has a +-- set of event handlers, which are simply Lua functions called in the order +-- they were connected to an event. This enables dynamically loaded modules to +-- connect to events. -- -- Events themselves are nothing special. They do not have to be declared in -- order to be used. They are simply strings containing an arbitrary event name. --- When an event of this name occurs, either generated by Textadept or you, all --- event handlers assigned to it are run. +-- When an event of this name is emitted, either by Textadept or you, all event +-- handlers assigned to it are run. Events can be given any number of arguments. +-- These arguments will be passed to the event's handler functions. If an event +-- handler returns a `true` or `false` boolean value explicitly, no subsequent +-- handlers are called. This is useful if you want to stop the propagation of an +-- event like a keypress if it has already been handled. -- --- Events can be given any number of arguments. These arguments will be passed --- to the event's handler functions. If a handler returns either true or false --- explicitly, all subsequent handlers are not called. This is useful if you --- want to stop the propagation of an event like a keypress. --- --- ## Textadept Events --- --- This is the set of default events that Textadept emits with the arguments --- they pass. Events that modules emit are listed on their respective LuaDoc --- pages. --- --- * `APPLEEVENT_ODOC` +-- @field APPLEEVENT_ODOC (string) -- Called when Mac OSX tells Textadept to open a document. --- * `uri`: The URI to open encoded in UTF-8. --- * `AUTO_C_CHAR_DELETED` +-- Arguments: +-- +-- * `uri`: The URI to open encoded in UTF-8. +-- @field AUTO_C_CHAR_DELETED (string) -- Called when the user deleted a character while the autocompletion list was -- active. --- * `AUTO_C_RELEASE` +-- @field AUTO_C_RELEASE (string) -- Called when the user has cancelled the autocompletion list. --- * `AUTO_C_SELECTION` +-- @field AUTO_C_SELECTION (string) -- Called when the user has selected an item in an autocompletion list and -- before the selection is inserted. -- Automatic insertion can be cancelled by calling -- [`buffer:auto_c_cancel()`][] before returning from the event handler. -- Arguments: --- * `text`: The text of the selection. --- * `position`: The start position of the word being completed. --- * `BUFFER_AFTER_SWITCH` +-- +-- * `text`: The text of the selection. +-- * `position`: The start position of the word being completed. +-- @field BUFFER_AFTER_SWITCH (string) -- Called right after a buffer is switched to. --- * `BUFFER_BEFORE_SWITCH` +-- This is emitted by [`view:goto_buffer()`][]. +-- @field BUFFER_BEFORE_SWITCH (string) -- Called right before another buffer is switched to. --- * `BUFFER_DELETED` +-- This is emitted by [`view:goto_buffer()`][]. +-- @field BUFFER_DELETED (string) -- Called after a buffer was deleted. --- * `BUFFER_NEW` +-- This is emitted by [`buffer:delete()`][]. +-- @field BUFFER_NEW (string) -- Called when a new buffer is created. --- * `CALL_TIP_CLICK` +-- This is emitted on startup and by [`new_buffer()`][]. +-- @field CALL_TIP_CLICK (string) -- Called when the user clicks on a calltip. -- Arguments: --- * `position`: Set to 1 if the click is in an up arrow, 2 if in a down --- arrow, and 0 if elsewhere. --- * `CHAR_ADDED` +-- +-- * `position`: Set to 1 if the click is in an up arrow, 2 if in a down +-- arrow, and 0 if elsewhere. +-- @field CHAR_ADDED (string) -- Called when an ordinary text character is added to the buffer. -- Arguments: --- * `ch`: The text character byte. --- * `COMMAND_ENTRY_COMMAND` +-- +-- * `ch`: The text character byte. +-- @field COMMAND_ENTRY_COMMAND (string) -- Called when a command is entered into the Command Entry. -- Arguments: --- * `command`: The command text. --- * `COMMAND_ENTRY_KEYPRESS` +-- +-- * `command`: The command text. +-- @field COMMAND_ENTRY_KEYPRESS (string) -- Called when a key is pressed in the Command Entry. -- Arguments: --- * `code`: The key code. --- * `shift`: The Shift key is held down. --- * `ctrl`: The Control/Command key is held down. --- * `alt`: The Alt/option key is held down. --- * `meta`: The Control key on Mac OSX is held down. --- * `DOUBLE_CLICK` +-- +-- * `code`: The key code. +-- * `shift`: The Shift key is held down. +-- * `ctrl`: The Control/Command key is held down. +-- * `alt`: The Alt/option key is held down. +-- * `meta`: The Control key on Mac OSX is held down. +-- @field DOUBLE_CLICK (string) -- Called when the mouse button is double-clicked. -- Arguments: --- * `position`: The text position of the double click. --- * `line`: The line of the double click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. --- * `DWELL_END` +-- +-- * `position`: The text position of the double click. +-- * `line`: The line of the double click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero or +-- more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK+. +-- @field DWELL_END (string) -- Called after a `DWELL_START` and the mouse is moved or other activity such -- as key press indicates the dwell is over. -- Arguments: --- * `position`: The nearest position in the document to the position where --- the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. --- * `DWELL_START` +-- +-- * `position`: The nearest position in the document to the position where +-- the mouse pointer was lingering. +-- * `x`: Where the pointer lingered. +-- * `y`: Where the pointer lingered. +-- @field DWELL_START (string) -- Called when the user keeps the mouse in one position for the dwell period -- (see `_SCINTILLA.constants.SCI_SETMOUSEDWELLTIME`). -- Arguments: --- * `position`: The nearest position in the document to the position where --- the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. --- * `ERROR` +-- +-- * `position`: The nearest position in the document to the position where +-- the mouse pointer was lingering. +-- * `x`: Where the pointer lingered. +-- * `y`: Where the pointer lingered. +-- @field ERROR (string) -- Called when an error occurs. -- Arguments: --- * `text`: The error text. --- * `FIND` +-- +-- * `text`: The error text. +-- @field FIND (string) -- Called when finding text via the Find dialog box. -- Arguments: --- * `text`: The text to search for. --- * `next`: Search forward. --- * `HOTSPOT_CLICK` +-- +-- * `text`: The text to search for. +-- * `next`: Search forward. +-- @field HOTSPOT_CLICK (string) -- Called when the user clicks on text that is in a style with the hotspot -- attribute set. -- Arguments: --- * `position`: The text position of the click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. --- * `HOTSPOT_DOUBLE_CLICK` +-- +-- * `position`: The text position of the click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero or +-- more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK+. +-- @field HOTSPOT_DOUBLE_CLICK (string) -- Called when the user double clicks on text that is in a style with the -- hotspot attribute set. -- Arguments: --- * `position`: The text position of the double click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. --- * `HOTSPOT_RELEASE_CLICK` +-- +-- * `position`: The text position of the double click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero or +-- more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK+. +-- @field HOTSPOT_RELEASE_CLICK (string) -- Called when the user releases the mouse on text that is in a style with the -- hotspot attribute set. -- Arguments: --- * `position`: The text position of the release. --- * `INDICATOR_CLICK` +-- +-- * `position`: The text position of the release. +-- @field INDICATOR_CLICK (string) -- Called when the user clicks the mouse on text that has an indicator. -- Arguments: --- * `position`: The text position of the click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. --- * `INDICATOR_RELEASE` +-- +-- * `position`: The text position of the click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero or +-- more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK+. +-- @field INDICATOR_RELEASE (string) -- Called when the user releases the mouse on text that has an indicator. -- Arguments: --- * `position`: The text position of the release. --- * `KEYPRESS` +-- +-- * `position`: The text position of the release. +-- @field KEYPRESS (string) -- Called when a key is pressed. -- Arguments: --- * `code`: The key code. --- * `shift`: The Shift key is held down. --- * `ctrl`: The Control/Command key is held down. --- * `alt`: The Alt/option key is held down. --- * `meta`: The Control key on Mac OSX is held down. --- * `MARGIN_CLICK` +-- +-- * `code`: The key code. +-- * `shift`: The Shift key is held down. +-- * `ctrl`: The Control/Command key is held down. +-- * `alt`: The Alt/option key is held down. +-- * `meta`: The Control key on Mac OSX is held down. +-- @field MARGIN_CLICK (string) -- Called when the mouse is clicked inside a margin. -- Arguments: --- * `margin`: The margin number that was clicked. --- * `position`: The position of the start of the line in the buffer that --- corresponds to the margin click. --- * `modifiers`: The appropriate combination of --- `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`, --- and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were --- held down at the time of the margin click. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. --- * `MENU_CLICKED` +-- +-- * `margin`: The margin number that was clicked. +-- * `position`: The position of the start of the line in the buffer that +-- corresponds to the margin click. +-- * `modifiers`: The appropriate combination of +-- `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`, +-- and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were held +-- down at the time of the margin click. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK+. +-- @field MENU_CLICKED (string) -- Called when a menu item is selected. -- Arguments: --- * `menu_id`: The numeric ID of the menu item set in [`gui.gtkmenu()`][]. --- * `QUIT` +-- +-- * `menu_id`: The numeric ID of the menu item set in [`gui.menu()`][]. +-- @field QUIT (string) -- Called when quitting Textadept. -- When connecting to this event, connect with an index of 1 or the handler -- will be ignored. --- * `REPLACE` +-- This is emitted by [`quit()`][]. +-- @field REPLACE (string) -- Called to replace selected (found) text. -- Arguments: --- * `text`: The text to replace selected text with. --- * `REPLACE_ALL` +-- +-- * `text`: The text to replace selected text with. +-- @field REPLACE_ALL (string) -- Called to replace all occurances of found text. -- Arguments: --- * `find_text`: The text to search for. --- * `repl_text`: The text to replace found text with. --- * `RESET_AFTER` +-- +-- * `find_text`: The text to search for. +-- * `repl_text`: The text to replace found text with. +-- @field RESET_AFTER (string) -- Called after resetting the Lua state. --- This is triggered by [`reset()`][]. --- * `RESET_BEFORE` +-- This is emitted by [`reset()`][]. +-- @field RESET_BEFORE (string) -- Called before resetting the Lua state. --- This is triggered by [`reset()`][]. --- * `SAVE_POINT_LEFT` +-- This is emitted by [`reset()`][]. +-- @field SAVE_POINT_LEFT (string) -- Called when a save point is left. --- * `SAVE_POINT_REACHED` +-- @field SAVE_POINT_REACHED (string) -- Called when a save point is entered. --- * `UPDATE_UI` +-- @field UPDATE_UI (string) -- Called when either the text or styling of the buffer has changed or the -- selection range has changed. --- * `URI_DROPPED` +-- @field URI_DROPPED (string) -- Called when the user has dragged a URI such as a file name onto the view. -- Arguments: --- * `text`: The URI text encoded in UTF-8. --- * `USER_LIST_SELECTION` +-- +-- * `text`: The URI text encoded in UTF-8. +-- @field USER_LIST_SELECTION (string) -- Called when the user has selected an item in a user list. -- Arguments: --- * `list_type`: This is set to the list_type parameter from the --- [`buffer:user_list_show()`][] call that initiated the list. --- * `text`: The text of the selection. --- * `position`: The position the list was displayed at. --- * `VIEW_NEW` +-- +-- * `list_type`: This is set to the list_type parameter from the +-- [`buffer:user_list_show()`][] call that initiated the list. +-- * `text`: The text of the selection. +-- * `position`: The position the list was displayed at. +-- @field VIEW_NEW (string) -- Called when a new view is created. --- * `VIEW_BEFORE_SWITCH` +-- This is emitted on startup and by [`view:split()`][]. +-- @field VIEW_BEFORE_SWITCH (string) -- Called right before another view is switched to. --- * `VIEW_AFTER_SWITCH` +-- This is emitted by [`gui.goto_view()`][]. +-- @field VIEW_AFTER_SWITCH (string) -- Called right after another view is switched to. +-- This is emitted by [`gui.goto_view()`][]. -- --- [`buffer:auto_c_cancel()`]: buffer.html#buffer.auto_c_cancel --- [`gui.gtkmenu()`]: gui.html#gtkmenu +-- [`buffer:auto_c_cancel()`]: buffer.html#auto_c_cancel +-- [`view:goto_buffer()`]: view.html#goto_buffer +-- [`new_buffer()`]: _G.html#new_buffer +-- [`buffer:delete()`]: buffer.html#delete +-- [`gui.menu()`]: gui.html#menu +-- [`quit()`]: _G.html#quit -- [`reset()`]: _G.html#reset --- [`buffer:user_list_show()`]: buffer.html#buffer.user_list_show --- --- ## Example --- --- The following Lua code generates and handles a custom `my_event` event: --- --- function my_event_handler(message) --- gui.print(message) --- end --- --- events.connect('my_event', my_event_handler) --- events.emit('my_event', 'my message') -- prints 'my message' to a view +-- [`buffer:user_list_show()`]: buffer.html#user_list_show +-- [`view:split()`]: view.html#split +-- [`gui.goto_view()`]: gui.html#goto_view module('events')]] --- @@ -256,11 +274,12 @@ M.handlers = {} --- -- Adds a handler function to an event. --- @param event The string event name. It is arbitrary and need not be defined --- anywhere. +-- @param event The string event name. It is arbitrary and does not need to be +-- defined previously. -- @param f The Lua function to add. -- @param index Optional index to insert the handler into. -- @return Index of handler. +-- @usage events.connect('my_event', function(message) gui.print(message) end) -- @see disconnect -- @name connect function M.connect(event, f, index) @@ -274,7 +293,7 @@ end --- -- Disconnects a handler function from an event. -- @param event The string event name. --- @param index Index of the handler (returned by `events.connect()`). +-- @param index Index of the handler returned by `events.connect()`. -- @see connect -- @name disconnect function M.disconnect(event, index) @@ -285,14 +304,16 @@ end local error_emitted = false --- --- Calls all handlers for the given event in sequence (effectively "generating" --- the event). +-- Calls all handlers for the given event in sequence. -- If `true` or `false` is explicitly returned by any handler, the event is not --- propagated any further; iteration ceases. --- @param event The string event name. +-- propagated any further; iteration ceases. This is useful if you want to stop +-- the propagation of an event like a keypress. +-- @param event The string event name. It is arbitrary and does not need to be +-- defined previously. -- @param ... Arguments passed to the handler. --- @return `true` or `false` if any handler explicitly returned such; nil +-- @return `true` or `false` if any handler explicitly returned such; `nil` -- otherwise. +-- @usage events.emit('my_event', 'my message') -- @name emit function M.emit(event, ...) if not event then error(_L['Undefined event name']) end diff --git a/core/file_io.lua b/core/file_io.lua index 36417661..0ea94bca 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -2,18 +2,16 @@ --[[ This comment is for LuaDoc. --- --- Extends Lua's io package to provide file input/output routines for Textadept. +-- Extends Lua's `io` package with Textadept functions for working with files. -- -- ## Working with UTF-8 -- --- If your filesystem does not use UTF-8 encoded filenames, conversions to and --- from that encoding are necessary since all of Textadept's internal strings --- are UTF-8 encoded. When opening and saving files through dialogs, these --- conversions are performed autmatically, but if you need to do them manually, --- use [`string.iconv()`][] along with `_CHARSET`, your filesystem's detected --- encoding. --- --- Example: +-- If your filesystem does not use UTF-8 encoded filenames (e.g. Windows), +-- conversions to and from that encoding are necessary since all of Textadept's +-- internal strings are UTF-8 encoded. When opening and saving files through +-- dialogs, these conversions are performed automatically, but if you need to do +-- them manually, use [`string.iconv()`][] along with [`_CHARSET`][], your +-- filesystem's detected encoding. An example is -- -- events.connect(events.FILE_OPENED, function(utf8_filename) -- local filename = utf8_filename:iconv(_CHARSET, 'UTF-8') @@ -23,25 +21,33 @@ -- end) -- -- [`string.iconv()`]: string.html#iconv +-- [`_CHARSET`]: _G.html#_CHARSET -- -- ## File Events -- -- * `_G.events.FILE_OPENED` -- Called when a file is opened in a new buffer. +-- This is emitted by [`open_file()`](#open_file) -- Arguments: -- * `filename`: The filename encoded in UTF-8. -- * `_G.events.FILE_BEFORE_SAVE` -- Called right before a file is saved to disk. +-- This is emitted by [`buffer:save()`][] -- Arguments: -- * `filename`: The filename encoded in UTF-8. -- * `_G.events.FILE_AFTER_SAVE` -- Called right after a file is saved to disk. +-- This is emitted by [`buffer:save()`][] -- Arguments: -- * `filename`: The filename encoded in UTF-8. -- * `_G.events.FILE_SAVED_AS` -- Called when a file is saved under a different filename. +-- This is emitted by [`buffer:save_as()`][] -- Arguments: -- * `filename`: The filename encoded in UTF-8. +-- +-- [`buffer:save()`]: buffer.html#save +-- [`buffer:save_as()`]: buffer.html#save_as module('io')]] -- Events. @@ -59,7 +65,7 @@ events.FILE_SAVED_AS = 'file_saved_as' io.recent_files = {} --- --- List of byte-order marks (BOMs). +-- List of byte-order marks (BOMs) for identifying unicode file types. -- @class table -- @name boms io.boms = { @@ -94,16 +100,23 @@ local function detect_encoding(text) end --- --- List of encodings to try to decode files as after UTF-8. +-- List of encodings to try to decode files as. +-- You should add to this list if you get a "Conversion failed" error when +-- trying to open a file whose encoding is not recognized. Valid encodings are +-- [GNU iconv's encodings][]. +-- +-- [GNU iconv's encodings]: http://www.gnu.org/software/libiconv/ -- @class table -- @name try_encodings io.try_encodings = { 'UTF-8', 'ASCII', 'ISO-8859-1', 'MacRoman' } --- -- Opens a list of files. +-- Emits a `FILE_OPENED` event. -- @param utf8_filenames A `\n` separated list of UTF-8-encoded filenames to -- open. If `nil`, the user is prompted with a fileselect dialog. -- @usage io.open_file(utf8_encoded_filename) +-- @see _G.events -- @name open_file function io.open_file(utf8_filenames) utf8_filenames = utf8_filenames or @@ -259,6 +272,7 @@ end --- -- Saves all dirty buffers to their respective files. -- @usage io.save_all() +-- @see buffer.save -- @name save_all function io.save_all() local current_buffer = _BUFFERS[buffer] @@ -281,7 +295,7 @@ local function close(buffer) '--button1', _L['_Cancel'], '--button2', _L['Close _without saving'], '--no-newline') ~= '2' then - return false + return nil -- returning false can cause unwanted key command propagation end buffer:delete() return true @@ -293,6 +307,7 @@ end -- saved automatically. They must be saved manually. -- @usage io.close_all() -- @return `true` if user did not cancel. +-- @see buffer.close -- @name close_all function io.close_all() while #_BUFFERS > 1 do diff --git a/core/gui.lua b/core/gui.lua index 4431d350..c6170a8b 100644 --- a/core/gui.lua +++ b/core/gui.lua @@ -3,17 +3,18 @@ local gui = gui --[[ This comment is for LuaDoc. ---- The core gui table. +--- +-- Utilities for Textadept's user interface. -- @field title (string, Write-only) -- The title of the Textadept window. -- @field context_menu --- A `gui.menu` defining the editor's context menu. +-- A [`gui.menu`](#menu) defining the editor's context menu. -- @field clipboard_text (string, Read-only) -- The text on the clipboard. -- @field statusbar_text (string, Write-only) -- The text displayed by the statusbar. -- @field docstatusbar_text (string, Write-only) --- The text displayed by the doc statusbar. +-- The text displayed by the buffer statusbar. module('gui')]] local _L = _L @@ -45,10 +46,10 @@ local function _print(buffer_type, ...) end --- -- Helper function for printing messages to buffers. --- Splits the view and opens a new buffer for printing messages. If the message --- buffer is already open and a view is currently showing it, the message is --- printed to that view. Otherwise the view is split, goes to the open message --- buffer, and prints to it. +-- Splits the view and opens a new buffer for printing messages to. If the +-- message buffer is already open in a view, the message is printed to that +-- view. Otherwise the view is split and the message buffer is opened or +-- displayed before being printed to. -- @param buffer_type String type of message buffer. -- @param ... Message strings. -- @usage gui._print(_L['[Error Buffer]'], error_message) @@ -58,26 +59,27 @@ function gui._print(buffer_type, ...) pcall(_print, buffer_type, ...) end --- -- Prints messages to the Textadept message buffer. --- Opens a new buffer (if one has not already been opened) for printing --- messages. +-- Opens a new buffer if one has not already been opened for printing messages. -- @param ... Message strings. -- @name print function gui.print(...) gui._print(_L['[Message Buffer]'], ...) end --- --- Shortcut function for `gui.dialog('filtered_list', ...)` with 'Ok' and +-- Shortcut function for `gui.dialog('filteredlist', ...)` with 'Ok' and -- 'Cancel' buttons. --- @param title The title for the filteredlist dialog. +-- @param title The title for the filtered list dialog. -- @param columns A column name or list of column names. -- @param items An item or list of items. -- @param int_return If `true`, returns the integer index of the selected item --- in the filteredlist. The default value is `false`, which returns the string --- item. Not compatible with a `'--select-multiple'` filteredlist. +-- in the filtered list and is not compatible with the `'--select-multiple'` +-- option. The default value is `false`, which returns the string item(s). -- @param ... Additional parameters to pass to `gui.dialog()`. --- @return Either a string or integer on success; `nil` otherwise. +-- @return Either a string or integer on success; `nil` otherwise. In strings, +-- multiple items are separated by newlines. -- @usage gui.filteredlist('Title', 'Foo', { 'Bar', 'Baz' }) -- @usage gui.filteredlist('Title', { 'Foo', 'Bar' }, { 'a', 'b', 'c', 'd' }, -- false, '--output-column', '2') +-- @see dialog -- @name filteredlist function gui.filteredlist(title, columns, items, int_return, ...) local out = gui.dialog('filteredlist', @@ -151,11 +153,11 @@ local theme_file = not NCURSES and 'theme' or 'theme_term' local THEME --- -- Sets the editor theme from the given name. --- Themes in `_USERHOME/themes/` are checked first, followed by `_HOME/themes/`. --- If the name contains slashes ('/' on Linux and Mac OSX and '\' on Win32), it --- is assumed to be an absolute path so `_USERHOME` and `_HOME` are not checked. --- Throws an error if the theme is not found. Any errors in the theme are --- printed to `io.stderr`. +-- Themes with the given name in the `_USERHOME/themes/` directory override +-- themes of the same name in `_HOME/themes/`. If the name contains slashes (`\` +-- on Windows, `/` otherwise), it is assumed to be an absolute path to a theme +-- instead of a theme name. An error is thrown if the theme is not found. Any +-- errors in the theme are printed to `io.stderr`. -- @param name The name or absolute path of a theme. If nil, sets the default -- theme. -- @name set_theme @@ -210,7 +212,8 @@ function gui.set_theme(name) end --- --- Prompts the user to select an editor theme from a filtered list. +-- Prompts the user to select an editor theme from a filtered list dialog. +-- Themes in the `_HOME/themes/` and `_USERHOME/themes/` directories are listed. -- @name select_theme function gui.select_theme() local themes, themes_found = {}, {} @@ -425,12 +428,13 @@ events_connect(events.ERROR, --- -- A table of menus defining a menubar. (Write-only) +-- @see _M.textadept.menu.set_menubar -- @class table -- @name menubar local menubar --- --- The size of the Textadept window (`{ width, height }`). +-- A table containing the width and height values of the Textadept window. -- @class table -- @name size local size @@ -438,12 +442,13 @@ local size The functions below are Lua C functions. --- --- Displays a gtdialog of a specified type with the given string arguments. +-- Displays a [gtdialog][1] of a specified type with the given string arguments. -- Each argument is like a string in Lua's `arg` table. Tables of strings are -- allowed as arguments and are expanded in place. This is useful for --- filteredlist dialogs with many items. --- For more information on gtdialog, see [http://foicica.com/gtdialog]( --- http://foicica.com/gtdialog). +-- filtered list dialogs with many items. +-- For more information on gtdialog, see [http://foicica.com/gtdialog][1]. +-- +-- [1]: http://foicica.com/gtdialog -- @param kind The kind of gtdialog. -- @param ... Parameters to the gtdialog. -- @return string gtdialog result. @@ -453,6 +458,7 @@ local dialog --- -- Gets the current split view structure. +-- This is primarily used in session saving. -- @return table of split views. Each split view entry is a table with 4 -- fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either -- nested split view entries or the views themselves; `vertical` is a flag @@ -464,16 +470,22 @@ local get_split_table --- -- Goes to the specified view. --- Generates `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events. --- @param n A relative or absolute view index. +-- Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events. +-- @param n A relative or absolute view index in `_G._VIEWS`. -- @param relative Flag indicating if n is a relative index or not. The default -- value is `false`. +-- @see _G._G._VIEWS +-- @see events.VIEW_BEFORE_SWITCH +-- @see events.VIEW_AFTER_SWITCH -- @class function -- @name goto_view local goto_view --- -- Creates a menu, returning the userdata. +-- This is a low-level function. You probably want to use the higher-level +-- `_M.textadept.menu.set_menubar()` or `_M.textadept.menu.set_contextmenu()` +-- functions. Emits a `MENU_CLICKED` event when a menu item is selected. -- @param menu_table A table defining the menu. It is an ordered list of tables -- with a string menu item, integer menu ID, and optional GDK keycode and -- modifier mask. The latter two are used to display key shortcuts in the @@ -481,8 +493,10 @@ local goto_view -- empty, a menu separator item is created. Submenus are just nested -- menu-structure tables. Their title text is defined with a `title` key. -- @usage gui.menu{ { '_New', 1 }, { '_Open', 2 }, { '' }, { '_Quit', 4 } } --- @usage gui.menu{ { '_New', 1, keys.get_gdk_key('cn') } } --- @see keys.get_gdk_key +-- @usage gui.menu{ { '_New', 1, string.byte('n'), 4 } } -- 'Ctrl+N' +-- @see events.MENU_CLICKED +-- @see _M.textadept.menu.set_menubar +-- @see _M.textadept.menu.set_contextmenu -- @class function -- @name menu local menu diff --git a/core/iface.lua b/core/iface.lua index 84aaf241..db6d0f85 100644 --- a/core/iface.lua +++ b/core/iface.lua @@ -5,23 +5,42 @@ local M = {} --[[ This comment is for LuaDoc. --- -- Scintilla constants, functions, and properties. --- Do not modify anything in this module. Doing so will result in instability. +-- Do not modify anything in this module. Doing so will have unpredicable +-- consequences. module('_SCINTILLA')]] --- -- Scintilla constants. +-- Each key is a Scintilla constant with its associated numeric value. -- @class table -- @name constants M.constants = {ANNOTATION_BOXED=2,ANNOTATION_HIDDEN=0,ANNOTATION_STANDARD=1,CARETSTYLE_BLOCK=2,CARETSTYLE_INVISIBLE=0,CARETSTYLE_LINE=1,CARET_EVEN=0x08,CARET_JUMPS=0x10,CARET_SLOP=0x01,CARET_STRICT=0x04,EDGE_BACKGROUND=2,EDGE_LINE=1,EDGE_NONE=0,INDIC0_MASK=0x20,INDIC1_MASK=0x40,INDIC2_MASK=0x80,INDICS_MASK=0xE0,INDIC_BOX=6,INDIC_CONTAINER=8,INDIC_DASH=9,INDIC_DIAGONAL=3,INDIC_DOTBOX=12,INDIC_DOTS=10,INDIC_HIDDEN=5,INDIC_MAX=31,INDIC_PLAIN=0,INDIC_ROUNDBOX=7,INDIC_SQUIGGLE=1,INDIC_SQUIGGLELOW=11,INDIC_SQUIGGLEPIXMAP=13,INDIC_STRAIGHTBOX=8,INDIC_STRIKE=4,INDIC_TT=2,INVALID_POSITION=-1,KEYWORDSET_MAX=8,MARKER_MAX=31,SCEN_CHANGE=768,SCEN_KILLFOCUS=256,SCEN_SETFOCUS=512,SCFIND_MATCHCASE=4,SCFIND_POSIX=0x00400000,SCFIND_REGEXP=0x00200000,SCFIND_WHOLEWORD=2,SCFIND_WORDSTART=0x00100000,SCI_ANNOTATIONGETLINES=2546,SCI_ANNOTATIONGETSTYLE=2543,SCI_ANNOTATIONGETSTYLEOFFSET=2551,SCI_ANNOTATIONGETSTYLES=2545,SCI_ANNOTATIONGETTEXT=2541,SCI_ANNOTATIONGETVISIBLE=2549,SCI_ANNOTATIONSETSTYLE=2542,SCI_ANNOTATIONSETSTYLEOFFSET=2550,SCI_ANNOTATIONSETSTYLES=2544,SCI_ANNOTATIONSETTEXT=2540,SCI_ANNOTATIONSETVISIBLE=2548,SCI_AUTOCGETAUTOHIDE=2119,SCI_AUTOCGETCANCELATSTART=2111,SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR=2635,SCI_AUTOCGETCHOOSESINGLE=2114,SCI_AUTOCGETCURRENT=2445,SCI_AUTOCGETCURRENTTEXT=2610,SCI_AUTOCGETDROPRESTOFWORD=2271,SCI_AUTOCGETIGNORECASE=2116,SCI_AUTOCGETMAXHEIGHT=2211,SCI_AUTOCGETMAXWIDTH=2209,SCI_AUTOCGETSEPARATOR=2107,SCI_AUTOCGETTYPESEPARATOR=2285,SCI_AUTOCSETAUTOHIDE=2118,SCI_AUTOCSETCANCELATSTART=2110,SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR=2634,SCI_AUTOCSETCHOOSESINGLE=2113,SCI_AUTOCSETDROPRESTOFWORD=2270,SCI_AUTOCSETFILLUPS=2112,SCI_AUTOCSETIGNORECASE=2115,SCI_AUTOCSETMAXHEIGHT=2210,SCI_AUTOCSETMAXWIDTH=2208,SCI_AUTOCSETSEPARATOR=2106,SCI_AUTOCSETTYPESEPARATOR=2286,SCI_CALLTIPSETBACK=2205,SCI_CALLTIPSETFORE=2206,SCI_CALLTIPSETFOREHLT=2207,SCI_CALLTIPSETPOSITION=2213,SCI_CALLTIPUSESTYLE=2212,SCI_GETADDITIONALCARETFORE=2605,SCI_GETADDITIONALCARETSBLINK=2568,SCI_GETADDITIONALCARETSVISIBLE=2609,SCI_GETADDITIONALSELALPHA=2603,SCI_GETADDITIONALSELECTIONTYPING=2566,SCI_GETALLLINESVISIBLE=2236,SCI_GETANCHOR=2009,SCI_GETBACKSPACEUNINDENTS=2263,SCI_GETBUFFEREDDRAW=2034,SCI_GETCARETFORE=2138,SCI_GETCARETLINEBACK=2097,SCI_GETCARETLINEBACKALPHA=2471,SCI_GETCARETLINEVISIBLE=2095,SCI_GETCARETPERIOD=2075,SCI_GETCARETSTICKY=2457,SCI_GETCARETSTYLE=2513,SCI_GETCARETWIDTH=2189,SCI_GETCHARACTERPOINTER=2520,SCI_GETCHARAT=2007,SCI_GETCODEPAGE=2137,SCI_GETCOLUMN=2129,SCI_GETCONTROLCHARSYMBOL=2389,SCI_GETCURRENTPOS=2008,SCI_GETCURSOR=2387,SCI_GETDIRECTFUNCTION=2184,SCI_GETDIRECTPOINTER=2185,SCI_GETDOCPOINTER=2357,SCI_GETEDGECOLOUR=2364,SCI_GETEDGECOLUMN=2360,SCI_GETEDGEMODE=2362,SCI_GETENDATLASTLINE=2278,SCI_GETENDSTYLED=2028,SCI_GETEOLMODE=2030,SCI_GETEXTRAASCENT=2526,SCI_GETEXTRADESCENT=2528,SCI_GETFIRSTVISIBLELINE=2152,SCI_GETFOCUS=2381,SCI_GETFOLDEXPANDED=2230,SCI_GETFOLDLEVEL=2223,SCI_GETFOLDPARENT=2225,SCI_GETFONTQUALITY=2612,SCI_GETGAPPOSITION=2644,SCI_GETHIGHLIGHTGUIDE=2135,SCI_GETHOTSPOTACTIVEUNDERLINE=2496,SCI_GETHOTSPOTSINGLELINE=2497,SCI_GETHSCROLLBAR=2131,SCI_GETIDENTIFIER=2623,SCI_GETINDENT=2123,SCI_GETINDENTATIONGUIDES=2133,SCI_GETINDICATORCURRENT=2501,SCI_GETINDICATORVALUE=2503,SCI_GETKEYSUNICODE=2522,SCI_GETLAYOUTCACHE=2273,SCI_GETLENGTH=2006,SCI_GETLEXER=4002,SCI_GETLEXERLANGUAGE=4012,SCI_GETLINECOUNT=2154,SCI_GETLINEENDPOSITION=2136,SCI_GETLINEINDENTATION=2127,SCI_GETLINEINDENTPOSITION=2128,SCI_GETLINESTATE=2093,SCI_GETLINEVISIBLE=2228,SCI_GETMAINSELECTION=2575,SCI_GETMARGINCURSORN=2249,SCI_GETMARGINLEFT=2156,SCI_GETMARGINMASKN=2245,SCI_GETMARGINOPTIONS=2557,SCI_GETMARGINRIGHT=2158,SCI_GETMARGINSENSITIVEN=2247,SCI_GETMARGINTYPEN=2241,SCI_GETMARGINWIDTHN=2243,SCI_GETMAXLINESTATE=2094,SCI_GETMODEVENTMASK=2378,SCI_GETMODIFY=2159,SCI_GETMOUSEDOWNCAPTURES=2385,SCI_GETMOUSEDWELLTIME=2265,SCI_GETMULTIPASTE=2615,SCI_GETMULTIPLESELECTION=2564,SCI_GETOVERTYPE=2187,SCI_GETPASTECONVERTENDINGS=2468,SCI_GETPOSITIONCACHE=2515,SCI_GETPRINTCOLOURMODE=2149,SCI_GETPRINTMAGNIFICATION=2147,SCI_GETPRINTWRAPMODE=2407,SCI_GETPROPERTY=4008,SCI_GETPROPERTYEXPANDED=4009,SCI_GETPROPERTYINT=4010,SCI_GETPUNCTUATIONCHARS=2649,SCI_GETREADONLY=2140,SCI_GETRECTANGULARSELECTIONANCHOR=2591,SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE=2595,SCI_GETRECTANGULARSELECTIONCARET=2589,SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE=2593,SCI_GETRECTANGULARSELECTIONMODIFIER=2599,SCI_GETSCROLLWIDTH=2275,SCI_GETSCROLLWIDTHTRACKING=2517,SCI_GETSEARCHFLAGS=2199,SCI_GETSELALPHA=2477,SCI_GETSELECTIONEMPTY=2650,SCI_GETSELECTIONEND=2145,SCI_GETSELECTIONMODE=2423,SCI_GETSELECTIONNANCHOR=2579,SCI_GETSELECTIONNANCHORVIRTUALSPACE=2583,SCI_GETSELECTIONNCARET=2577,SCI_GETSELECTIONNCARETVIRTUALSPACE=2581,SCI_GETSELECTIONNEND=2587,SCI_GETSELECTIONNSTART=2585,SCI_GETSELECTIONS=2570,SCI_GETSELECTIONSTART=2143,SCI_GETSELEOLFILLED=2479,SCI_GETSTATUS=2383,SCI_GETSTYLEAT=2010,SCI_GETSTYLEBITS=2091,SCI_GETSTYLEBITSNEEDED=4011,SCI_GETTABINDENTS=2261,SCI_GETTABWIDTH=2121,SCI_GETTAG=2616,SCI_GETTARGETEND=2193,SCI_GETTARGETSTART=2191,SCI_GETTECHNOLOGY=2631,SCI_GETTEXTLENGTH=2183,SCI_GETTWOPHASEDRAW=2283,SCI_GETUNDOCOLLECTION=2019,SCI_GETUSETABS=2125,SCI_GETVIEWEOL=2355,SCI_GETVIEWWS=2020,SCI_GETVIRTUALSPACEOPTIONS=2597,SCI_GETVSCROLLBAR=2281,SCI_GETWHITESPACECHARS=2647,SCI_GETWHITESPACESIZE=2087,SCI_GETWORDCHARS=2646,SCI_GETWRAPINDENTMODE=2473,SCI_GETWRAPMODE=2269,SCI_GETWRAPSTARTINDENT=2465,SCI_GETWRAPVISUALFLAGS=2461,SCI_GETWRAPVISUALFLAGSLOCATION=2463,SCI_GETXOFFSET=2398,SCI_GETZOOM=2374,SCI_INDICGETALPHA=2524,SCI_INDICGETFORE=2083,SCI_INDICGETOUTLINEALPHA=2559,SCI_INDICGETSTYLE=2081,SCI_INDICGETUNDER=2511,SCI_INDICSETALPHA=2523,SCI_INDICSETFORE=2082,SCI_INDICSETOUTLINEALPHA=2558,SCI_INDICSETSTYLE=2080,SCI_INDICSETUNDER=2510,SCI_LEXER_START=4000,SCI_LINESONSCREEN=2370,SCI_MARGINGETSTYLE=2533,SCI_MARGINGETSTYLEOFFSET=2538,SCI_MARGINGETSTYLES=2535,SCI_MARGINGETTEXT=2531,SCI_MARGINSETSTYLE=2532,SCI_MARGINSETSTYLEOFFSET=2537,SCI_MARGINSETSTYLES=2534,SCI_MARGINSETTEXT=2530,SCI_MARKERSETALPHA=2476,SCI_MARKERSETBACK=2042,SCI_MARKERSETBACKSELECTED=2292,SCI_MARKERSETFORE=2041,SCI_OPTIONAL_START=3000,SCI_RGBAIMAGESETHEIGHT=2625,SCI_RGBAIMAGESETSCALE=2651,SCI_RGBAIMAGESETWIDTH=2624,SCI_SELECTIONISRECTANGLE=2372,SCI_SETADDITIONALCARETFORE=2604,SCI_SETADDITIONALCARETSBLINK=2567,SCI_SETADDITIONALCARETSVISIBLE=2608,SCI_SETADDITIONALSELALPHA=2602,SCI_SETADDITIONALSELBACK=2601,SCI_SETADDITIONALSELECTIONTYPING=2565,SCI_SETADDITIONALSELFORE=2600,SCI_SETANCHOR=2026,SCI_SETBACKSPACEUNINDENTS=2262,SCI_SETBUFFEREDDRAW=2035,SCI_SETCARETFORE=2069,SCI_SETCARETLINEBACK=2098,SCI_SETCARETLINEBACKALPHA=2470,SCI_SETCARETLINEVISIBLE=2096,SCI_SETCARETPERIOD=2076,SCI_SETCARETSTICKY=2458,SCI_SETCARETSTYLE=2512,SCI_SETCARETWIDTH=2188,SCI_SETCODEPAGE=2037,SCI_SETCONTROLCHARSYMBOL=2388,SCI_SETCURRENTPOS=2141,SCI_SETCURSOR=2386,SCI_SETDOCPOINTER=2358,SCI_SETEDGECOLOUR=2365,SCI_SETEDGECOLUMN=2361,SCI_SETEDGEMODE=2363,SCI_SETENDATLASTLINE=2277,SCI_SETEOLMODE=2031,SCI_SETEXTRAASCENT=2525,SCI_SETEXTRADESCENT=2527,SCI_SETFIRSTVISIBLELINE=2613,SCI_SETFOCUS=2380,SCI_SETFOLDEXPANDED=2229,SCI_SETFOLDFLAGS=2233,SCI_SETFOLDLEVEL=2222,SCI_SETFONTQUALITY=2611,SCI_SETHIGHLIGHTGUIDE=2134,SCI_SETHOTSPOTACTIVEUNDERLINE=2412,SCI_SETHOTSPOTSINGLELINE=2421,SCI_SETHSCROLLBAR=2130,SCI_SETIDENTIFIER=2622,SCI_SETINDENT=2122,SCI_SETINDENTATIONGUIDES=2132,SCI_SETINDICATORCURRENT=2500,SCI_SETINDICATORVALUE=2502,SCI_SETKEYSUNICODE=2521,SCI_SETKEYWORDS=4005,SCI_SETLAYOUTCACHE=2272,SCI_SETLEXER=4001,SCI_SETLEXERLANGUAGE=4006,SCI_SETLINEINDENTATION=2126,SCI_SETLINESTATE=2092,SCI_SETMAINSELECTION=2574,SCI_SETMARGINCURSORN=2248,SCI_SETMARGINLEFT=2155,SCI_SETMARGINMASKN=2244,SCI_SETMARGINOPTIONS=2539,SCI_SETMARGINRIGHT=2157,SCI_SETMARGINSENSITIVEN=2246,SCI_SETMARGINTYPEN=2240,SCI_SETMARGINWIDTHN=2242,SCI_SETMODEVENTMASK=2359,SCI_SETMOUSEDOWNCAPTURES=2384,SCI_SETMOUSEDWELLTIME=2264,SCI_SETMULTIPASTE=2614,SCI_SETMULTIPLESELECTION=2563,SCI_SETOVERTYPE=2186,SCI_SETPASTECONVERTENDINGS=2467,SCI_SETPOSITIONCACHE=2514,SCI_SETPRINTCOLOURMODE=2148,SCI_SETPRINTMAGNIFICATION=2146,SCI_SETPRINTWRAPMODE=2406,SCI_SETPROPERTY=4004,SCI_SETPUNCTUATIONCHARS=2648,SCI_SETREADONLY=2171,SCI_SETRECTANGULARSELECTIONANCHOR=2590,SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE=2594,SCI_SETRECTANGULARSELECTIONCARET=2588,SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE=2592,SCI_SETRECTANGULARSELECTIONMODIFIER=2598,SCI_SETSCROLLWIDTH=2274,SCI_SETSCROLLWIDTHTRACKING=2516,SCI_SETSEARCHFLAGS=2198,SCI_SETSELALPHA=2478,SCI_SETSELECTIONEND=2144,SCI_SETSELECTIONMODE=2422,SCI_SETSELECTIONNANCHOR=2578,SCI_SETSELECTIONNANCHORVIRTUALSPACE=2582,SCI_SETSELECTIONNCARET=2576,SCI_SETSELECTIONNCARETVIRTUALSPACE=2580,SCI_SETSELECTIONNEND=2586,SCI_SETSELECTIONNSTART=2584,SCI_SETSELECTIONSTART=2142,SCI_SETSELEOLFILLED=2480,SCI_SETSTATUS=2382,SCI_SETSTYLEBITS=2090,SCI_SETTABINDENTS=2260,SCI_SETTABWIDTH=2036,SCI_SETTARGETEND=2192,SCI_SETTARGETSTART=2190,SCI_SETTECHNOLOGY=2630,SCI_SETTWOPHASEDRAW=2284,SCI_SETUNDOCOLLECTION=2012,SCI_SETUSETABS=2124,SCI_SETVIEWEOL=2356,SCI_SETVIEWWS=2021,SCI_SETVIRTUALSPACEOPTIONS=2596,SCI_SETVSCROLLBAR=2280,SCI_SETWHITESPACECHARS=2443,SCI_SETWHITESPACESIZE=2086,SCI_SETWORDCHARS=2077,SCI_SETWRAPINDENTMODE=2472,SCI_SETWRAPMODE=2268,SCI_SETWRAPSTARTINDENT=2464,SCI_SETWRAPVISUALFLAGS=2460,SCI_SETWRAPVISUALFLAGSLOCATION=2462,SCI_SETXOFFSET=2397,SCI_SETZOOM=2373,SCI_START=2000,SCI_STYLEGETBACK=2482,SCI_STYLEGETBOLD=2483,SCI_STYLEGETCASE=2489,SCI_STYLEGETCHANGEABLE=2492,SCI_STYLEGETCHARACTERSET=2490,SCI_STYLEGETEOLFILLED=2487,SCI_STYLEGETFONT=2486,SCI_STYLEGETFORE=2481,SCI_STYLEGETHOTSPOT=2493,SCI_STYLEGETITALIC=2484,SCI_STYLEGETSIZE=2485,SCI_STYLEGETSIZEFRACTIONAL=2062,SCI_STYLEGETUNDERLINE=2488,SCI_STYLEGETVISIBLE=2491,SCI_STYLEGETWEIGHT=2064,SCI_STYLESETBACK=2052,SCI_STYLESETBOLD=2053,SCI_STYLESETCASE=2060,SCI_STYLESETCHANGEABLE=2099,SCI_STYLESETCHARACTERSET=2066,SCI_STYLESETEOLFILLED=2057,SCI_STYLESETFONT=2056,SCI_STYLESETFORE=2051,SCI_STYLESETHOTSPOT=2409,SCI_STYLESETITALIC=2054,SCI_STYLESETSIZE=2055,SCI_STYLESETSIZEFRACTIONAL=2061,SCI_STYLESETUNDERLINE=2059,SCI_STYLESETVISIBLE=2074,SCI_STYLESETWEIGHT=2063,SCK_ADD=310,SCK_BACK=8,SCK_DELETE=308,SCK_DIVIDE=312,SCK_DOWN=300,SCK_END=305,SCK_ESCAPE=7,SCK_HOME=304,SCK_INSERT=309,SCK_LEFT=302,SCK_MENU=315,SCK_NEXT=307,SCK_PRIOR=306,SCK_RETURN=13,SCK_RIGHT=303,SCK_RWIN=314,SCK_SUBTRACT=311,SCK_TAB=9,SCK_UP=301,SCK_WIN=313,SCMOD_ALT=4,SCMOD_CTRL=2,SCMOD_META=16,SCMOD_NORM=0,SCMOD_SHIFT=1,SCMOD_SUPER=8,SCVS_NONE=0,SCVS_RECTANGULARSELECTION=1,SCVS_USERACCESSIBLE=2,SCWS_INVISIBLE=0,SCWS_VISIBLEAFTERINDENT=2,SCWS_VISIBLEALWAYS=1,SC_ALPHA_NOALPHA=256,SC_ALPHA_OPAQUE=255,SC_ALPHA_TRANSPARENT=0,SC_CACHE_CARET=1,SC_CACHE_DOCUMENT=3,SC_CACHE_NONE=0,SC_CACHE_PAGE=2,SC_CARETSTICKY_OFF=0,SC_CARETSTICKY_ON=1,SC_CARETSTICKY_WHITESPACE=2,SC_CASEINSENSITIVEBEHAVIOUR_IGNORECASE=1,SC_CASEINSENSITIVEBEHAVIOUR_RESPECTCASE=0,SC_CASE_LOWER=2,SC_CASE_MIXED=0,SC_CASE_UPPER=1,SC_CHARSET_8859_15=1000,SC_CHARSET_ANSI=0,SC_CHARSET_ARABIC=178,SC_CHARSET_BALTIC=186,SC_CHARSET_CHINESEBIG5=136,SC_CHARSET_CYRILLIC=1251,SC_CHARSET_DEFAULT=1,SC_CHARSET_EASTEUROPE=238,SC_CHARSET_GB2312=134,SC_CHARSET_GREEK=161,SC_CHARSET_HANGUL=129,SC_CHARSET_HEBREW=177,SC_CHARSET_JOHAB=130,SC_CHARSET_MAC=77,SC_CHARSET_OEM=255,SC_CHARSET_RUSSIAN=204,SC_CHARSET_SHIFTJIS=128,SC_CHARSET_SYMBOL=2,SC_CHARSET_THAI=222,SC_CHARSET_TURKISH=162,SC_CHARSET_VIETNAMESE=163,SC_CP_UTF8=65001,SC_CURSORARROW=2,SC_CURSORNORMAL=-1,SC_CURSORREVERSEARROW=7,SC_CURSORWAIT=4,SC_EFF_QUALITY_ANTIALIASED=2,SC_EFF_QUALITY_DEFAULT=0,SC_EFF_QUALITY_LCD_OPTIMIZED=3,SC_EFF_QUALITY_MASK=0xF,SC_EFF_QUALITY_NON_ANTIALIASED=1,SC_EOL_CR=1,SC_EOL_CRLF=0,SC_EOL_LF=2,SC_FOLDFLAG_LEVELNUMBERS=0x0040,SC_FOLDFLAG_LINEAFTER_CONTRACTED=0x0010,SC_FOLDFLAG_LINEAFTER_EXPANDED=0x0008,SC_FOLDFLAG_LINEBEFORE_CONTRACTED=0x0004,SC_FOLDFLAG_LINEBEFORE_EXPANDED=0x0002,SC_FOLDLEVELBASE=0x400,SC_FOLDLEVELHEADERFLAG=0x2000,SC_FOLDLEVELNUMBERMASK=0x0FFF,SC_FOLDLEVELWHITEFLAG=0x1000,SC_FONT_SIZE_MULTIPLIER=100,SC_IV_LOOKBOTH=3,SC_IV_LOOKFORWARD=2,SC_IV_NONE=0,SC_IV_REAL=1,SC_LASTSTEPINUNDOREDO=0x100,SC_MARGINOPTION_NONE=0,SC_MARGINOPTION_SUBLINESELECT=1,SC_MARGIN_BACK=2,SC_MARGIN_FORE=3,SC_MARGIN_NUMBER=1,SC_MARGIN_RTEXT=5,SC_MARGIN_SYMBOL=0,SC_MARGIN_TEXT=4,SC_MARKNUM_FOLDER=30,SC_MARKNUM_FOLDEREND=25,SC_MARKNUM_FOLDERMIDTAIL=27,SC_MARKNUM_FOLDEROPEN=31,SC_MARKNUM_FOLDEROPENMID=26,SC_MARKNUM_FOLDERSUB=29,SC_MARKNUM_FOLDERTAIL=28,SC_MARK_ARROW=2,SC_MARK_ARROWDOWN=6,SC_MARK_ARROWS=24,SC_MARK_AVAILABLE=28,SC_MARK_BACKGROUND=22,SC_MARK_BOXMINUS=14,SC_MARK_BOXMINUSCONNECTED=15,SC_MARK_BOXPLUS=12,SC_MARK_BOXPLUSCONNECTED=13,SC_MARK_CHARACTER=10000,SC_MARK_CIRCLE=0,SC_MARK_CIRCLEMINUS=20,SC_MARK_CIRCLEMINUSCONNECTED=21,SC_MARK_CIRCLEPLUS=18,SC_MARK_CIRCLEPLUSCONNECTED=19,SC_MARK_DOTDOTDOT=23,SC_MARK_EMPTY=5,SC_MARK_FULLRECT=26,SC_MARK_LCORNER=10,SC_MARK_LCORNERCURVE=16,SC_MARK_LEFTRECT=27,SC_MARK_MINUS=7,SC_MARK_PIXMAP=25,SC_MARK_PLUS=8,SC_MARK_RGBAIMAGE=30,SC_MARK_ROUNDRECT=1,SC_MARK_SHORTARROW=4,SC_MARK_SMALLRECT=3,SC_MARK_TCORNER=11,SC_MARK_TCORNERCURVE=17,SC_MARK_UNDERLINE=29,SC_MARK_VLINE=9,SC_MASK_FOLDERS=-33554432,SC_MODEVENTMASKALL=0xFFFFF,SC_MOD_BEFOREDELETE=0x800,SC_MOD_BEFOREINSERT=0x400,SC_MOD_CHANGEANNOTATION=0x20000,SC_MOD_CHANGEFOLD=0x8,SC_MOD_CHANGEINDICATOR=0x4000,SC_MOD_CHANGELINESTATE=0x8000,SC_MOD_CHANGEMARGIN=0x10000,SC_MOD_CHANGEMARKER=0x200,SC_MOD_CHANGESTYLE=0x4,SC_MOD_CONTAINER=0x40000,SC_MOD_DELETETEXT=0x2,SC_MOD_INSERTTEXT=0x1,SC_MOD_LEXERSTATE=0x80000,SC_MULTILINEUNDOREDO=0x1000,SC_MULTIPASTE_EACH=1,SC_MULTIPASTE_ONCE=0,SC_MULTISTEPUNDOREDO=0x80,SC_PERFORMED_REDO=0x40,SC_PERFORMED_UNDO=0x20,SC_PERFORMED_USER=0x10,SC_PRINT_BLACKONWHITE=2,SC_PRINT_COLOURONWHITE=3,SC_PRINT_COLOURONWHITEDEFAULTBG=4,SC_PRINT_INVERTLIGHT=1,SC_PRINT_NORMAL=0,SC_SEL_LINES=2,SC_SEL_RECTANGLE=1,SC_SEL_STREAM=0,SC_SEL_THIN=3,SC_STARTACTION=0x2000,SC_STATUS_BADALLOC=2,SC_STATUS_FAILURE=1,SC_STATUS_OK=0,SC_TECHNOLOGY_DEFAULT=0,SC_TECHNOLOGY_DIRECTWRITE=1,SC_TIME_FOREVER=10000000,SC_TYPE_BOOLEAN=0,SC_TYPE_INTEGER=1,SC_TYPE_STRING=2,SC_UPDATE_CONTENT=0x1,SC_UPDATE_H_SCROLL=0x8,SC_UPDATE_SELECTION=0x2,SC_UPDATE_V_SCROLL=0x4,SC_WEIGHT_BOLD=700,SC_WEIGHT_NORMAL=400,SC_WEIGHT_SEMIBOLD=600,SC_WRAPINDENT_FIXED=0,SC_WRAPINDENT_INDENT=2,SC_WRAPINDENT_SAME=1,SC_WRAPVISUALFLAGLOC_DEFAULT=0x0000,SC_WRAPVISUALFLAGLOC_END_BY_TEXT=0x0001,SC_WRAPVISUALFLAGLOC_START_BY_TEXT=0x0002,SC_WRAPVISUALFLAG_END=0x0001,SC_WRAPVISUALFLAG_MARGIN=0x0004,SC_WRAPVISUALFLAG_NONE=0x0000,SC_WRAPVISUALFLAG_START=0x0002,SC_WRAP_CHAR=2,SC_WRAP_NONE=0,SC_WRAP_WORD=1,STYLE_BRACEBAD=35,STYLE_BRACELIGHT=34,STYLE_CALLTIP=38,STYLE_CONTROLCHAR=36,STYLE_DEFAULT=32,STYLE_INDENTGUIDE=37,STYLE_LASTPREDEFINED=39,STYLE_LINENUMBER=33,STYLE_MAX=255,UNDO_MAY_COALESCE=1,VISIBLE_SLOP=0x01,VISIBLE_STRICT=0x04,SCN_DOUBLECLICK=2006,SCN_AUTOCCHARDELETED=2027,SCN_SAVEPOINTLEFT=2003,SCN_PAINTED=2013,SCN_HOTSPOTRELEASECLICK=2028,SCN_UPDATEUI=2007,SCN_STYLENEEDED=2000,SCN_AUTOCCANCELLED=2026,SCN_MACRORECORD=2009,SCN_INDICATORRELEASE=2024,SCN_MODIFIED=2008,SCN_SAVEPOINTREACHED=2002,SCN_HOTSPOTDOUBLECLICK=2020,SCN_NEEDSHOWN=2011,SCN_CALLTIPCLICK=2021,SCN_AUTOCSELECTION=2022,SCN_DWELLEND=2017,SCN_ZOOM=2018,SCN_CHARADDED=2001,SCN_HOTSPOTCLICK=2019,SCN_KEY=2005,SCN_DWELLSTART=2016,SCN_MARGINCLICK=2010,SCN_USERLISTSELECTION=2014,SCN_URIDROPPED=2015,SCN_INDICATORCLICK=2023,SCN_MODIFYATTEMPTRO=2004,SCLEX_CONTAINER=0,SCLEX_AUTOMATIC=1000,SCLEX_LPEG=999,SCLEX_NULL=1} --- -- Scintilla functions. +-- Each key is a Scintilla function name with a table value containing its ID, +-- return type, wParam type, and lParam type. Types are as follows: +-- +-- + `0`: Void. +-- + `1`: Integer. +-- + `2`: Length of the given lParam string. +-- + `3`: Integer position. +-- + `4`: Colour in `0xBBGGRR` format. +-- + `5`: Boolean `true` or `false`. +-- + `6`: Bitmask of Scintilla key modifiers and a key value. +-- + `7`: String parameter. +-- + `8`: String return value. -- @class table -- @name functions M.functions = {add_ref_document={2376,0,0,1},add_selection={2573,1,1,1},add_styled_text={2002,0,2,9},add_text={2001,0,2,7},add_undo_action={2560,0,1,1},allocate={2446,0,1,0},annotation_clear_all={2547,0,0,0},append_text={2282,0,2,7},assign_cmd_key={2070,0,6,1},auto_c_active={2102,5,0,0},auto_c_cancel={2101,0,0,0},auto_c_complete={2104,0,0,0},auto_c_pos_start={2103,3,0,0},auto_c_select={2108,0,0,7},auto_c_show={2100,0,1,7},auto_c_stops={2105,0,0,7},back_tab={2328,0,0,0},begin_undo_action={2078,0,0,0},brace_bad_light={2352,0,3,0},brace_bad_light_indicator={2499,0,5,1},brace_highlight={2351,0,3,3},brace_highlight_indicator={2498,0,5,1},brace_match={2353,3,3,0},call_tip_active={2202,5,0,0},call_tip_cancel={2201,0,0,0},call_tip_pos_start={2203,3,0,0},call_tip_set_hlt={2204,0,1,1},call_tip_show={2200,0,3,7},can_paste={2173,5,0,0},can_redo={2016,5,0,0},can_undo={2174,5,0,0},cancel={2325,0,0,0},change_lexer_state={2617,1,3,3},char_left={2304,0,0,0},char_left_extend={2305,0,0,0},char_left_rect_extend={2428,0,0,0},char_position_from_point={2561,3,1,1},char_position_from_point_close={2562,3,1,1},char_right={2306,0,0,0},char_right_extend={2307,0,0,0},char_right_rect_extend={2429,0,0,0},choose_caret_x={2399,0,0,0},clear={2180,0,0,0},clear_all={2004,0,0,0},clear_all_cmd_keys={2072,0,0,0},clear_cmd_key={2071,0,6,0},clear_document_style={2005,0,0,0},clear_registered_images={2408,0,0,0},clear_selections={2571,0,0,0},colourise={4003,0,3,3},contracted_fold_next={2618,1,1,0},convert_eo_ls={2029,0,1,0},copy={2178,0,0,0},copy_allow_line={2519,0,0,0},copy_range={2419,0,3,3},copy_text={2420,0,2,7},count_characters={2633,1,1,1},create_document={2375,1,0,0},create_loader={2632,1,1,0},cut={2177,0,0,0},del_line_left={2395,0,0,0},del_line_right={2396,0,0,0},del_word_left={2335,0,0,0},del_word_right={2336,0,0,0},del_word_right_end={2518,0,0,0},delete_back={2326,0,0,0},delete_back_not_line={2344,0,0,0},delete_range={2645,0,3,1},describe_key_word_sets={4017,1,0,8},describe_property={4016,1,7,8},doc_line_from_visible={2221,1,1,0},document_end={2318,0,0,0},document_end_extend={2319,0,0,0},document_start={2316,0,0,0},document_start_extend={2317,0,0,0},edit_toggle_overtype={2324,0,0,0},empty_undo_buffer={2175,0,0,0},encoded_from_utf8={2449,1,7,8},end_undo_action={2079,0,0,0},ensure_visible={2232,0,1,0},ensure_visible_enforce_policy={2234,0,1,0},find_column={2456,1,1,1},find_indicator_flash={2641,0,3,3},find_indicator_hide={2642,0,0,0},find_indicator_show={2640,0,3,3},find_text={2150,3,1,11},form_feed={2330,0,0,0},format_range={2151,3,5,12},get_cur_line={2027,1,2,8},get_hotspot_active_back={2495,4,0,0},get_hotspot_active_fore={2494,4,0,0},get_last_child={2224,1,1,1},get_line={2153,1,1,8},get_line_sel_end_position={2425,3,1,0},get_line_sel_start_position={2424,3,1,0},get_range_pointer={2643,1,1,1},get_sel_text={2161,1,0,8},get_styled_text={2015,1,0,10},get_text={2182,1,2,8},get_text_range={2162,1,0,10},goto_line={2024,0,1,0},goto_pos={2025,0,3,0},grab_focus={2400,0,0,0},hide_lines={2227,0,1,1},hide_selection={2163,0,5,0},home={2312,0,0,0},home_display={2345,0,0,0},home_display_extend={2346,0,0,0},home_extend={2313,0,0,0},home_rect_extend={2430,0,0,0},home_wrap={2349,0,0,0},home_wrap_extend={2450,0,0,0},indicator_all_on_for={2506,1,1,0},indicator_clear_range={2505,0,1,1},indicator_end={2509,1,1,1},indicator_fill_range={2504,0,1,1},indicator_start={2508,1,1,1},indicator_value_at={2507,1,1,1},insert_text={2003,0,3,7},line_copy={2455,0,0,0},line_cut={2337,0,0,0},line_delete={2338,0,0,0},line_down={2300,0,0,0},line_down_extend={2301,0,0,0},line_down_rect_extend={2426,0,0,0},line_duplicate={2404,0,0,0},line_end={2314,0,0,0},line_end_display={2347,0,0,0},line_end_display_extend={2348,0,0,0},line_end_extend={2315,0,0,0},line_end_rect_extend={2432,0,0,0},line_end_wrap={2451,0,0,0},line_end_wrap_extend={2452,0,0,0},line_from_position={2166,1,3,0},line_length={2350,1,1,0},line_scroll={2168,0,1,1},line_scroll_down={2342,0,0,0},line_scroll_up={2343,0,0,0},line_transpose={2339,0,0,0},line_up={2302,0,0,0},line_up_extend={2303,0,0,0},line_up_rect_extend={2427,0,0,0},lines_join={2288,0,0,0},lines_split={2289,0,1,0},load_lexer_library={4007,0,0,7},lower_case={2340,0,0,0},margin_text_clear_all={2536,0,0,0},marker_add={2043,1,1,1},marker_add_set={2466,0,1,1},marker_define={2040,0,1,1},marker_define_pixmap={2049,0,1,7},marker_define_rgba_image={2626,0,1,7},marker_delete={2044,0,1,1},marker_delete_all={2045,0,1,0},marker_delete_handle={2018,0,1,0},marker_enable_highlight={2293,0,5,0},marker_get={2046,1,1,0},marker_line_from_handle={2017,1,1,0},marker_next={2047,1,1,1},marker_previous={2048,1,1,1},marker_symbol_defined={2529,1,1,0},move_caret_inside_view={2401,0,0,0},move_selected_lines_down={2621,0,0,0},move_selected_lines_up={2620,0,0,0},new_line={2329,0,0,0},null={2172,0,0,0},page_down={2322,0,0,0},page_down_extend={2323,0,0,0},page_down_rect_extend={2434,0,0,0},page_up={2320,0,0,0},page_up_extend={2321,0,0,0},page_up_rect_extend={2433,0,0,0},para_down={2413,0,0,0},para_down_extend={2414,0,0,0},para_up={2415,0,0,0},para_up_extend={2416,0,0,0},paste={2179,0,0,0},point_x_from_position={2164,1,0,3},point_y_from_position={2165,1,0,3},position_after={2418,3,3,0},position_before={2417,3,3,0},position_from_line={2167,3,1,0},position_from_point={2022,3,1,1},position_from_point_close={2023,3,1,1},private_lexer_call={4013,1,1,1},property_names={4014,1,0,8},property_type={4015,1,7,0},redo={2011,0,0,0},register_image={2405,0,1,7},register_rgba_image={2627,0,1,7},release_document={2377,0,0,1},replace_sel={2170,0,0,7},replace_target={2194,1,2,7},replace_target_re={2195,1,2,7},rotate_selection={2606,0,0,0},scroll_caret={2169,0,0,0},scroll_to_end={2629,0,0,0},scroll_to_start={2628,0,0,0},search_anchor={2366,0,0,0},search_in_target={2197,1,2,7},search_next={2367,1,1,7},search_prev={2368,1,1,7},select_all={2013,0,0,0},selection_duplicate={2469,0,0,0},set_chars_default={2444,0,0,0},set_empty_selection={2556,0,3,0},set_fold_margin_colour={2290,0,5,4},set_fold_margin_hi_colour={2291,0,5,4},set_hotspot_active_back={2411,0,5,4},set_hotspot_active_fore={2410,0,5,4},set_length_for_encode={2448,0,1,0},set_save_point={2014,0,0,0},set_sel={2160,0,3,3},set_sel_back={2068,0,5,4},set_sel_fore={2067,0,5,4},set_selection={2572,1,1,1},set_styling={2033,0,2,1},set_styling_ex={2073,0,2,7},set_text={2181,0,0,7},set_visible_policy={2394,0,1,1},set_whitespace_back={2085,0,5,4},set_whitespace_fore={2084,0,5,4},set_x_caret_policy={2402,0,1,1},set_y_caret_policy={2403,0,1,1},show_lines={2226,0,1,1},start_record={3001,0,0,0},start_styling={2032,0,3,1},stop_record={3002,0,0,0},stuttered_page_down={2437,0,0,0},stuttered_page_down_extend={2438,0,0,0},stuttered_page_up={2435,0,0,0},stuttered_page_up_extend={2436,0,0,0},style_clear_all={2050,0,0,0},style_reset_default={2058,0,0,0},swap_main_anchor_caret={2607,0,0,0},tab={2327,0,0,0},target_as_utf8={2447,1,0,8},target_from_selection={2287,0,0,0},text_height={2279,1,1,0},text_width={2276,1,1,7},toggle_caret_sticky={2459,0,0,0},toggle_fold={2231,0,1,0},undo={2176,0,0,0},upper_case={2341,0,0,0},use_pop_up={2371,0,5,0},user_list_show={2117,0,1,7},vc_home={2331,0,0,0},vc_home_display={2652,0,0,0},vc_home_display_extend={2653,0,0,0},vc_home_extend={2332,0,0,0},vc_home_rect_extend={2431,0,0,0},vc_home_wrap={2453,0,0,0},vc_home_wrap_extend={2454,0,0,0},vertical_centre_caret={2619,0,0,0},visible_from_doc_line={2220,1,1,0},word_end_position={2267,1,3,5},word_left={2308,0,0,0},word_left_end={2439,0,0,0},word_left_end_extend={2440,0,0,0},word_left_extend={2309,0,0,0},word_part_left={2390,0,0,0},word_part_left_extend={2391,0,0,0},word_part_right={2392,0,0,0},word_part_right_extend={2393,0,0,0},word_right={2310,0,0,0},word_right_end={2441,0,0,0},word_right_end_extend={2442,0,0,0},word_right_extend={2311,0,0,0},word_start_position={2266,1,3,5},wrap_count={2235,1,1,0},zoom_in={2333,0,0,0},zoom_out={2334,0,0,0}} --- -- Scintilla properties. +-- Each key is a Scintilla property name with a table value containing the ID of +-- its "get" function, the ID of its "set" function, its return type, and its +-- wParam type. The wParam type will be non-zero if the property is an indexable +-- property. Types are the same as in the `functions` table. +-- @see functions -- @class table -- @name properties M.properties = {additional_caret_fore={2605,2604,4,0},additional_carets_blink={2568,2567,5,0},additional_carets_visible={2609,2608,5,0},additional_sel_alpha={2603,2602,1,0},additional_sel_back={0,2601,4,0},additional_sel_fore={0,2600,4,0},additional_selection_typing={2566,2565,5,0},all_lines_visible={2236,0,5,0},anchor={2009,2026,3,0},annotation_lines={2546,0,1,1},annotation_style={2543,2542,1,1},annotation_style_offset={2551,2550,1,0},annotation_styles={2545,2544,8,1},annotation_text={2541,2540,8,1},annotation_visible={2549,2548,1,0},auto_c_auto_hide={2119,2118,5,0},auto_c_cancel_at_start={2111,2110,5,0},auto_c_case_insensitive_behaviour={2635,2634,1,0},auto_c_choose_single={2114,2113,5,0},auto_c_current={2445,0,1,0},auto_c_current_text={2610,0,8,0},auto_c_drop_rest_of_word={2271,2270,5,0},auto_c_fill_ups={0,2112,7,0},auto_c_ignore_case={2116,2115,5,0},auto_c_max_height={2211,2210,1,0},auto_c_max_width={2209,2208,1,0},auto_c_separator={2107,2106,1,0},auto_c_type_separator={2285,2286,1,0},back_space_un_indents={2263,2262,5,0},buffered_draw={2034,2035,5,0},call_tip_back={0,2205,4,0},call_tip_fore={0,2206,4,0},call_tip_fore_hlt={0,2207,4,0},call_tip_position={0,2213,5,0},call_tip_use_style={0,2212,1,0},caret_fore={2138,2069,4,0},caret_line_back={2097,2098,4,0},caret_line_back_alpha={2471,2470,1,0},caret_line_visible={2095,2096,5,0},caret_period={2075,2076,1,0},caret_sticky={2457,2458,1,0},caret_style={2513,2512,1,0},caret_width={2189,2188,1,0},char_at={2007,0,1,3},character_pointer={2520,0,1,0},code_page={2137,2037,1,0},column={2129,0,1,3},control_char_symbol={2389,2388,1,0},current_pos={2008,2141,3,0},cursor={2387,2386,1,0},direct_function={2184,0,1,0},direct_pointer={2185,0,1,0},doc_pointer={2357,2358,1,0},eol_mode={2030,2031,1,0},edge_colour={2364,2365,4,0},edge_column={2360,2361,1,0},edge_mode={2362,2363,1,0},end_at_last_line={2278,2277,5,0},end_styled={2028,0,3,0},extra_ascent={2526,2525,1,0},extra_descent={2528,2527,1,0},first_visible_line={2152,2613,1,0},focus={2381,2380,5,0},fold_expanded={2230,2229,5,1},fold_flags={0,2233,1,0},fold_level={2223,2222,1,1},fold_parent={2225,0,1,1},font_quality={2612,2611,1,0},gap_position={2644,0,3,0},h_scroll_bar={2131,2130,5,0},highlight_guide={2135,2134,1,0},hotspot_active_underline={2496,2412,5,0},hotspot_single_line={2497,2421,5,0},identifier={2623,2622,1,0},indent={2123,2122,1,0},indentation_guides={2133,2132,1,0},indic_alpha={2524,2523,1,1},indic_fore={2083,2082,4,1},indic_outline_alpha={2559,2558,1,1},indic_style={2081,2080,1,1},indic_under={2511,2510,5,1},indicator_current={2501,2500,1,0},indicator_value={2503,2502,1,0},key_words={0,4005,7,1},keys_unicode={2522,2521,5,0},layout_cache={2273,2272,1,0},length={2006,0,1,0},lexer={4002,4001,1,0},lexer_language={4012,4006,8,0},line_count={2154,0,1,0},line_end_position={2136,0,3,1},line_indent_position={2128,0,3,1},line_indentation={2127,2126,1,1},line_state={2093,2092,1,1},line_visible={2228,0,5,1},lines_on_screen={2370,0,1,0},main_selection={2575,2574,1,0},margin_cursor_n={2249,2248,1,1},margin_left={2156,2155,1,0},margin_mask_n={2245,2244,1,1},margin_options={2557,2539,1,0},margin_right={2158,2157,1,0},margin_sensitive_n={2247,2246,5,1},margin_style={2533,2532,1,1},margin_style_offset={2538,2537,1,0},margin_styles={2535,2534,8,1},margin_text={2531,2530,8,1},margin_type_n={2241,2240,1,1},margin_width_n={2243,2242,1,1},marker_alpha={0,2476,1,1},marker_back={0,2042,4,1},marker_back_selected={0,2292,4,1},marker_fore={0,2041,4,1},max_line_state={2094,0,1,0},mod_event_mask={2378,2359,1,0},modify={2159,0,5,0},mouse_down_captures={2385,2384,5,0},mouse_dwell_time={2265,2264,1,0},multi_paste={2615,2614,1,0},multiple_selection={2564,2563,5,0},overtype={2187,2186,5,0},paste_convert_endings={2468,2467,5,0},position_cache={2515,2514,1,0},print_colour_mode={2149,2148,1,0},print_magnification={2147,2146,1,0},print_wrap_mode={2407,2406,1,0},property={4008,4004,8,7},property_expanded={4009,0,8,7},property_int={4010,0,1,7},punctuation_chars={2649,2648,8,0},rgba_image_height={0,2625,1,0},rgba_image_scale={0,2651,1,0},rgba_image_width={0,2624,1,0},read_only={2140,2171,5,0},rectangular_selection_anchor={2591,2590,3,0},rectangular_selection_anchor_virtual_space={2595,2594,1,0},rectangular_selection_caret={2589,2588,3,0},rectangular_selection_caret_virtual_space={2593,2592,1,0},rectangular_selection_modifier={2599,2598,1,0},scroll_width={2275,2274,1,0},scroll_width_tracking={2517,2516,5,0},search_flags={2199,2198,1,0},sel_alpha={2477,2478,1,0},sel_eol_filled={2479,2480,5,0},selection_empty={2650,0,5,0},selection_end={2145,2144,3,0},selection_is_rectangle={2372,0,5,0},selection_mode={2423,2422,1,0},selection_n_anchor={2579,2578,3,1},selection_n_anchor_virtual_space={2583,2582,1,1},selection_n_caret={2577,2576,3,1},selection_n_caret_virtual_space={2581,2580,1,1},selection_n_end={2587,2586,3,1},selection_n_start={2585,2584,3,1},selection_start={2143,2142,3,0},selections={2570,0,1,0},status={2383,2382,1,0},style_at={2010,0,1,3},style_back={2482,2052,4,1},style_bits={2091,2090,1,0},style_bits_needed={4011,0,1,0},style_bold={2483,2053,5,1},style_case={2489,2060,1,1},style_changeable={2492,2099,5,1},style_character_set={2490,2066,1,1},style_eol_filled={2487,2057,5,1},style_font={2486,2056,8,1},style_fore={2481,2051,4,1},style_hot_spot={2493,2409,5,1},style_italic={2484,2054,5,1},style_size={2485,2055,1,1},style_size_fractional={2062,2061,1,1},style_underline={2488,2059,5,1},style_visible={2491,2074,5,1},style_weight={2064,2063,1,1},tab_indents={2261,2260,5,0},tab_width={2121,2036,1,0},tag={2616,0,8,1},target_end={2193,2192,3,0},target_start={2191,2190,3,0},technology={2631,2630,1,0},text_length={2183,0,1,0},two_phase_draw={2283,2284,5,0},undo_collection={2019,2012,5,0},use_tabs={2125,2124,5,0},v_scroll_bar={2281,2280,5,0},view_eol={2355,2356,5,0},view_ws={2020,2021,1,0},virtual_space_options={2597,2596,1,0},whitespace_chars={2647,2443,8,0},whitespace_size={2087,2086,1,0},word_chars={2646,2077,8,0},wrap_indent_mode={2473,2472,1,0},wrap_mode={2269,2268,1,0},wrap_start_indent={2465,2464,1,0},wrap_visual_flags={2461,2460,1,0},wrap_visual_flags_location={2463,2462,1,0},x_offset={2398,2397,1,0},zoom={2374,2373,1,0}} @@ -55,7 +74,7 @@ end --- -- Returns a unique user list type. -- Use this function for custom user lists in order to prevent clashes with --- type identifiers of other custom user lists. +-- list identifiers of other custom user lists. -- @usage local list_type = _SCINTILLA.next_user_list_type() -- @see buffer.user_list_show -- @name next_user_list_type diff --git a/core/init.lua b/core/init.lua index fd3e1b9c..4473c11b 100644 --- a/core/init.lua +++ b/core/init.lua @@ -22,19 +22,26 @@ _M = {} -- modules table --[[ This comment is for LuaDoc. --- --- Extends Lua's _G table to provide extra functions and fields. +-- Extends Lua's _G table to provide extra functions and fields for Textadept. -- @field _HOME (string) -- Path to the directory containing Textadept. -- @field _LEXERPATH (string) --- Paths to lexers, formatted like --- [`package.path`](http://lua.org/manual/5.2/manual.html#pdf-package.path). +-- Paths to lexers, formatted like [`package.path`][]. +-- +-- [`package.path`]: http://lua.org/manual/5.2/manual.html#pdf-package.path -- @field _RELEASE (string) -- The Textadept release version. -- @field _USERHOME (string) --- Path to the user's `~/.textadept/`. +-- Path to the user's `~/.textadept/`, where all preferences and user-data is +-- stored. +-- On Windows machines `~/` is the value of the `USERHOME` environment +-- variable, typically `C:\Users\<username>\` or +-- `C:\Documents and Settings\<username>\`. On Linux, BSD, and Mac OSX +-- machines `~/` is the value of `HOME`, typically `/home/<username>/` and +-- `/Users/<username>/` respectively. -- @field _CHARSET (string) -- The character set encoding of the filesystem. --- This is used in [File I/O](io.html). +-- This is used when [working with files](io.html). -- @field RESETTING (bool) -- If [`reset()`](#reset) has been called, this flag is `true` while the Lua -- state is being re-initialized. @@ -44,13 +51,21 @@ _M = {} -- modules table -- If Textadept is running on Mac OSX, this flag is `true`. -- @field NCURSES (bool) -- If Textadept is running in the terminal, this flag is `true`. +-- ncurses feature incompatibilities are listed in the [Appendix][]. +-- +-- [Appendix]: ../14_Appendix.html#Ncurses.Compatibility +-- @field buffer The current [buffer][] in the current [view](#view). +-- +-- [buffer]: buffer.html +-- @field view The currently focused [view](view.html). module('_G')]] --[[ The tables below were defined in C. --- --- Command line parameters. +-- Command line parameters passed to Textadept. -- @class table +-- @see _G.args -- @name arg local arg @@ -59,9 +74,10 @@ local arg -- Numeric keys have buffer values and buffer keys have their associated numeric -- keys. -- @class table --- @name _BUFFERS -- @usage _BUFFERS[1] contains the first buffer. -- @usage _BUFFERS[buffer] returns the index of the current buffer in _BUFFERS. +-- @see _G.buffer +-- @name _BUFFERS local _BUFFERS --- @@ -69,23 +85,28 @@ local _BUFFERS -- Numeric keys have view values and view keys have their associated numeric -- keys. -- @class table --- @name _VIEWS -- @usage _VIEWS[1] contains the first view. -- @usage _VIEWS[view] returns the index of the current view in _VIEWS. +-- @see _G.view +-- @name _VIEWS local _VIEWS -- The functions below are Lua C functions. --- -- Creates a new buffer. --- Generates a `BUFFER_NEW` event. +-- Emits a `BUFFER_NEW` event. -- @return the new buffer. -- @class function +-- @see events.BUFFER_NEW -- @name new_buffer local new_buffer --- -- Quits Textadept. +-- Emits a `QUIT` event. If any handler returns `false`, Textadept does not +-- quit. +-- @see events.QUIT -- @class function -- @name quit local quit @@ -93,12 +114,12 @@ local quit --- -- Resets the Lua state by reloading all init scripts. -- Language-specific modules for opened files are NOT reloaded. Re-opening the --- files that use them will reload those modules. --- This function is useful for modifying init scripts (such as the user's --- `modules/textadept/keys.lua`) on the fly without having to restart Textadept. --- `_G.RESETTING` is set to `true` when re-initing the Lua State. Any scripts --- that need to differentiate between startup and reset can utilize this --- variable. +-- files that use them will reload those modules instead. +-- This function is useful for modifying user scripts (such as +-- `~/.textadept/init.lua` and `~/.textadept/modules/textadept/keys.lua`) on +-- the fly without having to restart Textadept. `_G.RESETTING` is set to `true` +-- when re-initing the Lua State. Any scripts that need to differentiate between +-- startup and reset can utilize this variable. -- @class function -- @see RESETTING -- @name reset @@ -106,8 +127,8 @@ local reset --- -- Calls a given function after an interval of time. --- To repeatedly call the function, return true inside the function. A `nil` or --- `false` return value stops repetition. +-- To repeatedly call the function, return `true` inside the function. A `nil` +-- or `false` return value stops repetition. -- @param interval The interval in seconds to call the function after. -- @param f The function to call. -- @param ... Additional arguments to pass to `f`. diff --git a/core/keys.lua b/core/keys.lua index d09a0ef5..65042fe0 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -4,103 +4,88 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Manages key commands in Textadept. +-- Manages key bindings in Textadept. -- -- ## Overview -- --- Key commands are defined in the global table `keys`. Each key-value pair in --- `keys` consists of either: +-- Key bindings are defined in the global table `keys`. Each key-value pair in +-- `keys` consists of either a string key sequence and its associated command, +-- a string lexer language (from the `lexers/` directory) with a table of key +-- sequences and commands, or a key sequence with a table of more sequences and +-- commands. The latter is part of what is called a "key chain". When searching +-- for a command to run based on a key sequence, key bindings in the current +-- lexer have priority, followed by the ones in the global table. This means if +-- there are two commands with the same key sequence, the one specific to the +-- current lexer is run. However, if the command returns the boolean value +-- `false`, the lower-priority command is also run. (This is useful for +-- language-specific modules to override commands like Adeptsense +-- autocompletion, but fall back to word autocompletion if the first command +-- fails.) -- --- * A string representing a key command and an associated function or table. --- * A string language name and its associated `keys`-like table. --- * A string representing a key command and its associated `keys`-like table. --- (This is a keychain sequence.) +-- ## Key Sequences -- --- Language names are the names of the lexer files in `lexers/` such as `cpp` --- and `lua`. +-- Key sequences are strings built from a combination of modifier keys and the +-- key itself. Modifier keys are `Control`, `Shift`, and `Alt` on Windows, +-- Linux, BSD, and in ncurses. On Mac OSX they are `Command` (`⌘`), `Alt/Option` +-- (`⌥`), `Control` (`^`), and `Shift` (`⇧`). These modifiers have the following +-- string representations: -- --- A key command string is built from a combination of the `CTRL`, `ALT`, --- `META`, `SHIFT`, and `ADD` constants as well as the pressed key itself. The --- value of `ADD` is inserted between each of `CTRL`, `ALT`, `META`, `SHIFT`, --- and the key. For example: +-- Modifier | Linux / Win32 | Mac OSX | Terminal | +-- ---------|---------------|---------|----------| +-- Control | `'c'` | `'m'` | `'c'` | +-- Alt | `'a'` | `'a'` | `'m'` | +-- Shift | `'s'` | `'s'` | `'s'` | +-- Command | N/A | `'c'` | N/A | -- --- -- keys.lua: --- CTRL = 'Ctrl' --- ALT = 'Alt' --- SHIFT = 'Shift' --- META = 'Meta' --- ADD = '+' --- -- pressing control, alt, shift, and 'a' yields: 'Ctrl+Alt+Shift+A' +-- For key values less than 255, their string representation is the character +-- that would normally be inserted if the `Ctrl`, `Alt`, and `Command` modifiers +-- were not held down. Therefore, a combination of `Ctrl+Alt+Shift+A` has the +-- key sequence `caA` on Windows and Linux, but a combination of +-- `Ctrl+Shift+Tab` has the key sequence `cs\t`. On a United States English +-- keyboard, since the combination of `Ctrl+Shift+,` has the key sequence `c<` +-- (`Shift+,` inserts a `<`), the key binding is referred to as `Ctrl+<`. This +-- allows key bindings to be language and layout agnostic. For key values +-- greater than 255, the [`KEYSYMS`](#KEYSYMS) lookup table is used. Therefore, +-- `Ctrl+Right Arrow` has the key sequence `cright`. Uncommenting the `print()` +-- statements in `core/keys.lua` will print key sequences to standard out +-- (stdout) for inspection. -- --- For key values less than 255, Lua's [`string.char()`][] is used to determine --- the key's string representation. Otherwise, the [`KEYSYMS`](#KEYSYMS) lookup --- table is used. +-- ## Commands -- --- [`string.char()`]: http://www.lua.org/manual/5.2/manual.html#pdf-string.char +-- Commands associated with key sequences can be either Lua functions, or +-- tables containing Lua functions with a set of arguments to call the function +-- with. Examples are -- --- Normally, Lua functions are assigned to key commands, but those functions are --- called without any arguments. In order to pass arguments to a function, --- assign a table to the key command. This table contains the function followed --- by its arguments in order. Any [buffer][] or [view][] references are handled --- correctly at runtime. +-- keys['cn'] = new_buffer +-- keys['cs'] = buffer.save +-- keys['a('] = { _M.textadept.editing.enclose, '(', ')' } -- --- [buffer]: buffer.html --- [view]: view.html +-- Note that [`buffer`][] references are handled properly. -- --- Key commands can be chained like in Emacs using keychain sequences. By --- default, the `Esc` key (`Apple+Esc` on Mac OSX) cancels the current keychain, --- but it can be redefined by re-defining [`CLEAR`](#CLEAR). Naturally, the --- clear sequence cannot be chained. +-- [`buffer`]: buffer.html -- --- ## Precedence +-- ## Key Chains -- --- When searching for a key command to execute in the `keys` table, key commands --- in the current lexer have priority, followed by the ones in the global table. +-- Key chains are a powerful concept. They allow multiple key bindings to be +-- assigned to one key sequence. Language-specific modules +-- [use key chains](#LANGUAGE_MODULE_PREFIX) for their functions. By default, +-- the `Esc` (`⎋` on Mac OSX | `Esc` in ncurses) key cancels a key chain, but it +-- can be redefined via [`CLEAR`](#CLEAR). An example key chain looks like -- --- ### Propagation --- --- Normally when the same key command is assigned to two separate functions of --- different precedence, the higher priority key command is run and the lower --- priority one is not. However, it is sometimes desirable to have the lower --- priority command run after the higher one. For example, `Ctrl+Enter` may --- trigger Adeptsense autocompletion in lexers that have Adeptsense, but should --- fall back on autocompleting words in the buffer if no Adeptsense completions --- are available. In order for this to happen, the first function has to return --- `false` (and only `false`; `nil` is not sufficient) when it wants to allow a --- lower priority function to run. Any other return value halts propagation and --- the key is consumed. --- --- ## Example --- --- keys = { --- ['ctrl+f'] = buffer.char_right --- ['ctrl+b'] = buffer.char_left, --- lua = { --- ['ctrl+f'] = { buffer.add_text, buffer, 'function' }, --- ['ctrl+b'] = function() return false end --- } +-- keys['aa'] = { +-- a = function1, +-- b = function2, +-- c = { function3, arg1, arg2 } -- } --- --- The first two key commands are global and call `buffer:char_right()` and --- `buffer:char_left()` respectively. The last two commands apply only in the --- Lua lexer. If `ctrl+f` is pressed in a Lua file, the global key command with --- the same shortcut is overridden and `function` is added to the buffer. --- However, `ctrl+b` in a Lua file does not override its global command because --- of the `false` return. Instead, propagation occurs as described above. --- --- ## Problems --- --- All Lua functions must be defined **before** they are reference in key --- commands. Therefore, any module containing key commands should be loaded --- after all other modules, whose functions are being referenced, have been --- loaded. -- @field CLEAR (string) --- The string representing the key sequence that clears the current keychain. --- The default value is `'esc'` (Escape). +-- The string representing the key sequence that clears the current key chain. +-- It cannot be part of a key chain. +-- The default value is `'esc'` for the `Esc` (`⎋` on Mac OSX | `Esc` in +-- ncurses) key. -- @field LANGUAGE_MODULE_PREFIX (string) --- The starting key command of the keychain reserved for language-specific +-- The starting key command of the key chain reserved for language-specific -- modules. --- The default value is Ctrl/Cmd+L. +-- The default value is `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in ncurses). module('keys')]] local ADD = '' @@ -120,9 +105,9 @@ local getmetatable = getmetatable local error = function(e) events.emit(events.ERROR, e) end --- --- Lookup table for key codes higher than 255. --- If a key code given to `keypress()` is higher than 255, this table is used to --- return a string representation of the key if it exists. +-- Lookup table for string representations of GDK key codes higher than 255. +-- Key codes can be identified by temporarily uncommenting the `print()` +-- statements in `core/keys.lua` -- @class table -- @name KEYSYMS M.KEYSYMS = { @@ -235,7 +220,7 @@ end local function keypress(code, shift, control, alt, meta) local buffer = buffer local key - --print(code, M.KEYSYMS[ch], shift, control, alt, meta) + --print(code, M.KEYSYMS[code], shift, control, alt, meta) if code < 256 then key = string_char(code) shift = shift and code < 32 -- for printable characters, key is upper case diff --git a/core/locale.lua b/core/locale.lua index 449f4dee..68a8266c 100644 --- a/core/locale.lua +++ b/core/locale.lua @@ -5,12 +5,15 @@ local M = {} --[[ This comment is for LuaDoc. --- -- Table of all messages used by Textadept for localization. +-- If the table does not contain the localized version of a given message, it +-- returns a string indicating so via a metamethod. module('_L')]] local none = 'No Localization: ' --- -- Returns whether or not a localized message exists for the given message. +-- This function is necessary since `_L[message]` never returns `nil`. -- @param message The message to localize. -- @return `true` if a localization exists, `false` otherwise. function M._EXISTS(message) return M[message] ~= none..message end diff --git a/doc/.api_index.md b/doc/.api_index.md new file mode 100644 index 00000000..3a9fb25d --- /dev/null +++ b/doc/.api_index.md @@ -0,0 +1,6 @@ +# Lua API + +The Lua API documentation is a complement to the [manual][]. Please ensure you +are familiar with the basic concepts presented in the manual before proceeding. + +[manual]: ../01_Introduction.html diff --git a/doc/01_Introduction.md b/doc/01_Introduction.md index f4a27577..5ac05e8c 100644 --- a/doc/01_Introduction.md +++ b/doc/01_Introduction.md @@ -7,58 +7,63 @@ Textadept is a fast, minimalist, and ridiculously extensible cross-platform text editor for programmers. Written in a combination of C and [Lua][] and relentlessly optimized for speed and minimalism over the years, Textadept is an -ideal editor for programmers who want endless extensibility options without -sacrificing speed or succumbing to code bloat and featuritis. +ideal editor for programmers who want endless extensibility without sacrificing +speed or succumbing to code bloat and featuritis. [Lua]: http://lua.org ### Fast Textadept is _fast_. It starts up instantly and has a very responsive user -interface (UI). Even though the editor is mostly written in Lua, Lua is one of -the fastest scripting languages available. With the optional [LuaJIT][] version, +interface. Even though the editor is mostly written in Lua, Lua is one of the +fastest scripting languages available. With the optional [LuaJIT][] version, Textadept is faster than ever before. [LuaJIT]: http://luajit.org ### Minimalist -Textadept is minimalist. Not only is this apparent in the UI, but the editor's C -core was designed to never exceed 2000 lines of code and its Lua extension code -is not supposed to go beyond 4000 lines. After 5 years of development, Textadept -has maintained the same amount of code since its inception (~5600 lines) while -evolving into a vastly superior editor. +Textadept is minimalist. Not only is this apparent in its appearance, but the +editor's C core was designed to never exceed 2000 lines of code and its Lua +extension code is capped at 4000 lines. After 5 years of development, Textadept +has maintained the same amount of code since its inception while evolving into a +vastly superior editor. ### Ridiculously Extensible Textadept is ridiculously extensible. It was designed to be that way from the -very beginning. The features came later. Most of Textadept is written in Lua, +very beginning. The features came later. Most of Textadept's internals use Lua, from syntax highlighting to opening and saving files to searching and replacing and more. Textadept gives you complete control over the entire application using Lua. You can do everything from moving the caret to changing menus and key -commands on-the-fly to handling UI events. The possibilities are limitless. +commands on-the-fly to handling core events. The possibilities are limitless.  ## Manual Notation -* `~/` is denoted as the user's home directory. On Windows machines this is the - value of the `USERHOME` environment variable (typically `C:\Users\<username>\` - or `C:\Documents and Settings\<username>\`). On Linux and Mac OSX machines it - is the value of `HOME` (typically `/home/<username>/` and `/Users/<username>/` - respectively). -* Any relative directory paths, i.e. paths that do not begin with `/` or `C:\`, - are relative to the location of Textadept. -* Key combinations are not case-sensitive. `Ctrl+N` means the `N` key is pressed - with only the `Control` key being held down, not the `Shift` key. - `Ctrl+Shift+N` means the `N` key is pressed with both `Control` and `Shift` - keys being held down. The same notation is applicable to key chains: - `Ctrl+N, N` vs. `Ctrl+N, Shift+N`. In the first key chain, `Control` and `N` - are pressed followed by `N` with no modifiers. The second has `Control` and - `N` pressed followed by `Shift` and `N`. -* When mentioning key commands, the Mac OSX and ncurses equivalents will often - be shown in parenthesis. It may be tempting to assume that some Windows/Linux - keys map to Mac OSX's (e.g. `Ctrl` to `⌘`) or ncurses' (e.g. `Ctrl` to `^`), - but this is not always the case. Please do not view the key equivalents as - translations of one another, but rather as separate entities. This will - minimize confusion. +This manual uses notation that is worth clarifying. + +Directories and file paths are represented like this: `/path/to/file_or_dir`. +(On Windows machines, `/` and `\` can be used interchangeably as directory +separators.) Any relative paths, paths that do not begin with `/` or `C:\`, are +relative to the location of Textadept. `~/` is denoted as the user's home +directory. On Windows machines this is the value of the `USERHOME` environment +variable, typically `C:\Users\<username>\` or +`C:\Documents and Settings\<username>\`. On Linux, BSD, and Mac OSX machines it +is the value of `HOME`, typically `/home/<username>/` and `/Users/<username>/` +respectively. + +Key bindings are represented like this: `Ctrl+N`. They are not case sensitive. +`Ctrl+N` means the `N` key is pressed with only the `Control` modifier key being +held down, not the `Shift` modifier key. `Ctrl+Shift+N` means the `N` key is +pressed with both `Control` and `Shift` modifiers held down. The same notation +is applicable to key chains: `Ctrl+N, N` vs. `Ctrl+N, Shift+N`. In the first key +chain, `Control` and `N` are pressed followed by `N` with no modifiers. The +second has `Control` and `N` pressed followed by `Shift` and `N`. + +When key bindings are mentioned, the Mac OSX and ncurses equivalents are often +shown in parenthesis. It may be tempting to assume that some Windows/Linux keys +map to Mac OSX's (e.g. `Ctrl` to `⌘`) or ncurses' (e.g. `Ctrl` to `^`), but this +is not always the case. Please do not view the key equivalents as translations +of one another, but rather as separate entities. This will minimize confusion. diff --git a/doc/02_Installation.md b/doc/02_Installation.md index 89c224c3..a631e715 100644 --- a/doc/02_Installation.md +++ b/doc/02_Installation.md @@ -2,37 +2,32 @@ ## Requirements -In its bid for minimalism, Textadept also needs very little to run. In fact, the -only thing it needs is [GTK+][] >= 2.18 on Linux systems. GTK is already -included in Windows and Mac OSX packages. Textadept also has its own version of -Lua. - -The terminal version of Textadept requires [ncurses][]. This dependency is only -necessary if you wish to run Textadept from a terminal. - -Notes: - -* The Linux binaries provided require GLib >= 2.28 to support single-instance - functionality. You can compile Textadept with earlier versions of GLib down to - 2.22. For reference, Ubuntu 11.04, Debian Wheezy, Fedora 15, and openSUSE 11.4 - support GLib 2.28 or higher. -* For Win32 and Mac OSX, more than 3/4 of the download and unpackaged - application sizes are due to GTK+, the cross-platform GUI toolkit Textadept - uses. Textadept itself is much smaller. +In its bid for minimalism, Textadept also needs very little to run. The GUI +version needs only [GTK+][], a cross-platform GUI toolkit, version 2.18 or later +on Linux and BSD systems. A GTK+ runtime is already bundled into the Windows +and Mac OSX packages. Textadept also has its own [copy of Lua][]. The terminal +version of Textadept requires [ncurses][]. This dependency is only necessary if +you wish to run the editor from a terminal. [GTK+]: http://gtk.org +[copy of Lua]: 11_Scripting.html#Lua.Configuration [ncurses]: http://invisible-island.net/ncurses/ncurses.html -### Linux +### Linux and BSD + +Most Linux and BSD systems already have GTK+ installed. If not, it is probably +available through your package manager. Otherwise, compile and install it from +the [GTK+ website][]. -Most Linux systems already have GTK+ installed. If not, it is probably available -through your package manager. Otherwise, compile and install it from the -[GTK+ website][]. +The GUI versions of Textadept in the Linux binary downloads require GLib version +2.28 or later to support single-instance functionality. You can compile +Textadept with earlier versions of GLib down to 2.22. For reference, Ubuntu +11.04, Debian Wheezy, Fedora 15, and openSUSE 11.4 support GLib 2.28 or later. -Most Linux systems already have ncurses installed. If not, look for it in your -package manager, or compile and install it from the [ncurses website][]. For -Debian-based distributions like Ubuntu, the package is typically called -`libncursesw5`. Note: you should have a version of ncurses compiled with "wide" +Most Linux and BSD systems already have ncurses installed. If not, look for it in +your package manager, or compile and install it from the [ncurses website][]. +For Debian-based distributions like Ubuntu, the package is typically called +`libncursesw5`. Note: you need to have a version of ncurses compiled with "wide" (multibyte) character support installed. [GTK+ website]: http://www.gtk.org/download-linux.html @@ -48,15 +43,18 @@ No requirements. ## Download -Download Textadept from the [project page][]. Select the appropriate package for -your platform. +Download Textadept from the project's [download page][] by selecting the +appropriate package for your platform. For Windows and Mac OSX, more than 3/4 of +the download and unpackaged application sizes are due to the bundled GTK+. +Textadept itself is much smaller. -You can also download an official set of [language-specific modules][], but this -is optional. The list of language modules in the package is contained [here][]. -Textadept includes C/C++ and Lua language modules by default. +You can also download an official set of [language-specific modules][] from the +download page, but this is optional. The list of language modules in the package +is contained [here][]. Textadept includes C/C++ and Lua language modules by +default. -[project page]: http://foicica.com/textadept -[language-specific modules]: 7_Modules.html#Language.Specific +[download page]: http://foicica.com/textadept/download +[language-specific modules]: 07_Modules.html#Language-Specific [here]: http://foicica.com/hg ## Installation @@ -64,47 +62,48 @@ Textadept includes C/C++ and Lua language modules by default. Textadept is designed to be as easy as possible to install by any user. You do not need to have administrator privileges. -### Linux +### Linux and BSD Unpack the archive anywhere. If you downloaded the set of language-specific modules, unpack it where you -unpacked the Textadept archive. The modules will be contained in -`/path/to/textadept_VERSION/modules/`. +unpacked the Textadept archive. The modules will be contained in the +`/path/to/textadept_VERSION/modules/` directory. ### Mac OSX Unpack the archive and move `Textadept.app` to your user or system `Applications` directory like any other Mac OSX application. There is also a `ta` script for launching Textadept from the command line that you can put in -your `PATH`, but this is optional. +your `PATH` (e.g. `/usr/local/bin`), but this is optional. If you downloaded the set of language-specific modules, unpack it, right-click `Textadept.app`, select `Show Package Contents`, navigate to -`Contents/Resources/modules`, and copy the unpacked modules there. +`Contents/Resources/modules/`, and copy the unpacked modules there. ### Windows Unpack the archive anywhere. If you downloaded the set of language-specific modules, unpack it where you -unpacked the Textadept archive. The modules will be contained in -`textadept_VERSION\modules\`. +unpacked the Textadept archive. The modules will be contained in the +`textadept_VERSION\modules\` directory. ## Running -### Linux +### Linux and BSD Run Textadept by running `/path/to/textadept_VERSION/textadept` from the -terminal. You can also create a symlink to the executable in your `PATH` (e.g. -`/usr/bin`) or make a GNOME, KDE, XFCE, etc. button or menu launcher. +terminal. You can also create a symbolic link to the executable in your `PATH` +(e.g. `/usr/bin`) or make a GNOME, KDE, XFCE, etc. button or menu launcher. There is also a `textadeptjit` executable for running Textadept with [LuaJIT][]. Please note there may be [compatibility issues][]. The `textadept` executable is recommended. The `textadept-ncurses` and `textadeptjit-ncurses` executables are versions of -Textadept for the terminal. +Textadept for the terminal. Run them as you would run the `textadept` and +`textadeptjit` executables, but from a terminal instead. [LuaJIT]: http://luajit.org [compatibility issues]: 11_Scripting.html#LuaJIT @@ -114,17 +113,21 @@ Textadept for the terminal. It is difficult to provide a single binary that runs on all Linux platforms since the versions of software installed vary widely from distribution to distribution. Because the Linux version of Textadept uses the version of GTK+ -installed on your system, an error like: `error while loading shared libraries: -<lib>: cannot open shared object file: No such file or directory` may occur when -trying to run the program. The solution is actually quite painless even though -it requires recompiling Textadept. See the [compiling][] page for more -information. +installed on your system, an error like: + + error while loading shared libraries: <lib>: cannot open shared object + file: No such file or directory + +may occur when trying to run the program. The solution is actually quite +painless even though it requires recompiling Textadept. See the [compiling][] +page for more information. [compiling]: 12_Compiling.html ### Mac OSX -Run Textadept by double-clicking `Textadept.app`. +Run Textadept by double-clicking `Textadept.app`. You can also pin it to your +dock. `Textadept.app` also contains an executable for running Textadept with [LuaJIT][]. You can enable it by setting a `TEXTADEPTJIT` @@ -137,16 +140,16 @@ non-LuaJIT executable is recommended. #### Environment Variables -By default, GUI apps like Textadept do not utilize environment variables such as +By default, GUI apps like Textadept do not utilize environment variables like `PATH` from your shell profile. Therefore, any [modules][] that use programs contained in `PATH` (e.g. the progams in `/usr/local/bin/`) for run and compile -commands will not be found. The solution is to follow these [instructions][] to +commands will not be found. The solution is to follow [these instructions][] to export whichever environment variables you need. At the very least, set `PATH` to be `$PATH`. You will have to logout and log back in for the changes to take effect. -[modules]: 7_Modules.html -[instructions]: http://developer.apple.com/library/mac/#qa/qa1067/_index.html +[modules]: 07_Modules.html +[these instructions]: http://developer.apple.com/library/mac/#qa/qa1067/_index.html ### Windows @@ -160,14 +163,20 @@ There is also a `textadeptjit.exe` executable for running Textadept with [LuaJIT]: http://luajit.org [compatibility issues]: 11_Scripting.html#LuaJIT +### `~/.textadept` + +Textadept stores all of your preferences and user-data in your `~/.textadept/` +folder. If this folder does not exist, Textadept creates it on startup. You will +learn more about this folder later. + ## Single Instance Textadept is a single-instance application on Linux, BSD, and Mac OSX. This means that after Textadept is opened, running `textadept file.ext` (`ta file.ext` on Mac OSX) from the command line or opening a file with -Textadept from a file manager will open `file.ext` in the already open instance -of Textadept. You can override this and open the file in a new instance by -passing a `-f` or `--force` switch to Textadept: `textadept -f file.ext` +Textadept from a file manager will open `file.ext` in the existing instance of +Textadept. You can override this and open the file in a new instance by passing +a `-f` or `--force` switch to Textadept: `textadept -f file.ext` (`ta -f file.ext`). When the force switch is not present, files will be opened in the original Textadept instance, regardless of how many instances are open. diff --git a/doc/03_UserInterface.md b/doc/03_UserInterface.md index 540ba2cc..948038cb 100644 --- a/doc/03_UserInterface.md +++ b/doc/03_UserInterface.md @@ -2,40 +2,47 @@  -Textadept's user interface was designed to be simple. It consists of a menubar -(GUI version), editor view, initially hidden find/replace dialog, initially -hidden command entry, and statusbar. Below are brief descriptions of these -features. More in-depth discussion about some of them is provided later in the -manual. +Textadept's user interface was designed to be simple. It consists of a menu (GUI +version only), editor view, and statusbar. There is also a find & replace pane +and a command entry, both of which are initially hidden. Below are brief +descriptions of these features. More in-depth discussion about some of them is +provided later in the manual. -## Menubar +## Menu -The completely customizable (and optional!) menubar provides access to all of -Textadept's features. It is only available in the GUI version of Textadept. -In the terminal, you can use the -[command selection](10_Advanced.html#Command.Selection) dialog instead. +The completely customizable menu provides access to all of Textadept's features. +It is only available in the GUI version of Textadept. In the terminal, you can +use the [command selection][] dialog instead. Textadept is very keyboard-driven +so most menu items have an assigned key shortcut. Key bindings are changeable +in your [key preferences][] and will reflect in the menu. Here is a +[complete list][] of default key bindings. + +[command selection]: 10_Advanced.html#Command.Selection +[key preferences]: 08_Preferences.html#Key.Bindings +[complete list]: api/_M.textadept.keys.html#Key.Bindings ## Editor View -The editor view is where you will spend most of your time in Textadept. It -supports unlimited split views (GUI version) and is completely controllable by -Lua. +The editor view is where you will spend most of your time in Textadept. In the +GUI version, you can split this view into as many other views as you would like. +Each view is completely controllable by Lua. -## Find and Replace Dialog +## Find & Replace Pane -This compact dialog is a great way to slice and dice through your document or +This compact pane is a great way to slice and dice through your document or a directory of files. You can even find and replace text using Lua patterns. It is -available when you need it and quickly gets out of your way when you do not, -minimizing distractions. +available only when you need it and quickly gets out of your way when you do +not, minimizing distractions. ## Command Entry -The versatile command entry functions as both a place to execute Lua commands -with the internal Lua state and find text incrementally. You can extend it to do -even more if you would like. Like the find/replace dialog, the command entry -pops in and out as you wish. +The versatile command entry functions as, among other things, a place to execute +Lua commands with Textadept's internal Lua state, find text incrementally, and +execute shell commands. You can extend it to do even more. Like the Find & +Replace pane, the command entry pops in and out as you wish. ## Statusbar -The left side of the statusbar displays any status messages. The right side -shows the current buffer's status. +The statusbar is actually composed to two statusbars. The one on the left-hand +side displays temporary status messages. The one on the right-hand side +persistently shows the current buffer status. diff --git a/doc/04_WorkingWithFiles.md b/doc/04_WorkingWithFiles.md index 4508e4a1..dd9f515c 100644 --- a/doc/04_WorkingWithFiles.md +++ b/doc/04_WorkingWithFiles.md @@ -1,22 +1,15 @@ # Working with Files -## Lack of Tabs +## Buffers One of the first things you will notice when opening multiple files in Textadept is that there is no tab bar showing the files that are open. This was a design -decision. Textadept was built to support unlimited split views, so having a tab -bar with all open buffers would clutter the interface greatly. There is also the -question of where to place the bar (above, below, or to one side) and how many -to have (one for each split view or a single one under the menubar). +decision because Textadept was built to support unlimited split views. Having a +single tab bar for multiple views would cause confusion and having one tab bar +per view would clutter the interface. -You can see which buffer is active by looking at Textadept's titlebar. Pressing -`Ctrl+Tab` (`^⇥` on Mac OSX | `M-N` in ncurses) cycles to the next buffer and -`Ctrl+Shift+Tab` (`^⇧⇥` | `M-P`) cycles to the previous one. - -## Buffer Browser - -To move quickly between buffers, press `Ctrl+B` (`⌘B` on Mac OSX | `M-B` or -`M-S-B` in ncurses) to open the buffer browser. +Instead of having tabs, Textadept has the buffer browser. Press `Ctrl+B` (`⌘B` +on Mac OSX | `M-B` or `M-S-B` in ncurses) to open it.  @@ -27,17 +20,104 @@ wildcards. You can also just use the arrow keys. Pressing `Enter` or selecting  -## Split Views +You can see which buffer is active by looking at Textadept's titlebar. Pressing +`Ctrl+Tab` (`^⇥` on Mac OSX | `M-N` in ncurses) cycles to the next buffer and +`Ctrl+Shift+Tab` (`^⇧⇥` | `M-P`) cycles to the previous one. + +### Settings + +Individual files have three configurable settings: indentation, line endings, +and encoding. Indentation is composed of an indentation character and an +indentation size. Line endings are characters that separate lines. File +encoding determines how text characters are displayed. Textadept shows these +settings in the buffer status statusbar. + + + +#### Indentation + +Indentation is usually set by a [language-specific module][] or the current +[theme][]. By default, indentation is 2 spaces. You can toggle between using +tabs and spaces manually by pressing `Ctrl+Alt+Shift+T` (`^⇧T` on Mac OSX | +`M-T` or `M-S-T` in ncurses). Toggling between tabs and spaces only affects +future indentation; it does not convert existing indentation. `Ctrl+Alt+I` (`^I` +| `M-I`) performs the conversion. (If the buffer is using tabs, all indenting +spaces are converted to tabs. If the buffer is using spaces, all indenting tabs +are converted to spaces.) Similarly, you can set indentation size manually using +the `Buffer -> Indentation` menu. + +[language-specific module]: 07_Modules.html#Buffer.Properties +[theme]: 09_Themes.html#Buffer + +#### Line Endings + +Line endings, commonly known as end-of-line (EOL) markers, are set based on the +current platform. On Windows, CRLF (`\r\n`) is used. Otherwise, LF (`\n`) is. +This can be changed manually using the `Buffer -> EOL Mode` menu. + +#### Encodings + +Textadept represents all characters and strings internally as UTF-8. You will +not notice any difference for working with files containing ASCII text since +UTF-8 is compatible with it. Textadept can also detect ISO-8859-1 and MacRoman, +the primary encodings used on Windows and Mac OSX respectively. Files with more +exotic encodings may not be detected properly, if at all. You can change the +list of encodings Textadept tries to detect via [`io.try_encodings`][]. + +It is recommended to use UTF-8 encoded files because UTF-8 is very well +supported by other text editors and operating systems. You can change file +encoding via the `Buffer -> Encoding` menu. Conversion is immediate, requiring +no separate steps. Textadept saves new files as UTF-8 by default, but does not +alter the encoding of existing files. + +[`io.try_encodings`]: api/io.html#try_encodings + +### Recent Files + +Pressing `Ctrl+Alt+O` (`^⌘O` on Mac OSX | `M-^O` in ncurses) brings up a dialog +that behaves like the buffer browser, but displays a list of recently opened +files to reopen. -Textadept allows you to split the editor window as many times as you like either -horizontally or vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits horizontally -(top-bottom) and `Ctrl+Alt+V` splits vertically (`^S` and `^V` respectively on -Mac OSX | N/A in ncurses). You can resize the splitter bar by clicking and -dragging with the mouse or using `Ctrl+Alt++` and `Ctrl+Alt+-` (`^+` and `^-` | -N/A). The same file can be worked with in multiple split views. +### Sessions + +By default, Textadept saves its state on exit so it can be restored the next +time the editor starts up. You can disable this by passing the `-n` or +`--no-session` switch to Textadept on startup. Sessions can be manually saved +and opened via the `File -> Save Session...` and `File -> Load Session...` +menus. Session files store information such as open buffers, current split +views, caret and scroll positions in each buffer, Textadept's window size, and +recently opened files. Tampering with session files may have unintended +consequences. + +### Snapopen + +A quicker, though slightly more limited alternative to the standard file +selection dialog is snapopen. It behaves like the buffer browser, but displays a +list of files to open, including files in sub-directories. You can snapopen the +current file's directory with `Ctrl+Alt+Shift+O` (`^⌘⇧O` on Mac OSX | `M-S-O` in +ncurses) or from the `Tools -> Snapopen -> Current Directory` menu. Snapopen is +pretty limited from the menu, but more versatile in [scripts][]. `Ctrl+U` (`⌘U` +| `^U`) snaps open `~/.textadept/`. + +[scripts]: api/_M.textadept.snapopen.html + + + +## Views + +### Split Views + +Textadept allows you to split the editor window as many times as you like both +horizontally and vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits horizontally +into top and bottom views and `Ctrl+Alt+V` splits vertically (`^S` and `^V` +respectively on Mac OSX | N/A in ncurses) into side-by-side views. You can +resize the splitter bar by clicking and dragging with the mouse or using +`Ctrl+Alt++` and `Ctrl+Alt+-` (`^+` and `^-` | N/A). The same file can be worked +with in multiple views. Pressing `Ctrl+Alt+N` (`^⌥⇥` on Mac OSX | N/A in ncurses) goes to the next view -and `Ctrl+Alt+P` (`^⌥⇧⇥` | N/A) goes to the previous one. +and `Ctrl+Alt+P` (`^⌥⇧⇥` | N/A) goes to the previous one. Note: depending on the +split sequence, the order when cycling between views may be unexpected. To unsplit a view, enter the view to keep open and press `Ctrl+Alt+W` (`^W` on Mac OSX | N/A in ncurses). To unsplit all views, use `Ctrl+Alt+Shift+W` (`^⇧W` | @@ -45,28 +125,42 @@ N/A). Split views are unavailable in ncurses. -## Sessions +### Settings -By default, Textadept saves the list of open buffers on exit so it can reload -them the next time it starts up. You can disable this by passing the `-n` or -`--no-session` switch to Textadept on startup. Sessions can be manually saved -and opened via the `File -> Save Session...` and `File -> Load Session...` -menus. +Individual views have many configurable settings. Among the more useful settings +are viewing line endings, handling long lines, viewing indentation guides, and +viewing whitespace. These options change how buffers in the view are displayed. -Sessions save additional information such as current split views, caret and -scroll positions in each buffer, Textadept's window size, and recently opened -files. +#### Line Endings -## Snapopen +Normally, EOL characters (`\r` and `\n`) are invisible. Pressing +`Ctrl+Alt+Enter` (`^↩` on Mac OSX | none in ncurses) toggles their visibility. -A quicker, though slightly more limited alternative to the standard -`File -> Open` dialog is snapopen. It behaves like the buffer browser, but -displays a list of files to open, including files in subdirectories. You can -snapopen the current file's directory with `Ctrl+Alt+Shift+O` (`^⌘⇧O` on Mac -OSX | `M-S-O` in ncurses) or from the `Tools -> Snapopen -> Current Directory` -menu. Snapopen is pretty limited from the menu, but more versatile in scripts. -See its [LuaDoc][]. `Ctrl+U` (`⌘U` | `^U`) snaps open `~/.textadept/`. +#### Long Lines -[LuaDoc]: api/_M.textadept.snapopen.html +By default, lines with more characters than the view can show are not wrapped +into view. `Ctrl+Alt+\` (`^\` on Mac OSX | none in ncurses) toggles line +wrapping. - +#### Indentation Guides + +By default, small guiding lines are shown based on indentation level. +`Ctrl+Alt+Shift+I` (`^⇧I` on Mac OSX | N/A in ncurses) toggles showing these +guides. + +Indentation guides are unavailable in ncurses. + +#### Whitespace + +Normally, whitespace characters, tabs and spaces, are invisible. Pressing +`Ctrl+Alt+Shift+S` (`^⇧S` on Mac OSX | none in ncurses) toggles their +visibility. Visible spaces are shown as dots and visible tabs are shown as +arrows. + +### Zoom + +You can temporarily increase or decrease the font size in a view with `Ctrl+=` +(`⌘=` on Mac OSX | N/A in ncurses) and `Ctrl+-` (`⌘-` | N/A) respectively. +`Ctrl+0` (`⌘0` | N/A) resets the zoom. + +Zooming is unavailable in ncurses. diff --git a/doc/05_FileNavigation.md b/doc/05_FileNavigation.md index 93e7f9d9..e0749313 100644 --- a/doc/05_FileNavigation.md +++ b/doc/05_FileNavigation.md @@ -1,26 +1,37 @@ # File Navigation -## Bookmarks +## Basic Movements -You can place bookmarks on lines in buffers to jump back to them later. Use the -`Tools -> Bookmark` menu options or key commands to do so. +Textadept supports the key bindings you are accustomed to for navigating text +fields on your platform. The arrow keys move the caret in a particular +direction, `Ctrl+Left` and `Ctrl+Right` (`^⇠` and `^⇢` on Mac OSX | `^Left` and +`^Right` in ncurses) move by words, `PgUp` and `PgDn` (`⇞` and `⇟` | `PgUp` and +`PgDn`) move by pages, etc. Mac OSX and ncurses also support some Bash-style +bindings like `^B`, `^F`, `^P`, `^N`, `^A`, and `^E`. A complete list of +movement bindings is found in the "Movement" section of the +[key bindings list][]. -## Goto Line +[key bindings list]: api/_M.textadept.keys.html#Key.Bindings -To jump to a specific line in a file, press `Ctrl+J` (`⌘J` on Mac OSX | `^J` in -ncurses) and specify the line number in the prompt and press `Enter` (`↩` | -`Enter`) or select `OK`. - -## Goto Matching Brace +## Brace Match By default, Textadept will highlight the matching brace characters under the -caret : `(`, `)`, `[`, `]`, `{`, `}`, `<`, and `>`. Pressing `Ctrl+M` (`^M` on -Mac OSX | `M-M` in ncurses) moves the caret to that matching brace and -`Ctrl+Shift+M` (`^⇧M` | `M-S-M`) extends the selection. +caret : `(`, `)`, `[`, `]`, `{`, and `}`. Pressing `Ctrl+M` (`^M` on Mac OSX | +`M-M` in ncurses) moves the caret to that matching brace.  -## Mac OSX and ncurses +## Bookmarks -Textadept supports the keybindings you are accustomed to for navigating text -fields in Mac OSX and entering commands in the Linux/BSD terminal. +You can place bookmarks on lines in buffers to jump back to them later. +`Ctrl+F2` (`⌘F2` on Mac OSX | none in ncurses) toggles a bookmark on the current +line, `F2` jumps to the next bookmarked line, `Shift+F2` (`⇧F2` | none) jumps to +the previously bookmarked line, `Alt+F2` (`⌥F2` | none) jumps to the bookmark +selected from a list, and `Ctrl+Shift+F2` (`⌘⇧F2` | none) clears all bookmarks +in the current buffer. + +## Goto Line + +To jump to a specific line in a file, press `Ctrl+J` (`⌘J` on Mac OSX | `^J` in +ncurses) and specify the line number in the prompt and press `Enter` (`↩` | +`Enter`) or select `OK`. diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md index b09487ec..8ae6ae6e 100644 --- a/doc/06_AdeptEditing.md +++ b/doc/06_AdeptEditing.md @@ -1,197 +1,270 @@ # Adept Editing -## Key Commands +## Basic Editing -Textadept is entirely keyboard-driven. See the comprehensive list of key -commands in the [appendix][]. Key commands can be modified in your -[key preferences][]. +Textadept has many basic editing features you are familiar with: basic text +entry, undo/redo, clipboard manipulation, deleting characters and words, +duplicating lines, joining lines, and transposing characters. These are +accessible from the top-level `Edit` menu and have associated key bindings. +Some of the basic editing features you may not be familiar with are discussed +below. -[appendix]: 14_Appendix.html#Key.Bindings -[key preferences]: 9_Preferences.html#Key.Commands - -## Character Autopairing +### Autopaired Characters Usually, quote (`'`, `"`) and brace (`(`, `[`, `{`) characters go together in pairs. By default, Textadept automatically inserts the complement character when -the first is typed. Similarly, the complement is deleted when you press -`Backspace` (`⌫`) over the first. See the [preferences][] page if you would like -to disable this. +the first is typed. Similarly, the complement is deleted when you press `Bksp` +(`⌫` on Mac OSX | `Bksp` in ncurses) over the first. See the [preferences][] +page if you would like to disable this. -[preferences]: 9_Preferences.html#Module.Settings +[preferences]: 08_Preferences.html#Generic -## Word Completion +### Word Completion Textadept provides buffer-based word completion. Start typing a word, press -`Ctrl+Return` (`^⎋` on Mac OSX | `M-Enter` in ncurses), and a list of suggested -completions based on words in the current document is provided. Continuing to -type changes the suggestion. Press `Enter` (`↩` | `Enter`) to complete the -selected word. +`Ctrl+Enter` (`^⎋` on Mac OSX | `M-Enter` in ncurses), and a list of suggested +completions based on words in the current buffer is provided. Continuing to type +changes the suggestion. Press `Enter` (`↩` | `Enter`) to complete the selected +word.  -## Adeptsense +### Virtual Space Mode -Textadept has the capability to autocomplete symbols for programming languages -and display API documentation. Lua is of course supported extremely well and -other languages have basic support with the help of [ctags][]. Symbol completion -is available by pressing `Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` in ncurses). -Documentation for symbols is available with `Ctrl+H` (`^H` | `M-H` or `M-S-H`). +Virtual space (freehand) mode is enabled and disabled with `Ctrl+Alt+Shift+V` +(`^⇧V` in Mac OSX | none in ncurses). When enabled, caret movement is not +restricted by line endings. - - - +### Overwrite Mode - +Overwrite mode is enabled and disabled with the `Insert` key. When enabled, +characters in the buffer will be overwritten instead of inserted as you type. +The caret also changes to an underline when in overwrite mode. -For more information on adding adeptsense support for another language, see -the [LuaDoc][]. +## Selections -[ctags]: http://ctags.sf.net -[LuaDoc]: api/_M.textadept.adeptsense.html +Textadept has many ways of creating and working with selections. Basic +selections are what you get when you do things like hold the `Shift` modifier +key (`⇧` on Mac OSX | `S-` in ncurses) while pressing the arrow keys, click and +drag the mouse over a range of text, or press `Ctrl+A` (`⌘A` | `M-A`) for +"Select All". More advanced selections like multiple and rectangular selections +are more complicated to create, but have powerful uses. -## Find and Replace +### Multiple Selection -`Ctrl+F` (`⌘F` on Mac OSX | `M-F` or `M-S-F` in ncurses) brings up the -Find/Replace dialog. In addition to offering the usual find and replace, -Textadept allows you to find with [Lua patterns][] and replace with Lua captures -and even Lua code! For example: replacing all `(%w+)` with -`%(string.upper('%1'))` capitalizes all words in the buffer. Lua captures (`%n`) -are only available from a Lua pattern search, but embedded Lua code enclosed in -`%()` is always allowed. +Clicking the mouse at a point in the buffer while holding the `Ctrl` modifier +key (`^` on Mac OSX | N/A in ncurses) places an additional caret at that point. +Clicking and dragging while holding the same modifier creates multiple +selections. When you start typing, the text is mirrored at each selection. -Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key commands -for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, `^⇧R` -respectively on Mac OSX | `M-G`, `M-S-G`, `M-R`, `M-S-R` in ncurses) only work -when the Find/Replace dialog is hidden. When it is visible in the GUI version, -use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and `Alt+A` (`⌘N`, `⌘P`, -`⌘R`, `⌘A` | N/A) for English locale. +This is currently unavailable in ncurses. -In the ncurses version, use `Tab` and `S-Tab` to toggle between the find next, -find previous, replace, and replace all buttons; `Up` and `Down` arrows switch -between the find and replace text fields; `^P` and `^N` cycles through history; -and `F1-F4` toggles find options. +### Rectangular Selection -[Lua patterns]: 14_Appendix.html#Lua.Patterns +Holding `Alt+Shift` (`⌥⇧` on Mac OSX | `M-S-` in ncurses) and pressing the arrow +keys enables rectangular selections to be made. Start typing to type on each +line. -### Find in Files + + + -`Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX | none in ncurses) and -will prompt for a directory to search. The results are displayed in a new -buffer. Double-clicking a search result jumps to it in the file. You can also -use the `Ctrl+Alt+G` and `Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` on Mac OSX | none -in ncurses) key commands. Replace in Files is not supported. You will have to -`Find in Files` first, and then `Replace All` for each file a result is found -in. The `Match Case`, `Whole Word`, and `Lua pattern` flags still apply. +### Select to Matching Brace - +Putting the caret over a brace character (`(`, `)`, `[`, `]`, `{`, or `}`) and +pressing `Ctrl+Shift+M` (`^⇧M` on Mac OSX| `M-S-M` in ncurses) extends the +selection to the brace character's matching brace. -### Find Incremental +### Entity Selection -You can start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | -`M-^F` in ncurses). Incremental search searches the buffer as you type. Only the -`Match Case` option is recognized. Pressing `Esc` (`⎋` | `Esc`) stops it. +Textadept allows you to select many different entities from the caret. For +example, `Ctrl+"` (`^"` on Mac OSX | `M-"` in ncurses) selects all characters in +a `""` sequence. Typing `Ctrl++` (`^+` | `M-+`) as a follow-up selects the +double-quotes too. See the `Edit -> Select In...` menu for available entities +and their key bindings. -### Replace in Selection +### Transforms -By default, `Replace All` replaces all text in the buffer. If you want to -replace all text in just a portion of the buffer, select a block of text and -then `Replace All`. +#### Enclose Entities -## Indentation +As a complement to selecting entities, you can enclose text as entities. The +`Edit -> Selection -> Enclose In...` menu contains all available entities and +their key bindings. -### Change Indent Level +If no text is selected, the word to the left of the caret is enclosed. + +#### Change Case + +Pressing `Ctrl+Alt+U` or `Ctrl+Alt+Shift+U` (`^U` or `^⇧U` on Mac OSX | `M-^U` +or `M-^L` in ncurses) converts selected text to upper-case letters or lower-case +letters respectively. + +#### Change Indent Level The amount of indentation for a selected set of lines is increased by pressing -`Tab` (`⇥` | `Tab`) and decreased by pressing `Shift+Tab` (`⇧⇥` | `S-Tab`). -Using these key sequences when no selection is present does not have the same -effect. +`Tab` (`⇥` on Mac OSX | `Tab` in ncurses) and decreased by pressing `Shift+Tab` +(`⇧⇥` | `S-Tab`). Whole lines do not have to be selected. As long as any part of +a line is selected, the entire line is eligible for indenting/dedenting. Using +these key sequences when no selection is present does not have the same effect. + +#### Move Lines + +Selected lines are moved with the `Ctrl+Shift+Up` and `Ctrl+Shift+Down` (`^⇧⇡` +and `^⇧⇣` on Mac OSX | `S-^Up` and `S-^Down` in ncurses) keys. Like with +changing indent level, as long as any part of a line is selected, the entire +line is eligible for moving. + +## Find & Replace -### Change Indent Size +`Ctrl+F` (`⌘F` on Mac OSX | `M-F` or `M-S-F` in ncurses) brings up the Find & +Replace pane. In addition to offering the usual find and replace with "Match +Case" and "Whole Word" options and find/replace history, Textadept allows you to +find with [Lua patterns][] and replace with Lua captures and even Lua code! For +example: replacing all `(%w+)` with `%(string.upper('%1'))` upper-cases all +words in the buffer. Lua captures (`%`_`n`_) are only available from a Lua +pattern search, but embedded Lua code enclosed in `%()` is always allowed. -The indent size is usually set by a [language-specific module][] or the -[theme][]. You can set it manually using the `Buffer -> Indentation` menu. -Textadept shows what it is using for indentation in the document statusbar. +Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key bindings +for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, `^⇧R` +respectively on Mac OSX | `M-G`, `M-S-G`, `M-R`, `M-S-R` in ncurses) only work +when the Find & Replace pane is hidden. When the pane is visible in the GUI +version, use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and `Alt+A` (`⌘N`, +`⌘P`, `⌘R`, `⌘A` | N/A) for English locale. - +In the ncurses version, `Tab` and `S-Tab` toggles between the find next, find +previous, replace, and replace all buttons; `Up` and `Down` arrows switch +between the find and replace text fields; `^P` and `^N` cycles through history; +and `F1-F4` toggles find options. -[language-specific module]: 7_Modules.html#Buffer.Properties -[theme]: 8_Themes.html#Buffer +[Lua patterns]: 14_Appendix.html#Lua.Patterns -### Using Tabs +### Replace in Selection -You can use tabs instead of the default spaces by pressing `Ctrl+Alt+Shift+T` -(`^⇧T` on Mac OSX | `M-T` or `M-S-T` in ncurses) or using the `Buffer -> Toggle -Use Tabs` menu. Textadept shows what it is using for indentation in the document -statusbar. +By default, `Replace All` replaces all text in the buffer. If you want to +replace all text in just a portion of the buffer, select a block of text and +then `Replace All`. -The default option is usually set by a [language-specific module][] or the -[theme][]. +### Find in Files -[language-specific module]: 7_Modules.html#Buffer.Properties -[theme]: 8_Themes.html#Buffer +`Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX | none in ncurses) and +will prompt for a directory to search. The results are displayed in a new +buffer. Double-clicking a search result jumps to it in the file. You can also +use the `Ctrl+Alt+G` and `Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` on Mac OSX | none +in ncurses) key bindings. Replace in Files is not supported. You will have to +`Find in Files` first, and then `Replace All` for each file a result is found +in. The `Match Case`, `Whole Word`, and `Lua pattern` flags still apply. -### Converting Indentation +_Warning_: currently, there is no way to specify a file-type filter, so Find in +Files will scan **all** files, even binary ones, in **all** sub-directories. +Searches also block Textadept from receiving additional input, making the +interface temporarily unresponsive. Searching large directories or projects can +be very time consuming and frustrating, so using a specialized, external tool +such as [ack][] is recommended. -Use the `Edit -> Convert Indentation` menu to convert indentation. If the buffer -is using tabs, all spaces are converted to tabs. If the buffer is using spaces, -all tabs are converted to spaces. + -## Selecting Text +[ack]: http://betterthangrep.com/ -### Rectangular Selection +### Incremental Find -Holding `Alt+Shift` (`⌥⇧` on Mac OSX | `M-S` in ncurses) and pressing the arrow -keys enables rectangular selections to be made. Start typing to type on each -line. +You can start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | +`M-^F` in ncurses). Incremental search searches the buffer as you type. Only the +`Match Case` option is recognized. Pressing `Esc` (`⎋` | `Esc`) stops the +search. - - - +## Source Code Editing -### Multiple Selection +Textadept would not be a programmer's editor without some features for editing +source code. Textadept understands the syntax and structure of more than 80 +different programming languages and recognizes hundreds of file types. It uses +this knowledge to make viewing and editing code faster and easier. -Clicking the mouse at a point in the buffer while holding `Control` places an -additional caret at that point. Clicking and dragging while holding `Control` -creates multiple selections. Start typing to enter text at each selection. +### Lexers -This is currently unavailable in ncurses. +When you open a file, chances are that Textadept will identify the programming +language associated with that file and set a "lexer" to highlight syntactic +elements of the code. You can set or change the lexer manually by pressing +`Ctrl+Shift+L` (`⌘⇧L` on Mac OSX | `M-S-L` in ncurses) and selecting a lexer +from the list. You can customize how Textadept recognizes files in your +[file type preferences][]. -### Selecting Entities +Lexers can sometimes lose track of their context while you are editing and +highlight syntax incorrectly. Pressing `F5` triggers a full redraw. -Textadept allows you to select many different entities from the caret. For -example, `Ctrl+"` (`^"` on Mac OSX | `M-"` in ncurses) selects all characters in -a `""` sequence. Typing `Ctrl++` (`^+` | `M-+`) as a follow-up selects the -double-quotes too. See the `Edit -> Select In...` menu for available entities -and their key commands. +[file type preferences]: 08_Preferences.html#File.Types -## Enclosing Text +### Code Folding -As a complement to selecting entities, you can enclose text as entities. The -`Edit -> Selection -> Enclose In...` menu contains all available entities and -their key commands. +Some lexers support code folding, where blocks of code can be temporarily +hidden, making viewing easier. Fold points are denoted by arrows in the margin +to the left of the code. Clicking on one toggles the folding for that block of +code. -If no text is selected, the word to the left of the caret is enclosed. + -## Word Highlight +### Word Highlight All occurrences of a given word are highlighted by putting the caret over the word and pressing `Ctrl+Alt+Shift+H` (`⌘⇧H` on Mac OSX | N/A in ncurses). This -is useful to show occurrences of a variable name in source code. +is useful to show occurrences of a variable name, but is not limited to source +code. + + This is not supported in ncurses. - +### Adeptsense + +Textadept has the capability to autocomplete symbols for programming languages +and display API documentation. Symbol completion is available by pressing +`Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` in ncurses). Documentation for symbols +is available with `Ctrl+H` (`^H` | `M-H` or `M-S-H`). Note: In order for this +feature to work, the language you are working with must have an [Adeptsense][] +defined. Language-specific modules usually [define Adeptsenses][]. -## Editing Modes + + + -### Virtual Space + -Virtual space (freehand) mode is enabled and disabled with `Ctrl+Alt+Shift+V` -(`^⇧V` in Mac OSX | none in ncurses). When enabled, caret movement is not -restricted by line endings. +[Adeptsense]: api/_M.textadept.adeptsense.html +[define Adeptsenses]: api/_M.html#Adeptsense + +### Snippets + +Snippets are essentially pieces of text inserted into a document. However, +snippets are not limited to static text. They can be dynamic templates which +contain placeholders for further user input, can mirror or transform those user +inputs, and/or execute arbitrary code. Snippets are useful for rapidly +constructing blocks of code such as control structures, method calls, and +function declarations. Press `Ctrl+K` (`⌥⇥` on Mac OSX | `M-K` in ncurses) for a +list of available snippets. Snippets are composed of trigger word and snippet +text. Instead of manually selecting a snippet, you can type its trigger word +followed by the `Tab` (`⇥` | `Tab`) key. Subsequent presses of `Tab` (`⇥` | +`Tab`) cause the caret to enter placeholders in sequential order, `Shift+Tab` +(`⇧⇥` | `S-Tab`) goes back to the previous placeholder, and `Ctrl+Shift+K` +(`⌥⇧⇥` | `M-S-K`) cancels the current snippet. Snippets can be nested (inserted +from within another snippet) and are not limited to source code. +Language-specific modules usually [define snippets][], but you can create your +own custom snippets in your [snippet preferences][]. + + + + -### Overwrite +[define snippets]: api/_M.html#Snippets +[snippet preferences]: 08_Preferences.html#Snippets -Overwrite mode is enabled and disabled with the `Insert` key. When enabled, -characters in the buffer will be overwritten instead of inserted as you type. -The caret also changes to an underline when in overwrite mode. +### Toggle Comments + +Pressing `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in ncurses) comments or uncomments +the code on the selected lines. As long as any part of a line is selected, the +entire line will be commented or uncommented. Note: In order for this feature to +work, the language you are working with must have its comment prefix defined. +Language-specific modules usually [define prefixes][], but it can also be done +[manually][] in your [user-init file][]. + +[define prefixes]: api/_M.html#Block.Comment +[manually]: http://foicica.com/wiki/comment-supplemental +[user-init file]: 08_Preferences.html#User.Init diff --git a/doc/07_Modules.md b/doc/07_Modules.md index afe9f0db..8ea211e8 100644 --- a/doc/07_Modules.md +++ b/doc/07_Modules.md @@ -1,92 +1,69 @@ # Modules -Most of Textadept's functionality comes from modules written in Lua. A module -consists of a single directory with an `init.lua` script to load any additional -Lua files (typically in the same location). Essentially there are two classes of -module: generic and language-specific. +Most of Textadept's functionality comes from Lua modules. Essentially there are +two classes of module: generic and language-specific. A generic module provides +features for all programming languages while a language-specific module provides +features for a specific programming language. ## Generic -This class of modules is usually available globally for programming in all -languages or writing plain-text. An example is the [textadept module][] which -implements most of Textadept's functionality (find/replace, key commands, menus, -snippets, etc.). These kinds of modules are generally loaded on startup. See the -[preferences][] page for instructions on how to load generic modules when -Textadept starts. +Generic modules have a broad scope and are usually available for programming in +all languages or writing plain-text. An example is the [textadept module][] +which implements most of Textadept's functionality (find & replace, key +bindings, menus, snippets, etc.). These kinds of modules are generally loaded on +startup. See the [preferences][] page for instructions on how to load generic +modules when Textadept starts. [textadept module]: api/_M.textadept.html -[preferences]: 9_Preferences.html#User.Init +[preferences]: 08_Preferences.html#Loading.Modules -## Language Specific +## Language-Specific -Each module of this class of modules is named after a language lexer in the -`lexers/` directory and is only available only for editing code in that -particular programming language unless you specify otherwise. Examples are the -[cpp][] and [lua][] modules which provide special editing features for the C/C++ -and Lua languages respectively. +Language-specific modules have a scope limited to a single programming language. +The name of the module is named after the language's lexer in the `lexers/` +directory and is automatically loaded when editing source code in that +particular language. In addition to some of the editing features discussed +[earlier][], these kinds of modules typically also have shell commands for +running and compiling code, indentation settings, custom key bindings, and +perhaps a custom context menu. These features are discussed below. -[cpp]: api/_M.cpp.html -[lua]: api/_M.lua.html +[earlier]: 06_AdeptEditing.html#Source.Code.Editing -### Lexer +### Compile and Run -All languages have a [lexer][] that performs syntax highlighting on the source -code. While the lexer itself is not part of the module, its existence in -`lexers/` is required. +Most language-specific modules have a command that compiles and/or runs the code +in the current file. Pressing `Ctrl+Shift+R` (`⌘⇧R` on Mac OSX | `M-^R` in +ncurses) executes the command for compiling code and `Ctrl+R` (`⌘R` | `^R`) +executes the command for running code. Double-clicking on any error messages +will jump to where the errors occurred. Note: In order for these features to +work, the language you are working with must have its run command and error +format defined. If the language-specific module does not exist or does not +[define][] commands or an error format, it can be done [manually][] in your +[user-init file][]. -[lexer]: api/lexer.html +[define]: api/_M.html#Compile.and.Run +[manually]: http://foicica.com/wiki/run-supplemental +[user-init file]: 08_Preferences.html#User.Init -### Activation - -Language-specific modules are automatically loaded when a file of that language -is loaded or a buffer's lexer is set to that language. - -### Snippets - -Most language-specific modules have a set of [snippets][]. Press `Ctrl+K` (`⌥⇥` -on Mac OSX | `M-K` in ncurses) for a list of available snippets or see the -module's Lua code. To insert a snippet, type its trigger followed by the `Tab` -(`⇥` | `Tab`) key. Subsequent presses of `Tab` (`⇥` | `Tab`) causes the caret to -enter tab stops in sequential order, `Shift+Tab` (`⇧⇥` | `S-Tab`) goes back to -the previous tab stop, and `Ctrl+Shift+K` (`⌥⇧⇥` | `M-S-K`) cancels the current -snippet. Snippets can be nested (inserted from within another snippet). - - - - - -[snippets]: api/_M.textadept.snippets.html - -### Commands - -Most language-specific modules have a set of [key commands][]. See the module's -Lua code for which key commands are available. They are typically stored in the -`Ctrl+L` (`⌘L` on Mac OSX | `M-L` in ncurses) key prefix. - -[key commands]: api/_M.textadept.keys.html - -#### Run - -Most language-specific modules have a command that runs the code in the current -file. Pressing `Ctrl+R` (`⌘R` on Mac OSX | `^R` in ncurses) runs that command. - -#### Compile +### Buffer Properties -Most language-specific modules have a command that compiles the code in the -current file. Pressing `Ctrl+Shift+R` (`⌘⇧R` on Mac OSX | `M-^R` in ncurses) -runs that command. +Some programming languages have style guidelines for indentation and/or line +endings which differ from Textadept's defaults. In this case, language-specific +modules [set][] these preferences. If you wish to change them or use your own +preferences, see the [language module preferences][] section. -#### Block Comments +[set]: api/_M.html#Buffer.Properties +[language module preferences]: 08_Preferences.html#Language-Specific -Pressing `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in ncurses) comments or uncomments -the code on the selected lines. +### Key Bindings -### Buffer Properties +Most language-specific modules have a set of key bindings for +[custom commands][]. See the module's [LuaDoc][] or code to find out which key +bindings are assigned. They are typically stored in the `Ctrl+L` (`⌘L` on Mac +OSX | `M-L` in ncurses) key chain prefix. -Sometimes language-specific modules set default buffer properties like tabs and -indentation size. See the module's Lua code for these settings. If you wish to -change them or use different settings, see the -[Customizing Modules](#Customizing.Modules) section below. +[custom commands]: api/_M.html#Commands +[LuaDoc]: api/index.html ### Context Menu @@ -99,9 +76,7 @@ The officially supported language modules are hosted [here][] and are available as a separate download. To upgrade to the most recent version of a module, you can either use [Mercurial][] (run `hg pull` and then `hg update` on or from within the module) or download a zipped version from the module's repository -homepage and overwrite the existing one. If you do not have access to `_HOME`, -place the updated module in your `_USERHOME` and replace all instances of -`_HOME` with `_USERHOME` in the module's `init.lua`. +homepage and overwrite the existing one. For now, user-created modules are obtained from the [wiki][]. @@ -111,7 +86,10 @@ For now, user-created modules are obtained from the [wiki][]. ## Installing Modules -It is recommended to put all custom or user-created modules in your +If you do not have write permissions for the directory Textadept is installed +in, place the module in your `~/.textadept/modules/` folder and replace all +instances of `_HOME` with `_USERHOME` in the module's `init.lua`. It is +recommended to put all custom or user-created modules in your `~/.textadept/modules/` directory so they will not be overwritten when you update Textadept. Also, modules in that directory override any modules in Textadept's `modules/` directory. This means that if you have your own `lua` @@ -119,41 +97,6 @@ module, it will be loaded instead of the one that comes with Textadept. ## Developing Modules -See the [LuaDoc][] for modules. - -[LuaDoc]: api/_M.html - -## Customizing Modules - -It is never recommended to modify the default modules that come with Textadept, -even if you just want to change the buffer settings for a language-specific -module or add a few more snippets. Instead you have two options: load your own -module instead of the default one or load your custom module code after the -default module loads. To load your own module, simply place it appropriately in -`~/.textadept/modules/`. To load your module code after the default module -loads, create a `post_init.lua` Lua script in the appropriate -`~/.textadept/modules/` sub-folder. Please note that for generic modules, only -the first option applies. Either option applies for language-specific modules. - -Suppose you wanted to completely change the menubar structure. You would first -create a new `menu.lua` and then put it in `~/.textadept/modules/textadept/`. -Now when Textadept looks for `menu.lua`, it will load yours instead of its own. -Similarly, if you copy the default Lua language-specific module (`modules/lua`) -to `~/.textadept/modules/` and make custom changes, that module is loaded for -editing Lua code instead of the default module. - -If you keep a modified copy of language-specific modules, you will likely want -to update them with each new Textadept release. Instead of potentially wasting -time merging your changes, you can load custom code independent of the module in -a `post_init.lua` file. For example, instead of copying the `lua` module and -changing its `set_buffer_properties()` function to use tabs, you can do this -from `post_init.lua`: - - function _M.lua.set_buffer_properties() - buffer.use_tabs = true - end - -Similarly, you can use `post_init.lua` to change the compile/run commands, load -more [Adeptsense tags][], and add additional key commands and snippets. +See the [module LuaDoc][]. -[Adeptsense tags]: api/_M.textadept.adeptsense.html#load_ctags +[module LuaDoc]: api/_M.html diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md new file mode 100644 index 00000000..f0cdd2f0 --- /dev/null +++ b/doc/08_Preferences.md @@ -0,0 +1,181 @@ +# Preferences + +At this point it is assumed you are at least familiar with the basics of +[Lua][]. You do not have to know a lot of the language to configure Textadept. + +[Lua]: http://www.lua.org + +## User Init + +Textadept executes a `~/.textadept/init.lua`, your user-init file, on startup. +If this file does not exist, Textadept creates it for you. You can use the file +to indicate what you want Textadept to do when the application starts. At first, +it simply loads a module that contains most of Textadept's functionality. +However, you are not restricted to just loading modules. You can run any Lua +code you desire. It is important to realize that Textadept will not load +anything you do not tell it to. If your `~/.textadept/init.lua` exists and is +empty, no modules are loaded (pretty much rendering Textadept useless). + +## Modules + +It is never recommended to modify the default modules that come with Textadept, +even if you just want to change an option in a generic module, modify the buffer +settings for a language-specific module, edit file types, or just add a small +bit of custom code. Those changes may be overwritten when you upgrade Textadept +to a newer version. Instead you have two options: load your own module instead +of the default one, or run your custom module code after the default module +loads. To load your own module, simply place it appropriately in +`~/.textadept/modules/`. To run your module code after a default generic module +loads, put your code in `~/.textadept/init.lua`. To run your module code after a +default language-specific module loads, create a `post_init.lua` Lua script in +the appropriate `~/.textadept/modules/` module folder. + +### Generic + +Many of Textadept's generic modules have settings you can change from +`~/.textadept/init.lua` after the module is loaded. These settings are viewed +from module's [LuaDoc][]. For example, to disable character autopairing and +stripping whitespace on save, your `~/.textadept/init.lua` might look like: + + _M.textadept = require 'textadept' + + _M.textadept.editing.AUTOPAIR = false + _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false + +Now suppose you wanted to load all of Textadept's default modules except for the +menu. Copy the `textadept` module's `init.lua` (located in the +`modules/textadept/` directory) to `~/.textadept/modules/textadept/` and change + + M.menu = require 'textadept.menu' + +to + + --M.menu = require 'textadept.menu' + +Now when Textadept looks for `modules/textadept/init.lua`, it will load yours +instead of its own, and load everything but the menu. If instead you wanted to +completely change the menu structure, you would first create a new `menu.lua` +and then put it in `~/.textadept/modules/textadept/`. Textadept will now load +your `menu.lua` instead of its own. + +[LuaDoc]: api/index.html + +### Language-Specific + +Similar to generic modules, copying the default Lua language-specific module +(`modules/lua`) to `~/.textadept/modules/` causes Textadept to load that module +for editing Lua code instead of the default one. If you make custom changes to +these kinds of copies of language-specific modules, you will likely want to +update them with each new Textadept release. Instead of potentially wasting time +merging your changes, you can run custom code independent of a module in the +module's `post_init.lua` file. For example, instead of copying the `lua` module +and changing its `set_buffer_properties()` function to use tabs, you can do this +from `~/.textadept/modules/lua/post_init.lua`: + + function _M.lua.set_buffer_properties() + buffer.use_tabs = true + end + +Similarly, you can use `post_init.lua` to change the module's +[compile and run][] commands, load more [Adeptsense tags][], and add additional +[key bindings](#Key.Bindings) and [snippets](#Snippets) (instead of in +`~/.textadept/init.lua`). For example: + + _M.textadept.run.run_command.lua = 'lua5.2' + _M.lua.sense:load_ctags('/path/to/my/projects/tags') + keys.lua['c\n'] = function() + buffer:line_end() buffer:add_text('end') buffer:new_line() + end + snippets.lua['ver'] = '%<_VERSION>' + +[compile and run]: 07_Modules.html#Compile.and.Run +[Adeptsense tags]: api/_M.textadept.adeptsense.html#load_ctags + +### Loading Modules + +Suppose you created or downloaded a generic module called `foo` that you wanted +to load along with the default modules Your `~/.textadept/init.lua` would +contain the following: + + _M.textadept = require 'textadept' + _M.foo = require 'foo' + +### Key Bindings + +For simple changes to key bindings, `~/.textadept/init.lua` is a good place to +put them. For example, maybe you want `Ctrl+Shift+C` to create a new buffer +instead of `Ctrl+N`: + + keys.cC = new_buffer + keys.cn = nil + +If you plan on redefining most key bindings, you would probably want to copy or +create a new `keys.lua` and then put it in `~/.textadept/modules/textadept/`. +You can learn more about key bindings in the [key bindings LuaDoc][]. + +[key bindings LuaDoc]: api/keys.html + +### Snippets + +You can add global snippets in `~/.textadept/init.lua`, such as: + + snippets['file'] = '%<buffer.filename>' + snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>" + +So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX | `Tab` in +ncurses) will insert the snippet, regardless of the current programming +language. You can learn about snippet syntax in the [snippets LuaDoc][]. + +[snippets LuaDoc]: api/_M.textadept.snippets.html + +## Locale + +Textadept attempts to auto-detect your locale settings using the `LANG` +environment variable. If it is unsuccessful, the English locale is used by +default. To set the locale manually, copy the desired locale file from the +`core/locales/` folder to `~/.textadept/locale.conf`. If your language is not +yet supported by Textadept, please translate the English messages in +`core/locale.conf` to your language and send the modified `locale.conf` file to +[me][]. I will include it in a future release. + +[me]: README.html#Contact + +## File Types + +Textadept recognizes a wide range of programming language files by any of the +following: + +* File extension. +* Keywords in the file's shebang (`#!/path/to/exe`) line. +* A pattern that matches the text of the file's first line. + +Built-in file types are located in `modules/textadept/mime_types.conf`. You +can override or add to them in your `~/.textadept/mime_types.conf`: + + % Recognize .luadoc files as Lua code. + luadoc lua + + % Change .html files to be recognized as XML files instead of HTML ones. + html xml + +### Detect by Extension + + file_ext lexer + +Note: `file_ext` should not start with a `.` (period). + +### Detect by Shebang + + #shebang_word lexer + +Examples of `shebang_word`s are `lua`, `ruby`, `python`. + +### Detect by Pattern + + /pattern lexer + +[Lua pattern syntax][] is used. Only the last space, the one separating the +pattern from the lexer, is significant. No spaces in the pattern need to be +escaped. + +[Lua pattern syntax]: 14_Appendix.html#Lua.Patterns diff --git a/doc/08_Themes.md b/doc/08_Themes.md deleted file mode 100644 index 5a171c82..00000000 --- a/doc/08_Themes.md +++ /dev/null @@ -1,91 +0,0 @@ -# Themes - -Textadept's look and feel can be customized with themes. The themes that come -with Textadept are `light`, `dark`, and `term`. By default the `light` theme is -used for the GUI version and `term` for the ncurses version. To change the -theme, create a `~/.textadept/theme` and/or `~/.textadept/theme_term` whose -first lines of text are the names of the themes you would like to use. - - - - - - - -Themes apply to all buffers. You cannot assign a theme to a particular file or -filetype. You can change things like tab and indent settings per filetype -however by creating a [language-specific module]. - -[language-specific module]: 7_Modules.html#Buffer.Properties - -## Creating or Modifying Themes - -Each theme is a single folder on the filesystem composed of three files: -`lexer.lua`, `buffer.lua`, and `view.lua`. It is recommended to put themes in -your `~/.textadept/themes/` directory so they will not be overwritten when you -update Textadept. Themes in that directory override any themes in Textadept's -`themes/` directory. This means that if you have your own `light` theme, it will -be loaded instead of the one that comes with Textadept. - -To use a theme not located in `~/.textadept/themes/` or Textadept's `themes/` -directory, you need to specify an absolute path to the theme's folder in your -`~/.textadept/theme` file. - -### Lexer - -Textadept uses lexers to assign names to buffer elements like comments, strings, -and keywords. These elements are assigned styles composed of font and color -information in the theme's `lexer.lua`. See the `Styling Tokens` section of the -[lexer][] page for more information on how to create styles and colors. - -[lexer]: api/lexer.html - -### Buffer - -`buffer.lua` contains buffer-specific properties like indentation size and -whether or not to use tabs. For example, to set the default tab size to 4 and -use tabs: - - buffer.tab_width = 4 - buffer.use_tabs = true - buffer.indent = 4 - -See the [LuaDoc][] for documentation on the properties. - -[LuaDoc]: api/buffer.html - -### View - -`view.lua` contains view-specific properties like caret and selection colors. -See the [LuaDoc][] for documentation on the properties. - -[LuaDoc]: api/buffer.html - -## Testing Themes - -You can reload or switch between themes on the fly using `Ctrl+Shift+T` (`⌘⇧T` -on Mac OSX | none in ncurses), but be aware that the Scintilla views do not -reset themselves, so any options set explicitly in the previous theme's -`view.lua` file that are not set explicitly in the new theme will carry over. -The switch feature is intended primarily for theme exploration and/or -development and can be slow when many buffers or views are open. - -Any errors that occur in the theme are printed to `io.stderr`. - -## Theming the GUI - -There is no way to theme GUI controls like text fields and buttons from within -Textadept. Instead, use [GTK Resource files][]. The `GtkWindow` name is -`textadept`. For example, styling all text fields with a -`"textadept-entry-style"` would be done like this: - - widget "textadept*GtkEntry*" style "textadept-entry-style" - -[GTK Resource files]: http://library.gnome.org/devel/gtk/stable/gtk-Resource-Files.html - -## Getting Themes - -For now, user-created themes are obtained from the [wiki][]. The classic `dark`, -`light`, and `scite` themes prior to version 4.3 have been moved there. - -[wiki]: http://foicica.com/wiki/textadept diff --git a/doc/09_Preferences.md b/doc/09_Preferences.md deleted file mode 100644 index 64f63dbd..00000000 --- a/doc/09_Preferences.md +++ /dev/null @@ -1,143 +0,0 @@ -# Preferences - -At this point it is assumed you are at least familiar with the basics of -[Lua][]. You do not have to know a lot of the language to configure Textadept. - -[Lua]: http://www.lua.org - -## User Init - -Textadept loads modules from your `~/.textadept/init.lua` on startup. If this -file does not exist, Textadept creates it with a list of default modules to -load. You can then use the file to indicate what else you want Textadept to -load. For example if you created a generic module called `foo` that you wanted -to load alongside the default modules, your `~/.textadept/init.lua` would -contain - - require 'textadept' - _M.foo = require 'foo' - -Please note that the `textadept` module populates the `_M.textadept` table -itself because of internal dependencies. Normally, modules do not do this, hence -why `_M.foo = require 'foo'` is used. - -If instead you wanted to load all of Textadept's default modules except for the -menu, copy the `textadept` module's `init.lua` (located in the -`modules/textadept/` directory) to `~/.textadept/modules/textadept/` and change - - M.menu = require 'textadept.menu' - -to - - --M.menu = require 'textadept.menu' - -Of course if you prefer, you can put the relevant code directly in -`~/.textadept/init.lua` instead. - -It is important to realize that Textadept will not load anything you do not tell -it to. If your `~/.textadept/init.lua` exists and is empty, no modules are -loaded (pretty much rendering Textadept useless). - -### Module Settings - -Many of Textadept's modules have settings you can change from your -`~/.textadept/init.lua`. These settings are viewed from module's -[LuaDoc][]. For example, to disable character autopairing and -whitespace stripping on save, your `~/.textadept/init.lua` might look like: - - require 'textadept' - - _M.textadept.editing.AUTOPAIR = false - _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false - -[LuaDoc]: api/index.html - -### Other - -Your `~/.textadept/init.lua` is not restricted to just loading modules or -setting preferences. It is just Lua code that is run when Textadept loads. For -more information, see the [scripting][] page. - -[scripting]: 11_Scripting.html - -#### Snippets - -You can add global snippets to `snippets` such as: - - snippets['file'] = '%<buffer.filename>' - snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>" - -So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX | `Tab` in -ncurses) will insert the snippet. - -#### Key Commands - -It is not recommended to edit Textadept's `modules/textadept/keys.lua` for -changing the key bindings since your changes could be overwritten when updating -Textadept. Instead, modify `keys` from within your `~/.textadept/init.lua` or -from a file loaded by `~/.textadept/init.lua`. For example maybe you want -`Ctrl+Shift+C` to create a new buffer instead of `Ctrl+N`: - - keys.cC = new_buffer - keys.cn = nil - -## Locale - -Most messages displayed by Textadept are localized. `core/locale.conf` contains -these messages. By default, Textadept is localized in English. To use a -different language, put a translated version of `core/locale.conf` in your -`~/.textadept/` folder. Translations are located in `core/locales/`. - -Feel free to translate Textadept and send your modified `locale.conf` files -to me. I will include them in future releases. - -## Mime Types - -Textadept recognizes a wide range of programming language files by any of the -following: - -* File extension. -* Keywords in the file's shebang (`#!/path/to/exe`) line. -* A pattern that matches the text of the file's first line. - -Built-in mime-types are located in `modules/textadept/mime_types.conf`. You -can override or add to them in your `~/.textadept/mime_types.conf`: - - % Recognize .luadoc files as Lua code. - luadoc lua - - % Change .html files to be recognized as XML files instead of HTML ones. - html xml - -It is not recommended to edit Textadept's `modules/textadept/mime_types.conf` -because your changes may be overwritten when updating Textadept. - -### Detect by File Extension - - file_ext lexer - -Note: `file_ext` should not start with a `.` (period). - -### Detect by Shebang Keywords - - #shebang_word lexer - -Examples of `shebang_word`'s are `lua`, `ruby`, `python`. - -### Detect by Pattern - - /pattern lexer - -Only the last space, the one separating the pattern from the lexer, is -significant. No spaces in the pattern need to be escaped. - -## More Language Preferences - -Textadept does not come with language-specific modules for all languages so you -can add run commands, compile commands, and block quotes manually: - -* [Run/Compile commands][] -* [Block Quotes][] - -[Run/Compile commands]: http://foicica.com/wiki/RunSupplemental -[Block Quotes]: http://foicica.com/wiki/CommentSupplemental diff --git a/doc/09_Themes.md b/doc/09_Themes.md new file mode 100644 index 00000000..37f5379e --- /dev/null +++ b/doc/09_Themes.md @@ -0,0 +1,95 @@ +# Themes + +Textadept's look and feel is customized with themes. The themes that come with +Textadept are `light`, `dark`, and `term`. By default the `light` theme is used +for the GUI version and `term` for the ncurses version. + +<span style="display: block; clear: right;"></span> + + + + + + + +## Structure + +Each theme is a single folder composed of three files: `lexer.lua`, +`buffer.lua`, and `view.lua`. It is recommended to put custom or downloaded +themes in your `~/.textadept/themes/` directory so they will not be overwritten +when you update Textadept. Also, themes in that directory override any themes in +Textadept's `themes/` directory. This means that if you have your own `light` +theme, it will be loaded instead of the one that comes with Textadept. + +### Lexer + +`lexer.lua` contains definitions for how to "style" syntactic elements like +comments, strings, and keywords in programming languages. [Styles][] are +composed of fonts and colors and apply universally to all programming language +elements, resulting in a single, unified theme. + +[Styles]: api/lexer.html#Styling.Tokens + +### Buffer + +`buffer.lua` contains [buffer-specific properties][] like the indentation +character and indentation size. For example, to use tabs instead of spaces and +have a tab size of 4 spaces by default: + + buffer.tab_width = 4 + buffer.use_tabs = true + +You can use [Adeptsense][] to view a property's documentation or read the +[buffer LuaDoc][]. + +[buffer-specific properties]: 04_WorkingWithFiles.html#Settings +[Adeptsense]: 06_AdeptEditing.html#Adeptsense +[buffer LuaDoc]: api/buffer.html + +### View + +`view.lua` contains view-specific properties which apply to all buffers. These +properties are numerous and control many aspects of how buffers are displayed, +from caret and selection colors to margin configurations to marker definitions. +View properties also control editor behaviors like scrolling and autocompletion. +Existing themes have various properties commented out. Uncomment a property to +turn it on or change its value. You can use [Adeptsense][] to view a property's +documentation or read the [LuaDoc][]. + +[Adeptsense]: 06_AdeptEditing.html#Adeptsense +[LuaDoc]: api/buffer.html + +## Switch Themes + +You can switch between or reload themes using `Ctrl+Shift+T` (`⌘⇧T` on Mac OSX | +none in ncurses). However, be aware that the views do not reset themselves. Any +properties set explicitly in the previous theme's `view.lua` file that are not +set explicitly in the new theme will carry over. Restarting Textadept will fix +this. Also, be aware that themes apply to all buffers. You cannot assign a theme +to a particular file or file type. (You can change things like tab and indent +settings per filetype, however, by creating a [language-specific module][].) +Behind the scenes, Textadept is setting the theme name in a `~/.textadept/theme` +or `~/.textadept/theme_term` file. To use a theme not listed, specify an +absolute path to the theme's folder in your `~/.textadept/theme` or +`~/.textadept/theme_term` file. When testing themes, any errors that occur are +printed to standard error. + +[language-specific module]: 07_Modules.html#Buffer.Properties + +## GUI Theme + +There is no way to theme GUI controls like text fields and buttons from within +Textadept. Instead, use [GTK+ Resource files][]. The `GtkWindow` name is +`textadept`. For example, styling all text fields with a +`"textadept-entry-style"` would be done like this: + + widget "textadept*GtkEntry*" style "textadept-entry-style" + +[GTK+ Resource files]: http://library.gnome.org/devel/gtk/stable/gtk-Resource-Files.html + +## Getting Themes + +For now, user-created themes are obtained from the [wiki][]. The classic `dark`, +`light`, and `scite` themes prior to version 4.3 have been moved there. + +[wiki]: http://foicica.com/wiki/textadept diff --git a/doc/10_Advanced.md b/doc/10_Advanced.md index adae9ad7..1009733e 100644 --- a/doc/10_Advanced.md +++ b/doc/10_Advanced.md @@ -4,17 +4,20 @@ Access to the Lua state is available through the command entry. Press `Ctrl+E` (`⌘E` on Mac OSX | `M-C` in ncurses) to access it. It is useful for debugging, -inspecting, and entering buffer or view commands. If you try to cause +inspecting, and entering `buffer` or `view` commands. If you try to cause instability in Textadept's Lua state, you might very well succeed so be careful. -For more information, see the [scripting][] page. - -Abbreviated commands for the `buffer`, `view` and `gui` are available. So -`buffer:append_text('foo')` can be shortened to `append_text('foo')`. `print()` -redirects to [`gui.print()`][]. Use `_G.print()` for Lua's `print()`. +For available commands, see the [Lua API][]. Abbreviated commands for +[`buffer`][], [`view`][] and [`gui`][] are available: the command +`buffer:append_text('foo')` can be shortened to `append_text('foo')`. As a +result, use `_G.print()` for Lua's `print()` since [`gui.print()`][] is +shortened to `print()`.  -[scripting]: 11_Scripting.html +[Lua API]: api/index.html +[`buffer`]: api/buffer.html +[`view`]: api/view.html +[`gui`]: api/gui.html [`gui.print()`]: api/gui.html#print ### Tab Completion @@ -38,12 +41,15 @@ the implementation. If you did not disable the menu in your [preferences][], then pressing `Ctrl+Shift+E` (`⌘⇧E` on Mac OSX | `M-S-C` in ncurses) brings up the command -selection dialog. Typing part of any command filters the list with spaces being +selection dialog. Typing part of any command filters the list, with spaces being wildcards. This is an easy way to run commands without navigating the menus, -using the mouse, or remembering key commands. It is also useful for looking up -particular key commands quickly. +using the mouse, or remembering key bindings. It is also useful for looking up +particular key bindings quickly. Note: the key bindings in the dialog do not +look like those in the menu. This different notation is how bindings are +represented internally. You can learn more about this in the [keys LuaDoc]. -[preferences]: 9_Preferences.html#User.Init +[preferences]: 08_Preferences.html#User.Init +[keys LuaDoc]: api/keys.html ## Shell Commands and Filtering Text @@ -67,19 +73,3 @@ The standard input (stdin) for shell commands is determined as follows: * If no text is selected, the entire buffer is used. The input text is replaced with the standard output (stdout) of the command. - -## File Encoding - -Textadept represents all characters and strings internally as UTF-8. You will -not notice any difference for working with files containing ASCII text since -UTF-8 is compatible with it. Textadept can also detect ISO-8859-1 and MacRoman, -the primary encodings used on Windows and Mac OSX respectively. Files with more -exotic encodings may not be detected properly, if at all. You can change the -list of encodings Textadept tries to detect via [`io.try_encodings`][]. - -It is recommended to use UTF-8 encoded files because UTF-8 is very well -supported by other text editors and operating systems. You can change the file's -encoding via the `Buffer -> Encoding` menu. Textadept saves new files as UTF-8 -by default. - -[`io.try_encodings`]: api/io.html#try_encodings diff --git a/doc/11_Scripting.md b/doc/11_Scripting.md index a214fe0f..3c546f1a 100644 --- a/doc/11_Scripting.md +++ b/doc/11_Scripting.md @@ -1,41 +1,37 @@ # Scripting -Textadept has superb support for editing Lua code. Syntax autocomplete and -LuaDoc is available for many Textadept objects as well as Lua's standard -libraries. See the [`lua` module documentation][] for more information. +Textadept is entirely scriptable with Lua. In fact, the editor is mostly written +in Lua. As a result, Textadept has superb support for editing Lua code. Syntax +autocomplete and API documentation is available for many Textadept objects as +well as Lua's standard libraries. The [`lua` module][] also has more tools for +working with Lua code.   -[`lua` module documentation]: api/_M.lua.html +[`lua` module]: api/_M.lua.html ## LuaDoc and Examples -Textadept's API is heavily documented. The [API docs][] are the ultimate +Textadept's API is heavily documented. The [API documentation][] is the ultimate resource on scripting Textadept. There are of course abundant scripting examples -since Textadept is mostly written in Lua. +since the editor is written primarily in Lua. -[API docs]: api/index.html +[API documentation]: api/index.html ### Generating LuaDoc You can generate API documentation for your own modules using the -`doc/markdowndoc.lua` [LuaDoc][] module: +`doc/markdowndoc.lua` [LuaDoc][] module (you must have [Discount][] installed): - luadoc -d . --doclet _HOME/doc/markdowndoc [module(s)] - -or - - luadoc -d . -t template_dir --doclet _HOME/doc/markdowndoc [module(s)] + luadoc -d . [-t template_dir] --doclet _HOME/doc/markdowndoc [module(s)] where `_HOME` is where Textadept is installed and `template_dir` is an optional template directory that contains two Markdown files: `.header.md` and `.footer.md`. (See `doc/.header.md` and `doc/.footer.md` for examples.) An -`api/` directory containing the API documentation is created in the current -directory. - -You must have [Discount][] installed. +`api/` directory containing the API documentation HTML files is created in the +current directory. [LuaDoc]: http://keplerproject.github.com/luadoc/ [Discount]: http://www.pell.portland.or.us/~orc/Code/discount/ @@ -82,19 +78,19 @@ an organized folder structure. Textadept's core Lua modules are contained in `core/`. These are absolutely necessary in order for the application to run. They are responsible for -Textadept's Lua to C interface, event structure, file input/output, and +Textadept's Lua to C interface, event structure, file interactions, and localization. ### Lexers -Lexer Lua modules are responsible for the syntax highlighting of source code. -They are located in `lexers/`. +Lexer modules are responsible for the syntax highlighting of source code. They +are located in `lexers/`. ### Modules -Editor Lua modules are contained in `modules/`. These provide advanced text -editing capabilities and can be available for all programming languages or -targeted at specific ones. +Editing modules are contained in `modules/`. These provide advanced text editing +capabilities and can be available for all programming languages or targeted at +specific ones. ### Themes @@ -103,10 +99,11 @@ Built-in themes to customize the look and behavior of Textadept are located in ### User -User Lua modules are contained in the `~/.textadept/` folder. This folder may -contain `lexers/`, `modules/`, and `themes/` subdirectories. +User preferences, Lua modules, themes, and user-data are contained in the +`~/.textadept/` folder. This folder may contain `lexers/`, `modules/`, and +`themes/` sub-directories. -### GTK +### GTK+ -The `etc/`, `lib/`, and `share/` directories are used by GTK and only appear in +The `etc/`, `lib/`, and `share/` directories are used by GTK+ and only appear in the Win32 and Mac OSX packages. diff --git a/doc/12_Compiling.md b/doc/12_Compiling.md index e16aba01..c6481176 100644 --- a/doc/12_Compiling.md +++ b/doc/12_Compiling.md @@ -7,21 +7,23 @@ as running it. ### Linux and BSD -Linux systems need the GTK+ development libraries. Your package manager should -allow you to install them. For Debian-based distributions like Ubuntu, the -package is typically called `libgtk2.0-dev`. Otherwise, compile and install GTK -from the [GTK+ website][]. Additionally you will need the [GNU C compiler][] -(`gcc`) and [GNU Make][] (`make`). Both should be available for your Linux -distribution through its package manager. For example, Ubuntu includes these -tools in the `build-essential` package. +First, Linux and BSD systems will need the [GNU C compiler][] (`gcc`) and +[GNU Make][] (`make`). Both should be available for your distribution through a +package manager. For example, Ubuntu includes these tools in the +`build-essential` package. + +Next, the GTK+ development libraries are necessary for compiling the GUI version +of Textadept. Your package manager should allow you to install them. For +Debian-based Linux distributions like Ubuntu, the package is typically called +`libgtk2.0-dev`. Otherwise, compile and install GTK+ from the [GTK+ website][]. If you would like to compile the terminal version of Textadept, you will need the ncurses development library. Similarly, it should be available from your -package manager. For Debian-based distributions like Ubuntu, the package is -typically called `libncurses5-dev`. Otherwise, compile and install ncurses from -the [ncurses website][]. Note: you should have a development version of ncurses -compiled with "wide" (multibyte) character support installed. (Therefore, Debian -users will also need `libncursesw5-dev`.) +package manager. For Debian-based Linux distributions like Ubuntu, the package +is typically called `libncurses5-dev`. Otherwise, compile and install ncurses +from the [ncurses website][]. Note: you need to have a development version of +ncurses compiled with "wide" (multibyte) character support installed. +(Therefore, Debian users will _also_ need `libncursesw5-dev`.) In addition, BSD users will need to have [libiconv][] installed. @@ -34,31 +36,31 @@ In addition, BSD users will need to have [libiconv][] installed. ### Windows Compiling Textadept on Windows is no longer supported. If you wish to do so -however, you need a C compiler that supports the C99 standard (Microsoft's does -not), the [GTK+ for Windows bundle][] (2.24 is recommended), and [libiconv][] +however, you need a C compiler that supports the C99 standard, the +[GTK+ for Windows bundle][] (2.24 is recommended), and [libiconv for Windows][] (the "Developer files" zip). The preferred way to compile for Windows is cross-compiling from Linux. To do -so, in addition to the GTK bundle mentioned above, you need [MinGW][] with the +so, in addition to the GTK+ bundle mentioned above, you need [MinGW][] with the Windows header files. They should be available from your package manager. [GTK+ for Windows bundle]: http://www.gtk.org/download/win32.html -[libiconv]: http://gnuwin32.sourceforge.net/packages/libiconv.htm +[libiconv for Windows]: http://gnuwin32.sourceforge.net/packages/libiconv.htm [MinGW]: http://mingw.org ### Mac OSX Compiling Textadept on Mac OSX is no longer supported. The preferred way is cross-compiling from Linux. To do so, you will need my [GTK+ for OSX bundle][] -and the [Apple Crosscompiler][] binaries. +and the [Apple Cross-compiler][] binaries. [GTK+ for OSX bundle]: download/gtkosx-2.24.9.zip -[Apple Crosscompiler]: https://launchpad.net/~flosoft/+archive/cross-apple +[Apple Cross-compiler]: https://launchpad.net/~flosoft/+archive/cross-apple ## Compiling -Make sure you downloaded the `textadept_x.x.src.zip` (regardless of what -platform you are on) and not a platform-specific binary package. +Make sure you downloaded the `textadept_x.x.src.zip`, regardless of what +platform you are on, and not a platform-specific binary package. ### Linux and BSD @@ -68,10 +70,13 @@ Make a symlink from them to `/usr/bin/` or elsewhere in your `PATH`. Similarly, `make ncurses` builds `textadept-ncurses` and `textadeptjit-ncurses`. -Note: you may have to run `make CFLAGS="-I/usr/local/include" -CXXFLAGS="-I/usr/local/include -L/usr/local/lib"` if the prefix where any -dependencies are installed is `/usr/local` and your compiler flags do not -include them by default. +Note: you may have to run + + make CFLAGS="-I/usr/local/include" \ + CXXFLAGS="-I/usr/local/include -L/usr/local/lib" + +if the prefix where any dependencies are installed is `/usr/local` and your +compiler flags do not include them by default. #### Installing @@ -79,8 +84,8 @@ Textadept is self-contained, meaning it does not need to be installed and can be run from wherever it is located. However, if you want to install Textadept like a normal Linux application, run the usual `make` and then `make install` or `sudo make install` depending on your privilages. The default prefix is -`/usr/local` but you can change this by setting `DESTDIR` (e.g. `make install -DESTDIR=/prefix/to/install/to`). +`/usr/local` but you can change this by setting `DESTDIR` (e.g. +`make install DESTDIR=/prefix/to/install/to`). ### Cross Compiling for Windows @@ -109,12 +114,12 @@ Similarly, `make osx-ncurses` builds `../textadept-ncurses.osx` and #### Compiling on OSX (Legacy) -[XCode][] is needed for Mac OSX as well as [jhbuild][] (for GTK). After building -`meta-gtk-osx-bootstrap` and `meta-gtk-osx-core`, you need to build +[XCode][] is needed for Mac OSX as well as [jhbuild][] (for GTK+). After +building `meta-gtk-osx-bootstrap` and `meta-gtk-osx-core`, you need to build `meta-gtk-osx-themes`. Note that the entire compiling process can easily take 30 minutes or more and ultimately consume nearly 1GB of disk space. -After using `jhbuild`, GTK is in `~/gtk` so make a symlink from `~/gtk/inst` to +After using `jhbuild`, GTK+ is in `~/gtk` so make a symlink from `~/gtk/inst` to `src/gtkosx` in Textadept. Then open `src/Makefile` and uncomment the `Darwin` block. Finally, run `make osx` to build `../textadept.osx` and `../textadeptjit.osx`. diff --git a/doc/13_Help.md b/doc/13_Help.md index afddcde4..ee245fcc 100644 --- a/doc/13_Help.md +++ b/doc/13_Help.md @@ -5,6 +5,8 @@ Passing `-h` or `--help` to Textadept shows a list of available command line parameters. +This is unavailable in ncurses. + ## Online Help Textadept has a [mailing list][] and a [wiki][]. You can also join us on IRC via diff --git a/doc/14_Appendix.md b/doc/14_Appendix.md index 67f318d7..5057445c 100644 --- a/doc/14_Appendix.md +++ b/doc/14_Appendix.md @@ -1,184 +1,5 @@ # Appendix -## 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<br/>Alt+Backspace|⌘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 -Ctrl+V<br/>Shift+Ins |⌘V |^V |Paste -Ctrl+D |⌘D |None |Duplicate line -Del |⌦<br/>^D |Del<br/>^D |Delete -Alt+Del |^⌦ |M-Del<br/>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<br/>M-S-F|Find -Ctrl+G<br/>F3 |⌘G |M-G |Find next -Ctrl+Shift+G<br/>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<br/>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<br/>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<br/>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<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+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 -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 |None |Toggle show indent guides -Ctrl+Alt+Shift+S |^⇧S |None |Toggle view whitespace -Ctrl+Alt+Shift+V |^⇧V |None |Toggle virtual space -Ctrl+= |⌘= |M-= |Zoom in -Ctrl+- |⌘- |M-- |Zoom out -Ctrl+0 |⌘0 |M-0 |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 |⇣<br/>^N |^N<br/>Down |Line down -Shift+Down |⇧⇣<br/>^⇧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 |⇡<br/>^P |^P<br/>Up |Line up -Shift+Up |⇧⇡<br/>^⇧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 |⇠<br/>^B |^B<br/>Left |Char left -Shift+Left |⇧⇠<br/>^⇧B |S-Left |Char left extend selection -Ctrl+Left |^⇠<br/>^⌘B |^Left |Word left -Ctrl+Shift+Left |^⇧⇠<br/>^⌘⇧B|S-^Left |Word left extend selection -Alt+Shift+Left |⌥⇧⇠ |M-S-Left |Char left extend rect. selection -Right |⇢<br/>^F |^F<br/>Right|Char right -Shift+Right |⇧⇢<br/>^⇧F |S-Right |Char right extend selection -Ctrl+Right |^⇢<br/>^⌘F |^Right |Word right -Ctrl+Shift+Right |^⇧⇢<br/>^⌘⇧F|S-^Right |Word right extend selection -Alt+Shift+Right |⌥⇧⇢ |M-S-Right |Char right extend rect. selection -Home |⌘⇠<br/>^A |^A<br/>Home |Line start -Shift+Home |⌘⇧⇠<br/>^⇧A |M-S-A |Line start extend selection -Ctrl+Home |⌘⇡<br/>⌘↖ |M-^A |Document start -Ctrl+Shift+Home |⌘⇧⇡<br/>⌘⇧↖ |None |Document start extend selection -Alt+Shift+Home |⌥⇧↖ |None |Line start extend rect. selection -End |⌘⇢<br/>^E |^E<br/>End |Line end -Shift+End |⌘⇧⇢<br/>^⇧E |M-S-E |Line end extend selection -Ctrl+End |⌘⇣<br/>⌘↘ |M-^E |Document end -Ctrl+Shift+End |⌘⇧⇣<br/>⌘⇧↘ |None |Document end extend selection -Alt+Shift+End |⌥⇧↘ |None |Line end extend rect. selection -PageUp |⇞ |PageUp |Page up -Shift+PageUp |⇧⇞ |M-S-U |Page up extend selection -Alt+Shift+PageUp |⌥⇧⇞ |None |Page up extend rect. selection -PageDown |⇟ |PageDown |Page down -Shift+PageDown |⇧⇟ |M-S-D |Page down extend selection -Alt+Shift+PageDown |⌥⇧⇟ |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 -Backspace |⌫<br/>⇧⌫ |^H<br/>Bksp |Delete back -Ctrl+Backspace |⌘⌫ |None |Delete word left -Ctrl+Shift+Backspace|⌘⇧⌫ |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. - ## Lua Patterns The following is taken from the [Lua 5.2 Reference Manual][]. @@ -282,7 +103,7 @@ As a special case, the empty capture `()` captures the current string position Textadept 5.5 beta introduced an ncurses version that can run in a terminal emulator. However, since ncurses is quite low-level in terms of graphics -capability compared to GTK, the ncurses version of Textadept lacks some +capability compared to GTK+, the ncurses version of Textadept lacks some features in its editing component Scintilla: * Any settings with alpha values are not supported. @@ -694,9 +515,9 @@ Notice the `l.` prefix before most identifiers. #### Key and Menu Changes -Textadept 4 allow key shortcuts to appear in menus, but only simple ones, not -keychains. Therefore, Textadept's key commands have changed radically, as has -the menu structure and menu mnemonics. In order for key shortcuts to appear in +Textadept 4 allow key bindings to appear in menus, but only simple ones, not +keychains. Therefore, Textadept's key bindings have changed radically, as has +the menu structure and menu mnemonics. In order for key bindings to appear in menus, `_m.textadept.menu` needs to know which commands are assigned to which keys. Therefore, the menu module needs to be `require`d *after* `_m.textadept.keys`. If your `~/.textadept/init.lua` is calling @@ -704,7 +525,7 @@ keys. Therefore, the menu module needs to be `require`d *after* individual modules from `_m.textadept`, ensure `_m.textadept.menu` is loaded after `_m.textadept.keys`. -On Mac OSX, key command definition has changed. `m` is now ⌘ (command) and `a` +On Mac OSX, key binding definition has changed. `m` is now ⌘ (command) and `a` is now ⌥ (alt/option). `c` remains ^ (control). Previously `a` was ⌘ and ⌥ was undefined. Please note, however, that not all ⌥ combinations by themselves will work since that key is typically used to compose locale-dependent characters. @@ -738,11 +559,11 @@ in your `~/.textadept/init.lua` will load all the modules you would expect. Please see the [preferences][] page for instructions on how to load specific modules. -[preferences]: 9_Preferences.html#User.Init +[preferences]: 08_Preferences.html#User.Init ##### Autoloading -Key commands in `~/.textadept/key_commands.lua` and snippets in +Key bindings in `~/.textadept/key_commands.lua` and snippets in `~/.textadept/snippets.lua` are no longer auto-loaded. Instead, modify [`keys`][] and/or [`snippets`][] from within your `~/.textadept/init.lua` or a file loaded by `~/.textadept/init.lua`. diff --git a/doc/images/folding.png b/doc/images/folding.png Binary files differnew file mode 100644 index 00000000..7eb6d87d --- /dev/null +++ b/doc/images/folding.png diff --git a/doc/markdowndoc.lua b/doc/markdowndoc.lua index 85069370..e44e8c37 100644 --- a/doc/markdowndoc.lua +++ b/doc/markdowndoc.lua @@ -170,6 +170,12 @@ function M.start(doc) -- Write index.html. template.nav = nav + local api_index = M.options.output_dir..'/.api_index.md' + if (require 'lfs').attributes(api_index) then + local p = io_popen('markdown -f toc -T "'..api_index..'"') + template.toc, template.main = p:read('*all'):match('^(.-\n</ul>\n)(.+)$') + p:close() + end f = io_open(M.options.output_dir..'/api/index.html', 'wb') local html = HTML:gsub('%%%(([^)]+)%)', template) f:write(html) diff --git a/modules/cpp/init.lua b/modules/cpp/init.lua index a63ad0e8..7610e6bf 100644 --- a/modules/cpp/init.lua +++ b/modules/cpp/init.lua @@ -6,12 +6,10 @@ local M = {} --- -- The cpp module. -- It provides utilities for editing C/C++ code. --- User tags are loaded from `_USERHOME/modules/cpp/tags` and user apis are --- loaded from `_USERHOME/modules/cpp/api`. -- --- ## Key Commands +-- ## Key Bindings -- --- + `Ctrl+L, M` (`⌘L, M` on Mac OSX) +-- + `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 @@ -19,10 +17,12 @@ local M = {} -- + `->` -- When to the right of a known symbol, show an autocompletion list of fields -- and functions. --- + `Shift+Return` (`⇧↩`) --- Add ';' to line end and insert newline. +-- + `Shift+Enter` (`⇧↩` | `S-Enter`) +-- Add `;` to the end of the current line and insert a newline. -- @field sense -- The C/C++ [Adeptsense](_M.textadept.adeptsense.html). +-- It loads user tags from `_USERHOME/modules/cpp/tags` and user apidocs from +-- `_USERHOME/modules/cpp/api`. module('_M.cpp')]] local m_editing, m_run = _M.textadept.editing, _M.textadept.run @@ -50,9 +50,10 @@ end -- Adeptsense. M.sense = _M.textadept.adeptsense.new('cpp') +local as = _M.textadept.adeptsense M.sense.ctags_kinds = { - c = 'classes', d = 'functions', e = 'fields', f = 'functions', g = 'classes', - m = 'fields', s = 'classes', t = 'classes' + c = as.CLASS, d = as.FUNCTION, e = as.FIELD, f = as.FUNCTION, g = as.CLASS, + m = as.FIELD, s = as.CLASS, t = as.CLASS } M.sense:load_ctags(_HOME..'/modules/cpp/tags', true) M.sense.api_files = { _HOME..'/modules/cpp/api', _HOME..'/modules/cpp/lua_api' } @@ -73,7 +74,7 @@ end -- Commands. --- --- Container for C/C++-specific key commands. +-- Container for C/C++-specific key bindings. -- @class table -- @name _G.keys.cpp keys.cpp = { diff --git a/modules/lua/api b/modules/lua/api index 0f022373..bf61479e 100644 --- a/modules/lua/api +++ b/modules/lua/api @@ -1,18 +1,18 @@ ANNOTATION_BOXED _SCINTILLA.constants.ANNOTATION_BOXED\n2 ANNOTATION_HIDDEN _SCINTILLA.constants.ANNOTATION_HIDDEN\n0 ANNOTATION_STANDARD _SCINTILLA.constants.ANNOTATION_STANDARD\n1 -APPLEEVENT_ODOC events.APPLEEVENT_ODOC\nCalled when Mac OSX tells Textadept to open a document.\n * `uri`: The URI to open encoded in UTF-8. -AUTOINDENT _M.textadept.editing.AUTOINDENT (bool)\nMatch the indentation level of the previous line when pressing the Enter\nkey.\nThe default value is `true`. -AUTOPAIR _M.textadept.editing.AUTOPAIR (bool)\nOpening `(`, `[`, `[`, `"`, or `'` characters are automatically closed.\nThe default value is `true`. -AUTO_C_CHAR_DELETED events.AUTO_C_CHAR_DELETED\nCalled when the user deleted a character while the autocompletion list was\nactive. -AUTO_C_RELEASE events.AUTO_C_RELEASE\nCalled when the user has cancelled the autocompletion list. -AUTO_C_SELECTION events.AUTO_C_SELECTION\nCalled when the user has selected an item in an autocompletion list and\nbefore the selection is inserted.\nAutomatic insertion can be cancelled by calling\n`buffer:auto_c_cancel()` before returning from the event handler.\nArguments:\n * `text`: The text of the selection.\n * `position`: The start position of the word being completed. -BUFFER_AFTER_SWITCH events.BUFFER_AFTER_SWITCH\nCalled right after a buffer is switched to. -BUFFER_BEFORE_SWITCH events.BUFFER_BEFORE_SWITCH\nCalled right before another buffer is switched to. -BUFFER_DELETED events.BUFFER_DELETED\nCalled after a buffer was deleted. -BUFFER_NEW events.BUFFER_NEW\nCalled when a new buffer is created. +APPLEEVENT_ODOC events.APPLEEVENT_ODOC (string)\nCalled when Mac OSX tells Textadept to open a document.\nArguments:\n\n* `uri`: The URI to open encoded in UTF-8. +AUTOINDENT _M.textadept.editing.AUTOINDENT (bool)\nMatch the indentation level of the previous line when pressing the `Enter`\n(`↩` on Mac OSX | `Enter` in ncurses) key.\nThe default value is `true`. +AUTOPAIR _M.textadept.editing.AUTOPAIR (bool)\nOpening `(`, `[`, `{`, `"`, or `'` characters are automatically closed.\nThe default value is `true`.\nAuto-paired characters are defined in the `char_matches`\ntable. +AUTO_C_CHAR_DELETED events.AUTO_C_CHAR_DELETED (string)\nCalled when the user deleted a character while the autocompletion list was\nactive. +AUTO_C_RELEASE events.AUTO_C_RELEASE (string)\nCalled when the user has cancelled the autocompletion list. +AUTO_C_SELECTION events.AUTO_C_SELECTION (string)\nCalled when the user has selected an item in an autocompletion list and\nbefore the selection is inserted.\nAutomatic insertion can be cancelled by calling\n`buffer:auto_c_cancel()` before returning from the event handler.\nArguments:\n\n* `text`: The text of the selection.\n* `position`: The start position of the word being completed. +BUFFER_AFTER_SWITCH events.BUFFER_AFTER_SWITCH (string)\nCalled right after a buffer is switched to.\nThis is emitted by `view:goto_buffer()`. +BUFFER_BEFORE_SWITCH events.BUFFER_BEFORE_SWITCH (string)\nCalled right before another buffer is switched to.\nThis is emitted by `view:goto_buffer()`. +BUFFER_DELETED events.BUFFER_DELETED (string)\nCalled after a buffer was deleted.\nThis is emitted by `buffer:delete()`. +BUFFER_NEW events.BUFFER_NEW (string)\nCalled when a new buffer is created.\nThis is emitted on startup and by `new_buffer()`. C lpeg.C(patt)\nCreates a simple capture, which captures the substring of the subject that\nmatches patt. The captured value is a string. If patt has other captures,\ntheir values are returned after this one. -CALL_TIP_CLICK events.CALL_TIP_CLICK\nCalled when the user clicks on a calltip.\nArguments:\n * `position`: Set to 1 if the click is in an up arrow, 2 if in a down\n arrow, and 0 if elsewhere. +CALL_TIP_CLICK events.CALL_TIP_CLICK (string)\nCalled when the user clicks on a calltip.\nArguments:\n\n* `position`: Set to 1 if the click is in an up arrow, 2 if in a down\n arrow, and 0 if elsewhere. CARETSTYLE_BLOCK _SCINTILLA.constants.CARETSTYLE_BLOCK\n2 CARETSTYLE_INVISIBLE _SCINTILLA.constants.CARETSTYLE_INVISIBLE\n0 CARETSTYLE_LINE _SCINTILLA.constants.CARETSTYLE_LINE\n1 @@ -20,13 +20,14 @@ CARET_EVEN _SCINTILLA.constants.CARET_EVEN\n8 CARET_JUMPS _SCINTILLA.constants.CARET_JUMPS\n16 CARET_SLOP _SCINTILLA.constants.CARET_SLOP\n1 CARET_STRICT _SCINTILLA.constants.CARET_STRICT\n4 -CHAR_ADDED events.CHAR_ADDED\nCalled when an ordinary text character is added to the buffer.\nArguments:\n * `ch`: The text character byte. +CHAR_ADDED events.CHAR_ADDED (string)\nCalled when an ordinary text character is added to the buffer.\nArguments:\n\n* `ch`: The text character byte. +CLASS _M.textadept.adeptsense.CLASS (string)\nCtags kind for Adeptsense classes. CLASS lexer.CLASS\nToken type for class tokens. -CLEAR keys.CLEAR (string)\nThe string representing the key sequence that clears the current keychain.\nThe default value is `'esc'` (Escape). -COMMAND_ENTRY_COMMAND events.COMMAND_ENTRY_COMMAND\nCalled when a command is entered into the Command Entry.\nArguments:\n * `command`: The command text. -COMMAND_ENTRY_KEYPRESS events.COMMAND_ENTRY_KEYPRESS\nCalled when a key is pressed in the Command Entry.\nArguments:\n * `code`: The key code.\n * `shift`: The Shift key is held down.\n * `ctrl`: The Control/Command key is held down.\n * `alt`: The Alt/option key is held down.\n * `meta`: The Control key on Mac OSX is held down. +CLEAR keys.CLEAR (string)\nThe string representing the key sequence that clears the current key chain.\nIt cannot be part of a key chain.\nThe default value is `'esc'` for the `Esc` (`⎋` on Mac OSX | `Esc` in\nncurses) key. +COMMAND_ENTRY_COMMAND events.COMMAND_ENTRY_COMMAND (string)\nCalled when a command is entered into the Command Entry.\nArguments:\n\n* `command`: The command text. +COMMAND_ENTRY_KEYPRESS events.COMMAND_ENTRY_KEYPRESS (string)\nCalled when a key is pressed in the Command Entry.\nArguments:\n\n* `code`: The key code.\n* `shift`: The Shift key is held down.\n* `ctrl`: The Control/Command key is held down.\n* `alt`: The Alt/option key is held down.\n* `meta`: The Control key on Mac OSX is held down. COMMENT lexer.COMMENT\nToken type for comment tokens. -COMPILE_OUTPUT events.COMPILE_OUTPUT\nCalled after a compile command is executed.\nWhen connecting to this event (typically from a language-specific module),\nconnect with an index of `1` and return `true` if the event was handled and\nyou want to override the default handler that prints the output to a new\nview.\nArguments:\n * `lexer`: The lexer language.\n * `output`: The output from the command. +COMPILE_OUTPUT events.COMPILE_OUTPUT\nCalled after a compile command is executed.\nBy default, compiler output is printed to the message buffer. To override\nthis behavior, connect to the event with an index of `1` and return `true`.\nArguments:\n * `lexer`: The lexer language.\n * `output`: The output from the command. CONSTANT lexer.CONSTANT\nToken type for constant tokens. Carg lpeg.Carg(n)\nCreates an argument capture. This pattern matches the empty string and\nproduces the value given as the nth extra argument given in the call to\nlpeg.match. Cb lpeg.Cb(name)\nCreates a back capture. This pattern matches the empty string and produces\nthe values produced by the most recent group capture named name.\n\nMost recent means the last complete outermost group capture with the given\nname. A Complete capture means that the entire pattern corresponding to the\ncapture has matched. An Outermost capture means that the capture is not\ninside another complete capture. @@ -38,35 +39,37 @@ Cp lpeg.Cp()\nCreates a position capture. It matches the empty string and captur Cs lpeg.Cs(patt)\nCreates a substitution capture, which captures the substring of the subject\nthat matches patt, with substitutions. For any capture inside patt with a\nvalue, the substring that matched the capture is replaced by the capture\nvalue (which should be a string). The final captured value is the string\nresulting from all replacements. Ct lpeg.Ct(patt)\nCreates a table capture. This capture creates a table and puts all values\nfrom all anonymous captures made by patt inside this table in successive\ninteger keys, starting at 1. Moreover, for each named capture group created\nby patt, the first value of the group is put into the table with the group\nname as its key. The captured value is only the table. DEFAULT lexer.DEFAULT\nToken type for default tokens. -DEFAULT_DEPTH _M.textadept.snapopen.DEFAULT_DEPTH (number)\nMaximum directory depth to search. The default value is `99`. -DEFAULT_SESSION _M.textadept.session.DEFAULT_SESSION (string)\nThe path to the default session file. -DOUBLE_CLICK events.DOUBLE_CLICK\nCalled when the mouse button is double-clicked.\nArguments:\n * `position`: The text position of the double click.\n * `line`: The line of the double click.\n * `modifiers`: The key modifiers held down. It is a combination of zero\n or more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK. -DWELL_END events.DWELL_END\nCalled after a `DWELL_START` and the mouse is moved or other activity such\nas key press indicates the dwell is over.\nArguments:\n * `position`: The nearest position in the document to the position where\n the mouse pointer was lingering.\n * `x`: Where the pointer lingered.\n * `y`: Where the pointer lingered. -DWELL_START events.DWELL_START\nCalled when the user keeps the mouse in one position for the dwell period\n(see `_SCINTILLA.constants.SCI_SETMOUSEDWELLTIME`).\nArguments:\n * `position`: The nearest position in the document to the position where\n the mouse pointer was lingering.\n * `x`: Where the pointer lingered.\n * `y`: Where the pointer lingered. +DEFAULT_DEPTH _M.textadept.snapopen.DEFAULT_DEPTH (number)\nMaximum directory depth to search.\nThe default value is `99`. +DEFAULT_SESSION _M.textadept.session.DEFAULT_SESSION (string)\nThe path to the default session file.\nThe default value is `_USERHOME/session`, or `_USERHOME/session_term` if\n`_G.NCURSES` is `true`. +DOUBLE_CLICK events.DOUBLE_CLICK (string)\nCalled when the mouse button is double-clicked.\nArguments:\n\n* `position`: The text position of the double click.\n* `line`: The line of the double click.\n* `modifiers`: The key modifiers held down. It is a combination of zero or\n more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK+. +DWELL_END events.DWELL_END (string)\nCalled after a `DWELL_START` and the mouse is moved or other activity such\nas key press indicates the dwell is over.\nArguments:\n\n* `position`: The nearest position in the document to the position where\n the mouse pointer was lingering.\n* `x`: Where the pointer lingered.\n* `y`: Where the pointer lingered. +DWELL_START events.DWELL_START (string)\nCalled when the user keeps the mouse in one position for the dwell period\n(see `_SCINTILLA.constants.SCI_SETMOUSEDWELLTIME`).\nArguments:\n\n* `position`: The nearest position in the document to the position where\n the mouse pointer was lingering.\n* `x`: Where the pointer lingered.\n* `y`: Where the pointer lingered. EDGE_BACKGROUND _SCINTILLA.constants.EDGE_BACKGROUND\n2 EDGE_LINE _SCINTILLA.constants.EDGE_LINE\n1 EDGE_NONE _SCINTILLA.constants.EDGE_NONE\n0 -ERROR events.ERROR\nCalled when an error occurs.\nArguments:\n * `text`: The error text. +ERROR events.ERROR (string)\nCalled when an error occurs.\nArguments:\n\n* `text`: The error text. ERROR lexer.ERROR\nToken type for error tokens. +FIELD _M.textadept.adeptsense.FIELD (string)\nCtags kind for Adeptsense fields. FIELDS _M.textadept.adeptsense.FIELDS (string)\nXPM image for Adeptsense fields. -FILE_AFTER_SAVE events.FILE_AFTER_SAVE\nCalled right after a file is saved to disk.\nArguments:\n * `filename`: The filename encoded in UTF-8. -FILE_BEFORE_SAVE events.FILE_BEFORE_SAVE\nCalled right before a file is saved to disk.\nArguments:\n * `filename`: The filename encoded in UTF-8. -FILE_OPENED events.FILE_OPENED\nCalled when a file is opened in a new buffer.\nArguments:\n * `filename`: The filename encoded in UTF-8. -FILE_SAVED_AS events.FILE_SAVED_AS\nCalled when a file is saved under a different filename.\nArguments:\n * `filename`: The filename encoded in UTF-8. -FILTER _M.textadept.snapopen.FILTER (table)\nDefault file and directory filters. -FIND events.FIND\nCalled when finding text via the Find dialog box.\nArguments:\n * `text`: The text to search for.\n * `next`: Search forward. +FILE_AFTER_SAVE events.FILE_AFTER_SAVE\nCalled right after a file is saved to disk.\nThis is emitted by `buffer:save()`\nArguments:\n * `filename`: The filename encoded in UTF-8. +FILE_BEFORE_SAVE events.FILE_BEFORE_SAVE\nCalled right before a file is saved to disk.\nThis is emitted by `buffer:save()`\nArguments:\n * `filename`: The filename encoded in UTF-8. +FILE_OPENED events.FILE_OPENED\nCalled when a file is opened in a new buffer.\nThis is emitted by `open_file()`\nArguments:\n * `filename`: The filename encoded in UTF-8. +FILE_SAVED_AS events.FILE_SAVED_AS\nCalled when a file is saved under a different filename.\nThis is emitted by `buffer:save_as()`\nArguments:\n * `filename`: The filename encoded in UTF-8. +FILTER _M.textadept.snapopen.FILTER (table)\nDefault file and directory filters.\nContains common binary file extensions and version control folders. +FIND events.FIND (string)\nCalled when finding text via the Find dialog box.\nArguments:\n\n* `text`: The text to search for.\n* `next`: Search forward. +FUNCTION _M.textadept.adeptsense.FUNCTION (string)\nCtags kind for Adeptsense functions. FUNCTION lexer.FUNCTION\nToken type for function toeksn. FUNCTIONS _M.textadept.adeptsense.FUNCTIONS (string)\nXPM image for Adeptsense functions. -HIGHLIGHT_BRACES _M.textadept.editing.HIGHLIGHT_BRACES (bool)\nHighlight matching `()[]{}` characters.\nThe default value is `true`. -HOTSPOT_CLICK events.HOTSPOT_CLICK\nCalled when the user clicks on text that is in a style with the hotspot\nattribute set.\nArguments:\n * `position`: The text position of the click.\n * `modifiers`: The key modifiers held down. It is a combination of zero\n or more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK. -HOTSPOT_DOUBLE_CLICK events.HOTSPOT_DOUBLE_CLICK\nCalled when the user double clicks on text that is in a style with the\nhotspot attribute set.\nArguments:\n * `position`: The text position of the double click.\n * `modifiers`: The key modifiers held down. It is a combination of zero\n or more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK. -HOTSPOT_RELEASE_CLICK events.HOTSPOT_RELEASE_CLICK\nCalled when the user releases the mouse on text that is in a style with the\nhotspot attribute set.\nArguments:\n * `position`: The text position of the release. +HIGHLIGHT_BRACES _M.textadept.editing.HIGHLIGHT_BRACES (bool)\nHighlight matching `()[]{}` characters.\nThe default value is `true`.\nMatching braces are defined in the `braces` table. +HOTSPOT_CLICK events.HOTSPOT_CLICK (string)\nCalled when the user clicks on text that is in a style with the hotspot\nattribute set.\nArguments:\n\n* `position`: The text position of the click.\n* `modifiers`: The key modifiers held down. It is a combination of zero or\n more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK+. +HOTSPOT_DOUBLE_CLICK events.HOTSPOT_DOUBLE_CLICK (string)\nCalled when the user double clicks on text that is in a style with the\nhotspot attribute set.\nArguments:\n\n* `position`: The text position of the double click.\n* `modifiers`: The key modifiers held down. It is a combination of zero or\n more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK+. +HOTSPOT_RELEASE_CLICK events.HOTSPOT_RELEASE_CLICK (string)\nCalled when the user releases the mouse on text that is in a style with the\nhotspot attribute set.\nArguments:\n\n* `position`: The text position of the release. IDENTIFIER lexer.IDENTIFIER\nToken type for identifier tokens. INDIC0_MASK _SCINTILLA.constants.INDIC0_MASK\n32 INDIC1_MASK _SCINTILLA.constants.INDIC1_MASK\n64 INDIC2_MASK _SCINTILLA.constants.INDIC2_MASK\n128 -INDICATOR_CLICK events.INDICATOR_CLICK\nCalled when the user clicks the mouse on text that has an indicator.\nArguments:\n * `position`: The text position of the click.\n * `modifiers`: The key modifiers held down. It is a combination of zero\n or more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK. -INDICATOR_RELEASE events.INDICATOR_RELEASE\nCalled when the user releases the mouse on text that has an indicator.\nArguments:\n * `position`: The text position of the release. +INDICATOR_CLICK events.INDICATOR_CLICK (string)\nCalled when the user clicks the mouse on text that has an indicator.\nArguments:\n\n* `position`: The text position of the click.\n* `modifiers`: The key modifiers held down. It is a combination of zero or\n more of `_SCINTILLA.constants.SCMOD_ALT`,\n `_SCINTILLA.constants.SCMOD_CTRL`,\n `_SCINTILLA.constants.SCMOD_SHIFT`, and\n `_SCINTILLA.constants.SCMOD_META`.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK+. +INDICATOR_RELEASE events.INDICATOR_RELEASE (string)\nCalled when the user releases the mouse on text that has an indicator.\nArguments:\n\n* `position`: The text position of the release. INDICS_MASK _SCINTILLA.constants.INDICS_MASK\n224 INDIC_BOX _SCINTILLA.constants.INDIC_BOX\n6 INDIC_CONTAINER _SCINTILLA.constants.INDIC_CONTAINER\n8 @@ -76,7 +79,7 @@ INDIC_DOTBOX _SCINTILLA.constants.INDIC_DOTBOX\n12 INDIC_DOTS _SCINTILLA.constants.INDIC_DOTS\n10 INDIC_HIDDEN _SCINTILLA.constants.INDIC_HIDDEN\n5 INDIC_HIGHLIGHT_ALPHA _M.textadept.editing.INDIC_HIGHLIGHT_ALPHA (number)\nThe alpha transparency value between `0` (transparent) and `255` (opaque)\nused for an indicator for a highlighted word.\nThe default value is `100`. -INDIC_HIGHLIGHT_BACK _M.textadept.editing.INDIC_HIGHLIGHT_BACK (number)\nThe color used for an indicator for a highlighted word in `0xBBGGRR`\nformat. +INDIC_HIGHLIGHT_BACK _M.textadept.editing.INDIC_HIGHLIGHT_BACK (number)\nThe color used for an indicator for a highlighted word\nin `0xBBGGRR` format. INDIC_MAX _SCINTILLA.constants.INDIC_MAX\n31 INDIC_PLAIN _SCINTILLA.constants.INDIC_PLAIN\n0 INDIC_ROUNDBOX _SCINTILLA.constants.INDIC_ROUNDBOX\n7 @@ -87,40 +90,40 @@ INDIC_STRAIGHTBOX _SCINTILLA.constants.INDIC_STRAIGHTBOX\n8 INDIC_STRIKE _SCINTILLA.constants.INDIC_STRIKE\n4 INDIC_TT _SCINTILLA.constants.INDIC_TT\n2 INVALID_POSITION _SCINTILLA.constants.INVALID_POSITION\n-1 -KEYPRESS events.KEYPRESS\nCalled when a key is pressed.\nArguments:\n * `code`: The key code.\n * `shift`: The Shift key is held down.\n * `ctrl`: The Control/Command key is held down.\n * `alt`: The Alt/option key is held down.\n * `meta`: The Control key on Mac OSX is held down. -KEYSYMS keys.KEYSYMS (table)\nLookup table for key codes higher than 255.\nIf a key code given to `keypress()` is higher than 255, this table is used to\nreturn a string representation of the key if it exists. +KEYPRESS events.KEYPRESS (string)\nCalled when a key is pressed.\nArguments:\n\n* `code`: The key code.\n* `shift`: The Shift key is held down.\n* `ctrl`: The Control/Command key is held down.\n* `alt`: The Alt/option key is held down.\n* `meta`: The Control key on Mac OSX is held down. +KEYSYMS keys.KEYSYMS (table)\nLookup table for string representations of GDK key codes higher than 255.\nKey codes can be identified by temporarily uncommenting the `print()`\nstatements in `core/keys.lua` KEYWORD lexer.KEYWORD\nToken type for keyword tokens. KEYWORDSET_MAX _SCINTILLA.constants.KEYWORDSET_MAX\n8 LABEL lexer.LABEL\nToken type for label tokens. -LANGUAGE_MODULE_LOADED events.LANGUAGE_MODULE_LOADED\nCalled when loading a language-specific module.\nThis is useful for overriding its key commands since they are not available\nwhen Textadept starts.\nArguments:\n * `lang`: The language lexer name. -LANGUAGE_MODULE_PREFIX keys.LANGUAGE_MODULE_PREFIX (string)\nThe starting key command of the keychain reserved for language-specific\nmodules.\nThe default value is Ctrl/Cmd+L. -MARGIN_CLICK events.MARGIN_CLICK\nCalled when the mouse is clicked inside a margin.\nArguments:\n * `margin`: The margin number that was clicked.\n * `position`: The position of the start of the line in the buffer that\n corresponds to the margin click.\n * `modifiers`: The appropriate combination of\n `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`,\n and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were\n held down at the time of the margin click.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK. +LANGUAGE_MODULE_LOADED events.LANGUAGE_MODULE_LOADED\nCalled after loading a language-specific module.\nThis is useful for overriding a language-specific module's key bindings\nor other properties since the module is not loaded when Textadept starts.\nArguments:\n * `lang`: The language lexer name. +LANGUAGE_MODULE_PREFIX keys.LANGUAGE_MODULE_PREFIX (string)\nThe starting key command of the key chain reserved for language-specific\nmodules.\nThe default value is `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in ncurses). +MARGIN_CLICK events.MARGIN_CLICK (string)\nCalled when the mouse is clicked inside a margin.\nArguments:\n\n* `margin`: The margin number that was clicked.\n* `position`: The position of the start of the line in the buffer that\n corresponds to the margin click.\n* `modifiers`: The appropriate combination of\n `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`,\n and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were held\n down at the time of the margin click.\n Note: If you set `buffer.rectangular_selection_modifier` to\n `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both*\n Ctrl and Alt due to a Scintilla limitation with GTK+. MARKER_MAX _SCINTILLA.constants.MARKER_MAX\n31 MARK_BOOKMARK_COLOR _M.textadept.bookmarks.MARK_BOOKMARK_COLOR (number)\nThe color used for a bookmarked line in `0xBBGGRR` format. -MARK_HIGHLIGHT_BACK _M.textadept.editing.MARK_HIGHLIGHT_BACK (number)\nThe background color used for a line containing a highlighted word in\n`0xBBGGRR` format. -MAX _M.textadept.snapopen.MAX (number)\nMaximum number of files to list. The default value is `1000`. -MAX_RECENT_FILES _M.textadept.session.MAX_RECENT_FILES (number)\nThe maximum number of files from the recent files list to save to the\nsession.\nThe default value is `10`. -MENU_CLICKED events.MENU_CLICKED\nCalled when a menu item is selected.\nArguments:\n * `menu_id`: The numeric ID of the menu item set in `gui.gtkmenu()`. -NCURSES _G.NCURSES (bool)\nIf Textadept is running in the terminal, this flag is `true`. +MARK_HIGHLIGHT_BACK _M.textadept.editing.MARK_HIGHLIGHT_BACK (number)\nThe background color used for a line containing a\nhighlighted word in `0xBBGGRR` format. +MAX _M.textadept.snapopen.MAX (number)\nMaximum number of files to list.\nThe default value is `1000`. +MAX_RECENT_FILES _M.textadept.session.MAX_RECENT_FILES (number)\nThe maximum number of files from `io.recent_files` to save to the\nsession.\nThe default value is `10`. +MENU_CLICKED events.MENU_CLICKED (string)\nCalled when a menu item is selected.\nArguments:\n\n* `menu_id`: The numeric ID of the menu item set in `gui.menu()`. +NCURSES _G.NCURSES (bool)\nIf Textadept is running in the terminal, this flag is `true`.\nncurses feature incompatibilities are listed in the Appendix. NUMBER lexer.NUMBER\nToken type for number tokens. OPERATOR lexer.OPERATOR\nToken type for operator tokens. OSX _G.OSX (bool)\nIf Textadept is running on Mac OSX, this flag is `true`. P lpeg.P(value)\nConverts the given value into a proper pattern, according to the following\nrules:\n * If the argument is a pattern, it is returned unmodified.\n * If the argument is a string, it is translated to a pattern that matches\n literally the string.\n * If the argument is a non-negative number n, the result is a pattern that\n matches exactly n characters.\n * If the argument is a negative number -n, the result is a pattern that\n succeeds only if the input string does not have n characters: lpeg.P(-n)\n is equivalent to -lpeg.P(n) (see the unary minus operation).\n * If the argument is a boolean, the result is a pattern that always\n succeeds or always fails (according to the boolean value), without\n consuming any input.\n * If the argument is a table, it is interpreted as a grammar (see\n Grammars).\n * If the argument is a function, returns a pattern equivalent to a\n match-time capture over the empty string. PATHS _M.textadept.snapopen.PATHS (table)\nTable of default UTF-8 paths to search. PREPROCESSOR lexer.PREPROCESSOR\nToken type for preprocessor tokens. -QUIT events.QUIT\nCalled when quitting Textadept.\nWhen connecting to this event, connect with an index of 1 or the handler\nwill be ignored. +QUIT events.QUIT (string)\nCalled when quitting Textadept.\nWhen connecting to this event, connect with an index of 1 or the handler\nwill be ignored.\nThis is emitted by `quit()`. R lpeg.R({range})\nReturns a pattern that matches any single character belonging to one of the\ngiven ranges. Each range is a string xy of length 2, representing all\ncharacters with code between the codes of x and y (both inclusive).\n\nAs an example, the pattern lpeg.R("09") matches any digit, and lpeg.R("az",\n"AZ") matches any ASCII letter. REGEX lexer.REGEX\nToken type for regex tokens. -REPLACE events.REPLACE\nCalled to replace selected (found) text.\nArguments:\n * `text`: The text to replace selected text with. -REPLACE_ALL events.REPLACE_ALL\nCalled to replace all occurances of found text.\nArguments:\n * `find_text`: The text to search for.\n * `repl_text`: The text to replace found text with. +REPLACE events.REPLACE (string)\nCalled to replace selected (found) text.\nArguments:\n\n* `text`: The text to replace selected text with. +REPLACE_ALL events.REPLACE_ALL (string)\nCalled to replace all occurances of found text.\nArguments:\n\n* `find_text`: The text to search for.\n* `repl_text`: The text to replace found text with. RESETTING _G.RESETTING (bool)\nIf `reset()` has been called, this flag is `true` while the Lua\nstate is being re-initialized. -RESET_AFTER events.RESET_AFTER\nCalled after resetting the Lua state.\nThis is triggered by `reset()`. -RESET_BEFORE events.RESET_BEFORE\nCalled before resetting the Lua state.\nThis is triggered by `reset()`. -RUN_OUTPUT events.RUN_OUTPUT\nCalled after a run command is executed.\nWhen connecting to this event (typically from a language-specific module),\nconnect with an index of `1` and return `true` if the event was handled and\nyou want to override the default handler that prints the output to a new\nview.\nArguments:\n * `lexer`: The lexer language.\n * `output`: The output from the command. +RESET_AFTER events.RESET_AFTER (string)\nCalled after resetting the Lua state.\nThis is emitted by `reset()`. +RESET_BEFORE events.RESET_BEFORE (string)\nCalled before resetting the Lua state.\nThis is emitted by `reset()`. +RUN_OUTPUT events.RUN_OUTPUT\nCalled after a run command is executed.\nBy default, output is printed to the message buffer. To override this\nbehavior, connect to the event with an index of `1` and return `true`.\nArguments:\n * `lexer`: The lexer language.\n * `output`: The output from the command. S lpeg.S(string)\nReturns a pattern that matches any single character that appears in the given\nstring. (The S stands for Set.)\n\nAs an example, the pattern lpeg.S("+-*/") matches any arithmetic operator.\n\nNote that, if s is a character (that is, a string of length 1), then\nlpeg.P(s) is equivalent to lpeg.S(s) which is equivalent to lpeg.R(s..s).\nNote also that both lpeg.S("") and lpeg.R() are patterns that always fail. -SAVE_ON_QUIT _M.textadept.session.SAVE_ON_QUIT (bool)\nSave the session when quitting.\nThe default value is `true` and can be disabled by passing the command line\nswitch `-n` or `--nosession` to Textadept. -SAVE_POINT_LEFT events.SAVE_POINT_LEFT\nCalled when a save point is left. -SAVE_POINT_REACHED events.SAVE_POINT_REACHED\nCalled when a save point is entered. +SAVE_ON_QUIT _M.textadept.session.SAVE_ON_QUIT (bool)\nSave the session when quitting.\nThe default value is `true`, but can be disabled by passing the command\nline switch `-n` or `--nosession` to Textadept. +SAVE_POINT_LEFT events.SAVE_POINT_LEFT (string)\nCalled when a save point is left. +SAVE_POINT_REACHED events.SAVE_POINT_REACHED (string)\nCalled when a save point is entered. SCEN_CHANGE _SCINTILLA.constants.SCEN_CHANGE\n768 SCEN_KILLFOCUS _SCINTILLA.constants.SCEN_KILLFOCUS\n256 SCEN_SETFOCUS _SCINTILLA.constants.SCEN_SETFOCUS\n512 @@ -735,38 +738,38 @@ STYLE_LINENUMBER _SCINTILLA.constants.STYLE_LINENUMBER\n33 STYLE_MAX _SCINTILLA.constants.STYLE_MAX\n255 TYPE lexer.TYPE\nToken type for type tokens. UNDO_MAY_COALESCE _SCINTILLA.constants.UNDO_MAY_COALESCE\n1 -UPDATE_UI events.UPDATE_UI\nCalled when either the text or styling of the buffer has changed or the\nselection range has changed. -URI_DROPPED events.URI_DROPPED\nCalled when the user has dragged a URI such as a file name onto the view.\nArguments:\n * `text`: The URI text encoded in UTF-8. -USER_LIST_SELECTION events.USER_LIST_SELECTION\nCalled when the user has selected an item in a user list.\nArguments:\n * `list_type`: This is set to the list_type parameter from the\n `buffer:user_list_show()` call that initiated the list.\n * `text`: The text of the selection.\n * `position`: The position the list was displayed at. +UPDATE_UI events.UPDATE_UI (string)\nCalled when either the text or styling of the buffer has changed or the\nselection range has changed. +URI_DROPPED events.URI_DROPPED (string)\nCalled when the user has dragged a URI such as a file name onto the view.\nArguments:\n\n* `text`: The URI text encoded in UTF-8. +USER_LIST_SELECTION events.USER_LIST_SELECTION (string)\nCalled when the user has selected an item in a user list.\nArguments:\n\n* `list_type`: This is set to the list_type parameter from the\n `buffer:user_list_show()` call that initiated the list.\n* `text`: The text of the selection.\n* `position`: The position the list was displayed at. V lpeg.V(v)\nThis operation creates a non-terminal (a variable) for a grammar. The created\nnon-terminal refers to the rule indexed by v in the enclosing grammar. (See\nGrammars for details.) VARIABLE lexer.VARIABLE\nToken type for variable tokens. -VIEW_AFTER_SWITCH events.VIEW_AFTER_SWITCH\nCalled right after another view is switched to. -VIEW_BEFORE_SWITCH events.VIEW_BEFORE_SWITCH\nCalled right before another view is switched to. -VIEW_NEW events.VIEW_NEW\nCalled when a new view is created. +VIEW_AFTER_SWITCH events.VIEW_AFTER_SWITCH (string)\nCalled right after another view is switched to.\nThis is emitted by `gui.goto_view()`. +VIEW_BEFORE_SWITCH events.VIEW_BEFORE_SWITCH (string)\nCalled right before another view is switched to.\nThis is emitted by `gui.goto_view()`. +VIEW_NEW events.VIEW_NEW (string)\nCalled when a new view is created.\nThis is emitted on startup and by `view:split()`. VISIBLE_SLOP _SCINTILLA.constants.VISIBLE_SLOP\n1 VISIBLE_STRICT _SCINTILLA.constants.VISIBLE_STRICT\n4 WHITESPACE lexer.WHITESPACE\nToken type for whitespace tokens. WIN32 _G.WIN32 (bool)\nIf Textadept is running on Windows, this flag is `true`. -_BUFFERS _G._BUFFERS (table)\nTable of all open buffers in Textadept.\nNumeric keys have buffer values and buffer keys have their associated numeric\nkeys. -_CHARSET _G._CHARSET (string)\nThe character set encoding of the filesystem.\nThis is used in File I/O. +_BUFFERS _G._BUFFERS (table)\nTable of all open buffers in Textadept.\nNumeric keys have buffer values and buffer keys have their associated numeric\nkeys.\n@see _G.buffer +_CHARSET _G._CHARSET (string)\nThe character set encoding of the filesystem.\nThis is used when working with files. _EMBEDDEDRULES lexer._EMBEDDEDRULES (table)\nSet of rules for an embedded lexer.\nFor a parent lexer name, contains child's `start_rule`, `token_rule`, and\n`end_rule` patterns. -_EXISTS M._EXISTS(message)\nReturns whether or not a localized message exists for the given message.\n@param message The message to localize.\n@return `true` if a localization exists, `false` otherwise. +_EXISTS M._EXISTS(message)\nReturns whether or not a localized message exists for the given message.\nThis function is necessary since `_L[message]` never returns `nil`.\n@param message The message to localize.\n@return `true` if a localization exists, `false` otherwise. _G _G._G (module)\nLua _G module. _G _G._G (table)\nA global variable (not a function) that holds the global environment\n(see §2.2). Lua itself does not use this variable; changing its value does\nnot affect any environment, nor vice-versa. _HOME _G._HOME (string)\nPath to the directory containing Textadept. -_L _G._L (module)\nTable of all messages used by Textadept for localization. -_LEXERPATH _G._LEXERPATH (string)\nPaths to lexers, formatted like\n`package.path`. +_L _G._L (module)\nTable of all messages used by Textadept for localization.\nIf the table does not contain the localized version of a given message, it\nreturns a string indicating so via a metamethod. +_LEXERPATH _G._LEXERPATH (string)\nPaths to lexers, formatted like `package.path`. _M _G._M (module)\nA table of loaded modules. _RELEASE _G._RELEASE (string)\nThe Textadept release version. _RULES lexer._RULES (table)\nList of rule names with associated LPeg patterns for a specific lexer.\nIt is accessible to other lexers for embedded lexer applications. -_SCINTILLA _G._SCINTILLA (module)\nScintilla constants, functions, and properties.\nDo not modify anything in this module. Doing so will result in instability. -_USERHOME _G._USERHOME (string)\nPath to the user's `~/.textadept/`. +_SCINTILLA _G._SCINTILLA (module)\nScintilla constants, functions, and properties.\nDo not modify anything in this module. Doing so will have unpredicable\nconsequences. +_USERHOME _G._USERHOME (string)\nPath to the user's `~/.textadept/`, where all preferences and user-data is\nstored.\nOn Windows machines `~/` is the value of the `USERHOME` environment\nvariable, typically `C:\Users\<username>\` or\n`C:\Documents and Settings\<username>\`. On Linux, BSD, and Mac OSX\nmachines `~/` is the value of `HOME`, typically `/home/<username>/` and\n`/Users/<username>/` respectively. _VERSION _G._VERSION (string)\nA global variable (not a function) that holds a string containing the\ncurrent interpreter version. The current contents of this variable is\n"`Lua 5.2`". -_VIEWS _G._VIEWS (table)\nTable of all views in Textadept.\nNumeric keys have view values and view keys have their associated numeric\nkeys. +_VIEWS _G._VIEWS (table)\nTable of all views in Textadept.\nNumeric keys have view values and view keys have their associated numeric\nkeys.\n@see _G.view _cancel_current _M.textadept.snippets._cancel_current()\nCancels the active snippet, reverting to the state before its activation, and\nrestores the previously running snippet (if any). -_insert _M.textadept.snippets._insert(text)\nInserts a snippet.\n@param text Optional snippet text. If none is specified, the snippet text\n is determined from the trigger and lexer.\n@return `false` if no snippet was expanded; `true` otherwise. -_previous _M.textadept.snippets._previous()\nGoes back to the previous placeholder, reverting any changes from the current\none.\n@return `false` if no snippet is active; `nil` otherwise. -_print gui._print(buffer_type, ...)\nHelper function for printing messages to buffers.\nSplits the view and opens a new buffer for printing messages. If the message\nbuffer is already open and a view is currently showing it, the message is\nprinted to that view. Otherwise the view is split, goes to the open message\nbuffer, and prints to it.\n@param buffer_type String type of message buffer.\n@param ... Message strings.\n@usage gui._print(_L['[Error Buffer]'], error_message)\n@usage gui._print(_L['[Message Buffer]'], message) +_insert _M.textadept.snippets._insert(text)\nInserts a new snippet or goes to the next placeholder of the active snippet.\n@param text Optional snippet text. If `nil`, attempts to insert a new snippet\n based on the trigger, the word to the left of the caret, and the current\n lexer.\n@return `false` if no action was taken; `nil` otherwise.\n@see buffer.word_chars +_previous _M.textadept.snippets._previous()\nGoes back to the previous snippet placeholder, reverting any changes from the\ncurrent one.\n@return `false` if no snippet is active; `nil` otherwise. +_print gui._print(buffer_type, ...)\nHelper function for printing messages to buffers.\nSplits the view and opens a new buffer for printing messages to. If the\nmessage buffer is already open in a view, the message is printed to that\nview. Otherwise the view is split and the message buffer is opened or\ndisplayed before being printed to.\n@param buffer_type String type of message buffer.\n@param ... Message strings.\n@usage gui._print(_L['[Error Buffer]'], error_message)\n@usage gui._print(_L['[Message Buffer]'], message) _select _M.textadept.snippets._select()\nPrompts the user to select a snippet to insert from a filtered list dialog.\nGlobal snippets and snippets in the current lexer are shown. abs math.abs(x)\nReturns the absolute value of `x`. acos math.acos(x)\nReturns the arc cosine of `x` (in radians). @@ -780,11 +783,11 @@ additional_sel_alpha buffer.additional_sel_alpha (number)\nThe alpha of addition additional_sel_back buffer.additional_sel_back (number)\nThe background color of additional selections in `0xBBGGRR` format.\n`buffer:set_sel_back(true, ...)` must have been called previously for this\nto have an effect. additional_sel_fore buffer.additional_sel_fore (number)\nThe foreground color of additional selections in `0xBBGGRR` format.\n`buffer:set_sel_fore(true, ...)` must have been called previously for this\nto have an effect. additional_selection_typing buffer.additional_selection_typing (bool)\nWhether typing can be performed into multiple selections. -adeptsense _M.textadept.adeptsense (module)\nLanguage autocompletion support for the textadept module. +adeptsense _M.textadept.adeptsense (module)\nCode autocompletion and documentation support for programming languages. allocate buffer.allocate(buffer, bytes)\nEnlarge the document to a particular size of text bytes.\nThe document will not be made smaller than its current contents.\n@param buffer The global buffer. alnum lexer.alnum\nMatches any alphanumeric character (`A-Z`, `a-z`, `0-9`). alpha lexer.alpha\nMatches any alphabetic character (`A-Z`, `a-z`). -always_show_globals _M.textadept.adeptsense.always_show_globals (bool)\nInclude globals in the list of completions offered.\nGlobals are classes, functions, and fields that do not belong to another\nclass. They are contained in `completions['']`. The default value is\n`true`. +always_show_globals _M.textadept.adeptsense.always_show_globals (bool)\nInclude globals in the list of completions offered.\nGlobals are classes, functions, and fields that do not belong to another\nclass. They are contained in `completions['']`.\nThe default value is `true`. anchor buffer.anchor (number)\nThe position of the opposite end of the selection to the caret. annotation_clear_all buffer.annotation_clear_all(buffer)\nClear the annotations from all lines.\n@param buffer The global buffer. annotation_lines buffer.annotation_lines (table, Read-only)\nTable of the number of annotation lines for lines starting from zero. @@ -793,9 +796,9 @@ annotation_style_offset buffer.annotation_style_offset (number)\nThe start of th annotation_text buffer.annotation_text (table)\nTable of annotation text for lines starting from zero. annotation_visible buffer.annotation_visible (number)\nThe visibility of annotations.\n\n* `_SCINTILLA.constants.ANNOTATION_HIDDEN` (0)\n Annotations are not displayed.\n* `_SCINTILLA.constants.ANNOTATION_STANDARD` (1)\n Annotations are drawn left justified with no adornment.\n* `_SCINTILLA.constants.ANNOTATION_BOXED` (2)\n Annotations are indented to match the text and are surrounded by a box. any lexer.any\nMatches any single character. -api_files _M.textadept.adeptsense.api_files (table)\nContains a list of api files used by `show_apidoc()`.\nEach line in the api file contains a symbol name (not the full symbol)\nfollowed by a space character and then the symbol's documentation. Since\nthere may be many duplicate symbol names, it is recommended to put the full\nsymbol and arguments, if any, on the first line. (e.g. `Class.function(arg1,\narg2, ...)`). This allows the correct documentation to be shown based on the\ncurrent context. In the documentation, newlines are represented with `\\n`. A\n`\` before `\\n` escapes the newline. +api_files _M.textadept.adeptsense.api_files (table)\nContains a list of api files used by `show_apidoc()`.\nEach line in the api file contains a symbol name (not the full symbol)\nfollowed by a space character and then the symbol's documentation. Since\nthere may be many duplicate symbol names, it is recommended to put the full\nsymbol and arguments, if any, on the first line. (e.g. `Class.function(arg1,\narg2, ...)`). This allows the correct documentation to be shown based on the\ncurrent context. In the documentation, newlines are represented with `\n`. A\n`\` before `\n` escapes the newline. append_text buffer.append_text(buffer, text)\nAppend a string to the end of the document without changing the selection.\nThe current selection is not changed and the new text is not scrolled into\nview.\n@param buffer The global buffer.\n@param text The text. -arg _G.arg (table)\nCommand line parameters. +arg _G.arg (table)\nCommand line parameters passed to Textadept.\n@see _G.args args _G.args (module)\nProcesses command line arguments for Textadept. arshift bit32.arshift(x, disp)\nReturns the number `x` shifted `disp` bits to the right. The number `disp`\nmay be any representable integer. Negative displacements shift to the left.\n\nThis shift operation is what is called arithmetic shift. Vacant bits on the\nleft are filled with copies of the higher bit of `x`; vacant bits on the\nright are filled with zeros. In particular, displacements with absolute\nvalues higher than 31 result in zero or `0xFFFFFFFF` (all original bits are\nshifted out). ascii lexer.ascii\nMatches any ASCII character (`0`..`127`). @@ -824,7 +827,7 @@ auto_c_separator buffer.auto_c_separator (number)\nThe auto-completion list sepa auto_c_show buffer.auto_c_show(buffer, len_entered, item_list)\nDisplay an auto-completion list.\n@param len_entered The number of characters before the caret used to provide\n the context.\n@param item_list List of words separated by separator characters (initially\n spaces). The list of words should be in sorted order. auto_c_stops buffer.auto_c_stops(buffer, chars)\nDefine a set of characters that when typed cancel the auto-completion list.\n@param buffer The global buffer.\n@param chars String list of characters. This list is empty by default. auto_c_type_separator buffer.auto_c_type_separator (number)\nThe auto-completion list type-separator character byte.\nThe default is `'?'`. Autocompletion list items may display an image as\nwell as text. Each image is first registered with an integer type. Then\nthis integer is included in the text of the list separated by a `?` from\nthe text. -autocomplete_word _M.textadept.editing.autocomplete_word(word_chars, default_words)\nPops up an autocompletion list for the current word based on other words in\nthe document.\n@param word_chars String of chars considered to be part of words.\n@param default_words Optional list of words considered to be in the document,\n even if they are not. Words may contain registered images.\n@return `true` if there were completions to show; `false` otherwise. +autocomplete_word _M.textadept.editing.autocomplete_word(word_chars, default_words)\nPops up an autocompletion list for the current word based on other words in\nthe document.\n@param word_chars String of characters considered to be part of words. Since\n this string is used in a Lua pattern character set, character classes and\n ranges may be used.\n@param default_words Optional list of words considered to be in the document,\n even if they are not. Words may contain registered images.\n@usage _M.textadept.editing.autocomplete_word('%w_')\n@return `true` if there were completions to show; `false` otherwise. back_space_un_indents buffer.back_space_un_indents (bool)\nWhether a backspace pressed when caret is within indentation unindents. back_tab buffer.back_tab(buffer)\nDedent the selected lines.\n@param buffer The global buffer. band bit32.band(...)\nReturns the bitwise "and" of its operands. @@ -832,18 +835,19 @@ begin_undo_action buffer.begin_undo_action(buffer)\nStart a sequence of actions bit32 _G.bit32 (module)\nLua bit32 module. block_comment _M.textadept.editing.block_comment(comment)\nBlock comments or uncomments code with a given comment string.\nIf none is specified, uses the `comment_string` table.\n@param comment The comment string inserted or removed from the beginning of\n each line in the selection.\n@see comment_string bnot bit32.bnot(x)\nReturns the bitwise negation of `x`. For any integer `x`, the following\nidentity holds:\n\n assert(bit32.bnot(x) == (-1 - x) % 2^32) -boms io.boms (table)\nList of byte-order marks (BOMs). -bookmarks _M.textadept.bookmarks (module)\nBookmarks for the textadept module. +boms io.boms (table)\nList of byte-order marks (BOMs) for identifying unicode file types. +bookmarks _M.textadept.bookmarks (module)\nBookmarks for Textadept. bor bit32.bor(...)\nReturns the bitwise "or" of its operands. brace_bad_light buffer.brace_bad_light(buffer, pos)\nHighlight the character at a position indicating there is no matching brace.\n@param buffer The global buffer.\n@param pos The position or -1 to remove the highlight. brace_bad_light_indicator buffer.brace_bad_light_indicator(buffer, use_indicator, indic_num)\nUse specified indicator to highlight non matching brace instead of changing\nits style.\n@param buffer The global buffer.\n@param use_indicator Use an indicator.\n@param indic_num The indicator number. brace_highlight buffer.brace_highlight(buffer, pos1, pos2)\nHighlight the characters at two positions.\nIf indent guides are enabled, the indent that corresponds with the brace can\nbe highlighted by locating the column with `buffer.column` and highlight the\nindent with `buffer.highlight_guide`.\n@param buffer The global buffer.\n@param pos1 The first position.\n@param pos2 The second position. brace_highlight_indicator buffer.brace_highlight_indicator(buffer, use_indicator, indic_num)\nUse specified indicator to highlight matching braces instead of changing\ntheir style.\n@param buffer The global buffer.\n@param use_indicator Use an indicator.\n@param indic_num The indicator number. brace_match buffer.brace_match(buffer, pos)\nFind the position of a matching brace or `-1` if no match.\nThe brace characters handled are `(`, `)`, `[`, `]`, `{`, `}`, `<`, and `>`.\nThe search is forwards from an opening brace and backwards from a closing\nbrace. A match only occurs if the style of the matching brace is the same as\nthe starting brace or the matching brace is beyond the end of styling. Nested\nbraces are handled correctly.\n@param buffer The global buffer.\n@param pos The position.\n@return number. -braces _M.textadept.editing.braces (table)\nHighlighted brace characters.\nKeys are lexer language names and values are tables of characters that count\nas brace characters. This table can be populated by language-specific\nmodules. The defaults are '(', ')', '[', ']', '{', and '}'.\n@see HIGHLIGHT_BRACES +braces _M.textadept.editing.braces (table)\nHighlighted brace characters.\nKeys are lexer language names and values are tables of character ASCII values\nthat count as brace characters. The defaults are `(`, `)`, `[`, `]`, `{`, and\n`}`.\nThis table can be populated by language-specific modules.\n@see HIGHLIGHT_BRACES btest bit32.btest(...)\nReturns a boolean signaling whether the bitwise "and" of its operands is\ndifferent from zero. -buffer _G.buffer (module)\nThe current buffer in the current view.\nIt also represents the structure of any buffer table in `_G._BUFFER`. -buffer view.buffer (table)\nThe buffer this view contains. (Read-only) +buffer _G.buffer (module)\nA Textadept buffer object.\nBe careful when storing references to a buffer object because if you attempt\ncall a buffer function with a non-global buffer, you will get an error. See\n`check_global()` for more information. +buffer _G.buffer\nThe current buffer in the current view. +buffer view.buffer (table)\nThe buffer the view contains. (Read-only) buffered_draw buffer.buffered_draw (bool)\nWhether drawing is buffered.\nIf drawing is buffered then each line of text is drawn into a bitmap buffer\nbefore drawing it to the screen to avoid flicker. The default is for\ndrawing to be buffered. first or directly onto the screen. byte string.byte(s [, i [, j]])\nReturns the internal numerical codes of the characters `s[i]`, `s[i+1]`,\n..., `s[j]`. The default value for `i` is 1; the default value for `j`\nis `i`. These indices are corrected following the same rules of function\n`string.sub`.\n\nNumerical codes are not necessarily portable across platforms. call_tip_active buffer.call_tip_active(buffer)\nIs there an active call tip?\n@param buffer The global buffer.\n@return bool @@ -875,14 +879,14 @@ char_at buffer.char_at (table, Read-only)\nTable of character bytes at positions char_left buffer.char_left(buffer)\nMove caret left one character.\n@param buffer The global buffer. char_left_extend buffer.char_left_extend(buffer)\nMove caret left one character extending selection to new caret position.\n@param buffer The global buffer. char_left_rect_extend buffer.char_left_rect_extend(buffer)\nMove caret left one character, extending rectangular selection to new caret\nposition.\n@param buffer The global buffer. -char_matches _M.textadept.editing.char_matches (table)\nAuto-matched characters.\nUsed for auto-matching parentheses, brackets, braces, quotes, etc. Keys are\nlexer language names and values are tables of character match pairs. This\ntable can be populated by language-specific modules. The defaults are '()',\n'[]', '{}', '''', and '""'.\n@see AUTOPAIR +char_matches _M.textadept.editing.char_matches (table)\nAuto-matched characters.\nUsed for auto-matching parentheses, brackets, braces, quotes, etc. Keys are\nlexer language names and values are tables of character match pairs. A pair's\nkey is an ASCII value and the value is the string character match. The\ndefaults are `()`, `[]`, `{}`, `''`, and `""`.\nThis table can be populated by language-specific modules.\n@see AUTOPAIR char_position_from_point buffer.char_position_from_point(buffer, x, y)\nFind the position of a character from a point within the window.\n@param buffer The global buffer.\n@return number char_position_from_point_close buffer.char_position_from_point_close(buffer, x, y)\nFind the position of a character from a point within the window.\nReturn `-1` if not close to text.\n@param buffer The global buffer.\n@return number char_right buffer.char_right(buffer)\nMove caret right one character.\n@param buffer The global buffer. char_right_extend buffer.char_right_extend(buffer)\nMove caret right one character extending selection to new caret position.\n@param buffer The global buffer. char_right_rect_extend buffer.char_right_rect_extend(buffer)\nMove caret right one character, extending rectangular selection to new caret\nposition.\n@param buffer The global buffer. chdir lfs.chdir(path)\nChanges the current working directory to the given path.\n\nReturns true in case of success or nil plus an error string. -check_global buffer.check_global(buffer)\nChecks whether the given buffer is the global one.\nIf not, throws an error indicating so. It is necessary to call this at the\ntop of all buffer functions to avoid unexpected behavior since most buffer\nfunctions operate on `_G.buffer`, which is not necessarily the given one.\n@param buffer The buffer to check. +check_global buffer.check_global(buffer)\nChecks whether the given buffer is the global one.\nIf not, throws an error indicating so. It is necessary to call this at the\ntop of all buffer functions to avoid unexpected behavior since most buffer\nfunctions operate on `_G.buffer`, which is not necessarily the given one.\n@param buffer The buffer to check.\n@see _G._G.buffer choose_caret_x buffer.choose_caret_x(buffer)\nSet the last x chosen value to be the caret x position.\nThe view remembers the x value of the last position horizontally moved to\nexplicitly by the user and this value is then used when moving vertically\nsuch as by using the up and down keys. This function sets the current x\nposition of the caret as the remembered value.\n@param buffer The global buffer. class_definition _M.textadept.adeptsense.syntax.class_definition (table)\nA Lua pattern representing the language's class\n definition syntax. The first capture returned must be the class name. A\n second, optional capture contains the class' superclass (if any). If no\n completions are found for the class name, completions for the superclass\n are shown (if any). Completions will not be shown for both a class and\n superclass unless defined in a previously loaded ctags file. Also, multiple\n superclasses cannot be recognized by this pattern; use a ctags file\n instead. The default value is `'class%s+([%w_]+)'`. clear _M.textadept.adeptsense.clear(sense)\nClears an Adeptsense.\nThis is necessary for loading a new ctags file or completions from a\ndifferent project.\n@param sense The Adeptsense returned by `adeptsense.new()`. @@ -895,10 +899,10 @@ clear_registered_images buffer.clear_registered_images(buffer)\nClear all the re clear_selections buffer.clear_selections(buffer)\nClear selections to a single empty stream selection.\n@param buffer The global buffer. clipboard_text gui.clipboard_text (string, Read-only)\nThe text on the clipboard. clock os.clock()\nReturns an approximation of the amount in seconds of CPU time used by\nthe program. -close buffer.close(buffer)\nCloses the current buffer.\n@param buffer The global buffer.\nIf the buffer is dirty, the user is prompted to continue. The buffer is not\nsaved automatically. It must be done manually. +close buffer.close(buffer)\nCloses the current buffer.\n@param buffer The global buffer.\nIf the buffer is dirty, the user is prompted to continue. The buffer is not\nsaved automatically. It must be done manually.\n@return `true` if the buffer was closed; `nil` otherwise. close file:close()\nCloses `file`. Note that files are automatically closed when their\nhandles are garbage collected, but that takes an unpredictable amount of\ntime to happen.\n\nWhen closing a file handle created with `io.popen`, `file:close` returns the\nsame values returned by `os.execute`. close io.close([file])\nEquivalent to `file:close()`. Without a `file`, closes the default\noutput file. -close_all io.close_all()\nCloses all open buffers.\nIf any buffer is dirty, the user is prompted to continue. No buffers are\nsaved automatically. They must be saved manually.\n@usage io.close_all()\n@return `true` if user did not cancel. +close_all io.close_all()\nCloses all open buffers.\nIf any buffer is dirty, the user is prompted to continue. No buffers are\nsaved automatically. They must be saved manually.\n@usage io.close_all()\n@return `true` if user did not cancel.\n@see buffer.close cntrl lexer.cntrl\nMatches any control character (`0`..`31`). code_page buffer.code_page (number)\nThe code page used to interpret the bytes of the document as characters.\nThe `_SCINTILLA.constants.SC_CP_UTF8` value can be used to enter Unicode\nmode. collectgarbage _G.collectgarbage([opt [, arg]])\nThis function is a generic interface to the garbage collector. It\nperforms different functions according to its first argument, `opt`:\n "collect": performs a full garbage-collection cycle. This is the default\n option.\n "stop": stops automatic execution of the garbage collector.\n "restart": restarts automatic execution of the garbage collector.\n "count": returns the total memory in use by Lua (in Kbytes) and a second\n value with the total memory in bytes modulo 1024. The first value\n has a fractional part, so the following equality is always true:\n\n k, b = collectgarbage("count")\n assert(k*1024 == math.floor(k)*1024 + b)\n\n (The second result is useful when Lua is compiled with a non\n floating-point type for numbers.)\n "step": performs a garbage-collection step. The step "size" is controlled\n by `arg` (larger values mean more steps) in a non-specified way. If\n you want to control the step size you must experimentally tune the\n value of `arg`. Returns true if the step finished a collection\n cycle.\n "setpause": sets `arg` as the new value for the *pause* of the collector\n (see §2.5). Returns the previous value for *pause*.\n "setstepmul": sets `arg` as the new value for the *step multiplier*\n of the collector (see §2.5). Returns the previous value for\n *step*.\n "isrunning": returns a boolean that tells whether the collector is running\n (i.e., not stopped).\n "generational": changes the collector to generational mode. This is an\n experimental feature (see §2.5).\n "incremental": changes the collector to incremental mode. This is the\n default mode. @@ -906,24 +910,24 @@ color lexer.color(r, g, b)\nCreates a Scintilla color.\n@param r The string red colors lexer.colors (table)\nTable of common colors for a theme.\nThis table should be redefined in each theme. colourise buffer.colourise(buffer, start_pos, end_pos)\nColorise a segment of the document using the current lexing language.\n@param buffer The global buffer.\n@param start_pos The start position.\n@param end_pos The end position or `-1` to style from `start_pos` to the end\n of the document. column buffer.column (table, Read-only)\nTable of column numbers, taking tab widths into account, for positions\nstarting from zero. -command_entry gui.command_entry (module)\nTextadept's Command entry. +command_entry gui.command_entry (module)\nTextadept's Command Entry. comment_string _M.textadept.editing.comment_string (table)\nComment strings for various lexer languages.\nUsed by the `block_comment()` function. Keys are lexer language names and\nvalues are the line comment delimiters for the language. This table is\ntypically populated by language-specific modules.\n@see block_comment -compile _M.textadept.run.compile()\nCompiles the file as specified by its extension in the `compile_command`\ntable.\n@see compile_command -compile_command _M.textadept.run.compile_command (table)\nFile extensions and their associated 'compile' actions.\nEach key is a file extension whose value is a either a command line string to\nexecute or a function returning one.\nThis table is typically populated by language-specific modules. +compile _M.textadept.run.compile()\nCompiles the file based on its extension using the command from the\n`compile_command` table.\n@see compile_command +compile_command _M.textadept.run.compile_command (table)\nFile extensions and their associated "compile" shell commands.\nEach key is a file extension whose value is a either a command line string to\nexecute or a function returning one.\nThis table is typically populated by language-specific modules. complete _M.textadept.adeptsense.complete(sense, only_fields, only_functions)\nShows an autocompletion list for the symbol behind the caret.\n@param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses\n the current language's Adeptsense (if it exists).\n@param only_fields If `true`, returns list of only fields. The default value\n is `false`.\n@param only_functions If `true`, returns list of only functions. The default\n value is `false`.\n@return `true` on success or `false`.\n@see get_symbol\n@see get_completions completions _M.textadept.adeptsense.completions (table)\nContains lists of possible completions for known symbols.\nEach symbol key has a table value that contains a list of field completions\nwith a `fields` key and a list of functions completions with a `functions`\nkey. This table is normally populated by `load_ctags()`, but can also be set\nby the user. concat table.concat(list [, sep [, i [, j]]])\nGiven a list where all elements are strings or numbers, returns\n`list[i]..sep..list[i+1] ··· sep..list[j]`. The default value for `sep` is\nthe empty string, the default for `i` is 1, and the default for `j` is\n`#list`. If `i` is greater than `j`, returns the empty string. config package.config (string)\nA string describing some compile-time configurations for packages. This\nstring is a sequence of lines:\n The first line is the directory separator string. Default is '`\`' for\n Windows and '`/`' for all other systems.\n The second line is the character that separates templates in a path.\n Default is '`;`'.\n The third line is the string that marks the substitution points in a\n template. Default is '`?`'.\n The fourth line is a string that, in a path in Windows, is replaced by\n the executable's directory. Default is '`!`'.\n The fifth line is a mark to ignore all text before it when building the\n `luaopen_` function name. Default is '`-`'. -connect events.connect(event, f, index)\nAdds a handler function to an event.\n@param event The string event name. It is arbitrary and need not be defined\n anywhere.\n@param f The Lua function to add.\n@param index Optional index to insert the handler into.\n@return Index of handler.\n@see disconnect -constants _SCINTILLA.constants (table)\nScintilla constants. -context_menu _M.textadept.menu.context_menu (table)\nContains the default right-click context menu. +connect events.connect(event, f, index)\nAdds a handler function to an event.\n@param event The string event name. It is arbitrary and does not need to be\n defined previously.\n@param f The Lua function to add.\n@param index Optional index to insert the handler into.\n@usage events.connect('my_event', function(message) gui.print(message) end)\n@return Index of handler.\n@see disconnect +constants _SCINTILLA.constants (table)\nScintilla constants.\nEach key is a Scintilla constant with its associated numeric value. +context_menu _M.textadept.menu.context_menu (table)\nContains the default right-click context menu.\n@see set_contextmenu context_menu gui.context_menu\nA `gui.menu` defining the editor's context menu. contracted_fold_next buffer.contracted_fold_next(buffer, line_start)\nFind the next line at or after line_start that is a contracted fold header\nline.\nReturn `-1` when no more lines.\n@param buffer The global buffer.\n@param line_start The start line number.\n@return number control_char_symbol buffer.control_char_symbol (number)\nThe way control characters are displayed.\nIf less than `32`, keep the rounded rectangle as ASCII mnemonics.\nOtherwise, use the given character byte. The default value is `0`. -control_structure_patterns _M.lua.control_structure_patterns (table)\nPatterns for auto 'end' completion for control structures.\n@see try_to_autocomplete_end -control_structure_patterns _M.ruby.control_structure_patterns (table)\nPatterns for auto 'end' completion for control structures.\n@see try_to_autocomplete_end +control_structure_patterns _M.lua.control_structure_patterns (table)\nPatterns for auto `end` completion for control structures.\n@see try_to_autocomplete_end +control_structure_patterns _M.ruby.control_structure_patterns (table)\nPatterns for auto `end` completion for control structures.\n@see try_to_autocomplete_end convert_eo_ls buffer.convert_eo_ls(buffer, mode)\nConverts all line endings in the document to one mode.\n@param buffer The global buffer.\n@param mode The line ending mode. Valid values are:\n `_SCINTILLA.constants.SC_EOL_CRLF` (0),\n `_SCINTILLA.constants.SC_EOL_CR (1)`, or\n `_SCINTILLA.constants.SC_EOL_LF (2)`. -convert_indentation _M.textadept.editing.convert_indentation()\nConverts indentation between tabs and spaces. +convert_indentation _M.textadept.editing.convert_indentation()\nConverts indentation between tabs and spaces.\nIf `buffer.use_tabs` is `true`, all indenting spaces are converted to tabs.\nOtherwise, all indenting tabs are converted to spaces.\n@see buffer.use_tabs copy buffer.copy(buffer)\nCopy the selection to the clipboard.\n@param buffer The buffer copy_allow_line buffer.copy_allow_line(buffer)\nCopy the selection, if selection empty copy the line with the caret.\n@param buffer The global buffer. copy_range buffer.copy_range(buffer, start_pos, end_pos)\nCopy a range of text to the clipboard. Positions are clipped into the\ndocument.\n@param buffer The global buffer.\n@param start_pos The start position.\n@param end_pos The end position. @@ -933,14 +937,14 @@ cos math.cos(x)\nReturns the cosine of `x` (assumed to be in radians). cosh math.cosh(x)\nReturns the hyperbolic cosine of `x`. count_characters buffer.count_characters(buffer, start_pos, end_pos)\nCount characters between two positions.\n@return number cpath package.cpath (string)\nThe path used by `require` to search for a C loader.\nLua initializes the C path `package.cpath` in the same way it initializes\nthe Lua path `package.path`, using the environment variable `LUA_CPATH_5_2`\nor the environment variable `LUA_CPATH` or a default path defined in\n`luaconf.h`. -cpp _G.keys.cpp (table)\nContainer for C/C++-specific key commands. +cpp _G.keys.cpp (table)\nContainer for C/C++-specific key bindings. cpp _G.snippets.cpp (table)\nContainer for C/C++-specific snippets. -cpp _M.cpp (module)\nThe cpp module.\nIt provides utilities for editing C/C++ code.\nUser tags are loaded from `_USERHOME/modules/cpp/tags` and user apis are\nloaded from `_USERHOME/modules/cpp/api`. +cpp _M.cpp (module)\nThe cpp module.\nIt provides utilities for editing C/C++ code. create coroutine.create(f)\nCreates a new coroutine, with body `f`. `f` must be a Lua\nfunction. Returns this new coroutine, an object with type `"thread"`. -css _G.keys.css (table)\nContainer for CSS-specific key commands. +css _G.keys.css (table)\nContainer for CSS-specific key bindings. css _G.snippets.css (table)\nContainer for CSS-specific snippets. -css _M.css (module)\nThe css module.\nIt provides utilities for editing CSS code.\nUser tags are loaded from `_USERHOME/modules/css/tags` and user apis are\nloaded from `_USERHOME/modules/css/api`. -ctags_kinds _M.textadept.adeptsense.ctags_kinds (table)\nContains a map of ctags kinds to Adeptsense kinds.\nRecognized kinds are `'functions'`, `'fields'`, and `'classes'`. Classes are\nquite simply containers for functions and fields so Lua modules would count\nas classes. Any other kinds will be passed to `handle_ctag()` for\nuser-defined handling.\n@see handle_ctag +css _M.css (module)\nThe css module.\nIt provides utilities for editing CSS code. +ctags_kinds _M.textadept.adeptsense.ctags_kinds (table)\nContains a map of ctags kinds to Adeptsense kinds.\nRecognized kinds are `FUNCTION`, `FIELD`, and `CLASS`. Classes are quite\nsimply containers for functions and fields so Lua modules would count as\nclasses. Any other kinds will be passed to `handle_ctag()` for user-defined\nhandling.\n@see handle_ctag current_pos buffer.current_pos (number)\nThe position of the caret.\nWhen setting, the caret is not scrolled into view. currentdir lfs.currentdir()\nReturns a string with the current working directory or nil plus an error\nstring. cursor buffer.cursor (number)\nThe cursor type.\n\n* `_SCINTILLA.constants.SC_CURSORNORMAL` (-1)\n The normal cursor is displayed.\n* `_SCINTILLA.constants.SC_CURSORWAIT` (4)\n The wait cursor is displayed when the mouse is over the view. @@ -955,21 +959,21 @@ del_line_right buffer.del_line_right(buffer)\nDelete forwards from the current p del_word_left buffer.del_word_left(buffer)\nDelete the word to the left of the caret.\n@param buffer The global buffer. del_word_right buffer.del_word_right(buffer)\nDelete the word to the right of the caret.\n@param buffer The global buffer. del_word_right_end buffer.del_word_right_end(buffer)\nDelete the word to the right of the caret, but not the trailing non-word\ncharacters.\n@param buffer The global buffer. -delete buffer.delete(buffer)\nDeletes the current buffer.\nWARNING: this function should NOT be called via scripts. Use `buffer:close()`\ninstead, which prompts for confirmation if necessary. Generates a\n`BUFFER_DELETED` event.\n@param buffer The global buffer. +delete buffer.delete(buffer)\nDeletes the current buffer.\nWARNING: this function should NOT be called via scripts. Use `buffer:close()`\ninstead, which prompts for confirmation if necessary. Emits a\n`BUFFER_DELETED` event.\n@param buffer The global buffer.\n@see events.BUFFER_DELETED delete_back buffer.delete_back(buffer)\nDelete the selection or if no selection, the character before the caret.\n@param buffer The global buffer. delete_back_not_line buffer.delete_back_not_line(buffer)\nDelete the selection or if no selection, the character before the caret.\nWill not delete the character before at the start of a line. delete_range buffer.delete_range(buffer, pos, length)\nDelete a range of text in the document.\n@param pos The start position of the range to delete.\n@param length The length of the range to delete. delimited_range lexer.delimited_range(chars, escape, end_optional, balanced, forbidden)\nCreates an LPeg pattern that matches a range of characters delimitted by a\nspecific character(s).\nThis can be used to match a string, parenthesis, etc.\n@param chars The character(s) that bound the matched range.\n@param escape Optional escape character. This parameter may be omitted, nil,\n or the empty string.\n@param end_optional Optional flag indicating whether or not an ending\n delimiter is optional or not. If true, the range begun by the start\n delimiter matches until an end delimiter or the end of the input is\n reached.\n@param balanced Optional flag indicating whether or not a balanced range is\n matched, like `%b` in Lua's `string.find`. This flag only applies if\n `chars` consists of two different characters (e.g. '()').\n@param forbidden Optional string of characters forbidden in a delimited\n range. Each character is part of the set.\n@usage local sq_str_noescapes = delimited_range("'")\n@usage local sq_str_escapes = delimited_range("'", '\\', true)\n@usage local unbalanced_parens = delimited_range('()', '\\', true)\n@usage local balanced_parens = delimited_range('()', '\\', true, true) -dialog gui.dialog(kind, ...)\nDisplays a gtdialog of a specified type with the given string arguments.\nEach argument is like a string in Lua's `arg` table. Tables of strings are\nallowed as arguments and are expanded in place. This is useful for\nfilteredlist dialogs with many items.\nFor more information on gtdialog, see http://foicica.com/gtdialog.\n@param kind The kind of gtdialog.\n@param ... Parameters to the gtdialog.\n@return string gtdialog result. +dialog gui.dialog(kind, ...)\nDisplays a gtdialog of a specified type with the given string arguments.\nEach argument is like a string in Lua's `arg` table. Tables of strings are\nallowed as arguments and are expanded in place. This is useful for\nfiltered list dialogs with many items.\nFor more information on gtdialog, see http://foicica.com/gtdialog.\n@param kind The kind of gtdialog.\n@param ... Parameters to the gtdialog.\n@return string gtdialog result. difftime os.difftime(t2, t1)\nReturns the number of seconds from time `t1` to time `t2`. In POSIX,\nWindows, and some other systems, this value is exactly `t2`*-*`t1`. digit lexer.digit\nMatches any digit (`0-9`). dir lfs.dir(path)\nLua iterator over the entries of a given directory. Each time the iterator is\ncalled with dir_obj it returns a directory entry's name as a string, or nil\nif there are no more entries. You can also iterate by calling dir_obj:next(),\nand explicitly close the directory before the iteration finished with\ndir_obj:close(). Raises an error if path is not a directory. direct_function buffer.direct_function (number, Read-only)\nA pointer to a function that processes messages for this view. direct_pointer buffer.direct_pointer (number, Read-only)\nA pointer value to use as the first argument when calling the function\nreturned by direct_function. dirty buffer.dirty (bool)\nFlag indicating whether or not the buffer has been modified since it was\nlast saved. -disconnect events.disconnect(event, index)\nDisconnects a handler function from an event.\n@param event The string event name.\n@param index Index of the handler (returned by `events.connect()`).\n@see connect +disconnect events.disconnect(event, index)\nDisconnects a handler function from an event.\n@param event The string event name.\n@param index Index of the handler returned by `events.connect()`.\n@see connect doc_line_from_visible buffer.doc_line_from_visible(buffer)\nFind the document line of a display line taking hidden lines into account.\n@param buffer The global buffer.\n@return number -docstatusbar_text gui.docstatusbar_text (string, Write-only)\nThe text displayed by the doc statusbar. +docstatusbar_text gui.docstatusbar_text (string, Write-only)\nThe text displayed by the buffer statusbar. document_end buffer.document_end(buffer)\nMove caret to last position in document.\n@param buffer The global buffer. document_end_extend buffer.document_end_extend(buffer)\nMove caret to last position in document extending selection to new caret\nposition.\n@param buffer The global buffer. document_start buffer.document_start(buffer)\nMove caret to first position in document.\n@param buffer The global buffer. @@ -980,9 +984,9 @@ edge_colour buffer.edge_colour (number)\nThe color used in edge indication in `0 edge_column buffer.edge_column (number)\nThe column number which text should be kept within. edge_mode buffer.edge_mode (number)\nThe edge highlight mode.\n\n* `_SCINTILLA.constants.EDGE_NONE` (0)\n Long lines are not marked. This is the default state.\n* `_SCINTILLA.constants.EDGE_LINE` (1)\n A vertical line is drawn at the column number set by\n `buffer.edge_column`.\n* `_SCINTILLA.constants.EDGE_BACKGROUND` (2)\n The background color of characters after the column limit is changed to\n the color set by `buffer.edge_colour`. edit_toggle_overtype buffer.edit_toggle_overtype(buffer)\nSwitch from insert to overtype mode or the reverse.\n@param buffer The global buffer. -editing _M.textadept.editing (module)\nEditing commands for the textadept module. +editing _M.textadept.editing (module)\nEditing features for Textadept. embed_lexer lexer.embed_lexer(parent, child, start_rule, end_rule)\nEmbeds a child lexer language in a parent one.\n@param parent The parent lexer.\n@param child The child lexer.\n@param start_rule The token that signals the beginning of the embedded\n lexer.\n@param end_rule The token that signals the end of the embedded lexer.\n@usage embed_lexer(M, css, css_start_rule, css_end_rule)\n@usage embed_lexer(html, M, php_start_rule, php_end_rule)\n@usage embed_lexer(html, ruby, ruby_start_rule, rule_end_rule) -emit events.emit(event, ...)\nCalls all handlers for the given event in sequence (effectively "generating"\nthe event).\nIf `true` or `false` is explicitly returned by any handler, the event is not\npropagated any further; iteration ceases.\n@param event The string event name.\n@param ... Arguments passed to the handler.\n@return `true` or `false` if any handler explicitly returned such; nil\n otherwise. +emit events.emit(event, ...)\nCalls all handlers for the given event in sequence.\nIf `true` or `false` is explicitly returned by any handler, the event is not\npropagated any further; iteration ceases. This is useful if you want to stop\nthe propagation of an event like a keypress.\n@param event The string event name. It is arbitrary and does not need to be\n defined previously.\n@param ... Arguments passed to the handler.\n@usage events.emit('my_event', 'my message')\n@return `true` or `false` if any handler explicitly returned such; `nil`\n otherwise. empty_undo_buffer buffer.empty_undo_buffer(buffer)\nDelete the undo history.\nIt also sets the save point to the start of the undo buffer, so the document\nwill appear to be unmodified.\n@param buffer The global buffer. enclose _M.textadept.editing.enclose(left, right)\nEncloses text within a given pair of strings.\nIf text is selected, it is enclosed. Otherwise, the previous word is\nenclosed.\n@param left The left part of the enclosure.\n@param right The right part of the enclosure. encoded_from_utf8 buffer.encoded_from_utf8(buffer, string)\nTranslates a UTF8 string into the document encoding.\nReturn the length of the result in bytes. On error return `0`.\n@param buffer The global buffer.\n@param string The string.\n@return number @@ -996,31 +1000,31 @@ ensure_visible_enforce_policy buffer.ensure_visible_enforce_policy(buffer, line) entry_text gui.command_entry.entry_text (string)\nThe text in the entry. eol_mode buffer.eol_mode (number)\nThe current end of line mode.\n\n* `_SCINTILLA.constants.SC_EOL_CRLF` (0)\n `CRLF`.\n* `_SCINTILLA.constants.SC_EOL_CR` (1)\n `CR`.\n* `_SCINTILLA.constants.SC_EOL_LF` (2)\n `LF`. error _G.error(message [, level])\nTerminates the last protected function called and returns `message`\nas the error message. Function `error` never returns.\n\nUsually, `error` adds some information about the error position at the\nbeginning of the message, if the message is a string. The `level` argument\nspecifies how to get the error position. With level 1 (the default), the\nerror position is where the `error` function was called. Level 2 points the\nerror to where the function that called `error` was called; and so on.\nPassing a level 0 avoids the addition of error position information to the\nmessage. -error_detail _M.textadept.run.error_detail (table)\nA table of error string details.\nEach entry is a table with the following fields:\n\n + `pattern`: The Lua pattern that matches a specific error string.\n + `filename`: The index of the Lua capture that contains the filename the\n error occured in.\n + `line`: The index of the Lua capture that contains the line number the\n error occured on.\n + `message`: [Optional] The index of the Lua capture that contains the\n error's message. A call tip will be displayed if a message was captured.\n\nWhen an error message is double-clicked, the user is taken to the point of\nerror.\nThis table is usually populated by language-specific modules. +error_detail _M.textadept.run.error_detail (table)\nA table of error string details for different programming languages.\nEach key is a lexer name whose value is a table with the following fields:\n\n + `pattern`: The Lua pattern that matches a specific error string with\n captures for the filename the error occurs in, the line number the error\n occurred on, and an optional error message.\n + `filename`: The index of the Lua capture that contains the filename the\n error occured in.\n + `line`: The index of the Lua capture that contains the line number the\n error occured on.\n + `message`: (Optional) The index of the Lua capture that contains the\n error's message. An annotation will be displayed if a message was\n captured.\n\nWhen an error message is double-clicked, the user is taken to the point of\nerror.\nThis table is usually populated by language-specific modules. events _G.events (module)\nTextadept's core event structure and handlers. -execute _M.textadept.run.execute(command, lexer)\nExecutes the command line parameter and prints the output to Textadept.\n@param command The command line string.\n It can have the following macros:\n + `%(filepath)`: The full path of the current file.\n + `%(filedir)`: The current file's directory path.\n + `%(filename)`: The name of the file including extension.\n + `%(filename_noext)`: The name of the file excluding extension.\n@param lexer The current lexer. +execute _M.textadept.run.execute(command, compiling)\nExecutes the command line parameter.\nEmits a `COMPILE_OUTPUT` or `RUN_OUTPUT` event based on the `compiling` flag.\n@param command The command line string.\n It can have the following macros:\n + `%(filepath)`: The full path of the current file.\n + `%(filedir)`: The current file's directory path.\n + `%(filename)`: The name of the file including extension.\n + `%(filename_noext)`: The name of the file excluding extension.\n@param compiling Flag indicating whether or not the command is a compiler\n command. The default value is `false`.\n@see _G.events execute os.execute([command])\nThis function is equivalent to the C function `system`. It passes\n`command` to be executed by an operating system shell. Its first result is\n`true` if the command terminated successfully, or `nil` otherwise. After this\nfirst result the function returns a string and a number, as follows:\n "exit": the command terminated normally; the following number is the exit\n status of the command.\n "signal": the command was terminated by a signal; the following number is\n the signal that terminated the command.\n\nWhen called without a `command`, `os.execute` returns a boolean that is true\nif a shell is available. exit os.exit([code [, close]])\nCalls the C function `exit` to terminate the host program. If `code` is\n`true`, the returned status is `EXIT_SUCCESS`; if `code` is `false`, the\nreturned status is `EXIT_FAILURE`; if `code` is a number, the returned status\nis this number. The default value for `code` is `true`.\n\nIf the optional second argument `close` is true, closes the Lua state before\nexiting. exp math.exp(x)\nReturns the value *e^x*. extend lexer.extend\nMatches any ASCII extended character (`0`..`255`). -extensions _M.textadept.mime_types.extensions (table)\nFile extensions with their associated lexers. +extensions _M.textadept.mime_types.extensions (table)\nTable of file extensions with their associated lexers.\nIf the file type is not recognized by shebang words or first-line patterns,\neach file extension is matched against the file's extension. extra_ascent buffer.extra_ascent (number)\nThe extra ascent, the maximum that any style extends above the baseline,\nadded to each line. extra_descent buffer.extra_descent (number)\nThe extra descent, the maximum that any style extends below the baseline,\nadded to each line. extract bit32.extract(n, field [, width])\nReturns the unsigned number formed by the bits `field` to `field + width - 1`\nfrom `n`. Bits are numbered from 0 (least significant) to 31 (most\nsignificant). All accessed bits must be in the range [0, 31].\n\nThe default for `width` is 1. filename buffer.filename (string)\nThe absolute path to the file associated with this buffer.\nIt is encoded in UTF-8. Use `string.iconv()` for\ncharset conversions. -filter_through _M.textadept.filter_through (module)\nFilter-Through for the textadept module. -filter_through _M.textadept.filter_through.filter_through()\nPrompts for a Linux, Mac OSX, or Windows shell command to filter text\nthrough.\nThe standard input (stdin) for shell commands is determined as follows:\n\n1. If text is selected and spans multiple lines, all text on the lines\ncontaining the selection is used. However, if the end of the selection is at\nthe beginning of a line, only the EOL (end of line) characters from the\nprevious line are included as input. The rest of the line is excluded.\n2. If text is selected and spans a single line, only the selected text is\nused.\n3. If no text is selected, the entire buffer is used.\n\nThe input text is replaced with the standard output (stdout) of the command. -filteredlist gui.filteredlist(title, columns, items, int_return, ...)\nShortcut function for `gui.dialog('filtered_list', ...)` with 'Ok' and\n'Cancel' buttons.\n@param title The title for the filteredlist dialog.\n@param columns A column name or list of column names.\n@param items An item or list of items.\n@param int_return If `true`, returns the integer index of the selected item\n in the filteredlist. The default value is `false`, which returns the string\n item. Not compatible with a `'--select-multiple'` filteredlist.\n@param ... Additional parameters to pass to `gui.dialog()`.\n@usage gui.filteredlist('Title', 'Foo', { 'Bar', 'Baz' })\n@usage gui.filteredlist('Title', { 'Foo', 'Bar' }, { 'a', 'b', 'c', 'd' },\n false, '--output-column', '2')\n@return Either a string or integer on success; `nil` otherwise. -find gui.find (module)\nTextadept's integrated find/replace dialog. +filter_through _M.textadept.filter_through (module)\nFilters text through shell commands. +filter_through _M.textadept.filter_through.filter_through()\nPrompts for a Linux, BSD, Mac OSX, or Windows shell command to filter text\nthrough.\nThe standard input (stdin) for shell commands is determined as follows:\n\n1. If text is selected and spans multiple lines, all text on the lines\ncontaining the selection is used. However, if the end of the selection is at\nthe beginning of a line, only the EOL (end of line) characters from the\nprevious line are included as input. The rest of the line is excluded.\n2. If text is selected and spans a single line, only the selected text is\nused.\n3. If no text is selected, the entire buffer is used.\n\nThe input text is replaced with the standard output (stdout) of the command. +filteredlist gui.filteredlist(title, columns, items, int_return, ...)\nShortcut function for `gui.dialog('filteredlist', ...)` with 'Ok' and\n'Cancel' buttons.\n@param title The title for the filtered list dialog.\n@param columns A column name or list of column names.\n@param items An item or list of items.\n@param int_return If `true`, returns the integer index of the selected item\n in the filtered list and is not compatible with the `'--select-multiple'`\n option. The default value is `false`, which returns the string item(s).\n@param ... Additional parameters to pass to `gui.dialog()`.\n@usage gui.filteredlist('Title', 'Foo', { 'Bar', 'Baz' })\n@usage gui.filteredlist('Title', { 'Foo', 'Bar' }, { 'a', 'b', 'c', 'd' },\n false, '--output-column', '2')\n@return Either a string or integer on success; `nil` otherwise. In strings,\n multiple items are separated by newlines.\n@see dialog +find gui.find (module)\nTextadept's Find & Replace pane. find string.find(s, pattern [, init [, plain]])\nLooks for the first match of `pattern` in the string `s`. If it finds a\nmatch, then `find` returns the indices of `s` where this occurrence starts\nand ends; otherwise, it returns nil. A third, optional numerical argument\n`init` specifies where to start the search; its default value is 1 and\ncan be negative. A value of true as a fourth, optional argument `plain`\nturns off the pattern matching facilities, so the function does a plain\n"find substring" operation, with no characters in `pattern` being considered\nmagic. Note that if `plain` is given, then `init` must be given as well.\n\nIf the pattern has captures, then in a successful match the captured values\nare also returned, after the two indices. find_column buffer.find_column(buffer, line, column)\nFind the position of a column on a line taking into account tabs and\nmulti-byte characters.\nIf beyond end of line, return line end position.\n@param buffer The global buffer.\n@param line The line number.\n@param column The column number. find_entry_text gui.find.find_entry_text (string)\nThe text in the find entry. -find_in_files gui.find.find_in_files(utf8_dir)\nPerforms a find in files with the given directory.\nUse the `gui.find` fields to set the text to find and option flags.\n@param utf8_dir UTF-8 encoded directory name. If none is provided, the user\n is prompted for one. -find_incremental gui.find.find_incremental()\nBegins an incremental find using the Lua command entry.\nLua command functionality will be unavailable until the search is finished\n(pressing 'Escape' by default). +find_in_files gui.find.find_in_files(utf8_dir)\nSearches the given directory for files that match search text and options and\nprints the results to a buffer.\nUse the `find_text`, `match_case`, `whole_word`, and `lua` fields to set the\nsearch text and option flags, respectively.\n@param utf8_dir UTF-8 encoded directory name. If `nil`, the user is prompted\nfor one. +find_incremental gui.find.find_incremental()\nBegins an incremental find using the command entry.\nOnly the `match_case` find option is recognized. Normal command entry\nfunctionality will be unavailable until the search is finished by pressing\n`Esc` (`⎋` on Mac OSX | `Esc` in ncurses). find_label_text gui.find.find_label_text (string, Write-only)\nThe text of the 'Find' label.\nThis is primarily used for localization. -find_next gui.find.find_next()\nMimicks a press of the 'Find Next' button in the Find box. +find_next gui.find.find_next()\nMimicks a press of the 'Find Next' button. find_next_button_text gui.find.find_next_button_text (string, Write-only)\nThe text of the 'Find Next' button.\nThis is primarily used for localization. -find_prev gui.find.find_prev()\nMimicks a press of the 'Find Prev' button in the Find box. +find_prev gui.find.find_prev()\nMimicks a press of the 'Find Prev' button. find_prev_button_text gui.find.find_prev_button_text (string, Write-only)\nThe text of the 'Find Prev' button.\nThis is primarily used for localization. first_visible_line buffer.first_visible_line (number)\nThe display line at the top of the display. float lexer.float\nMatches a floating point number. @@ -1030,7 +1034,7 @@ flush io.flush()\nEquivalent to `io.output():flush()`. fmod math.fmod(x, y)\nReturns the remainder of the division of `x` by `y` that rounds the\nquotient towards zero. focus buffer.focus (bool)\nThe internal focus flag. focus gui.command_entry.focus()\nFocuses the command entry. -focus gui.find.focus()\nDisplays and focuses the find/replace dialog. +focus gui.find.focus()\nDisplays and focuses the Find & Replace pane. fold lexer.fold(text, start_pos, start_line, start_level)\nFolds the given text.\nCalled by LexLPeg.cxx; do not call from Lua.\nIf the current lexer has no _fold function, folding by indentation is\nperformed if the 'fold.by.indentation' property is set.\n@param text The document text to fold.\n@param start_pos The position in the document text starts at.\n@param start_line The line number text starts on.\n@param start_level The fold level text starts on.\n@return Table of fold levels. fold_expanded buffer.fold_expanded (bool)\nExpanded state of a header line. fold_flags buffer.fold_flags (number)\nThe style options for folding.\nBits set in flags determine where folding lines are drawn:\n\n* `_SCINTILLA.constants.SC_FOLDFLAG_LINEBEFORE_EXPANDED` (2)\n Draw above if expanded.\n* `_SCINTILLA.constants.SC_FOLDFLAG_LINEBEFORE_CONTRACTED` (4)\n Draw above if not expanded.\n* `_SCINTILLA.constants.SC_FOLDFLAG_LINEAFTER_EXPANDED` (8)\n Draw below if expanded.\n* `_SCINTILLA.constants.SC_FOLDFLAG_LINEAFTER_CONTRACTED` (16)\n Draw below if not expanded. @@ -1039,9 +1043,9 @@ fold_line_comments lexer.fold_line_comments(prefix)\nReturns a fold function tha fold_parent buffer.fold_parent (table, Read-only)\nTable of parent line numbers for child lines starting from zero.\n`-1` means no line was found. font_quality buffer.font_quality (number)\n(Windows only)\n The quality level for text.\n\n * `_SCINTILLA.constants.SC_EFF_QUALITY_DEFAULt` (0).\n * `_SCINTILLA.constants.SC_EFF_QUALITY_NON_ANTIALIASED` (1).\n * `_SCINTILLA.constants.SC_EFF_QUALITY_ANTIALIASED` (2).\n * `_SCINTILLA.constants.SC_EFF_QUALITY_LCD_OPTIMIZED` (3). form_feed buffer.form_feed(buffer)\nInsert a Form Feed character.\n@param buffer The global buffer. -format string.format(formatstring, ···)\nReturns a formatted version of its variable number of arguments following the\ndescription given in its first argument (which must be a string). The format\nstring follows the same rules as the C function `sprintf`. The only\ndifferences are that the options/modifiers `*`, `h`, `L`, `l`, `n`, and `p`\nare not supported and that there is an extra option, `q`. The `q` option\nformats a string between double quotes, using escape sequences when necessary\nto ensure that it can safely be read back by the Lua interpreter. For\ninstance, the call\n\n string.format('%q', 'a string with "quotes" and \\n new line')\n\nmay produce the string:\n\n "a string with \"quotes\" and \\n new line"\n\nOptions `A` and `a` (when available), `E`, `e`, `f`, `G`, and `g` all expect\na number as argument. Options `c`, `d`, `i`, `o`, `u`, `X`, and `x` also\nexpect a number, but the range of that number may be limited by the\nunderlying C implementation. For options `o`, `u`, `X`, and `x`, the number\ncannot be negative. Option `q` expects a string; option `s` expects a string\nwithout embedded zeros. If the argument to option `s` is not a string, it is\nconverted to one following the same rules of `tostring`. +format string.format(formatstring, ···)\nReturns a formatted version of its variable number of arguments following the\ndescription given in its first argument (which must be a string). The format\nstring follows the same rules as the C function `sprintf`. The only\ndifferences are that the options/modifiers `*`, `h`, `L`, `l`, `n`, and `p`\nare not supported and that there is an extra option, `q`. The `q` option\nformats a string between double quotes, using escape sequences when necessary\nto ensure that it can safely be read back by the Lua interpreter. For\ninstance, the call\n\n string.format('%q', 'a string with "quotes" and \n new line')\n\nmay produce the string:\n\n "a string with \"quotes\" and \\n new line"\n\nOptions `A` and `a` (when available), `E`, `e`, `f`, `G`, and `g` all expect\na number as argument. Options `c`, `d`, `i`, `o`, `u`, `X`, and `x` also\nexpect a number, but the range of that number may be limited by the\nunderlying C implementation. For options `o`, `u`, `X`, and `x`, the number\ncannot be negative. Option `q` expects a string; option `s` expects a string\nwithout embedded zeros. If the argument to option `s` is not a string, it is\nconverted to one following the same rules of `tostring`. frexp math.frexp(x)\nReturns `m` and `e` such that 'x = m2^e', `e` is an integer and the\nabsolute value of `m` is in the range *[0.5, 1)* (or zero when `x` is zero). -functions _SCINTILLA.functions (table)\nScintilla functions. +functions _SCINTILLA.functions (table)\nScintilla functions.\nEach key is a Scintilla function name with a table value containing its ID,\nreturn type, wParam type, and lParam type. Types are as follows:\n\n + `0`: Void.\n + `1`: Integer.\n + `2`: Length of the given lParam string.\n + `3`: Integer position.\n + `4`: Colour in `0xBBGGRR` format.\n + `5`: Boolean `true` or `false`.\n + `6`: Bitmask of Scintilla key modifiers and a key value.\n + `7`: String parameter.\n + `8`: String return value. gap_position buffer.gap_position (number, Read-only)\nA position which, to avoid performance costs, should not be within the\nrange of a call to `buffer:get_range_pointer()`. get_apidoc _M.textadept.adeptsense.get_apidoc(sense, symbol)\nReturns a list of apidocs for the given symbol.\nIf there are multiple apidocs, the index of one to display is the value of\nthe `pos` key in the returned list.\n@param sense The Adeptsense returned by `adeptsense.new()`.\n@param symbol The symbol to get apidocs for.\n@return apidoc_list or `nil` get_class _M.textadept.adeptsense.get_class(sense, symbol)\nReturns the class name for a given symbol.\nIf the symbol is `sense.syntax.self` and a class definition using the\n`sense.syntax.class_definition` keyword is found, that class is returned.\nOtherwise the buffer is searched backwards for a type declaration of the\nsymbol according to the patterns in `sense.syntax.type_declarations`.\n@param sense The Adeptsense returned by `adeptsense.new()`.\n@param symbol The symbol to get the class of.\n@return class or `nil`\n@see syntax @@ -1059,7 +1063,7 @@ get_line_sel_start_position buffer.get_line_sel_start_position(buffer, line)\nRe get_property lexer.get_property(key, default)\nReturns an integer property value for a given key.\n@param key The property key.\n@param default Optional integer value to return if key is not set. get_range_pointer buffer.get_range_pointer(buffer, position, range_length)\nReturn a read-only pointer to a range of characters in the document.\nMay move the gap so that the range is contiguous, but will only move up to\nrange_length bytes.\nThe gap is not moved unless it is within the requested range so this call can\nbe faster than `SCI_GETCHARACTERPOINTER`. This can be used by application\ncode that is able to act on blocks of text or ranges of lines. get_sel_text buffer.get_sel_text(buffer)\nRetrieve the selected text.\nAlso returns the length of the text.\n@param buffer The global buffer.\n@return string, number -get_split_table gui.get_split_table()\nGets the current split view structure.\n@return table of split views. Each split view entry is a table with 4\n fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either\n nested split view entries or the views themselves; `vertical` is a flag\n indicating if the split is vertical or not; and `size` is the integer\n position of the split resizer. +get_split_table gui.get_split_table()\nGets the current split view structure.\nThis is primarily used in session saving.\n@return table of split views. Each split view entry is a table with 4\n fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either\n nested split view entries or the views themselves; `vertical` is a flag\n indicating if the split is vertical or not; and `size` is the integer\n position of the split resizer. get_style_at lexer.get_style_at(pos)\nReturns the string style name and style number at a given position.\n@param pos The position to get the style for. get_style_name buffer.get_style_name(buffer, style_num)\nReturns the name of the style associated with a style number.\n@param buffer The global buffer.\n@param style_num A style number from `0` to `255`.\n@see buffer.style_at get_symbol _M.textadept.adeptsense.get_symbol(sense)\nReturns a full symbol (if any) and current symbol part (if any) behind the\ncaret.\nFor example: `buffer.cur` would return `'buffer'` and `'cur'`.\n@param sense The Adeptsense returned by `adeptsense.new()`.\n@return symbol or `''`\n@return part or `''` @@ -1075,24 +1079,22 @@ getupvalue debug.getupvalue(f, up)\nThis function returns the name and the value getuservalue debug.getuservalue(u)\nReturns the Lua value associated to `u`. If `u` is not a userdata, returns\nnil. gmatch string.gmatch(s, pattern)\nReturns an iterator function that, each time it is called, returns the\nnext captures from `pattern` over the string `s`. If `pattern` specifies no\ncaptures, then the whole match is produced in each call.\n\nAs an example, the following loop will iterate over all the words from string\n`s`, printing one per line:\n\n s = "hello world from Lua"\n for w in string.gmatch(s, "%a+") do\n print(w)\n end\n\nThe next example collects all pairs `key=value` from the given string into a\ntable:\n\n t = {}\n s = "from=world, to=Lua"\n for k, v in string.gmatch(s, "(%w+)=(%w+)") do\n t[k] = v\n end\n\nFor this function, a caret '`^`' at the start of a pattern does not work as\nan anchor, as this would prevent the iteration. goto_bookmark _M.textadept.bookmarks.goto_bookmark()\nGoes to selected bookmark from a filtered list. -goto_buffer view:goto_buffer(n, relative)\nGoes to the specified buffer in the indexed view.\nGenerates `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events.\n@param n A relative or absolute buffer index. An absolute index of `-1` goes\n to the last buffer.\n@param relative Flag indicating if `n` is a relative index or not. The\n default value is `false`. -goto_ctag _M.textadept.adeptsense.goto_ctag(sense, k, title)\nDisplays a filteredlist of all known symbols of the given kind (classes,\nfunctions, fields, etc.) and jumps to the source of the selected one.\n@param sense The Adeptsense returned by `adeptsense.new()`.\n@param k The ctag character kind (e.g. `'f'` for a Lua function).\n@param title The title for the filteredlist dialog. -goto_error _M.textadept.run.goto_error(pos, line_num)\nGoes to the line in the file an error occured at and displays a calltip with\nthe error message.\nThis is typically called when the user double-clicks an error message,\n@param pos The position of the caret.\n@param line_num The line the error occurs on.\n@see error_detail +goto_buffer view.goto_buffer(view, n, relative)\nGoes to the specified buffer in the given view.\nEmits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events.\n@param view The view to switch buffers in.\n@param n A relative or absolute buffer index in `_G._BUFFERS`. An absolute\n index of `-1` goes to the last buffer.\n@param relative Flag indicating if `n` is a relative index or not. The\n default value is `false`.\n@see _G._G._BUFFERS\n@see events.BUFFER_BEFORE_SWITCH\n@see events.BUFFER_AFTER_SWITCH +goto_ctag _M.textadept.adeptsense.goto_ctag(sense, k, title)\nDisplays a filtered list dialog of all known symbols of the given kind\n(classes, functions, fields, etc.) and jumps to the source of the selected\none.\n@param sense The Adeptsense returned by `adeptsense.new()`.\n@param k The ctag character kind (e.g. `'f'` for a Lua function).\n@param title The title for the filtered list dialog. +goto_error _M.textadept.run.goto_error(pos, line_num)\nGoes to the line in the file an error occured at based on the error message\nat the given position and displays an annotation with the error message.\nThis is typically called by an event handler for when the user double-clicks\non an error message.\n@param pos The position of the caret.\n@param line_num The line number the caret is on with the error message.\n@see error_detail goto_file gui.goto_file(filename, split, preferred_view, sloppy)\nGoes to the buffer with the given filename.\nIf the desired buffer is open in a view, goes to that view. Otherwise, opens\nthe buffer in either the `preferred_view` if given, the first view that is\nnot the current one, a split view if `split` is `true`, or the current view.\n@param filename The filename of the buffer to go to.\n@param split If there is only one view, split it and open the buffer in the\n other view.\n@param preferred_view When multiple views exist and the desired buffer is not\n open in any of them, open it in this one.\n@param sloppy Flag indicating whether or not to not match `filename` to\n `buffer.filename` exactly. When `true`, matches `filename` to only the last\n part of `buffer.filename` This is useful for run and compile commands which\n output relative filenames and paths instead of full ones and it is likely\n that the file in question is already open. The default value is `false`. -goto_file_in_list gui.find.goto_file_in_list(next)\nGoes to the next or previous file found relative to the file\non the current line.\n@param next Flag indicating whether or not to go to the next file. +goto_file_in_list gui.find.goto_file_in_list(next)\nGoes to the next or previous file found relative to the file on the current\nline in the results list.\n@param next Flag indicating whether or not to go to the next file. goto_line _M.textadept.editing.goto_line(line)\nGoes to the requested line.\n@param line Optional line number to go to. If `nil`, the user is prompted for\n one. goto_line buffer.goto_line(buffer, line)\nSet caret to start of a line and ensure it is visible.\n@param buffer The global buffer.\n@param line The line number. goto_next _M.textadept.bookmarks.goto_next()\nGoes to the next bookmark in the current buffer. goto_pos buffer.goto_pos(buffer, pos)\nSet caret to a position and ensure it is visible.\nThe anchor position is set the same as the current position.\n@param buffer The global buffer.\n@param pos The position. goto_prev _M.textadept.bookmarks.goto_prev()\nGoes to the previous bookmark in the current buffer. -goto_required _M.php.goto_required()\nDetermines the PHP file being 'require'd or 'include'd, and opens it in\nTextadept. -goto_required _M.ruby.goto_required()\nDetermine the Ruby file being 'require'd, and search through the RUBYPATH\nfor that file and open it in Textadept. -goto_view gui.goto_view(n, relative)\nGoes to the specified view.\nGenerates `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.\n@param n A relative or absolute view index.\n@param relative Flag indicating if n is a relative index or not. The default\n value is `false`. +goto_view gui.goto_view(n, relative)\nGoes to the specified view.\nEmits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.\n@param n A relative or absolute view index in `_G._VIEWS`.\n@param relative Flag indicating if n is a relative index or not. The default\n value is `false`.\n@see _G._G._VIEWS\n@see events.VIEW_BEFORE_SWITCH\n@see events.VIEW_AFTER_SWITCH grab_focus buffer.grab_focus(buffer)\nSet the focus to this view.\n@param buffer The global buffer. graph lexer.graph\nMatches any graphical character (`!` to `~`). -grow_selection _M.textadept.editing.grow_selection(amount)\nGrows the selection by a character amount on either end.\n@param amount The amount to grow the selection on either end. +grow_selection _M.textadept.editing.grow_selection(amount)\nGrows the selection by the given number of characters on either end.\n@param amount The number of characters to grow the selection by on either\n end. gsub string.gsub(s, pattern, repl [, n])\nReturns a copy of `s` in which all (or the first `n`, if given)\noccurrences of the `pattern` have been replaced by a replacement string\nspecified by `repl`, which can be a string, a table, or a function. `gsub`\nalso returns, as its second value, the total number of matches that occurred.\nThe name `gsub` comes from "Global SUBstitution".\n\nIf `repl` is a string, then its value is used for replacement. The character\n`%` works as an escape character: any sequence in `repl` of the form `%d`,\nwith `d` between 1 and 9, stands for the value of the `d`-th captured\nsubstring (see below). The sequence `%0` stands for the whole match. The\nsequence `%%` stands for a single `%`.\n\nIf `repl` is a table, then the table is queried for every match, using\nthe first capture as the key; if the pattern specifies no captures, then\nthe whole match is used as the key.\nIf `repl` is a function, then this function is called every time a match\noccurs, with all captured substrings passed as arguments, in order; if\nthe pattern specifies no captures, then the whole match is passed as a\nsole argument.\n\nIf the value returned by the table query or by the function call is a\nstring or a number, then it is used as the replacement string; otherwise,\nif it is false or nil, then there is no replacement (that is, the original\nmatch is kept in the string).\n\nHere are some examples:\n\n x = string.gsub("hello world", "(%w+)", "%1 %1")\n --> x="hello hello world world"\n x = string.gsub("hello world", "%w+", "%0 %0", 1)\n --> x="hello hello world"\n x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")\n --> x="world hello Lua from"\n x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)\n --> x="home = /home/roberto, user = roberto"\n x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)\n return load(s)()\n end)\n --> x="4+5 = 9"\n local t = {name="lua", version="5.2"}\n x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)\n --> x="lua-5.2.tar.gz" -gui _G.gui (module)\nThe core gui table. +gui _G.gui (module)\nUtilities for Textadept's user interface. h_scroll_bar buffer.h_scroll_bar (bool)\nWhether the horizontal scroll bar is visible.\nSet to `false` to never see it and `true` to enable it again. The default\nstate is to display it when needed. handle_clear _M.textadept.adeptsense.handle_clear(sense)\nCalled when clearing an Adeptsense.\nThis function should be replaced with your own if you have any persistant\nobjects that need to be deleted.\n@param sense The Adeptsense returned by `adeptsense.new()`. handle_ctag _M.textadept.adeptsense.handle_ctag(sense, tag_name, file_name, ex_cmd, ext_fields)\nCalled by `load_ctags()` when a ctag kind is not recognized.\nThis method should be replaced with your own that is specific to the\nlanguage.\n@param sense The Adeptsense returned by `adeptsense.new()`.\n@param tag_name The tag name.\n@param file_name The name of the file the tag belongs to.\n@param ex_cmd The `ex_cmd` returned by ctags.\n@param ext_fields The `ext_fields` returned by ctags. @@ -1101,7 +1103,7 @@ hex_num lexer.hex_num\nMatches a hexadecimal number. hide_lines buffer.hide_lines(buffer, start_line, end_line)\nMake a range of lines invisible.\nThis has no effect on fold levels or fold flags. `start_line` can not be\nhidden.\n@param buffer The global buffer.\n@param start_line The start line.\n@param end_line The end line. hide_selection buffer.hide_selection(buffer, normal)\nDraw the selection in normal style or with selection highlighted.\n@param buffer The global buffer.\n@param normal Draw normal selection. highlight_guide buffer.highlight_guide (number)\nThe highlighted indentation guide column.\nSet to `0` to cancel this highlight. -highlight_word _M.textadept.editing.highlight_word()\nHighlights all occurances of the word under the caret and adds markers to the\nlines they are on. +highlight_word _M.textadept.editing.highlight_word()\nHighlights all occurances of either the selected text or the word under the\ncaret and adds markers to the lines they are on.\n@see buffer.word_chars home buffer.home(buffer)\nMove caret to first position on line.\n@param buffer The global buffer. home_display buffer.home_display(buffer)\nMove caret to first position on display line.\n@param buffer The global buffer. home_display_extend buffer.home_display_extend(buffer)\nMove caret to first position on display line extending selection to new caret\nposition.\n@param buffer The global buffer. @@ -1112,9 +1114,9 @@ home_wrap_extend buffer.home_wrap_extend(buffer)\nLike `buffer:home_wrap()` but hotspot_active_underline buffer.hotspot_active_underline (bool)\nWhether active hotspots are underlined. hotspot_single_line buffer.hotspot_single_line (bool)\nWhether hotspots are limited to single line so hotspots on two lines do not\nmerge. huge math.huge (number)\nThe value `HUGE_VAL`, a value larger than or equal to any other numerical\nvalue. -hypertext _G.keys.hypertext (table)\nContainer for HTML-specific key commands. +hypertext _G.keys.hypertext (table)\nContainer for HTML-specific key bindings. hypertext _G.snippets.hypertext (table)\nContainer for HTML-specific snippets. -hypertext _M.hypertext (module)\nThe hypertext module.\nIt provides utilities for editing HTML code.\nUser tags are loaded from `_USERHOME/modules/hypertext/tags` and user apis\nare loaded from `_USERHOME/modules/hypertext/api`. +hypertext _M.hypertext (module)\nThe hypertext module.\nIt provides utilities for editing HTML code. iconv string.iconv(text, to, from)\nConverts a string from one character set to another using iconv.\nValid character sets are GNU iconv's character sets.\n@param text The text to convert.\n@param to The character set to convert to.\n@param from The character set to convert from. in_files gui.find.in_files (bool)\nSearch for the text in a list of files. in_files_label_text gui.find.in_files_label_text (string, Write-only)\nThe text of the 'In files' label.\nThis is primarily used for localization. @@ -1140,12 +1142,12 @@ insert_text buffer.insert_text(buffer, pos, text)\nInsert string at a position.\ integer lexer.integer\nMatches a decimal, hexadecimal, or octal number. io _G.io (module)\nLua io module. ipairs _G.ipairs(t)\nIf `t` has a metamethod `__ipairs`, calls it with `t` as argument and returns\nthe first three results from the call.\n\nOtherwise, returns three values: an iterator function, the table `t`, and 0,\nso that the construction\n\n for i,v in ipairs(t) do *body* end\n\nwill iterate over the pairs (`1,t[1]`), (`2,t[2]`), ..., up to the\nfirst integer key absent from the table. -java _G.keys.java (table)\nContainer for Java-specific key commands. +java _G.keys.java (table)\nContainer for Java-specific key bindings. java _G.snippets.java (table)\nContainer for Java-specific snippets. -java _M.java (module)\nThe java module.\nIt provides utilities for editing Java code.\nUser tags are loaded from `_USERHOME/modules/java/tags` and user apis are\nloaded from `_USERHOME/modules/java/api`. -join_lines _M.textadept.editing.join_lines()\nJoins the currently selected lines.\nIf no lines are selected, joins the current line with the line below. -keys _G.keys (module)\nManages key commands in Textadept. -keys _M.textadept.keys (module)\nDefines key commands for Textadept.\nThis set of key commands is pretty standard among other text editors.\nThis module, should be `require`d last, but before `_M.textadept.menu`. +java _M.java (module)\nThe java module.\nIt provides utilities for editing Java code. +join_lines _M.textadept.editing.join_lines()\nJoins the currently selected lines.\nAs long as any part of a line is selected, the entire line is eligible for\njoining. If no lines are selected, joins the current line with the line\nbelow. +keys _G.keys (module)\nManages key bindings in Textadept. +keys _M.textadept.keys (module)\nDefines key commands for Textadept.\nThis set of key commands is pretty standard among other text editors.\nThis module should be `require`d last, but before `_M.textadept.menu`. keys_unicode buffer.keys_unicode (bool)\nInterpret keyboard input as Unicode. last_char_includes lexer.last_char_includes(s)\nCreates an LPeg pattern that matches any previous non-whitespace character\nin the given set.\n@param s String character set like one passed to `lpeg.S()`.\n@usage local regex = l.last_char_includes('+-*!%^&|=,([{') *\n l.delimited_range('/', '\\') layout_cache buffer.layout_cache (number)\nThe degree of caching of layout information.\n\n* `_SCINTILLA.constants.SC_CACHE_NONE` (0)\n No lines are cached.\n* `_SCINTILLA.constants.SC_CACHE_CARET` (1)\n The line containing the text caret.\n This is the default.\n* `_SCINTILLA.constants.SC_CACHE_PAGE` (2)\n Visible lines plus the line containing the caret.\n* `_SCINTILLA.constants.SC_CACHE_DOCUMENT` (3)\n All lines in the document. @@ -1197,7 +1199,7 @@ load _G.load(ld [, source [, mode [, env]]])\nLoads a chunk.\n\nIf `ld` is a str load _M.textadept.session.load(filename)\nLoads a Textadept session file.\nTextadept restores split views, opened buffers, cursor information, and\nrecent files.\n@param filename The absolute path to the session file to load. If `nil`, the\n user is prompted for one.\n@usage _M.textadept.session.load(filename)\n@return `true` if the session file was opened and read; `false` otherwise.\n@see DEFAULT_SESSION load lexer.load(lexer_name)\nInitializes the specified lexer.\n@param lexer_name The name of the lexing language. load_ctags _M.textadept.adeptsense.load_ctags(sense, tag_file, nolocations)\nLoads the given ctags file for autocompletion.\nIt is recommended to pass `-n` to ctags in order to use line numbers instead\nof text patterns to locate tags. This will greatly reduce memory usage for a\nlarge number of symbols if `nolocations` is not `true`.\n@param sense The Adeptsense returned by `adeptsense.new()`.\n@param tag_file The path of the ctags file to load.\n@param nolocations If `true`, does not store the locations of the tags for\n use by `goto_ctag()`. The default value is `false`. -load_project _M.rails.load_project(utf8_dir)\nSets keys.al.o to snapopen a Rails project.\nIf not directory is provided, the user is prompted for one.\n@param utf8_dir The UTF-8 Rails project directory. +load_project _M.rails.load_project(utf8_dir)\nOpens a Rails project for snapopen.\nIf not directory is provided, the user is prompted for one.\n@param utf8_dir The UTF-8 Rails project directory. loaded package.loaded (table)\nA table used by `require` to control which modules are already loaded. When\nyou require a module `modname` and `package.loaded[modname]` is not false,\n`require` simply returns the value stored there.\nThis variable is only a reference to the real table; assignments to this\nvariable do not change the table used by `require`. loadfile _G.loadfile([filename [, mode [, env]]])\nSimilar to `load`, but gets the chunk from file `filename` or from the\nstandard input, if no file name is given. loadlib package.loadlib(libname, funcname)\nDynamically links the host program with the C library `libname`.\n\nIf `funcname` is "`*`", then it only links with the library, making the\nsymbols exported by the library available to other dynamically linked\nlibraries. Otherwise, it looks for a function `funcname` inside the library\nand returns this function as a C function. (So, `funcname` must follow the\nprototype `lua_CFunction`).\n\nThis is a low-level function. It completely bypasses the package and module\nsystem. Unlike `require`, it does not perform any path searching and does\nnot automatically adds extensions. `libname` must be the complete file name\nof the C library, including if necessary a path and an extension. `funcname`\nmust be the exact name exported by the C library (which may depend on the\nC compiler and linker used).\n\nThis function is not supported by Standard C. As such, it is only available\non some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix\nsystems that support the `dlfcn` standard). @@ -1212,9 +1214,9 @@ lower_case buffer.lower_case(buffer)\nTransform the selection to lower case.\n@p lpeg _G.lpeg (module)\nLua lpeg module. lrotate bit32.lrotate(x, disp)\nReturns the number `x` rotated `disp` bits to the left. The number `disp` may\nbe any representable integer.\n\nFor any valid displacement, the following identity holds:\n\n assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))\n\nIn particular, negative displacements rotate to the right. lshift bit32.lshift(x, disp)\nReturns the number `x` shifted `disp` bits to the left. The number `disp` may\nbe any representable integer. Negative displacements shift to the right. In\nany direction, vacant bits are filled with zeros. In particular,\ndisplacements with absolute values higher than 31 result in zero (all bits\nare shifted out).\n\nFor positive displacements, the following equality holds:\n\n assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32) -lua _G.keys.lua (table)\nContainer for Lua-specific key commands. +lua _G.keys.lua (table)\nContainer for Lua-specific key bindings. lua _G.snippets.lua (table)\nContainer for Lua-specific snippets. -lua _M.lua (module)\nThe lua module.\nIt provides utilities for editing Lua code.\nUser tags are loaded from `_USERHOME/modules/lua/tags` and user apis are\nloaded from `_USERHOME/modules/lua/api`. +lua _M.lua (module)\nThe lua module.\nIt provides utilities for editing Lua code. lua gui.find.lua (bool)\nThe search text is interpreted as a Lua pattern. lua_pattern_label_text gui.find.lua_pattern_label_text (string, Write-only)\nThe text of the 'Lua pattern' label.\nThis is primarily used for localization. main_selection buffer.main_selection (number)\nThe main selection.\nThe main selection may be displayed in different colors or with a\ndifferently styled caret. Only an already existing selection can be made\nmain. @@ -1257,10 +1259,10 @@ math _G.math (module)\nLua math module. max math.max(x, ···)\nReturns the maximum value among its arguments. max_line_state buffer.max_line_state (number, Read-only)\nThe last line number that has line state. menu _M.textadept.menu (module)\nProvides dynamic menus for Textadept.\nThis module should be `require`d last, after `_M.textadept.keys` since it\nlooks up defined key commands to show them in menus. -menu gui.menu(menu_table)\nCreates a menu, returning the userdata.\n@param menu_table A table defining the menu. It is an ordered list of tables\n with a string menu item, integer menu ID, and optional GDK keycode and\n modifier mask. The latter two are used to display key shortcuts in the\n menu. `_` characters are treated as a menu mnemonics. If the menu item is\n empty, a menu separator item is created. Submenus are just nested\n menu-structure tables. Their title text is defined with a `title` key.\n@usage gui.menu{ { '_New', 1 }, { '_Open', 2 }, { '' }, { '_Quit', 4 } }\n@usage gui.menu{ { '_New', 1, keys.get_gdk_key('cn') } }\n@see keys.get_gdk_key -menubar _M.textadept.menu.menubar (table)\nContains the main menubar. -menubar gui.menubar (table)\nA table of menus defining a menubar. (Write-only) -mime_types _M.textadept.mime_types (module)\nHandles file-specific settings. +menu gui.menu(menu_table)\nCreates a menu, returning the userdata.\nThis is a low-level function. You probably want to use the higher-level\n`_M.textadept.menu.set_menubar()` or `_M.textadept.menu.set_contextmenu()`\nfunctions. Emits a `MENU_CLICKED` event when a menu item is selected.\n@param menu_table A table defining the menu. It is an ordered list of tables\n with a string menu item, integer menu ID, and optional GDK keycode and\n modifier mask. The latter two are used to display key shortcuts in the\n menu. `_` characters are treated as a menu mnemonics. If the menu item is\n empty, a menu separator item is created. Submenus are just nested\n menu-structure tables. Their title text is defined with a `title` key.\n@usage gui.menu{ { '_New', 1 }, { '_Open', 2 }, { '' }, { '_Quit', 4 } }\n@usage gui.menu{ { '_New', 1, string.byte('n'), 4 } } -- 'Ctrl+N'\n@see events.MENU_CLICKED\n@see _M.textadept.menu.set_menubar\n@see _M.textadept.menu.set_contextmenu +menubar _M.textadept.menu.menubar (table)\nContains the main menubar.\n@see set_menubar +menubar gui.menubar (table)\nA table of menus defining a menubar. (Write-only)\n@see _M.textadept.menu.set_menubar +mime_types _M.textadept.mime_types (module)\nHandles file type detection. min math.min(x, ···)\nReturns the minimum value among its arguments. mkdir lfs.mkdir(dirname)\nCreates a new directory. The argument is the name of the new directory.\n\nReturns true if the operation was successful; in case of error, it returns\nnil plus an error string. modf math.modf(x)\nReturns two numbers, the integral part of `x` and the fractional part of\n`x`. @@ -1274,19 +1276,19 @@ multi_paste buffer.multi_paste (bool)\nThe effect of pasting when there are mult multiple_selection buffer.multiple_selection (bool)\nWhether multiple selections can be made.\nWhen multiple selection is disabled, it is not possible to select multiple\nranges by holding down the Ctrl key while dragging with the mouse. nested_pair lexer.nested_pair(start_chars, end_chars, end_optional)\nSimilar to `delimited_range()`, but allows for multi-character delimitters.\nThis is useful for lexers with tokens such as nested block comments. With\nsingle-character delimiters, this function is identical to\n`delimited_range(start_chars..end_chars, nil, end_optional, true)`.\n@param start_chars The string starting a nested sequence.\n@param end_chars The string ending a nested sequence.\n@param end_optional Optional flag indicating whether or not an ending\n delimiter is optional or not. If true, the range begun by the start\n delimiter matches until an end delimiter or the end of the input is\n reached.\n@usage local nested_comment = l.nested_pair('/*', '*/', true) new _M.textadept.adeptsense.new(lang)\nCreates a new Adeptsense for the given lexer language.\nOnly one sense can exist per language.\n@param lang The lexer language to create an Adeptsense for.\n@usage local lua_sense = _M.textadept.adeptsense.new('lua')\n@return adeptsense -new_buffer _G.new_buffer()\nCreates a new buffer.\nGenerates a `BUFFER_NEW` event.\n@return the new buffer. +new_buffer _G.new_buffer()\nCreates a new buffer.\nEmits a `BUFFER_NEW` event.\n@return the new buffer.\n@see events.BUFFER_NEW new_line buffer.new_line(buffer)\nInsert a new line, may use a CRLF, CR or LF depending on EOL mode.\n@param buffer The global buffer. newline lexer.newline\nMatches any newline characters. next _G.next(table [, index])\nAllows a program to traverse all fields of a table. Its first argument is\na table and its second argument is an index in this table. `next` returns\nthe next index of the table and its associated value. When called with nil\nas its second argument, `next` returns an initial index and its associated\nvalue. When called with the last index, or with nil in an empty table, `next`\nreturns nil. If the second argument is absent, then it is interpreted as\nnil. In particular, you can use `next(t)` to check whether a table is empty.\n\nThe order in which the indices are enumerated is not specified, *even for\nnumeric indices*. (To traverse a table in numeric order, use a numerical\n`for`.)\n\nThe behavior of `next` is undefined if, during the traversal, you assign any\nvalue to a non-existent field in the table. You may however modify existing\nfields. In particular, you may clear existing fields. next_indic_number _SCINTILLA.next_indic_number()\nReturns a unique indicator number.\nUse this function for custom indicators in order to prevent clashes with\nidentifiers of other custom indicators.\n@usage local indic_num = _SCINTILLA.next_indic_number()\n@see buffer.indic_style next_marker_number _SCINTILLA.next_marker_number()\nReturns a unique marker number.\nUse this function for custom markers in order to prevent clashes with\nidentifiers of other custom markers.\n@usage local marknum = _SCINTILLA.next_marker_number()\n@see buffer.marker_define -next_user_list_type _SCINTILLA.next_user_list_type()\nReturns a unique user list type.\nUse this function for custom user lists in order to prevent clashes with\ntype identifiers of other custom user lists.\n@usage local list_type = _SCINTILLA.next_user_list_type()\n@see buffer.user_list_show +next_user_list_type _SCINTILLA.next_user_list_type()\nReturns a unique user list type.\nUse this function for custom user lists in order to prevent clashes with\nlist identifiers of other custom user lists.\n@usage local list_type = _SCINTILLA.next_user_list_type()\n@see buffer.user_list_show nonnewline lexer.nonnewline\nMatches any non-newline character. nonnewline_esc lexer.nonnewline_esc\nMatches any non-newline character excluding newlines escaped with `\\`. oct_num lexer.oct_num\nMatches an octal number. -open _M.textadept.snapopen.open(utf8_paths, filter, exclude_PATHS, exclude_FILTER, depth)\nQuickly open a file in set of directories.\n@param utf8_paths A UTF-8 string directory path or table of UTF-8 directory\n paths to search.\n@param filter A filter for files and folders to exclude. The filter may be\n a string or table. Each filter is a Lua pattern. Any files matching a\n filter are excluded. Prefix a pattern with `!` to exclude any files that\n do not match the filter. File extensions can be more efficiently excluded\n by adding the extension text to a table assigned to an `extensions` key in\n the filter table instead of using individual filters. Directories can be\n excluded by adding filters to a table assigned to a `folders` key in the\n filter table. All strings should be UTF-8 encoded.\n@param exclude_PATHS Flag indicating whether or not to exclude `PATHS` in the\n search. The default value is `false`.\n@param exclude_FILTER Flag indicating whether or not to exclude `FILTER` from\n `filter` in the search. If false, adds `FILTER` to the given `filter`.\n The default value is `false`.\n@param depth Number of directories to recurse into for finding files.\n The default value is `DEFAULT_DEPTH`.\n@usage _M.textadept.snapopen.open()\n@usage _M.textadept.snapopen.open(buffer.filename:match('^.+/'), nil, true)\n@usage _M.textadept.snapopen.open(nil, '!%.lua$')\n@usage _M.textadept.snapopen.open(nil, { folders = { '%.hg' } }) +open _M.textadept.snapopen.open(utf8_paths, filter, exclude_PATHS, exclude_FILTER, depth)\nQuickly open files in set of directories using a filtered list dialog.\nThe number of files in the list is capped at `MAX`.\n@param utf8_paths A UTF-8 string directory path or table of UTF-8 directory\n paths to search.\n@param filter A filter for files and folders to exclude. The filter may be\n a string or table. Each filter is a Lua pattern. Any files matching a\n filter are excluded. Prefix a pattern with `!` to exclude any files that\n do not match a filter. File extensions can be more efficiently excluded by\n adding the extension text to a table assigned to an `extensions` key in the\n filter table instead of using individual filters. Directories can be\n excluded by adding filters to a table assigned to a `folders` key in the\n filter table. All strings should be UTF-8 encoded.\n@param exclude_PATHS Flag indicating whether or not to exclude `PATHS` in the\n search. The default value is `false`.\n@param exclude_FILTER Flag indicating whether or not to exclude `FILTER` from\n `filter` in the search. If false, adds `FILTER` to the given `filter`.\n The default value is `false`.\n@param depth Number of directories to recurse into for finding files.\n The default value is `DEFAULT_DEPTH`.\n@usage _M.textadept.snapopen.open() -- list all files in PATHS\n@usage _M.textadept.snapopen.open(buffer.filename:match('^.+/'), nil, true)\n -- list all files in the current file's directory\n@usage _M.textadept.snapopen.open(nil, '!%.lua$') -- list all Lua files in\n PATHS\n@usage _M.textadept.snapopen.open('/project', { folders = { 'secret' } },\n true) -- list all project files except those in a secret folder\n@see PATHS\n@see FILTER\n@see DEFAULT_DEPTH\n@see MAX open io.open(filename [, mode])\nThis function opens a file, in the mode specified in the string `mode`. It\nreturns a new file handle, or, in case of errors, nil plus an error message.\n\nThe `mode` string can be any of the following:\n "r": read mode (the default);\n "w": write mode;\n "a": append mode;\n "r+": update mode, all previous data is preserved;\n "w+": update mode, all previous data is erased;\n "a+": append update mode, previous data is preserved, writing is only\n allowed at the end of file.\n\nThe `mode` string can also have a '`b`' at the end, which is needed in\nsome systems to open the file in binary mode. -open_file io.open_file(utf8_filenames)\nOpens a list of files.\n@param utf8_filenames A `\\n` separated list of UTF-8-encoded filenames to\n open. If `nil`, the user is prompted with a fileselect dialog.\n@usage io.open_file(utf8_encoded_filename) +open_file io.open_file(utf8_filenames)\nOpens a list of files.\nEmits a `FILE_OPENED` event.\n@param utf8_filenames A `\n` separated list of UTF-8-encoded filenames to\n open. If `nil`, the user is prompted with a fileselect dialog.\n@usage io.open_file(utf8_encoded_filename)\n@see _G.events open_recent_file io.open_recent_file()\nPrompts the user to open a recently opened file.\n@see recent_files os _G.os (module)\nLua os module. output io.output([file])\nSimilar to `io.input`, but operates over the default output file. @@ -1306,11 +1308,11 @@ para_up buffer.para_up(buffer)\nMove caret one paragraph up (delimited by empty para_up_extend buffer.para_up_extend(buffer)\nMove caret one paragraph up (delimited by empty lines) extending selection to\nnew caret position.\n@param buffer The global buffer. paste buffer.paste(buffer)\nPaste the contents of the clipboard into the document replacing the\nselection.\n@param buffer The global buffer. path package.path (string)\nThe path used by `require` to search for a Lua loader.\nAt start-up, Lua initializes this variable with the value of the\nenvironment variable `LUA_PATH_5_2` or the environment variable `LUA_PATH`\nor with a default path defined in `luaconf.h`, if those environment\nvariables are not defined. Any "`;;`" in the value of the environment\nvariable is replaced by the default path. -patterns _M.textadept.mime_types.patterns (table)\nFirst-line patterns and their associated lexers. +patterns _M.textadept.mime_types.patterns (table)\nTable of first-line patterns and their associated lexers.\nIf a file type is not recognized by shebang words, each pattern is matched\nagainst the first line in the file. pcall _G.pcall(f [, arg1, ···])\nCalls function `f` with the given arguments in *protected mode*. This\nmeans that any error inside `f` is not propagated; instead, `pcall` catches\nthe error and returns a status code. Its first result is the status code (a\nboolean), which is true if the call succeeds without errors. In such case,\n`pcall` also returns all results from the call, after this first result. In\ncase of any error, `pcall` returns false plus the error message. -php _G.keys.php (table)\nContainer for PHP-specific key commands. +php _G.keys.php (table)\nContainer for PHP-specific key bindings. php _G.snippets.php (table)\nContainer for PHP-specific snippets. -php _M.php (module)\nThe php module.\nIt provides utilities for editing PHP code.\nUser tags are loaded from `_USERHOME/modules/php/tags` and user apis are\nloaded from `_USERHOME/modules/php/api`. +php _M.php (module)\nThe php module.\nIt provides utilities for editing PHP code. pi math.pi (number)\nThe value of 'π'. point_x_from_position buffer.point_x_from_position(buffer, pos)\nRetrieve the x value of the point in the window where a position is\ndisplayed.\n@param buffer The global buffer.\n@param pos The position.\n@return number point_y_from_position buffer.point_y_from_position(buffer, pos)\nRetrieve the y value of the point in the window where a position is\ndisplayed.\n@param buffer The global buffer.\n@param pos The position.\n@return number @@ -1324,24 +1326,24 @@ position_from_point_close buffer.position_from_point_close(buffer, x, y)\nReturn pow math.pow(x, y)\nReturns *x^y*. (You can also use the expression `x^y` to compute this\nvalue.) preload package.preload (table)\nA table to store loaders for specific modules (see `require`).\nThis variable is only a reference to the real table; assignments to this\nvariable do not change the table used by `require`. print _G.print(···)\nReceives any number of arguments and prints their values to `stdout`, using\nthe `tostring` function to convert each argument to a string. `print` is not\nintended for formatted output, but only as a quick way to show a value,\nfor instance for debugging. For complete control over the output, use\n`string.format` and `io.write`. -print gui.print(...)\nPrints messages to the Textadept message buffer.\nOpens a new buffer (if one has not already been opened) for printing\nmessages.\n@param ... Message strings. +print gui.print(...)\nPrints messages to the Textadept message buffer.\nOpens a new buffer if one has not already been opened for printing messages.\n@param ... Message strings. print lexer.print\nMatches any printable character (space to `~`). print_colour_mode buffer.print_colour_mode (number)\nThe print color mode.\n\n* `_SCINTILLA.constants.SC_PRINT_NORMAL` (0)\n Print using the current screen colors.\n This is the default.\n* `_SCINTILLA.constants.SC_PRINT_INVERTLIGHT` (1)\n If you use a dark screen background this saves ink by inverting the light\n value of all colors and printing on a white background.\n* `_SCINTILLA.constants.SC_PRINT_BLACKONWHITE` (2)\n Print all text as black on a white background.\n* `_SCINTILLA.constants.SC_PRINT_COLOURONWHITE` (3)\n Everything prints in its own color on a white background.\n* `_SCINTILLA.constants.SC_PRINT_COLOURONWHITEDEFAULTBG` (4)\n Everything prints in its own color on a white background except that line\n numbers use their own background color. print_magnification buffer.print_magnification (number)\nThe print magnification added to the point size of each style for printing. print_wrap_mode buffer.print_wrap_mode (number)\nPrinting line wrap mode.\n\n* `_SCINTILLA.constants.SC_WRAP_NONE` (0)\n Each line of text generates one line of output and the line is truncated\n if it is too long to fit into the print area.\n* `_SCINTILLA.constants.SC_WRAP_WORD` (1)\n Wraps printed output so that all characters fit into the print rectangle.\n Tries to wrap only between words as indicated by white space or style\n changes although if a word is longer than a line, it will be wrapped\n before the line end. This is the default.\n* `_SCINTILLA.constants.SC_WRAP_CHAR` (2). private_lexer_call buffer.private_lexer_call(buffer, operation, data)\nFor private communication between an application and a known lexer.\n@param buffer The global buffer.\n@param operation An operation number.\n@param data Number data. -process args.process(arg)\nProcesses command line arguments.\nAdd command line switches with `args.register()`. Any unrecognized arguments\nare treated as filepaths and opened.\nGenerates an `'arg_none'` event when no args are present.\n@param arg Argument table.\n@see register -properties _SCINTILLA.properties (table)\nScintilla properties. +process args.process(arg)\nProcesses command line arguments.\nAdd command line switches with `args.register()`. Any unrecognized arguments\nare treated as filepaths and opened.\nEmits an `'arg_none'` event when no args are present.\n@param arg Argument table.\n@see register\n@see events +properties _SCINTILLA.properties (table)\nScintilla properties.\nEach key is a Scintilla property name with a table value containing the ID of\nits "get" function, the ID of its "set" function, its return type, and its\nwParam type. The wParam type will be non-zero if the property is an indexable\nproperty. Types are the same as in the `functions` table.\n@see functions property buffer.property (table)\nTable of keyword:value string pairs used by a lexer for some optional\nfeatures. property_expanded buffer.property_expanded (table)\nTable of keyword:value string pairs used by a lexer for some optional\nfeatures with `$()` variable replacement on returned string. property_int buffer.property_int (table, Read-only)\nInterprets `buffer.property[keyword]` as an integer if found or returns\n`0`. punct lexer.punct\nMatches any punctuation character not alphanumeric (`!` to `/`, `:` to `@`,\n `[` to `'`, `{` to `~`). punctuation_chars buffer.punctuation_chars (string)\nThe set of characters making up punctuation characters.\nUse after setting `buffer.word_chars`. -quit _G.quit()\nQuits Textadept. +quit _G.quit()\nQuits Textadept.\nEmits a `QUIT` event. If any handler returns `false`, Textadept does not\nquit.\n@see events.QUIT rad math.rad(x)\nReturns the angle `x` (given in degrees) in radians. -rails _G.keys.rails (table)\nContainer for Rails-specific key commands. +rails _G.keys.rails (table)\nContainer for Rails-specific key bindings. rails _G.snippets.rails (table)\nContainer for Rails-specific snippets. -rails _M.rails (module)\nThe rails module.\nIt provides utilities for editing Ruby on Rails code.\nUser tags are loaded from `_USERHOME/modules/rails/tags` and user apis are\nloaded from `_USERHOME/modules/rails/api`. +rails _M.rails (module)\nThe rails module.\nIt provides utilities for editing Ruby on Rails code. random math.random([m [, n]])\nThis function is an interface to the simple pseudo-random generator\nfunction `rand` provided by Standard C. (No guarantees can be given for its\nstatistical properties.)\n\nWhen called without arguments, returns a uniform pseudo-random real\nnumber in the range [0,1). When called with an integer number `m`,\n`math.random` returns a uniform pseudo-random integer in the range [1, m].\nWhen called with two integer numbers `m` and `n`, `math.random` returns a\nuniform pseudo-random integer in the range [m, n]. randomseed math.randomseed(x)\nSets `x` as the "seed" for the pseudo-random generator: equal seeds\nproduce equal sequences of numbers. rawequal _G.rawequal(v1, v2)\nChecks whether `v1` is equal to `v2`, without invoking any\nmetamethod. Returns a boolean. @@ -1351,7 +1353,6 @@ rawset _G.rawset(table, index, value)\nSets the real value of `table[index]` to read file:read(···)\nReads the file `file`, according to the given formats, which specify\nwhat to read. For each format, the function returns a string (or a number)\nwith the characters read, or nil if it cannot read data with the specified\nformat. When called without formats, it uses a default format that reads\nthe next line (see below).\n\nThe available formats are\n "*n": reads a number; this is the only format that returns a number\n instead of a string.\n "*a": reads the whole file, starting at the current position. On end of\n file, it returns the empty string.\n "*l": reads the next line skipping the end of line, returning nil on\n end of file. This is the default format.\n "*L": reads the next line keeping the end of line (if present), returning\n nil on end of file.\n *number*: reads a string with up to this number of bytes, returning nil on\n end of file. If number is zero, it reads nothing and returns an empty\n string, or nil on end of file. read io.read(···)\nEquivalent to `io.input():read(···)`. read_only buffer.read_only (bool)\nRead-only mode. -rebuild_command_tables _M.textadept.menu.rebuild_command_tables()\nRebuilds the tables used by `select_command()`.\nThis should be called every time `set_menubar()` is called. recent_files io.recent_files (table)\nList of recently opened files.\nThe most recent are towards the top. rectangular_selection_anchor buffer.rectangular_selection_anchor (number)\nThe position of the anchor of the rectangular selection. rectangular_selection_anchor_virtual_space buffer.rectangular_selection_anchor_virtual_space (number)\nThe amount of virtual space for the anchor of the rectangular selection. @@ -1359,7 +1360,7 @@ rectangular_selection_caret buffer.rectangular_selection_caret (number)\nThe pos rectangular_selection_caret_virtual_space buffer.rectangular_selection_caret_virtual_space (number)\nThe amount of virtual space for the caret of the rectangular selection. rectangular_selection_modifier buffer.rectangular_selection_modifier (number)\nThe modifier key used to indicate that a rectangular selection should be\ncreated when combined with a mouse drag.\n\n* `_SCINTILLA.constants.SCMOD_CTRL` (2)\n Control key (default).\n* `_SCINTILLA.constants.SCMOD_ALT` (4)\n Alt key.\n* `_SCINTILLA.constants.SCMOD_SUPER` (8)\n Left Windows key on a Windows keyboard or the Command key on a Mac. redo buffer.redo(buffer)\nRedoes the next action on the undo history.\n@param buffer The global buffer. -register args.register(switch1, switch2, narg, f, description)\nRegisters a command line switch.\n@param switch1 String switch (short version).\n@param switch2 String switch (long version).\n@param narg The number of expected parameters for the switch.\n@param f The Lua function to run when the switch is tripped.\n@param description Description of the switch. +register args.register(switch1, switch2, narg, f, description)\nRegisters a command line switch.\n@param switch1 String switch (short version).\n@param switch2 String switch (long version).\n@param narg The number of expected parameters for the switch.\n@param f The Lua function to run when the switch is tripped.\n@param description Description of the switch for command line help. register_image buffer.register_image(buffer, type, xpm_data)\nRegister an XPM image for use in autocompletion lists.\n@param buffer The global buffer.\n@param type Integer type to register the image with.\n@param xpm_data XPM data as is described for `buffer:marker_define_pixmap()`. register_rgba_image buffer.register_rgba_image(buffer, type, pixels)\nRegister an RGBA image for use in autocompletion lists.\nIt has the width and height from `buffer.rgba_image_width` and\n`buffer.rgba_image_height`.\n@param buffer The global buffer.\n@param type Integer type to register the image with.\n@param pixels RGBA data as is described for\n `buffer:marker_define_rgba_image()`. reload buffer.reload(buffer)\nReloads the file in a given buffer.\n@param buffer The global buffer. @@ -1368,8 +1369,8 @@ remove table.remove(list [, pos])\nRemoves from `list` the element at position ` rename os.rename(oldname, newname)\nRenames file or directory named `oldname` to `newname`. If this function\nfails, it returns nil, plus a string describing the error and the error code. rep string.rep(s, n [, sep])\nReturns a string that is the concatenation of `n` copies of the string `s`\nseparated by the string `sep`. The default value for `sep` is the empty\nstring (that is, no separator). replace bit32.replace(n, v, field [, width])\nReturns a copy of `n` with the bits `field` to `field + width - 1` replaced\nby the value `v`. See `bit32.extract` for details about `field` and `width`. -replace gui.find.replace()\nMimicks a press of the 'Replace' button in the Find box. -replace_all gui.find.replace_all()\nMimicks a press of the 'Replace All' button in the Find box. +replace gui.find.replace()\nMimicks a press of the 'Replace' button. +replace_all gui.find.replace_all()\nMimicks a press of the 'Replace All' button. replace_all_button_text gui.find.replace_all_button_text (string, Write-only)\nThe text of the 'Replace All' button.\nThis is primarily used for localization. replace_button_text gui.find.replace_button_text (string, Write-only)\nThe text of the 'Replace' button.\nThis is primarily used for localization. replace_entry_text gui.find.replace_entry_text (string)\nThe text in the replace entry. @@ -1378,30 +1379,30 @@ replace_sel buffer.replace_sel(buffer, text)\nReplace the selected text with the replace_target buffer.replace_target(buffer, text)\nReplace the target text with the argument text.\nAfter replacement, the target range refers to the replacement text.\nReturns the length of the replacement text.\n@param buffer The global buffer.\n@param text The text (can contain NULs).\n@return number replace_target_re buffer.replace_target_re(buffer, text)\nReplace the target text with the argument text after `\d` processing.\nLooks for `\d` where `d` is between `1` and `9` and replaces these with the\nstrings matched in the last search operation which were surrounded by `\(`\nand `\)`. Returns the length of the replacement text including any change\ncaused by processing the `\d` patterns.\n@param buffer The global buffer.\n@param text The text (can contain NULs).\n@return number require _G.require(modname)\nLoads the given module. The function starts by looking into the\n`package.loaded` table to determine whether `modname` is already\nloaded. If it is, then `require` returns the value stored at\n`package.loaded[modname]`. Otherwise, it tries to find a *loader* for\nthe module.\n\nTo find a loader, `require` is guided by the `package.searchers` sequence. By\nchanging this sequence, we can change how `require` looks for a module. The\nfollowing explanation is based on the default configuration for\n`package.searchers`.\n\nFirst `require` queries `package.preload[modname]`. If it has a value,\nthis value (which should be a function) is the loader. Otherwise `require`\nsearches for a Lua loader using the path stored in `package.path`. If\nthat also fails, it searches for a C loader using the path stored in\n`package.cpath`. If that also fails, it tries an *all-in-one* loader (see\n`package.searchers`).\n\nOnce a loader is found, `require` calls the loader with two arguments:\n`modname` and an extra value dependent on how it got the loader. (If the\nloader came from a file, this extra value is the file name.) If the loader\nreturns any non-nil value, `require` assigns the returned value to\n`package.loaded[modname]`. If the loader does not return a non-nil value and\nhas not assigned any value to `package.loaded[modname]`, then `require`\nassigns <b>true</b> to this entry. In any case, `require` returns the final\nvalue of `package.loaded[modname]`.\n\nIf there is any error loading or running the module, or if it cannot find\nany loader for the module, then `require` raises an error. -reset _G.reset()\nResets the Lua state by reloading all init scripts.\nLanguage-specific modules for opened files are NOT reloaded. Re-opening the\nfiles that use them will reload those modules.\nThis function is useful for modifying init scripts (such as the user's\n`modules/textadept/keys.lua`) on the fly without having to restart Textadept.\n`_G.RESETTING` is set to `true` when re-initing the Lua State. Any scripts\nthat need to differentiate between startup and reset can utilize this\nvariable.\n@see RESETTING +reset _G.reset()\nResets the Lua state by reloading all init scripts.\nLanguage-specific modules for opened files are NOT reloaded. Re-opening the\nfiles that use them will reload those modules instead.\nThis function is useful for modifying user scripts (such as\n`~/.textadept/init.lua` and `~/.textadept/modules/textadept/keys.lua`) on\nthe fly without having to restart Textadept. `_G.RESETTING` is set to `true`\nwhen re-initing the Lua State. Any scripts that need to differentiate between\nstartup and reset can utilize this variable.\n@see RESETTING resume coroutine.resume(co [, val1, ···])\nStarts or continues the execution of coroutine `co`. The first time\nyou resume a coroutine, it starts running its body. The values `val1`,\n... are passed as the arguments to the body function. If the coroutine\nhas yielded, `resume` restarts it; the values `val1`, ... are passed\nas the results from the yield.\n\nIf the coroutine runs without any errors, `resume` returns true plus any\nvalues passed to `yield` (if the coroutine yields) or any values returned\nby the body function (if the coroutine terminates). If there is any error,\n`resume` returns false plus the error message. reverse string.reverse(s)\nReturns a string that is the string `s` reversed. rgba_image_height buffer.rgba_image_height (number)\nThe height for future RGBA image data. rgba_image_scale buffer.rgba_image_scale (number)\nThe scale factor in percent for future RGBA image data.\nThis is useful on OSX with a retina display where each display unit is 2\npixels: use a factor of 200 so that each image pixel is dsplayed using a\nscreen pixel. The default scale, 100, will stretch each image pixel to\ncover 4 screen pixels on a retina display. rgba_image_width buffer.rgba_image_width (number)\nThe width for future RGBA image data. -rhtml _G.keys.rhtml (table)\nContainer for RHTML-specific key commands. +rhtml _G.keys.rhtml (table)\nContainer for RHTML-specific key bindings. rhtml _G.snippets.rhtml (table)\nContainer for RHTML-specific snippets. -rhtml _M.rhtml (module)\nThe RHTML module.\nIt provides utilities for editing RHTML.\nUser tags are loaded from `_USERHOME/modules/rhtml/tags` and user apis are\nloaded from `_USERHOME/modules/rhtml/api`. +rhtml _M.rhtml (module)\nThe RHTML module.\nIt provides utilities for editing RHTML. rmdir lfs.rmdir(dirname)\nRemoves an existing directory. The argument is the name of the directory.\n\nReturns true if the operation was successful; in case of error, it returns\nnil plus an error string. rotate_selection buffer.rotate_selection(buffer)\nSet the main selection to the next selection.\n@param buffer The global buffer. rrotate bit32.rrotate(x, disp)\nReturns the number `x` rotated `disp` bits to the right. The number `disp`\nmay be any representable integer.\n\nFor any valid displacement, the following identity holds:\n\n assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32))\n\nIn particular, negative displacements rotate to the left. rshift bit32.rshift(x, disp)\nReturns the number `x` shifted `disp` bits to the right. The number `disp`\nmay be any representable integer. Negative displacements shift to the left.\nIn any direction, vacant bits are filled with zeros. In particular,\ndisplacements with absolute values higher than 31 result in zero (all bits\nare shifted out).\n\nFor positive displacements, the following equality holds:\n\n assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp))\n\nThis shift operation is what is called logical shift. -ruby _G.keys.ruby (table)\nContainer for Ruby-specific key commands. +ruby _G.keys.ruby (table)\nContainer for Ruby-specific key bindings. ruby _G.snippets.ruby (table)\nContainer for Ruby-specific snippets. -ruby _M.ruby (module)\nThe ruby module.\nIt provides utilities for editing Ruby code.\nUser tags are loaded from `_USERHOME/modules/ruby/tags` and user apis are\nloaded from `_USERHOME/modules/ruby/api`. -run _M.textadept.run (module)\nModule for running/executing source files.\nTypically, language-specific modules populate the `compile_command`,\n`run_command`, and `error_detail` tables for a particular language's file\nextension. -run _M.textadept.run.run()\nRuns/executes the file as specified by its extension in the `run_command`\ntable.\n@see run_command -run_command _M.textadept.run.run_command (table)\nFile extensions and their associated 'go' actions.\nEach key is a file extension whose value is either a command line string to\nexecute or a function returning one.\nThis table is typically populated by language-specific modules. +ruby _M.ruby (module)\nThe ruby module.\nIt provides utilities for editing Ruby code. +run _M.textadept.run (module)\nCompile and run/execute source files with Textadept.\nTypically, language-specific modules populate the `compile_command`,\n`run_command`, and `error_detail` tables for a particular language's file\nextension. +run _M.textadept.run.run()\nRuns/executes the file based on its extension using the command from the\n`run_command` table.\n@see run_command +run_command _M.textadept.run.run_command (table)\nFile extensions and their associated "run" shell commands.\nEach key is a file extension whose value is either a command line string to\nexecute or a function returning one.\nThis table is typically populated by language-specific modules. running coroutine.running()\nReturns the running coroutine plus a boolean, true when the running coroutine\nis the main one. save _M.textadept.session.save(filename)\nSaves a Textadept session to a file.\nSaves split views, opened buffers, cursor information, and recent files.\n@param filename The absolute path to the session file to save. If `nil`, the\n user is prompted for one.\n@usage _M.textadept.session.save(filename)\n@see DEFAULT_SESSION -save buffer.save(buffer)\nSaves the current buffer to a file.\n@param buffer The global buffer. -save_all io.save_all()\nSaves all dirty buffers to their respective files.\n@usage io.save_all() -save_as buffer.save_as(buffer, utf8_filename)\nSaves the current buffer to a file different than its filename property.\n@param buffer The global buffer.\n@param utf8_filename The new filepath to save the buffer to. Must be UTF-8\n encoded. +save buffer.save(buffer)\nSaves the current buffer to a file.\nEmits `FILE_BEFORE_SAVE` and `FILE_AFTER_SAVE` events.\n@param buffer The global buffer.\n@see _G.events +save_all io.save_all()\nSaves all dirty buffers to their respective files.\n@usage io.save_all()\n@see buffer.save +save_as buffer.save_as(buffer, utf8_filename)\nSaves the current buffer to a file different than its filename property.\nEmits a `FILE_SAVED_AS` event.\n@param buffer The global buffer.\n@param utf8_filename The new filepath to save the buffer to. Must be UTF-8\n encoded.\n@see _G.events scroll_caret buffer.scroll_caret(buffer)\nEnsure the caret is visible.\n@param buffer The global buffer. scroll_to_end buffer.scroll_to_end(buffer)\nScroll to end of document.\n@param buffer The global buffer. scroll_to_start buffer.scroll_to_start(buffer)\nScroll to start of document.\n@param buffer The global buffer. @@ -1419,14 +1420,14 @@ sel_alpha buffer.sel_alpha (number)\nThe alpha of the selection, between `0` (tr sel_eol_filled buffer.sel_eol_filled (bool)\nThe selection end of line fill.\nThe selection can be drawn up to the right hand border by setting this\nproperty. select _G.select(index, ···)\nIf `index` is a number, returns all arguments after argument number\n`index`; a negative number indexes from the end (-1 is the last argument).\nOtherwise, `index` must be the string `"#"`, and `select` returns the total\nnumber of extra arguments it received. select_all buffer.select_all(buffer)\nSelect all the text in the document.\nThe current position is not scrolled into view.\n@param buffer The global buffer. -select_command _M.textadept.menu.select_command()\nPrompts the user with a filteredlist to run menu commands. +select_command _M.textadept.menu.select_command()\nPrompts the user with a filtered list dialog to run menu commands. select_enclosed _M.textadept.editing.select_enclosed(left, right)\nSelects text between a given pair of strings.\n@param left The left part of the enclosure.\n@param right The right part of the enclosure. -select_indented_block _M.textadept.editing.select_indented_block()\nSelects indented blocks intelligently.\nIf no block of text is selected, all text with the current level of\nindentation is selected. If a block of text is selected and the lines to the\ntop and bottom of it are one indentation level lower, they are added to the\nselection. In all other cases, the behavior is the same as if no text is\nselected. -select_lexer _M.textadept.mime_types.select_lexer()\nPrompts the user to select a lexer from a filtered list for the current\nbuffer. +select_indented_block _M.textadept.editing.select_indented_block()\nSelects indented blocks intelligently.\nIf no block of text is selected, all text with the current level of\nindentation is selected. If a block of text is selected and the lines\nimmediately above and below it are one indentation level lower, they are\nadded to the selection. In all other cases, the behavior is the same as if no\ntext is selected. +select_lexer _M.textadept.mime_types.select_lexer()\nPrompts the user to select a lexer from a filtered list for the current\nbuffer.\n@see buffer.set_lexer select_line _M.textadept.editing.select_line()\nSelects the current line. -select_paragraph _M.textadept.editing.select_paragraph()\nSelects the current paragraph.\nParagraphs are delimited by two or more consecutive newlines. -select_theme gui.select_theme()\nPrompts the user to select an editor theme from a filtered list. -select_word _M.textadept.editing.select_word()\nSelects the current word under the caret. +select_paragraph _M.textadept.editing.select_paragraph()\nSelects the current paragraph.\nParagraphs are surrounded by one or more blank lines. +select_theme gui.select_theme()\nPrompts the user to select an editor theme from a filtered list dialog.\nThemes in the `_HOME/themes/` and `_USERHOME/themes/` directories are listed. +select_word _M.textadept.editing.select_word()\nSelects the current word under the caret.\n@see buffer.word_chars selection_duplicate buffer.selection_duplicate(buffer)\nDuplicate the selection.\nIf selection empty duplicate the line containing the caret.\n@param buffer The global buffer. selection_empty buffer.selection_empty (bool, Read-only)\nIs every selected range empty? selection_end buffer.selection_end (number)\nThe position that ends the selection - this becomes the current position.\nThis does not make the caret visible. @@ -1441,16 +1442,16 @@ selection_n_start buffer.selection_n_start (table)\nTable of positions that star selection_start buffer.selection_start (number)\nThe position that starts the selection - this becomes the anchor.\nThis does not make the caret visible. selections buffer.selections (number, Read-only)\nThe number of selections currently active. self _M.textadept.adeptsense.syntax.self (table)\nThe language's syntax-equivalent of `self`. Default is `'self'`. -sense _M.cpp.sense\nThe C/C++ Adeptsense. -sense _M.css.sense\nThe CSS Adeptsense. -sense _M.hypertext.sense\nThe HTML Adeptsense. -sense _M.java.sense\nThe Java Adeptsense. -sense _M.lua.sense\nThe Lua Adeptsense. -sense _M.php.sense\nThe PHP Adeptsense. -sense _M.rails.sense\nThe Rails Adeptsense. -sense _M.rhtml.sense\nThe RHTML Adeptsense. -sense _M.ruby.sense\nThe Ruby Adeptsense. -session _M.textadept.session (module)\nSession support for the textadept module. +sense _M.cpp.sense\nThe C/C++ Adeptsense.\n It loads user tags from `_USERHOME/modules/cpp/tags` and user apidocs from\n `_USERHOME/modules/cpp/api`. +sense _M.css.sense\nThe CSS Adeptsense.\n It loads user tags from `_USERHOME/modules/css/tags` and user apidocs from\n `_USERHOME/modules/css/api`. +sense _M.hypertext.sense\nThe HTML Adeptsense.\n It loads user tags from `_USERHOME/modules/hypertext/tags` and user apidocs\n from `_USERHOME/modules/hypertext/api`. +sense _M.java.sense\nThe Java Adeptsense.\n It loads user tags from `_USERHOME/modules/java/tags` and user apidocs from\n `_USERHOME/modules/java/api`. +sense _M.lua.sense\nThe Lua Adeptsense.\n It loads user tags from `_USERHOME/modules/lua/tags` and user apidocs from\n `_USERHOME/modules/lua/api`. +sense _M.php.sense\nThe PHP Adeptsense.\n It loads user tags from `_USERHOME/modules/php/tags` and user apidocs from\n `_USERHOME/modules/php/api`. +sense _M.rails.sense\nThe Rails Adeptsense.\n It loads user tags from `_USERHOME/modules/rails/tags` and user apidocs\n from `_USERHOME/modules/rails/api`. +sense _M.rhtml.sense\nThe RHTML Adeptsense.\n It loads user tags from `_USERHOME/modules/rhtml/tags` and user apidocs\n from `_USERHOME/modules/rhtml/api`. +sense _M.ruby.sense\nThe Ruby Adeptsense.\n It loads user tags from `_USERHOME/modules/ruby/tags` and user apidocs from\n `_USERHOME/modules/ruby/api`. +session _M.textadept.session (module)\nSession support for Textadept. set_buffer_properties _M.cpp.set_buffer_properties()\nSets default buffer properties for C/C++ files. set_buffer_properties _M.css.set_buffer_properties()\nSets default buffer properties for CSS files. set_buffer_properties _M.hypertext.set_buffer_properties()\nSets default buffer properties for HTML files. @@ -1459,16 +1460,16 @@ set_buffer_properties _M.lua.set_buffer_properties()\nSets default buffer proper set_buffer_properties _M.php.set_buffer_properties()\nSets default buffer properties for PHP files. set_buffer_properties _M.ruby.set_buffer_properties()\nSets default buffer properties for Ruby files. set_chars_default buffer.set_chars_default(buffer)\nReset the set of characters for whitespace and word characters to the\ndefaults.\nThis sets whitespace to space, tab and other characters with codes less than\n`0x20`, with word characters set to alphanumeric and `'_'`.\n@param buffer The global buffer. -set_contextmenu _M.textadept.menu.set_contextmenu(menu_table)\nSets `gui.context_menu` from the given menu table.\n@param menu_table The menu table to create the context menu from. Each table\n entry is either a submenu or menu text and a function or action table.\n@see set_menubar +set_contextmenu _M.textadept.menu.set_contextmenu(menu_table)\nSets `gui.context_menu` from the given menu table.\n@param menu_table The menu table to create the context menu from. The menu is\n an ordered list of menu entries and, if applicable, has a `title` key for\n the submenu title. Menu entries are either submenus of the same form as\n menus, or tables containing menu text and either a function to call or a\n table containing the function to call with its parameters.\n@see gui.context_menu\n@see gui.menu set_empty_selection buffer.set_empty_selection(buffer, pos)\nSet caret to a position, while removing any existing selection.\nThe caret is not scrolled into view.\n@param buffer The buffer\n@param pos The position to move to. -set_encoding buffer.set_encoding(buffer, encoding)\nSets the encoding for the buffer, converting its contents in the process.\n@param buffer The global buffer.\n@param encoding The encoding to set. Valid encodings are ones that GTK's\n `g_convert()` function accepts (typically GNU iconv's encodings).\n@usage buffer.set_encoding(buffer, 'ASCII') +set_encoding buffer.set_encoding(buffer, encoding)\nSets the encoding for the buffer, converting its contents in the process.\n@param buffer The global buffer.\n@param encoding The encoding to set. Valid encodings are ones that GNU iconv\n accepts.\n@usage buffer.set_encoding(buffer, 'ASCII') set_fold_margin_colour buffer.set_fold_margin_colour(buffer, use_setting, color)\nSet the colors used as a chequerboard pattern in the fold margin.\n@param buffer The global buffer.\n@param use_setting Enable color change.\n@param color A color in `0xBBGGRR` format. set_fold_margin_hi_colour buffer.set_fold_margin_hi_colour(buffer, use_setting, color)\nSet the colors used as a checkerboard pattern in the fold margin.\n@param buffer The global buffer.\n@param use_setting Enable color change.\n@param color A color in `0xBBGGRR` format. set_hotspot_active_back buffer.set_hotspot_active_back(buffer, use_setting, color)\nSet a back color for active hotspots.\n@param buffer The global buffer.\n@param use_setting Enable the color change.\n@param color A color in `0xBBGGRR` format. set_hotspot_active_fore buffer.set_hotspot_active_fore(buffer, use_setting, color)\nSet a fore color for active hotspots.\n@param buffer The global buffer.\n@param use_setting Enable the color change.\n@param color A color in `0xBBGGRR` format. set_length_for_encode buffer.set_length_for_encode(buffer, bytes)\nSet the length of the utf8 argument for calling `buffer:encoded_from_utf8()`.\n@param buffer The global buffer.\n@param bytes Bytes or `-1` for measuring to first NUL. set_lexer buffer.set_lexer(buffer, lang)\nReplacement for `buffer.lexer_language =`.\nSets a `buffer._lexer` field so it can be restored without querying the\nmime-types tables. Also if the user manually sets the lexer, it should be\nrestored.\nLoads the language-specific module if it exists.\nThis function is added by `_M.textadept.mime_types`.\n@param buffer The global buffer.\n@param lang The string language to set.\n@usage buffer.set_lexer(buffer, 'language_name') -set_menubar _M.textadept.menu.set_menubar(menubar)\nSets `gui.menubar` from the given table of menus.\n@param menubar The table of menus to create the menubar from.\n@see gui.menu\n@see rebuild_command_tables +set_menubar _M.textadept.menu.set_menubar(menubar)\nSets `gui.menubar` from the given table of menus.\n@param menubar The table of menus to create the menubar from. Each menu is\n an ordered list of menu entries and has a `title` key for the menu/submenu\n title. Menu entries are either submenus of the same form as menus, or\n tables containing menu text and either a function to call or a table\n containing the function to call with its parameters.\n@see gui.menubar\n@see gui.menu set_save_point buffer.set_save_point(buffer)\nRemember the current position in the undo history as the position at which\nthe document was saved.\n@param buffer The global buffer. set_sel buffer.set_sel(buffer, start_pos, end_pos)\nSelect a range of text.\nThe caret is scrolled into view after this operation.\n@param buffer The global buffer.\n@param start_pos Start position. If negative, it means the end of the\n document.\n@param end_pos End position. If negative, it means remove any selection (i.e.\n set the `anchor` to the same position as `current_pos`). set_sel_back buffer.set_sel_back(buffer, use_setting, color)\nSet the background color of the main and additional selections and whether to\nuse this setting.\n@param buffer The global buffer.\n@param use_setting Enable color change.\n@param color A color in `0xBBGGRR` format. @@ -1476,7 +1477,7 @@ set_sel_fore buffer.set_sel_fore(buffer, use_setting, color)\nSet the foreground set_selection buffer.set_selection(buffer, caret, anchor)\nSet a simple selection from anchor to caret.\n@param buffer The global buffer.\n@param caret The caret.\n@param anchor The anchor. set_styling buffer.set_styling(buffer, length, style)\nChange style from current styling position for length characters to a style\nand move the current styling position to after this newly styled segment.\n@param buffer The global buffer.\n@param length The length to style.\n@param style The style number to set. set_text buffer.set_text(buffer, text)\nReplace the contents of the document with the argument text.\n@param buffer The global buffer.\n@param text The text. -set_theme gui.set_theme(name)\nSets the editor theme from the given name.\nThemes in `_USERHOME/themes/` are checked first, followed by `_HOME/themes/`.\nIf the name contains slashes ('/' on Linux and Mac OSX and '\' on Win32), it\nis assumed to be an absolute path so `_USERHOME` and `_HOME` are not checked.\nThrows an error if the theme is not found. Any errors in the theme are\nprinted to `io.stderr`.\n@param name The name or absolute path of a theme. If nil, sets the default\n theme. +set_theme gui.set_theme(name)\nSets the editor theme from the given name.\nThemes with the given name in the `_USERHOME/themes/` directory override\nthemes of the same name in `_HOME/themes/`. If the name contains slashes (`\`\non Windows, `/` otherwise), it is assumed to be an absolute path to a theme\ninstead of a theme name. An error is thrown if the theme is not found. Any\nerrors in the theme are printed to `io.stderr`.\n@param name The name or absolute path of a theme. If nil, sets the default\n theme. set_visible_policy buffer.set_visible_policy(buffer, visible_policy, visible_slop)\nSet the way the display area is determined when a particular line is to be\nmoved to by `buffer:goto_line()`, etc.\nIt is similar in operation to `buffer:set_y_caret_policy()`.\n@param buffer The global buffer.\n@param visible_policy A combination of `_SCINTILLA.constants.VISIBLE_SLOP`,\n (0x01) and `_SCINTILLA.constants.VISIBLE_STRICT` (0x04).\n@param visible_slop The slop value. set_whitespace_back buffer.set_whitespace_back(buffer, use_setting, color)\nSet the background color of all whitespace and whether to use this setting.\n@param buffer The global buffer.\n@param use_setting Enable color change.\n@param color A color in `0xBBGGRR` format. set_whitespace_fore buffer.set_whitespace_fore(buffer, use_setting, color)\nSet the foreground color of all whitespace and whether to use this setting.\n@param buffer The global buffer.\n@param use_setting Enable color change.\n@param color A color in `0xBBGGRR` format. @@ -1492,21 +1493,21 @@ setmode lfs.setmode(file, mode)\nSets the writing mode for a file. The mode stri setupvalue debug.setupvalue(f, up, value)\nThis function assigns the value `value` to the upvalue with index `up`\nof the function `f`. The function returns nil if there is no upvalue with the\ngiven index. Otherwise, it returns the name of the upvalue. setuservalue debug.setuservalue(udata, value)\nSets the given `value` as the Lua value associated to the given `udata`.\n`value` must be a table or nil; `udata` must be a full userdata.\n\nReturns `udata`. setvbuf file:setvbuf(mode [, size])\nSets the buffering mode for an output file. There are three available\nmodes:\n "no": no buffering; the result of any output operation appears immediately.\n "full": full buffering; output operation is performed only when the\n buffer is full or when you explicitly `flush` the file (see\n `io.flush`).\n "line": line buffering; output is buffered until a newline is output or\n there is any input from some special files (such as a terminal\n device).\n\nFor the last two cases, `size` specifies the size of the buffer, in\nbytes. The default is an appropriate size. -shebangs _M.textadept.mime_types.shebangs (table)\nShebang words and their associated lexers. +shebangs _M.textadept.mime_types.shebangs (table)\nTable of shebang words and their associated lexers.\nIf the file has a shebang line, a line that starts with `#!` and is the first\nline in the file, each shebang word is matched against that line. show_apidoc _M.textadept.adeptsense.show_apidoc(sense)\nShows a calltip with API documentation for the symbol behind the caret.\nIf documentation is already being shown, cycles through multiple definitions.\n@param sense The Adeptsense returned by `adeptsense.new()`. If `nil`, uses\n the current language's Adeptsense (if it exists).\n@return list of api docs on success or `nil`.\n@see get_symbol\n@see get_apidoc -show_completions gui.command_entry.show_completions(completions)\nShows the given list of completions for the current word prefix.\nOn selection, the current word prefix is replaced with the completion.\n@param completions The table of completions to show. Non-string values are\n ignored. +show_completions gui.command_entry.show_completions(completions)\nShows the given list of completions for the current word prefix.\nOn selection, the current word prefix is replaced with the completion. Word\nprefix characters are alphanumerics and underscores.\n@param completions The table of completions to show. Non-string values are\n ignored. show_lines buffer.show_lines(buffer, start_line, end_line)\nMake a range of lines visible.\nThis has no effect on fold levels or fold flags. `start_line` can not be\nhidden.\n@param buffer The global buffer.\n@param start_line The start line.\n@param end_line The end line. sin math.sin(x)\nReturns the sine of `x` (assumed to be in radians). -singular _M.rails.singular\nA map of plural controller names to their singulars. Add key-value pairs to\nthis if singularize() is incorrectly converting your plural\ncontroller name to its singular model name. +singular _M.rails.singular\nA map of plural controller names to their singulars. Add key-value pairs to\n this if the local function `singularize()` is incorrectly converting your\n plural controller name to its singular model name. sinh math.sinh(x)\nReturns the hyperbolic sine of `x`. -size gui.size (table)\nThe size of the Textadept window (`{ width, height }`). +size gui.size (table)\nA table containing the width and height values of the Textadept window. size view.size (number)\nThe position of the split resizer (if this view is part of a split view). -snapopen _M.textadept.snapopen (module)\nSnapopen for the textadept module. -snippets _G.snippets (table)\nProvides access to snippets from `_G`. -snippets _M.textadept.snippets (module)\nProvides Lua-style snippets for Textadept. +snapopen _M.textadept.snapopen (module)\nQuickly open files in a set of directories using a filtered list dialog. +snippets _G.snippets (table)\nTable of snippet triggers with their snippet text.\nLanguage-specific snippets are in another table value whose key is the\nlanguage's lexer name.\nThis table also contains the `_M.textadept.snippets` module. +snippets _M.textadept.snippets (module)\nSnippets for Textadept. sort table.sort(list [, comp])\nSorts list elements in a given order, *in-place*, from `list[1]` to\n`list[#list]`. If `comp` is given, then it must be a function that receives\ntwo list elements and returns true when the first element must come before\nthe second in the final order (so that `not comp(list[i+1],list[i])` will be\ntrue after the sort). If `comp` is not given, then the standard Lua operator\n`<` is used instead.\n\nThe sort algorithm is not stable; that is, elements considered equal by the\ngiven order may have their relative positions changed by the sort. -space lexer.space\nMatches any whitespace character (`\t`, `\v`, `\f`, `\\n`, `\r`, space). -split view:split(vertical)\nSplits the indexed view vertically or horizontally and focuses the new view.\n@param vertical Flag indicating a vertical split. The default value is\n `false` for horizontal.\n@return old view and new view tables. +space lexer.space\nMatches any whitespace character (`\t`, `\v`, `\f`, `\n`, `\r`, space). +split view.split(view, vertical)\nSplits the given view vertically or horizontally and focuses the new view.\nEmits a `VIEW_NEW` event.\n@param view The view to split.\n@param vertical Flag indicating a vertical split. The default value is\n `false` for horizontal.\n@return old view and new view.\n@see events.VIEW_NEW sqrt math.sqrt(x)\nReturns the square root of `x`. (You can also use the expression `x^0.5`\nto compute this value.) start_record buffer.start_record(buffer)\nStart notifying the container of all key presses and commands.\n@param buffer The global buffer. start_styling buffer.start_styling(buffer, position, mask)\nSet the current styling position to pos and the styling mask to mask.\nThe styling mask can be used to protect some bits in each styling byte from\nmodification.\n@param buffer The global buffer.\n@param position The styling position.\n@param mask The bit mask of the style bytes that can be set. @@ -1523,7 +1524,7 @@ stuttered_page_down buffer.stuttered_page_down(buffer)\nMove caret to bottom of stuttered_page_down_extend buffer.stuttered_page_down_extend(buffer)\nMove caret to bottom of page, or one page down if already at bottom of page,\nextending selection to new caret position.\n@param buffer The global buffer. stuttered_page_up buffer.stuttered_page_up(buffer)\nMove caret to top of page, or one page up if already at top of page.\n@param buffer The global buffer. stuttered_page_up_extend buffer.stuttered_page_up_extend(buffer)\nMove caret to top of page, or one page up if already at top of page,\nextending selection to new caret position.\n@param buffer The global buffer. -style lexer.style(style_table)\nCreates a Scintilla style from a table of style properties.\n@param style_table A table of style properties.\nStyle properties available:\n * font [string]\n * size [integer]\n * bold [boolean]\n * italic [boolean]\n * underline [boolean]\n * fore [integer] (Use value returned by [`color()`](#color))\n * back [integer] (Use value returned by [`color()`](#color))\n * eolfilled [boolean]\n * characterset [?]\n * case [integer]\n * visible [boolean]\n * changeable [boolean]\n * hotspot [boolean]\n@usage local bold_italic = style { bold = true, italic = true }\n@see color +style lexer.style(style_table)\nCreates a Scintilla style from a table of style properties.\n@param style_table A table of style properties.\nStyle properties available:\n * font [string]\n * size [integer]\n * bold [boolean]\n * italic [boolean]\n * underline [boolean]\n * fore [integer] (Use value returned by `color()`)\n * back [integer] (Use value returned by `color()`)\n * eolfilled [boolean]\n * characterset [?]\n * case [integer]\n * visible [boolean]\n * changeable [boolean]\n * hotspot [boolean]\n@usage local bold_italic = style { bold = true, italic = true }\n@see color style_at buffer.style_at (table, Read-only)\nTable of style bytes at positions in the document starting at zero. style_back buffer.style_back (table)\nTable of background colors in `0xBBGGRR` format for styles from `0` to\n`255`. style_bits buffer.style_bits (number)\nThe number of bits in style bytes used to hold the lexical state. @@ -1567,7 +1568,7 @@ style_whitespace lexer.style_whitespace\nStyle typically used for whitespace. sub string.sub(s, i [, j])\nReturns the substring of `s` that starts at `i` and continues until\n`j`; `i` and `j` can be negative. If `j` is absent, then it is assumed to\nbe equal to -1 (which is the same as the string length). In particular,\nthe call `string.sub(s,1,j)` returns a prefix of `s` with length `j`, and\n`string.sub(s, -i)` returns a suffix of `s` with length `i`.\n\nIf, after the translation of negative indices, `i` is less than 1, it is\ncorrected to 1. If `j` is greater than the string length, it is corrected to\nthat length. If, after these corrections, `i` is greater than `j`, the\nfunction returns the empty string. swap_main_anchor_caret buffer.swap_main_anchor_caret(buffer)\nSwap that caret and anchor of the main selection.\n@param buffer The global buffer. switch_buffer gui.switch_buffer()\nDisplays a dialog with a list of buffers to switch to and switches to the\nselected one, if any. -symbol_chars _M.textadept.adeptsense.syntax.symbol_chars (table)\nA Lua pattern of characters allowed in a symbol,\n including member operators. The pattern should be a character set. The\n default is `'[%w_%.]'`. +symbol_chars _M.textadept.adeptsense.syntax.symbol_chars (table)\nA Lua pattern of characters allowed in a symbol,\n including member operators. The pattern should be a character set.\n The default is `'[%w_%.]'`. symlinkattributes lfs.symlinkattributes(filepath [, aname])\nIdentical to lfs.attributes except that it obtains information about the link\nitself (not the file it refers to). This function is not available in Windows\nso you may want to make sure that lfs.symlinkattributes exists before using\nit. syntax _M.textadept.adeptsense.syntax (table)\nContains syntax-specific values for the language.\n@see get_class tab buffer.tab(buffer)\nIf selection is empty or all on one line replace the selection with a tab\ncharacter, or if more than one line selected, indent the lines.\n@param buffer The global buffer. @@ -1587,12 +1588,12 @@ text_range buffer.text_range(buffer, start_pos, end_pos)\nGets a range of text f text_width buffer.text_width(buffer, style_num, text)\nMeasure the pixel width of some text in a particular style.\nDoes not handle tab or control characters.\n@param buffer The global buffer.\n@param style_num The style number between `0` and `255`.\n@param text The text.\n@return number textadept _M.textadept (module)\nThe textadept module.\nIt provides utilities for editing text in Textadept. time os.time([table])\nReturns the current time when called without arguments, or a time\nrepresenting the date and time specified by the given table. This table\nmust have fields `year`, `month`, and `day`, and may have fields `hour`\n(default is 12), `min` (default is 0), `sec` (default is 0), and `isdst`\n(default is nil). For a description of these fields, see the `os.date`\nfunction.\n\nThe returned value is a number, whose meaning depends on your system. In\nPOSIX, Windows, and some other systems, this number counts the number of\nseconds since some given start time (the "epoch"). In other systems, the\nmeaning is not specified, and the number returned by `time` can be used only\nas an argument to `os.date` and `os.difftime`. -timeout _G.timeout(interval, f, ...)\nCalls a given function after an interval of time.\nTo repeatedly call the function, return true inside the function. A `nil` or\n`false` return value stops repetition.\n@param interval The interval in seconds to call the function after.\n@param f The function to call.\n@param ... Additional arguments to pass to `f`. +timeout _G.timeout(interval, f, ...)\nCalls a given function after an interval of time.\nTo repeatedly call the function, return `true` inside the function. A `nil`\nor `false` return value stops repetition.\n@param interval The interval in seconds to call the function after.\n@param f The function to call.\n@param ... Additional arguments to pass to `f`. title gui.title (string, Write-only)\nThe title of the Textadept window. tmpfile io.tmpfile()\nReturns a handle for a temporary file. This file is opened in update\nmode and it is automatically removed when the program ends. tmpname os.tmpname()\nReturns a string with a file name that can be used for a temporary\nfile. The file must be explicitly opened before its use and explicitly\nremoved when no longer needed.\n\nOn POSIX systems, this function also creates a file with that name, to avoid\nsecurity risks. (Someone else might create the file with wrong permissions in\nthe time between getting the name and creating the file.) You still have to\nopen the file to use it and to remove it (even if you do not use it).\n\nWhen possible, you may prefer to use `io.tmpfile`, which automatically\nremoves the file when the program ends. toggle _M.textadept.bookmarks.toggle(on)\nToggles a bookmark on the current line.\n@param on If `true`, adds a bookmark to the current line. If `false`, removes\n the bookmark on the current line. Otherwise, toggles a bookmark. -toggle_block _M.ruby.toggle_block()\nToggles between { ... } and do ... end Ruby blocks.\nIf the caret is inside a { ... } single-line block, that block is converted\nto a multiple-line do .. end block. If the caret is on a line that contains\nsingle-line do ... end block, that block is converted to a single-line\n{ ... } block. If the caret is inside a multiple-line do ... end block, that\nblock is converted to a single-line { ... } block with all newlines replaced\nby a space. Indentation is important. The 'do' and 'end' keywords must be on\nlines with the same level of indentation to toggle correctly +toggle_block _M.ruby.toggle_block()\nToggles between `{ ... }` and `do ... end` Ruby blocks.\nIf the caret is inside a `{ ... }` single-line block, that block is converted\nto a multiple-line `do .. end` block. If the caret is on a line that contains\nsingle-line `do ... end` block, that block is converted to a single-line\n`{ ... }` block. If the caret is inside a multiple-line `do ... end` block,\nthat block is converted to a single-line `{ ... }` block with all newlines\nreplaced by a space. Indentation is important. The `do` and `end` keywords\nmust be on lines with the same level of indentation to toggle correctly. toggle_caret_sticky buffer.toggle_caret_sticky(buffer)\nSwitch between sticky and non-sticky: meant to be bound to a key.\nSee `buffer.caret_sticky`.\n@param buffer The global buffer. toggle_fold buffer.toggle_fold(buffer, line)\nSwitch a header line between expanded and contracted.\n@param buffer The global buffer.\n@param line The line number. token lexer.token(name, patt)\nCreates an LPeg capture table index with the name and position of the token.\n@param name The name of token. If this name is not in `l.tokens` then you\n will have to specify a style for it in `lexer._tokenstyles`.\n@param patt The LPeg pattern associated with the token.\n@usage local ws = token(l.WHITESPACE, l.space^1)\n@usage php_start_rule = token('php_tag', '<?' * ('php' * l.space)^-1) @@ -1601,21 +1602,21 @@ tostring _G.tostring(v)\nReceives a value of any type and converts it to a strin touch lfs.touch(filepath [, atime [, mtime]])\nSet access and modification times of a file. This function is a bind to utime\nfunction. The first argument is the filename, the second argument (atime) is\nthe access time, and the third argument (mtime) is the modification time.\nBoth times are provided in seconds (which should be generated with Lua\nstandard function os.time). If the modification time is omitted, the access\ntime provided is used; if both times are omitted, the current time is used.\n\nReturns true if the operation was successful; in case of error, it returns\nnil plus an error string. traceback debug.traceback([thread, ] [message] [, level])\nIf `message` is present but is neither a string nor nil, this function\nreturns `message` without further processing. Otherwise, it returns a string\nwith a traceback of the call stack. An optional `message` string is appended\nat the beginning of the traceback. An optional `level` number tells at which\nlevel to start the traceback (default is 1, the function calling\n`traceback`). transpose_chars _M.textadept.editing.transpose_chars()\nTransposes characters intelligently.\nIf the caret is at the end of a line, the two characters before the caret are\ntransposed. Otherwise, the characters to the left and right are. -try_encodings io.try_encodings (table)\nList of encodings to try to decode files as after UTF-8. -try_to_autocomplete_end _M.lua.try_to_autocomplete_end()\nTries to autocomplete Lua's 'end' keyword for control structures like 'if',\n'while', 'for', etc.\n@see control_structure_patterns -try_to_autocomplete_end _M.ruby.try_to_autocomplete_end()\nTries to autocomplete Ruby's 'end' keyword for control structures like 'if',\n'while', 'for', etc.\n@see control_structure_patterns +try_encodings io.try_encodings (table)\nList of encodings to try to decode files as.\nYou should add to this list if you get a "Conversion failed" error when\ntrying to open a file whose encoding is not recognized. Valid encodings are\nGNU iconv's encodings. +try_to_autocomplete_end _M.lua.try_to_autocomplete_end()\nTries to autocomplete Lua's `end` keyword for control structures like `if`,\n`while`, `for`, etc.\n@see control_structure_patterns +try_to_autocomplete_end _M.ruby.try_to_autocomplete_end()\nTries to autocomplete Ruby's `end` keyword for control structures like `if`,\n`while`, `for`, etc.\n@see control_structure_patterns two_phase_draw buffer.two_phase_draw (bool)\nTwo phase drawing mode.\nWhen `true`, drawing is performed in two phases, first the background and\nthen the foreground. This avoids chopping off characters that overlap the\nnext run. The default is for drawing to be two phase. type _G.type(v)\nReturns the type of its only argument, coded as a string. The possible\nresults of this function are "\n`nil`" (a string, not the value nil), "`number`", "`string`", "`boolean`",\n"`table`", "`function`", "`thread`", and "`userdata`". type io.type(obj)\nChecks whether `obj` is a valid file handle. Returns the string `"file"`\nif `obj` is an open file handle, `"closed file"` if `obj` is a closed file\nhandle, or nil if `obj` is not a file handle. type lpeg.type(value)\nIf the given value is a pattern, returns the string "pattern". Otherwise\nreturns nil. type_assignments _M.textadept.adeptsense.syntax.type_assignments (table)\nA map of Lua patterns to class types for variable\n assignments. This is typically used for dynamically typed languages. For\n example, `sense.type_assignments['^"'] = 'string'` would recognize string\n assignments in Lua so the `foo` in `foo = "bar"` would be recognized as\n type `string`. The class type value can contain pattern captures. -type_declarations _M.textadept.adeptsense.syntax.type_declarations (table)\nA list of Lua patterns used for determining the\n class type of a symbol. The first capture returned must be the class name.\n Use `%_` to match the symbol. The default value is `'(%u[%w_%.]+)%s+%_'`. -type_declarations_exclude _M.textadept.adeptsense.syntax.type_declarations_exclude (table)\nA table of types to exclude, even if they\n match a type_declaration pattern. Each excluded type is a table key and has\n a `true` boolean value. For example, `{ Foo = true }` excludes any type\n whose name is `Foo`. The default value is `{}`. +type_declarations _M.textadept.adeptsense.syntax.type_declarations (table)\nA list of Lua patterns used for determining the\n class type of a symbol. The first capture returned must be the class name.\n Use `%_` to match the symbol.\n The default value is `'(%u[%w_%.]+)%s+%_'`. +type_declarations_exclude _M.textadept.adeptsense.syntax.type_declarations_exclude (table)\nA table of types to exclude, even if they\n match a type_declaration pattern. Each excluded type is a table key and has\n a `true` boolean value. For example, `{ Foo = true }` excludes any type\n whose name is `Foo`.\n The default value is `{}`. undo buffer.undo(buffer)\nUndo one action in the undo history.\n@param buffer The global buffer. undo_collection buffer.undo_collection (bool)\nWhether to collect undo information.\nWhen stopping collection, use `buffer:empty_undo_buffer()` to avoid the\nundo buffer being unsynchronized with the data in the buffer. unlock lfs.unlock(filehandle[, start[, length]])\nUnlocks a file or a part of it. This function works on open files; the file\nhandle should be specified as the first argument. The optional arguments\nstart and length can be used to specify a starting point and its length; both\nshould be numbers.\n\nReturns true if the operation was successful; in case of error, it returns\nnil plus an error string. unpack table.unpack(list [, i [, j]])\nReturns the elements from the given table. This function is equivalent to\n\n return list[i], list[i+1], ···, list[j]\n\nBy default, `i` is 1 and `j` is `#list`. -unsplit view:unsplit()\nUnsplits the indexed view if possible.\n@return boolean if the view was unsplit or not. +unsplit view.unsplit(view)\nUnsplits the given view if possible.\n@param view The view to unsplit.\n@return boolean if the view was unsplit or not. upper lexer.upper\nMatches any uppercase character (`A-Z`). upper string.upper(s)\nReceives a string and returns a copy of this string with all lowercase\nletters changed to uppercase. All other characters are left unchanged. The\ndefinition of what a lowercase letter is depends on the current locale. upper_case buffer.upper_case(buffer)\nTransform the selection to upper case.\n@param buffer The global buffer. @@ -1634,7 +1635,8 @@ vc_home_wrap buffer.vc_home_wrap(buffer)\nMove caret to before first visible cha vc_home_wrap_extend buffer.vc_home_wrap_extend(buffer)\nLike `buffer:vc_home_wrap()` but extending selection to new caret position.\n@param buffer The global buffer. version lpeg.version()\nReturns a string with the running version of LPeg. vertical_centre_caret buffer.vertical_centre_caret(buffer)\nCenter current line in window.\n@param buffer The global buffer. -view _G.view (module)\nThe currently focused view.\nIt also represents the structure of any view table in `_G._VIEWS`. +view _G.view (module)\nA Textadept view object. +view _G.view\nThe currently focused view. view_eol buffer.view_eol (bool)\nWhether the end of line characters are visible.\nNormally, the end of line characters are hidden. view_ws buffer.view_ws (number)\nThe visibility of white space characters.\n\n* `_SCINTILLA.constants.SCWS_INVISIBLE` (0)\n The normal display mode with white space displayed as an empty background\n color.\n* `_SCINTILLA.constants.SCWS_VISIBLEALWAYS` (1)\n White space characters are drawn as dots and arrows.\n* `_SCINTILLA.constants.SCWS_VISIBLEAFTERINDENT` (2)\n White space used for indentation is displayed normally but after the\n first visible character, it is shown as dots and arrows. virtual_space_options buffer.virtual_space_options (number)\nVirtual space options.\n\n* `_SCINTILLA.constants.SCVS_NONE` (0)\n Disables all use of virtual space (default).\n* `_SCINTILLA.constants.SCVS_RECTANGULARSELECTION` (1)\n Enabled only for rectangular selections.\n* `_SCINTILLA.constants.SCVS_USERACCESSIBLE` (2)\n Enabled. @@ -1644,7 +1646,7 @@ whitespace_size buffer.whitespace_size (number)\nThe size of the dots used to ma whole_word gui.find.whole_word (bool)\nOnly whole-word matches are allowed in searches. whole_word_label_text gui.find.whole_word_label_text (string, Write-only)\nThe text of the 'Whole word' label.\nThis is primarily used for localization. word lexer.word\nMatches a typical word starting with a letter or underscore and then any\n alphanumeric or underscore characters. -word_chars _M.textadept.adeptsense.syntax.word_chars (table)\nA Lua pattern of characters allowed in a word. The default\n is `'%w_'`. +word_chars _M.textadept.adeptsense.syntax.word_chars (table)\nA Lua pattern of characters allowed in a word.\n The default is `'%w_'`. word_chars buffer.word_chars (string)\nThe set of characters making up words when moving or selecting by word. word_end_position buffer.word_end_position(buffer, pos, only_word_chars)\nGet position of end of word.\n@param buffer The global buffer.\n@param pos The position.\n@param only_word_chars If `true`, stops searching at the first non-word\n character in the search direction. Otherwise, the first character in the\n search direction sets the type of the search as word or non-word and the\n search stops at the first non-matching character. Searches are also\n terminated by the start or end of the document. word_left buffer.word_left(buffer)\nMove caret left one word.\n@param buffer The global buffer. diff --git a/modules/lua/init.lua b/modules/lua/init.lua index 32dd5742..7d00a030 100644 --- a/modules/lua/init.lua +++ b/modules/lua/init.lua @@ -6,15 +6,14 @@ local M = {} --- -- The lua module. -- It provides utilities for editing Lua code. --- User tags are loaded from `_USERHOME/modules/lua/tags` and user apis are --- loaded from `_USERHOME/modules/lua/api`. -- --- ## Key Commands +-- ## Key Bindings -- --- + `Ctrl+L, M` (`⌘L, M` on Mac OSX) +-- + `Ctrl+L, M` (`⌘L, M` on Mac OSX | `M-L, M` in ncurses) -- Open this module for editing. --- + `Shift+Return` (`⇧↩`) --- Try to autocomplete an `if`, `for`, etc. statement with `end`. +-- + `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. @@ -23,12 +22,15 @@ local M = {} -- functions only. -- @field sense -- The Lua [Adeptsense](_M.textadept.adeptsense.html). +-- It loads user tags from `_USERHOME/modules/lua/tags` and user apidocs from +-- `_USERHOME/modules/lua/api`. module('_M.lua')]] local m_editing, m_run = _M.textadept.editing, _M.textadept.run -- Comment string tables use lexer names. m_editing.comment_string.lua = '--' -- Compile and Run command tables use file extensions. +m_run.compile_command.lua = 'luac %(filename)' m_run.run_command.lua = 'lua %(filename)' m_run.error_detail.lua = { pattern = '^lua: (.-):(%d+): (.+)$', @@ -60,8 +62,9 @@ M.sense:add_trigger('.') M.sense:add_trigger(':', false, true) -- script/update_doc generates a fake set of ctags used for autocompletion. +local as = _M.textadept.adeptsense M.sense.ctags_kinds = { - f = 'functions', F = 'fields', m = 'classes', t = 'fields' + f = as.FUNCTION, F = as.FIELD, m = as.CLASS, t = as.FIELD } M.sense:load_ctags(_HOME..'/modules/lua/tags', true) @@ -93,7 +96,7 @@ end -- Commands. --- --- Patterns for auto 'end' completion for control structures. +-- Patterns for auto `end` completion for control structures. -- @class table -- @name control_structure_patterns -- @see try_to_autocomplete_end @@ -103,8 +106,8 @@ local control_structure_patterns = { } --- --- Tries to autocomplete Lua's 'end' keyword for control structures like 'if', --- 'while', 'for', etc. +-- Tries to autocomplete Lua's `end` keyword for control structures like `if`, +-- `while`, `for`, etc. -- @see control_structure_patterns -- @name try_to_autocomplete_end function M.try_to_autocomplete_end() @@ -146,7 +149,7 @@ events.connect(events.FILE_AFTER_SAVE, function() end) --- --- Container for Lua-specific key commands. +-- Container for Lua-specific key bindings. -- @class table -- @name _G.keys.lua keys.lua = { diff --git a/modules/lua/tags b/modules/lua/tags index 0c2c1bc5..ea27ba31 100644 --- a/modules/lua/tags +++ b/modules/lua/tags @@ -21,6 +21,7 @@ CARET_JUMPS _ 0;" F class:_SCINTILLA.constants CARET_SLOP _ 0;" F class:_SCINTILLA.constants CARET_STRICT _ 0;" F class:_SCINTILLA.constants CHAR_ADDED _ 0;" F class:events +CLASS _ 0;" F class:_M.textadept.adeptsense CLASS _ 0;" F class:lexer CLEAR _ 0;" F class:keys COMMAND_ENTRY_COMMAND _ 0;" F class:events @@ -48,6 +49,7 @@ EDGE_LINE _ 0;" F class:_SCINTILLA.constants EDGE_NONE _ 0;" F class:_SCINTILLA.constants ERROR _ 0;" F class:events ERROR _ 0;" F class:lexer +FIELD _ 0;" F class:_M.textadept.adeptsense FIELDS _ 0;" F class:_M.textadept.adeptsense FILE_AFTER_SAVE _ 0;" F class:events FILE_BEFORE_SAVE _ 0;" F class:events @@ -55,6 +57,7 @@ FILE_OPENED _ 0;" F class:events FILE_SAVED_AS _ 0;" F class:events FILTER _ 0;" t class:_M.textadept.snapopen FIND _ 0;" F class:events +FUNCTION _ 0;" F class:_M.textadept.adeptsense FUNCTION _ 0;" F class:lexer FUNCTIONS _ 0;" F class:_M.textadept.adeptsense HIGHLIGHT_BRACES _ 0;" F class:_M.textadept.editing @@ -868,6 +871,7 @@ brace_highlight_indicator _ 0;" f class:buffer brace_match _ 0;" f class:buffer braces _ 0;" t class:_M.textadept.editing btest _ 0;" f class:bit32 +buffer _ 0;" F buffer _ 0;" m buffer _ 0;" t buffer _ 0;" t class:view @@ -1115,8 +1119,6 @@ goto_line _ 0;" f class:buffer goto_next _ 0;" f class:_M.textadept.bookmarks goto_pos _ 0;" f class:buffer goto_prev _ 0;" f class:_M.textadept.bookmarks -goto_required _ 0;" f class:_M.php -goto_required _ 0;" f class:_M.ruby goto_view _ 0;" f class:gui grab_focus _ 0;" f class:buffer graph _ 0;" F class:lexer @@ -1392,7 +1394,6 @@ rawset _ 0;" f read _ 0;" f class:file read _ 0;" f class:io read_only _ 0;" F class:buffer -rebuild_command_tables _ 0;" f class:_M.textadept.menu recent_files _ 0;" t class:io rectangular_selection_anchor _ 0;" F class:buffer rectangular_selection_anchor_virtual_space _ 0;" F class:buffer @@ -1677,6 +1678,7 @@ vc_home_wrap _ 0;" f class:buffer vc_home_wrap_extend _ 0;" f class:buffer version _ 0;" f class:lpeg vertical_centre_caret _ 0;" f class:buffer +view _ 0;" F view _ 0;" m view _ 0;" t view_eol _ 0;" F class:buffer 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<br/>Alt+Backspace|⌘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 +-- Ctrl+V<br/>Shift+Ins |⌘V |^V |Paste +-- Ctrl+D |⌘D |None |Duplicate line +-- Del |⌦<br/>^D |Del<br/>^D |Delete +-- Alt+Del |^⌦ |M-Del<br/>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<br/>M-S-F|Find +-- Ctrl+G<br/>F3 |⌘G |M-G |Find next +-- Ctrl+Shift+G<br/>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<br/>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<br/>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<br/>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<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+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 +-- 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 |⇣<br/>^N |^N<br/>Down |Line down +-- Shift+Down |⇧⇣<br/>^⇧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 |⇡<br/>^P |^P<br/>Up |Line up +-- Shift+Up |⇧⇡<br/>^⇧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 |⇠<br/>^B |^B<br/>Left |Char left +-- Shift+Left |⇧⇠<br/>^⇧B |S-Left |Char left extend selection +-- Ctrl+Left |^⇠<br/>^⌘B |^Left |Word left +-- Ctrl+Shift+Left |^⇧⇠<br/>^⌘⇧B|S-^Left |Word left extend selection +-- Alt+Shift+Left |⌥⇧⇠ |M-S-Left |Char left extend rect. selection +-- Right |⇢<br/>^F |^F<br/>Right|Char right +-- Shift+Right |⇧⇢<br/>^⇧F |S-Right |Char right extend selection +-- Ctrl+Right |^⇢<br/>^⌘F |^Right |Word right +-- Ctrl+Shift+Right|^⇧⇢<br/>^⌘⇧F|S-^Right |Word right extend selection +-- Alt+Shift+Right |⌥⇧⇢ |M-S-Right |Char right extend rect. selection +-- Home |⌘⇠<br/>^A |^A<br/>Home |Line start +-- Shift+Home |⌘⇧⇠<br/>^⇧A |M-S-A |Line start extend selection +-- Ctrl+Home |⌘⇡<br/>⌘↖ |M-^A |Document start +-- Ctrl+Shift+Home |⌘⇧⇡<br/>⌘⇧↖ |None |Document start extend selection +-- Alt+Shift+Home |⌥⇧↖ |None |Line start extend rect. selection +-- End |⌘⇢<br/>^E |^E<br/>End |Line end +-- Shift+End |⌘⇧⇢<br/>^⇧E |M-S-E |Line end extend selection +-- Ctrl+End |⌘⇣<br/>⌘↘ |M-^E |Document end +-- Ctrl+Shift+End |⌘⇧⇣<br/>⌘⇧↘ |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 |⌫<br/>⇧⌫ |^H<br/>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. -- --- %<lua_code> --- %num<lua_code> --- %[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 = '%<buffer.filename>' --- 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 diff --git a/themes/dark/buffer.lua b/themes/dark/buffer.lua index 40fd6a8a..e02fc719 100644 --- a/themes/dark/buffer.lua +++ b/themes/dark/buffer.lua @@ -11,6 +11,6 @@ buffer.property['fold.line.comments'] = '0' -- Tabs and Indentation. buffer.tab_width = 2 buffer.use_tabs = false -buffer.indent = 2 +--buffer.indent = 2 buffer.tab_indents = true buffer.back_space_un_indents = true diff --git a/themes/light/buffer.lua b/themes/light/buffer.lua index 26c8f6d2..eb0da320 100644 --- a/themes/light/buffer.lua +++ b/themes/light/buffer.lua @@ -11,6 +11,6 @@ buffer.property['fold.line.comments'] = '0' -- Tabs and Indentation. buffer.tab_width = 2 buffer.use_tabs = false -buffer.indent = 2 +--buffer.indent = 2 buffer.tab_indents = true buffer.back_space_un_indents = true diff --git a/themes/term/buffer.lua b/themes/term/buffer.lua index 2f2aef61..8f5ca3fe 100644 --- a/themes/term/buffer.lua +++ b/themes/term/buffer.lua @@ -11,6 +11,6 @@ buffer.property['fold.line.comments'] = '0' -- Tabs and Indentation. buffer.tab_width = 2 buffer.use_tabs = false -buffer.indent = 2 +--buffer.indent = 2 buffer.tab_indents = true buffer.back_space_un_indents = true |
