How to create a vim-ale plugin

A simple, Hello World-style tutorial for how to create a vim-ale plugin, including formatter, linter, and/or LSP server (Language Server Protocol).

vi ./example.hello.txt

In this tutorial / example project we have:

hellolang	A fictional language for this example (*.hello.txt)
hello-fmt	The formatter; What vim-ale calls a "fixer"
hello-lint	The linter with LSP support

Table of Contents

• HelloLang Demo
• Anatomy of a vim-ale plugin
• A Short Intro to VimScript
• The Language Server Protocol
• Debugging

Demo

1. Install vim-ale-hello-world to ~/.vim/pack/plugin/start/

   git clone --depth=1 \
       https://github.com/beyondcodebootcamp/vim-ale-hello-world.git \
       ~/.vim/pack/plugins/start/vim-ale-hello-world

2. Update ~/.vimrc to recognize hellolang

   let g:ale_fix_on_save = 1
   let g:ale_lint_on_save = 1
   
   let g:ale_fixers = {
   \  'hellolang': ['hellofmt'],
   \}
   
   " NOTE: generally you don't need manual linter config
   " let g:ale_linters = {
   " \  'hellolang': ['hellolint'],
   " \}

3. Install node and the hello-lint Language Server

   curl https://webi.sh/node | sh

   pushd ~/.vim/pack/plugins/start/vim-ale-hello-world/
   npm ci

4. Update your PATH to include hello-fmt and hello-lint at ~/.vim/pack/plugins/start/vim-ale-hello-world/bin/

   export PATH="$HOME/.vim/pack/plugins/start/vim-ale-hello-world/bin/:$PATH"

Now *.hello.txt is registered as hellolang which using hello-fmt as a fixer, hello-lint as a linter (and for LSP), and javascript for syntax highlighting (because custom syntax highlighting is outside the scope of this tutorial).

You can try opening and saving (:w) a file to watch the magic happen:

vi ./example.hello.txt

:w

// Needs more Hello, World!

Anatomy

There are TWO possible configurations for a plugin:

Internal

An internal plugin is a Pull Request to vim-ale:

~/
├── bin/
│   ├── hello-fmt
│   └── hello-lint
│
└── .vim/
    ├── pack/plugins/start/ale/
    │   │
    │   ├── ale_linters/hellolang/
    │   │   └── hello_lint.vim
    │   │
    │   └── autoload/ale/
    │       ├── fix/
    │       │   └── registry.vim
    │       └── fixers/
    │           └── hello_fmt.vim
    │
    └── plugins/
        └── hellolang.vim

External

The advantage of an external plugin is that you don't have to get your plugin into "core" in order for others to use it.

THIS plugin is external (obviously vim-ale wouldn't want our demo language in core).

~/
├── bin/
│   ├── hello-fmt
│   └── hello-lint
│
└── .vim/
    ├── pack/plugins/start/vim-ale-hello-world/
    │   │
    │   ├── ale_linters/hellolang/
    │   │   └── hello_lint.vim
    │   │
    │   ├── autoload/hello_world/fixers/
    │   │   └── hello_fmt.vim
    │   │
    │   └── plugin/
    │       └── hello_world.vim
    │
    └── plugins/
        └── hellolang.vim

VimScript

Here's the minimum you need to know about vimscript to create a plugin:

• special directories
  • autoload
  • plugin
• functions & paths
• variables & scope

The autoload Directory

The autoload directory will LAZY LOAD functions when they are called.

The plugin Directory

Vim files in plugin will always load as soon as vim starts.

Functions & Paths

1. A function declaration looks like this:

   function! hello_world#fixers#hello_fmt#GetExecutable(buffer) abort
     " ...
   endfunction

   • function means declare and function! means declare or replace
   • The function name is GetExecutable.
   • The function path is hello_world#fixers#hello_fmt.
   • File and function paths MUST use _ (underscore) rather than - (hyphen)

2. A function invocation looks like this:

   call hello_world#fixers#hello_fmt#GetExecutable(buffer)

3. If the function is not defined at the time it is called, autoload will attempt to find it by translating its function path to a file path:

   Function Path: hello_world#fixers#hello_fmt#GetExecutable
   
   Plugin Root:  ~/.vim/pack/plugins/start/vim-ale-hello-world/
   
   Fixer Path:   ./autoload/ale/fixers/hello_fmt.vim
   

Variables & Scope

There are some special scope prefixes. The prefixes allow you to reuse the same name in different scopes or contexts.

• a:foo refers to a function argument (even if it was declared as 'foo')
• let g:foo = 'bar' refers to a global variable (accessible everywhere)
• let l:foo = 'bar' refers to a local variable (scoped to a function)
• function! s:foo() declares the function local to the current script

The Protocol

LSP Messages are HTTP-like and

• Start with Content-Type: <byte-length>
• Separated by \r\n
• Contain a JSON body

LSP has tonnes of features, very few of which are needed by vim-ale for linting.

Examples

See ./events/.

Debugging

• :messages
• :ALEInfo
• --log <logfile>

Many errors are silenced by default and not available in :messages.

Often the last few lines of :ALEInfo will contain more helpful error messages and warnings.

You can use --log <logfile> to view the output of ch_log, which can help in debugging a variety of problems.

vim --log ~/vim.log

tail -f ~/vim.log