File-change detection                                    *watch-file*
    1. Save this code to a file.
    2. Execute it with ":luafile %".
    3. Use ":Watch %" to watch any file.
    4. Try editing the file from another text editor.
    5. Observe that the file reloads in Nvim (because on_change() calls
       |:checktime|). >lua

    local w = vim.uv.new_fs_event()
    local function on_change(err, fname, status)
      -- Do work...
      vim.api.nvim_command('checktime')
      -- Debounce: stop/start.
      w:stop()
      watch_file(fname)
    end
    function watch_file(fname)
      local fullpath = vim.api.nvim_call_function(
        'fnamemodify', {fname, ':p'})
      w:start(fullpath, {}, vim.schedule_wrap(function(...)
        on_change(...) end))
    end
    vim.api.nvim_command(
      "command! -nargs=1 Watch call luaeval('watch_file(_A)', expand('<args>'))")
<
                                                         *inotify-limitations*
When on Linux you may need to increase the maximum number of `inotify` watches
and queued events as the default limit can be too low. To increase the limit,
run: >bash
    sysctl fs.inotify.max_user_watches=494462
<
This will increase the limit to 494462 watches and queued events. These lines
can be added to `/etc/sysctl.conf` to make the changes persistent.

Note that each watch is a structure in the Kernel, thus available memory is
also a bottleneck for using inotify. In fact, a watch can take up to 1KB of
space. This means a million watches could result in 1GB of extra RAM usage.

Example: TCP echo-server                                          *tcp-server*
    1. Save this code to a file.
    2. Execute it with ":luafile %".
    3. Note the port number.
    4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >lua

    local function create_server(host, port, on_connect)
      local server = vim.uv.new_tcp()
      server:bind(host, port)
      server:listen(128, function(err)
        assert(not err, err)  -- Check for errors.
        local sock = vim.uv.new_tcp()
        server:accept(sock)  -- Accept client connection.
        on_connect(sock)  -- Start reading messages.
      end)
      return server
    end
    local server = create_server('0.0.0.0', 0, function(sock)
      sock:read_start(function(err, chunk)
        assert(not err, err)  -- Check for errors.
        if chunk then
          sock:write(chunk)  -- Echo received messages to the channel.
        else  -- EOF (stream closed).
          sock:close()  -- Always close handles to avoid leaks.
        end
      end)
    end)
    print('TCP echo-server listening on port: '..server:getsockname().port)
<
Multithreading                                            *lua-loop-threading*

Plugins can perform work in separate (os-level) threads using the threading
APIs in luv, for instance `vim.uv.new_thread`. Each thread has its own
separate Lua interpreter state, with no access to Lua globals on the main
thread. Neither can the editor state (buffers, windows, etc) be directly
accessed from threads.

A subset of the `vim.*` stdlib is available in threads, including:

- `vim.uv` with a separate event loop per thread.
- `vim.mpack` and `vim.json` (useful for serializing messages between threads)
- `require` in threads can use Lua packages from the global |package.path|
- `print()` and `vim.inspect`
- `vim.diff`
- Most utility functions in `vim.*` that work with pure Lua values, like
  `vim.split`, `vim.tbl_*`, `vim.list_*`, etc.
- `vim.is_thread()` returns true from a non-main thread.


==============================================================================
VIM.HL                                                                *vim.hl*

vim.hl.on_yank({opts})                                      *vim.hl.on_yank()*
    Highlight the yanked text during a |TextYankPost| event.

    Add the following to your `init.vim`: >vim
        autocmd TextYankPost * silent! lua vim.hl.on_yank {higroup='Visual', timeout=300}
<