diff options
Diffstat (limited to '.vim/doc/screen.txt')
| -rw-r--r-- | .vim/doc/screen.txt | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/.vim/doc/screen.txt b/.vim/doc/screen.txt new file mode 100644 index 0000000..12c78fe --- /dev/null +++ b/.vim/doc/screen.txt @@ -0,0 +1,390 @@ +*screen.txt* + +Author: Eric Van Dewoestine <ervandew@gmail.com> + +This plugin is licensed under the terms of the BSD License. Please see +screen.vim for the license in its entirety. + +----------------------------------------------------------------------------- +Screen *screen* + +Introduction |screen-intro| +Screen Usage |screen-usage| + :ScreenShell |screen-shell| + :ScreenShellAttach |screen-shellattach| + :ScreenSend |screen-send| + :ScreenQuit |screen-quit| +Screen Options |screen-options| + Terminal muliplexer |screen-impl| + Shell height |screen-shellheight| + Quit on exit |screen-quitonexit| + External shell |screen-externalshell| + Server name |screen-servername| + Terminal |screen-terminal| +Custom mappings |screen-mappings| +Script integration |screen-scriptintegration| +Gotchas |screen-gotchas| +Troubleshooting |screen-troubleshooting| + +----------------------------------------------------------------------------- +Introduction *screen-intro* + +This plugin aims to simulate an embedded shell in vim by allowing you to +easily convert your current vim session into one running in gnu screen with a +split gnu screen window containing a shell, and to quickly send +statements/code to whatever program is running in that shell (bash, python, +irb, etc.). Spawning the shell in your favorite terminal emulator is also +supported for gvim users or anyone else that just prefers an external shell. + +Currently tested on Linux and Windows (win32 gvim and cygwin vim), but +should also work on any unix based platform where screen is supported (OSX, +BSD, Solaris, etc.). Note that in my testing of cygwin, invocations of screen +were significantly slower and less fluid than on Linux. The Windows +experience is better when using gvim to spawn a cygwin shell running screen. + +Tmux Users: On non-windows systems, tmux is also supported in place of gnu +screen. To use tmux simply add the following to your vimrc: + let g:ScreenImpl = 'Tmux' + + Note: With tmux, :ScreenShellAttach is currently not supported. + +Windows Users: Whether you are using gvim or not, you will need cygwin +installed with cygwin's bin directory in your windows PATH. + +----------------------------------------------------------------------------- +Screen usage *screen-usage* + +Here is a sample workflow utilizing screen.vim to execute some python code in +the python interactive interpreter: + + 1. Edit a python file + $ vim something.py + + 2. Decide you want to run all or pieces of the code in an interactive python + shell + :ScreenShell python + + 3. Send code from a vim buffer to the shell + :ScreenSend + + 4. Quit the screen session and return to your original vim session + :ScreenQuit + or + :qa + +Below is a comprehensive list of the commands which screen.vim provides: + +:ScreenShell [cmd] *screen-shell* *:ScreenShell* + Starts a screen hosted shell performing the following steps depending on + your environment. + + When running a console vim on a unix based OS (Linux, BSD, OSX): + 1. save a session file from your currently running vim instance + (current tab only) + 2. start gnu screen with vim running in it + 3. load your saved session file + 4. create a lower gnu screen split window and start a shell, or if + g:ScreenShellExternal is set, start an external terminal with + screen running. + 5. if a command was supplied to :ScreenShell, run it in the new + shell. + Ex. :ScreenShell ipython + + Note: If you are already in a gnu screen session, then only steps + 4 and 5 above will be run. + + When running gvim: + 1. start an external terminal with screen running. + 2. if a command was supplied to :ScreenShell, run it in the new + shell. + Ex. :ScreenShell ipython + +:ScreenShellVertical [cmd] *screen-shell-vertical* *:ScreenShellVertical* + Just like |:ScreenShell| but when creating the split region for the shell, a + vertical split is used instead of the default horizontal split. Supported + via tmux by default, but gnu screen requires the vertical split patch + (http://fungi.yuggoth.org/vsp4s/) or the unreleased screen 4.1 code and you + must explicitly enable support for gnu screen vertical splitting in + screen.vim by adding the following to your vimrc, indicating whether you are + using a patched gnu screen or the 4.1 code base: + let g:ScreenShellGnuScreenVerticalSupport = 'patch' + or + let g:ScreenShellGnuScreenVerticalSupport = 'native' + + +:ScreenShellAttach [session] *screen-shellattach* *:ScreenShellAttach* + Sets the necessary internal variables to allow :ScreenSend invocations to + send to the specified screen session. If no session is provided, then the + first session found is used. If the session is in the "Detached" state, + then a new terminal is opened with a new screen instance attached to the + session. Attaching to a detached session is not currently supported on + windows due to deficiencies in the cygwin version of gnu screen. + + Note: for screen sessions attached to via this mechanism, :ScreenSend + invocations will send the text to the active screen window instead of + targeting the 'shell' window when used from :ScreenShell. However, this + behavior can be configured via the g:ScreenShellAttachTargetCurrent + variable, which when non 0, will set the title on the currently focused gnu + screen window and target it for all send commands. + +:ScreenSend + Send the visual selection or the entire buffer contents to the running gnu + screen shell window. + +:ScreenQuit + Save all currently modified vim buffers and quit gnu screen, returning you + to your previous vim instance running outside of gnu screen + + Note: :ScreenQuit is not available if you where already in a gnu + screen session when you ran :ScreenShell. + Note: By default, if the gnu screen session was started by + :ScreenShell, then exiting vim will quit the gnu screen session as + well (configurable via g:ScreenShellQuitOnVimExit). + + +----------------------------------------------------------------------------- +Screen Options *screen-options* + +Screen is configured via several global variables that you can set in your +|vimrc| file according to your needs. Below is a comprehensive list of the +variables available. + +Terminal Multiplexer *screen-impl* + *g:ScreenImpl* + +g:ScreenImpl (default value: 'GnuScreen') + +This sets the name of the terminal multiplexer you want to use. Support +values include 'GnuScreen' or 'Tmux'. + + +Shell height *screen-shellheight* + *g:ScreenShellHeight* + +g:ScreenShellHeight (default value: 15) + +Sets the height of the gnu screen (or tmux) region used for the shell. When +the value is less than or equal to 0, then half of vim's reported window +height will be used. + + +Shell width *screen-shellwidth* + *g:ScreenShellWidth* + +g:ScreenShellWidth (default value: -1) + +Sets the width of the gnu screen (or tmux) region used for the shell when +splitting the region vertically (vertical split support in gnu screen requires +the vertical split patch). When the value is less than or equal to 0, then +half of vim's reported window width will be used. + + +Quit on exit *screen-quitonexit* + *g:ScreenShellQuitOnVimExit* + +g:ScreenShellQuitOnVimExit (default value: 1) + +When non-zero and the gnu screen (or tmux) session was started by this script, +the screen session will be closed when vim exits. + + +External Shell *screen-externalshell* + *g:ScreenShellExternal* + +g:ScreenShellExternal (default value: 0) + +When non-zero and not already in a screen session, an external shell will be +spawned instead of using a split region for the shell. Note: when using gvim, +an external shell is always used. + + +Initial focus *screen-focus* + *g:ScreenShellInitialFocus* + +g:ScreenShellInitialFocus (default value: 'vim') + +When set to 'shell' the newly created shell region will be focused when first +creating the shell region. + + +Server Name *screen-servername* + *g:ScreenShellServerName* + +g:ScreenShellServerName (default value: 'vim') + +If the gnu screen session is started by this plugin, then the value of this +setting will be used for the servername arg of the vim instance started in the +new gnu screen session (not applicable for gvim users). The default is 'vim' +unless you have g:ScreenShellExternal enabled, in which case, if you still +want to restart vim in a screen session with a servername, then simply set +this variable in your vimrc. + + +Terminal *screen-terminal* + *g:ScreenShellTerminal* + +g:ScreenShellTerminal (default value: '') + +When g:ScreenShellExternal is enabled or you are running gvim, this value will +be used as the name of the terminal executable to be used. If this value is +empty, a list of common terminals will be tried until one is found. + + +Expand Tabs *screen-expandtabs* + *g:ScreenShellExpandTabs* + +g:ScreenShellExpandTabs (default value: 0) + +When sending text from vim to an external program, that program may interpret +tabs as an attempt to perform completion resulting in the text sent not +performing the function you intended. As a work around, you can set this +setting to a non 0 value resulting in all tabs being expanded to spaces before +sending the text to screen/tmux. + +----------------------------------------------------------------------------- +Custom Mappings *screen-mappings* + +Defining custom key mappings for for screen.vim can be accomplished like with +any other plugin: > + nmap <C-c><C-c> :ScreenShell<cr> +> + +But you may want to have different mappings depending on the whether you have +an active screen shell open or not. For this case screen.vim provides a couple +autocmd groups which you can use to listen for entering or exiting of a screen +shell session. Here is an example which sets some global key bindings based +on the screen shell state: > + + function! s:ScreenShellListener() + if g:ScreenShellActive + nmap <C-c><C-c> :ScreenSend<cr> + nmap <C-c><C-x> :ScreenQuit<cr> + else + nmap <C-c><C-c> :ScreenShell<cr> + endif + endfunction + + nmap <C-c><C-c> :ScreenShell<cr> + augroup ScreenShellEnter + autocmd User * call <SID>ScreenShellListener() + augroup END + augroup ScreenShellExit + autocmd User * call <SID>ScreenShellListener() + augroup END +> + +You can also take this a step further and do the same as the above, but do so +on a per filetype basis, where the key binding are buffer local and interact +with the filetype's associated interpreter. Here is an example which can be +put in a python ftplugin: > + + function! s:ScreenShellListener() + if g:ScreenShellActive + if g:ScreenShellCmd == 'python' + nmap <buffer> <C-c><C-c> :ScreenSend<cr> + else + nmap <buffer> <C-c><C-c> <Nop> + endif + else + nmap <buffer> <C-c><C-c> :ScreenShell python<cr> + endif + endfunction + + call s:ScreenShellListener() + augroup ScreenShellEnter + autocmd User *.py call <SID>ScreenShellListener() + augroup END + augroup ScreenShellExit + autocmd User *.py call <SID>ScreenShellListener() + augroup END +> + +Note how the :ScreenShell mapping starts the python interpreter. Before +mapping the :ScreenSend command, the function also checks if the shell was +started with the 'python' command, allowing you to unmap (<Nop> in this case +to counter act any global defined mapping) the send command if some other +shell command is running (irb, lisp interpreter, etc). + +----------------------------------------------------------------------------- +Script Integration *screen-scriptintegration* + +To permit integration with your own, or 3rd party, scripts, a funcref is made +globally available while the screen shell mode is enabled, allowing you to +send your own strings to the attached shell. + +Here are some examples of using this funcref to send some commands to bash: > + :call ScreenShellSend("echo foo\necho bar") + :call ScreenShellSend('echo -e "foo\nbar"') + :call ScreenShellSend("echo -e \"foo\\nbar\"") +> + +Sending a list of strings is also supported: > + :call ScreenShellSend(["echo foo", "echo bar"]) +> + +You can test that the funcref exists using: > + exists('ScreenShellSend') +> + +In addition to sending text to the screen shell, another funcref is available +allowing you to focus the shell region in screen. Note: focusing an external +screen shell is not supported. + +To focus the shell region from vim you can invoke the funcref like so: > + :call ScreenShellFocus() +> + +This will focus the bottom most region which is expected to be the one running +your shell or other program. + + +----------------------------------------------------------------------------- +Gotchas *screen-gotchas* + +While running vim in gnu screen, if you detach the session instead of +quitting, then when returning to the non-screen vim, vim will complain about +swap files already existing. So try to avoid detaching. + +Not all vim plugins support saving state to or loading from vim session files, +so when running :ScreenShell some buffers may not load correctly if they are +backed by such a plugin. + + +----------------------------------------------------------------------------- +Troubleshooting *screen-troubleshooting* + +Below are a list of possible issues you may encounter and some info on +resolving those issues. + +- When already in a screen session, running :ScreenShell results in a nested + screen session instead of using the existing one. + *screen-bootstrap* + + When running :ScreenShell from a console version of vim, screen.vim examines + the $TERM environment variable which it expects to start with 'screen' + ('screen', 'screen-256color', etc.) if you are in an existing screen/tmux + session. Should the TERM value not start with 'screen', then screen.vim + assumes that a screen session must be started for you. + + The cause of TERM not containing a 'screen' values is usually the result of + having a non-screen term value in your ~/.screenrc or the term value you are + using doesn't have a corresponding terminfo file resulting in $TERM being + set to some other value. Take a look at the |screen-256color| docs below for + more information. + +- 256 color support *screen-256color* + + To enable 256 color support in screen you'll need to add the following to + your ~/.screenrc: + + term screen-256color + + Please note that this will set your $TERM to 'screen-256color' which will + require that your system has a corresponding terminfo file. Not all systems + have this installed by default so you may need to install an additional + package: + + ubuntu - $ apt-get install ncurses-term + + +vim:tw=78:ts=8:ft=help:norl: |