*vimteractive*   Sending commands from vim to interactive programs

                    Vimteractive - main help file


==============================================================================
CONTENTS                                               *vimteractive-contents*

    1.Intro........................................|vimteractive-intro|
    2.Usage........................................|vimteractive-usage|
    3.Common issues................................|vimteractive-issues|
    4.Extending functionality......................|vimteractive-extending|
    5.About........................................|vimteractive-about|
    6.License......................................|vimteractive-license|

==============================================================================
1. Intro                                                  *vimteractive-intro*

Vimteractive was inspired by the workflow of the vim-ipython plugin:

    https://github.com/ivanov/vim-ipython

This plugin is designed to extend a subset of the functionality of vim-ipython
to other REPLs (including ipython). It is based around the unix philosophy of
"do one thing and do it well".  It aims to provide a robust and simple link
between text files and language shells. Vimteractive will never aim to do
things like autocompletion, leaving that to other, more developed tools such as
YouCompleteMe or GitHub copilot.

The activating commands are
- ipython          |:Iipython|
- julia            |:Ijulia|
- maple            |:Imaple|
- mathematica      |:Imathematica|
- bash             |:Ibash|
- zsh              |:Izsh|
- python           |:Ipython|
- clojure          |:Iclojure|
- apl              |:Iclojure|
- R                |:IR|
- mathematica      |:Imathematica|
- sgpt             |:Isgpt|
- gpt-command-line |:Igpt|
- autodetect based on filetype |:Iterm|

Commands may be sent from a text file to the chosen REPL using CTRL-S. If
there is no REPL, CTRL-S will automatically open one for you using
|:Iterm|.  See |v_CTRL_S| for more details.

For some terminals, the output of the last command may be retrieved with
``CTRL-Y``. See |v_CTRL_Y| for more details.

Note: it's highly recommended to use IPython as your default Python
interpreter. You can set it like this:

    let g:vimteractive_default_shells = { 'python': 'ipython' }

Since this package leverages the native vim interactive terminal, it is
only compatible with vim 8 or greater.

==============================================================================
2. Usage                                                  *vimteractive-usage*

To use the key-bindings, you should first disable the CTRL-S default, which is
a terminal command to freeze the output. You can disable this by putting

stty -ixon

into your .bashrc (or equivalent shell profile file)

------------------------------------------------------------------------------
Example usage                                           *vimteractive-example*

Create a python file "test.py" with the following content:

    import matplotlib.pyplot as plt
    import numpy

    fig, ax = plt.subplots()
    x = numpy.linspace(-2,2,1000)
    y = x**3-x
    ax.plot(x, y)
    ax.set_xlabel('$x$')
    ax.set_ylabel('$y$')

Now start an ipython REPL in vim with |:Iipython|. You should see a preview
window open above with your ipython prompt. Position your cursor over the first
line of test.py, and press  |v_CTRL-S|. You should see this line now appear in the
first prompt of the preview window. Do the same with the second and fourth
lines. At the fourth line, you should see a figure appear once it's constructed
with plt.subplots(). Continue by sending lines to the REPL. You can send
multiple lines by doing a visual selection and pressing |v_CTRL-S|.

If you switch windows with CTRL-W k, you will see the terminal buffer switch
to a more usual looking normal-mode buffer, from which you can perform
traditional normal mode commands. However, if you try to insert, you will
enter the REPL, and be able to enter commands interactively into the
prompt as if you had run it in the command line. You can save this buffer if
you wish to a new file if it contains valuable output

You may want to send lines to one REPL from two buffers. To achieve that, run
:Iconn <buffer_name> where <buffer_name> is a name of buffer containing REPL.
If there is only one REPL, you can use just |:Iconn|.

------------------------------------------------------------------------------
Supported terminals                                   *vimteractive-terminals*

*:Iipython*     Activate an ipython REPL
*:Ijulia*       Activate a julia REPL
*:Imaple*       Activate a maple REPL
*:Imathematica* Activate a mathematica REPL
*:Ibash*        Activate a bash REPL
*:Izsh*         Activate a zsh REPL
*:Ipython*      Activate a python REPL
*:Iclojure*     Activate a clojure REPL
*:Iapl*         Activate an apl REPL
*:IR*           Activate an R REPL
*:Isgpt*        Activate an sgpt REPL
*:Igpt*         Activate an gpt-command-line REPL
*:Iterm*        Activate a REPL based on current filetype

------------------------------------------------------------------------------
Sending commands                                                    *v_CTRL_S*

CTRL-S sends lines of text to the REPL in a mode-dependent manner:

In |Normal-mode|, CTRL-S sends the line currently occupied by the cursor
the REPL.

In |Insert-mode|, CTRL-S sends the line currently being edited, and then
returns to insert mode at the same location.

In |Visual-mode|, CTRL-S sends the current selection to the REPL.

ALT-S sends all lines from the start to the current line.

If there is no active REPL for current buffer, CTRL-S will automatically
create one for you using |:Iterm|.

------------------------------------------------------------------------------
Retrieving command outputs                                          *v_CTRL_Y*

CTRL-Y retrieves the output of the last command sent to the REPL. This only
implemented in a subset of REPLs (|:Iipython|, |:Isgpt| and |:Igpt|)

In |Normal-mode|, CTRL-Y retrieves the output of the last command sent to the
REPL and places it in the current buffer.

In |Insert-mode|, CTRL-Y retrieves the output of the last command sent to the
REPL and places it in the current buffer, and then returns to insert mode
after the output.

------------------------------------------------------------------------------
Connecting to existing REPLs                *:Iconn* *vimteractive-connecting*

:Iconn [{buffer}] connects current buffer to REPL in {buffer}. You can connect
any number of buffers to one REPL. {buffer} can be omitted if there is only 
one REPL.

]v and [v can be used to cycle between connected buffers in the style of
unimpaired.

==============================================================================
3. Common issues                                         *vimteractive-issues*

------------------------------------------------------------------------------
Bracketed paste                          *vimteractive-issues-bracketed-paste*

If you see strange symbols like ^[[200~ when sending lines to your new
interpreter, you may be on an older system which does not have bracketed paste
enabled, or have other shell misbehaviour issues. You can change the default
setting with

    let g:vimteractive_bracketed_paste_default = 0


==============================================================================
4. Vimteractive options                                 *vimteractive-options*

These options can be put in your |.vimrc|, or run manually as desired:

    let g:vimteractive_vertical = 1        " Vertically split REPLs
    let g:vimteractive_autostart = 0       " Don't start REPLs by default
    let g:vimteractive_switch_mode = 0     " Don't switch to normal mode


==============================================================================
5. Extending functionality                            *vimteractive-extending*

To add a new interpreter to Vimteractive, you should define
g:vimteractive_commands variable. For example:

    let g:vimteractive_commands = { 'pythonasync': 'python -m asyncio' }

will provide you :Ipythonasync command starting Python 3.8+ asyncio REPL.
If you want to make this command default for python filetype, you should do

    let g:vimteractive_default_shells = { 'python': 'pythonasync' }

If you see escape sequences appearing when you do CTRL-S for your interpreter,
you may try to disable bracketed paste mode for it:

    let g:vimteractive_bracketed_paste = { 'pythonasync': 0 }

If your interpreter has slow-starting REPL (like Clojure), you may want to
wait before sending data to it at the first time. Specify time to wait in
milliseconds like this:

    let g:vimteractive_slow_prompt = { 'pythonasync': 200 }

This project is very much in an beta phase, so if you have any issues that
arise on your system, feel free to contact me:

    williamjameshandley@gmail.com

==============================================================================
6. About                                          *vimteractive-functionality*

The core maintainer of vimteractive is:

    Will Handley (GitHub: williamjameshandley)

Find the latest version of vimteractive at:

    http://github.com/williamjameshandley/vimteractive

==============================================================================
7. License                                              *vimteractive-license*

Vimteractive is licensed under GPL 3.0
