Frequently Asked Questions
- - -Table of Contents
Why is there an extra newline?
If you have a newline at the end of the snippet definition file, then YASnippet will add a newline when you expanding a snippet. Please don't add a newline at the end if you don't want it when you saving the snippet file.
+
Note some editors will automatically add a newline for you. In Emacs, if
you set require-final-newline to t, it will add the final newline
for you automatically.
Why doesn't TAB expand a snippet?
First check the mode line to see if there's yas. If not, then try
M-x yas-minor-mode to manually turn on the minor mode and try to
@@ -182,25 +198,28 @@ expand the snippet again. If it works, then, you can add the following
code to your .emacs before loading YASnippet:
(add-hook 'the-major-mode-hook 'yas-minor-mode-on) +(add-hook 'the-major-mode-hook 'yas-minor-mode-on)- +
where the-major-mode is the major mode in which yas-minor-mode isn't
enabled by default.
From YASnippet 0.6 you can also use the command M-x yas-global-mode to
turn on YASnippet automatically for all major modes.
If yas-minor-mode is on but the snippet still not expanded. Then try
to see what command is bound to the TAB key: press C-h k and then
press TAB. Emacs will show you the result.
You'll see a buffer prompted by Emacs saying that
TAB runs the command .... Alternatively, you might see
@@ -210,77 +229,77 @@ command other than yas-expand<
following code to work around:
(add-hook 'org-mode-hook - (let ((original-command (lookup-key org-mode-map [tab]))) - `(lambda () - (setq yas-fallback-behavior - '(apply ,original-command)) - (local-set-key [tab] 'yas-expand)))) +(add-hook 'org-mode-hook + (let ((original-command (lookup-key org-mode-map [tab]))) + `(lambda () + (setq yas-fallback-behavior + '(apply ,original-command)) + (local-set-key [tab] 'yas-expand))))- +
replace org-mode-hook and org-mode-map with the major mode hook you
are dealing with (Use C-h m to see what major mode you are in).
As an alternative, you can also try
+(defun yas-advise-indent-function (function-symbol) +(defun yas-advise-indent-function (function-symbol) (eval `(defadvice ,function-symbol (around yas-try-expand-first activate) - ,(format - "Try to expand a snippet before point, then call `%s' as usual" - function-symbol) - (let ((yas-fallback-behavior nil)) - (unless (and (interactive-p) - (yas-expand)) - ad-do-it))))) + ,(format + "Try to expand a snippet before point, then call `%s' as usual" + function-symbol) + (let ((yas-fallback-behavior nil)) + (unless (and (interactive-p) + (yas-expand)) + ad-do-it))))) (yas-advise-indent-function 'ruby-indent-line)- +
To advise the modes indentation function bound to TAB, (in this case
ruby-indent-line) to first try to run yas-expand.
If the output of C-h k RET <tab> tells you that <tab> is indeed
bound to yas-expand but YASnippet still doesn't work, check your
configuration and you may also ask for help on the discussion group.
-See this particular thread for quite some solutions and alternatives.
+See this particular thread for quite some solutions and alternatives.
Don't forget to attach the information on what command is bound to TAB
as well as the mode information (Can be obtained by C-h m).
Why doesn't TAB navigation work with flyspell
A workaround is to inhibit flyspell overlays while the snippet is active:
+(add-hook 'flyspell-incorrect-hook - #'(lambda (dummy1 dummy2 dymmy3) - (and yas-active-field-overlay - (overlay-buffer yas-active-field-overlay)))) +(add-hook 'flyspell-incorrect-hook + #'(lambda (dummy1 dummy2 dymmy3) + (and yas-active-field-overlay + (overlay-buffer yas-active-field-overlay))))- +
This is apparently related to overlay priorities. For some reason, the @@ -291,22 +310,19 @@ solve this problem, drop a line in the discussion group.
How to I use alternative keys, i.e. not TAB?
Edit the keymaps yas-minor-mode-map and
yas-keymap as you would any other keymap:
(define-key yas-minor-mode-map (kbd "<tab>") nil) +(define-key yas-minor-mode-map (kbd "<tab>") nil) (define-key yas-minor-mode-map (kbd "TAB") nil) (define-key yas-minor-mode-map (kbd "<the new key>") 'yas-expand) @@ -318,30 +334,26 @@ Edit the keymaps- - +yas-m (define-key yas-keymap (kbd "<new-next-field-key>") 'yas-next-field-or-maybe-expand) (define-key yas-keymap (kbd "<new-prev-field-key>") 'yas-prev)
How do I turn off the minor mode where in some buffers?
The best way, since version 0.6.1c, is to set the default value of the
variable yas-dont-activate to a lambda function like so:
(set-default 'yas-dont-activate - #'(lambda () - (and yas-root-directory - (null (yas-get-snippet-tables))))) +(set-default 'yas-dont-activate + #'(lambda () + (and yas-root-directory + (null (yas-get-snippet-tables)))))- +
This is also the default value starting for that version. It skips the @@ -349,28 +361,25 @@ minor mode in buffers where it is not applicable (no snippet tables), but only once you have setup your yas-root-directory.
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… +whose key is the filename. This is behavior still provided by +version 0.6 for backward compatibilty, but is somewhat +deprecated…
For example, you want to define a snippet by the key < which is not a
valid character for filename on Windows. This means you can't use the
filename as a trigger key in this case.
You should rather use the # key: directive to specify the key of the
defined snippet explicitly and name your snippet with an arbitrary valid
@@ -378,23 +387,21 @@ filename, lt.YASnippet for example, using < for the
directive:
# key: <
+# key: <
# name: <...></...>
# --
<${1:div}>$0</$1>
-
Generated by Org version 7.9.3f with Emacs version 24 on 2014-10-01T21:16+0100 from 08b044e559cc350c6e7142d088ec2d4a82e378cb +
Generated by Emacs 24.4.91.1 (Org mode 8.2.10) on from 7703a55ac416a131dec45fa6a1e0ec1e31adf760
- - +Yet another snippet extension
- -The YASnippet documentation has been split into separate parts: +
+The YASnippet documentation has been split into separate parts:
--
+
+
- README
- Contains an introduction, installation instructions and other important - notes. +Contains an introduction, installation instructions and other important +notes.
+
- Organizing Snippets
- Describes ways to organize your snippets in the hard disk. +Describes ways to organize your snippets in the hard disk.
+
- Expanding Snippets
- Describes how YASnippet chooses snippets for expansion at point. +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
ido, etc… +Maybe, you'll want some snippets to be expanded in a particular mode, +or only under certain conditions, or be prompted usingido, etc…
+
- Writing Snippets
- Describes the YASnippet definition syntax, which is very close (but - not equivalent) to Textmate's. Includes a section about converting - TextMate snippets. +Describes the YASnippet definition syntax, which is very close (but +not equivalent) to Textmate's. Includes a section about converting +TextMate snippets.
+
- The YASnippet menu
- Explains how to use the YASnippet menu to explore, learn and modify - snippets. +Explains how to use the YASnippet menu to explore, learn and modify +snippets.
+
- Frequently asked questions
- Answers to frequently asked questions. +Answers to frequently asked questions.
+
- YASnippet Symbol Reference
- An automatically generated listing of all YASnippet commands, - (customization) variables, and functions. -
-
Generated by Org version 7.9.3f with Emacs version 24 on 2014-10-01T21:16+0100 from 08b044e559cc350c6e7142d088ec2d4a82e378cb +An automatically generated listing of all YASnippet commands, +(customization) variables, and functions.
- - + + +Generated by Emacs 24.4.91.1 (Org mode 8.2.10) on from 7703a55ac416a131dec45fa6a1e0ec1e31adf760 +
+Writing snippets
- - -Table of Contents
# contributor: snippet author- Plain Text
- Embedded Emacs-lisp code
- Tab stop fields
- Placeholder fields -
- Mirrors -
- Mirrors with transformations +
- +
- Mirrors with
- Fields with transformations
- Choosing fields value from a list and other tricks
- Nested placeholder fields @@ -176,109 +196,107 @@ for the JavaScript code in this tag.
Snippet development
Quickly finding snippets
-There are some ways you can quickly find a snippet file: +There are some ways you can quickly find a snippet file or create a new one:
--
+
+
M-x yas-new-snippet- Prompts you for a snippet name, then tries to guess a suitable - directory to store it, prompting you for creation if it does not - exist. Finally, places you in a new buffer set to
snippet-modeso - you can write your snippet. +Creates a new buffer with a template for making a new snippet. +The buffer is insnippet-mode(see below). When you are done +editing the new snippet, useC-c C-cto save it. This will +prompt for a directory two steps: first, the snippet table +(with a default based on the major mode you started in), and then +then snippet collection directory (defaults to the first directory +inyas-snippet-dirs. (See Organizing Snippets +for more detail on how snippets are organized.)
+
M-x yas-find-snippets- Lets you find the snippet file in the directory the snippet was - loaded from (if it exists) like
find-file-other-window. The - directory searching logic is similar toM-x yas-new-snippet. +Lets you find the snippet file in the directory the snippet was +loaded from (if it exists) likefind-file-other-window. The +directory searching logic is similar toM-x yas-new-snippet.
+
M-x yas-visit-snippet-file- 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. -
+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) and
you can start editing your snippet.
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.
Two commands are defined in this mode:
--
+
+
M-x yas-load-snippet-buffer- When editing a snippet, this loads the snippet into the correct - mode and menu. Bound to
C-c C-cby default while in -snippet-mode. +When editing a snippet, this loads the snippet into the correct +mode and menu. Bound toC-c C-cby default while in +snippet-mode.
+
M-x yas-tryout-snippet- When editing a snippet, this opens a new empty buffer, sets it to - the appropriate major mode and inserts the snippet there, so you - can see what it looks like. This is bound to
C-c C-twhile in -snippet-mode. -
+When editing a snippet, this opens a new empty buffer, sets it to
+the appropriate major mode and inserts the snippet there, so you
+can see what it looks like. This is bound to
C-c C-t while in
+snippet-mode.
+
+
There are also snippets for writing snippets: vars, $f and $m
:-).
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
count as comments, some of which can be directives (or meta data).
@@ -286,30 +304,28 @@ Snippet directives look like # property: value and tweak certain
snippets properties described below. If no # -- is found, the whole
file is considered the snippet template.
Here's a typical example:
+# contributor: pluskid <pluskid@gmail.com>
+# contributor: pluskid <pluskid@gmail.com>
# name: __...__
# --
__${init}__
-
+Here's a list of currently supported directives:
-# 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
@@ -317,55 +333,49 @@ that runs yas-expand
# 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 -- +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
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
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.
+
The # group: property only affect menu construction (See
the YASnippet menu) and the same effect can be
@@ -373,6 +383,7 @@ achieved by grouping snippets into sub-directories and using the
.yas-make-groups special file (for this see
Organizing Snippets
Refer to the bundled snippets for ruby-mode for examples on the
# group: directive. Group can also be nested, e.g.
@@ -380,22 +391,22 @@ Refer to the bundled snippets for ruby-mode for examples on the
group which is under the control structure group.
# 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
+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.
Interesting variables to override are yas-wrap-around-region and
yas-indent-line (see Expanding Snippets).
As an example, you might normally have yas-indent-line set to 'auto
and yas-wrap-around-region set to t, but for this particularly
@@ -403,52 +414,49 @@ brilliant piece of ASCII art these values would mess up your hard work.
You can then use:
# name: ASCII home +# name: ASCII home # expand-env: ((yas-indent-line 'fixed) (yas-wrap-around-region 'nil)) # -- - welcome to my - X humble - / \ home, - / \ $0 - / \ - /-------\ - | | - | +-+ | - | | | | - +--+-+--+ + welcome to my + X humble + / \ home, + / \ $0 + / \ + /-------\ + | | + | +-+ | + | | | | + +--+-+--+- - +
# 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.
+
Additionally a variable yas-prefix is set to to the prefix argument
you normally use for a command. This allows for small variations on the
same snippet, for example in this "html-mode" snippet.
# name: <p>...</p> +# name: <p>...</p> # binding: C-c C-c C-m # -- <p>`(when yas-prefix "\n")`$0`(when yas-prefix "\n")`</p>- +
This binding will be recorded in the keymap html-mode-map. To expand a
@@ -456,73 +464,59 @@ paragraph tag newlines, just press C-u C-c C-c C-m. Omitting the
# 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
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
This is optional and has no effect whatsoever on snippet functionality, but it looks nice.
Template syntax
+The syntax of the snippet template is simple but powerful, very similar to TextMate's.
-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
@@ -530,35 +524,33 @@ use \ to escape them: \$ and \`. The
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.
Here's an example for c-mode` to calculate the header file guard dynamically:
+#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
+#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1
$0
#endif /* $1 */
-
+
From version 0.6, snippets expansions are run with some special
@@ -566,13 +558,13 @@ Emacs-lisp variables bound. One of this is
-
-for ($1;$2;$3) {
+for ($1;$2;$3) {
`yas-selected-text`$0
}
-
+
to "wrap" the selected region inside your recently inserted snippet.
@@ -580,14 +572,11 @@ Alternatively, you can also customize the variable
yas-wrap-around-region to t which will do this automatically.
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
@@ -595,81 +584,72 @@ 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>
+<div$1>
$0
</div>
-
Placeholder fields
-Tab stops can have default values – a.k.a placeholders. The syntax is +Tab stops can have default values – a.k.a placeholders. The syntax is like this:
+${N:default value}
+${N:default value}
-
+They acts as the default value for a tab stop. But when you firstly 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 +3.6 for this field.
Mirrors
+We refer the tab stops with placeholders as a field. A field can have mirrors. Its mirrors will get updated when you change the text of a field. Here's an example:
+\begin{${1:enumerate}}
+\begin{${1:enumerate}}
$0
\end{$1}
-
+
When you type "document" at ${1:enumerate}, the word "document" will
also be inserted at \end{$1}. The best explanation is to see the
screencast(YouTube or avi video).
The tab stops with the same number to the field act as its mirrors. If none of the tab stops has an initial value, the first one is selected as the field and others mirrors.
Mirrors with transformations
+Mirrors with
If the value of an ${n:-construct starts with and contains $(,
then it is interpreted as a mirror for field n with a
@@ -680,9 +660,9 @@ content (string) contained in the field n. Here's an example for
Objective-C:
- (${1:id})${2:foo}
+- (${1:id})${2:foo}
{
return $2;
}
@@ -694,7 +674,7 @@ Objective-C:
}
$0
-
+
Look at ${2:$(capitalize yas-text)}, it is a mirror with
@@ -705,85 +685,84 @@ transformed text. So in this example, if you type "baz" in the field,
the transformed text will be "Baz". This example is also available in
the screencast.
Another example is for rst-mode. In reStructuredText, the document
-title can be some text surrounded by "===" below and above. The "==="
+title can be some text surrounded by "=" below and above. The "="
should be at least as long as the text. So
===== +===== Title =====- +
is a valid title but
+=== +=== Title ===- +
is not. Here's an snippet for rst title:
+${1:$(make-string (string-width yas-text) ?\=)}
+${1:$(make-string (string-width yas-text) ?\=)}
${1:Title}
${1:$(make-string (string-width yas-text) ?\=)}
$0
-
-
+Fields with transformations
From version 0.6 on, you can also have lisp transformation inside fields. These work mostly mirror transformations but are evaluated when you first enter the field, after each change you make to the field and also just before you exit the field.
+The syntax is also a tiny bit different, so that the parser can distinguish between fields and mirrors. In the following example
-
- #define "${1:mydefine$(upcase yas-text)}"
-
+
+#define "${1:mydefine$(upcase yas-text)}"
+
mydefine gets automatically upcased to MYDEFINE once you enter the
field. As you type text, it gets filtered through the transformation
every time.
Note that to tell this kind of expression from a mirror with a
transformation, YASnippet needs extra text between the : and the
transformation's $. If you don't want this extra-text, you can use two
$'s instead.
- #define "${1:$$(upcase yas-text)}"
-
+
+#define "${1:$$(upcase yas-text)}"
+
Please note that as soon as a transformation takes place, it changes the @@ -792,14 +771,11 @@ value of the field and sets it its internal modification state to does not take place. This is by design.
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 @@ -807,80 +783,79 @@ the field, and with some useful variables bound, notably can place a transformation in the primary field that lets you select default values for it.
+
The yas-choose-value does this work for you. For example:
<div align="${2:$$(yas-choose-value '("right" "center" "left"))}">
+<div align="${2:$$(yas-choose-value '("right" "center" "left"))}">
$0
</div>
-
+
See the definition of yas-choose-value to see how it was written using
the two variables.
Here's another use, for LaTeX-mode, which calls reftex-label just as you
enter snippet field 2. This one makes use of yas-modified-p directly.
\section{${1:"Titel der Tour"}}%
+\section{${1:"Titel der Tour"}}%
\index{$1}%
\label{{2:"waiting for reftex-label call..."$(unless yas-modified-p (reftex-label nil 'dont-
insert))}}%
-
+
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
From version 0.6 on, you can also have nested placeholders of the type:
+<div${1: id="${2:some_id}"}>$0</div>
+<div${1: id="${2:some_id}"}>$0</div>
-
+
This allows you to choose if you want to give this div an id
attribute. If you tab forward after expanding it will let you change
-"some_id" to whatever you like. Alternatively, you can just press C-d
+"some\id" to whatever you like. Alternatively, you can just press C-d
(which executes yas-skip-and-clear-or-delete-char) and go straight to
the exit marker.
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.
-
Generated by Emacs 24.4.91.1 (Org mode 8.2.10) on from 7703a55ac416a131dec45fa6a1e0ec1e31adf760 +
+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 -
-Table of Contents
Triggering expansion
-+This section describes how YASnippet chooses snippets for expansion at point. +
- You can use YASnippet to expand snippets in different ways: +Maybe, you'll want some snippets to be expanded in a particular +mode, or only under certain conditions, or be prompted using
--
+
+
- When
yas-minor-modeis active: --
+
- Type the snippet's trigger key then calling
yas-expand(bound toTABby default). -
+
- Use the snippet's keybinding. - +
- By expanding directly from the "YASnippet" menu in the menu-bar - -
- Using hippie-expand +
- Using hippie-expand
+
- Type the snippet's trigger key then calling
- Call
yas-insert-snippet(useM-x yas-insert-snippet=or its - keybindingC-c & C-s). - +keybindingC-c & C-s).
+
- Use m2m's excellent auto-complete - TODO: example for this - +TODO: example for this +
- Expanding from emacs-lisp code
- 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… +These are loaded from a directory hierarchy in your file system. See +Organizing Snippets. They are named +after major modes likehtml-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 RETto find out which major - mode you are in currently. +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 RETto 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. +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-modeto - consider snippet tables whose name does not correspond to a major - mode. Typically, you call this from a minor mode hook, for example: -
+Use - Buffer-local
-
yas-buffer-local-condition- variable +yas-buffer-local-condition+variable- This variable provides finer grained control over what snippets can - be expanded in the current buffer. The default value won't let you - expand snippets inside comments or string literals for example. See - The condition system_ for more info. -
+This variable provides finer grained control over what snippets can
+be expanded in the current buffer. The default value won't let you
+expand snippets inside comments or string literals for example. See
+The condition system\_ for more info.
+
+
- It usually looks beautiful. E.g. when you compile Emacs with gtk - support, this menu will be rendered with your gtk theme. +support, this menu will be rendered with your gtk theme.
- Your window system may or may not allow to you use
C-n,C-pto - navigate this menu. +navigate this menu. - This function can't be used when in a terminal.
- The currently loaded snippet definitions, organized by major mode, - and optional grouping. - - -
- A rundown of the most common commands, (followed by their - keybindings) including commands to load directories and reload all - snippet definitions. - - -
- A series of submenus for customizing and exploring YASnippet - behavior. - -
- The currently loaded snippet definitions, organized by major mode, +and optional grouping. + + +
- A rundown of the most common commands, (followed by their +keybindings) including commands to load directories and reload all +snippet definitions. + + +
- A series of submenus for customizing and exploring YASnippet +behavior. + +
- Basic structure
- Setting up
yas-snippet-dirs - The
.yas-parentsfile
- - The
.yas-make-groupsfile
- - The
.yas-setup.elfile + - TODO The
.yas-make-groupsfile
+ - TODO The
.yas-setup.elfile -
- - The
.yas-compiled-snippet.elfile --
-
- +
- TODO
+ - The
.yas-compiled-snippet.elfile - The
.yas-skipfile-
-
- +
- TODO
- a personal collection that lives in
~/.emacs.d/snippets - the bundled collection, taken as a relative path to
yasnippet.ellocaltion yas-selected-text()yas-hippie-try-expand(first-time?)yas-global-mode-cmhh()
+yas-lookup-snippet(name&optionalmodenoerror)yas-throw(text)yas-inside-string()yas-x-prompt(promptchoices&optionaldisplay-fn)
@@ -225,6 +243,7 @@ for the JavaScript code in this tag.
yas-substr(strpattern&optionalsubexp)yas-unimplemented(&optionalmissing-feature)yas-expand-snippet(content&optionalstartendexpand-env)
+yas-minor-mode-set-explicitly()- Useful variables @@ -253,695 +272,661 @@ for the JavaScript code in this tag.
call-other-commandmeans try to temporarily disable YASnippet - and call the next command bound to whatever key was used to - invokeyas-expand. - +and call the next command bound to whatever key was used to +invokeyas-expand.
+
- nil or the symbol
return-nilmean do nothing. (and -yas-expandreturns nil) - +yas-expandreturns nil)
+
- A Lisp form (apply command . args) means interactively call - command, if args is non-nil, call command non-interactively - with args as arguments. +command. If args is non-nil, call command non-interactively +with args as arguments.
- prompt: A string to prompt the user - +
- choices: a list of strings or objects. - +
- optional display-fn : A function that, when applied to each of
- To signal that your particular style of prompting is
- To signal that the user quit the prompting process, you can
fixedIndent the snippet to the current column; +-
+
fixedIndent the snippet to the current column;
+
autoIndent each line of the snippet withindent-according-to-mode
Every other value means don't apply any snippet-side indentation after expansion (the manual per-line "$>" indentation still applies).
- If it evaluates to nil, no snippets can be expanded. - +
- If it evaluates to the a cons (require-snippet-condition
- . requirement)
+. requirement)
-
-
+
- Snippets bearing no "# condition:" directive are not - considered - +considered +
- Snippets bearing conditions that evaluate to nil (or - produce an error) won't be considered. - +produce an error) won't be considered. +
- If the snippet has a condition that evaluates to non-nil
- result:
+result:
-
-
+
- If requirement is t, the snippet is considered - +
- If requirement is
eqresult, the snippet is - considered - +considered
+
- Otherwise, the snippet is not considered. -
+
- If it evaluates to the symbol 'always, all snippets are - considered for expansion, regardless of any conditions. - +considered for expansion, regardless of any conditions. +
- If it evaluates to t or some other non-nil value
-
-
+
- Snippet bearing no conditions, or conditions that - evaluate to non-nil, are considered for expansion. - +evaluate to non-nil, are considered for expansion. +
- Otherwise, the snippet is not considered.
Triggering expansion
++You can use YASnippet to expand snippets in different ways: +
+ +Trigger key
yas-expand tries to expand a snippet abbrev (also known as
snippet key) before point.
When yas-minor-mode is enabled, it binds yas-expand to TAB and
<tab> by default, however, you can freely set it to some other key:
(define-key yas-minor-mode-map (kbd "<tab>") nil) +(define-key yas-minor-mode-map (kbd "<tab>") nil) (define-key yas-minor-mode-map (kbd "TAB") nil) (define-key yas-minor-mode-map (kbd "<the new key>") '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:
-
+
+
+
When you use yas-global-mode you can also selectively disable
YASnippet in some buffers by setting the buffer-local variable
yas-dont-active in the buffer's mode hook.
Fallback behaviour
yas-fallback-behaviour is a customization variable bound to
'call-other-command by default. If yas-expand failed to find any
suitable snippet to expand, it will disable the minor mode temporarily
and find if there's any other command bound to the same key.
If found, the command will be called. Usually this works very well -–when there's a snippet, expand it, otherwise, call whatever command +–when there's a snippet, expand it, otherwise, call whatever command originally bind to the trigger key.
+
However, you can change this behavior by customizing the
yas-fallback-behavior variable. If you set this variable to
@@ -284,63 +302,53 @@ However, you can change this behavior by customizing the
Insert at point
-The command yas-insert-snippet lets you insert snippets 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.
Snippet keybinding
See the section of the # binding: directive in
Writing Snippets.
Expanding from the menu
See the YASnippet Menu.
Expanding with hippie-expand
To integrate with hippie-expand, just put
yas-hippie-try-expand in
@@ -349,137 +357,130 @@ 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 you own
-elisp code. You should call
-yas-expand-snippet instead of
-yas-expand in this case.
+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. In fact, expanding from the
-YASnippet menu has the same effect of evaluating the follow code:
+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) +(yas-expand-snippet template)- +
-See the internal documentation on yas-expand-snippet for more
-information.
+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:
--
+
+
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 +;; 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))) + #'(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
@@ -489,154 +490,151 @@ snippets is just boring. So has a buffer local variable
yas-buffer-local-condition. You can set this variable to
(not (python-in-string/comment)) 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-in-string/comment) - '(require-snippet-condition . force-in-comment) - t)))) +(add-hook 'python-mode-hook + (lambda () + (setq yas-buffer-local-condition + '(if (python-in-string/comment) + '(require-snippet-condition . force-in-comment) + t))))- +
-… and specify the condition for a snippet that you're going to expand
+… and specify the condition for a snippet that you're going to expand
in comment to be evaluated to the symbol force-in-comment. Then it can
be expanded as you expected, while other snippets like if still can't
expanded in comment.
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 +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)) +(setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))- +
Currently there are some alternatives solution with YASnippet.
-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
means:
-
+
+
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
-
+
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 24.4.91.1 (Org mode 8.2.10) on from 7703a55ac416a131dec45fa6a1e0ec1e31adf760 +
+YASnippet menu
- - -
-When yas-minor-mode is active, YASnippet will setup a menu just after
-the "Buffers" menu in the menubar.
-
-In this menu, you can find -
--
-
-
-
Table of Contents
+When yas-minor-mode is active, YASnippet will setup a menu just after
+the "Buffers" menu in the menubar.
+
+In this menu, you can find +
+ +-
+
+
Loading snippets from menu
-Invoking "Load snippets…" from the menu invokes yas-load-directory
+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
+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
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 click on one of them, the default behavior is to expand it, unconditionally, inside the current buffer.
+
You can however, customize variable yas-visit-from-menu to be t
which will take you to the snippet definition file when you select it
from the menu.
If you want the menu show only snippet tables whose name corresponds to
a "real" major mode. You do this by setting yas-use-menu to
'real-modes.
Finally, to have the menu show only the tables for the currently active
mode, set yas-use-menu to abbreviate.
These customizations can also be found in the menu itself, under the "Snippet menu behavior" submenu.
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 .
+Writing snippets.
Prompting method
The "Prompting method" submenu contains options to control the value of
-yas-prompt-functions. See Expanding snippets .
+yas-prompt-functions. See Expanding snippets.
Misc
The "Misc" submenu contains options to control the values of more variables. -
Generated by Emacs 24.4.91.1 (Org mode 8.2.10) on from 7703a55ac416a131dec45fa6a1e0ec1e31adf760 +
+Organizing snippets
- - -Table of Contents
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 names. +Snippet collections can be stored in plain text files. They are arranged by +sub-directories naming snippet tables. These mostly name Emacs major names.
- - -. ++. |-- c-mode | `-- printf |-- java-mode @@ -185,81 +198,74 @@ for the JavaScript code in this tag. `-- time-- 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. +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
+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.
+
- 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.
+The default considers:
- The default considers: -
--
+
+
- When you come across other snippet collections, do the following to try them - out: +When you come across other snippet collections, do the following to try them +out:
+;; Develop in ~/emacs.d/mysnippets, but also
+;; Develop in ~/emacs.d/mysnippets, but also
;; try out snippets in ~/Downloads/interesting-snippets
(setq yas-snippet-dirs '("~/emacs.d/mysnippets"
- "~/Downloads/interesting-snippets"))
+ "~/Downloads/interesting-snippets"))
;; OR, keeping YASnippet defaults try out ~/Downloads/interesting-snippets
(setq yas-snippet-dirs (append yas-snippet-dirs
- '("~/Downloads/interesting-snippets")))
+ '("~/Downloads/interesting-snippets")))
-
+
- Collections appearing earlier in the list shadow snippets with same names
- appearing in collections later in the list. yas-new-snippet always stores
- snippets in the first collection.
+Collections appearing earlier in the list override snippets with same names
+appearing in collections later in the list. yas-new-snippet always stores
+snippets in the first collection.
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.
+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
@@ -273,35 +279,33 @@ for the JavaScript code in this tag.
|-- email
`-- time
-
-
-
+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.
+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:
+
$ tree ruby-mode/ ++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 @@ -316,73 +320,57 @@ ruby-mode/ `-- ...-- Yet another way to create a nice snippet menu is to write into -
.yas-make-groupsa menu definition. TODO +Yet another way to create a nice snippet menu is to write into +.yas-make-groupsa menu definition. TODO
TODO The .yas-setup.el file
TODO
-TODO
TODO The .yas-compiled-snippet.el file
+The .yas-compiled-snippet.el file
TODO
-TODO The .yas-skip file
-TODO
-Generated by Org version 7.9.3f with Emacs version 24 on 2014-10-01T21:16+0100 from 08b044e559cc350c6e7142d088ec2d4a82e378cb +
+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
+
+A .yas-skip file in a mode's snippet subdirectory tells YASnippet
+not to load snippets from there.
+
TODO
+Generated by Emacs 24.4.91.1 (Org mode 8.2.10) on from 7703a55ac416a131dec45fa6a1e0ec1e31adf760 +
+Reference
- - - - - -Table of Contents
Interactive functions
yas-abort-snippet (&optional snippet)
/warning/: no doc for symbol yas-abort-snippet
+
+warning: no doc for symbol yas-abort-snippet
yas-visit-snippet-file ()
+yas-visit-snippet-file ()
Choose a snippet to edit, selection like yas-insert-snippet.
+
+Choose a snippet to edit, selection like yas-insert-snippet.
Only success if selected snippet was loaded from a file. Put the
visited file in snippet-mode.
yas-load-snippet-buffer (table &optional interactive)
+yas-load-snippet-buffer (table &optional interactive)
Parse and load current buffer's snippet definition into table.
+
+Parse and load current buffer's snippet definition into table.
table is a symbol naming a passed to yas--table-get-create.
When called interactively, prompt for the table name.
yas-global-mode (&optional arg)
+yas-global-mode (&optional arg)
Toggle Yas minor mode in all buffers. +
+Toggle Yas minor mode in all buffers.
With prefix arg, enable Yas-Global mode if arg is positive;
otherwise, disable it. If called from Lisp, enable the mode if
arg is omitted or nil.
Yas minor mode is enabled in all buffers where
yas-minor-mode-on would do it.
See yas-minor-mode for more information on Yas minor mode.
yas-skip-and-clear-or-delete-char (&optional field)
+yas-skip-and-clear-or-delete-char (&optional field)
Clears unmodified field if at field start, skips to next tab. +
+Clears unmodified field if at field start, skips to next tab.
+
Otherwise deletes a character normally by calling delete-char.
yas-next-field (&optional arg)
+yas-next-field (&optional arg)
Navigate to the argth next field.
+
+Navigate to the argth next field.
If there's none, exit the snippet.
yas-insert-snippet (&optional no-condition)
+yas-insert-snippet (&optional no-condition)
Choose a snippet to expand, pop-up a list of choices according +
+Choose a snippet to expand, pop-up a list of choices according
to yas-prompt-functions.
With prefix argument no-condition, bypass filtering of snippets
by condition.
yas-activate-extra-mode (mode)
+yas-activate-extra-mode (mode)
Activates the snippets for the given mode in the buffer.
+
+Activates the snippets for the given mode in the buffer.
The function can be called in the hook of a minor mode to activate snippets associated with that mode.
yas-recompile-all ()
+yas-recompile-all ()
Compile every dir in yas-snippet-dirs.
+
+Compile every dir in yas-snippet-dirs.
yas-compile-directory (top-level-dir)
+yas-compile-directory (top-level-dir)
Create .yas-compiled-snippets.el files under subdirs of top-level-dir.
+
+Create .yas-compiled-snippets.el files under subdirs of top-level-dir.
This works by stubbing a few functions, then calling
yas-load-directory.
yas-direct-keymaps-reload ()
+yas-direct-keymaps-reload ()
Force reload the direct keybinding for active snippet tables. +
+Force reload the direct keybinding for active snippet tables.
yas-tryout-snippet (&optional debug)
+yas-tryout-snippet (&optional debug)
Test current buffer's snippet template in other buffer. +
+Test current buffer's snippet template in other buffer.
yas-exit-snippet (snippet)
+yas-exit-snippet (snippet)
Goto exit-marker of snippet.
+
+Goto exit-marker of snippet.
yas-expand (&optional field)
+yas-expand (&optional field)
Expand a snippet before point. If no snippet +
+Expand a snippet before point. If no snippet
expansion is possible, defer to yas-fallback-behavior (which see).
Optional argument field is for non-interactive use and is an
object satisfying yas--field-p to restrict the expansion to.
yas-minor-mode (&optional arg)
+yas-minor-mode (&optional arg)
Toggle YASnippet mode. +
+Toggle YASnippet mode.
+
When YASnippet mode is enabled, yas-expand, normally bound to
the tab key, expands snippets of code depending on the major
mode.
With no argument, this command toggles the mode. positive prefix argument turns on the mode. Negative prefix argument turns off the mode.
+Key bindings: \{yas-minor-mode-map}
yas-minor-mode-on ()
+yas-minor-mode-on ()
Turn on YASnippet minor mode. +
+Turn on YASnippet minor mode.
+
Honour yas-dont-activate, which see.
yas-reload-all (&optional no-jit interactive)
+yas-reload-all (&optional no-jit interactive)
Reload all snippets and rebuild the YASnippet menu. +
+Reload all snippets and rebuild the YASnippet menu.
+
When no-jit is non-nil force immediate reload of all known
snippets under yas-snippet-dirs, otherwise use just-in-time
loading.
When called interactively, use just-in-time loading when given a prefix argument.
yas-load-directory (top-level-dir &optional use-jit interactive)
+yas-load-directory (top-level-dir &optional use-jit interactive)
Load snippets in directory hierarchy top-level-dir.
+
+Load snippets in directory hierarchy top-level-dir.
Below top-level-dir each directory should be a mode name.
With prefix argument use-jit do jit-loading of snippets.
yas-new-snippet (&optional no-template)
+yas-new-snippet (&optional no-template)
Pops a new buffer for writing a snippet. +
+Pops a new buffer for writing a snippet.
+
Expands a snippet-writing snippet, unless the optional prefix arg
no-template is non-nil.
yas-load-snippet-buffer-and-close (table &optional kill)
+yas-load-snippet-buffer-and-close (table &optional kill)
Load the snippet with yas-load-snippet-buffer, possibly
+
+Load the snippet with yas-load-snippet-buffer, possibly
save, then quit-window if saved.
If the snippet is new, ask the user whether (and where) to save it. If the snippet already has a file, just save it.
+
The prefix argument kill is passed to quit-window.
Don't use this from a Lisp program, call yas-load-snippet-buffer
and kill-buffer instead.
yas-describe-tables (&optional choose)
+yas-describe-tables (&optional choose)
Display snippets for each table. +
+Display snippets for each table.
yas-deactivate-extra-mode (mode)
+yas-deactivate-extra-mode (mode)
Deactivates the snippets for the given mode in the buffer.
+
+Deactivates the snippets for the given mode in the buffer.
yas-next-field-or-maybe-expand ()
+yas-next-field-or-maybe-expand ()
Try to expand a snippet at a key before point. +
+Try to expand a snippet at a key before point.
+
Otherwise delegate to yas-next-field.
yas-about ()
+yas-about ()
/warning/: no doc for symbol yas-about
+
+warning: no doc for symbol yas-about
yas-prev-field ()
+yas-prev-field ()
Navigate to prev field. If there's none, exit the snippet. +
+Navigate to prev field. If there's none, exit the snippet.
yas-expand-from-trigger-key (&optional field)
+yas-expand-from-trigger-key (&optional field)
Expand a snippet before point. +
+Expand a snippet before point.
+
If no snippet expansion is possible, fall back to the behaviour
defined in yas-fallback-behavior.
Optional argument field is for non-interactive use and is an
object satisfying yas--field-p to restrict the expansion to.
-
Customization variables
yas-choose-tables-first
If non-nil, and multiple eligible snippet tables, prompts user for tables first.
+Otherwise, user chooses between the merging together of all eligible tables.
+
This affects yas-insert-snippet, yas-visit-snippet-file
yas-snippet-revival
+yas-snippet-revival
Non-nil means re-activate snippet fields after undo/redo.
yas-also-auto-indent-first-line
+yas-also-auto-indent-first-line
Non-nil means also auto indent first line according to mode.
+
Naturally this is only valid when yas-indent-line is auto
yas-new-snippet-default
+yas-new-snippet-default
Default snippet to use when creating a new snippet. If nil, don't use any snippet.
yas-choose-keys-first
+yas-choose-keys-first
If non-nil, prompt for snippet key first, then for template.
+Otherwise prompts for all possible snippet names.
+
This affects yas-insert-snippet and yas-visit-snippet-file.
yas-fallback-behavior
+yas-fallback-behavior
How to act when yas-expand does not expand a snippet.
-
+
+
yas-wrap-around-region
+yas-wrap-around-region
If non-nil, snippet expansion wraps around selected region.
+The wrapping occurs just before the snippet's exit marker. This can be overridden on a per-snippet basis.
yas-prompt-functions
+yas-prompt-functions
Functions to prompt for keys, templates, etc interactively.
+These functions are called with the following arguments:
--
+
+
the objects in choices will return a string. +
+the objects in choices will return a string.
+The return value of any function you put here should be one of the objects in choices, properly formatted with display-fn (if that is passed).
--
+
+
unavailable at the moment, you can also have the function return +
+unavailable at the moment, you can also have the function return nil.
--
+
+
signal quit with
-
- (signal 'quit "user quit!").
+signal quit with
+
+(signal 'quit "user quit!").
yas-triggers-in-field
+yas-triggers-in-field
If non-nil, allow stacked expansions (snippets inside snippets).
+
Otherwise yas-next-field-or-maybe-expand just moves on to the
next field
yas-trigger-symbol
+yas-trigger-symbol
The text that will be used in menu to represent the trigger.
yas-indent-line
+yas-indent-line
Controls indenting applied to a recent snippet expansion.
+The following values are possible:
--
-
yas-expand-only-for-last-commands
+yas-expand-only-for-last-commands
List of last-command values to restrict tab-triggering to, or nil.
Leave this set at nil (the default) to be able to trigger an expansion simply by placing the cursor after a valid tab trigger, using whichever commands.
+Optionally, set this to something like '(self-insert-command) if you to wish restrict expansion to only happen when the last @@ -949,507 +934,506 @@ letter of the snippet tab trigger was typed immediately before the trigger key itself.
yas-snippet-dirs ()
+yas-snippet-dirs ()
Return variable yas-snippet-dirs as list of strings.
+
+Return variable yas-snippet-dirs as list of strings.
Useful functions
-Useful functions
+yas-completing-prompt (prompt choices &optional display-fn completion-fn)
+yas-completing-prompt (prompt choices &optional display-fn completion-fn)
/warning/: no doc for symbol yas-completing-prompt
+
+warning: no doc for symbol yas-completing-prompt
yas-selected-text ()
+yas-selected-text ()
Return yas-selected-text if that exists and is non-empty, else nil.
+
+Return yas-selected-text if that exists and is non-empty, else nil.
yas-hippie-try-expand (first-time?)
+yas-hippie-try-expand (first-time?)
Integrate with hippie expand. +
+Integrate with hippie expand.
+
Just put this function in hippie-expand-try-functions-list.
yas-global-mode-cmhh ()
+yas-global-mode-cmhh ()
/warning/: no doc for symbol yas-global-mode-cmhh
+
+warning: no doc for symbol yas-global-mode-cmhh
yas-lookup-snippet (name &optional mode noerror)
+
+Get the snippet content for the snippet name in mode's tables.
+
+mode defaults to the current buffer's major-mode. If noerror
+is non-nil, then don't signal an error if there isn't any snippet
+called name.
+
+Honours yas-buffer-local-condition.
+
yas-throw (text)
+yas-throw (text)
Throw a yas–exception with text as the reason.
+
+Throw a yas–exception with text as the reason.
yas-inside-string ()
+yas-inside-string ()
Return non-nil if the point is inside a string according to font-lock. +
+Return non-nil if the point is inside a string according to font-lock.
yas-x-prompt (prompt choices &optional display-fn)
+yas-x-prompt (prompt choices &optional display-fn)
Display choices in a x-window prompt. +
+Display choices in a x-window prompt.
yas-shortest-key-until-whitespace (_start-point)
+yas-shortest-key-until-whitespace (_start-point)
Like yas-longest-key-from-whitespace but take the shortest key.
+
+Like yas-longest-key-from-whitespace but take the shortest key.
yas-longest-key-from-whitespace (start-point)
+yas-longest-key-from-whitespace (start-point)
As yas-key-syntaxes element, look for longest key between point and whitespace.
+
+As yas-key-syntaxes element, look for longest key between point and whitespace.
A newline will be considered whitespace even if the mode syntax marks it as something else (typically comment ender).
yas-ido-prompt (prompt choices &optional display-fn)
+yas-ido-prompt (prompt choices &optional display-fn)
/warning/: no doc for symbol yas-ido-prompt
+
+warning: no doc for symbol yas-ido-prompt
yas-try-key-from-whitespace (_start-point)
+yas-try-key-from-whitespace (_start-point)
As yas-key-syntaxes element, look for whitespace delimited key.
+
+As yas-key-syntaxes element, look for whitespace delimited key.
A newline will be considered whitespace even if the mode syntax marks it as something else (typically comment ender).
yas-dropdown-prompt (_prompt choices &optional display-fn)
+yas-dropdown-prompt (_prompt choices &optional display-fn)
/warning/: no doc for symbol yas-dropdown-prompt
+
+warning: no doc for symbol yas-dropdown-prompt
yas-define-snippets (mode snippets)
+yas-define-snippets (mode snippets)
Define snippets for mode.
+
+Define snippets for mode.
snippets is a list of snippet definitions, each taking the
following form
- (key template name condition group expand-env file keybinding uuid) +(key template name condition group expand-env load-file keybinding uuid save-file)
+Within these, only key and template are actually mandatory.
+template might be a Lisp form or a string, depending on whether this is a snippet or a snippet-command.
+
condition, expand-env and keybinding are Lisp forms, they have
been yas--read-lisp-ed and will eventually be
yas--eval-lisp-ed.
The remaining elements are strings.
+file is probably of very little use if you're programatically defining snippets.
+uuid is the snippet's "unique-id". Loading a second snippet file with the same uuid would replace the previous snippet.
+
You can use yas--parse-template to return such lists based on
the current buffers contents.
yas-global-mode-enable-in-buffers ()
+yas-global-mode-enable-in-buffers ()
/warning/: no doc for symbol yas-global-mode-enable-in-buffers
+
+warning: no doc for symbol yas-global-mode-enable-in-buffers
yas-no-prompt (_prompt choices &optional _display-fn)
+yas-no-prompt (_prompt choices &optional _display-fn)
/warning/: no doc for symbol yas-no-prompt
+
+warning: no doc for symbol yas-no-prompt
yas-active-keys ()
+yas-active-keys ()
Return all active trigger keys for current buffer and point. +
+Return all active trigger keys for current buffer and point.
yas-define-condition-cache (func doc &rest body)
+yas-define-condition-cache (func doc &rest body)
Define a function func with doc doc and body body.
+
+Define a function func with doc doc and body body.
body is executed at most once every snippet expansion attempt, to check
expansion conditions.
It doesn't make any sense to call func programatically.
yas-global-mode-check-buffers ()
+yas-global-mode-check-buffers ()
/warning/: no doc for symbol yas-global-mode-check-buffers
+
+warning: no doc for symbol yas-global-mode-check-buffers
yas-field-value (number)
+yas-field-value (number)
Get the string for field with number.
+
+Get the string for field with number.
Use this in primary and mirror transformations to tget.
yas-verify-value (possibilities)
+yas-verify-value (possibilities)
Verify that the current field value is in possibilities.
+
+Verify that the current field value is in possibilities.
Otherwise throw exception.
yas-key-to-value (alist)
+yas-key-to-value (alist)
/warning/: no doc for symbol yas-key-to-value
+
+warning: no doc for symbol yas-key-to-value
yas-choose-value (&rest possibilities)
+yas-choose-value (&rest possibilities)
Prompt for a string in possibilities and return it.
+
+Prompt for a string in possibilities and return it.
The last element of possibilities may be a list of strings.
yas-substr (str pattern &optional subexp)
+yas-substr (str pattern &optional subexp)
Search pattern in str and return subexpth match.
+
+Search pattern in str and return subexpth match.
If found, the content of subexp group subexp (default 0) is
returned, or else the original str will be returned.
yas-unimplemented (&optional missing-feature)
+yas-unimplemented (&optional missing-feature)
/warning/: no doc for symbol yas-unimplemented
+
+warning: no doc for symbol yas-unimplemented
yas-expand-snippet (content &optional start end expand-env)
+yas-expand-snippet (content &optional start end expand-env)
Expand snippet content at current point.
+
+Expand snippet content at current point.
Text between start and end will be deleted before inserting
-template. expand-env is are let-style variable to value bindings
+template. expand-env is a list of (sym value) let-style dynamic bindings
considered when expanding the snippet.
-
Useful variables
-Useful variables
+yas-after-exit-snippet-hook
+yas-after-exit-snippet-hook
Hooks to run after a snippet exited.
+The hooks will be run in an environment where some variables bound to proper values:
+
yas-snippet-beg : The beginning of the region of the snippet.
yas-snippet-end : Similar to beg.
Attention: These hooks are not run when exiting nested/stacked snippet expansion!
yas-global-mode-hook
+yas-global-mode-hook
-/warning/: no doc for symbol yas-global-mode-hook
+Hook run after entering or leaving yas-global-mode.
+No problems result if this variable is not bound.
+add-hook automatically binds it. (This is true for all hook variables.)
yas-dont-activate
+yas-dont-activate
If non-nil don't let yas-global-mode affect some buffers.
If a function of zero arguments, then its result is used.
+If a list of functions, then all functions must return nil to activate yas for this buffer.
+
In Emacsen <= 23, this variable is buffer-local. Because
yas-minor-mode-on is called by yas-global-mode after
@@ -1457,6 +1441,7 @@ executing the buffer's major mode hook, setting this variable
there is an effective way to define exceptions to the "global"
activation behaviour.
In Emacsen > 23, only the global value is used. To define per-mode exceptions to the "global" activation behaviour, call @@ -1464,114 +1449,105 @@ per-mode exceptions to the "global" activation behaviour, call mode's hook.
yas-buffer-local-condition
+yas-buffer-local-condition
Snippet expanding condition.
+This variable is a Lisp form which is evaluated every time a snippet expansion is attempted:
--
+
+
Here's an example preventing snippets from being expanded from
inside comments, in python-mode only, with the exception of
snippets returning the symbol 'force-in-comment in their
conditions.
- (add-hook 'python-mode-hook - '(lambda () - (setq yas-buffer-local-condition - '(if (python-in-string/comment) - '(require-snippet-condition . force-in-comment) - t)))) +(add-hook 'python-mode-hook + '(lambda () + (setq yas-buffer-local-condition + '(if (python-in-string/comment) + '(require-snippet-condition . force-in-comment) + t))))
+
The default value is similar, it filters out potential snippet
expansions inside comments and string literals, unless the
@@ -1579,57 +1555,47 @@ snippet itself contains a condition that returns the symbol
force-in-comment.
yas-before-expand-snippet-hook
+yas-before-expand-snippet-hook
Hooks to run just before expanding a snippet.
yas-key-syntaxes
+yas-key-syntaxes
Syntaxes and functions to help look for trigger keys before point.
+Each element in this list specifies how to skip buffer positions backwards and look for the start of a trigger key.
+
Each element can be either a string or a function receiving the
original point as an argument. A string element is simply passed
@@ -1637,17 +1603,20 @@ to skip-syntax-backward whereas a function element is called
with no arguments and should also place point before the original
position.
The string between the resulting buffer position and the original point is matched against the trigger keys in the active snippet tables.
+
If no expandable snippets are found, the next element is the list
is tried, unless a function element returned the symbol again,
in which case it is called again from the previous position and
may once more reposition point.
For example, if yas-key-syntaxes' value is '("w" "w_"),
trigger keys composed exclusively of "word"-syntax characters
@@ -1655,9 +1624,11 @@ are looked for first. Failing that, longer keys composed of
"word" or "symbol" syntax are looked for. Therefore,
triggering after
foo-bar
+
will, according to the "w" element first try "barbaz". If
that isn't a trigger key, "foo-barbaz" is tried, respecting the
@@ -1666,79 +1637,65 @@ key for an active snippet, it won't be expanded, unless a
function is added to yas-key-syntaxes that eventually places
point between "bar" and "baz".
See also Info node `(elisp) Syntax Descriptors'.
yas-minor-mode-hook
+yas-minor-mode-hook
-Hook run when yas-minor-mode is turned on.
+Hook run after entering or leaving yas-minor-mode.
+No problems result if this variable is not bound.
+add-hook automatically binds it. (This is true for all hook variables.)
yas-verbosity
+yas-verbosity
Log level for yas--message 4 means trace most anything, 0 means nothing.