1 " File: screenpaste.vim
2 " Description: pastes/inserts current GNU Screen buffer in (almost) any mode
4 " Mercurial: $Id: screenpaste.vim,v 41183f681647 2008-01-06 17:29 +0100 blacktrash $
5 " Author: Christian Ebert <blacktrash@gmx.net>
6 " Credits: Mathieu Clabaut and Guo-Peng Wen for inline doc self-install code
7 " URL: http://www.vim.org/script.php?script_id=1512
8 " Requirements: GNU Screen must be in $PATH
9 " Documentation: :help screenpaste
10 " self installing to its current version when plugin is loaded
11 " to review before install go to last section of this file
13 " GetLatestVimScripts: 1512 1 :AutoInstall: screenpaste.vim
15 " Init: store 'compatible' settings {{{1
19 if !exists("g:loaded_screenpaste")
20 " Fast Load: global vars, mappings, commands, doc install
21 " load functions only on demand via autocmd
22 " at Vim startup only run checks, load global vars, mappings, commands,
23 " and install Help if not up to date or not present
25 " full path to plugin -- needed for Screen_UpdateDocs and demand load
26 let s:plug_path = expand("<sfile>:p")
27 " name of plugin w/o extension for messages
28 let s:plug_name = fnamemodify(s:plug_path, ":t:r")
30 " Global Variables: {{{1
31 " g:screen_executable: name of GNU Screen executable
32 if !exists("g:screen_executable")
33 let g:screen_executable = "screen"
36 " g:screen_clmode: how screenpaste behaves in Vim's command-line
37 if !exists("g:screen_clmode")
38 let g:screen_clmode = "search"
39 elseif g:screen_clmode !~# '^\%(s\%(earch\|ub\)\|noesc\)$'
40 echomsg s:plug_name.": `".g:screen_clmode."':"
41 \ "invalid value for screen_clmode."
42 \ "Reset to 'search' (default)"
43 let g:screen_clmode = "search"
46 " g:screen_register: instead of register "0 use this one
47 if !exists("g:screen_register")
48 let g:screen_register = '"'
49 elseif g:screen_register !~ '^["0-9a-zA-Z]$'
50 echomsg s:plug_name.": `".g:screen_register."':"
51 \ "invalid value for screen_register."
52 \ "Reset to '\"' (default)"
53 let g:screen_register = '"'
56 if !exists("g:screen_visualselect")
57 let g:screen_visualselect = 0
60 " Checks: for system() and Screen executable {{{1
61 function! s:Screen_CleanUp(msg)
63 echomsg s:plug_name.":" a:msg "Plugin not loaded"
65 let g:loaded_screenpaste = "no"
67 unlet s:save_cpo s:plug_name g:screen_executable g:screen_clmode
70 " bail out if system() is not available
72 call <SID>Screen_CleanUp("builtin system() function not available.")
76 " bail out if GNUscreen is not present
77 if !executable(g:screen_executable)
78 call <SID>Screen_CleanUp("`".g:screen_executable."' not executable.")
82 let s:curr_version = "v5.92"
84 " Mappings: propose defaults {{{1
85 if !hasmapto("<Plug>ScreenpastePut") " nvo
86 map <unique> <Leader>p <Plug>ScreenpastePut
88 if !hasmapto("<Plug>ScreenpasteGPut") " nvo
89 map <unique> <Leader>gp <Plug>ScreenpasteGPut
91 if !hasmapto("<Plug>ScreenpastePutBefore", "n")
92 nmap <unique> <Leader>P <Plug>ScreenpastePutBefore
94 if !hasmapto("<Plug>ScreenpasteGPutBefore", "n")
95 nmap <unique> <Leader>gP <Plug>ScreenpasteGPutBefore
97 if !hasmapto("<Plug>ScreenpastePut", "ic")
98 map! <unique> <Leader>p <Plug>ScreenpastePut
101 " Internal Mappings: {{{1
102 nnoremap <script> <silent> <Plug>ScreenpastePut
103 \ :call <SID>Screen_NPut("p")<CR>
104 nnoremap <script> <silent> <Plug>ScreenpasteGPut
105 \ :call <SID>Screen_NPut("gp")<CR>
106 nnoremap <script> <silent> <Plug>ScreenpastePutBefore
107 \ :call <SID>Screen_NPut("P")<CR>
108 nnoremap <script> <silent> <Plug>ScreenpasteGPutBefore
109 \ :call <SID>Screen_NPut("gP")<CR>
110 vnoremap <script> <silent> <Plug>ScreenpastePut
111 \ :<C-U> call <SID>Screen_VPut("")<CR>
112 vnoremap <script> <silent> <Plug>ScreenpasteGPut
113 \ :<C-U> call <SID>Screen_VPut("g")<CR>
114 inoremap <script> <silent> <Plug>ScreenpastePut
115 \ <C-R>=<SID>Screen_IPut()<CR><C-R>=<SID>Screen_TwRestore()<CR>
116 cnoremap <script> <Plug>ScreenpastePut
117 \ <C-R>=<SID>Screen_CPut()<CR>
120 " configuration for command-line-mode
121 " in v:version >= 700 this works with <SID>
122 function! Screen_ClCfgComplete(A, L, P)
123 return "search\nsub\nnoesc"
125 command -nargs=1 -complete=custom,Screen_ClCfgComplete
126 \ ScreenCmdlineConf call <SID>Screen_ClConfig(<f-args>, 1)
127 command ScreenCmdlineInfo call <SID>Screen_ClConfig(g:screen_clmode, 1)
128 command ScreenSearch call <SID>Screen_ClConfig("search", 1)
129 command ScreenSub call <SID>Screen_ClConfig("sub", 1)
130 command ScreenNoEsc call <SID>Screen_ClConfig("noesc", 1)
131 " yank Screen buffer into register (default: screen_register)
132 command -register ScreenYank call <SID>Screen_Yank("<register>")
134 command -count=0 -bang -register ScreenPut
135 \ call <SID>Screen_PutCommand("<count>", "<bang>", "<register>")
138 " ===== end of public configuration ==========================================
139 " Help Install: automatically when needed {{{1
140 " Function: Screen_FlexiMkdir tries to adapt to system {{{2
141 function! s:Screen_FlexiMkdir(dir)
144 elseif !exists("+shellslash")
145 call system("mkdir -p '".a:dir."'")
147 let l:ssl = &shellslash
150 " no single spaces for M$? (untested)
151 call system('mkdir "'.a:dir.'"')
153 let &shellslash = l:ssl
159 " and now the doc install itself
160 function! s:Screen_UpdateDocs()
161 " figure out document path
162 let l:vim_doc_dir = fnamemodify(s:plug_path, ":h:h")."/doc"
163 if filewritable(l:vim_doc_dir) != 2
164 let l:doc_install_intro = s:plug_name." doc install:"
165 echomsg l:doc_install_intro "Trying doc path" l:vim_doc_dir
166 echomsg " relative to" s:plug_path
167 silent! call <SID>Screen_FlexiMkdir(l:vim_doc_dir)
168 if filewritable(l:vim_doc_dir) != 2
169 " try first item in 'runtimepath' which is comma-separated list
171 \ substitute(&runtimepath, '^\([^,]*\).*', '\1/doc', 'e')
172 echomsg l:doc_install_intro "Trying doc path" l:vim_doc_dir
173 echomsg " using first item of 'runtimepath'"
174 if filewritable(l:vim_doc_dir) != 2
175 silent! call <SID>Screen_FlexiMkdir(l:vim_doc_dir)
176 if filewritable(l:vim_doc_dir) != 2
178 echomsg l:doc_install_intro "Unable to detect writeable doc directory"
179 echomsg " type `:help add-local-help' for more information"
185 " full name of help file
186 let l:doc_file = l:vim_doc_dir."/".s:plug_name.".txt"
187 " bail out if document file is still up to date
188 if filereadable(l:doc_file) &&
189 \ getftime(s:plug_path) < getftime(l:doc_file)
192 let l:lz = &lazyredraw
193 let l:hls = &hlsearch
194 set lazyredraw nohlsearch
195 " create a new buffer & read in the plugin file
197 setlocal noswapfile modifiable nomodeline
199 setlocal nofoldenable
201 silent execute "read" escape(s:plug_path, " ")
202 let l:doc_buf = bufnr("%")
204 " delete from first line line starting with
206 silent 1,/^=\{3,}\s\+START_DOC\C/ delete _
207 " delete from line starting with
210 silent /^=\{3,}\s\+END_DOC\C/,$ delete _
211 " add modeline for help, modeline string mangled intentionally
212 " to avoid its being recognized when it is parsed
213 call append(line("$"), "")
214 call append(line("$"), " v"."im:tw=78:ts=8:ft=help:norl:")
216 silent execute "normal :1s/#version#/ ".s:curr_version."/\<CR>"
217 " write file `screenpaste.txt'
218 silent execute "wq!" escape(l:doc_file, " ") "| bwipeout" l:doc_buf
220 silent execute "helptags" l:vim_doc_dir
221 let &hlsearch = l:hls
222 let &lazyredraw = l:lz
226 if <SID>Screen_UpdateDocs()
227 echomsg s:plug_name s:curr_version.": updated documentation"
230 " Demand Load: via autcmd FuncUndefined : {{{1
231 " get the current script ID
232 function! s:Screen_SID()
233 " <sfile> inside a function yields {function-name}
234 return matchstr(expand('<sfile>'), '<SNR>\zs\d\+\ze_SID$')
236 " load functions on demand
237 execute "autocmd FuncUndefined"
238 \ "*".<SID>Screen_SID()."Screen_* source" escape(s:plug_path, " ")
240 " Purge Functions: that have done their one-time duty {{{1
241 delfunction <SID>Screen_CleanUp
242 delfunction <SID>Screen_FlexiMkdir
243 delfunction <SID>Screen_UpdateDocs
244 delfunction <SID>Screen_SID
246 let g:loaded_screenpaste = s:curr_version."_fast_load_done"
248 let &cpo = s:save_cpo
249 unlet s:save_cpo s:plug_path
253 if g:loaded_screenpaste != s:curr_version."_fast_load_done"
254 let &cpo = s:save_cpo
259 let g:loaded_screenpaste = s:curr_version
262 " ===== end of fast load =====================================================
263 " Script Vars: characters to be escaped on cmdline {{{1
265 " patterns and strings (for user info)
266 let s:esc_search_ma = '][/\^$*.~'
267 let s:esc_search_noma = ']/\^$'
268 let s:esc_sub_ma = '/\~&'
269 let s:esc_sub_noma = '/\'
270 let s:info_search_ma = "] [ / \\ ^ $ ~ * . (magic)"
271 let s:info_search_noma = "] / \\ ^ $ (nomagic)"
272 let s:info_sub_ma = "/ \\ ~ & (magic)"
273 let s:info_sub_noma = "/ \\ (nomagic)"
276 " these contain the current values for cmdline conversion, and,
277 " at startup, are set to the values corresponding to 'noesc'
278 " because for 'search' and 'sub' Screen_ClConfig is called with
279 " the current value of screen_clmode everytime Screen_CPut is called
280 " with the purpose to adapt to current setting of 'magic'
284 " Function: Screen_BufEscape escapes chars in Screen buffer for cmdline {{{1
285 function! s:Screen_BufEscape()
286 let l:screen_buf = <SID>Screen_Yank()
288 let l:screen_buf = escape(l:screen_buf, s:cl_esc)
290 return substitute(l:screen_buf, "\<C-J>", s:cl_eol, 'g')
293 " Function: Screen_ClConfig configures cmdline insertion {{{1
294 " variables configured here and used by Screen_CPut function:
296 " g:screen_clmode cmdline behaviour
298 " s:cl_eol eol-conversion
299 " s:cl_esc character group pattern to be escaped
300 " s:esc_info displays escaped characters
301 " s:eol_info displays eol-conversion
302 function! s:Screen_ClConfig(mod, msg)
303 if a:mod !~# '^\%(s\%(earch\|ub\)\|noesc\)$'
305 echon "`" a:mod "': invalid value for screen_clmode\n"
306 \ "use one of: search | sub | noesc"
310 let g:screen_clmode = a:mod
311 " call version dependent function to assign escapes
312 call <SID>Screen_ClEscape()
314 echon "set '" g:screen_clmode "' "
315 \ "for Screen buffer insertion in cmdline:\n"
316 \ "eol-conversion to literal " s:eol_info "\n"
317 \ "escaped characters " s:esc_info
321 " ============================================================================
322 " Vim7 Functions: subroutines, Screen_CPut (command detection) {{{1
323 " ============================================================================
324 " functions and helpers making use of Vim7 features
327 " Function: Screen_ReadBuf returns Screen buffer as text {{{2
328 function! s:Screen_ReadBuf(screen_tmpfile)
330 return join(readfile(a:screen_tmpfile, "b"), "\n")
331 catch /^Vim\%((\a\+)\)\=:E484/
332 " Screen buffer empty, no tmpfile created
337 " Function: Screen_ClEscape chars to be escaped in cmdline {{{2
338 " initialize dict vars
339 let s:cl_esc_dict = {
340 \ "search": {0: s:esc_search_noma, 1: s:esc_search_ma},
341 \ "sub": {0: s:esc_sub_noma, 1: s:esc_sub_ma },
342 \ "noesc": {0: '', 1: '' }
344 let s:cl_info_dict = {
345 \ "search": {0: s:info_search_noma, 1: s:info_search_ma},
346 \ "sub" : {0: s:info_sub_noma, 1: s:info_sub_ma },
347 \ "noesc" : {0: 'none', 1: 'none' }
349 let s:eol_conv_dict =
350 \ {"search": '\\n', "sub": '\\r', "noesc": '\\n'}
351 let s:eol_info_dict =
352 \ {"search": '\n', "sub": '\r', "noesc": '\n'}
354 function! s:Screen_ClEscape()
355 let s:cl_esc = s:cl_esc_dict[g:screen_clmode][&magic]
356 let s:esc_info = s:cl_info_dict[g:screen_clmode][&magic]
357 let s:cl_eol = s:eol_conv_dict[g:screen_clmode]
358 let s:eol_info = s:eol_info_dict[g:screen_clmode]
361 " Function: Screen_CPut writes converted Screen buffer to cmdline {{{2
362 " Screen call needed for :insert and :append commands in Screen_CPut
363 " using slowpaste avoids need for manual redraw
364 let s:screen_slowpaste =
365 \ g:screen_executable." -X slowpaste 10;".
366 \ g:screen_executable." -X paste .;".
367 \ g:screen_executable." -X slowpaste 0"
369 function! s:Screen_CPut()
370 " automatically adapt 'screen_clmode' to cmdtype if possible
371 " or instant paste in case of :insert or :append
372 let l:cmdtype = getcmdtype()
373 if l:cmdtype == '-' && exists("$STY")
374 " :insert, :append inside Screen session
375 call system(s:screen_slowpaste)
378 " store current cmdline behaviour
379 let l:save_clmode = g:screen_clmode
380 " detect cmdtype if not 'noesc'
381 if g:screen_clmode != "noesc"
382 if l:cmdtype =~ '[/?]'
383 " search: always call config to adapt to 'magic'
384 call <SID>Screen_ClConfig("search", 0)
385 elseif l:cmdtype =~ '[@-]'
386 " input() or :insert, :append outside Screen session
387 call <SID>Screen_ClConfig("noesc", 0)
389 " search, sub: always call config to adapt to 'magic'
390 call <SID>Screen_ClConfig(g:screen_clmode, 0)
393 let l:screen_buf = <SID>Screen_BufEscape()
394 " restore global 'screen_clmode' if changed
395 if l:save_clmode != g:screen_clmode
396 call <SID>Screen_ClConfig(l:save_clmode, 0)
402 " ============================================================================
403 " Vim6 Functions: subroutines, Screen_CPut (w/o command detection) {{{1
404 " (see Vim7 for more comments)
407 " Function: Screen_ReadBuf returns Screen buffer as text {{{2
408 function! s:Screen_ReadBuf(screen_tmpfile)
409 let l:store_quote = @"
410 let l:store_null = @0
411 let l:lz = &lazyredraw
412 silent execute "1 sview" a:screen_tmpfile
415 let &lazyredraw = l:lz
416 " remove closing newline to mimic reading in binary mode
417 " otherwise always a linewise register
418 let l:screen_buf = substitute(@0, '\n\%$', '', 'e')
419 let @" = l:store_quote
420 let @0 = l:store_null
424 " Function: Screen_ClEscape assigns chars to be escaped in cmdline {{{2
425 function! s:Screen_ClEscape()
426 if &magic && g:screen_clmode == "search"
427 let s:cl_esc = s:esc_search_ma
428 let s:esc_info = s:info_search_ma
429 elseif &magic && g:screen_clmode == "sub"
430 let s:cl_esc = s:esc_sub_ma
431 let s:esc_info = s:info_sub_ma
432 elseif g:screen_clmode == "search"
433 let s:cl_esc = s:esc_search_noma
434 let s:esc_info = s:info_search_noma
435 elseif g:screen_clmode == "sub"
436 let s:cl_esc = s:esc_sub_noma
437 let s:esc_info = s:info_sub_noma
440 let s:esc_info = "none"
442 if g:screen_clmode != "sub"
444 let s:eol_info = '\n'
447 let s:eol_info = '\r'
451 " Function: Screen_CPut writes converted Screen buffer to cmdline {{{2
452 " no detection of cmdtype
453 function! s:Screen_CPut()
454 if g:screen_clmode != "noesc"
455 " catch eventual change of &magic
456 call <SID>Screen_ClConfig(g:screen_clmode, 0)
458 return <SID>Screen_BufEscape()
464 " ============================================================================
465 " Function: Screen_Yank snatches current Screen buffer {{{1
466 function! s:Screen_Yank(...)
467 let l:screen_tmpfile = tempname()
468 call system(g:screen_executable." -X writebuf ".l:screen_tmpfile)
470 return <SID>Screen_ReadBuf(l:screen_tmpfile)
472 let l:screen_buf = <SID>Screen_ReadBuf(l:screen_tmpfile)
473 if strlen(l:screen_buf)
475 call setreg(a:1, l:screen_buf)
477 call setreg(g:screen_register, l:screen_buf)
480 elseif g:screen_register =~ '\u'
485 echo "Screen buffer is empty"
492 " Function: Screen_NPut pastes in normal mode {{{1
493 function! s:Screen_NPut(p)
494 if <SID>Screen_Yank(g:screen_register)
495 execute 'normal! "'.g:screen_register.a:p
499 " Function: Screen_IPut pastes in insert mode {{{1
500 " Function: Screen_TwRestore restores 'paste' {{{2
501 " helper function, only called right after Screen_IPut
502 " because Screen_IPut must return result before
503 " being able to restore paste its previous value
504 function! s:Screen_TwRestore()
505 let &paste = s:curr_paste
509 function! s:Screen_IPut()
510 let s:curr_paste = &paste
512 let l:screen_buf = <SID>Screen_Yank()
516 " Function: Screen_VPut pastes in visual mode {{{1
517 function! s:Screen_VPut(go)
518 if <SID>Screen_Yank(g:screen_register)
519 if g:screen_register =~ '["@]'
520 " we have to use another register because
521 " visual selection is deleted into unnamed register
524 let g:screen_register = "z"
526 execute 'normal! gv"'.g:screen_register.a:go.'p'
527 if g:screen_visualselect
528 execute "normal! `[".visualmode()."`]"
530 if exists("l:store_reg")
531 let g:screen_register = '"'
536 " reset visual after showing message for 3 secs
542 " Function: Screen_PutCommand is called from :ScreenPut {{{1
543 function! s:Screen_PutCommand(line, bang, reg)
545 let l:reg = g:screen_register
549 if <SID>Screen_Yank(l:reg)
551 execute a:line "put".a:bang l:reg
553 execute "put".a:bang l:reg
558 " Finale: restore 'compatible' settings {{{1
559 let &cpo = s:save_cpo
564 " ============================================================================
565 " Section: inline documentation (self-installing) {{{1
566 " to read the docs from this file with proper syntax coloring, type
570 *screenpaste.txt* Paste/insert GNU Screen buffer in (almost) any mode #version#
572 Author: Christian Ebert <blacktrash@gmx.net>
575 SCREENPASTE REFERENCE MANUAL~
577 *screenpaste* *screenpaste.vim*
579 ==============================================================================
581 1. Contents *screenpaste-toc*
583 Screen Paste Plugin |screenpaste-intro|
584 Activation |screenpaste-activate|
585 Usage |screenpaste-usage|
586 Options |screenpaste-options|
587 Changing Mappings |screenpaste-mappings|
588 Commands |screenpaste-commands|
589 Bugs and Limitations |screenpaste-bugs|
590 Credits |screenpaste-credits|
592 ==============================================================================
594 2. Screen Paste Plugin *screenpaste-intro*
596 The terminal window manager Screen http://www.gnu.org/software/screen
597 offers the capability to copy and paste between windows.
599 In principle you can just do "C-a ]" (default) to paste the current Screen
600 buffer into a vim buffer. However this gives unexpected results when 'paste'
601 is not set or in Vim's command-line.
603 This script provides mappings and commands to get correct results.
605 As an additional feature the current Screen buffer is available in any Vim
606 instance, even those /outside/ the current Screen session.
608 When pasting into command-line in Vim7 many commands are autodetected and the
609 behaviour adapts automatically (|getcmdtype()|).
611 The underlying mechanism of screenpaste consists in getting hold of the
612 current Screen buffer via calling to Screen to write it to a temporary file.
613 At this point Vim takes over, reads the contents of the file, and puts them to
614 use either directly (in Insert, Replace or Command-line mode) or, in Normal
615 and Visual mode, by writing to a register and, most often, putting the
616 contents of the register into the Vim buffer. Which is why the default
617 keybindings mimic |p|, |P|, |gp|, |gP|, with the |mapleader| prepended, as
618 well as |:ScreenPut| and |:ScreenYank| behave almost like |:put| and |:yank|
621 ==============================================================================
623 3. Activation *screenpaste-activate*
625 Either copy screenpaste.vim to your plugin directory (|add-global-plugin|),
626 or to your macros directory and source it (manually or from |vimrc|): >
627 :runtime macros/screenpaste.vim
629 :source $HOME/.vim/macros/screenpaste.vim
631 The Vim Help documentation installs itself when you restart Vim.
633 The GNU Screen executable has to be in $PATH. Otherwise screenpaste bails out
634 giving an error message.
636 ==============================================================================
638 4. Usage *screenpaste-usage*
640 Think of the current Screen buffer as of a register at your disposal via the
641 |screenpaste| mappings and commands.
644 When you type the plugin's Ex command
648 this works like executing |:put| with the current Screen buffer as register.
649 It puts the text after the current line. Like |:put| it accepts a prepended
650 number as parameter designating the target line as well as an appended bang
651 to put the text before the indicated line and an optional register argument
652 which defaults to |screen_register| when omitted.
654 |:ScreenPut| differs from |:put| as the register is not only written into the
655 buffer but filled with the current Screen buffer beforehand.
658 If you want to just get hold of the current Screen buffer for further
663 and the Screen buffer is at your disposal in the |screen_register|. Similar
664 to |:yank| you can also execute the command with an explicit register
667 Note: Screen's copy mechanism discards spaces at the end and the beginning of
668 a selection in case there are printable characters in the same line. In Vim
669 terms one could consider this like selecting 'exclusive', and to get a
670 |linewise| "yank" the selection has to span visually more than one line, the
671 newline at the end of a visually selected single line is not included.
674 All other commands configure the treatment of the current Screen buffer when
675 it is pasted into the command-line. Please refer to |screen_clmode| and
676 |screenpaste-commands| for further information.
681 In |Insert|, |Replace|, and |Command-line| modes (by default) simply type: >
683 to paste the current Screen buffer. In these modes the |screen_register| is
686 Note: mappings are ignored in Insert mode while |'paste'| is set. But in that
687 case Screen's "paste" command (bound to "C-a]" by default) works just fine and
688 there's no need to work around this via |'pastetoggle'|.
691 The plugin's mappings for |Normal| and |Visual| mode emulate the non-Ex
692 commands |p|, |P|, |gp|, and |gP|: They put the text of the current Screen
693 buffer after or before the cursor, or replace the visual selection with it,
694 just as if the unnamed register would contain the current Screen buffer (see
697 If the Screen buffer is empty they do nothing, the registers stay untouched,
698 and only a corresponding message is displayed in the menu.
700 Note however that the optional initial [count] argument to the original non-Ex
701 commands will not work with these mappings (|screenpaste-bugs|).
703 In their default state the |Normal| and |Visual| mode mappings consist of the
704 same letters as the corresponding non-Ex commands with the |mapleader|
708 <Leader>P (not in Visual)
710 <Leader>gP (not in Visual)
712 For simplicity we use the default |screenpaste-mappings| and the default
713 |<Leader>| "\" in the following description.
716 \p Put current Screen buffer after the cursor.
719 \P Put current Screen buffer before the cursor.
720 Not available in Visual mode.
723 \gp Like "\p" but leave the cursor after the pasted text.
726 \gP Like "\P" but leave the cursor after the pasted text.
727 Not available in Visual mode.
729 In |Visual| mode we do not need "\P" and "\gP" as "\p" and "\P" have the same
730 effect of replacing the Visual selected text with the current Screen buffer.
733 To summarize, supposing the default |<Leader>| "\" and the default
734 |screenpaste-mappings| you can type:
736 \p in Normal mode to put Screen buffer after cursor
737 \gp in Normal mode to put Screen buffer after cursor and leave cursor
738 after the end of new text
739 \P in Normal mode to put Screen buffer before cursor
740 \gP in Normal mode to put Screen buffer before cursor and leave cursor
741 after the end of new text
742 \p in Visual mode to replace visual selection with Screen buffer
743 \gp in Visual mode to put Screen buffer after cursor and leave cursor
744 after the end of new text
745 \p in Insert and Replace mode to paste Screen buffer
746 \p in Command-line-mode to put Screen buffer in command line
748 ==============================================================================
750 5. Options *screenpaste-options*
752 g:loaded_screenpaste *loaded_screenpaste*
754 This option normally is set by screenpaste to avoid loading the script
755 more than once. But you can use it to get the current script version: >
756 :echo loaded_screenpaste
758 If you want to disable screenpaste, put the following line in your
760 let g:loaded_screenpaste = 1
762 g:screen_executable *screen_executable*
765 Default Value 'screen'
767 Set this option if the name of your GNU Screen executable differs from
768 "screen", or if you like to specify it's full path: >
769 let g:screen_executable = "/usr/local/bin/screen"
771 g:screen_visualselect *screen_visualselect*
775 If set to 1 and in Visual mode the text from the Screen buffer is
776 visually selected after the put operation.
778 g:screen_register *screen_register*
781 Valid Values "a-z0-9A-Z
784 The non-Ex put "commands" (mappings) act in a twofold operation when
785 executed in Normal or Visual mode: they yank the Screen buffer into a
786 register in the background, and then put the register into the buffer
787 or command-line. This variable controls the register that is used for
788 the first part of the operation. It defaults to the unnamed register
791 Normally you should be fine with the default setting. But if you
792 prefer to reserve a register of your choice for the Screen buffer you
793 can do so with this option. Besides the default "", you may choose
794 any named (|quote_alpha|) or numbered (|quote_number|) register.
795 Consult |registers| about their behaviour.
797 For a one time operation with a special register the use of
798 |ScreenPut| ex-command and its register argument is recommended.
800 Note: Due to the mechanics of the script even a numbered register has
801 to be passed as string, ie. it has to quoted when you set it; eg. >
802 :let g:screen_register = "8"
803 < Note as well that specifying an uppercase letter means that the
804 contents of the Screen buffer will be appended to the register named
805 with the corresponding lowercase character (|quote_alpha|).
807 g:screen_clmode *screen_clmode*
810 Valid Values 'search', 'sub', 'noesc'
811 Default Value 'search'
813 This setting controls how the Screen buffer is treated when pasted in
816 You can change the setting at startup in your |vimrc|: >
817 let g:screen_clmode = "sub"
819 To change its value in a vim session you might want to use one of the
820 |:ScreenCmdlineConf|, |:ScreenSearch|, |:ScreenSub|, |:ScreenNoEsc|
821 commands as they also give a short informative message on how the mode
822 of your choice will act, and prevent you from setting an invalid value.
824 Information on the current value and the resulting behaviour is also
825 available via the |:ScreenCmdlineInfo| command.
827 Modes and their behaviour:
830 Converts end-of-line to literal '\n'.
831 Escapes characters according to the current setting of 'magic':
832 magic: [ ] / \ ^ * . ~ $
835 Use this mode to search for occurrences of current Screen buffer.
836 Example as typed using default mapleader: >
839 < If the current Screen buffer is `[hello world.]' and 'magic' is set,
841 :%s/\[hello world\.\]/repl/g
844 Converts end-of-line to literal '\r'.
845 Escapes characters according to the current setting of 'magic':
849 Use this mode to substitute a pattern with current Screen buffer.
850 Example as typed using default mapleader: >
853 < If the current Screen buffer is `http://www.vim.org', the above
855 :%s/pattern/http:\/\/www.vim.org/g
856 < *screenpaste-noesc*
858 Converts end-of-line to literal '\n'.
860 Use this mode to paste current Screen buffer literally into command
864 |/|, |?|, |input()|, |:insert|, and |:append| commands are
865 autodetected when not in 'noesc' |screen_clmode|. This means that even
866 when you are in 'sub' mode you can type: >
868 < and this becomes (using above example for 'search'): >
871 Note: If you paste a Screen buffer containing newlines while in an
872 |:insert| or |:append| but outside a running Screen session the
873 newlines are escaped because we cannot call Screen's paste mechanism
874 without clobbering a parallel Screen session, and Vim would insert
875 <Nul> characters instead (see |NL-used-for-Nul|).
878 For |:insert| and |:append| commands use Screen's "C-a ]"
880 ==============================================================================
882 6. Changing Mappings *screenpaste-mappings*
885 *ScreenpastePutBefore*
886 *ScreenpasteGPutBefore*
888 The right-hand-side |{rhs}| mappings provided by this plugin and the modes in
889 which to apply them are: >
891 <Plug>ScreenpastePut Normal, Visual, Insert, Command-line
892 <Plug>ScreenpasteGPut Normal, Visual
893 <Plug>ScreenpastePutBefore Normal
894 <Plug>ScreenpasteGPutBefore Normal
896 Use these to customize the default mappings <Leader>p, <Leader>gp, <Leader>P,
897 and <Leader>gP to your taste (see |using-<Plug>| and |:map-modes|).
899 The default mappings would look like this in a |vimrc|:
901 map <Leader>p <Plug>ScreenpastePut " Normal, Visual mode
902 map! <Leader>p <Plug>ScreenpastePut " Insert, Command-line mode
903 map <Leader>gp <Plug>ScreenpasteGPut " Normal, Visual mode
904 nmap <Leader>P <Plug>ScreenpastePutBefore " Normal mode
905 nmap <Leader>gP <Plug>ScreenpasteGPutBefore " Normal mode
907 You can tweak them by changing their left-hand-side |{lhs}|.
909 Normal (put after cursor) and Visual mode:
911 :map {lhs} <Plug>ScreenpastePut \p
912 :map {lhs} <Plug>ScreenpasteGPut \gp
915 map <Leader>P <Plug>ScreenpastePut
917 Normal mode (put before cursor):
919 :nmap {lhs} <Plug>ScreenpastePutBefore \P
920 :nmap {lhs} <Plug>ScreenpasteGPutBefore \gP
923 nmap <Leader>I <Plug>ScreenpastePutBefore
925 Insert and Command-line mode:
927 :map! {lhs} <Plug>ScreenpastePut \p
929 Vimrc example, to avoid character mappings when inserting: >
930 map! <F7> <Plug>ScreenpastePut
932 ==============================================================================
934 7. Commands *screenpaste-commands*
937 :ScreenYank [x] Yank current Screen buffer into register [x] (default
941 :[line]ScreenPut [x] Put the text from current Screen buffer after [line]
942 (default current line) using register [x] (default
945 You can use this command for instance to append the contents of the
946 Screen buffer to a named register and then paste in one go: >
948 < puts the contents of register "a and the Screen buffer after line 3.
950 :[line]ScreenPut! [x] Put the text from current Screen buffer before [line]
951 (default current line) using register [x] (default
955 :ScreenCmdlineConf {mode}
956 Tell screenpaste to convert the current Screen
957 buffer in command-line-mode according to {mode}.
958 Takes one argument of: "search", "sub", "noesc" (w/o
960 Changes |screen_clmode| accordingly.
962 :ScreenCmdlineConf noesc
965 :ScreenComdlineInfo Display information on current command-line-mode
966 behaviour, ie. current |screen_clmode| and what it
970 :ScreenSearch Set |screen_clmode| to 'search'.
972 :ScreenCmdlineConf search
975 :ScreenSub Set |screen_clmode| to 'sub'.
977 :ScreenCmdlineConf sub
980 :ScreenNoEsc Set |screen_clmode| to 'noesc'.
982 :ScreenCmdlineConf noesc
984 ==============================================================================
986 8. Bugs and Limitations *screenpaste-bugs*
988 Found no way (yet?) to make optional initial [count] argument work with
989 (Normal mode) mappings.
991 Screen's copy mechanism treats spaces (including newlines) at the beginning or
992 the end of a selection in a different manner than Vim's visual yank does.
994 Screen expands tabs, expect incorrect results if the Screen buffer contains
997 ==============================================================================
999 Credits *screenpaste-credits*
1001 Mathieu Clabaut, Guo-Peng Wen let me steal and tweak the inline
1002 self-install code for this Help document.
1004 ==============================================================================
1007 " EOF vim600: set foldmethod=marker: