vim/bundle/screenpaste/doc/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: