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):
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 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>
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
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.
# 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 test
Credits 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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4