Smartparens

https://smartparens.readthedocs.io/en/latest/
Admin
Smartparens is a minor mode for Emacs that deals with parentheses pairs, providing intelligent...
Tokens:5,882
Snippets:85
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Define Anonymous Pair Configuration with Actions

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Define an anonymous pair configuration directly within a buffer-local hook. Ensure at least one action is specified to prevent pair removal. This example adds a `# #` pair to `php-mode` buffers.

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

--------------------------------

### Example Custom Predicate: sp-point-after-word-p

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Definition of the built-in 'sp-point-after-word-p' predicate, which checks if the point is after a word character. This predicate is specifically tested for the 'insert' action.

```lisp
(defun sp-point-after-word-p (id action context)
  "Return t if point is after a word, nil otherwise.  This
predicate is only tested on \"insert\" action."
  (when (eq action 'insert)
    (save-excursion
      (backward-char 1)
      (looking-back "\\sw\\|\\s_"))))
```

--------------------------------

### Define Local Pair with When Filter

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Example of defining a local pair for a backtick that autopairs only when the point is inside a string in emacs-lisp-mode.

```lisp
(sp-local-pair 'emacs-lisp-mode "`" nil :when '(sp-in-string-p))
```

--------------------------------

### Get Parent Major Modes

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

This snippet retrieves a list of parent major modes for the current buffer's major mode. It's useful for understanding mode inheritance when defining local pairs.

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

--------------------------------

### Configure Smartparens Pair Actions

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Use `sp-pair` to define which actions a delimiter pair should support globally. By default, all actions are enabled.

```Emacs Lisp
(sp-pair "'" "'" :actions '(wrap))          ;; only use '' pair for wrapping
(sp-pair "%" "%" :actions '(insert))        ;; only use %% pair for auto insertion, never for wrapping
(sp-pair "(" ")" :actions '(wrap insert))   ;; use () pair for both actions.
```

--------------------------------

### Define Basic Pairs

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Use the `sp-pair` function to define new pairs. Pairs can have the same opening and closing strings.

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

```

--------------------------------

### Basic Insertion

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Represents a simple insertion of the string 'ab'.

```Emacs Lisp
"ab" => (progn (insert "ab"))
```

--------------------------------

### Configure Multiple Modes with `sp-with-modes`

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

The `sp-with-modes` macro simplifies configuring multiple pairs across specified major modes. It automatically applies subsequent forms to the given modes.

```emacs-lisp
(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))
```

--------------------------------

### Add Wrapping Binding for Pairs

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Define a binding for the wrapping action using the `:wrap` keyword. This command wraps the next expression or an active region with the specified pair.

```Emacs Lisp
(sp-pair "(" ")" :wrap "C-(")
;; |foobar
;; hit C-(
;; becomes (|foobar)

```

--------------------------------

### Local Pair Definition with Post-Handler (Emacs Lisp)

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Defines a local pair for Emacs Lisp mode with a post-handler that inserts a space, remembers the position, and inserts another space, creating a formatted pair.

```Emacs Lisp
(sp-local-pair 'emacs-lisp-mode "(" nil :post-handlers '(:add " | "))
;; so that typing `(' results into `( | )', where | is the point.
```

--------------------------------

### Configure Local Smartparens Pair Actions

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Use `sp-local-pair` to override or disable actions for a specific delimiter pair within a major mode. Setting actions to `nil` completely disables the pair in that mode.

```Emacs Lisp
(sp-local-pair 'emacs-lisp-mode "'" nil :actions nil)           ;; no '' pair in emacs-lisp-mode
(sp-local-pair 'markdown-mode "`" nil :actions '(insert))       ;; only use ` for auto insertion in markdown-mode
(sp-local-pair 'latex-mode "\\\"" nil :actions '(:rem insert))   ;; do not use \" for insert action but use it for any other action
```

--------------------------------

### Insertion with Save Excursion

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Inserts 'a', then 'b' while saving the point to return after 'b' is inserted.

```Emacs Lisp
"a|b" =>
(progn
  (insert "a")
  (save-excursion
    (insert "b")))
```

--------------------------------

### Pretty-Formatting Comments

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

This specification pretty-formats /**/ style comments after RET.

```Emacs Lisp
"* ||\n[i]" =>  ;; pretty-formats /**/ style comments after RET
(progn
  (insert "* ")
  (save-excursion
    (insert "\n")
    (indent-according-to-mode))
  (indent-according-to-mode))
```

--------------------------------

### Local Pair Definition with Post-Handler (C++)

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Defines a local pair for C++ mode with a post-handler that uses the insertion specification language.

```Emacs Lisp
(sp-local-pair 'c++-mode "{" nil :post-handlers '((my-create-newline-and-enter-sexp "RET")))
;; =>
(sp-local-pair 'c++-mode "{" nil :post-handlers '(("||\n[i]" "RET")))
```

--------------------------------

### Configure Delayed Insertion for Ruby Mode

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Sets up a delayed insertion for the 'def' and 'end' pair in Ruby mode. The closing pair is inserted only if the next action is SPC, RET, or <evil-ret>.

```emacs-lisp
(sp-local-pair 'ruby-mode "def" "end"
               :when '(("SPC" "RET" "<evil-ret>"))
               )
```

--------------------------------

### Add Insert Binding with Trigger

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Define a binding for the insert action using the `:insert` keyword and optionally a `:trigger`. This inserts the pair in the buffer, useful for hotkeys or chords.

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

```

--------------------------------

### Apply Named Pair Definition to Buffer

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Apply a previously defined named pair configuration to the current buffer using `sp-update-local-pairs`. This merges the named configuration into the buffer's local definitions.

```emacs-lisp
(sp-update-local-pairs 'escaped-pairs)
```

--------------------------------

### Define Custom Named Pair Definitions

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Define custom named pair configurations using `sp-local-pair`. These sets can be applied across major modes.

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

--------------------------------

### Define Local Smartparens Pair

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Use `sp-local-pair` to define a pair that is specific to a major mode. This allows overriding global definitions for certain contexts.

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

--------------------------------

### Add Custom Hook to C Mode Pair

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Adds the `my-open-block-c-mode` function to the post-handlers for the '{' pair in C mode. Uses :add to preserve existing global handlers.

```Emacs Lisp
(sp-local-pair 'c-mode "{" nil :post-handlers '(:add my-open-block-c-mode))
```

--------------------------------

### Add Global Filter

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Adds a global filter using sp-pair. This sets a default behavior for all modes.

```Emacs Lisp
(sp-pair "'" nil :unless '(sp-point-after-word-p))
```

--------------------------------

### Define Delayed Action Hook for C++ Mode

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Defines a function to create a newline and enter a sexp block, intended for delayed execution after specific key presses. This hook is intended for use with the :post-handlers argument.

```Emacs Lisp
(defun my-create-newline-and-enter-sexp (&rest _ignored)
  "Open a new brace or bracket expression, with relevant newlines and indent. "
  (newline)
  (indent-according-to-mode)
  (forward-line -1)
  (indent-according-to-mode))
```

--------------------------------

### Default Smartparens Pairs

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Smartparens includes a list of common default pairs. These are defined as a list of cons cells, where each cell represents an opening and closing delimiter pair.

```emacs-lisp
"\\(" . "\\)" ;; 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
```

--------------------------------

### Delayed RET Action for C-like Languages

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

This specification is useful as a delayed RET action for {} pairs in C-like languages, inserting a newline and indenting.

```Emacs Lisp
"||\n[i]" =>   ;; this is useful as a delayed RET action for {} pair in C-like languages
(progn         ;; cf. my-create-newline-and-enter-sexp above
  (save-excursion
    (insert "\n")
    (indent-according-to-mode))
  (indent-according-to-mode))
```

--------------------------------

### Define Custom C Mode Open Block Hook

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Defines a function to automatically add newlines and position the cursor inside a newly inserted pair in C mode. This hook is intended for use with the :post-handlers argument.

```Emacs Lisp
(defun my-open-block-c-mode (id action context)
  (when (eq action 'insert)
    (newline)
    (newline)
    (indent-according-to-mode)
    (previous-line)
    (indent-according-to-mode)))
```

--------------------------------

### Enable Escaping When Wrapping a Region

Source: https://smartparens.readthedocs.io/en/latest/automatic-escaping.html

If non-nil, escape special characters inside the just wrapped region. This is enabled by default.

```Emacs Lisp
sp-escape-wrapped-region
```

--------------------------------

### Add Custom Space Hook to Emacs Lisp Pair

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Adds the `my-add-space-after-sexp-insertion` function to the post-handlers for the '(' pair in Emacs Lisp mode. Uses :add to preserve existing global handlers.

```Emacs Lisp
(sp-local-pair 'emacs-lisp-mode "(" nil :post-handlers '(:add my-add-space-after-sexp-insertion))
```

--------------------------------

### Remove Filter Locally (Simplified)

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Achieves the same result as removing a filter locally in C-mode when only one filter is involved. This simplifies the syntax for removing a single local filter.

```Emacs Lisp
(sp-local-pair '(c-mode) "'" nil :unless nil)
```

--------------------------------

### Add Delayed Action Hook to C++ Mode Pair

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Associates a delayed action hook with the '{' pair in C++ mode, triggering the `my-create-newline-and-enter-sexp` function after the 'RET' key is pressed following an insertion.

```Emacs Lisp
(sp-local-pair 'c++-mode "{" nil :post-handlers '((my-create-newline-and-enter-sexp "RET")))
```

--------------------------------

### Add 'escape' Action for Delimiter Insertion

Source: https://smartparens.readthedocs.io/en/latest/automatic-escaping.html

This action tells smartparens to escape a single inserted delimiter even if the insert action was inhibited. It is tried after 'wrap and 'insert actions.

```Emacs Lisp
'escape
```

--------------------------------

### Define Custom Space Insertion Hook for Emacs Lisp

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Defines a function to add a space after a pair if it's immediately followed by a word or another pair. This hook is intended for use with the :post-handlers argument.

```Emacs Lisp
(defun my-add-space-after-sexp-insertion (id action _context)
  (when (eq action 'insert)
    (save-excursion
      (forward-char (length (plist-get (sp-get-pair id) :close)))
      (when (or (eq (char-syntax (following-char)) ?w)
                (looking-at (sp--get-opening-regexp)))
        (insert " "))))
```

--------------------------------

### Filter Logic Expression

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

The logical expression that determines if an action should be performed based on 'when' and 'unless' lists.

```lisp
(and (test-predicates when-list)
     (not (test-predicates unless-list)))
```

--------------------------------

### Remove Smartparens Pairs

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Use `sp-pair` with the `:actions :rem` argument to remove specific pairs. This is primarily for debugging or removing built-in pairs.

```emacs-lisp
;; 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)
```

--------------------------------

### Enable Escaping Quotes After Insertion

Source: https://smartparens.readthedocs.io/en/latest/automatic-escaping.html

If non-nil, escape string quotes if typed inside a string. This hook is triggered on the 'insert action.

```Emacs Lisp
sp-escape-quotes-after-insert
```

--------------------------------

### Remove Local Smartparens Pair

Source: https://smartparens.readthedocs.io/en/latest/pair-management.html

Call `sp-local-pair` with the `:actions :rem` argument to remove a locally defined pair. This does not affect global pairs.

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

--------------------------------

### Remove Filter Locally in C-mode

Source: https://smartparens.readthedocs.io/en/latest/permissions.html

Removes a previously added global filter locally within C-mode using sp-local-pair. This demonstrates overriding global settings for specific modes.

```Emacs Lisp
(sp-local-pair '(c-mode) "'" nil :unless '(:rem sp-point-after-word-p))
```
Tokens:
Raw