git.r.bdr.sh - rbdr/dotfiles/blob - atom/packages/vim-surround/README.md

   1 # Vim Surround for Atom [![Build Status](https://travis-ci.org/gepoch/vim-surround.svg?branch=master)](https://travis-ci.org/gepoch/vim-surround)
   2
   3 Surround is an implementation of vim-surround for the [atom](http://atom.io)
   4 editor, creating a vim-surround with the power of Atom!
   5
   6 You should definitely have [vim-mode](https://atom.io/packages/vim-mode) for
   7 this package to function properly, of course.
   8
   9 Inspiration from and kudos to the wonderful [vim-surround for
  10 vim](https://github.com/tpope/vim-surround)
  11
  12 See vim-surround on [github](https://github.com/gepoch/vim-surround) or
  13 [atom.io](https://atom.io/packages/vim-surround).
  14
  15 ## News
  16
  17 * This package supports visual mode's `s )` set of commands for a configurable
  18   set of pairs.
  19
  20 * Next on the roadmap are pair deletions with `d )` and friends.
  21
  22 * New in 0.4: Multiple cursors are now supported, and conveniently work just
  23   like you think they do.
  24
  25 * New in 0.5: Stable configuration changes and configurable surround key!
  26
  27 * New in 0.7: Change surround and delete surround added.
  28
  29 * New in 0.8: Tentative support for
  30   [vim-mode-next](https://atom.io/packages/vim-mode-next). See
  31   [#28](https://github.com/gepoch/vim-surround/issues/28).
  32
  33 ### Muscle Memory Compatability Note
  34
  35 vim-surround uses a lowercase `s` instead of `S` for surround commands! This is
  36 configurable in the package settings, if you would like to set it to the
  37 original keybinding.
  38
  39 ## How to use Surround
  40
  41 ### Surrounding
  42
  43 For double quotes, highlight the string in visual mode and enter `s "`.
  44
  45 ```
  46 Hello world -> "Hello world"
  47 ```
  48
  49 For parentheses there are two options. `s )` will surround as normal. `s (`
  50 will pad with a space. All asymmetrical pairs have the secondary space-padded
  51 form.
  52
  53 For example:
  54
  55 `s )`
  56
  57 ```
  58 Hello world -> (Hello world)
  59 ```
  60
  61 `s (`
  62
  63 ```
  64 Hello world -> ( Hello world )
  65 ```
  66
  67 ### Changing Surrounding Pairs
  68
  69 Suppose I want to make double quotes into single quotes. To do this, I should
  70 put my cursor inside the double quotes in question and enter `c s " '`
  71
  72 ```
  73 "Hello world" -> 'Hello world'
  74 ```
  75
  76 ### Deleting Surrounding Pairs
  77
  78 To delete the single quotes, place your cursor inside of them and enter `d s '`
  79
  80 ```
  81 'Hello world' -> Hello world
  82 ```
  83 ### Configuration
  84
  85 Currently, the following pairs work out of the box!:
  86
  87 - ()
  88 - []
  89 - {}
  90 - ""
  91 - ''
  92
  93 You can add to the available pairs in atom's settings, and the commands will
  94 be dynamically added to your keybindings.
  95
  96 For example if I'm working on Jinja templates, and I want to add the ability to
  97 surround using `{%` and `%}` I would add this in my settings:
  98
  99 ```
 100 (), [], {}, "", '', {%%}
 101 ```
 102
 103 Then:
 104
 105 `s % }`
 106
 107 ```
 108 Hello world -> {%Hello world%}
 109 ```
 110
 111 `s { %`
 112
 113 ```
 114 Hello world -> {% Hello world %}
 115 ```
 116
 117 ### TODO
 118
 119 - [x] Implement deleting surrounding pairs with `d s`
 120 - [x] Implement changing surrounding pairs with `c s`
 121 - [ ] Intelligent tag surrounding/deleting/replacing with `s <q>` and friends.