feat: allow evaluating whole buffer

feat(attach_to_buffer): add user command

Makefile

@@ -9,7 +9,7 @@ watch = '*.lua'
 
 .PHONY: api_documentation luacheck stylua test
 
-all: test luacheck
+all: test luacheck stylua
 
 api_documentation:
 	nvim -u scripts/make_api_documentation/init.lua -l scripts/make_api_documentation/main.lua

README.md

@@ -3,7 +3,9 @@
 **lua-console.nvim** - is a handy scratch pad / REPL / debug console for Lua development and Neovim exploration and configuration.  
 Acts as a user friendly replacement of command mode - messages loop and as a handy scratch pad to store and test your code gists.
 
-<img src="doc/demo.gif">
+***Update: Although it originated as a tool for Lua development, it has now evolved into supporting other languages too. See [`evaluating other languages`](#evaluating-other-languages).***
+
+<br/><img src="doc/demo.gif">
 
 ## 💡 Motivation
 
@@ -13,15 +15,15 @@ syntax error and retyping the whole thing again, copying the paths from error st
 
 ## ✨ Features
 
-- Evaluate single line expressions
-- Evaluate visually selected lines of code
+- Evaluate single line expressions and statements, visually selected lines of code or the whole buffer
 - 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/buffer, 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
-- Save / Load console session
-- Use as scratch pad for code gists
+- Save / Load / Autosave console session
+- Use as a scratch pad for code gists
+- Attach code evaluators to any buffer
 
 
 ## 📦 Installation
@@ -35,43 +37,48 @@ return {
 }
 ```
 otherwise, install with your favorite package manager and add
-`require('lua-console').setup({ your_custom_options })` somewhere in your config.
+`require('lua-console').setup { custom_options }` 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.
+> All settings are self explanatory, 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.
+Mappings are local to the console, except the ones for toggling the console - `` ` `` and attaching to a buffer - ``<Leader>` ``. All mappings can be overridden in your custom 
+config. If you want to delete a mapping - set its value to `false`.
 
 <details><summary>Default Settings</summary>
 
 <!-- config:start -->
-
+`config.lua`
 ```lua
 opts = {
   buffer = {
-    prepend_result_with = '=> ',
+    result_prefix = '=> ',
     save_path = vim.fn.stdpath('state') .. '/lua-console.lua',
-    load_on_start = true, -- load saved session on first entry
-    preserve_context = true -- preserve context between executions
+    autosave = true, -- autosave on console hide / close
+    load_on_start = true, -- load saved session on start
+    preserve_context = true,  -- preserve results between evaluations
   },
   window = {
-    border = 'double',  -- single|double|rounded
+    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 = '?'
-  }
+  },
 }
 ```
 <!-- config:end -->
@@ -84,7 +91,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 range of lines and press `Enter` to evaluate the code in the range. 
+- Visually select 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.
@@ -97,22 +104,23 @@ opts = {
   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. 
-- Use `S` and `L` to save / load the console session to preserve history of your hacking. 
+- Use `S` and `L` to save / load the console session to preserve history of your hacking.  If the `autosave` option is on, the contents of the console will be 
+  saved whenever it is toggled or closed. 
 - 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. 
+> By default, the option `preserve_context` is on, which means that the execution context is preserved between evaluations. 
 
-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 = ..`.
+All the code executed in the console is evaluated in isolated environment.  This means that any variables you declare without the `local` keyword 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. 
+The option `preserve_context` means that although you declare 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`.
+If you want the context to be cleared before every execution, set `preserve_context = false`.
 
 There are two functions available within the console:
 
@@ -124,27 +132,117 @@ There are two functions available within the console:
 
 ### Attaching code evaluator to other buffers
 
-- The evaluator behind the console can be attached to any buffer by calling or mapping `require('lua-console.utils).attach(buf_number)` where `buf_number` can be omitted for current buffer.
-  You will be able to evaluate the code as in the console and follow links.  The evaluators and their contexts are isolated for each attached buffer.
-- You can also setup external code runners for languages other than lua.
-
+- The evaluator behind the console can be attached/detached to any buffer by pressing ``<Leader>` `` or executing command `LuaConsole AttachToggle`.
+  You will be able to evaluate the code in the buffer as in the console and follow links.  The evaluators and their contexts are isolated for each attached buffer.
 
 ### Evaluating other languages
 
-- It is possible to setup external code executors for other languages.  There are examples for `ruby, racket` in the `exev_config.lua`. `Python, go, rust` - are WIP. 
-- The language is determined either from the buffer type, which you can set manually with `vim.bo.filetype = 'lang'` or by prefixing your code with `===lang` on the line above. 
-  The prefix can be changed in the config, e.g.
+#### Setting up
+
+- It is possible to setup external code executors for other languages.  Evaluators for `ruby` and `racket` are working out of the box, support for other languages is coming. 
+  Meanwhile, you can easily setup your own language.  
+- Below is the default configuration which can be overridden or extended by your custom config (`default_process_opts` will be 
+  replaced by language specific opts), e.g. a possible config for `python` could be:
+
+  ```lua
+  require('lua-console').setup { 
+    external_evaluators = {
+      python = {
+        cmd = { 'python3', '-c' },
+        env = { PYTHONPATH = '~/projects' },
+        timeout = 100000,
+        formatter = function(result) do_something; return result end,
+      },
+    }
+  }
+  ```
+
+- You can also setup a custom formatter to format the evaluator output before appending results to the console or buffer. Example is in the config.
+
+  <details><summary>Default External Evaluators Settings</summary>
+
+  <!-- config:start -->
+  `exev_config.lua`
+  ```lua
+  ---Formats the output of external evaluator
+  ---@param result string[]
+  ---@return string[]
+  local function generic_formatter(result)
+    local width = vim.o.columns
+    local sep_start = ('='):rep(width)
+    local sep_end = ('='):rep(width)
+
+    table.insert(result, 1, sep_start)
+    table.insert(result, sep_end)
+
+    return result
+  end
+
+  local external_evaluators = {
+    lang_prefix = '===',
+    default_process_opts = {
+      cwd = nil,
+      env = { EMPTY = '' },
+      clear_env = false,
+      stdin = false,
+      stdout = false,
+      stderr = false,
+      text = true,
+      timeout = nil,
+      detach = false,
+      on_exit = nil,
+    },
+
+    ruby = {
+      cmd = { 'ruby', '-e' },
+      env = { RUBY_VERSION = '3.3.0' },
+      code_prefix = '$stdout.sync = true;',
+      formatter = generic_formatter,
+    },
+
+    racket = {
+      cmd = { 'racket', '-e' },
+      formatter = generic_formatter,
+    },
+  }
 
+  return external_evaluators
   ```
+  <!-- config:end -->
+
+  </details>
+
+  #### Usage
+
+- The language evaluator is determined either from (in order of precedence):
+
+  - The code prefix `===lang` on the line above your code snippet, in which case it only applies to the snippet directly below and it should be included in the selection 
+  for evaluation. The prefix can be changed in the config.
+  - The code prefix on the top line of the console/buffer, in which case it applies to the whole buffer.
+  - The file type of the buffer. 
+  <br/> 
+
+  ```racket
+  ===racket
+
+
+    (define (log str)
+      (displayln (format "~v" str)))
+
+
+    (define (fact n)
+      (if (= n 0)
+          1
+          (* n (fact (- n 1)))))
+
+    (displayln (fact 111))
+  ```
+
+  ```ruby
   ===ruby
     5.times { puts 'Hey' }
   ```
 
-- You can also setup a custom formatter to format the executor output before appending results to the console or buffer. Example is in the config.
-- Unlike lua, the context with external evaluators is not preserved yet, but it is WIP.
-u
-
-
 ## Alternatives and comparison
 
 There are a number of alternatives available, notably:

lua/lua-console.lua

@@ -23,7 +23,7 @@ local get_or_create_buffer = function()
   vim.diagnostic.enable(false, { bufnr = buf })
 
   mappings.set_console_mappings(buf)
-  mappings.set_evaluator_mappings(buf)
+  mappings.set_evaluator_mappings(buf, true)
   mappings.set_console_autocommands(buf)
 
   if config.buffer.load_on_start then utils.load_saved_console(buf) end
@@ -78,10 +78,8 @@ local setup = function(opts)
   mappings = require('lua-console.mappings')
   utils = require('lua-console.utils')
 
-  vim.keymap.set('n', config.mappings.toggle, '', {
-    callback = toggle_console,
-    desc = 'Toggle Lua console',
-  })
+  mappings.set_global_mappings()
+  mappings.set_console_commands()
 
   return config
 end

lua/lua-console/config.lua

@@ -4,9 +4,9 @@ local default_config = {
   buffer = {
     result_prefix = '=> ',
     save_path = vim.fn.stdpath('state') .. '/lua-console.lua',
-    autosave = true,
+    autosave = true, -- autosave on console hide / close
     load_on_start = true, -- load saved session on start
-    preserve_context = true,
+    preserve_context = true, -- preserve results between evaluations
   },
   window = {
     relative = 'editor',
@@ -20,8 +20,10 @@ local default_config = {
   },
   mappings = {
     toggle = '`',
+    attach = '<Leader>`',
     quit = 'q',
     eval = '<CR>',
+    eval_buffer = '<S-CR>',
     open = 'gf',
     messages = 'M',
     save = 'S',

lua/lua-console/exev_config.lua

@@ -2,8 +2,9 @@
 ---@param result string[]
 ---@return string[]
 local function generic_formatter(result)
-  local sep_start = ('='):rep(vim.o.columns)
-  local sep_end = ('='):rep(vim.o.columns)
+  local width = vim.o.columns
+  local sep_start = ('='):rep(width)
+  local sep_end = ('='):rep(width)
 
   table.insert(result, 1, sep_start)
   table.insert(result, sep_end)
@@ -37,6 +38,11 @@ local external_evaluators = {
     cmd = { 'racket', '-e' },
     formatter = generic_formatter,
   },
+
+  python = {
+    cmd = { 'python3', '-c' },
+    formatter = generic_formatter,
+  },
 }
 
 return external_evaluators