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 ### Muscle Memory Compatability Note
  30
  31 vim-surround uses a lowercase `s` instead of `S` for surround commands! This is
  32 configurable in the package settings, if you would like to set it to the
  33 original keybinding.
  34
  35 ## How to use Surround
  36
  37 ### Surrounding
  38
  39 For double quotes, highlight the string in visual mode and enter `s "`.
  40
  41 ```
  42 Hello world -> "Hello world"
  43 ```
  44
  45 For parentheses there are two options. `s )` will surround as normal. `s (`
  46 will pad with a space. All asymmetrical pairs have the secondary space-padded
  47 form.
  48
  49 For example:
  50
  51 `s )`
  52
  53 ```
  54 Hello world -> (Hello world)
  55 ```
  56
  57 `s (`
  58
  59 ```
  60 Hello world -> ( Hello world )
  61 ```
  62
  63 ### Changing Surrounding Pairs
  64
  65 Suppose I want to make double quotes into single quotes. To do this, I should
  66 put my cursor inside the double quotes in question and enter `c s " '`
  67
  68 ```
  69 "Hello world" -> 'Hello world'
  70 ```
  71
  72 ### Deleting Surrounding Pairs
  73
  74 To delete the single quotes, place your cursor inside of them and enter `d s '`
  75
  76 ```
  77 'Hello world' -> Hello world
  78 ```
  79 ### Configuration
  80
  81 Currently, the following pairs work out of the box!:
  82
  83 - ()
  84 - []
  85 - {}
  86 - ""
  87 - ''
  88
  89 You can add to the available pairs in atom's settings, and the commands will
  90 be dynamically added to your keybindings.
  91
  92 For example if I'm working on Jinja templates, and I want to add the ability to
  93 surround using `{%` and `%}` I would add this in my settings:
  94
  95 ```
  96 (), [], {}, "", '', {%%}
  97 ```
  98
  99 Then:
 100
 101 `s % }`
 102
 103 ```
 104 Hello world -> {%Hello world%}
 105 ```
 106
 107 `s { %`
 108
 109 ```
 110 Hello world -> {% Hello world %}
 111 ```
 112
 113 ### TODO
 114
 115 - [x] Implement deleting surrounding pairs with `d s`
 116 - [x] Implement changing surrounding pairs with `c s`
 117 - [ ] Intelligent tag surrounding/deleting/replacing with `s <q>` and friends.