-- Copyright 2007-2015 Mitchell mitchell.att.foicica.com. See LICENSE. -- This is a DUMMY FILE used for making LuaDoc for built-in functions in the -- global _M table. --[[ This comment is for LuaDoc. --- -- A table of loaded Textadept language modules. -- -- ## Module Guidelines -- -- 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.) -- -- 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. -- -- ### Language Modules -- -- 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, and context menu items. -- -- #### 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: -- -- textadept.run.compile_commands.lua = 'luac "%f"' -- textadept.run.run_commands.lua = 'lua "%f"' -- -- 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 -- -- As with compile and run commands, any recognized errors are flagged. -- -- -- #### Buffer Properties -- -- 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 -- end -- end -- -- #### 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. -- -- #### Snippets -- -- [Snippets](#textadept.snippets) for common language constructs are useful. -- Some snippets for common Lua control structures look like -- -- 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", -- } -- -- #### 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 -- } | } -- -- 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. -- -- keys.lua[not OSX and not CURSES and 'cl' or 'ml'] = { -- ... -- } -- -- #### Context Menu -- -- 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 -- -- textadept.menu.context_menu[#textadept.menu.context_menu + 1] = { -- title = 'Lua', -- {'Autocomplete "end"', M.try_to_autocomplete_end} -- } module('_M')]]