diff options
author | 2016-06-15 09:10:07 -0400 | |
---|---|---|
committer | 2016-06-15 09:10:07 -0400 | |
commit | 27c42565b3b1cccf0c2eb5770614b67617de6b48 (patch) | |
tree | 48fabf8671cff4aa20a1c7150504bba680e87679 | |
parent | 32d756e63267ded00c37a2d67f91d74f0d08ae0c (diff) |
Refactored LuaDoc for `_M`; core/._M.luadoc
-rw-r--r-- | core/._M.luadoc | 185 |
1 files changed, 80 insertions, 105 deletions
diff --git a/core/._M.luadoc b/core/._M.luadoc index 2fd1b9b6..ae2463fe 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -6,35 +6,44 @@ --- -- A table of loaded Textadept language modules. -- --- ## Module Guidelines +-- Language modules are a special kind of module that Textadept automatically +-- loads when editing source code in a particular programming language. The only +-- thing "special" about them is they are named after a lexer. Otherwise they +-- are plain Lua modules. The *~/.textadept/modules/* directory houses language +-- modules (along with other modules). -- --- Textadept modules are identical to Lua modules and behave in the same way. --- Modules consist of a single directory with an *init.lua* script and any --- necessary support files. (For an example, see *modules/textadept/init.lua*, --- which is a module that provides most of Textadept's functionality.) +-- A language module is designed to provide extra functionality for a single +-- programming language. Some examples of what language modules can do: -- --- Loaded modules, even language modules, persist in Textadept's Lua State; --- Textadept never unloads them. Therefore, modules should define functions or --- variables within the module itself, not globally. +-- * Specify block comment syntax for lines of code +-- * Define compile and run commands for source files +-- * Set language-specific editor properties like indentation rules +-- * Specify code autocompletion routines +-- * Declare snippets +-- * Define commands and key bindings for them +-- * Add to the top-level menu or right-click editor context menu -- --- ### Language Modules +-- Examples of these features are described in the sections below. -- --- Language modules are a special kind of module that Textadept automatically --- loads when editing source code in a particular programming language. When --- writing a language module, and in order to fully take advantage of --- Textadept's features, you should include at a minimum: run and/or compile --- commands, an event handler for setting buffer properties like indentation, --- and if possible, an autocompleter. Optional features are extra snippets, --- commands, context menu items, and a syntax checking command. --- --- #### Compile and Run --- --- The `Ctrl+Shift+R` and `Ctrl+R` (`⌘⇧R` and `⌘R` on Mac OSX | `M-^R` and `^R` --- in curses) key bindings compile and run code, respectively. If Textadept does --- not execute the correct commands for your language, modify them in the --- [`textadept.run.compile_commands`]() and [`textadept.run.run_commands`]() --- tables using the appropriate lexer key. Commands may contain macros. For Lua, --- it would look like: +-- ## Block Comment +-- +-- Many languages have different syntaxes for single line comments and +-- multi-line comments in source code. Textadept's block comment feature only +-- uses one of those syntaxes for a given language. If you prefer the other +-- syntax, or if Textadept does not support block comments for a particular +-- language, modify the [`textadept.editing.comment_string`]() table. For +-- example: +-- +-- textadept.editing.comment_string.ansi_c = '//' -- change from /* ... */ +-- +-- ## Compile and Run +-- +-- Textadept knows most of the commands that compile and/or run code in source +-- files. However, it does not know all of them, and the ones that it does know +-- may not be completely accurate in all cases. Compile and run commands are +-- read from the [`textadept.run.compile_commands`]() and +-- [`textadept.run.run_commands`]() tables using the appropriate lexer key, and +-- thus can be defined or modified. For Lua, it would look like: -- -- textadept.run.compile_commands.lua = 'luac "%f"' -- textadept.run.run_commands.lua = 'lua "%f"' @@ -42,60 +51,40 @@ -- Double-clicking on compile or runtime errors jumps to the error's location. -- If Textadept does not recognize your language's errors properly, add an error -- pattern to [`textadept.run.error_patterns`](). The Lua error pattern looks --- like --- --- table.insert(textadept.run.error_patterns, 1, --- '^luac?: (.-):(%d+): (.+)$') --- --- #### Build a Project --- --- The `Ctrl+Shift+B` (`⌘⇧B` on Mac OSX | `M-^B` in curses) key bindings build --- the current project. Textadept can only detect projects under version --- control, and uses [`io.get_project_root()`]() to do so. The editor looks in --- the detected project's root directory for some sort of "makefile" (GNU --- Makefiles, Ruby Rakefiles, etc.) and prompts the user for any additional --- arguments to pass to that makefile's run command. Textadept references --- [`textadept.run.build_commands`]() for makefiles and their associated run --- commands. Per-project build commands may also be defined. For example, the --- following command builds Textadept after prompting for makefile targets: --- --- textadept.run.build_commands[_HOME] = function() --- local button, target = ui.dialogs.standard_inputbox{ --- title = _L['Command'], informative_text = 'make -C src' --- } --- if button == 1 then return 'make -C src '..target end --- end +-- like: -- --- As with compile and run commands, any recognized errors are flagged. +-- local patterns = textadept.run.error_patterns +-- if not patterns.lua then patterns.lua = {} end +-- patterns.lua[#patterns.lua + 1] = '^luac?: (.-):(%d+): (.+)$' -- +-- ## Buffer Properties -- --- #### Buffer Properties +-- By default, Textadept uses 2 spaces for indentation. Some languages have +-- different indentation guidelines, however. As described in the manual, use +-- `events.LEXER_LOADED` to change this and any other language-specific editor +-- properties. For example: -- --- By default, Textadept uses 2 spaces for indentation. If your language has --- different indentation guidelines, change them from an --- `events.LEXER_LOADED` event handler. Using tabs of width 8 would look like --- --- events.connect(events.LEXER_LOADED, function(lang) --- if lang == 'lua' then --- buffer.tab_width = 8 --- buffer.use_tabs = true +-- events.connect(events.LEXER_LOADED, function(lexer) +-- if lexer == 'python' then +-- buffer.tab_width = 4 +-- buffer.use_tabs = false +-- buffer.view_ws = buffer.WS_VISIBLEALWAYS -- end -- end -- --- #### Autocompletion and Documentation +-- ## Autocompletion and Documentation -- --- The `Ctrl+Space` and `Ctrl+H` (`⌥⎋` and `^H` on Mac OSX | `^Space` and `M-H` --- or `M-S-H` in curses) 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 --- [autocompleter](#textadept.editing.autocompleters) and --- [API file(s)](#textadept.editing.api_files). All of Textadept's included --- language modules have examples of autocompleters and API documentation. +-- Textadept has the capability to autocomplete symbols for programming +-- languages and display API documentation. In order for these to work for a +-- given language, an [autocompleter](#textadept.editing.autocompleters) and +-- [API file(s)](#textadept.editing.api_files) must exist. All of Textadept's +-- included language modules have examples of autocompleters and API +-- documentation, as well as most of its officially supported language modules. -- --- #### Snippets +-- ## Snippets -- -- [Snippets](#textadept.snippets) for common language constructs are useful. --- Some snippets for common Lua control structures look like +-- Some snippets for common Lua control structures look like this: -- -- snippets.lua = { -- f = "function %1(name)(%2(args))\n\t%0\nend", @@ -104,58 +93,44 @@ -- forp = "for %1(k), %2(v) in pairs(%3(table)) do\n\t%0\nend", -- } -- --- #### Commands +-- ## Commands -- -- Additional editing features for the language can be useful. For example, the --- [Lua](#_M.lua) module has a feature to autocomplete the `end` keyword in a --- control structure and the [C](#_M.ansi_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 curses) key for easy access. --- --- -- In file *lua/init.lua* | -- In file *ansi_c/init.lua* --- | --- function M.try_to_autocomplete_end() | keys.ansi_c = { --- ... | ['s\n'] = function() --- end | buffer:line_end() --- | buffer:add_text(';') --- keys.lua = { | buffer:new_line() --- ['s\n'] = M.try_to_autocomplete_end | end --- } | } +-- [C](#_M.ansi_c) module has a feature to add a ';' to the end of the current +-- line and insert a new line. This command is bound to the `Shift+Enter` (`⇧↩` +-- on Mac OSX | `S-Enter` in curses) key for easy access: +-- +-- keys.ansi_c = { +-- ['s\n'] = function() +-- buffer:line_end() +-- buffer:add_text(';') +-- buffer:new_line() +-- end +-- } -- -- When defining key bindings for other commands, you may make use of a `Ctrl+L` -- (`⌘L` on Mac OSX | `M-L` in curses) keychain. Traditionally this prefix has -- been reserved for use by language modules (although neither Textadept nor its -- modules utilize it at the moment). Users may define this keychain for new or -- existing modules and it will not conflict with any default key bindings. +-- For example: -- -- keys.lua[not OSX and not CURSES and 'cl' or 'ml'] = { -- ... -- } -- --- #### Context Menu +-- ## Menus -- --- It may be useful to add language-specific menu options to the right-click --- context menu in order to access module features without using key bindings. --- For Lua this might look like +-- It may be useful to add language-specific menu options to the top-level menu +-- and/or right-click context menu in order to access module features without +-- using key bindings. For example: -- --- textadept.menu.context_menu[#textadept.menu.context_menu + 1] = { +-- local lua_menu = { -- title = 'Lua', --- {'Autocomplete "end"', M.try_to_autocomplete_end} +-- {'Item 1', function() ... end}, +-- {'Item 2', function() ... end} -- } --- --- #### Syntax Checking --- --- Textadept has the ability to run a syntax checking tool on source files --- immediately after saving them, and automatically does this for a number of --- interpreted languages and markup languages. If your language is not supported --- (properly or at all), you will have to update the --- [`textadept.run.syntax_commands`]() and --- [`textadept.run.syntax_error_patterns`]() tables. For Lua, this looks like --- --- textadept.run.syntax_commands.lua = 'luac -p "%f"' --- textadept.run.syntax_error_patterns.lua = ':(%d+): ([^\r\n]+)' --- --- This feature really only makes sense for interpreted and markup languages. --- Compiled languages should make use of Textadept's "Compile and Run" and error --- recognition facilities. +-- local tools = textadept.menu.menubar[_L['_Tools']] +-- tools[#tools + 1] = lua_menu +-- textadept.menu.context_menu[#textadept.menu.context_menu + 1] = lua_menu module('_M')]] |