*vimcmdline.txt*                                                  *vimcmdline*
				 vimcmdline~
			  Send lines to interpreter~

Author: Jakson A. Aquino <jalvesaq@gmail.com>

 1. Overview                                             |vimcmdline_overview|
 2. Usage                                                   |vimcmdline_usage|
 3. Options
    3.1 Change the default mappings                      |vimcmdline_mappings|
    3.2 Change output colors                               |vimcmdline_colors|
    3.3 Other options
        Split the window vertically                           |cmdline_vsplit|
        Remap <Esc> to :stopinsert in Neovim's terminal     |cmdline_esc_term|
        Start the interpreter in a Neovim's terminal       |cmdline_in_buffer|
        Height of interpreter window or pane             |cmdline_term_height|
        Width of interpreter window or pane               |cmdline_term_width|
        Temporary directory                                  |cmdline_tmp_dir|
        Keep the cursor at the end of terminal (nvim)    |cmdline_auto_scroll|
        Set the application to run as interpreter                |cmdline_app|
        Set actions for each interpreter                     |cmdline_actions|
        Run interpreter in external terminal       |cmdline_external_term_cmd|


==============================================================================
							 *vimcmdline_overview*
1. Overview~

This plugin sends lines from either Vim or Neovim to a command line
interpreter (REPL application). The interpreter runs in either Neovim or Vim
built-in terminal. If Tmux is installed, the interpreter can also run in an
external terminal emulator or in a tmux pane. If running in either a Neovim
built-in terminal or an external terminal, the plugin runs one instance of the
REPL application for each file type. If running in a tmux pane, it runs one
REPL application for Vim instance.


==============================================================================
							    *vimcmdline_usage*
2. Usage~

If you are editing one of the supported file types, in Normal mode do:

  - <LocalLeader>s to start the interpreter.

  - <Space> to send the current line to the interpreter.

  - <LocalLeader><Space> to send the current line to the interpreter and
    keep the cursor on the current line.

  - <LocalLeader>q to send the quit command to the interpreter.

For languages that can source chunks of code:

  - In Visual mode, press:

    - <Space> to send a selection of text to the interpreter.

  - And, in Normal mode, press:

    - <LocalLeader>p to send from the line to the end of paragraph.

    - <LocalLeader>b to send block of code between the two closest marks.

    - <LocalLeader>f to send the entire file to the interpreter.

    - <LocalLeader>m to send the text in the following motion to the
      interpreter. For example <LocalLeader>miw would send the selected word.

Your `~/.inputrc` should not include `set keymap vi` because it would cause
some applications to start in vi's edit mode. Then, you would always have to
press either `a` or `i` in the interpreter console before using it.


==============================================================================
3. Options~

							 *vimcmdline_mappings*
3.1 Change the default mappings~

Below are examples of how to change the default mappings in your |vimrc|:
>
 " vimcmdline mappings
 let cmdline_map_start          = '<LocalLeader>s'
 let cmdline_map_send           = '<Space>'
 let cmdline_map_send_and_stay  = '<LocalLeader><Space>'
 let cmdline_map_source_fun     = '<LocalLeader>f'
 let cmdline_map_send_paragraph = '<LocalLeader>p'
 let cmdline_map_send_block     = '<LocalLeader>b'
 let cmdline_map_send_motion    = '<LocalLeader>m'
 let cmdline_map_quit           = '<LocalLeader>q'
<
							   *vimcmdline_colors*
3.2 Change output colors~

If you are using Neovim, you can use its syntax highlight capabilities to
colorize the interpreter output, and you can customize the colors in your
|vimrc| in three different ways:

  1. The hex code of the foreground color.

  2. The ANSI number of the foreground color.

  3. The complete highlighting specification.

The example of customization below will work if either your editor supports
true colors or if it supports 256 colors (see in Neovim: |tui-colors|):
>
 if has('gui_running') || &termguicolors
     let cmdline_color_input    = '#9e9e9e'
     let cmdline_color_normal   = '#00afff'
     let cmdline_color_number   = '#00ffff'
     let cmdline_color_integer  = '#00ffff'
     let cmdline_color_float    = '#00ffff'
     let cmdline_color_complex  = '#00ffff'
     let cmdline_color_negnum   = '#d7afff'
     let cmdline_color_negfloat = '#d7afff'
     let cmdline_color_date     = '#00d7af'
     let cmdline_color_true     = '#5fd787'
     let cmdline_color_false    = '#ff5f5f'
     let cmdline_color_inf      = '#00afff'
     let cmdline_color_constant = '#5fafff'
     let cmdline_color_string   = '#5fd7af'
     let cmdline_color_stderr   = '#0087ff'
     let cmdline_color_error    = '#ff0000'
     let cmdline_color_warn     = '#c0ffff'
     let cmdline_color_index    = '#d7d787'
 elseif &t_Co == 256
     let cmdline_color_input    = 247
     let cmdline_color_normal   =  39
     let cmdline_color_number   =  51
     let cmdline_color_integer  =  51
     let cmdline_color_float    =  51
     let cmdline_color_complex  =  51
     let cmdline_color_negnum   = 183
     let cmdline_color_negfloat = 183
     let cmdline_color_date     =  43
     let cmdline_color_true     =  78
     let cmdline_color_false    = 203
     let cmdline_color_inf      =  39
     let cmdline_color_constant =  75
     let cmdline_color_string   =  79
     let cmdline_color_stderr   =  33
     let cmdline_color_error    =  15
     let cmdline_color_warn     =   1
     let cmdline_color_index    = 186
 endif
<
And the next example sets the value of an option with a complete highlighting
specification.
>
 let cmdline_color_error = 'ctermfg=1 ctermbg=15 guifg=#c00000 guibg=#ffffff gui=underline term=underline'
<
If you prefer that the output is highlighted using your current |colorscheme|,
put in your |vimrc|:
>
 let cmdline_follow_colorscheme = 1
<
If you want to completely disable the colorizing of the interpreter output,
put in your |vimrc|:
>
 let cmdline_outhl = 0
<
Option `cmdline_outhl` can also be a dictionary where you indicate for each
file type whether it should have the output of its interpreter highlighted
or not. Example:
>
 let cmdline_outhl = {'r': 0} " R package colorout is better
<
By default, all file types with a corresponding `syntax/cmdlineoutput_.vim`
script will be highlighted.


3.3 Other options~
							      *cmdline_vsplit*
By default, vimcmdline will split the window horizontally before starting the
interpreter. If you prefer to split it vertically, put in your |vimrc|:
>
 let cmdline_vsplit = 1
<
							    *cmdline_esc_term*
In the built-in terminal, you should have to press <C-\><C-N> to go from
Terminal mode to Normal mode, but vimcmdline maps <Esc> to go to Normal mode
in the built-in terminal. If you rather prefer that the <Esc> key is passed to
the interpreter, put in your |vimrc|:
>
 let cmdline_esc_term = 0
<
							   *cmdline_in_buffer*
If you are running Neovim, the interpreter will be started in its built-in
terminal. If you prefer to start it in a Tmux split pane, put in your |vimrc|:
>
 let cmdline_in_buffer = 0
<
							 *cmdline_term_height*
The terminal height will be 15 lines, but you can change it in your |vimrc|:
>
 let cmdline_term_height = 25
<
							  *cmdline_term_width*
If splitting the window vertically, the terminal width will be only 40
columns. If you want it wider, put a different value in your |vimrc|:
>
 let cmdline_term_width = 80
<
							     *cmdline_tmp_dir*
Vimcmdline uses the current time and the user name to create a unique
temporary directory for each Vim instance, but you can define a different
temporary directory in your |vimrc|:
>
 let cmdline_tmp_dir = '/tmp'
<
							 *cmdline_auto_scroll*
Neovim's terminal will automatically scroll when there is new output only if
the cursor is in the last line of the terminal buffer. Vimcmdline puts the
cursor in the last line of the terminal buffer before sending a new line to it
to ensure the automatic scroll. If you rather prefer the default behavior, put
in your |vimrc|:
>
 let cmdline_auto_scroll = 0
<
								 *cmdline_app*
You can define what application will be run as the interpreter for each
supported file type. If you want to do this, create a dictionary called
`cmdline_app`, and add items with the 'filetype' as key and the interpreter as
value, as in the example:
>
 let cmdline_app           = {}
 let cmdline_app['ruby']   = 'pry'
 let cmdline_app['sh']     = 'bash'
<
Example for |init.lua|:
>
 vim.g.cmdline_app = {
     sh = 'bash',
     r = 'ssh -t user@remote-machine R --no-save',
     python = '~/.py3env/bin/python3',
 }
<
							     *cmdline_actions*
You cand set special commands to be sent to the interpreters. Examples for R
and Python (for |init.lua|):
>
 vim.g.cmdline_actions = {
     r = {
         {'<LocalLeader>l', 'ls()'},
         {'<LocalLeader>s', 'summary(%s)'},
         {'<LocalLeader>r', 'print(%s)'},
         {'<LocalLeader>t', 'str(%s)'},
         {'<LocalLeader>h', 'help(%s)'},
         {'<LocalLeader>a', 'args(%s)'},
     },
     python = {
         {'<LocalLeader>l', 'locals()'},
         {'<LocalLeader>g', 'globals()'},
         {'<LocalLeader>p', 'print(%s)'},
         {'<LocalLeader>t', 'type(%s)'},
         {'<LocalLeader>d', 'dir(%s)'},
     }
 }
<
The `cmdline_actions` variable is a dictionary. Each item has a 'filetype' as
key and has two elements: the key combination and the command to be sent to
the interpreter. The string "%s" is replaced with the word under cursor (the
result of the Vim command `expand('<cword>')`).

						   *cmdline_external_term_cmd*
If you want to run the interpreter in an external terminal emulator, you have
to define in your |vimrc| the command to run it, as in the examples:
>
 let cmdline_external_term_cmd = "gnome-terminal -- '%s'"
 let cmdline_external_term_cmd = 'kitty %s &'
<
where `%s` will be replaced with the terminal command required to run the REPL
application in a tmux session. Note that `gnome-terminal` does not require an
`&` at the end of the command because it forks immediately after startup and
that `kitty` only works if `%s` is not between quotation marks.

When running in an external terminal emulator, vimcmdline requires Tmux to
work, and it generates a tmux.conf for its tmux session. If you rather prefer to
write and use your own tmux.conf, you should define its path as in the
example:
>
 let cmdline_tmux_conf = "~/vimcmdline_tmux.conf"
<



>
			 vim:tw=78:ts=8:ft=help:norl