docs(vimdoc): Auto-generate user / API documentation + vimtags

doc/lua-console.nvim.txt

@@ -8,8 +8,9 @@ Table of Contents                         *lua-console.nvim-table-of-contents*
   - ✨ Features|lua-console.nvim-💻-lua-console-main-develop-luarocks-✨-features|
   - 📦 Installation|lua-console.nvim-💻-lua-console-main-develop-luarocks-📦-installation|
   - ⚙️ Configuration|lua-console.nvim-💻-lua-console-main-develop-luarocks-⚙️-configuration|
-  - 🚀 Usage (with default mappings)|lua-console.nvim-💻-lua-console-main-develop-luarocks-🚀-usage-(with-default-mappings)|
+  - 🚀 Basic usage (with default mappings)|lua-console.nvim-💻-lua-console-main-develop-luarocks-🚀-basic-usage-(with-default-mappings)|
   - 📓 Notes on globals, locals and preserving execution context|lua-console.nvim-💻-lua-console-main-develop-luarocks-📓-notes-on-globals,-locals-and-preserving-execution-context|
+  - ⭐ Extra features|lua-console.nvim-💻-lua-console-main-develop-luarocks-⭐-extra-features|
   - Alternatives and comparison|lua-console.nvim-💻-lua-console-main-develop-luarocks-alternatives-and-comparison|
   - 🔥 All feedback and feature requests are very welcome! Enjoy!|lua-console.nvim-💻-lua-console-main-develop-luarocks-🔥-all-feedback-and-feature-requests-are-very-welcome!-enjoy!|
 
@@ -21,6 +22,9 @@ 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.
 
+**Update: Although it originated as a tool for Lua development, it has now
+evolved into supporting other languages too. See evaluating other languages.**
+
 
 
 
@@ -36,15 +40,15 @@ needed something better, so there it is.
 
 ✨ FEATURES*lua-console.nvim-💻-lua-console-main-develop-luarocks-✨-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*lua-console.nvim-💻-lua-console-main-develop-luarocks-📦-installation*
@@ -59,57 +63,64 @@ With lazy.nvim <https://github.com/folke/lazy.nvim>:
 <
 
 otherwise, install with your favorite package manager and add
-`require('lua-console').setup({opts})` somewhere in your config.
+`require('lua-console').setup { custom_options }` somewhere in your config.
 
 
 ⚙️ CONFIGURATION*lua-console.nvim-💻-lua-console-main-develop-luarocks-⚙️-configuration*
 
 
-  [!NOTE] All settings are very straight forward, but please read below about
+  [!NOTE] All settings are self explanatory, but please read below about
   |lua-console.nvim-`preserve_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`.
 
 Default Settings ~
 
+`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>',
-        clear = 'C',
+        eval_buffer = '<S-CR>',
+        open = 'gf',
         messages = 'M',
         save = 'S',
         load = 'L',
         resize_up = '<C-Up>',
         resize_down = '<C-Down>',
         help = '?'
-      }
+      },
     }
 <
 
 
-🚀 USAGE (WITH DEFAULT MAPPINGS)*lua-console.nvim-💻-lua-console-main-develop-luarocks-🚀-usage-(with-default-mappings)*
+🚀 BASIC USAGE (WITH DEFAULT MAPPINGS)*lua-console.nvim-💻-lua-console-main-develop-luarocks-🚀-basic-usage-(with-default-mappings)*
 
 - 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 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.
+    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.
+- Use `print()` in your code to output the results into the console. It accepts variable number of arguments, e.g. `print(var_1, var_2, ...)`.
+- Objects and functions are pretty printed, with function details and their source paths.
 - Press `gf` to follow the paths in stack traces and to function sources. Truncated paths work too.
 
 
@@ -118,34 +129,145 @@ Default Settings ~
   `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.
-- 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*lua-console.nvim-💻-lua-console-main-develop-luarocks-📓-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.
+  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 = ..`.
+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
+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:
 
 - `_ctx()` - will print the contents of the context
 - `_ctx_clear()` - clears the context
 
 
+⭐ EXTRA FEATURES*lua-console.nvim-💻-lua-console-main-develop-luarocks-⭐-extra-features*
+
+
+ATTACHING CODE EVALUATOR TO OTHER BUFFERS ~
+
+- 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 ~
+
+
+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.
+    Default External Evaluators Settings
+     ~
+    `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
+    <
+    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.
+    >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' }
+    <
+
+
 ALTERNATIVES AND COMPARISON*lua-console.nvim-💻-lua-console-main-develop-luarocks-alternatives-and-comparison*
 
 There are a number of alternatives available, notably: