docs: update help and docs

Author: YaroSpace

README.md

@@ -76,24 +76,27 @@ 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
   },
   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 +111,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 +145,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 +279,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,6 +9,7 @@ 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
   },
   window = {

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,17 +247,16 @@ 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]
@@ -442,7 +452,7 @@ local get_external_evaluator = function(buf, lang)
     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)
 

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)
 

spec/unit/utils_spec.lua

@@ -147,19 +147,42 @@ describe('lua-console.utils', function()
     end)
 
     it('provides access to context', function()
-      config.setup { buffer = { preserve_context = true } }
+      config.setup { buffer = { preserve_context = true, strip_local = false } }
+
+      code = { 'test_1 = 5; b = 10; local c = 100' }
+      lua_evaluator(code)
+
+      code = { 'test_1 = test_1 + 5; b = b * 10; c = c - 50' }
+      lua_evaluator(code)
+
+      code = { '_ctx' }
+
+      expected = h.to_string([[
+				{
+				  b = 100,
+				  test_1 = 10
+				}
+			]])
+
+      result = lua_evaluator(code)
+      assert.has_string(result, expected)
+    end)
+
+    it('strips local declaration', function()
+      config.setup { buffer = { preserve_context = true, strip_local = true } }
 
       code = { 'test_1 = 5; b = 10; local c = 100' }
       lua_evaluator(code)
 
       code = { 'test_1 = test_1 + 5; b = b * 10; c = c - 50' }
       lua_evaluator(code)
 
-      code = { '_ctx()' }
+      code = { '_ctx' }
 
       expected = h.to_string([[
 				{
 				  b = 100,
+				  c = 50,
 				  test_1 = 10
 				}
 			]])