/
ft_lua.txt
330 lines (261 loc) · 14.4 KB
/
ft_lua.txt
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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
*ft_lua.txt* Lua file type plug-in for the Vim text editor
===============================================================================
Contents ~
1. Introduction |ft_lua-introduction|
2. Installation |ft_lua-installation|
3. Options |ft_lua-options|
1. The |lua_path| option
2. The |lua_check_syntax| option
3. The |lua_check_globals| option
4. The |lua_interpreter_path| option
5. The |lua_internal| option
6. The |lua_compiler_name| option
7. The |lua_compiler_args| option
8. The |lua_error_format| option
9. The |lua_complete_keywords| option
10. The |lua_complete_globals| option
11. The |lua_complete_library| option
12. The |lua_complete_dynamic| option
13. The |lua_complete_omni| option
14. The |lua_omni_blacklist| option
15. The |lua_define_completefunc| option
16. The |lua_define_omnifunc| option
17. The |lua_define_completion_mappings| option
4. Commands |ft_lua-commands|
1. The |:LuaCheckSyntax| command
2. The |:LuaCheckGlobals| command
5. Contact |ft_lua-contact|
6. License |ft_lua-license|
7. References |ft_lua-references|
===============================================================================
*ft_lua-introduction*
Introduction ~
The Lua [1] file type plug-in for Vim makes it easier to work with Lua source
code in Vim by providing the following features:
- The |'includeexpr'| option is set so that the |gf| (go to file) mapping
knows how to resolve Lua module names using package.path [2]
- The |'include'| option is set so that Vim follows dofile() [3], loadfile()
[4] and require() [5] calls when looking for identifiers in included files
(this works together with the |'includeexpr'| option)
- An automatic command is installed that runs 'luac -p' when you save your
Lua scripts. If 'luac' reports any errors they are shown in the quick-fix
list and Vim jumps to the line of the first error. If 'luac -p' doesn't
report any errors a check for undefined global variables is performed by
parsing the output of 'luac -p -l'
- 'K' (normal mode) and '<F1>' (insert mode) on a Lua function or 'method'
call will try to open the relevant documentation in the Lua Reference for
Vim [6]
- The |'completefunc'| option is set to allow completion of Lua 5.2 keywords,
global variables and library members using Control-X Control-U
- The |'omnifunc'| option is set to allow dynamic completion of the variables
defined in all modules installed on the system using Control-X Control-O,
however it needs to be explicitly enabled by setting the
|lua_complete_omni| option because this functionality may have undesired
side effects! When you invoke omni completion after typing "require '" or
"require('" you get completion of module names
Image: Screenshot of omni completion (see reference [7])
- Several |text-objects| are defined so you can jump between blocks and
functions
- A pretty nifty hack of the matchit plug-in (see |matchit-install|) is
included: When the cursor is on a 'function' or 'return' keyword the '%'
mapping cycles between the relevant keywords ('function', 'return', 'end'),
this also works for branching statements ('if', 'elseif', 'else', 'end')
and looping statements ('for', 'while', 'repeat', 'until', 'end')
===============================================================================
*ft_lua-installation*
Installation ~
_Please note that the vim-lua-ftplugin plug-in requires my vim-misc plug-in
which is separately distributed._
Unzip the most recent ZIP archives of the vim-lua-ftplugin [8] and vim-misc [9]
plug-ins inside your Vim profile directory (usually this is '~/.vim' on UNIX
and '%USERPROFILE%\vimfiles' on Windows), restart Vim and execute the command
':helptags ~/.vim/doc' (use ':helptags ~\vimfiles\doc' instead on Windows).
If you prefer you can also use Pathogen [10], Vundle [11] or a similar tool to
install & update the vim-lua-ftplugin [12] and vim-misc [13] plug-ins using a
local clone of the git repository.
Now try it out: Edit a Lua script and try any of the features documented above.
Note that on Windows a command prompt window pops up whenever Lua is run as an
external process. If this bothers you then you can install my shell.vim [14]
plug-in which includes a DLL [15] that works around this issue. Once you've
installed both plug-ins it should work out of the box!
===============================================================================
*ft_lua-options*
Options ~
The Lua file type plug-in handles options as follows: First it looks at buffer
local variables, then it looks at global variables and if neither exists a
default is chosen. This means you can change how the plug-in works for
individual buffers. For example to change the location of the Lua compiler used
to check the syntax:
>
" This sets the default value for all buffers.
:let g:lua_compiler_name = '/usr/local/bin/luac'
" This is how you change the value for one buffer.
:let b:lua_compiler_name = '/usr/local/bin/lualint'
<
-------------------------------------------------------------------------------
The *lua_path* option
This option contains the value of 'package.path' as a string. You shouldn't
need to change this because the plug-in is aware of $LUA_PATH [2] and if that
isn't set the plug-in will run a Lua interpreter to get the value of
package.path [2].
-------------------------------------------------------------------------------
The *lua_check_syntax* option
When you write a Lua script to disk the plug-in automatically runs the Lua
compiler to check for syntax errors. To disable this behavior you can set this
option to false (0):
>
let g:lua_check_syntax = 0
<
You can manually check the syntax using the ':CheckSyntax' command.
-------------------------------------------------------------------------------
The *lua_check_globals* option
When you write a Lua script to disk the plug-in automatically runs the Lua
compiler to check for undefined global variables. To disable this behavior you
can set this option to false (0):
>
let g:lua_check_globals = 0
<
You can manually check the globals using the ':CheckGlobals' command.
-------------------------------------------------------------------------------
The *lua_interpreter_path* option
The name or path of the Lua interpreter used to evaluate Lua scripts used by
the plug-in (for example the script that checks for undefined global variables,
see |:LuaCheckGlobals|).
-------------------------------------------------------------------------------
The *lua_internal* option
If you're running a version of Vim that supports the Lua Interface for Vim (see
|if_lua.txt|) then all Lua code evaluated by the Lua file type plug-in is
evaluated using the Lua Interface for Vim. If the Lua Interface for Vim is not
available the plug-in falls back to using an external Lua interpreter. You can
set this to false (0) to force the plug-in to use an external Lua interpreter.
-------------------------------------------------------------------------------
The *lua_compiler_name* option
The name or path of the Lua compiler used to check for syntax errors (defaults
to 'luac'). You can set this option to run the Lua compiler from a non-standard
location or to run a dedicated syntax checker like lualint [16].
-------------------------------------------------------------------------------
The *lua_compiler_args* option
The argument(s) required by the compiler or syntax checker (defaults to '-p').
-------------------------------------------------------------------------------
The *lua_error_format* option
If you use a dedicated syntax checker you may need to change this option to
reflect the format of the messages printed by the syntax checker.
-------------------------------------------------------------------------------
The *lua_complete_keywords* option
To disable completion of keywords you can set this option to false (0).
-------------------------------------------------------------------------------
The *lua_complete_globals* option
To disable completion of global functions you can set this option to false (0).
-------------------------------------------------------------------------------
The *lua_complete_library* option
To disable completion of library functions you can set this option to false
(0).
-------------------------------------------------------------------------------
The *lua_complete_dynamic* option
When you type a dot after a word the Lua file type plug-in will automatically
start completion. To disable this behavior you can set this option to false
(0).
-------------------------------------------------------------------------------
The *lua_complete_omni* option
This option is disabled by default for two reasons:
- The omni completion support works by enumerating and loading all installed
modules. **If module loading has side effects this can have unintended
consequences!**
- Because all modules installed on the system are loaded, collecting the
completion candidates can be slow. After the first run the completion
candidates are cached so this will only bother you once (until you restart
Vim).
If you want to use the omni completion despite the warnings above, execute the
following command:
>
:let g:lua_complete_omni = 1
<
Now when you type Control-X Control-O Vim will hang for a moment, after which
you should be presented with an enormous list of completion candidates :-)
-------------------------------------------------------------------------------
The *lua_omni_blacklist* option
If you like the omni completion mode but certain modules are giving you trouble
(for example crashing Vim) you can exclude such modules from being loaded by
the omni completion. You can do so by setting 'lua_omni_module_blacklist' to a
list of strings containing Vim regular expression patterns. The patterns are
combined as follows:
>
" Here's the black list:
let g:lua_omni_blacklist = ['pl\.strict', 'lgi\..']
" Here's the resulting regular expression pattern:
'^\(pl\.strict\|lgi\..\)$'
<
The example above prevents the module 'pl.strict' and all modules with the
prefix 'lgi.' from being loaded.
-------------------------------------------------------------------------------
The *lua_define_completefunc* option
By default the Lua file type plug-in sets the |'completefunc'| option so that
Vim can complete Lua keywords, global variables and library members using
Control-X Control-U. If you don't want the 'completefunc' option to be changed
by the plug-in, you can set this option to zero (false) in your |vimrc| script:
>
:let g:lua_define_completefunc = 0
<
-------------------------------------------------------------------------------
The *lua_define_omnifunc* option
By default the Lua file type plug-in sets the |'omnifunc'| option so that Vim
can complete the names of all Lua modules installed on the local system. If you
don't want the 'omnifunc' option to be changed by the plug-in, you can set this
option to zero (false) in your |vimrc| script:
>
:let g:lua_define_omnifunc = 0
<
-------------------------------------------------------------------------------
The *lua_define_completion_mappings* option
By default the Lua file type plug-in defines insert mode mappings so that the
plug-in is called whenever you type a single quote, double quote or a dot
inside a Lua buffer. This enables context sensitive completion. If you don't
like these mappings you can set this option to zero (false). In that case the
mappings will not be defined.
===============================================================================
*ft_lua-commands*
Commands ~
-------------------------------------------------------------------------------
The *:LuaCheckSyntax* command
Check the current file for syntax errors using the Lua compiler. This command
is executed automatically when you write a Lua script to disk (i.e. when you
save your changes) unless |lua_check_syntax| is false.
-------------------------------------------------------------------------------
The *:LuaCheckGlobals* command
Check the current file for undefined global variables. This command is executed
automatically when you write a Lua script to disk (i.e. when you save your
changes) unless |lua_check_globals| is false or syntax errors were detected.
===============================================================================
*ft_lua-contact*
Contact ~
If you have questions, bug reports, suggestions, etc. the author can be
contacted at peter@peterodding.com. The latest version is available at
http://peterodding.com/code/vim/lua-ftplugin and http://github.com/xolox/vim-
lua-ftplugin. If you like this plug-in please vote for it on Vim Online [17].
===============================================================================
*ft_lua-license*
License ~
This software is licensed under the MIT license [18]. Š 2014 Peter Odding
<peter@peterodding.com>.
===============================================================================
*ft_lua-references*
References ~
[1] http://www.lua.org/
[2] http://www.lua.org/manual/5.2/manual.html#pdf-package.path
[3] http://www.lua.org/manual/5.2/manual.html#pdf-dofile
[4] http://www.lua.org/manual/5.2/manual.html#pdf-loadfile
[5] http://www.lua.org/manual/5.2/manual.html#pdf-require
[6] http://www.vim.org/scripts/script.php?script_id=1291
[7] http://peterodding.com/code/vim/lua-ftplugin/screenshots/omni-completion.png
[8] http://peterodding.com/code/vim/downloads/lua-ftplugin.zip
[9] http://peterodding.com/code/vim/downloads/misc.zip
[10] http://www.vim.org/scripts/script.php?script_id=2332
[11] https://github.com/gmarik/vundle
[12] http://github.com/xolox/vim-lua-ftplugin
[13] http://github.com/xolox/vim-misc
[14] http://peterodding.com/code/vim/shell/
[15] http://en.wikipedia.org/wiki/Dynamic-link_library
[16] http://lua-users.org/wiki/LuaLint
[17] http://www.vim.org/scripts/script.php?script_id=3625
[18] http://en.wikipedia.org/wiki/MIT_License
vim: ft=help