[New features] Execution context can be inspected and preserved betwe…

…en executions

[Improvements] Truncated stacktraces can be followed. Returning nil will show in virtual text, instead of printing.
[Fixes] Mapping for help toggle. Pretty printing results of functions that return multiple variables

fixed help message and added specs

Feature: preserving context and specs

improved printing algorithm

added truncated stacktrace inference

fixed handling of mupliple arguments by pretty print

feature supressing printing nil in favour of virtual text

.github/workflows/release-luarocks.yml

@@ -18,3 +18,17 @@ jobs:
         uses: nvim-neorocks/luarocks-tag-release@v7
         env:
           LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}
+        with:
+          name: lua-console.nvim
+          labels:  |
+            neovim
+            neovim-plugin
+        copy_directories:  |
+          doc
+          spec
+        test_dependencies: |
+          busted
+        summary: lua-console.nvim - a handy scratch pad / REPL / debug console for Lua development and Neovim exploration and configuration.
+        detailed_description:  |
+          Acts as a user friendly replacement of command mode - messages loop and 
+          as a handy scratch pad to store and test your code gists.

.luacheckrc

@@ -26,4 +26,6 @@ read_globals = {
   "assert"
 }
 
-exclude_files = {  }
+exclude_files = {
+  "spec/utfTerminal.lua"
+}

Makefile

@@ -14,7 +14,10 @@ stylua:
 
 test:
 	eval $(luarocks path --lua-version 5.1 --bin)
-	busted --run unit
+	busted -o spec/utfTerminal.lua --run unit
 
 watch:
-	while sleep 0.1; do ls -d spec/**/*.lua | entr -d -c make test; done
+	while sleep 0.1; do ls -d spec/**/*.lua | entr -d -c busted -o spec/utfTerminal.lua --run unit; done
+
+watch_current:
+	while sleep 0.1; do ls -d spec/**/*.lua | entr -d -c busted -o spec/utfTerminal.lua --run unit -t=current; done

README.md

@@ -16,7 +16,7 @@ syntax error and retyping the whole thing again, copying the paths from error st
 - Evaluate single line expressions
 - Evaluate visually selected lines of code
 - Pretty print Lua objects, including function details and their source paths
-- Show normal and error output in the console, including output of print(), errors and stacktraces. 
+- Show normal and error output in the console, including output of `print()`, errors and stacktraces. 
 - Syntax highlighting and autocompletion
 - Load Neovim’s messages into console for inspection and copy/paste
 - Open links from stacktraces and function sources
@@ -34,12 +34,17 @@ return {
   lazy = true, keys = "`", opts = {},
 }
 ```
-otherwise, install with your favourite package manager and add
+otherwise, install with your favorite package manager and add
 `require('lua-console').setup({opts})` somewhere in your config.
 
 
 ## ⚙️  Configuration
 
+> [!NOTE]
+> All settings are very straight forward, but please read below about [`preserve_context`](#-notes-on-globals-locals-and-preserving-execution-context) option.
+
+Mappings are local to the console, except the one for toggling, which is - `` ` `` by default.
+
 <details><summary>Default Settings</summary>
 
 <!-- config:start -->
@@ -49,13 +54,12 @@ opts = {
   buffer = {
     prepend_result_with = '=> ',
     save_path = vim.fn.stdpath('state') .. '/lua-console.lua',
-    load_on_start = true -- load saved session on first entry
+    load_on_start = true, -- load saved session on first entry
+    preserve_context = true -- preserve context between executions
   },
   window = {
-    anchor = 'SW',
     border = 'double',  -- single|double|rounded
     height = 0.6, -- percentage of main window
-    zindex = 1,
   },
   mappings = {
     toggle = '`',
@@ -71,20 +75,61 @@ opts = {
   }
 }
 ```
-
 <!-- config:end -->
 
 </details>
 
+
 ## 🚀 Usage (with default mappings)
 
-- Install, hit the mapped key `` ` `` and start exploring. 
+- 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 range of lines and press `Enter` to evaluate the code in the range. 
-- The evaluation of the last line is returned and printed, so no `return` is needed in most cases.
-- Use `print()` in your code to output the result into the console.  Objects and functions are pretty printed. 
+- The evaluation of the last line is returned and printed, so no `return` is needed in most cases.  
+  To avoid noise, if the only return of your execution is `nil`, e.g. from an assignment, like `a = 1`, it will not be printed, but shown as virtual text.
+- Use `print()` in your code to output the results into the console.  Accepts variable number of arguments, e.g. `print(var_1, var_2, ...)`.
+- Objects and functions are pretty printed, with function source paths.
+- Press `gf` to follow the paths in stack traces and to function sources. Truncated paths work too.
+
+> [!NOTE]
+> This is especially useful when you want to see where a function was redefined at runtime.  So, if you evaluate `vim.lsp.handlers['textDocument/hover']` for 
+  example, you can jump to its current definition, while Lsp/tags would take you to the original one.
+
 - Press `M` to load Neovim messages into the console. 
-- Press `gf` to follow the paths in stack traces and to function sources. 
 - Use `S` and `L` to save / load the console session to preserve history of your hacking. 
 - You can resize the console with `<C-Up>` and `<C-Down>`.
+
+
+## 📓 Notes on globals, locals and preserving execution context
+
+> [!IMPORTANT]
+> By default, the option `preserve_context` is on, which means that the context is preserved between executions. 
+
+All the code executed in the console is evaluated in isolated environment.  This means that any variables you declare will not be persisted in Neovim's global 
+environment, although all global variables are accessible.  If you want purposefully to alter the global state, use `_G.My_variable = ..`.
+
+The option `preserve_context` means that if you assign variables without `local`, they will be stored in console's local context and preserved between separate executions. 
+So, if you first execute `a = 1`, then `a = a + 1` and then `a` - you will get `2`. Variables with `local` are not preserved.  
+
+If you want a classic REPL experience, when the context is cleared on every execution, set `preserve_context = false`.
+
+There are two functions available within the console:
+
+- `_ctx()` - will print the contents of the context
+- `_ctx_clear()` - clears the context
+
+
+## Alternatives and comparison
+
+There are a number of alternatives available, notably:
+
+- [Luapad](https://github.com/rafcamlet/nvim-luapad)
+- [Luadev](https://github.com/bfredl/nvim-luadev)
+- [SnipRun](https://github.com/michaelb/sniprun)
+
+Initially, when starting with Lua and Neovim, I tried all the REPLs/code runners I could find.  However, I was not satisfied with all of them in one way or another.  
+Lua-console is an attempt to combine the best features of all of them, like REPL / scratch pad / code runner, while leaving the UX and config simple.
+
+
+## 🔥 All feedback and feature requests are very welcome!  Enjoy!