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-2013 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 modules.
--
-- ## Module Guidelines
--
-- At the very least, modules consist of a single directory with an *init.lua*
-- script. However, the script can load additional Lua files present in the
-- directory. (For an example, see *modules/textadept/init.lua*.)
--
-- Once modules are loaded, regardless of whether they are generic or
-- language-specific, they persist in Textadept's Lua State; they are never
-- unloaded. Therefore, modules should not set global functions or variables in
-- order to avoid polluting the global environment. All functions and variables
-- should be contained within the module.
--
-- ### Language-Specific
--
-- To fully take advantage of Textadept's features, language-specific modules
-- should have at a minimum: a block comment string, run and/or compile
-- commands, a buffer property setter function, and if possible, an Adeptsense.
-- Optional features are extra snippets and commands and a context menu.
--
-- #### Block Comment
--
-- The `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in ncurses) key binding toggles code
-- comments. In order for this to work for your language, the
-- [`_M.textadept.editing.comment_string`][] table must have a key with the
-- language's lexer name assigned to a comment prefix string. For Lua, it would
-- look like
--
-- _M.textadept.editing.comment_string.lua = '--'
--
-- [`_M.textadept.editing.comment_string`]: _M.textadept.editing.html#comment_string
--
-- #### Compile and Run
--
-- The `Ctrl+Shift+R` and `Ctrl+R` (`⌘⇧R` and `⌘R` on Mac OSX | `M-^R` and `^R`
-- in ncurses) key bindings compile and run code, respectively. In order for
-- these to work for your language, the [`_M.textadept.run.compile_command`][]
-- and [`_M.textadept.run.run_command`][] tables must have keys with the
-- language's lexer name assigned to compile and run shell commands,
-- respectively. Commands may contain [macros][]. For Lua, it would look like
--
-- _M.textadept.run.compile_command.lua = 'luac %(filename)'
-- _M.textadept.run.run_command = 'lua %(filename)'
--
-- The module should also define error details in
-- [`_M.textadept.run.error_detail`][] so double-clicking on compile or runtime
-- errors will jump to the error's location. The format for Lua errors looks
-- like
--
-- _M.textadept.run.error_detail.lua = {
-- pattern = '^lua: (.-):(%d+): (.+)$',
-- filename = 1, line = 2, message = 3
-- }
--
-- [`_M.textadept.run.compile_command`]: _M.textadept.run.html#compile_command
-- [`_M.textadept.run.run_command`]: _M.textadept.run.html#run_command
-- [macros]: _M.textadept.run.html#execute
-- [`_M.textadept.run.error_detail`]: _M.textadept.run.html#error_detail
--
-- #### Buffer Properties
--
-- By default, Textadept uses 2 spaces as indentation. If your language has
-- different indentation guidelines, change them in a `set_buffer_properties()`
-- function. Using tabs of width 8 would look like
--
-- function M.set_buffer_properties()
-- buffer.tab_width = 8
-- buffer.use_tabs = true
-- end
--
-- This function is called automatically to set the properties for the
-- language's source files.
--
-- #### Adeptsense
--
-- The `Ctrl+Space` and `Ctrl+H` (`⌥⎋` and `^H` on Mac OSX | `^Space` and `M-H`
-- or `M-S-H` in ncurses) 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 [Adeptsense][].
--
-- [Adeptsense]: _M.textadept.adeptsense.html
--
-- #### Snippets
--
-- [Snippets][] for common language constructs can be 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]: _M.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 ncurses) key for easy access.
--
-- function M.try_to_autocomplete_end()
-- ...
-- end
--
-- keys.lua = {
-- ['s\n'] = M.try_to_autocomplete_end
-- }
--
-- ---
--
-- keys.cpp = {
-- ['s\n'] = function()
-- buffer:line_end()
-- buffer:add_text(';')
-- buffer:new_line()
-- end
-- }
--
-- [Lua]: _M.lua.html
-- [C/C++]: _M.cpp.html
--
-- #### Context Menu
--
-- Language-specific [context menus][], accessible by right-clicking inside the
-- view, can be useful for accessing module features without using key bindings.
-- For Lua this may 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]: _M.textadept.menu.html#set_contextmenu
module('_M')]]
|
