]> ruderich.org/simon Gitweb - config/dotfiles.git/blob - screenpaste.txt
49cfeb61471cad5dd7f32c747c0504ff92d7bbe5
[config/dotfiles.git] / screenpaste.txt
1 *screenpaste.txt* Paste/insert GNU Screen buffer in (almost) any mode  v5.92
2
3 $Id: screenpaste.txt,v 8624db9970aa 2008-11-08 21:33 +0100 blacktrash $
4
5 For instructions on installing this file, type
6         :help add-local-help
7 inside Vim.
8
9 Author: Christian Ebert <blacktrash@gmx.net>
10
11
12                 SCREENPASTE REFERENCE MANUAL~
13
14 *screenpaste* *screenpaste.vim*
15
16 ==============================================================================
17
18 1. Contents                                             *screenpaste-toc*
19
20         Screen Paste Plugin                             |screenpaste-intro|
21         Installation                                    |screenpaste-install|
22         Usage                                           |screenpaste-usage|
23         Options                                         |screenpaste-options|
24         Changing Mappings                               |screenpaste-mappings|
25         Commands                                        |screenpaste-commands|
26         Bugs and Limitations                            |screenpaste-bugs|
27
28 ==============================================================================
29
30 2. Screen Paste Plugin                                  *screenpaste-intro*
31
32 The terminal window manager Screen http://www.gnu.org/software/screen
33 offers the capability to copy and paste between windows.
34
35 In principle you can just do "C-a ]" (default) to paste the current Screen
36 buffer into a vim buffer. However this gives unexpected results when 'paste'
37 is not set or in Vim's command-line.
38
39 This script provides mappings and commands to get correct results.
40
41 As an additional feature the current Screen buffer is available in any Vim
42 instance, even those /outside/ the current Screen session.
43
44 When pasting into command-line many commands are autodetected and the
45 behaviour adapts automatically (|getcmdtype()|).
46
47 The underlying mechanism of screenpaste consists in getting hold of the
48 current Screen buffer via calling to Screen to write it to a temporary file.
49 At this point Vim takes over, reads the contents of the file, and puts them to
50 use either directly (in Insert, Replace or Command-line mode) or, in Normal
51 and Visual mode, by writing to a register and, most often, putting the
52 contents of the register into the Vim buffer.  Which is why the default
53 keybindings mimic |p|, |P|, |gp|, |gP|, with the |mapleader| prepended, as
54 well as |:ScreenPut| and |:ScreenYank| behave almost like |:put| and |:yank|
55 respectively.
56
57 ==============================================================================
58
59 3. Installation                                         *screenpaste-install*
60
61 The screenpaste plugin comprises three files: screenpastePlugin.vim,
62 screenpaste.vim and screenpaste.txt (this file). To install the plugin, copy
63 screenpastePlugin.vim into a 'plugin' directory in your runtime path and
64 screenpaste.vim into the corresponding 'autoload' directory. See
65 |add-global-plugin| and |'runtimepath'|.
66
67 This help file goes into a 'doc' directory in the runtime path. Then execute
68 |:helptags|, specifying the full path of the 'doc' directory. See
69 |add-local-help| for details.
70
71 The GNU Screen executable has to be in $PATH. Otherwise screenpaste bails out
72 giving an error message.
73
74 ==============================================================================
75
76 4. Usage                                                *screenpaste-usage*
77
78 Think of the current Screen buffer as of a register at your disposal via the
79 |screenpaste| mappings and commands.
80
81                                                         *screenpaste-put*
82 When you type the plugin's Ex command
83 >
84         :ScreenPut
85
86 this works like executing |:put| with the current Screen buffer as register.
87 It puts the text after the current line.  Like |:put| it accepts a prepended
88 number as parameter designating the target line as well as an appended bang
89 to put the text before the indicated line and an optional register argument
90 which defaults to |screen_register| when omitted.
91
92 |:ScreenPut| differs from |:put| as the register is not only written into the
93 buffer but filled with the current Screen buffer beforehand.
94
95                                                         *screenpaste-yank*
96 If you want to just get hold of the current Screen buffer for further
97 processing, type
98 >
99         :ScreenYank
100 >
101 and the Screen buffer is at your disposal in the |screen_register|.  Similar
102 to |:yank| you can also execute the command with an explicit register
103 argument.
104
105 Note: Screen's copy mechanism discards spaces at the end and the beginning of
106 a selection in case there are printable characters in the same line.  In Vim
107 terms one could consider this like selecting 'exclusive', and to get a
108 |linewise| "yank" the selection has to span visually more than one line, the
109 newline at the end of a visually selected single line is not included.
110
111
112 All other commands configure the treatment of the current Screen buffer when
113 it is pasted into the command-line.  Please refer to |screen_clmode| and
114 |screenpaste-commands| for further information.
115
116
117 Mappings:~
118
119 In |Insert|, |Replace|, and |Command-line| modes (by default) simply type: >
120         \p
121 to paste the current Screen buffer.  In these modes the |screen_register| is
122 not changed.
123
124 Note: mappings are ignored in Insert mode while |'paste'| is set. But in that
125 case Screen's "paste" command (bound to "C-a]" by default) works just fine and
126 there's no need to work around this via |'pastetoggle'|.
127
128
129 The plugin's mappings for |Normal| and |Visual| mode emulate the non-Ex
130 commands |p|, |P|, |gp|, and |gP|:  They put the text of the current Screen
131 buffer after or before the cursor, or replace the visual selection with it,
132 just as if the unnamed register would contain the current Screen buffer (see
133 |screen_register|).
134
135 If the Screen buffer is empty they do nothing, the registers stay untouched,
136 and only a corresponding message is displayed in the menu.
137
138 Note however that the optional initial [count] argument to the original non-Ex
139 commands will not work with these mappings (|screenpaste-bugs|).
140
141 In their default state the |Normal| and |Visual| mode mappings consist of the
142 same letters as the corresponding non-Ex commands with the |mapleader|
143 prepended: >
144
145         <Leader>p
146         <Leader>P       (not in Visual)
147         <Leader>gp
148         <Leader>gP      (not in Visual)
149
150 For simplicity we use the default |screenpaste-mappings| and the default
151 |<Leader>| "\" in the following description.
152
153                                                         *screenpaste-p*
154 \p                      Put current Screen buffer after the cursor.
155
156                                                         *screenpaste-P*
157 \P                      Put current Screen buffer before the cursor.
158                         Not available in Visual mode.
159
160                                                         *screenpaste-gp*
161 \gp                     Like "\p" but leave the cursor after the pasted text.
162
163                                                         *screenpaste-gP*
164 \gP                     Like "\P" but leave the cursor after the pasted text.
165                         Not available in Visual mode.
166
167 In |Visual| mode we do not need "\P" and "\gP" as "\p" and "\P" have the same
168 effect of replacing the Visual selected text with the current Screen buffer.
169
170
171 To summarize, supposing the default |<Leader>| "\" and the default
172 |screenpaste-mappings| you can type:
173 >
174         \p  in Normal mode to put Screen buffer after cursor
175         \gp in Normal mode to put Screen buffer after cursor and leave cursor
176                 after the end of new text
177         \P  in Normal mode to put Screen buffer before cursor
178         \gP in Normal mode to put Screen buffer before cursor and leave cursor
179                 after the end of new text
180         \p  in Visual mode to replace visual selection with Screen buffer
181         \gp in Visual mode to put Screen buffer after cursor and leave cursor
182                 after the end of new text
183         \p  in Insert and Replace mode to paste Screen buffer
184         \p  in Command-line-mode to put Screen buffer in command line
185
186 ==============================================================================
187
188 5. Options                                              *screenpaste-options*
189
190 g:loaded_screenpaste                                    *loaded_screenpaste*
191
192         This option normally is set by screenpaste to avoid loading the script
193         more than once. But you can use it to get the current script version: >
194                 :echo loaded_screenpaste
195 <
196         If you want to disable screenpaste, put the following line in your
197         |vimrc|: >
198                 let g:loaded_screenpaste = 1
199
200 g:screen_executable                                     *screen_executable*
201
202 Type            String
203 Default Value   'screen'
204
205         Set this option if the name of your GNU Screen executable differs from
206         "screen", or if you like to specify it's full path: >
207                 let g:screen_executable = "/usr/local/bin/screen"
208
209 g:screen_wait                                           *screen_wait*
210
211 Type            String or Number
212 Valid Values    See |:sleep|
213 Default Value   '333m'
214
215         How long Vim should wait for Screen to write its exchange file.  If
216         you get messages that the Screen buffer is empty even though you know
217         that it actually is not, bump up this setting.
218
219 g:screen_visualselect                                   *screen_visualselect*
220 Type            Boolean
221 Default Value   0
222
223         If set to 1 and in Visual mode the text from the Screen buffer is
224         visually selected after the put operation.
225
226 g:screen_register                                       *screen_register*
227
228 Type            String or Number
229 Valid Values    "a-z0-9A-Z
230 Default Value   '"'
231
232         The non-Ex put "commands" (mappings) act in a twofold operation when
233         executed in Normal or Visual mode: they yank the Screen buffer into a
234         register in the background, and then put the register into the buffer
235         or command-line.  This variable controls the register that is used for
236         the first part of the operation.  It defaults to the unnamed register
237         "" (|quotequote|).
238
239         Normally you should be fine with the default setting.  But if you
240         prefer to reserve a register of your choice for the Screen buffer you
241         can do so with this option.  Besides the default "", you may choose
242         any named (|quote_alpha|) or numbered (|quote_number|) register.
243         Consult |registers| about their behaviour.
244
245         For a one time operation with a special register the use of
246         |ScreenPut| ex-command and its register argument is recommended.
247
248         Note: Specifying an uppercase letter means that the contents of the
249         Screen buffer will be appended to the register named with the
250         corresponding lowercase character (|quote_alpha|).
251
252 g:screen_clmode                                         *screen_clmode*
253
254 Type            String
255 Valid Values    'search', 'sub', 'noesc'
256 Default Value   'search'
257
258         This setting controls how the Screen buffer is treated when pasted in
259         the command line.
260
261         You can change the setting at startup in your |vimrc|: >
262                 let g:screen_clmode = "sub"
263 <
264         To change its value in a vim session you might want to use one of the
265         |:ScreenCmdlineConf|, |:ScreenSearch|, |:ScreenSub|, |:ScreenNoEsc|
266         commands as they also give a short informative message on how the mode
267         of your choice will act, and prevent you from setting an invalid value.
268
269         Information on the current value and the resulting behaviour is also
270         available via the |:ScreenCmdlineInfo| command.
271
272 Modes and their behaviour:
273                                                         *screenpaste-search*
274 'search' ~
275         Converts end-of-line to literal '\n'.
276         Escapes characters according to the current setting of 'magic':
277         magic:    [ ] / \ ^ * . ~ $
278         nomagic:    ] / \ ^       $
279
280         Use this mode to search for occurrences of current Screen buffer.
281         Example as typed using default mapleader: >
282                 :ScreenSearch
283                 :%s/\p/repl/g
284 <       If the current Screen buffer is `[hello world.]' and 'magic' is set,
285         the above becomes: >
286                 :%s/\[hello world\.\]/repl/g
287 <                                                       *screenpaste-sub*
288 'sub' ~
289         Converts end-of-line to literal '\r'.
290         Escapes characters according to the current setting of 'magic':
291         magic:    /  \  ~  &
292         nomagic:  /  \
293
294         Use this mode to substitute a pattern with current Screen buffer.
295         Example as typed using default mapleader: >
296                 :ScreenSub
297                 :%s/pattern/\p/g
298 <       If the current Screen buffer is `http://www.vim.org', the above
299         becomes: >
300                 :%s/pattern/http:\/\/www.vim.org/g
301 <                                                       *screenpaste-noesc*
302 'noesc' ~
303         Converts end-of-line to literal '\n'.
304
305         Use this mode to paste current Screen buffer literally into command
306         line.
307
308         |/|, |?|, |input()|, |:insert|, and |:append| commands are
309         autodetected when not in 'noesc' |screen_clmode|. This means that even
310         when you are in 'sub' mode you can type: >
311                 /\p
312 <       and this becomes (using above example for 'search'): >
313                 /\[hello world\.\]
314 <
315         Note: If you paste a Screen buffer containing newlines while in an
316         |:insert| or |:append| but outside a running Screen session the
317         newlines are escaped because we cannot call Screen's paste mechanism
318         without clobbering a parallel Screen session, and Vim would insert
319         <Nul> characters instead (see |NL-used-for-Nul|).
320
321 ==============================================================================
322
323 6. Changing Mappings                                    *screenpaste-mappings*
324                                                         *ScreenpastePut*
325                                                         *ScreenpasteGPut*
326                                                         *ScreenpastePutBefore*
327                                                         *ScreenpasteGPutBefore*
328
329 The right-hand-side |{rhs}| mappings provided by this plugin and the modes in
330 which to apply them are: >
331
332         <Plug>ScreenpastePut            Normal, Visual, Insert, Command-line
333         <Plug>ScreenpasteGPut           Normal, Visual
334         <Plug>ScreenpastePutBefore      Normal
335         <Plug>ScreenpasteGPutBefore     Normal
336 <
337 Use these to customize the default mappings <Leader>p, <Leader>gp, <Leader>P,
338 and <Leader>gP to your taste (see |using-<Plug>| and |:map-modes|).
339
340 The default mappings would look like this in a |vimrc|:
341
342 map  <Leader>p  <Plug>ScreenpastePut            " Normal, Visual mode
343 map! <Leader>p  <Plug>ScreenpastePut            " Insert, Command-line mode
344 map  <Leader>gp <Plug>ScreenpasteGPut           " Normal, Visual mode
345 nmap <Leader>P  <Plug>ScreenpastePutBefore      " Normal mode
346 nmap <Leader>gP <Plug>ScreenpasteGPutBefore     " Normal mode
347
348 You can tweak them by changing their left-hand-side |{lhs}|.
349
350 Normal (put after cursor) and Visual mode:
351                                                         default
352 :map    {lhs}   <Plug>ScreenpastePut                      \p
353 :map    {lhs}   <Plug>ScreenpasteGPut                     \gp
354
355         Vimrc example: >
356                 map  <Leader>P <Plug>ScreenpastePut
357
358 Normal mode (put before cursor):
359
360 :nmap   {lhs}   <Plug>ScreenpastePutBefore                \P
361 :nmap   {lhs}   <Plug>ScreenpasteGPutBefore               \gP
362
363         Vimrc example: >
364                 nmap <Leader>I <Plug>ScreenpastePutBefore
365
366 Insert and Command-line mode:
367
368 :map!   {lhs}   <Plug>ScreenpastePut                      \p
369
370         Vimrc example, to avoid character mappings when inserting: >
371                 map! <F7> <Plug>ScreenpastePut
372
373 ==============================================================================
374
375 7. Commands                                             *screenpaste-commands*
376
377                                                         *:ScreenYank*
378 :ScreenYank [x]         Yank current Screen buffer into register [x] (default
379                         |screen_register|).
380
381                                                         *:ScreenPut*
382 :[line]ScreenPut [x]    Put the text from current Screen buffer after [line]
383                         (default current line) using register [x] (default
384                         |screen_register|).
385
386         You can use this command for instance to append the contents of the
387         Screen buffer to a named register and then paste in one go: >
388                 :3 ScreenPut A
389 <       puts the contents of register "a and the Screen buffer after line 3.
390
391 :[line]ScreenPut! [x]   Put the text from current Screen buffer before [line]
392                         (default current line) using register [x] (default
393                         |screen_register|).
394
395                                                         *:ScreenCmdlineConf*
396 :ScreenCmdlineConf {mode}
397                         Tell screenpaste to convert the current Screen
398                         buffer in command-line-mode according to {mode}.
399                         Takes one argument of: "search", "sub", "noesc" (w/o
400                         quotes).
401                         Changes |screen_clmode| accordingly.
402         Example: >
403                 :ScreenCmdlineConf noesc
404 <
405                                                         *:ScreenCmdlineInfo*
406 :ScreenComdlineInfo     Display information on current command-line-mode
407                         behaviour, ie. current |screen_clmode| and what it
408                         does.
409
410                                                         *:ScreenSearch*
411 :ScreenSearch           Set |screen_clmode| to 'search'.
412         Equivalent to: >
413                 :ScreenCmdlineConf search
414 <
415                                                         *:ScreenSub*
416 :ScreenSub              Set |screen_clmode| to 'sub'.
417         Equivalent to: >
418                 :ScreenCmdlineConf sub
419 <
420                                                         *:ScreenNoEsc*
421 :ScreenNoEsc            Set |screen_clmode| to 'noesc'.
422         Equivalent to: >
423                 :ScreenCmdlineConf noesc
424
425 ==============================================================================
426
427 8. Bugs and Limitations                                 *screenpaste-bugs*
428
429 Found no way (yet?) to make optional initial [count] argument work with
430 (Normal mode) mappings.
431
432 Screen's copy mechanism treats spaces (including newlines) at the beginning or
433 the end of a selection in a different manner than Vim's visual yank does.
434
435 Screen expands tabs, expect incorrect results if the Screen buffer contains
436 tabs.
437
438 ==============================================================================
439
440  vim:tw=78:ts=8:ft=help:norl: