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
146
147
148
149
150
151
152
153
154
|
-- 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')]]
|
