vim/bundle/screenpaste/doc/screenpaste.txt

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