[[https://travis-ci.org/emacs-evil/evil-surround.svg?branch=master][https://travis-ci.org/emacs-evil/evil-surround.svg?branch=master]] [[https://melpa.org/#/evil-surround][https://melpa.org/packages/evil-surround-badge.svg]] [[https://stable.melpa.org/#/evil-surround][file:https://stable.melpa.org/packages/evil-surround-badge.svg]] [[https://www.gnu.org/licenses/gpl-3.0.en.html][https://img.shields.io/badge/license-GPLv3-blue.svg]]
This package emulates [[https://github.com/tpope/vim-surround][surround.vim]] by [[https://github.com/tpope][Tim Pope]]. The functionality is wrapped into a minor mode.
This package uses [[https://github.com/emacs-evil/evil][Evil]] as its vi layer.
To enable it through [[https://github.com/jwiegley/use-package][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
** Change surrounding
You can change a surrounding with =cs
** Delete surrounding
You can delete a surrounding with =ds
** 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))
Here are some usage examples (taken from [[https://github.com/tpope/vim-surround][surround.vim]]):
Press =cs"'= inside
"Hello world!"to change it to
'Hello world!'Now press =cs'= 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=
Hello world!
Finally, let's try out visual mode. Press a capital V (for linewise visual mode) followed by =S
=.
Hello world!
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 [[https://github.com/tpope/vim-surround/commit/6f0984a][commit]]. See the discussion in [[https://github.com/timcharper/evil-surround/pull/48][this]] pull request for more details.
** interactively
make make emacs
** command
make make test
Credits Credits and many [[https://github.com/emacs-evil/evil/issues/842][thanks]] go to [[http://github.com/timcharper][Tim Harper]], the original mantainer of the package.
LICENSE
[[https://www.gnu.org/licenses/gpl-3.0.en.html][GNU General Public License v3]]
GNU General Public License v3 Copyright (C) 2010 - 2017 Tim Harper Copyright (c) 2018 - 2020 The evil-surround Contributors