This package emulates surround.vim by Tim Pope. The functionality is wrapped into a minor mode.
This package uses Evil as its vi layer.
To enable it through use-package, add the following lines to ~/.emacs or ~/.emacs.d/init.el:
(use-package evil-surround
:ensure t
:config
(global-evil-surround-mode 1))Alternatively, you can add the evil-surround.el file to your load-path and add (require 'evil-surround) to your init file.
Also, instead of enabling it globally, you can also enable surround-mode for a given major mode by adding turn-on-surround-mode to the mode hook.
You can surround in visual-state with S<textobject> or gS<textobject>.
Or in normal-state with ys<textobject> or yS<textobject>.
You can change a surrounding with cs<old-textobject><new-textobject>.
You can delete a surrounding with ds<textobject>.
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
(push '(?~ . ("``" . "``")) evil-surround-pairs-alist))You can create new evil objects that will be respected by evil-surround. Just use the following code:
;; this macro was copied from here: https://stackoverflow.com/a/22418983/4921402
(defmacro define-and-bind-quoted-text-object (name key start-regex end-regex)
(let ((inner-name (make-symbol (concat "evil-inner-" name)))
(outer-name (make-symbol (concat "evil-a-" name))))
`(progn
(evil-define-text-object ,inner-name (count &optional beg end type)
(evil-select-paren ,start-regex ,end-regex beg end type count nil))
(evil-define-text-object ,outer-name (count &optional beg end type)
(evil-select-paren ,start-regex ,end-regex beg end type count t))
(define-key evil-inner-text-objects-map ,key #',inner-name)
(define-key evil-outer-text-objects-map ,key #',outer-name))))
(define-and-bind-quoted-text-object "pipe" "|" "|" "|")
(define-and-bind-quoted-text-object "slash" "/" "/" "/")
(define-and-bind-quoted-text-object "asterisk" "*" "*" "*")
(define-and-bind-quoted-text-object "dollar" "$" "\\$" "\\$") ;; sometimes your have to escape the regexBuffer-local text objects are useful for mode specific text objects that you
don’t want polluting the global keymap. To make these objects work with
evil-surround, do the following (for example to bind pipes to Q):
(defvar evil-some-local-inner-keymap (make-sparse-keymap)
"Inner text object test keymap")
(defvar evil-some-local-outer-keymap (make-sparse-keymap)
"Outer text object keymap")
(define-key evil-some-local-inner-keymap "Q" #'evil-inner-pipe)
(define-key evil-some-local-outer-keymap "Q" #'evil-a-pipe)
(define-key evil-visual-state-local-map "iQ" #'evil-inner-pipe)
(define-key evil-operator-state-local-map "iQ" #'evil-inner-pipe)
(define-key evil-visual-state-local-map "aQ" #'evil-a-pipe)
(define-key evil-operator-state-local-map "aQ" #'evil-a-pipe)
(setq evil-surround-local-inner-text-object-map-list (list evil-some-local-inner-keymap))
(setq evil-surround-local-outer-text-object-map-list (list evil-some-local-outer-keymap))
(setq-local evil-surround-pairs-alist (append '((?Q "|" . "|")) evil-surround-pairs-alist))note that the binding to evil-some-local-(inner|outer)-keymap is purely for organizational perpouses, you can skip that step and do:
(define-key evil-visual-state-local-map "iQ" #'evil-inner-pipe)
(define-key evil-operator-state-local-map "iQ" #'evil-inner-pipe)
(define-key evil-visual-state-local-map "aQ" #'evil-a-pipe)
(define-key evil-operator-state-local-map "aQ" #'evil-a-pipe)
(setq evil-surround-local-inner-text-object-map-list (list (lookup-key evil-operator-state-local-map "i")))
(setq evil-surround-local-outer-text-object-map-list (list (lookup-key evil-operator-state-local-map "a")))
(setq-local evil-surround-pairs-alist (append '((?Q "|" . "|")) evil-surround-pairs-alist))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))Here are some usage examples (taken from surround.vim):
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!")This is due to an upstream change in vim-surround. It happened in this commit. See the
discussion in this pull request for more details.
- you are encouraged to test your changes in a standard environment with a clean emacs using just the needed plugins.
# open a shell and go to the evil-surround directory, after cloning it
# this is a clean emacs with just the absolute minimum dependencies needed to test evil-surround interactivelly.
make
make emacs
# now load evil-surround/test/evil-surround-test.el and M-x ert and run the tests# open a shell and go to the evil-surround directory, after cloning it
# this commands ensure that the tests are using a clean emacs with just the absolute minimum dependencies needed.
make
make testCredits and many thanks go to Tim Harper, the original mantainer of the package.
GNU General Public License v3
Copyright (C) 2010 - 2017 Tim Harper
Copyright (c) 2018 - 2020 The evil-surround Contributors