Git Product home page Git Product logo

evil-surround's Introduction

Overview

This package emulates surround.vim by Tim Pope. 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 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 inevil-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 surround-operator-alist. For more information do: C-h v 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 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):

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: emacs-evil#48.

evil-surround's People

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.