Expanding snippets

Table of Contents

This section describes how YASnippet chooses snippets for expansion at point.

Maybe, you'll want some snippets to be expanded in a particular mode, or only under certain conditions, or be prompted using

Triggering expansion

You can use YASnippet to expand snippets in different ways:

  • When yas-minor-mode is active:
    • Type the snippet's trigger key then calling yas-expand (bound to TAB by default).
    • Use the snippet's keybinding.
    • By expanding directly from the "YASnippet" menu in the menu-bar
    • Using hippie-expand
  • Call yas-insert-snippet (use M-x yas-insert-snippet or its keybinding C-c & C-s).
  • Use m2m's excellent auto-complete TODO: example for this
  • Expanding from emacs-lisp code

Trigger key

yas-expand tries to expand a snippet abbrev (also known as snippet key) before point. YASnippet also provides a conditional binding for this command: the variable yas-maybe-expand contains a special value which, when bound in a keymap, tells Emacs to call yas-expand if and only if there is a snippet abbrev before point. If there is no snippet to expand, Emacs will behave as if yas-expand is unbound and so will run whatever command is bound to that key normally.

When yas-minor-mode is enabled, it binds yas-maybe-expand to TAB and <tab> by default, however, you can freely remove those bindings:

(define-key yas-minor-mode-map (kbd "<tab>") nil)
(define-key yas-minor-mode-map (kbd "TAB") nil)

And set your own:

;; Bind `SPC' to `yas-expand' when snippet expansion available (it
;; will still call `self-insert-command' otherwise).
(define-key yas-minor-mode-map (kbd "SPC") yas-maybe-expand)
;; Bind `C-c y' to `yas-expand' ONLY.
(define-key yas-minor-mode-map (kbd "C-c y") #'yas-expand)

To enable the YASnippet minor mode in all buffers globally use the command yas-global-mode. This will enable a modeline indicator, yas:

minor-mode-indicator.png

When you use yas-global-mode you can also selectively disable YASnippet in some buffers by calling yas-minor-mode with a negative argument in the buffer's mode hook.

Fallback behaviour

YASnippet used to support a more complicated way of sharing keybindings before yas-maybe-expand was added. This is now obsolete.

Insert at point

The command yas-insert-snippet lets you insert snippets at point for your current major mode. It prompts you for the snippet key first, and then for a snippet template if more than one template exists for the same key.

The list presented contains the snippets that can be inserted at point, according to the condition system. If you want to see all applicable snippets for the major mode, prefix this command with C-u.

The prompting methods used are again controlled by yas-prompt-functions.

Inserting region or register contents into snippet

It's often useful to inject already written text in the middle of a snippet. The variable yas-wrap-around-region when to t substitute the region contents into the $0 placeholder of a snippet expanded by yas-insert-snippet. Setting it to a character value (e.g. ?0) will insert the contents of corresponding register.

Older (versions 0.9.1 and below) of Yasnippet, supported a setting of cua that is equivalent to ?0 but only worked with cua-mode turned on. This setting is still supported for backwards compatibility, but is now entirely equivalent to ?0.

Snippet keybinding

See the section of the # binding: directive in Writing Snippets.

Expanding from the menu

Expanding with hippie-expand

To integrate with hippie-expand, just put yas-hippie-try-expand in hippie-expand-try-functions-list. This probably makes more sense when placed at the top of the list, but it can be put anywhere you prefer.

Expanding from emacs-lisp code

Sometimes you might want to expand a snippet directly from your own elisp code. You should call yas-expand-snippet instead of yas-expand in this case. yas-expand-snippet takes a string in snippet template syntax, if you want to expand an existing snippet you can use yas-lookup-snippet to find its contents by name.

As with expanding from the menubar, the condition system and multiple candidates doesn't affect expansion (the condition system does affect yas-lookup-snippet though). In fact, expanding from the YASnippet menu has the same effect of evaluating the follow code:

(yas-expand-snippet template)

See the internal documentation on yas-expand-snippet and yas-lookup-snippet for more information.

Controlling expansion

Eligible snippets

YASnippet does quite a bit of filtering to find out which snippets are eligible for expanding at the current cursor position.

In particular, the following things matter:

  • Currently loaded snippets tables

    These are loaded from a directory hierarchy in your file system. See Organizing Snippets. They are named after major modes like html-mode, ruby-mode, etc…

  • Major mode of the current buffer

    If the currrent major mode matches one of the loaded snippet tables, then all that table's snippets are considered for expansion. Use M-x describe-variable RET major-mode RET to find out which major mode you are in currently.

  • Parent tables

    Snippet tables defined as the parent of some other eligible table are also considered. This works recursively, i.e. parents of parents of eligible tables are also considered.

  • Buffer-local list of extra modes

    Use yas-activate-extra-mode to consider snippet tables whose name does not correspond to a major mode. Typically, you call this from a minor mode hook, for example:

;; When entering rinari-minor-mode, consider also the snippets in the
;; snippet table "rails-mode"
(add-hook 'rinari-minor-mode-hook
          #'(lambda ()
              (yas-activate-extra-mode 'rails-mode)))

The condition system

Consider this scenario: you are an old Emacs hacker. You like the abbrev-way and bind yas-expand to SPC. However, you don't want if to be expanded as a snippet when you are typing in a comment block or a string (e.g. in python-mode).

If you use the # condition : directive (see Writing Snippets) you could just specify the condition for if to be (not (python-syntax-comment-or-string-p)). But how about while, for, etc? Writing the same condition for all the snippets is just boring. So you can instead set yas-buffer-local-condition to (not (python-syntax-comment-or-string-p)) in python-mode-hook.

Then, what if you really want some particular snippet to expand even inside a comment? Set yas-buffer-local-condition like this

(add-hook 'python-mode-hook
          (lambda ()
            (setq yas-buffer-local-condition
                  '(if (python-syntax-comment-or-string-p)
                       '(require-snippet-condition . force-in-comment)
                     t))))

… and for a snippet that you want to expand in comments, specify a condition which evaluates to the symbol force-in-comment. Then it can be expanded as you expected, while other snippets like if still can't expanded in comments.

For the full set of possible conditions, see the documentation for yas-buffer-local-condition.

Multiples snippet with the same key

The rules outlined above can return more than one snippet to be expanded at point.

When there are multiple candidates, YASnippet will let you select one. The UI for selecting multiple candidate can be customized through yas-prompt-functions , which defines your preferred methods of being prompted for snippets.

You can customize it with M-x customize-variable RET yas-prompt-functions RET. Alternatively you can put in your emacs-file:

(setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))

Currently there are some alternatives solution with YASnippet.

Use the X window system

x-menu.png

The function yas-x-prompt can be used to show a popup menu for you to select. This menu will be part of you native window system widget, which means:

  • It usually looks beautiful. E.g. when you compile Emacs with gtk support, this menu will be rendered with your gtk theme.
  • Your window system may or may not allow to you use C-n, C-p to navigate this menu.
  • This function can't be used when in a terminal.

Minibuffer prompting

ido-menu.png

You can use functions yas-completing-prompt for the classic emacs completion method or yas-ido-prompt for a much nicer looking method. The best way is to try it. This works in a terminal.

Use dropdown-menu.el

dropdown-menu.png

The function yas-dropdown-prompt can also be placed in the yas-prompt-functions list.

This works in both window system and terminal and is customizable, you can use C-n, C-p to navigate, q to quit and even press 6 as a shortcut to select the 6th candidate.

Roll your own

See the documentation on variable yas-prompt-functions


Generated by Emacs 26.1 (Org mode 9.1.9) from 0.13.0 (2018-05-13 16:12:51)

Validate