docs: update help and docs

Author: YaroSpace

.luacheckrc

@@ -11,21 +11,22 @@ ignore = {
   -- Neovim lua API + luacheck thinks variables like `vim.wo.spell = true` is
   -- invalid when it actually is valid. So we have to display rule `W122`.
   --
-  "122", -- setting read-only field of vim...
-  "631",    -- max_line_length
-  "621", -- incostistant indentation
-  "611" -- line with whitespace
+  '122', -- setting read-only field of vim...
+  '631', -- max_line_length
+  '621', -- incostistant indentation
+  '611', -- line with whitespace
+  '111', -- setting non-standard global variable, i.e. _
 }
 
 -- Global objects defined by the C code
 read_globals = {
-  "vim",
-  "Lua_console",
-  "describe",
-  "it",
-  "assert"
+  'vim',
+  'Lua_console',
+  'describe',
+  'it',
+  'assert',
 }
 
 exclude_files = {
-  "spec/utfTerminal.lua"
+  'spec/utfTerminal.lua',
 }

README.md

@@ -76,24 +76,28 @@ opts = {
     preserve_context = true,  -- preserve results between evaluations
     strip_local = true, -- remove local identifier from source code
     print_one_line_results = true, -- prints one line results, even if already shown as virtual text
+    notify_result = false, -- notify result
+    clear_before_eval = false, -- clear output below result prefix before evaluation of the whole buffer
+    process_timeout = 2 * 1e5, -- number of instructions to process before timeout
   },
   window = {
     border = 'double', -- single|double|rounded
     height = 0.6, -- percentage of main window
   },
   mappings = {
-    toggle = '`',
-    attach = '<Leader>`',
-    quit = 'q',
-    eval = '<CR>',
-    eval_buffer = '<S-CR>',
-    open = 'gf',
-    messages = 'M',
-    save = 'S',
-    load = 'L',
-    resize_up = '<C-Up>',
-    resize_down = '<C-Down>',
-    help = '?'
+    toggle = '`', -- toggle console
+    attach = '<Leader>`', -- attach console to a buffer
+    quit = 'q', -- close console
+    eval = '<CR>', -- evaluate code
+    eval_buffer = '<S-CR>', -- evaluate whole buffer
+    kill_ps = '<Leader>K', -- kill evaluation process
+    open = 'gf', -- open link
+    messages = 'M', -- load Neovim messages
+    save = 'S', -- save session
+    load = 'L', -- load session
+    resize_up = '<C-Up>', -- resize up
+    resize_down = '<C-Down>', -- resize down
+    help = '?' -- help
   },
 }
 ```
@@ -108,7 +112,7 @@ opts = {
 - Install, press the mapped key `` ` `` and start exploring. 
 - Enter code as normal, in insert mode.
 - Hit `Enter` in normal mode to evaluate a variable, statement or an expression in the current line. 
-- Visually select a region or range of lines and press `Enter` to evaluate the code in the range or use `<S-Enter>` to evaluate the whole console.
+- Visually select a region or a range of lines and press `Enter` to evaluate the code in the range or use `<S-Enter>` to evaluate the whole console.
 - The evaluation of the last line is returned and printed, so no `return` is needed in most cases.  
   To avoid noise, if the return of your execution is `nil`, e.g. from a loop or a function without return, it will not be printed, but shown as virtual text. 
   The result of assignments on the last line will be also shown as virtual text.
@@ -142,7 +146,7 @@ If you want the context to be cleared before every execution, set `preserve_cont
 
 There are two functions available within the console:
 
-- `_ctx()` - will print the contents of the context
+- `_ctx` - will print the contents of the context
 - `_ctx_clear()` - clears the context
 
 <br>
@@ -276,6 +280,9 @@ There are two functions available within the console:
 
 <br>
 
+- If you need to kill the evaluation process, press `<Leader>K`.
+- You can use `_ex` command to get a reference to the evaluator process, which can be queried for status with `:is_closing()` and stopped with `:kill()`.
+
 ## Alternatives and comparison
 
 There are a number of alternatives available, notably:

lua/lua-console/config.lua

@@ -9,7 +9,9 @@ local default_config = {
     preserve_context = true, -- preserve results between evaluations
     strip_local = true, -- remove local identifier from source code
     print_one_line_results = true, -- prints one line results, even if already shown as virtual text
+    notify_result = false, -- notify result
     clear_before_eval = false, -- clear output below result prefix before evaluation of the whole buffer
+    process_timeout = 2 * 1e5, -- number of instructions to process before timeout
   },
   window = {
     relative = 'editor',

lua/lua-console/utils.lua

@@ -50,8 +50,8 @@ end
 ---@param lnum number line number
 ---@param position string virtual text position
 ---@param highlight string higlight group
-local show_virtual_text = function(buf, id, text, lnum, position, highlight)
-  local ns = vim.api.nvim_create_namespace('Lua-console')
+local show_virtual_text = function(buf, ns, id, text, lnum, position, highlight)
+  ns = ns == 0 and vim.api.nvim_create_namespace('Lua-console') or ns
 
   local ext_mark = vim.api.nvim_buf_get_extmark_by_id(0, ns, id, {})
   if #ext_mark > 0 then vim.api.nvim_buf_del_extmark(0, ns, id) end
@@ -69,36 +69,42 @@ end
 
 local toggle_help = function(buf)
   local cm = config.mappings
-  local ns = vim.api.nvim_create_namespace('Lua-console')
+  local ns = vim.api.nvim_create_namespace('Lua-console-help')
   local ids = vim.api.nvim_buf_get_extmarks(buf, ns, 0, -1, {})
   local message
 
   if #ids == 0 or ids[1][1] == 2 then
-    vim.api.nvim_buf_del_extmark(buf, ns, 2)
+    vim.api.nvim_buf_clear_namespace(buf, ns, 0, -1)
 
     message = cm.help .. ' - help  '
-    show_virtual_text(buf, 1, message, 0, 'right_align', 'Comment')
+    show_virtual_text(buf, ns, 1, message, 0, 'right_align', 'Comment')
   elseif ids[1][1] == 1 then
     vim.api.nvim_buf_del_extmark(buf, ns, 1)
 
-    message =
-      [[%s - eval a line or selection, %s - eval buffer, %s - kill process, %s - open file, %s - load messages, %s - save console, %s - load console, %s/%s - resize window, %s - toggle help]]
-    message = string.format(
-      message,
-      cm.eval,
-      cm.eval_buffer,
-      cm.kill_ps,
-      cm.open,
-      cm.messages,
-      cm.save,
-      cm.load,
-      cm.resize_up,
-      cm.resize_down,
-      cm.help
-    )
+    local keys = {
+      cm.eval .. ' - eval a line or selection',
+      cm.eval_buffer .. ' - eval buffer',
+      cm.kill_ps .. ' - kill process',
+      cm.open .. ' - open file',
+      cm.messages .. ' - load messages',
+      cm.save .. ' - save console',
+      cm.load .. ' - load console',
+      cm.resize_up .. ' - resize window up',
+      cm.resize_down .. ' - resize window down',
+      cm.help .. ' - toggle help',
+      ' ',
+      '_ctx - get current context',
+      '_ctx_clear() - clear current context',
+      '_ex - get current evaluator process',
+      '_ex:kill() - kill evaluator process',
+      '_ex:is_closing() - get process status',
+    }
 
     local visible_line = vim.fn.line('w0')
-    show_virtual_text(buf, 2, message, visible_line - 1, 'overlay', 'Comment')
+    vim.iter(keys):enumerate():each(function(i, key)
+      _ = vim.api.nvim_buf_line_count(buf) < i and vim.api.nvim_buf_set_lines(buf, i - 1, -1, false, { '' })
+      show_virtual_text(buf, ns, i + 1, key .. '  ', visible_line + i - 2, 'right_align', 'Comment')
+    end)
   end
 end
 
@@ -208,6 +214,11 @@ local print_to_buffer = function(...)
   vim.list_extend(print_buffer, ret)
 end
 
+local notify_result = function(ret)
+  if not config.buffer.notify_result then return end
+  vim.notify(to_string(ret), vim.log.levels.INFO)
+end
+
 ---@param buf number
 ---@param lines string[] Text to append to current buffer after current selection
 ---@param lnum? number|nil Line number to append from
@@ -227,7 +238,7 @@ local append_current_buffer = function(buf, lines, lnum)
   local _, last_assigned_val, last_assignment_lnum = get_last_assignment()
   if last_assignment_lnum then
     last_assigned_val = to_string(pretty_print(last_assigned_val), '', true)
-    show_virtual_text(buf, 3, prefix .. last_assigned_val, last_assignment_lnum - 1, 'eol', 'Comment')
+    show_virtual_text(buf, 0, 3, prefix .. last_assigned_val, last_assignment_lnum - 1, 'eol', 'Comment')
   end
 
   if vim.tbl_contains(empty_results, line) then
@@ -236,21 +247,20 @@ local append_current_buffer = function(buf, lines, lnum)
     virtual_text = get_line_assignment(vim.fn.getbufline(buf, lnum, lnum)) or line -- ! resets env._last_assignment by calling evaluator
 
     if last_assignment_lnum ~= lnum then
-      show_virtual_text(buf, 4, prefix .. virtual_text, lnum - 1, 'eol', 'Comment')
+      show_virtual_text(buf, 0, 4, prefix .. virtual_text, lnum - 1, 'eol', 'Comment')
     end
   end
 
   if #lines == 0 then return end
 
   if #lines == 1 and last_assignment_lnum ~= lnum and not config.buffer.show_one_line_results then
     virtual_text = lines[1]
-    show_virtual_text(buf, 4, prefix .. virtual_text, lnum - 1, 'eol', 'Comment')
-
-    return
+    return show_virtual_text(buf, 0, 4, prefix .. virtual_text, lnum - 1, 'eol', 'Comment')
+      and notify_result(virtual_text)
   end
 
   lines[1] = prefix .. lines[1]
-  table.insert(lines, 1, '') -- insert an empty line
+  _ = not config.buffer.clear_before_eval and table.insert(lines, 1, '') -- insert an empty line
 
   vim.api.nvim_buf_set_lines(buf, lnum, lnum, false, lines)
 end
@@ -337,6 +347,17 @@ function get_ctx(buf)
   return setmetatable(env, mt)
 end
 
+local function run_code(code)
+  debug.sethook(function()
+    error('EvaluationTimeout')
+  end, '', config.buffer.process_timeout)
+
+  local result = { xpcall(code, debug.traceback) }
+  debug.sethook()
+
+  return result
+end
+
 --- Evaluates Lua code and returns pretty printed result with errors if any
 --- @param lines string[] table with lines of Lua code
 --- @param ctx? table environment to execute code in
@@ -359,25 +380,20 @@ function lua_evaluator(lines, ctx)
   lines = to_string(lines)
   lines = config.buffer.strip_local and lines:gsub('local ', '') or lines
 
-  local code, error = load(lines, 'Lua console: ', 't', env)
-  if error then return to_table(error) end
+  local code, errors = load(lines, 'Lua console: ', 't', env)
+  if errors then return to_table(errors) end
 
   print_buffer = {}
 
-  ---@cast code function
-  local result = { xpcall(code, debug.traceback) }
-  local status, err = result[1], result[2]
+  local result = run_code(code)
+  local status, err = unpack(result)
 
   if status then
     table.remove(result, 1)
-
-    if #result > 0 then
-      print_to_buffer(unpack(result))
-    else
-      print_to_buffer(nil)
-    end
+    _ = #result > 0 and print_to_buffer(unpack(result)) or print_to_buffer(nil)
   else
-    vim.list_extend(print_buffer, clean_stacktrace(err))
+    err = err:match('EvaluationTimeout') and { 'Process timeout exceeded' } or clean_stacktrace(err)
+    vim.list_extend(print_buffer, err)
   end
 
   return print_buffer
@@ -433,16 +449,16 @@ local get_external_evaluator = function(buf, lang)
   opts.on_exit = function(system_completed)
     vim.schedule(function()
       vim.api.nvim_buf_del_extmark(buf, ns, 10)
+      _ = fun and fun(system_completed)
     end)
-    _ = fun and fun(system_completed)
   end
 
   return function(lines)
     local cmd = vim.tbl_extend('force', {}, lang_config.cmd)
     local code = (lang_config.code_prefix or '') .. to_string(remove_indentation(lines)) -- some languages, like python are concerned with indentation
     table.insert(cmd, code)
 
-    ns = show_virtual_text(buf, 10, 'Running...', 0, 'right_align', 'Comment')
+    ns = show_virtual_text(buf, 0, 10, 'Running...  ', vim.fn.line('w0'), 'right_align', 'Comment')
 
     local status, id = pcall(vim.system, cmd, opts, opts.on_exit)
 
@@ -491,7 +507,7 @@ end
 local clear_buffer = function(buf)
   for i = vim.api.nvim_buf_line_count(buf), 0, -1 do
     if vim.fn.getline(i):match('^' .. config.buffer.result_prefix) then
-      vim.api.nvim_buf_set_lines(buf, i - 1, -1, false, { '' })
+      vim.api.nvim_buf_set_lines(buf, i - 1, -1, false, {})
       break
     end
   end

spec/unit/external_evals_spec.lua

@@ -211,7 +211,6 @@ describe('external evaluators', function()
             text = 'Test 5',
             timeout = 20,
             detach = 'Test 7',
-            on_exit = 'Test 8',
           },
         },
       }
@@ -233,20 +232,21 @@ describe('external evaluators', function()
   end)
 
   it('uses removes indentation from code', function()
-      config.setup {
-        external_evaluators = { ruby = { code_prefix = '' }, }, }
-
-      content = {
-		    '  a = [1, 3, 5, 7, 9]',
-		    '    for val in a:',
-			  '      print(val)'
-		  }
-
-      expected = {
-		    'a = [1, 3, 5, 7, 9]',
-		    '  for val in a:',
-			  '    print(val)'
-		  }
+    config.setup {
+      external_evaluators = { ruby = { code_prefix = '' } },
+    }
+
+    content = {
+      '  a = [1, 3, 5, 7, 9]',
+      '    for val in a:',
+      '      print(val)',
+    }
+
+    expected = {
+      'a = [1, 3, 5, 7, 9]',
+      '  for val in a:',
+      '    print(val)',
+    }
 
     h.set_buffer(buf, content)
 

spec/unit/lua-console_spec.lua

@@ -23,7 +23,7 @@ describe('lua-console.nvim', function()
     it('sets up with custom config', function()
       config = {
         buffer = {
-          result_prefix = '$$ '
+          result_prefix = '$$ ',
         },
         window = {
           border = 'single',
@@ -32,6 +32,7 @@ describe('lua-console.nvim', function()
           toggle = '!#',
           attach = '!`',
           eval = '$#',
+          kill_ps = '!K',
         },
       }
 
@@ -107,6 +108,7 @@ describe('lua-console.nvim', function()
         local mappings = config.mappings
         mappings.toggle = nil
         mappings.attach = nil
+        mappings.kill_ps = nil
 
         local maps = h.get_maps(buf)