yasnippet/doc/snippet-expansion.org

#+SETUPFILE: org-setup.inc

#+TITLE: Expanding snippets

  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 [[sym:yas-minor-mode][=yas-minor-mode=]] is active:
     - Type the snippet's *trigger key* then calling [[sym:yas-expand][=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 [[sym:yas-insert-snippet][=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

[[sym:yas-expand][=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 [[sym:yas-expand][=yas-maybe-expand=]] contains a
special value which, when bound in a keymap, tells Emacs to call
[[sym:yas-expand][=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 [[sym:yas-expand][=yas-expand=]]
is unbound and so will run whatever command is bound to that key
normally.

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

#+begin_src emacs-lisp :exports code
   (define-key yas-minor-mode-map (kbd "<tab>") nil)
   (define-key yas-minor-mode-map (kbd "TAB") nil)
#+end_src

And set your own:

#+begin_src emacs-lisp :exports code
  ;; 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)
#+end_src


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

[[./images/minor-mode-indicator.png]]

When you use [[sym:yas-global-mode][=yas-global-mode=]] you can also selectively disable
YASnippet in some buffers by calling [[sym:yas-minor-mode][=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 [[sym:yas-expand][=yas-maybe-expand=]] was added.  This is now
obsolete.

** Insert at point

The command [[sym:yas-insert-snippet][=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
[[sym:yas-prompt-functions][=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 [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] when to t substitute
the region contents into the =$0= placeholder of a snippet expanded by
[[sym:yas-insert-snippet][=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
[[./snippet-development.org][Writing Snippets]].

** Expanding from the menu

See [[./snippet-menu.org][the YASnippet Menu]].

** Expanding with =hippie-expand=

To integrate with =hippie-expand=, just put
[[sym:yas-hippie-try-expand][=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 [[sym:yas-expand-snippet][=yas-expand-snippet=]] instead of
[[sym:yas-expand][=yas-expand=]] in this case. [[sym:yas-expand-snippet][=yas-expand-snippet=]] takes a string in
snippet template syntax, if you want to expand an existing snippet you
can use [[sym:yas-lookup-snippet][=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
[[sym:yas-lookup-snippet][=yas-lookup-snippet=]] though). In fact, expanding from the YASnippet
menu has the same effect of evaluating the follow code:

#+BEGIN_SRC emacs-lisp
  (yas-expand-snippet template)
#+END_SRC

See the internal documentation on [[sym:yas-expand-snippet][=yas-expand-snippet=]] and
[[sym:yas-lookup-snippet][=yas-lookup-snippet=]] for more information.

* Controlling expansion

** Eligible snippets<<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
   [[./snippet-organization.org][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.  As a special case,
  if a mode doesn't have a parent, then =fundamental-mode= is
  considered to be its parent.

-  Buffer-local list of extra modes

   Use [[sym:yas-activate-extra-mode][=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:

#+BEGIN_SRC emacs-lisp
  ;; 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)))
#+END_SRC

-  Buffer-local [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] variable

   This variable provides finer grained control over what snippets can
   be expanded in the current buffer.  For example, the constant
   [[sym:yas-not-string-or-comment-condition][=yas-not-string-or-comment-condition=]] has a value that disables
   snippet expansion inside comments or string literals.  See [[condition-system][the
   condition system]] for more info.

** The condition system <<condition-system>>

Consider this scenario: you are an old Emacs hacker. You like the
abbrev-way and bind [[sym:yas-expand][=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 [[./snippet-development.org][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 [[sym:yas-buffer-local-condition][=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 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] like this

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

... 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
[[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]].

** Multiples snippet with the same key

The rules outlined [[eligible-snippets][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
[[sym:yas-prompt-functions][=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:

#+BEGIN_SRC emacs-lisp
  (setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))
#+END_SRC

Currently there are some alternatives solution with YASnippet.

*** Use the X window system

[[./images/x-menu.png]]

The function [[sym:yas-x-prompt][=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

[[./images/ido-menu.png]]

You can use functions [[sym:yas-completing-prompt][=yas-completing-prompt=]] for the classic emacs
completion method or [[sym:yas-ido-prompt][=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=

[[./images/dropdown-menu.png]]

The function [[sym:yas-dropdown-prompt][=yas-dropdown-prompt=]] can also be placed in the
[[sym:yas-prompt-functions][=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 [[sym:yas-prompt-functions][=yas-prompt-functions=]]