update packages
This commit is contained in:
@@ -0,0 +1,284 @@
|
||||
#+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=]]
|
||||
Reference in New Issue
Block a user