smartpairs.txt

*smartpairs.txt*  Sensible pairings

Author:  Federico Ramirez <https://github.com/gosukiwi/>
License: Same terms as Vim itself (see |license|)

Help on using smartpairs                                             *smartpairs*

    1. INTRODUCTION ................................. |smartpairs-intro|
    2. INSERTING .................................... |smartpairs-inserting|
    3. JUMPING ...................................... |smartpairs-jumping|
    4. BACKSPACE .................................... |smartpairs-backspace|
    5. NEWLINE ...................................... |smartpairs-newline|
    6. FILETYPE PAIRINGS ...........................  |smartpairs-filetypes|

================================================================================
 1. INTRODUCTION                                               *smartpairs-intro*

This plugin is all about inserting proper pairings as you type. By default,
it will complete (), [], {}, '' and "".

Below is an example of smartpairs usage:

  You type    You get    Notes ~
  (           (_)        "_" represents the cursor
  <BS>        _
  [           [_]
  ]           []_
  <BS>        [_
  <BS>        _
  {           {_}
  <CR>        {         Cursor will be indented using current syntax
                _
              }

================================================================================
 2. INSERTING                                              *smartpairs-inserting*

When inserting pairs, smartpairs tries to be as predictable as possible. For
situations where you know you don't want to automatically expand a particular
character, you can use |<C-V>| before the character you want to use.

For example, if you want to input "(", you type "<C-V>(".

Smartpairs will not add a matching pair if the character before is an escape
character, in particular "\".

                                   *smartpairs-symmetric* *smartpairs-asymmetric*
Symmetric pairs (pairs where the opening and closing characters are equal,
such as "", '', etc) behave differently than asymmetric pairs ((), [], etc).

When typing, asymmetric pairs will always expand when the opening pair is
typed. Symmetric pairs will NOT expand when the previous character is itself.

  You type    You get    Notes ~
  '           '_'
  '           ''_
  '           '''_       Didn't expand here

Smartpairs will not break the undo sequence, so you can undo as usual.

================================================================================
 3. JUMPING                                                  *smartpairs-jumping*
When you type an opening pair and, instead of expanding it, the cursor moves,
this is called a jump. It allows you to easily move out of a pairing while
typing:

  You type        You get ~
  [               [_]
  ]               []_
  <Left><Left>    _[]
  [               [_]

                                                     *g:smartpairs_jumps_enabled*
default: 1 ~

If you don't want this behavior, or it conflicts with some other plugin, set
|g:smartpairs_jumps_enabled| to 0: >

    let g:smartpairs_jumps_enabled = 0
<

================================================================================
 4. BACKSPACE                                              *smartpairs-backspace*

By pressing backspace inside an empty pair, smartpair will try to delete it.
This operation behaves differently when the pairs are symmetric vs asymmetric.

For asymmetric pairs it will simply delete the pair.

  You type    You get ~
  (           (_)
  <BS>        _

For symmetric pairs, it will only delete if they are surrounded by empty
space, or if the previous character is not itself.

  You type    You get ~
  '           '_'
  '           ''_
  '           '''_
  <Left>      ''_'
  <BS>        '_'
  <BS>        _

                                                  *g:smartpairs_hijack_backspace*
default: 1 ~

If you don't want this behavior, or it conflicts with some other plugin, set
|g:smartpairs_hijack_backspace| to 0: >

    let g:smartpairs_hijack_backspace = 0
<

================================================================================
 5. NEWLINE                                                  *smartpairs-newline*

By pressing <CR> inside an empty pair, smartpairs will indent it using the
current syntax:

  You type       You get ~
  function(      function(_)
  ) {            function() {_}
  <CR>           function() {
                   _
                 }

                                                      *g:smartpairs_hijack_return*
default: 1 ~

If you don't want this behavior, or it conflicts with some other plugin, set
|g:smartpairs_hijack_return| to 0: >

    let g:smartpairs_hijack_return = 0
<

================================================================================
 6. FILETYPE PAIRINGS                                      *smartpairs-filetypes*

You can customize the pairings based on filetype by setting
|g:smartpairs_pairs|.

                                                             *g:smartpairs_pairs*
default:~
>
    let g:smartpairs_pairs['vim'] = { '(': ')', '[': ']', '{': '}', "'": "'" }
    let g:smartpairs_pairs['javascript'] = { '(': ')', '[': ']', '{': '}', '"': '"', "'": "'", '`': '`' }
<

If you need to know the filetype for your current buffer to define pairings,
you can do `:echo &filetype` to get it.

                                                     *g:smartpairs_default_pairs*

If no filetype pairs are found, the default will be used:

default: ~
>
    let g:smartpairs_default_pairs = {
          \ '(': ')',
          \ '[': ']',
          \ '{': '}',
          \ '"': '"',
          \ "'": "'",
          \ }
<

vim:tw=78:ts=8:ft=help:norl: