1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
# Overview
This package emulates [surround.vim by Tim Pope](https://github.com/tpope/vim-surround).
The functionality is wrapped into a minor mode.
To enable it globally, add the following lines to ~/.emacs:
(require 'evil-surround)
(global-evil-surround-mode 1)
Alternatively, you can enable surround-mode along a major mode by adding
`turn-on-surround-mode' to the mode hook.
This package uses [Evil](https://gitorious.org/evil) as its vi layer.
## Add surrounding ##
You can surround in visual-state with `S<textobject>` or `gS<textobject>`.
or in normal-state with `ys<textobject>` or `yS<textobject>`.
## Change surrounding ##
You can change a surrounding with `cs<old-textobject><new-textobject>`.
## Delete surrounding ##
You can delete a surrounding with `ds<textobject>`.
## Add new surround pairs ##
A surround pair is this (trigger char with textual left and right strings):
(?> . ("<" . ">"))
or this (trigger char and calling a function):
(?< . surround-read-tag)
You can add new by adding them to `evil-surround-pairs-alist`.
For more information do: `C-h v evil-surround-pairs-alist`.
`evil-surround-pairs-alist` is a buffer local variable, which means that you can have
different surround pairs in different modes.
By default `<` is used to insert a tag, in C++ this may not be useful - but
inserting angle brackets is, so you can add this:
(add-hook 'c++-mode-hook (lambda ()
(push '(?< . ("< " . " >")) evil-surround-pairs-alist)))
Don't worry about having two entries for `<` surround will take the first.
Or in Emacs Lisp modes using \` to enter \` ' is quite useful, but not adding a
pair of ` (the default behavior if no entry in `evil-surround-pairs-alist` is
present), so you can do this:
(add-hook 'emacs-lisp-mode-hook (lambda ()
(push '(?` . ("`" . "'")) evil-surround-pairs-alist)))
without affecting your Markdown surround pairs, where the default is useful.
To change the default `evil-surround-pairs-alist` you have to use `setq-default`, for
example to remove all default pairs:
(setq-default evil-surround-pairs-alist '())
or to add a pair that surrounds with two ` if you enter ~:
(setq-default evil-surround-pairs-alist (cons '(?~ ("``" . "``"))
evil-surround-pairs-alist))
## Add new supported operators ##
You can add support for new operators by adding them to `evil-surround-operator-alist`.
For more information do: `C-h v evil-surround-operator-alist`.
By default, surround works with `evil-change` and `evil-delete`.
To add support for the evil-paredit package, you need to add `evil-paredit-change`
and `evil-paredit-delete` to `evil-surround-operator-alist`, like so:
(add-to-list 'evil-surround-operator-alist
'(evil-paredit-change . change))
(add-to-list 'evil-surround-operator-alist
'(evil-paredit-delete . delete))
## Usage examples ##
Here are some usage examples (taken from
[surround.vim](https://github.com/tpope/vim-surround/blob/master/README.markdown)):
Press `cs"'` inside
"Hello world!"
to change it to
'Hello world!'
Now press `cs'<q>` to change it to
<q>Hello world!</q>
To go full circle, press `cst"` to get
"Hello world!"
To remove the delimiters entirely, press `ds"`.
Hello world!
Now with the cursor on "Hello", press `ysiw]` (`iw` is a text object).
[Hello] world!
Let's make that braces and add some space (use `}` instead of `{` for no
space): `cs]{`
{ Hello } world!
Now wrap the entire line in parentheses with `yssb` or `yss)`.
({ Hello } world!)
Revert to the original text: `ds{ds)`
Hello world!
Emphasize hello: `ysiw<em>`
<em>Hello</em> world!
Finally, let's try out visual mode. Press a capital V (for linewise
visual mode) followed by `S<p class="important">`.
<p class="important">
<em>Hello</em> world!
</p>
Suppose you want to call a function on your visual selection or a text
object. You can simply press `f` instead of the aforementioned keys
and are then prompted for a functionname in the minibuffer, like with
the tags. So with:
"Hello world!"
... after selecting the string, then pressing `Sf`, entering `print`
and pressing return you would get
print("Hello world!")
# FAAQ (frequently actually asked questions)
## Why does `vs` no longer surround?
This is due to an upstream change in `vim-surround`. It happened in this commit: https://github.com/tpope/vim-surround/commit/6f0984a. See the discussion in this pull request for more details: https://github.com/timcharper/evil-surround/pull/48.
|
