Frequently Asked Questions
│ │ │ │Table of Contents
│ │ │ │-
│ │ │ │ -
- Why are my snippet abbrev keys triggering when I don't want them too? │ │ │ │ -
- Why aren't my snippet abbrev keys triggering when I want them too? │ │ │ │ -
- Why is there an extra newline? │ │ │ │ -
- Why doesn't TAB navigation work with flyspell │ │ │ │ -
- How do I use alternative keys, i.e. not TAB? │ │ │ │ -
- How do I define an abbrev key containing characters not supported by the filesystem? │ │ │ │ +
- Why are my snippet abbrev keys triggering when I don't want them too? │ │ │ │ +
- Why aren't my snippet abbrev keys triggering when I want them too? │ │ │ │ +
- Why is there an extra newline? │ │ │ │ +
- Why doesn't TAB navigation work with flyspell │ │ │ │ +
- How do I use alternative keys, i.e. not TAB? │ │ │ │ +
- How do I define an abbrev key containing characters not supported by the filesystem? │ │ │ │
-
│ │ │ │
- Note: In addition to the questions and answers presented here, │ │ │ │ you might also with to visit the list of solved support issues in │ │ │ │ the Github issue tracker. It might be more up-to-date than this │ │ │ │ list. │ │ │ │
Why are my snippet abbrev keys triggering when I don't want them too?
│ │ │ │ -Why are my snippet abbrev keys triggering when I don't want them too?
│ │ │ │ +
│ │ │ │ Expansion of abbrev keys is controlled by yas-key-syntaxes
. Try
│ │ │ │ removing entries which correspond to the abbrev key character syntax.
│ │ │ │ For example, if you have a snippet with abbrev key "bar", that you
│ │ │ │ don't want to trigger when point follows the text foo_bar
, remove
│ │ │ │ the "w"
entry (since "bar" has only word syntax characters).
│ │ │ │
Why aren't my snippet abbrev keys triggering when I want them too?
│ │ │ │ -Why aren't my snippet abbrev keys triggering when I want them too?
│ │ │ │ +│ │ │ │ See previous question, but in reverse. │ │ │ │
│ │ │ │Why is there an extra newline?
│ │ │ │ -Why is there an extra newline?
│ │ │ │ +│ │ │ │ If there is a newline at the end of a snippet definition file, │ │ │ │ YASnippet will add a newline when expanding that snippet. When editing │ │ │ │ or saving a snippet file, please be careful not to accidentally add a │ │ │ │ terminal newline. │ │ │ │
│ │ │ │ │ │ │ │ @@ -270,17 +270,17 @@ │ │ │ │ Note that some editors will automatically add a newline for you. In │ │ │ │ Emacs, if you setrequire-final-newline
to t
, it will add the
│ │ │ │ final newline automatically.
│ │ │ │
│ │ │ │ Why doesn't TAB navigation work with flyspell
│ │ │ │ -Why doesn't TAB navigation work with flyspell
│ │ │ │ +│ │ │ │ This is Emacs Bug#26672, so you should upgrade to version 25.3 or │ │ │ │ better. Otherwise, a workaround is to inhibit flyspell overlays while │ │ │ │ the snippet is active: │ │ │ │
│ │ │ │ │ │ │ │How do I use alternative keys, i.e. not TAB?
│ │ │ │ -How do I use alternative keys, i.e. not TAB?
│ │ │ │ +
│ │ │ │ Edit the keymaps yas-minor-mode-map
and yas-keymap
as you would
│ │ │ │ any other keymap, but use yas-filtered-definition
on the definition
│ │ │ │ if you want to respect yas-keymap-disable-hook
:
│ │ │ │
How do I define an abbrev key containing characters not supported by the filesystem?
│ │ │ │ -How do I define an abbrev key containing characters not supported by the filesystem?
│ │ │ │ +-
│ │ │ │
- Note: This question applies if you're still defining snippets │ │ │ │ whose key is the filename. This is behavior still provided by │ │ │ │ version 0.6 for backward compatibilty, but is somewhat │ │ │ │ deprecated… │ │ │ │
Writing snippets
│ │ │ │Table of Contents
│ │ │ │-
│ │ │ │ -
- Snippet development │ │ │ │ +
- Snippet development
│ │ │ │
-
│ │ │ │ -
- Quickly finding snippets │ │ │ │ -
- Using the
snippet-mode
major mode
│ │ │ │ + - Quickly finding snippets │ │ │ │ +
- Using the
snippet-mode
major mode
│ │ │ │
│ │ │ │ - - File content │ │ │ │ +
- File content
│ │ │ │
-
│ │ │ │ -
# key:
snippet abbrev
│ │ │ │ -# name:
snippet name
│ │ │ │ -# condition:
snippet condition
│ │ │ │ -# group:
snippet menu grouping
│ │ │ │ -# expand-env:
expand environment
│ │ │ │ -# binding:
direct keybinding
│ │ │ │ -# type:
snippet
orcommand
│ │ │ │ -# uuid:
unique identifier
│ │ │ │ -# contributor:
snippet author
│ │ │ │ +# key:
snippet abbrev
│ │ │ │ +# name:
snippet name
│ │ │ │ +# condition:
snippet condition
│ │ │ │ +# group:
snippet menu grouping
│ │ │ │ +# expand-env:
expand environment
│ │ │ │ +# binding:
direct keybinding
│ │ │ │ +# type:
snippet
orcommand
│ │ │ │ +# uuid:
unique identifier
│ │ │ │ +# contributor:
snippet author
│ │ │ │
│ │ │ │ - - Template Syntax │ │ │ │ +
- Template Syntax
│ │ │ │
-
│ │ │ │ -
- Plain Text │ │ │ │ -
- Embedded Emacs Lisp code │ │ │ │ +
- Plain Text │ │ │ │ +
- Embedded Emacs Lisp code │ │ │ │ │ │ │ │ │ │ │ │ -
- Tab stop fields │ │ │ │ -
- Placeholder fields │ │ │ │ -
- Mirrors │ │ │ │ -
- Mirrors with transformations │ │ │ │ -
- Fields with transformations │ │ │ │ -
- Choosing fields value from a list and other tricks │ │ │ │ -
- Nested placeholder fields │ │ │ │ -
- Indentation markers │ │ │ │ +
- Tab stop fields │ │ │ │ +
- Placeholder fields │ │ │ │ +
- Mirrors │ │ │ │ +
- Mirrors with transformations │ │ │ │ +
- Fields with transformations │ │ │ │ +
- Choosing fields value from a list and other tricks │ │ │ │ +
- Nested placeholder fields │ │ │ │ +
- Indentation markers │ │ │ │
│ │ │ │
Snippet development
│ │ │ │ -Quickly finding snippets
│ │ │ │ -Snippet development
│ │ │ │ +Quickly finding snippets
│ │ │ │ +│ │ │ │ There are some ways you can quickly find a snippet file or create a new one: │ │ │ │
│ │ │ │ │ │ │ │-
│ │ │ │
│ │ │ │
│ │ │ │ │ │ │ │M-x yas-new-snippet
, key binding:C-c & C-n
│ │ │ ││ │ │ │ Creates a new buffer with a template for making a new snippet. The │ │ │ │ -buffer is in
snippet-mode
(see below). When you are done editing │ │ │ │ -the new snippet, useC-c C-c
to save it. │ │ │ │ +buffer is insnippet-mode
(see below). When you are done editing │ │ │ │ +the new snippet, useC-c C-c
to save it. │ │ │ │
│ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │M-x yas-visit-snippet-file
, key binding:C-c & C-v
│ │ │ ││ │ │ │ Prompts you for possible snippet expansions like │ │ │ │
yas-insert-snippet
, but instead of expanding it, takes you directly │ │ │ │ to the snippet definition's file, if it exists. │ │ │ │
│ │ │ │
│ │ │ │ -Once you find this file it will be set to snippet-mode
(see ahead)
│ │ │ │ +Once you find this file it will be set to snippet-mode
(see ahead)
│ │ │ │ and you can start editing your snippet.
│ │ │ │
Using the snippet-mode
major mode
│ │ │ │ -Using the snippet-mode
major mode
│ │ │ │ +
│ │ │ │ There is a major mode snippet-mode
to edit snippets. You can set the
│ │ │ │ buffer to this mode with M-x snippet-mode
. It provides reasonably
│ │ │ │ useful syntax highlighting.
│ │ │ │
│ │ │ │ @@ -320,15 +320,15 @@ │ │ │ │
│ │ │ │ Prompts for a snippet table (with a default based on snippet's │ │ │ │ major mode) and loads the snippet currently being edited. │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ M-x yas-load-snippet-buffer-and-close
, key binding: C-c C-c
│ │ │ │ -
│ │ │ │ +
│ │ │ │
│ │ │ │ Like yas-load-snippet-buffer
, but also saves the snippet and
│ │ │ │ calls quit-window
. The destination is decided based on the
│ │ │ │ chosen snippet table and snippet collection directly (defaulting to
│ │ │ │ the first directory in yas-snippet-dirs
(see Organizing Snippets
│ │ │ │ @@ -350,17 +350,17 @@
│ │ │ │ There are also snippets for writing snippets: vars
, $f
and $m
│ │ │ │ :-).
│ │ │ │
File content
│ │ │ │ -File content
│ │ │ │ +│ │ │ │ A file defining a snippet generally contains the template to be │ │ │ │ expanded. │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ Optionally, if the file contains a line of # --
, the lines above it
│ │ │ │ @@ -383,61 +383,61 @@
│ │ │ │
│ │ │ │ Here's a list of currently supported directives: │ │ │ │
│ │ │ │# key:
snippet abbrev
│ │ │ │ -# key:
snippet abbrev
│ │ │ │ +
│ │ │ │ This is the probably the most important directive, it's the
│ │ │ │ abbreviation you type to expand a snippet just before hitting the key
│ │ │ │ that runs yas-expand
. If you don't specify this,
│ │ │ │ the snippet will not be expandable through the trigger mechanism.
│ │ │ │
# name:
snippet name
│ │ │ │ -# name:
snippet name
│ │ │ │ +│ │ │ │ This is a one-line description of the snippet. It will be displayed in │ │ │ │ the menu. It's a good idea to select a descriptive name for a snippet – │ │ │ │ especially distinguishable among similar snippets. │ │ │ │
│ │ │ │ │ │ │ ││ │ │ │ If you omit this name, it will default to the file name the snippet │ │ │ │ was loaded from. │ │ │ │
│ │ │ │# condition:
snippet condition
│ │ │ │ -# condition:
snippet condition
│ │ │ │ +│ │ │ │ This is a piece of Emacs Lisp code. If a snippet has a condition, then │ │ │ │ it will only be expanded when the condition code evaluate to some │ │ │ │ non-nil value. │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ See also yas-buffer-local-condition
in
│ │ │ │ Expanding snippets
│ │ │ │
# group:
snippet menu grouping
│ │ │ │ -# group:
snippet menu grouping
│ │ │ │ +│ │ │ │ When expanding/visiting snippets from the menu-bar menu, snippets for a │ │ │ │ given mode can be grouped into sub-menus. This is useful if one has too │ │ │ │ many snippets for a mode which will make the menu too long. │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ @@ -453,17 +453,17 @@
│ │ │ │ # group:
directive. Group can also be nested, e.g.
│ │ │ │ control structure.loops
indicates that the snippet is under the loops
│ │ │ │ group which is under the control structure
group.
│ │ │ │
# expand-env:
expand environment
│ │ │ │ -# expand-env:
expand environment
│ │ │ │ +
│ │ │ │ This is another piece of Emacs Lisp code in the form of a let
varlist
│ │ │ │ form, i.e. a list of lists assigning values to variables. It can be
│ │ │ │ used to override variable values while the snippet is being expanded.
│ │ │ │
│ │ │ │ @@ -493,17 +493,17 @@ │ │ │ │ | | | | │ │ │ │ +--+-+--+ │ │ │ │ │ │ │ │
# binding:
direct keybinding
│ │ │ │ -# binding:
direct keybinding
│ │ │ │ +│ │ │ │ You can use this directive to expand a snippet directly from a normal │ │ │ │ Emacs keybinding. The keybinding will be registered in the Emacs keymap │ │ │ │ named after the major mode the snippet is active for. │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ @@ -524,77 +524,77 @@
│ │ │ │ This binding will be recorded in the keymap html-mode-map
. To expand a
│ │ │ │ paragraph tag newlines, just press C-u C-c C-c C-m
. Omitting the C-u
│ │ │ │ will expand the paragraph tag without newlines.
│ │ │ │
# type:
snippet
or command
│ │ │ │ -# type:
snippet
or command
│ │ │ │ +
│ │ │ │ If the type
directive is set to command
, the body of the snippet
│ │ │ │ is interpreted as Lisp code to be evaluated when the snippet is
│ │ │ │ triggered.
│ │ │ │
│ │ │ │ If it's snippet
(the default when there is no type
directive), the
│ │ │ │ -snippet body will be parsed according to the Template Syntax,
│ │ │ │ +snippet body will be parsed according to the Template Syntax,
│ │ │ │ described below.
│ │ │ │
# uuid:
unique identifier
│ │ │ │ -# uuid:
unique identifier
│ │ │ │ +│ │ │ │ This provides to a way to identify a snippet, independent of its name. │ │ │ │ Loading a second snippet file with the same uuid would replace the │ │ │ │ previous snippet. │ │ │ │
│ │ │ │# contributor:
snippet author
│ │ │ │ -# contributor:
snippet author
│ │ │ │ +│ │ │ │ This is optional and has no effect whatsoever on snippet functionality, │ │ │ │ but it looks nice. │ │ │ │
│ │ │ │Template Syntax
│ │ │ │ -Template Syntax
│ │ │ │ +│ │ │ │ The syntax of the snippet template is simple but powerful, very similar │ │ │ │ to TextMate's. │ │ │ │
│ │ │ │Plain Text
│ │ │ │ -Plain Text
│ │ │ │ +
│ │ │ │ Arbitrary text can be included as the content of a template. They are
│ │ │ │ usually interpreted as plain text, except $
and `
. You need to
│ │ │ │ use \
to escape them: \$
and \`
. The \
itself may also needed to be
│ │ │ │ escaped as \\
sometimes.
│ │ │ │
Embedded Emacs Lisp code
│ │ │ │ -Embedded Emacs Lisp code
│ │ │ │ +
│ │ │ │ Emacs Lisp code can be embedded inside the template, written inside
│ │ │ │ back-quotes (`
). The Lisp forms are evaluated when the snippet is
│ │ │ │ being expanded. The evaluation is done in the same buffer as the
│ │ │ │ snippet being expanded.
│ │ │ │
│ │ │ │ to "wrap" the selected region inside your recently inserted snippet.
│ │ │ │ Alternatively, you can also customize the variable
│ │ │ │ yas-wrap-around-region
to t
which will do this automatically.
│ │ │ │
Note: backquote expressions should not modify the buffer
│ │ │ │ -Note: backquote expressions should not modify the buffer
│ │ │ │ +│ │ │ │ Please note that the Lisp forms in backquotes should not modify the │ │ │ │ buffer, doing so will trigger a warning. For example, instead of │ │ │ │ doing │ │ │ │
│ │ │ │ │ │ │ │Tab stop fields
│ │ │ │ -Tab stop fields
│ │ │ │ +
│ │ │ │ Tab stops are fields that you can navigate back and forth by TAB
and
│ │ │ │ S-TAB
. They are written by $
followed with a number. $0
has the
│ │ │ │ special meaning of the exit point of a snippet. That is the last place
│ │ │ │ to go when you've traveled all the fields. Here's a typical example:
│ │ │ │
<div$1> │ │ │ │ $0 │ │ │ │ </div> │ │ │ ││ │ │ │
Placeholder fields
│ │ │ │ -Placeholder fields
│ │ │ │ +│ │ │ │ Tab stops can have default values – a.k.a placeholders. The syntax is │ │ │ │ like this: │ │ │ │
│ │ │ │ │ │ │ │${N:default value}
│ │ │ │
│ │ │ │ │ │ │ │ They act as the default value for a tab stop. But when you first │ │ │ │ type at a tab stop, the default value will be replaced by your typing. │ │ │ │ -The number can be omitted if you don't want to create mirrors or │ │ │ │ -transformations for this field. │ │ │ │ +The number can be omitted if you don't want to create mirrors or │ │ │ │ +transformations for this field. │ │ │ │
│ │ │ │Mirrors
│ │ │ │ -Mirrors
│ │ │ │ +│ │ │ │ We refer to tab stops with placeholders as a field. A field can │ │ │ │ have mirrors. All mirrors get updated whenever you update any field │ │ │ │ text. Here's an example: │ │ │ │
│ │ │ │ │ │ │ │Mirrors with transformations
│ │ │ │ -Mirrors with transformations
│ │ │ │ +
│ │ │ │ If the value of an ${n:
-construct starts with and contains $(
,
│ │ │ │ then it is interpreted as a mirror for field n
with a
│ │ │ │ transformation. The mirror's text content is calculated according to
│ │ │ │ this transformation, which is Emacs Lisp code that gets evaluated in
│ │ │ │ an environment where the variable yas-text
is bound to the text
│ │ │ │ content (string) contained in the field n
. Here's an example for
│ │ │ │ @@ -829,17 +829,17 @@
│ │ │ │
│ │ │ │ To keep the example simple, it uses ignore-errors
to suppress errors
│ │ │ │ due to incomplete format codes.
│ │ │ │
Fields with transformations
│ │ │ │ -Fields with transformations
│ │ │ │ +│ │ │ │ From version 0.6 on, you can also have Lisp transformation inside │ │ │ │ fields. These work mostly like mirror transformations. However, they │ │ │ │ are evaluated when you first enter the field, after each change you │ │ │ │ make to the field and also just before you exit the field. │ │ │ │
│ │ │ │ │ │ │ │ @@ -876,17 +876,17 @@ │ │ │ │ value of the field and sets it its internal modification state to │ │ │ │true
. As a consequence, the auto-deletion behaviour of normal fields
│ │ │ │ does not take place. This is by design.
│ │ │ │
│ │ │ │ Choosing fields value from a list and other tricks
│ │ │ │ -Choosing fields value from a list and other tricks
│ │ │ │ +
│ │ │ │ As mentioned, the field transformation is invoked just after you enter
│ │ │ │ the field, and with some useful variables bound, notably
│ │ │ │ yas-modified-p
and yas-moving-away-p
. Because of this feature you
│ │ │ │ can place a transformation in the primary field that lets you select
│ │ │ │ default values for it.
│ │ │ │
│ │ │ │ The function yas-verify-value
has another neat trick, and makes use
│ │ │ │ of yas-moving-away-p
. Try it and see! Also, check out this thread
│ │ │ │
Nested placeholder fields
│ │ │ │ -Nested placeholder fields
│ │ │ │ +│ │ │ │ From version 0.6 on, you can also have nested placeholders of the type: │ │ │ │
│ │ │ │ │ │ │ │<div${1: id="${2:some_id}"}>$0</div> │ │ │ ││ │ │ │ @@ -965,17 +965,17 @@ │ │ │ │ By the way,
C-d
will only clear the field if you cursor is at the
│ │ │ │ beginning of the field and it hasn't been changed yet. Otherwise, it
│ │ │ │ performs the normal Emacs delete-char
command.
│ │ │ │
│ │ │ │ Indentation markers
│ │ │ │ -Indentation markers
│ │ │ │ +
│ │ │ │ If yas-indent-line
is not set to 'auto
, it's still possible to
│ │ │ │ indent specific lines by adding an indentation marker, $>
, somewhere
│ │ │ │ on the line.
│ │ │ │
Expanding snippets
│ │ │ │Table of Contents
│ │ │ │-
│ │ │ │ -
- Triggering expansion │ │ │ │ +
- Triggering expansion
│ │ │ │
-
│ │ │ │ -
- Trigger key │ │ │ │ +
- Trigger key
│ │ │ │
-
│ │ │ │ -
- Fallback behaviour │ │ │ │ +
- Fallback behaviour │ │ │ │
│ │ │ │ - - Insert at point │ │ │ │ +
- Insert at point
│ │ │ │
-
│ │ │ │ -
- Inserting region or register contents into snippet │ │ │ │ +
- Inserting region or register contents into snippet │ │ │ │
│ │ │ │ - - Snippet keybinding │ │ │ │ -
- Expanding from the menu │ │ │ │ -
- Expanding with
hippie-expand
│ │ │ │ - - Expanding from emacs-lisp code │ │ │ │ +
- Snippet keybinding │ │ │ │ +
- Expanding from the menu │ │ │ │ +
- Expanding with
hippie-expand
│ │ │ │ + - Expanding from emacs-lisp code │ │ │ │
│ │ │ │ - - Controlling expansion │ │ │ │ +
- Controlling expansion
│ │ │ │
-
│ │ │ │ -
- Eligible snippets │ │ │ │ -
- The condition system │ │ │ │ -
- Multiples snippet with the same key │ │ │ │ +
- Eligible snippets │ │ │ │ +
- The condition system │ │ │ │ +
- Multiples snippet with the same key
│ │ │ │
-
│ │ │ │ -
- Use the X window system │ │ │ │ -
- Minibuffer prompting │ │ │ │ -
- Use
dropdown-menu.el
│ │ │ │ - - Roll your own │ │ │ │ +
- Use the X window system │ │ │ │ +
- Minibuffer prompting │ │ │ │ +
- Use
dropdown-menu.el
│ │ │ │ + - Roll your own │ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ Maybe, you'll want some snippets to be expanded in a particular │ │ │ │ mode, or only under certain conditions, or be prompted using │ │ │ │
│ │ │ │ │ │ │ │ -Triggering expansion
│ │ │ │ -Triggering expansion
│ │ │ │ +│ │ │ │ You can use YASnippet to expand snippets in different ways: │ │ │ │
│ │ │ │ │ │ │ │-
│ │ │ │
- When
yas-minor-mode
is active: │ │ │ │-
│ │ │ │ @@ -288,17 +288,17 @@
│ │ │ │
- Use m2m's excellent auto-complete │ │ │ │ TODO: example for this │ │ │ │ │ │ │ │
- Expanding from emacs-lisp code │ │ │ │
Trigger key
│ │ │ │ -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
│ │ │ │ @@ -334,41 +334,41 @@
│ │ │ │
│ │ │ │ To enable the YASnippet minor mode in all buffers globally use the
│ │ │ │ command yas-global-mode
. This will enable a modeline indicator,
│ │ │ │ yas
:
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ 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
│ │ │ │ -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
│ │ │ │ -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 prompting methods used are again controlled by
│ │ │ │ yas-prompt-functions
.
│ │ │ │
Inserting region or register contents into snippet
│ │ │ │ -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.
│ │ │ │
?0
.
│ │ │ │
│ │ │ │ Snippet keybinding
│ │ │ │ -Snippet keybinding
│ │ │ │ +
│ │ │ │ See the section of the # binding:
directive in
│ │ │ │ Writing Snippets.
│ │ │ │
Expanding from the menu
│ │ │ │ -Expanding from the menu
│ │ │ │ +│ │ │ │ See the YASnippet Menu. │ │ │ │
│ │ │ │Expanding with hippie-expand
│ │ │ │ -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
│ │ │ │ -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.
│ │ │ │
yas-expand-snippet
and
│ │ │ │ yas-lookup-snippet
for more information.
│ │ │ │
│ │ │ │ Controlling expansion
│ │ │ │ -Eligible snippets
│ │ │ │ -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:
│ │ │ │ @@ -543,24 +543,24 @@
│ │ │ │ Buffer-local 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
│ │ │ │ yas-not-string-or-comment-condition
has a value that disables
│ │ │ │ -snippet expansion inside comments or string literals. See the
│ │ │ │ +snippet expansion inside comments or string literals. See the
│ │ │ │ condition system for more info.
│ │ │ │
The condition system
│ │ │ │ -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
).
│ │ │ │
│ │ │ │ For the full set of possible conditions, see the documentation for
│ │ │ │ yas-buffer-local-condition
.
│ │ │ │
Multiples snippet with the same key
│ │ │ │ -Multiples snippet with the same key
│ │ │ │ +│ │ │ │ -The rules outlined above can return more than │ │ │ │ +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
│ │ │ │ @@ -629,19 +629,19 @@
│ │ │ │
│ │ │ │ Currently there are some alternatives solution with YASnippet. │ │ │ │
│ │ │ │Use the X window system
│ │ │ │ -Use the X window system
│ │ │ │ +│ │ │ │
│ │ │ │
│ │ │ │ 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
│ │ │ │ @@ -654,36 +654,36 @@
│ │ │ │
C-n
, C-p
to
│ │ │ │ navigate this menu.Minibuffer prompting
│ │ │ │ -Minibuffer prompting
│ │ │ │ +│ │ │ │
│ │ │ │
│ │ │ │ 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
│ │ │ │ -Use dropdown-menu.el
│ │ │ │ +│ │ │ │
│ │ │ │
│ │ │ │ The function yas-dropdown-prompt
can also be placed in the
│ │ │ │ yas-prompt-functions
list.
│ │ │ │ @@ -693,17 +693,17 @@
│ │ │ │ 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
│ │ │ │ -Roll your own
│ │ │ │ +
│ │ │ │ See the documentation on variable yas-prompt-functions
│ │ │ │
YASnippet menu
│ │ │ │Table of Contents
│ │ │ │-
│ │ │ │ -
- Loading snippets from menu │ │ │ │ -
- Snippet menu behavior │ │ │ │ -
- Controlling indenting │ │ │ │ -
- Prompting method │ │ │ │ -
- Misc │ │ │ │ +
- Loading snippets from menu │ │ │ │ +
- Snippet menu behavior │ │ │ │ +
- Controlling indenting │ │ │ │ +
- Prompting method │ │ │ │ +
- Misc │ │ │ │
│ │ │ │ When yas-minor-mode
is active, YASnippet will setup a menu just after
│ │ │ │ the "Buffers" menu in the menubar.
│ │ │ │
│ │ │ │
│ │ │ │Loading snippets from menu
│ │ │ │ -Loading snippets from menu
│ │ │ │ +
│ │ │ │ Invoking "Load snippets…" from the menu invokes yas-load-directory
│ │ │ │ and prompts you for a snippet directory hierarchy to load.
│ │ │ │
│ │ │ │ Also useful is the "Reload everything" item to invoke yas-reload-all
│ │ │ │ which uncondionally reloads all the snippets directories defined in
│ │ │ │ yas-snippet-dirs
and rebuilds the menus.
│ │ │ │
Snippet menu behavior
│ │ │ │ -Snippet menu behavior
│ │ │ │ +│ │ │ │ YASnippet will list in this section all the loaded snippet definitions │ │ │ │ organized by snippet table name. │ │ │ │
│ │ │ │ │ │ │ ││ │ │ │ You can use this section to explore currently loaded snippets. If you │ │ │ │ @@ -303,38 +303,38 @@ │ │ │ │
│ │ │ │ These customizations can also be found in the menu itself, under the │ │ │ │ "Snippet menu behavior" submenu. │ │ │ │
│ │ │ │Controlling indenting
│ │ │ │ -Controlling indenting
│ │ │ │ +
│ │ │ │ The "Indenting" submenu contains options to control the values of
│ │ │ │ yas-indent-line
and yas-also-auto-indent-first-line
. See
│ │ │ │ Writing snippets.
│ │ │ │
Prompting method
│ │ │ │ -Prompting method
│ │ │ │ +
│ │ │ │ The "Prompting method" submenu contains options to control the value of
│ │ │ │ yas-prompt-functions
. See Expanding snippets.
│ │ │ │
Misc
│ │ │ │ -Misc
│ │ │ │ +│ │ │ │ The "Misc" submenu contains options to control the values of more │ │ │ │ variables. │ │ │ │
│ │ │ │Organizing snippets
│ │ │ │Table of Contents
│ │ │ │-
│ │ │ │ -
- Basic structure │ │ │ │ -
- Setting up
yas-snippet-dirs
│ │ │ │ - - The
.yas-parents
file
│ │ │ │ - - TODO The
.yas-make-groups
file
│ │ │ │ - - The
.yas-setup.el
file
│ │ │ │ - - The
.yas-compiled-snippet.el
file
│ │ │ │ - - The
.yas-skip
file
│ │ │ │ + - Basic structure │ │ │ │ +
- Setting up
yas-snippet-dirs
│ │ │ │ + - The
.yas-parents
file
│ │ │ │ + - TODO The
.yas-make-groups
file
│ │ │ │ + - The
.yas-setup.el
file
│ │ │ │ + - The
.yas-compiled-snippet.el
file
│ │ │ │ + - The
.yas-skip
file
│ │ │ │
Basic structure
│ │ │ │ -Basic structure
│ │ │ │ +│ │ │ │ Snippet collections can be stored in plain text files. They are │ │ │ │ arranged by sub-directories naming snippet tables. These mostly │ │ │ │ name Emacs major mode names. │ │ │ │
│ │ │ │ │ │ │ │ -│ │ │ │ +│ │ │ │ . │ │ │ │ |-- c-mode │ │ │ │ | `-- printf │ │ │ │ |-- java-mode │ │ │ │ | `-- println │ │ │ │ `-- text-mode │ │ │ │ |-- email │ │ │ │ @@ -253,17 +253,17 @@ │ │ │ │ The collections are loaded into snippet tables which the │ │ │ │ triggering mechanism (see Expanding Snippets) looks up and │ │ │ │ (hopefully) causes the right snippet to be expanded for you. │ │ │ │ │ │ │ │
Setting up yas-snippet-dirs
│ │ │ │ -Setting up yas-snippet-dirs
│ │ │ │ +
│ │ │ │ The emacs variable yas-snippet-dirs
tells YASnippet
│ │ │ │ which collections to consider. It's used when you activate
│ │ │ │ yas-global-mode
or call
│ │ │ │ yas-reload-all
interactively.
│ │ │ │
yas-new-snippet
always stores
│ │ │ │ snippets in the first collection.
│ │ │ │
│ │ │ │ The .yas-parents
file
│ │ │ │ -The .yas-parents
file
│ │ │ │ +
│ │ │ │ It's very useful to have certain modes share snippets between
│ │ │ │ themselves. To do this, choose a mode subdirectory and place a
│ │ │ │ .yas-parents
containing a whitespace-separated list of other mode
│ │ │ │ names. When you reload those modes become parents of the original
│ │ │ │ mode.
│ │ │ │
│ │ │ │ +│ │ │ │ . │ │ │ │ |-- c-mode │ │ │ │ | |-- .yas-parents # contains "cc-mode text-mode" │ │ │ │ | `-- printf │ │ │ │ |-- cc-mode │ │ │ │ | |-- for │ │ │ │ | `-- while │ │ │ │ @@ -327,36 +327,36 @@ │ │ │ │ |-- email │ │ │ │ `-- time │ │ │ ││ │ │ │
TODO The .yas-make-groups
file
│ │ │ │ -TODO The .yas-make-groups
file
│ │ │ │ +
│ │ │ │ If you place an empty plain text file .yas-make-groups
inside one
│ │ │ │ of the mode directories, the names of these sub-directories are
│ │ │ │ considered groups of snippets and the menu is organized much more
│ │ │ │ cleanly:
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │ Another way to achieve this is to place a # group:
directive
│ │ │ │ inside the snippet definition. See Writing Snippets.
│ │ │ │
│ │ │ │ +│ │ │ │ $ tree ruby-mode/ │ │ │ │ ruby-mode/ │ │ │ │ |-- .yas-make-groups │ │ │ │ |-- collections │ │ │ │ | |-- each │ │ │ │ | `-- ... │ │ │ │ |-- control structure │ │ │ │ @@ -371,28 +371,28 @@ │ │ │ ││ │ │ │ Yet another way to create a nice snippet menu is to write into │ │ │ │
│ │ │ │.yas-make-groups
a menu definition. TODO │ │ │ │
The .yas-setup.el
file
│ │ │ │ -The .yas-setup.el
file
│ │ │ │ +
│ │ │ │ If there is file named .yas-setup.el
in a mode's snippet
│ │ │ │ subdirectory, it is loaded along with the snippets. Utility
│ │ │ │ functions used by the snippets can be put here.
│ │ │ │
The .yas-compiled-snippet.el
file
│ │ │ │ -The .yas-compiled-snippet.el
file
│ │ │ │ +
│ │ │ │ You may compile a top-level snippet directory with the
│ │ │ │ yas-compile-directory
function, which will create a
│ │ │ │ .yas-compiled-snippets.el
file under each mode subdirectory,
│ │ │ │ which contains definitions for all snippets in the subdirectory.
│ │ │ │ Compilation helps improve loading time.
│ │ │ │
│ │ │ │ Alternatively, you may compile all directories in the list
│ │ │ │ yas-snippet-dirs
with the yas-recompile-all
function.
│ │ │ │
The .yas-skip
file
│ │ │ │ -The .yas-skip
file
│ │ │ │ +
│ │ │ │ A .yas-skip
file in a mode's snippet subdirectory tells YASnippet
│ │ │ │ not to load snippets from there.
│ │ │ │
Reference
│ │ │ │Table of Contents
│ │ │ │-
│ │ │ │ -
- Interactive functions │ │ │ │ +
- Interactive functions
│ │ │ │
-
│ │ │ │
yas-visit-snippet-file
()
│ │ │ │ yas-new-snippet
(&optionalno-template
)
│ │ │ │ yas-expand-from-keymap
()
│ │ │ │ yas-prev-field
()
│ │ │ │ yas-minor-mode-on
()
│ │ │ │ yas-describe-table-by-namehash
()
│ │ │ │ @@ -249,15 +249,15 @@
│ │ │ │ yas-skip-and-clear-or-delete-char
(&optionalfield
)
│ │ │ │ yas-deactivate-extra-mode
(mode
)
│ │ │ │ yas-activate-extra-mode
(mode
)
│ │ │ │ yas-global-mode
(&optionalarg
)
│ │ │ │ yas-insert-snippet
(&optionalno-condition
)
│ │ │ │
│ │ │ │ - - Customization variables │ │ │ │ +
- Customization variables
│ │ │ │
-
│ │ │ │
yas-choose-tables-first
│ │ │ │ yas-buffer-local-condition
│ │ │ │ yas-choose-keys-first
│ │ │ │ yas-expand-only-for-last-commands
│ │ │ │ yas-global-mode-hook
│ │ │ │ yas-good-grace
│ │ │ │ @@ -276,15 +276,15 @@
│ │ │ │ yas-alias-to-yas/prefix-p
│ │ │ │ yas-keymap-disable-hook
│ │ │ │ yas-overlay-priority
│ │ │ │ yas-trigger-symbol
│ │ │ │ yas-indent-line
│ │ │ │
│ │ │ │ - - Useful functions │ │ │ │ +
- Useful functions
│ │ │ │
-
│ │ │ │
yas-global-mode-cmhh
()
│ │ │ │ yas-global-mode-check-buffers
()
│ │ │ │ yas-current-field
()
│ │ │ │ yas-choose-value
(&restpossibilities
)
│ │ │ │ yas-ido-prompt
(prompt
choices
&optionaldisplay-fn
)
│ │ │ │ yas-dropdown-prompt
(_prompt
choices
&optionaldisplay-fn
)
│ │ │ │ @@ -322,15 +322,15 @@
│ │ │ │ yas-default-from-field
(number
)
│ │ │ │ yas-active-snippets
(&optionalbeg
end
)
│ │ │ │ yas-maybe-ido-prompt
(prompt
choices
&optionaldisplay-fn
)
│ │ │ │ yas-auto-next
(&restbody
)
│ │ │ │ yas-throw
(text
)
│ │ │ │
│ │ │ │ - - Useful variables │ │ │ │ +
- Useful variables
│ │ │ │
-
│ │ │ │
yas-snippet-beg
│ │ │ │ yas-maybe-skip-and-clear-field
│ │ │ │ yas-not-string-or-comment-condition
│ │ │ │ yas-after-reload-hook
│ │ │ │ yas-keymap
│ │ │ │ yas-snippet-end
│ │ │ │ @@ -350,17 +350,17 @@
│ │ │ │ yas-modified-p
│ │ │ │
│ │ │ │
Interactive functions
│ │ │ │ -Interactive functions
│ │ │ │ +yas-visit-snippet-file
()
│ │ │ │
│ │ │ │ Choose a snippet to edit, selection like yas-insert-snippet
.
│ │ │ │
│ │ │ │ Key bindings: │ │ │ │
│ │ │ │ -│ │ │ │ +│ │ │ │ key binding │ │ │ │ --- ------- │ │ │ │ │ │ │ │ C-c Prefix Command │ │ │ │ │ │ │ │ C-c & Prefix Command │ │ │ │ │ │ │ │ @@ -796,17 +796,17 @@ │ │ │ ││ │ │ │ With prefix argument
│ │ │ │no-condition
, bypass filtering of snippets │ │ │ │ by condition. │ │ │ │
Customization variables
│ │ │ │ -Customization variables
│ │ │ │ +yas-choose-tables-first
│ │ │ │ │ │ │ │ If non-nil, and multiple eligible snippet tables, prompts user for tables first. │ │ │ │
│ │ │ │ @@ -1224,17 +1224,17 @@ │ │ │ │ Every other value means don't apply any snippet-side indentation │ │ │ │ after expansion (the manual per-line "$>" indentation still │ │ │ │ applies). │ │ │ │ │ │ │ │Useful functions
│ │ │ │ -Useful functions
│ │ │ │ +yas-global-mode-cmhh
()
│ │ │ │
│ │ │ │ warning: no doc for symbol yas-global-mode-cmhh
│ │ │ │
│ │ │ │ Signal yas-exception
with text
as the reason.
│ │ │ │
Useful variables
│ │ │ │ -Useful variables
│ │ │ │ +yas-snippet-beg
│ │ │ │ │ │ │ │ Beginning position of the last snippet committed. │ │ │ │