Merge pull request #287 from michaelb/dev

v1.3.14

Author: michaelb

CHANGELOG.md

@@ -1,3 +1,6 @@
+## v1.3.14
+- Improve Lua\_nvim's handling of 'local' requires in REPL mode
+
 ## v1.3.13
 - Support Python import list syntax
 

CHECKLIST.md

@@ -1,5 +1,6 @@
 # External contributions
  - only accept contributions to 'dev' branch OR release immediately after
+ (doc contribution can be exempted)
 
 # Prepare the release
 

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "sniprun"
-version = "1.3.13"
+version = "1.3.14"
 authors = ["michaelb <[email protected]>"]
 rust-version = "1.65"
 edition = "2018"
@@ -29,6 +29,7 @@ serial_test = "2.0"
 
 # jupyter-client = { git = "https://gitlab.com/srwalker101/rust-jupyter-client.git", branch = "dev" }
 
+rmp = "=0.8.8" # fix rmp version because it breaks MSRV
 
 # Python3 interpreter
 unindent = "0.2"

Cargo.toml

@@ -71,16 +71,18 @@ Sniprun will then:
 
 ## Prerequisites && dependencies
 
-- Sniprun is compatible with **Linux** and **MacOS**. (NixOS and Mac users _need_ the Rust [toolchain](https://www.rust-lang.org/tools/install) version >= 1.65 ). Standard POSIX utilities (grep, cut, sed ...) may be needed too, depending on the languages you want support for.
+- Sniprun is compatible with **Linux** and **MacOS**. (NixOS and Mac users _need_ the Rust [toolchain](https://www.rust-lang.org/tools/install) version >= 1.65, in order to compile sniprun locally). Standard POSIX utilities (grep, cut, sed ...) may be needed too, depending on the languages you want support for.
 
 - **Neovim** version >= 0.5
 
-- **Compiler / interpreter** for the languages you work with must be installed & on your \$PATH. In case specific build tools or softwares are required, those are documented in the navigation pane of the [wiki](https://michaelb.github.io/sniprun/), as well as in the [doc/sources/interpreters](https://github.com/michaelb/sniprun/tree/master/doc/sources/interpreters) folder, for each interpreter, which I urge you to get a look at before getting started as it also contains the potential limitations of each interpreter; this information can be accessed through `:SnipInfo <interpreter_name>` (tab autocompletion supported).
+- **Compiler / interpreter** for the languages you work with must be installed & on your \$PATH. In case non-standard build tools or softwares are required, those are documented in the navigation pane of the [wiki](https://michaelb.github.io/sniprun/), as well as in the [doc/sources/interpreters](https://github.com/michaelb/sniprun/tree/master/doc/sources/interpreters) folder, for each interpreter, which I urge you to get a look at before getting started as it also contains the potential limitations of each interpreter; this information can be accessed through `:SnipInfo <interpreter_name>` (tab autocompletion supported).
 
-- [optional] **cargo and the rust toolchain** version >= 1.65 (you can find those [here](https://www.rust-lang.org/tools/install)).
+- [optional] **cargo and the rust toolchain** version >= 1.65 (you can find those [here](https://www.rust-lang.org/tools/install)), if you want/need to compile sniprun locally.
 
 - [optional] the plugin [nvim-notify](https://github.com/rcarriga/nvim-notify) for the notification display style
 
+Note: Since sniprun is written in Rust and many users may not have/want a Rust toolchain, a binary compiled from a Github Action gets downloaded from Releases. If you don't want that, just install a Rust toolchain and replace the install.sh invocation in your config by `cargo build --release`.
+
 ## Install Sniprun
 
 ### Use your favorite plugin manager (recommended) ...
@@ -339,7 +341,7 @@ All of sniprun functionalities:
 
   (if you don't know what is the leader key you can find a short explanation [here](https://vim.works/2019/03/03/vims-leader-key-wtf-is-it/)).
 
-<details><summary> recommended mappings in lua</summary>
+<details open><summary> recommended mappings in lua</summary>
 <p>
 
 ```
@@ -350,7 +352,7 @@ vim.api.nvim_set_keymap('n', '<leader>ff', '<Plug>SnipRun', {silent = true})
 </details>
 </p>
 
-<details open><summary> recommended mappings in vimscript</summary>
+<details><summary> recommended mappings in vimscript</summary>
 <p>
 
 ```
@@ -361,7 +363,7 @@ vmap f <Plug>SnipRun
 </details>
 </p>
 
-- For interpreted languages with simple output, `:%SnipRun` (or a shortcut, wrapping it with `let b:caret=winsaveview()` and `call winrestview(b:caret)` in order to keep the cursor at the current position) may be a more convenient way to run your entire file. Example mapping `:%SnipRun` to F5: `vim.keymap.set('n', '<F5>', ":let b:caret=winsaveview() <CR> | :%SnipRun <CR>| :call winrestview(b:caret) <CR>", {})`, with my apologies for poor vimscript.
+- For interpreted languages with simple output, `:%SnipRun` (or a shortcut, wrapping it with `let b:caret=winsaveview()` and `call winrestview(b:caret)` in order to keep the cursor at the current position) may be a more convenient way to run your entire file. Example mapping `:%SnipRun` to F5: `vim.keymap.set('n', '<F5>', ":let b:caret=winsaveview() <CR> | :%SnipRun <CR>| :call winrestview(b:caret) <CR>", {})`, with my apologies for poor vimscript-fu.
 
 When running the whole file, SnipRun supports taking arguments on the command line: `:%SnipRun 5 "yay"` frictionlessly for interpreted languages, and compiled languages with entry point detection implemented (most of them).
 
@@ -439,21 +441,22 @@ Want (official) support for your language? Submit an [issue](https://github.com/
 
 \*\* True REPL under the hood
 
-\*\*\* if underlying language supports it
+\*\*\* REPL-like functionality if language in code block supports it
 
 (livemode)=
 # Live mode
 
 The live mode hooks the SnipRun command to the TextChanged event, meaning that at every change to make to the buffer, the current line will be sent to sniprun for evaluation. This can mean a lot of times, especially if you type fast.
 
-The result is a virtual text, displaying at the end of the current line that print the result (stdout) of the line. Nothing is displayed when the line is incomplete / incorrect, a bit like codi.
+The result is a virtual text, displaying at the end of the current line that print the result (stdout) of the line. Nothing is displayed when the line is incomplete / incorrect, a bit like [codi.vim](https://github.com/metakirby5/codi.vim).
 
 ## Warnings
 
-The live mode **will execute code you didn't think really about** (and by that I mean even less than usual)
+The live mode **will execute code you didn't think really about** (and by that I mean even less than usual).
+
 Thus:
- - Your code will get executed **lots** of times; check that your CPU can keep up. Even a slow 60wpm typing can make a Rust program recompile 3x per second, which is also different from sending 3 string/s to a running REPL.
- - Sniprun will try to execute even incomplete lines. You hadn't finished typing that `rm /path/to/arghhh` ? sniprun' not aware and removed the parent directory. Whoops. For these reasons, I strongly suggest to:
+ - Your code will get executed **lots** of times; check that your CPU can keep up. Even a 'slow' 30wpm typing can trigger constant program recompiles.
+ - Sniprun will try to execute even incomplete lines, example: you hadn't finished typing that `rm /path/to/arghhh` ? Sniprun saw you submitting `rm /path` and removed the parent directory. For these reasons, I strongly suggest to:
     - never run bash/shell with live mode
     - disable the live mode whenever your code modifies files or invoke system commands.
 
@@ -512,6 +515,7 @@ Due to its nature, Sniprun may have trouble with programs that :
 Begin by updating the plugin and running `:SnipReset` and then `:checkhealth sniprun`
 
 - **Silent fail**: the sniprun binary may be incompatible with your distro/OS/arch. Use `sh ./install.sh 1` as post-install to compile locally.
+- Any other kind of bug: a log file is produced in $XDG\_CACHE\_DIR/sniprun (~/.cache/sniprun on Linux or ~/Library/Caches/sniprun on MacOS), usually with all kinds of information of what happened during your last command.
 
 # Contribute
 
@@ -534,7 +538,7 @@ And many more projects, somewhat similar, but never quite, that I didn't like, n
 
 **Why should you use sniprun instead of these alternatives?**
 
-- **All-language support**. Sniprun can work with virtually any language, including compiled ones. If the language is not supported yet, anyone can create a sniprun interpreter for it!
+- **All-language support**. Sniprun can work with virtually any language, including compiled ones. If the language is not supported yet, anyone can create a sniprun interpreter for it! (or more simply, configure the generic interpreter)
 - **Better output/display**. Sniprun doesn't use precious screen space (like [codi](https://github.com/metakirby5/codi.vim) or [vim-slime](https://github.com/jpalardy/vim-slime)) by default (but it can).
 - **Fast, extendable and maintainable**: this is not a 2k-lines vim script, nor an inherently limited one-liner. It's a Rust project designed to be as clear and "contribuable" as possible.
 

doc/sources/README.md

@@ -120,6 +120,6 @@ sniprun internally expect, or be straight out incompatible with the formers. Be
 
 Exceptions:
  - Scala_original has both interpreter and compiler keys that should be set consistently with each other
- - *_jupyter, Generic, GFM_original, Orgmode_original, and Neorg_original do not support any of these keys
+ - *_jupyter, Generic, GFM_original, Orgmode_original, and Neorg_original do not support any of these keys, as they rely on the interpreter for the code's block language.
 
 

doc/sources/common_options.md

@@ -1,7 +1,7 @@
 ## Ada original
 
 
-dependencies: Need gcc-ada and gnatmake
+dependencies: Need `gcc-ada` and `gnatmake`
 
 
 Note: because Ada needs variables to be declared before the begin (in a non contiguous section of the file), SnipRun is not very useful here and will, in practice, only be able to run blocs like

doc/sources/interpreters/Ada_original.md

@@ -4,7 +4,7 @@ This interpreter require the `mono` toolbox to be installed: `csc` and `mono` mu
 
 a custom compiler can be specified :
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         CSharp_original = {

doc/sources/interpreters/CSharp_original.md

@@ -1,9 +1,9 @@
 ## C original
 
-gcc is recommended, for that it's able to detect, compile and run nested functions, however you can change the default compiler with:
+`gcc` is recommended, for that it's able to detect, compile and run nested functions, however you can change the default compiler with:
 
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         C_original = {
@@ -14,7 +14,7 @@ require'sniprun'.setup({
 })
 ```
 
-If you run with GCC, Sniprun will be able to run function + code in the same snippet, or functions + main() function regardlessly,but only the latter is supported by clang.
+If you run with GCC, Sniprun will be able to run function + code in the same snippet, or functions + main() function regardlessly, but only the latter is supported by `clang`.
 
 This interpreter will also only import (all)  #include \<...> but not any #include "..." (systems-wide include only, not the headers from your project, unless the environment variable `$C_INCLUDE_PATH` or `$CPLUS_INCLUDE_PATH` have been set). In this case, please make sure those variable cover **ALL** the paths needed to fetch every header file `#include`'d
 
@@ -27,7 +27,7 @@ the C\_original interpreter will also make use of the following environment vari
 - `$CFLAGS`
 
 
-and will add them to the build options it uses. Please specify _absolute path_, and not relative ones!
+and will add them to the build options it uses. Please specify _absolute paths_, and not relative ones!
 
 
 Using a tool such as [direnv](https://direnv.net/) may be really useful to set up those variables when you `cd` into your project' directory.

doc/sources/interpreters/C_original.md

@@ -7,7 +7,8 @@ The default interpreter command is `clojure` (or `clojure -e "(clojure.main/repl
 
 
  The defaults are equivalent to specifying:
-```
+
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         Clojure_fifo = {

doc/sources/interpreters/Clojure_fifo.md

@@ -3,9 +3,9 @@
 Limitations
 
  - Will only look and load external imports (include) that are SYSTEM import; as sniprun does not have any way to differentiate between #include "math.h"  (the system library) and #include "math2.h" (your custom header), it will NOT look for #include "....", but only #include \<....>   (those are restricted to system libraries).
- - Need 'g++' (or specifiy another compiler in configuration)
+ - Need `g++` (or specify another compiler in configuration)
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         Cpp_original = {

doc/sources/interpreters/Cpp_original.md

@@ -1,3 +1,3 @@
 ## D original
 
-For the D language, needs the 'dmd' executable
+For the D language, needs the `dmd` executable

doc/sources/interpreters/D_original.md

@@ -1,3 +1,3 @@
 ## Elixir original
 
-Needs "elixir" (or "iex" for REPL mode) available and in $PATH)
+Needs `elixir` (or `iex` for REPL mode) available and in $PATH)

doc/sources/interpreters/Elixir_original.md

@@ -6,7 +6,7 @@
 The default interpreter command is `dotnet fsi --nologo` but it can be changed via the configuration key
 
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         FSharp_fifo = {

doc/sources/interpreters/FSharp_fifo.md

@@ -25,7 +25,7 @@ done
 ### example 2
 
 
-\``rust  << running on this line will run the entire bloc
+\```rust  << running on this line will run the entire bloc
 
 println!("test");
 
@@ -36,11 +36,11 @@ println!("test");
 
 \* python, but you can ofc configure that: 
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         GFM_original = { 
-            default_filetype = 'bash' -- default filetype (not github flavored markdown name)
+            default_filetype = 'bash' -- default filetype (not 'github flavored markdown 'name' of the language, as they are sometimes different)
         }
     }
 })

doc/sources/interpreters/GFM_original.md

@@ -1,11 +1,11 @@
 ## Generic
 
-This interpreter allows you to support virtually any language, provided it's not to strange, at up to bloc-level
+This interpreter allows you to support virtually any language, provided it's not too strange, at up to bloc-level
 
 If you're trying to override an already-supported language, add Generic to the list of selected interpreters:
 
 
-```
+```lua
 require'sniprun'.setup({
     selected_interpreters = { 'Generic' },
 })
@@ -14,7 +14,7 @@ require'sniprun'.setup({
 to add support for, let's say, python2
 
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         Generic = {
@@ -24,7 +24,7 @@ require'sniprun'.setup({
                 extension = ".py",                 -- recommended, but not mandatory. Sniprun use this to create temporary files
 
                 interpreter = "python2",           -- interpreter or compiler (+ options if any)
-                compiler = "",                     -- one of those MUST be non-empty
+                compiler = "",                     -- exactly one of those MUST be non-empty
                 }
             }
         }
@@ -35,7 +35,7 @@ require'sniprun'.setup({
 to also add support for, let's suppose it wasn't officially supported, C
 
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         Generic = {
@@ -57,7 +57,7 @@ require'sniprun'.setup({
                 extension = ".c",                
 
                 interpreter = "",         
-                compiler = "gcc -o my_main -O3",                     -- compiler (+ options if necessary) (current working directory is sniprun's work directory)
+                compiler = "gcc -o my_main -O3",                     -- compiler (+ options if necessary) (current working directory is sniprun's work directory - next to sniprun's log in $XDG_CACHE_DIR)
 
                 exe_name = "my_main",                                -- executable name, by default a.out (always in sniprun's work directory)
                 boilerplate_pre = "#include <stdio.h>\nint main () {"  -- include this before code snippets
@@ -66,8 +66,8 @@ require'sniprun'.setup({
             }
         },
 
-    -- other sniprun options, for example:
     selected_interpreters = {"Generic"}
+    -- other sniprun options ...
 })
 ```
 
@@ -91,4 +91,4 @@ require'sniprun'.setup({
 
 ### Community examples for non-officially supported languages
 
-(contribute here)
+(contribute here: doc/sources/interpreters/Generic.md)

doc/sources/interpreters/Generic.md

@@ -1,8 +1,8 @@
 ## Go original
-the executable (go , llgo or whatever) executable used to _build_ the snippet can be configured via
+the executable (`go` , `llgo` or whatever) executable used to _build_ the snippet can be configured via
 
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         Go_original = {

doc/sources/interpreters/Go_original.md

@@ -1,3 +1,3 @@
 ## Haskell original
 
-require the 'ghc' compiler and the base libraries such as haskell-base-prelude
+require the `ghc` compiler and the base libraries such as haskell-base-prelude

doc/sources/interpreters/Haskell.md

@@ -11,7 +11,7 @@ But the REPL is VERY quirky (and even has a greeting saying it's unstable)
 It doesn't play well at all with sniprun's stdin-stdout mechanism, so while basic examples are working,
 I can't consider this a 'daily driver'... so REPL is disabled by default
 
-```
+```lua
 require('sniprun').setup({
     selected_interpreters={"JS_TS_bun"},
     repl_enable={"JS_TS_bun"}
@@ -27,7 +27,7 @@ sniprun runs your code snippets with
 
 more arguments for `bun run` can be added with the interpreter option:
 
-```
+```lua
 require'sniprun'.setup({
     interpreter_options = {
         JS_TS_bun = {

doc/sources/interpreters/JS_TS_bun.md

@@ -4,7 +4,7 @@ A REPL-capable (not enabled by default) Typescript / Javascript interpreter.
 
 `deno` needs to be installed and on your path (and working). The precise command used by sniprun is `deno repl -q`
 
-```
+```lua
 require('sniprun').setup({
     selected_interpreters={"JS_TS_deno"},
     repl_enable={"JS_TS_deno"}