hi-angel / evil-surround

you will be surrounded (surround.vim for evil, the extensible vi layer)

This package emulates surround.vim by Tim Pope. The functionality is wrapped into a minor mode.

This package uses Evil as its vi layer.

Installation

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.

Usage

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
              (push '(?~ . ("``" . "``")) evil-surround-pairs-alist))

Add new surround pairs through creation of evil objects

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 regex

Add surround pairs for buffer-local text objects

Buffer-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))

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))

Examples

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!")

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. See the discussion in this pull request for more details.

Contributing

• you are encouraged to test your changes in a standard environment with a clean emacs using just the needed plugins.

interactively

# 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

command

# 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 test

Credits

Credits and many thanks go to Tim Harper, the original mantainer of the package.

LICENSE

• GNU General Public License v3

GNU General Public License v3
Copyright (C) 2010 - 2017 Tim Harper
Copyright (c) 2018 - 2020 The evil-surround Contributors