Pair management

Adding pairs

Function sp-pair open close

To define a new pair use the sp-pair function. Here is an example of the most basic use:

(sp-pair "\{" "\}") ;; latex literal brackets (included by default)
(sp-pair "<#" "#>")
(sp-pair "$" "$")   ;; latex inline math mode. Pairs can have same opening and closing string

Pairs defined this way are by default used on all Actions. However, you can disable certain pairs for auto insertion and only have them for wrapping, only use them for navigation or use any other combination of actions. This is achieved by setting the pair’s actions to allow or disable certain operations in certain contexts.

The sp-pair function accepts a family of keyword arguments which can further specify the behaviour. The keyword arguments can be arbitrarily combined in any order, the only requirement is that the first two positional arguments are always open and close for the pair.

(sp-pair :wrap binding)

You can add a binding for a “wrapping” action. Smartparens automatically binds a command that wraps the next expression with this pair to the supplied binding. The bound command accepts the same prefix arguments as sp-select-next-thing. In addition, if a region is already active, it wraps this region.

Note

This is useful in combination with evil visual selection mode, since with regular emacs, smartparens wraps the active regions automatically when you press the delimiter.

Warning

No syntax check is performed on the active region. This might change in the future.

To add the binding use the :wrap keyword:

(sp-pair "(" ")" :wrap "C-(")
;; |foobar
;; hit C-(
;; becomes (|foobar)
(sp-pair :insert binding :trigger trigger)

You can also add a binding for “insert” action. This is done the exact same way as for wrapping, but the keyword is :insert. Pressing this simply inserts the pair in the buffer. This is useful if you want to insert the pair with a modifier hotkey or a chord. To simply provide a shorter (expandable) trigger, you can specify a :trigger keyword.

(sp-local-pair 'LaTeX-mode "\\left(" "\\right)" :insert "C-b l" :trigger "\\l(")

This will make smartparens insert \left(|\right) when you type \l( or hit C-b l (where | is the point). Typing out the entire opening delimiter \left( will also work.

Note

Many such commands for LaTeX are provided in configuration file smartparens-latex.el. Check it out!

Note

You don’t have to use both :trigger and insert; one or the other (or both) are fine.

It is generally better to add these bindings only to certain major modes where you wish you use this functionality instead of binding them globally to avoid hotkey clashes. See the section about local pair definitions.

Removing pairs

You can remove pairs by calling sp-pair using the optional key argument :actions with value :rem. This will also automatically delete any assigned Permissions! This command is mostly only useful for debugging or removing built-in pairs.

;; the second argument is the closing delimiter, so you need to skip it with nil
(sp-pair "\{" nil :actions :rem)
(sp-pair "'" nil :actions :rem)

Default pairs

Since some pairs are so common that virtually every user would use them, smartparens comes with a list of global default pairs. At the moment, this list includes:

("\\\\(" . "\\\\)") ;; emacs regexp parens
("\\{"   . "\\}")   ;; latex literal braces in math mode
("\\("   . "\\)")   ;; capture parens in regexp in various languages
("\\\""  . "\\\"")  ;; escaped quotes in strings
("\""    . "\"")    ;; string double quotes
("'"     . "'")     ;; string single quotes/character quotes
("("     . ")")     ;; parens (yay lisp)
("["     . "]")     ;; brackets
("{"     . "}")     ;; braces (a.k.a. curly brackets)
("`"     . "`")     ;; latex strings. tap twice for latex double quotes

Local pair definitions

Sometimes, a globally defined pair is not appropriate for certain major modes. You can redefine globally defined pairs to have different definition in specific major modes. For example, globally defined pair `` is used in markdown-mode to insert inline code. However, emacs-lisp-mode uses `' for links in comments and in LaTeX-mode this pair is used for quotes. Since they share the opening sequence (the “trigger”), it’s impossible to have both defined globally at the same time. Therefore, it is desired to redefine this global pair to this new value locally.

That is accomplished by using sp-local-pair function:

(sp-local-pair 'emacs-lisp-mode "`" "'") ;; adds `' as a local pair in emacs-lisp-mode

If a global pair with the same trigger does not exist, the pair is defined locally and will only be used in the specified mode. Therefore, you do not need to define a pair globally and then overload it locally. The local definition is sufficient.

Instead of one mode, you can also specify a list to handle multiple modes at the same time (for example '(emacs-lisp-mode LaTeX-mode)).

If you specify a parent major mode all the derived modes will automatically inherit all the definitions. If you want to add a pair to all programming modes you can define it for prog-mode. If you want to add a pair to all text modes you can define it for text-mode.

You can use the following snippet to get all the parent major modes of the major-mode in the current buffer

(let ((parents (list major-mode)))
  (while (get (car parents) 'derived-mode-parent)
    (push (get (car parents) 'derived-mode-parent) parents))
  parents)

Local pairs can be removed by calling sp-local-pair with optional keyword argument :actions with value :rem:

(sp-local-pair 'LaTeX-mode "`" nil :actions :rem)

Warning

This only removes the pairs you have previously added using sp-local-pair. It does not remove/disable a global pair in the specified mode. If you want to disable some pair in specific modes, set its permissions accordingly.

Macro sp-with-modes mode-or-modes &rest forms

When configuring a mode it is often the case that we modify multiple pairs at the same time. The macro sp-with-modes automatically supplies the mode-or-modes as first argument to all later forms (it can be a single symbol or a list of symbols for the multiple major modes).

(sp-with-modes 'emacs-lisp-mode
  ;; disable ', it's the quote character!
  (sp-local-pair "'" nil :actions nil)
  ;; also only use the pseudo-quote inside strings where it
  ;; serves as hyperlink.
  (sp-local-pair "`" "'" :when '(sp-in-string-p sp-in-comment-p)

Named pair definitions (buffer-local)

In addition to using the major mode or a parent mode you can also use an arbitrary symbol as the name of the configuration. This way you can build sets of pairs independent of the major mode hierarchies and you can apply them locally to buffers as you see fit.

The syntax for defining custom named definitions is the same as with sp-local-pair only except a major mode as the first argument you pass your desired name.

You can for example define a set of escaped pairs to be used cross-major-mode

(sp-local-pair 'escaped-pairs "\\<" "\\>")
(sp-local-pair 'escaped-pairs "\\`" "\\'")

You can then apply this definition buffer-locally to the current buffer with

(sp-update-local-pairs 'escaped-pairs)

This will merge this named configuration into the current buffer’s sp-local-pairs definitions.

Alternatively you can also use an anonymous configuration. The configuration is a plist of arguments with the same meaning as those of sp-local-pair with the additional requirement of adding :open and :close keywords for the opening and closing delimiters. You can also pass a list of such plists to apply all of them at once.

Warning

Make sure to specify at least one action in the :actions key otherwise the pair will be removed by the virtue of having no actions. When using sp-local-pair many of the keyword arguments get sensible defaults so you don’t have to specify them; this is not the case when using an anonymous configuration directly. When possible, use mode configrations or named configurations.

This can be used for example for local configuration with major-mode hooks:

(defun my-php-mode-init ()
  (sp-update-local-pairs '(:open "#"
                           :close "#"
                           :actions (insert))))
(add-hook 'php-mode-hook 'my-php-mode-init)

This will add the # # pair to php-mode buffers via the major mode hook.