*screenpaste.txt* Paste/insert GNU Screen buffer in (almost) any mode v5.92 $Id: screenpaste.txt,v 8624db9970aa 2008-11-08 21:33 +0100 blacktrash $ For instructions on installing this file, type :help add-local-help inside Vim. Author: Christian Ebert SCREENPASTE REFERENCE MANUAL~ *screenpaste* *screenpaste.vim* ============================================================================== 1. Contents *screenpaste-toc* Screen Paste Plugin |screenpaste-intro| Installation |screenpaste-install| Usage |screenpaste-usage| Options |screenpaste-options| Changing Mappings |screenpaste-mappings| Commands |screenpaste-commands| Bugs and Limitations |screenpaste-bugs| ============================================================================== 2. Screen Paste Plugin *screenpaste-intro* The terminal window manager Screen http://www.gnu.org/software/screen offers the capability to copy and paste between windows. In principle you can just do "C-a ]" (default) to paste the current Screen buffer into a vim buffer. However this gives unexpected results when 'paste' is not set or in Vim's command-line. This script provides mappings and commands to get correct results. As an additional feature the current Screen buffer is available in any Vim instance, even those /outside/ the current Screen session. When pasting into command-line many commands are autodetected and the behaviour adapts automatically (|getcmdtype()|). The underlying mechanism of screenpaste consists in getting hold of the current Screen buffer via calling to Screen to write it to a temporary file. At this point Vim takes over, reads the contents of the file, and puts them to use either directly (in Insert, Replace or Command-line mode) or, in Normal and Visual mode, by writing to a register and, most often, putting the contents of the register into the Vim buffer. Which is why the default keybindings mimic |p|, |P|, |gp|, |gP|, with the |mapleader| prepended, as well as |:ScreenPut| and |:ScreenYank| behave almost like |:put| and |:yank| respectively. ============================================================================== 3. Installation *screenpaste-install* The screenpaste plugin comprises three files: screenpastePlugin.vim, screenpaste.vim and screenpaste.txt (this file). To install the plugin, copy screenpastePlugin.vim into a 'plugin' directory in your runtime path and screenpaste.vim into the corresponding 'autoload' directory. See |add-global-plugin| and |'runtimepath'|. This help file goes into a 'doc' directory in the runtime path. Then execute |:helptags|, specifying the full path of the 'doc' directory. See |add-local-help| for details. The GNU Screen executable has to be in $PATH. Otherwise screenpaste bails out giving an error message. ============================================================================== 4. Usage *screenpaste-usage* Think of the current Screen buffer as of a register at your disposal via the |screenpaste| mappings and commands. *screenpaste-put* When you type the plugin's Ex command > :ScreenPut this works like executing |:put| with the current Screen buffer as register. It puts the text after the current line. Like |:put| it accepts a prepended number as parameter designating the target line as well as an appended bang to put the text before the indicated line and an optional register argument which defaults to |screen_register| when omitted. |:ScreenPut| differs from |:put| as the register is not only written into the buffer but filled with the current Screen buffer beforehand. *screenpaste-yank* If you want to just get hold of the current Screen buffer for further processing, type > :ScreenYank > and the Screen buffer is at your disposal in the |screen_register|. Similar to |:yank| you can also execute the command with an explicit register argument. Note: Screen's copy mechanism discards spaces at the end and the beginning of a selection in case there are printable characters in the same line. In Vim terms one could consider this like selecting 'exclusive', and to get a |linewise| "yank" the selection has to span visually more than one line, the newline at the end of a visually selected single line is not included. All other commands configure the treatment of the current Screen buffer when it is pasted into the command-line. Please refer to |screen_clmode| and |screenpaste-commands| for further information. Mappings:~ In |Insert|, |Replace|, and |Command-line| modes (by default) simply type: > \p to paste the current Screen buffer. In these modes the |screen_register| is not changed. Note: mappings are ignored in Insert mode while |'paste'| is set. But in that case Screen's "paste" command (bound to "C-a]" by default) works just fine and there's no need to work around this via |'pastetoggle'|. The plugin's mappings for |Normal| and |Visual| mode emulate the non-Ex commands |p|, |P|, |gp|, and |gP|: They put the text of the current Screen buffer after or before the cursor, or replace the visual selection with it, just as if the unnamed register would contain the current Screen buffer (see |screen_register|). If the Screen buffer is empty they do nothing, the registers stay untouched, and only a corresponding message is displayed in the menu. Note however that the optional initial [count] argument to the original non-Ex commands will not work with these mappings (|screenpaste-bugs|). In their default state the |Normal| and |Visual| mode mappings consist of the same letters as the corresponding non-Ex commands with the |mapleader| prepended: > p P (not in Visual) gp gP (not in Visual) For simplicity we use the default |screenpaste-mappings| and the default || "\" in the following description. *screenpaste-p* \p Put current Screen buffer after the cursor. *screenpaste-P* \P Put current Screen buffer before the cursor. Not available in Visual mode. *screenpaste-gp* \gp Like "\p" but leave the cursor after the pasted text. *screenpaste-gP* \gP Like "\P" but leave the cursor after the pasted text. Not available in Visual mode. In |Visual| mode we do not need "\P" and "\gP" as "\p" and "\P" have the same effect of replacing the Visual selected text with the current Screen buffer. To summarize, supposing the default || "\" and the default |screenpaste-mappings| you can type: > \p in Normal mode to put Screen buffer after cursor \gp in Normal mode to put Screen buffer after cursor and leave cursor after the end of new text \P in Normal mode to put Screen buffer before cursor \gP in Normal mode to put Screen buffer before cursor and leave cursor after the end of new text \p in Visual mode to replace visual selection with Screen buffer \gp in Visual mode to put Screen buffer after cursor and leave cursor after the end of new text \p in Insert and Replace mode to paste Screen buffer \p in Command-line-mode to put Screen buffer in command line ============================================================================== 5. Options *screenpaste-options* g:loaded_screenpaste *loaded_screenpaste* This option normally is set by screenpaste to avoid loading the script more than once. But you can use it to get the current script version: > :echo loaded_screenpaste < If you want to disable screenpaste, put the following line in your |vimrc|: > let g:loaded_screenpaste = 1 g:screen_executable *screen_executable* Type String Default Value 'screen' Set this option if the name of your GNU Screen executable differs from "screen", or if you like to specify it's full path: > let g:screen_executable = "/usr/local/bin/screen" g:screen_wait *screen_wait* Type String or Number Valid Values See |:sleep| Default Value '333m' How long Vim should wait for Screen to write its exchange file. If you get messages that the Screen buffer is empty even though you know that it actually is not, bump up this setting. g:screen_visualselect *screen_visualselect* Type Boolean Default Value 0 If set to 1 and in Visual mode the text from the Screen buffer is visually selected after the put operation. g:screen_register *screen_register* Type String or Number Valid Values "a-z0-9A-Z Default Value '"' The non-Ex put "commands" (mappings) act in a twofold operation when executed in Normal or Visual mode: they yank the Screen buffer into a register in the background, and then put the register into the buffer or command-line. This variable controls the register that is used for the first part of the operation. It defaults to the unnamed register "" (|quotequote|). Normally you should be fine with the default setting. But if you prefer to reserve a register of your choice for the Screen buffer you can do so with this option. Besides the default "", you may choose any named (|quote_alpha|) or numbered (|quote_number|) register. Consult |registers| about their behaviour. For a one time operation with a special register the use of |ScreenPut| ex-command and its register argument is recommended. Note: Specifying an uppercase letter means that the contents of the Screen buffer will be appended to the register named with the corresponding lowercase character (|quote_alpha|). g:screen_clmode *screen_clmode* Type String Valid Values 'search', 'sub', 'noesc' Default Value 'search' This setting controls how the Screen buffer is treated when pasted in the command line. You can change the setting at startup in your |vimrc|: > let g:screen_clmode = "sub" < To change its value in a vim session you might want to use one of the |:ScreenCmdlineConf|, |:ScreenSearch|, |:ScreenSub|, |:ScreenNoEsc| commands as they also give a short informative message on how the mode of your choice will act, and prevent you from setting an invalid value. Information on the current value and the resulting behaviour is also available via the |:ScreenCmdlineInfo| command. Modes and their behaviour: *screenpaste-search* 'search' ~ Converts end-of-line to literal '\n'. Escapes characters according to the current setting of 'magic': magic: [ ] / \ ^ * . ~ $ nomagic: ] / \ ^ $ Use this mode to search for occurrences of current Screen buffer. Example as typed using default mapleader: > :ScreenSearch :%s/\p/repl/g < If the current Screen buffer is `[hello world.]' and 'magic' is set, the above becomes: > :%s/\[hello world\.\]/repl/g < *screenpaste-sub* 'sub' ~ Converts end-of-line to literal '\r'. Escapes characters according to the current setting of 'magic': magic: / \ ~ & nomagic: / \ Use this mode to substitute a pattern with current Screen buffer. Example as typed using default mapleader: > :ScreenSub :%s/pattern/\p/g < If the current Screen buffer is `http://www.vim.org', the above becomes: > :%s/pattern/http:\/\/www.vim.org/g < *screenpaste-noesc* 'noesc' ~ Converts end-of-line to literal '\n'. Use this mode to paste current Screen buffer literally into command line. |/|, |?|, |input()|, |:insert|, and |:append| commands are autodetected when not in 'noesc' |screen_clmode|. This means that even when you are in 'sub' mode you can type: > /\p < and this becomes (using above example for 'search'): > /\[hello world\.\] < Note: If you paste a Screen buffer containing newlines while in an |:insert| or |:append| but outside a running Screen session the newlines are escaped because we cannot call Screen's paste mechanism without clobbering a parallel Screen session, and Vim would insert characters instead (see |NL-used-for-Nul|). ============================================================================== 6. Changing Mappings *screenpaste-mappings* *ScreenpastePut* *ScreenpasteGPut* *ScreenpastePutBefore* *ScreenpasteGPutBefore* The right-hand-side |{rhs}| mappings provided by this plugin and the modes in which to apply them are: > ScreenpastePut Normal, Visual, Insert, Command-line ScreenpasteGPut Normal, Visual ScreenpastePutBefore Normal ScreenpasteGPutBefore Normal < Use these to customize the default mappings p, gp, P, and gP to your taste (see |using-| and |:map-modes|). The default mappings would look like this in a |vimrc|: map p ScreenpastePut " Normal, Visual mode map! p ScreenpastePut " Insert, Command-line mode map gp ScreenpasteGPut " Normal, Visual mode nmap P ScreenpastePutBefore " Normal mode nmap gP ScreenpasteGPutBefore " Normal mode You can tweak them by changing their left-hand-side |{lhs}|. Normal (put after cursor) and Visual mode: default :map {lhs} ScreenpastePut \p :map {lhs} ScreenpasteGPut \gp Vimrc example: > map P ScreenpastePut Normal mode (put before cursor): :nmap {lhs} ScreenpastePutBefore \P :nmap {lhs} ScreenpasteGPutBefore \gP Vimrc example: > nmap I ScreenpastePutBefore Insert and Command-line mode: :map! {lhs} ScreenpastePut \p Vimrc example, to avoid character mappings when inserting: > map! ScreenpastePut ============================================================================== 7. Commands *screenpaste-commands* *:ScreenYank* :ScreenYank [x] Yank current Screen buffer into register [x] (default |screen_register|). *:ScreenPut* :[line]ScreenPut [x] Put the text from current Screen buffer after [line] (default current line) using register [x] (default |screen_register|). You can use this command for instance to append the contents of the Screen buffer to a named register and then paste in one go: > :3 ScreenPut A < puts the contents of register "a and the Screen buffer after line 3. :[line]ScreenPut! [x] Put the text from current Screen buffer before [line] (default current line) using register [x] (default |screen_register|). *:ScreenCmdlineConf* :ScreenCmdlineConf {mode} Tell screenpaste to convert the current Screen buffer in command-line-mode according to {mode}. Takes one argument of: "search", "sub", "noesc" (w/o quotes). Changes |screen_clmode| accordingly. Example: > :ScreenCmdlineConf noesc < *:ScreenCmdlineInfo* :ScreenComdlineInfo Display information on current command-line-mode behaviour, ie. current |screen_clmode| and what it does. *:ScreenSearch* :ScreenSearch Set |screen_clmode| to 'search'. Equivalent to: > :ScreenCmdlineConf search < *:ScreenSub* :ScreenSub Set |screen_clmode| to 'sub'. Equivalent to: > :ScreenCmdlineConf sub < *:ScreenNoEsc* :ScreenNoEsc Set |screen_clmode| to 'noesc'. Equivalent to: > :ScreenCmdlineConf noesc ============================================================================== 8. Bugs and Limitations *screenpaste-bugs* Found no way (yet?) to make optional initial [count] argument work with (Normal mode) mappings. Screen's copy mechanism treats spaces (including newlines) at the beginning or the end of a selection in a different manner than Vim's visual yank does. Screen expands tabs, expect incorrect results if the Screen buffer contains tabs. ============================================================================== vim:tw=78:ts=8:ft=help:norl: