You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**lua-console.nvim** - is a handy scratch pad / REPL / debug console for Lua development and Neovim exploration and configuration.
4
4
Acts as a user friendly replacement of command mode - messages loop and as a handy scratch pad to store and test your code gists.
5
5
6
-
<imgsrc="doc/demo.gif">
6
+
***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).***
7
+
8
+
<br/><imgsrc="doc/demo.gif">
7
9
8
10
## 💡 Motivation
9
11
@@ -13,15 +15,15 @@ syntax error and retyping the whole thing again, copying the paths from error st
13
15
14
16
## ✨ Features
15
17
16
-
- Evaluate single line expressions
17
-
- Evaluate visually selected lines of code
18
+
- Evaluate single line expressions and statements, visually selected lines of code or the whole buffer
18
19
- Pretty print Lua objects, including function details and their source paths
19
-
- Show normal and error output in the console, including output of `print()`, errors and stacktraces.
20
+
- Show normal and error output in the console/buffer, including output of `print()`, errors and stacktraces.
20
21
- Syntax highlighting and autocompletion
21
22
- Load Neovim’s messages into console for inspection and copy/paste
22
23
- Open links from stacktraces and function sources
23
-
- Save / Load console session
24
-
- Use as scratch pad for code gists
24
+
- Save / Load / Autosave console session
25
+
- Use as a scratch pad for code gists
26
+
- Attach code evaluators to any buffer
25
27
26
28
27
29
## 📦 Installation
@@ -35,91 +37,212 @@ return {
35
37
}
36
38
```
37
39
otherwise, install with your favorite package manager and add
38
-
`require('lua-console').setup({opts})` somewhere in your config.
40
+
`require('lua-console').setup { custom_options }` somewhere in your config.
39
41
40
42
41
43
## ⚙️ Configuration
42
44
43
45
> [!NOTE]
44
-
> All settings are very straight forward, but please read below about [`preserve_context`](#-notes-on-globals-locals-and-preserving-execution-context) option.
46
+
> All settings are self explanatory, but please read below about [`preserve_context`](#-notes-on-globals-locals-and-preserving-execution-context) option.
45
47
46
-
Mappings are local to the console, except the one for toggling, which is - `` ` `` by default.
48
+
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
49
+
config. If you want to delete a mapping - set its value to `false`.
load_on_start=true, -- load saved session on first entry
58
-
preserve_context=true-- preserve context between executions
60
+
autosave=true, -- autosave on console hide / close
61
+
load_on_start=true, -- load saved session on start
62
+
preserve_context=true, -- preserve results between evaluations
59
63
},
60
64
window= {
61
-
border='double', -- single|double|rounded
65
+
border='double', -- single|double|rounded
62
66
height=0.6, -- percentage of main window
63
67
},
64
68
mappings= {
65
69
toggle='`',
70
+
attach='<Leader>`',
66
71
quit='q',
67
72
eval='<CR>',
68
-
clear='C',
73
+
eval_buffer='<S-CR>',
74
+
open='gf',
69
75
messages='M',
70
76
save='S',
71
77
load='L',
72
78
resize_up='<C-Up>',
73
79
resize_down='<C-Down>',
74
80
help='?'
75
-
}
81
+
},
76
82
}
77
83
```
78
84
<!-- config:end -->
79
85
80
86
</details>
81
87
82
88
83
-
## 🚀 Usage (with default mappings)
89
+
## 🚀 Basic usage (with default mappings)
84
90
85
91
- Install, press the mapped key `` ` `` and start exploring.
86
92
- Enter code as normal, in insert mode.
87
93
- Hit `Enter` in normal mode to evaluate a variable, statement or an expression in the current line.
88
-
- Visually select a range of lines and press `Enter` to evaluate the code in the range.
94
+
- 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.
89
95
- The evaluation of the last line is returned and printed, so no `return` is needed in most cases.
90
-
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.
91
-
- Use `print()` in your code to output the results into the console. Accepts variable number of arguments, e.g. `print(var_1, var_2, ...)`.
92
-
- Objects and functions are pretty printed, with function source paths.
96
+
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.
97
+
The result of assignments on the last line will be also shown as virtual text.
98
+
- 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, ...)`.
99
+
- Objects and functions are pretty printed, with function details and their source paths.
93
100
- Press `gf` to follow the paths in stack traces and to function sources. Truncated paths work too.
94
101
95
102
> [!NOTE]
96
103
> 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
97
104
example, you can jump to its current definition, while Lsp/tags would take you to the original one.
98
105
99
106
- Press `M` to load Neovim messages into the console.
100
-
- Use `S` and `L` to save / load the console session to preserve history of your hacking.
107
+
- 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
108
+
saved whenever it is toggled or closed.
101
109
- You can resize the console with `<C-Up>` and `<C-Down>`.
102
110
103
111
104
112
## 📓 Notes on globals, locals and preserving execution context
105
113
106
114
> [!IMPORTANT]
107
-
> By default, the option `preserve_context` is on, which means that the context is preserved between executions.
115
+
> By default, the option `preserve_context` is on, which means that the execution context is preserved between evaluations.
108
116
109
-
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
110
-
environment, although all global variables are accessible. If you want purposefully to alter the global state, use `_G.My_variable = ..`.
117
+
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
118
+
in Neovim's global environment, although all global variables are accessible. If you want purposefully to alter the global state, use `_G.My_variable = ..`.
111
119
112
-
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.
120
+
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.
113
121
So, if you first execute `a = 1`, then `a = a + 1` and then `a` - you will get `2`. Variables with `local` are not preserved.
114
122
115
-
If you want a classic REPL experience, when the context is cleared on every execution, set `preserve_context = false`.
123
+
If you want the context to be cleared before every execution, set `preserve_context = false`.
116
124
117
125
There are two functions available within the console:
118
126
119
127
-`_ctx()` - will print the contents of the context
120
128
-`_ctx_clear()` - clears the context
121
129
122
130
131
+
## ⭐ Extra features
132
+
133
+
### Attaching code evaluator to other buffers
134
+
135
+
- The evaluator behind the console can be attached/detached to any buffer by pressing ``<Leader>` `` or executing command `LuaConsole AttachToggle`.
136
+
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.
137
+
138
+
### Evaluating other languages
139
+
140
+
#### Setting up
141
+
142
+
- 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.
143
+
Meanwhile, you can easily setup your own language.
144
+
- Below is the default configuration which can be overridden or extended by your custom config (`default_process_opts` will be
145
+
replaced by language specific opts), e.g. a possible config for `python` could be:
- The language evaluator is determined either from (in order of precedence):
218
+
219
+
- 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
220
+
for evaluation. The prefix can be changed in the config.
221
+
- The code prefix on the top line of the console/buffer, in which case it applies to the whole buffer.
222
+
- The file type of the buffer.
223
+
<br/>
224
+
225
+
```racket
226
+
===racket
227
+
228
+
229
+
(define (log str)
230
+
(displayln (format "~v" str)))
231
+
232
+
233
+
(define (fact n)
234
+
(if (= n 0)
235
+
1
236
+
(* n (fact (- n 1)))))
237
+
238
+
(displayln (fact 111))
239
+
```
240
+
241
+
```ruby
242
+
===ruby
243
+
5.times { puts'Hey' }
244
+
```
245
+
123
246
## Alternatives and comparison
124
247
125
248
There are a number of alternatives available, notably:
0 commit comments