-- Copyright 2007-2014 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*.) -- -- 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 -- -- To fully take advantage of Textadept's features, language modules should have -- 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 and commands and a context menu. -- -- #### 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 "%(filename)"' -- textadept.run.run_commands.lua = 'lua "%(filename)"' -- -- 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+): (.+)$') -- -- [`textadept.run.compile_commands`]: textadept.run.html#compile_commands -- [`textadept.run.run_commands`]: textadept.run.html#run_commands -- [macros]: textadept.run.html#execute -- [`textadept.run.error_patterns`]: textadept.run.html#error_patterns -- -- #### 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. -- -- [`io.get_project_root()`]: io.html#get_project_root -- [`textadept.run.build_commands`]: textadept.run.html#build_commands -- -- #### Buffer Properties -- -- By default, Textadept uses 2 spaces as 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][] and [API file(s)][]. -- -- [autocompleter]: textadept.editing.html#autocompleters -- [API file(s)]: textadept.editing.html#api_files -- -- #### Snippets -- -- [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", -- } -- -- [Snippets]: textadept.snippets.html -- -- #### Commands -- -- 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 curses) key for easy access. -- -- -- In file *lua/init.lua* | -- In file *cpp/init.lua* -- | -- function M.try_to_autocomplete_end() | keys.cpp = { -- ... | ['s\n'] = function() -- end | buffer:line_end() -- | buffer:add_text(';') -- keys.lua = { | buffer:new_line() -- ['s\n'] = M.try_to_autocomplete_end | end -- } | } -- -- [Lua]: _M.lua.html -- [C/C++]: _M.cpp.html -- -- #### Context Menu -- -- Language-specific [context menus][], accessible by right-clicking inside the -- view, are useful for accessing module features without using key bindings. -- For Lua this might 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} -- } -- -- [context menus]: textadept.menu.html#context_menu module('_M')]]