vim-multi-repl

A Vim 8 and Neovim plugin for sane, frictionless interaction with multiple REPLs and shells.

Each project you are working on uses a separate REPL for each file type (langauge). A single command sends your code to the appropriate REPL based on the buffer you're currently in.

This plugin uses vim-projectroot to determine the current project (so make sure you have it installed).

Installation

vim-multi-repl can be installed using any of the standard means of adding plugins to vim. For example, using vim-plug you could add the following to .vimrc

Plug 'haberdashPI/vim-multi-repl'

And then run :source % and :PlugInstall to install vim-multi-repl.

Usage

The available mappings and commands are as follows:

Open/hide a REPL

<Plug>(repl-toggle)

Default mapping: <c-w>'

In a file buffer, open and move to the REPL associated with that buffer. In a REPL, hide the REPL (it continues to run in the background).

Send current line or selected region

<Plug>(repl-send-text)

Default mapping: normal mode = <Leader>; visual mode = <Leader>.

Send the current line or highlighted text to the REPL associated with this buffer.

Normally this will work without a language specific configuration but there are optional prefixes and suffixes you can send for specific languages (see below).

Send motion

<Plug>(repl-send-motion)

Default mapping: <Leader>.

Send the text specified by a motion to the REPL associated with this buffer.

Normally this will work without a language specific configuration but there are optional prefixes and suffixes you can send for specific languages (see below).

Run current file

<Plug>(repl-run)

Default mapping: <Leader>r

Runs the current file in the REPL associated with this buffer. Depends on language specific configuration (see below).

Change directory

<Plug>(repl-cd)

Default mapping: <Leader>cd

Change directory to that of the current buffer's file in the REPL associated with this buffer. Depends on language specific configuration (see below).

<Plug>(repl-global-cd)

Default mapping: <Leader>gcd

Like <Plug>(repl-cd) but use the global default, not the language specific one.

This command can be handy if you open a language specific REPL using :REPL sh: you can change directories while in the shell using this command; then, once you've started the language specific program within the shell (e.g. ipython) you can use the language specific settings to change directories using <Plug>(repl-cd).

Resize

<Plug>(repl-resize)

Default mapping: normal and visual mode = <Leader>=, terminal mode = <C-w>=

Resize REPL to be g:repl_size lines (default = 20). When passed a count, it instead resizes to the specified number of lines.

Switch REPLs

<Plug>(repl-switch)

Default mapping: <C-w>g[n] where n = 1-9

While in the REPL, switch to REPL 1-9 (see below).

REPL

This command opens a given program with the given passed arguments. This is called automatically, as necessary, with no arugments, for each of the above mappings. It is only necessary to call manually if you wish to override the default REPL program or pass additional arguments to the program.

For example to remove all colors in ipython you could call

:REPL ipython --colors=no

REPLCloseAll

This command closes all REPLs that have been opened.

REPLlist

This command lists the name of all open REPLs.

Scroll Back

Though not strictly specific to REPLs, this plugin adds a mapping for terminals so that <C-w><C-u> switches to normal mode and scrolls up in the buffer.

Configuration

If you wish to remove the default mappings you can add let g:repl_default_mappings=0 to .vimrc.

vim-multi-repl comes preconfigured for the following languages:

1. Python (ipython)
2. Javascript (node)
3. MATLAB
4. R
5. Julia

You can quickly and easily configure it for your specific language or shell. For example, if python were not already available you could add the following to .vimrc:

augroup PythonREPL
  au!
  au FileType python let b:repl_program='ipython'
  au FileType python let b:repl_cd_prefix='%cd '
  au FileType python let b:repl_run_prefix='%run '
  au FileType python let b:repl_send_text_delay='250m'
  au FileType python let b:repl_send_prefix="%cpaste\n"
  au FileType python let b:repl_send_suffix="\n--\n"
augroup END

The delay is there to avoid some of the issues with ipython dropping text sent to it. This delay occurs directly after the send prefix and before the suffix.

Pull requests for new language configurations are welcome.

These language specific variables default to global variables of the same name (e.g. g:repl_program='sh').

You can configure the position and size of the REPL with the following variables:

let g:repl_size = 20
let g:repl_position = 'botright'

Multiple REPLs per filetype

By default there is one REPL per filetype and project. But you can have multiple REPLS for a given filetype and project, if you wish. These are referred to using numbers 1-9. Pass a count to <Plug>(repl-toggle) to switch to a specific REPL. In addition, while in terminal mode <Plug>(repl-switch) mapping will open a prompt for a single number (1-9) and switch to the given REPL.

In fact, each of the mappings can take a count which is used to specify which REPL to use. When no count is specified, the last REPL used by the current buffer is assumed, and REPL 1 is assumed if no REPL was previosuly used. If the REPL was closed, it gets re-opened.

Likewise, the :REPL command takes an optional first argument ranging from 1-9 that indicates the REPL you wish to start and the default is determined by the last REPL used in the current buffer.

TODO:

1. Make sure all of the defaults work correclty on Windows machines