472 lines
20 KiB
Plaintext
472 lines
20 KiB
Plaintext
*vim-tmux-runner.txt* For Vim version 7.3 Last change: 2012 Nov 25
|
||
|
||
Vim Tmux Runner
|
||
Vim and tmux, sittin' in a tree...
|
||
|
||
==============================================================================
|
||
CONTENTS *vtr-contents*
|
||
|
||
1. About............................ |VTR-About|
|
||
2. Usage ........................... |VTR-Usage|
|
||
2.1 ............................... |VtrSendCommandToRunner|
|
||
2.2 ............................... |VtrSendLineToRunner|
|
||
2.3 ............................... |VtrSendSelectedToRunner|
|
||
2.4 ............................... |VtrOpenRunner|
|
||
2.5 ............................... |VtrKillRunner|
|
||
2.6 ............................... |VtrFocusRunner|
|
||
2.7 ............................... |VtrResizeRunner|
|
||
2.8 ............................... |VtrReorientRunner|
|
||
2.9 ............................... |VtrDetachRunner|
|
||
2.10 ............................... |VtrReattachRunner|
|
||
2.11 ............................... |VtrClearRunner|
|
||
2.12 ............................... |VtrFlushCommand|
|
||
2.13 ............................... |VtrSendCtrlD|
|
||
2.14 ............................... |VtrSendFile|
|
||
3. Configuration ................... |VTR-Configuration|
|
||
3.1 ................................ |VtrPercentage|
|
||
3.2 ................................ |VtrOrientation|
|
||
3.3 ................................ |VtrInitialCommand|
|
||
3.4 ................................ |VtrGitCdUpOnOpen|
|
||
3.5 ................................ |VtrClearBeforeSend|
|
||
3.5 ................................ |VtrPrompt|
|
||
3.6 ................................ |VtrUseVtrMaps|
|
||
3.7 ................................ |VtrClearOnResize|
|
||
3.8 ................................ |VtrClearOnReorient|
|
||
3.9 ................................ |VtrClearOnReattach|
|
||
3.10 ............................... |VtrDetachedName|
|
||
3.11 ............................... |VtrClearSequence|
|
||
3.12 ............................... |VtrStripLeadningWhitespace|
|
||
3.13 ............................... |VtrClearEmptyLines|
|
||
3.14 ............................... |VtrAppendNewline|
|
||
|
||
==============================================================================
|
||
ABOUT (1) *VTR-About*
|
||
|
||
VTR -- Straightforward Vim/tmux integration
|
||
|
||
This plugin provides Vim with an understanding of tmux. The plugin provides
|
||
functionality to open a small tmux pane and send commands to run in that tmux
|
||
pane.
|
||
|
||
This plugin was created by Chris Toomey[1]. Any bugs or feature requests can
|
||
be entered at the github repo[2] for the plugin. Any feedback is greatly
|
||
appreciated.
|
||
|
||
This plugin was heavily inspired by Vimux[3]. It is meant to provide a very
|
||
similar feature set to Vimux, but use native vimscript. In addition VTR
|
||
provides a few commands beyond those in Vimux, such as the ability to rotate
|
||
the runner pane between orientations. In addition, the code for sending text
|
||
from a Vim buffer to the tmux runner pane for execution was modeled on the
|
||
tslime.vim[4] plugin.
|
||
|
||
[1] http://ctoomey.com
|
||
[2] https://github.com/christoomey/vim-tmux-runner/issues
|
||
[3] https://github.com/benmills/vimux
|
||
[4] https://github.com/kikijump/tslime.vim
|
||
|
||
==============================================================================
|
||
USAGE (2) *VTR-Usage*
|
||
|
||
VTR provides a collection of commands and functions that allow Vim to interact
|
||
with tmux. The primary command is VtrSendCommandToRunner. This allows for any
|
||
command string to be passed to tmux for execution. The commands
|
||
VtrSendLineToRunner and VtrSendSelectedToRunner allow for either the current
|
||
visually selected region or the current line to be sent to the tmux runner
|
||
pane for execution. This functionality is similar to SLIME[5] mode for the
|
||
Emacs text editor.
|
||
|
||
VTR uses a tmux "pane" to execute the provided command. A tmux pane is very
|
||
similar to a Vim split. Throughout VTR this tmux pane used for command
|
||
execution is referred to as the "runner" pane. The runner by default will
|
||
start an instance of the system shell, but other executables such as a python
|
||
REPL, ruby irb session, or similar then be opened within that shell be used.
|
||
The power of VTR and tmux is that each pane is a fully independent shell
|
||
environment. None the less, tmux allows for communication between these
|
||
environments and it is this ability that give VTR its power.
|
||
|
||
[5] http://common-lisp.net/project/slime/
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendCommandToRunner*
|
||
2.1 VtrSendCommandToRunner~
|
||
|
||
Send a command to the tmux runner pane. This is the primary purpose of VTR. A
|
||
new runner pane will be created. A detached pane will be reattached. By
|
||
default, the runner will be cleared before sending the provided command, but
|
||
this behavior can be disabled with the |VtrClearBeforeSend| setting.
|
||
|
||
The first time this command is called, it will prompt for a command to send to
|
||
the runner. The specific prompt text can be configured via the |VtPrompt|
|
||
setting. The command is then stored in an internal variable and will
|
||
continue to be used for subsequent calls to the command. The stored command
|
||
can be cleared using |VtrFlushCommand|.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendLineToRunner*
|
||
2.2 VtrSendLineToRunner~
|
||
|
||
Send the current line from the Vim buffer to the runner pane for execution.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendSelectedToRunner*
|
||
2.3 VtrSendSelectedToRunner~
|
||
|
||
Send the current visual selection in the Vim buffer to the runner pane for
|
||
execution.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrOpenRunner*
|
||
2.4 VtrOpenRunner~
|
||
|
||
Open a tmux pane, referred to as the "runner", adjacent to the tmux pane
|
||
containing the current Vim session. This command will make use of the
|
||
|VtrOrientation| and |VtrPercentage| settings. Note, this command will
|
||
restore a detached pane or create a new one as needed.
|
||
|
||
This command can also be passed a Vim Dictionary with parameters for the new
|
||
pane to override the defaults. This can be used to create context specific
|
||
runner panes with sizing and orientation that is relevant for that use case.
|
||
|
||
Script runner:
|
||
VtrOpenRunner {'orientation': 'h', 'percentage': 50}
|
||
|
||
Test runner:
|
||
VtrOpenRunner {'orientation': 'v', 'percentage': 20}
|
||
|
||
Ruby Repl:
|
||
VtrOpenRunner {'orientation': 'h', 'percentage': 50, 'cmd': 'irb'}
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrKillRunner*
|
||
2.5 VtrKillRunner~
|
||
|
||
Kill the tmux runner pane. this pane will kill either the local or detached
|
||
runner pane. this command does nothing if there is currently not a runner
|
||
pane.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrFocusRunner*
|
||
2.6 VtrFocusRunner~
|
||
|
||
Move the cursor to the runner to interact directly with it. A new runner will
|
||
be created if one does not exist and a detached pane will be restored as
|
||
needed.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrResizeRunner*
|
||
2.7 VtrResizeRunner~
|
||
|
||
Prompt for a new percentage then resize the runner pane to that percentage.
|
||
This command will update the |VtrPercentage| setting for the current Vim
|
||
session. The |VtrPercentage| will be reset if Vim is closed. By default, the
|
||
runner will be cleared after resizing, but this behavior can be disabled
|
||
with the |VtrClearOnResize| setting.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrReorientRunner*
|
||
2.8 VtrReorientRunner~
|
||
|
||
Switch the runner pane from its current orientation to the alternate
|
||
orientation (horizontal or vertical). The |VtrPercentage| will be maintained
|
||
through the reorientation. By default, the runner will be cleared after
|
||
reorienting, but this behavior can be disabled with the |VtrClearOnReorient|
|
||
setting.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrDetachRunner*
|
||
2.9 VtrDetachRunner~
|
||
|
||
Detach the runner pane to its own window while keeping the cursor focus on the
|
||
Vim window. This command is useful if there are details in the runner pane or
|
||
significant setup implemented in the runner pane that will be useful at a
|
||
later time, but current the runner pane is not needed. Rather than killing the
|
||
runner, this command simply stashes it away in its own window until it is
|
||
needed again. The runner can later be restored with any of |VtrReattachRunner|,
|
||
|VtrOpenRunner|, or |VtrFocusRunner|. The runner can still be killed with the
|
||
|VtrKillRunner| command.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrReattachRunner*
|
||
2.10 VtrReattachRunner~
|
||
|
||
Reattach the runner pane. This command assumes that the runner has previously
|
||
been dismissed using the |VtrDetachRunner| command. The pane will be restored
|
||
with the last |VtrOrientation| and |VtrPercentage| combination used. By
|
||
default the runner pane will be cleared after being reattached, but this
|
||
behavior can be disabled using the |VtrClearOnReattach| setting.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearRunner*
|
||
2.11 VtrClearRunner~
|
||
|
||
Send the key sequence defined by the |VtrClearSequence| setting to the runner.
|
||
By default this will clear any unfinished commands at the shell prompt and
|
||
move the prompt up to hide any previous command output.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrFlushCommand*
|
||
2.12 VtrFlushCommand~
|
||
|
||
Flush the previous run command variable. After running this command, the next
|
||
run of |VtrSendCommandToRunner| will again prompt for the command to run.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendCtrlD*
|
||
2.12 VtrSendCtrlD~
|
||
|
||
Send Ctrl-D key sequence to the runner without resetting the current command.
|
||
This is useful if you are repeatedly running a script in the debugger and
|
||
regularly need to kill the repl.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendFile*
|
||
:VtrSendFile[!]
|
||
|
||
Send a command to execute the current file as a script. The command will be
|
||
crafted based on the filetype of the current buffer, e.g. for a file "foo.rb"
|
||
(filetype "ruby"), the command would be "ruby {filename}" with {filename}
|
||
populated based on the current file. There are default configurations provided
|
||
for ruby, javascript (via node), python, and sh. You can override and or add
|
||
by defining a dictionary in your Vimrc, e.g.:
|
||
|
||
let g:vtr_filteype_runner_overrides = {
|
||
\ 'ruby': 'ruby -w {file}',
|
||
\ 'haskell': 'runhaskell {file}'
|
||
\ }
|
||
|
||
The key for each entry should be the fileype, and the value is a string for
|
||
which the {file} portion will be replaced by the current file name when run.
|
||
Any settings in your g:vtr_filteype_runner_overrides will take precedence
|
||
over the default values.
|
||
|
||
This command expects a runner to be attached. Add ! to force a runner.
|
||
|
||
==============================================================================
|
||
CONFIGURATION (3) *VTR-Configuration*
|
||
|
||
You can configure VTR using the following settings:
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrPercentage*
|
||
3.1 g:VtrPercentage~
|
||
|
||
The percent of the tmux window the runner pane will occupy.
|
||
|
||
let g:VtrPercentage = 35
|
||
|
||
Default: 20
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrOrientation*
|
||
3.2 g:VtrOrientation~
|
||
|
||
The orientation used when creating the tmux split pane to use as the runner
|
||
pane. The orientation argument is the inverse of Vim's, ie "horizontal" splits
|
||
in tmux will create a new pane to the right of the existing pane.
|
||
|
||
let g:VtrOrientation = "h"
|
||
|
||
Options:
|
||
"v": vertical (split pane below Vim pane)
|
||
"h": horizontal (split pane to the right of Vim pane)
|
||
|
||
Default: "v"
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrInitialCommand*
|
||
3.3 g:VtrInitialCommand~
|
||
|
||
Provide a command to be run just after the runner pane is created. This can
|
||
be used to set the working directory, define an environment variable, etc.
|
||
No command will be run if this is set to an empty string.
|
||
|
||
let g:VtrInitialCommand = "cd .."
|
||
|
||
Default: ""
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrGitCdUpOnOpen*
|
||
3.4 g:VtrGitCdUpOnOpen~
|
||
|
||
When opening a new runner, if currently within a git repo then change the
|
||
working directory to the root of the git repo. This can be useful for some
|
||
test runners which behave differently depending on where they are run from. By
|
||
default this functionality is disabled.
|
||
|
||
let g:VtrGitCdUpOnOpen = 1
|
||
|
||
Default: 0
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearBeforeSend*
|
||
3.5 g:VtrClearBeforeSend~
|
||
|
||
Before sending a command to the runner pane, send the clear sequence defined
|
||
by the |VtrClearSequence| setting. This will make it easier to view and
|
||
interpret the output in the runner pane. Set this to 0 to disable.
|
||
|
||
let g:VtrClearBeforeSend = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrPrompt*
|
||
3.5 g:VtrPrompt~
|
||
|
||
The string used when prompting for a command to run. It is best to include a
|
||
space at the end of this string to visually separate the prompt from the users
|
||
command.
|
||
|
||
let g:VtrPrompt = "What can I do you for?: "
|
||
|
||
Default: "Command to run: "
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrUseVtrMaps*
|
||
3.6 g:VtrUseVtrMaps~
|
||
|
||
Allow VTR to define a set of key mappings to provide easy access to the VTR
|
||
command set. As a Vim user, I consider my <leader> space to be sacred, so
|
||
these maps are disabled by default. To allow VTR to set its maps, add the
|
||
following to your vimrc:
|
||
|
||
let g:VtrUseVtrMaps = 1
|
||
|
||
The following normal mode maps are provided when g:VtrUseVtrMaps is set to 1:
|
||
|
||
Mapping | Command
|
||
-----------------------------
|
||
<leader>rr | VtrResizeRunner<cr>
|
||
<leader>ror | VtrReorientRunner<cr>
|
||
<leader>sc | VtrSendCommandToRunner<cr>
|
||
<leader>sl | VtrSendLineToRunner<cr>
|
||
<leader>or | VtrOpenRunner<cr>
|
||
<leader>kr | VtrKillRunner<cr>
|
||
<leader>fr | VtrFocusRunner<cr>
|
||
<leader>dr | VtrDetachRunner<cr>
|
||
<leader>ar | VtrReattachRunner<cr>
|
||
<leader>cr | VtrClearRunner<cr>
|
||
<leader>fc | VtrFlushCommand<cr>
|
||
|
||
In addition, a single visual mode map is provided to send a visually selected
|
||
region to the runner pane:
|
||
|
||
Mapping | Command
|
||
-----------------------------
|
||
<leader>sv | VtrSendSelectedToRunner<cr>
|
||
|
||
Default: 0
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearOnResize*
|
||
3.7 g:VtrClearOnResize~
|
||
|
||
Send the |VtrClearSequence| after resizing the runner via the
|
||
|VtrResizeRunner| command. This option is turned off by default as
|
||
most often a resize is used to better see the content currently in
|
||
the runner pane.
|
||
|
||
let g:VtrClearOnResize = 1
|
||
|
||
Default: 0
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearOnReorient*
|
||
3.8 g:VtrClearOnReorient~
|
||
|
||
Send the |VtrClearSequence| after reorienting the runner via the
|
||
|VtrReorientRunner| command.
|
||
|
||
let g:VtrClearOnReorient = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearOnReattach*
|
||
3.9 g:VtrClearOnReattach~
|
||
|
||
Send the |VtrClearSequence| after reattaching the runner via the
|
||
|VtrReattachRunner| command.
|
||
|
||
let g:VtrClearOnReattach = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrDetachedName*
|
||
3.10 g:VtrDetachedName~
|
||
|
||
The name to use for the temporary window used when dismissing the runner via
|
||
the |VtrDetachRunner| command. This is provided in the rare event that the
|
||
window name "VTR_Pane" is already used and you would like to distinguish the
|
||
VTR detached runner pane window.
|
||
|
||
let g:VtrDetachedName = "WildAndWackyWindowName"
|
||
|
||
Default: "VTR_Pane"
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearSequence*
|
||
3.11 g:VtrClearSequence~
|
||
|
||
The character sequence to send to clear the runner. This sequence is used in
|
||
the explicit VTR comamnd |VtrClearRunner|. In addition, the sequence may be
|
||
used with the commands |VtrSendCommandToRunner|, |VtrResizeRunner|,
|
||
|VtrReattachRunner|, and |VtrReorientRunner| depending on the current value of
|
||
their respective "ClearOn" settings.
|
||
|
||
The default sequence will clear any unfinished commands sent to the shell
|
||
prompt within the runner pane and clear the scrollback history to present a
|
||
clean prompt ready for the next command. The character literals, , for
|
||
<Ctrl-u> and <Ctrl-l> respectively, can be inserted using <Ctrl-v> while in
|
||
insert mode. See the help file, ':help i_Ctrl-v', for more detail.
|
||
|
||
let g:VtrClearSequence = " "
|
||
|
||
Default: " "
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrStripLeadningWhitespace*
|
||
|
||
3.12 g:VtrStripLeadingWhitespace~
|
||
|
||
When interacting with most REPLs, indentation will automatically be added to
|
||
the beginning of lines based on the syntax. The setting causes VTR to strip
|
||
leading whitespace before sending lines to avoid doubly indented lines.
|
||
|
||
By default this setting is enabled, but if you are using a language with
|
||
syntactic whitespace like python or coffeescript then you will likely want to
|
||
disable this setting.
|
||
|
||
let g:VtrStripLeadingWhitespace = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearEmptyLines*
|
||
|
||
3.13 g:VtrClearEmptyLines~
|
||
|
||
VTR will clear out empty lines in visually selected regions to avoid clutter in
|
||
the REPLs. If the blank lines are relevant, you can disable this behavior.
|
||
|
||
let g:VtrClearEmptyLines = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrAppendNewline*
|
||
|
||
3.14 g:VtrAppendNewline
|
||
|
||
If you are using python or any language with syntactic whitespace, an empty
|
||
line might be needed to close the preceding context. To enable appending a new
|
||
line to any multi line send, use the following setting.
|
||
|
||
let g:VtrAppendNewline = 1
|
||
|
||
Default: 0
|
||
|
||
==============================================================================
|
||
vim:tw=78:ts=2:sw=2:expandtab:ft=help:norl:
|