Interactive neovim scratchpad for lua

Luapad runs your code in context with overwritten print function and displays the captured input as virtual text right there, where it was called - in real time!

Luapad adds Lua command (as native lua command extension) with deep function completion.

WARNING!!!

Luapad evaluates every code that you put in it, so be careful what you type in, specially if it's system calls, file operations etc. Also calling functions like nvim_open_win isn't good idea, because every single change in buffer is evaluated (you will get new window with every typed char :D).

Luapad was designed to mess with small nvim lua code chunks. It probably will not work well with big "real" / "production" scripts.

All thoughts or/and error reports are welcome.

Installation

With vim-plug:

    Plug 'rafcamlet/nvim-luapad'

With packer.nvim and Neovim >= v0.8.0:

    use 'rafcamlet/nvim-luapad'

In versions of Neovim prior to v0.8.0, the CursorHold event is buggy. If you're using an older version, it's recomended to use this fix:

    use { 'rafcamlet/nvim-luapad', requires = "antoinemadec/FixCursorHold.nvim" }

Usage

Luapadd provides three different commands, that will help you with developing neovim plugins in lua:

• Luapad - which open interactive scratch buffer with real time evaluation.
• LuaRun - which run content of current buffer as lua script in new scope. You do not need to write file to disc or have to worry about overwriting functions in global scope.
• Lua - which is extension of native lua command with function completion. This command will be removed in the next release, because the current version of Neovim has built-in cmd completion.

From version 0.2 luapad will move towards lua api exposure. Several useful functions are already available.

require('luapad').init() -- same as Luapad command

-- Creates a new luapad instance and attaches it to the current buffer.
-- Optionally, you can pass a context table to it, the elements of which will be
-- available during the evaluation as "global" variables.
require('luapad').attach({
  context = { return_4 =  function() return 4 end }
})

-- Detaches current luapad instance from buffer, which just means turning it off. :)
require('luapad').detach()

-- Toggles luapad in current buffer.
require('luapad').toggle({
  context = { return_4 =  function() return 4 end }
})

-- You can also create new luapad instance by yourself, which can be helpfull if you
-- want to attach it to a buffer different than the current one.
local buffer_handler = 5
require('luapad.evaluator'):new {
  buf = buffer_handler,
  context = { a = 'asdf' }
}:start()

-- luapad/run offers a run function (same as the LuaRun command) but allows you
-- to specify a context tbl
require 'luapad.run'.run {
  context = {
    print = function(str) print(string.upper(str)) end
  }
}

-- If you turn off evaluation on change (and move) you can trigger it manualy by:
local luapad = require('luapad.evaluator'):new{buf = vim.api.nvim_get_current_buf()}
luapad:start()
luapad:eval()

-- You can always access current luapad instance by:
local luapad = require 'luapad.state'.current()
luapad:eval()

-- ...or iterate through all instances
for _, v in ipairs(require('luapad.state').instances) do
  v:eval()
end

Configuration

You can configure luapad via require('luapad').setup({}) function (or its alias config). Configuration via vim globals is disabled. If you want to use old configuration method, please checkout version 0.2.

Example configuration (note it isn't the default one!)

require('luapad').setup {
  count_limit = 150000,
  error_indicator = false,
  eval_on_move = true,
  error_highlight = 'WarningMsg',
  split_orientation = 'horizontal',
  on_init = function()
    print 'Hello from Luapad!'
  end,
  context = {
    the_answer = 42,
    shout = function(str) return(string.upper(str) .. '!') end
  }
}

Statusline

Luapad has ready to use lightline function_components.

let g:lightline = {
      \ 'active': {
      \   'left': [
      \     [ 'mode', 'paste' ],
      \     [ 'readonly', 'filename', 'modified' ],
      \     [ 'luapad_msg']
      \   ],
      \ 'right': [
      \   ['luapad_status'],
      \   ['lineinfo'],
      \   ['percent'],
      \ ],
      \ },
      \ 'component_function': {
      \   'luapad_msg': 'luapad#lightline_msg',
      \   'luapad_status': 'luapad#lightline_status',
      \ },
      \ }

But you can also create your own integration, using lua functions require'luapad.statusline'.status() and require'luapad.statusline'.msg().

local function luapad_color()
  if require('luapad.statusline').status() == 'ok' then
    return colors.green
  else
    return colors.red
  end
end

require('galaxyline').section.right[1] = {
  Luapad = {
    condition = require('luapad.state').current,
    highlight = { luapad_color(), colors.bg },
    provider = function()
      vim.cmd('hi GalaxyLuapad guifg=' .. luapad_color())
      local status = require('luapad.statusline').status()
      return string.upper(tostring(status))
    end
  }
}

Types of errors

Luapad separates errors into 3 categories:

Changelog

v0.3

• Drop viml configuration
• Improve preview window resizing (although it still needs some work)
• Fix "file no longer available" error
• Galaxyline example added to readme
• Upgrading specs
• Other minor upgrades and refactor

v0.2

• Better nvim native lsp integration (now you should have lsp completion in luapad buffers)
• Enable creation of multiple luapads instances
• Allow luapad to be attached to an existing buffer
• Add on_init callback
• Allow providing evaluation context for luapad buffers
• Allow configure luapad via lua
• Add eval_on_move and eval_on_change settings
• Expose luapad lua api
• Replace g:luapad_status and g:luapad_msg variables by status() and msg() lua functions.
• Now luapad print function print also nil values

TODO

• Allow changing orientation of the preview window

Shameless self promotion

If you want to start your adventure with writing lua plugins and are you are wondering where to begin, you can take a look at the links below.

1. How to write neovim plugins in Lua
2. How to make UI for neovim plugins in Lua