1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
-- 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')]]
|
