lua.vim - Lua file type plug-in for the Vim text editor

The Lua file type plug-in for Vim makes it easier to work with Lua source code in Vim by providing the following features:

Screenshot of omni completion

# 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 and vim-misc 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, Vundle or a similar tool to install & update the vim-lua-ftplugin and vim-misc 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 plug-in which includes a DLL that works around this issue. Once you’ve installed both plug-ins it should work out of the box!

# 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 and if that isn’t set the plug-in will run a Lua interpreter to get the value of package.path.

# 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_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.

# 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:

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_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.

# 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.

# License

This software is licensed under the MIT license.
© 2013 Peter Odding <peter@peterodding.com>.

Last updated Sat Aug 31 14:02:43 UTC 2013.