*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 ............................... |VtrSendLinesToRunner| 2.3 ............................... |VtrOpenRunner| 2.4 ............................... |VtrKillRunner| 2.5 ............................... |VtrFocusRunner| 2.6 ............................... |VtrResizeRunner| 2.7 ............................... |VtrReorientRunner| 2.8 ............................... |VtrDetachRunner| 2.9 ............................... |VtrReattachRunner| 2.10 ............................... |VtrClearRunner| 2.11 ............................... |VtrFlushCommand| 2.12 ............................... |VtrSendCtrlD| 2.13 ............................... |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 command VtrSendLinesToRunner 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|. ------------------------------------------------------------------------------ *VtrSendLinesToRunner* 2.2 VtrSendLinesToRunner~ Send the current line or the current visual selection from the Vim buffer to the runner pane for execution. ------------------------------------------------------------------------------ *VtrOpenRunner* 2.3 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.4 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.5 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.6 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.7 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.8 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.9 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.10 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.11 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* 2.13 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 elixir, javascript (via node), python, ruby, and sh. You can override and or add by defining a dictionary in your Vimrc, e.g.: let g:vtr_filetype_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_filetype_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 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 ----------------------------- rr | VtrResizeRunner ror | VtrReorientRunner sc | VtrSendCommandToRunner sl | VtrSendLinesToRunner or | VtrOpenRunner kr | VtrKillRunner fr | VtrFocusRunner dr | VtrDetachRunner ar | VtrReattachRunner cr | VtrClearRunner fc | VtrFlushCommand In addition, a single visual mode map is provided to send a visually selected region to the runner pane: Mapping | Command ----------------------------- sl | VtrSendLinesToRunner 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 and respectively, can be inserted using 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: