# Intro
-**yasnippet** is a template system for Emacs. It allows you to type an
+**YASnippet** is a template system for Emacs. It allows you to type an
abbreviation and automatically expand it into function
templates. Bundled language templates includes: C, C++, C#, Perl,
Python, Ruby,
SQL, LaTeX, HTML, CSS and more. The snippet syntax is inspired from
[TextMate's][textmate-snippets] syntax, you can even
-[import][import-docs] most TextMate templates to yasnippet. Watch
+[import][import-docs] most TextMate templates to YASnippet. Watch
[a demo on YouTube][youtube-demo] or download a
[higher resolution version][high-res-demo]
(add-to-list 'load-path
"~/.emacs.d/plugins/yasnippet")
(require 'yasnippet)
- (yas/global-mode 1)
-
-Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas/new-snippet`.
+ (yas-global-mode 1)
+Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`.
## Install with `package-install`
-In a recent emacs `M-x list-packages` is the recommended way to list and install packages.
-[MELPA][melpa] keeps a very recent snapshot of yasnippet, see http://melpa.milkbox.net/#installing.
+In a recent emacs `M-x list-packages` is the recommended way to list and install packages.
+[MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing.
## Install with el-get
:compile "yasnippet.el")
el-get-sources)
-## Use `yas/minor-mode` on a per-buffer basis
+## Use `yas-minor-mode` on a per-buffer basis
-To use yasnippet as a non-global minor mode, replace `(yas/global-mode 1)` with
-`(yas/reload-all)` to load the snippet tables. Then add a call to
-`(yas/minor-mode)` to the major-modes where you to enable yasnippet.
+To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
+`(yas-reload-all)` to load the snippet tables. Then add a call to
+`(yas-minor-mode)` to the major-modes where you to enable YASnippet.
(add-hook 'prog-mode-hook
'(lambda ()
- (yas/minor-mode)))
+ (yas-minor-mode)))
# (NOT) Contributing snippets
Please **do not** open pull requests or ask me to add snippets to
-yasnippet.
+YASnippet.
The bundled collection under `/snippets` is considered frozen: **I
will not add more snippets to it**.
-You can point `yas/snippet-dirs` to good snippet collections out
+You can point `yas-snippet-dirs` to good snippet collections out
there. If you have created snippets for a mode, or multiple modes,
consider creating a repository to host them, then tell users that it
-should be added like this to `yas/snippet-dirs`:
+should be added like this to `yas-snippet-dirs`:
- (setq yas/snippet-dirs
+ (setq yas-snippet-dirs
'("~/.emacs.d/snippets" ;; personal snippets
"/path/to/some/collection/" ;; just some foo-mode snippets
"/path/to/some/othercollection/" ;; some more foo-mode and a complete baz-mode
"/path/to/yasnippet/snippets" ;; the default collection
))
- (yas/global-mode 1) ;; or M-x yas/reload-all if you've started yasnippet already.
+ (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
# Importing TextMate snippets
(add-to-list 'load-path
"~/.emacs.d/plugins/yasnippet")
(require 'yasnippet)
- (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported"))
- (yas/global-mode 1)
+ (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported"))
+ (yas-global-mode 1)
Open some rails file (model, app, etc) and start using the textmate
snippets. Note that in the example above we have abandoned the
[the GitHub issue tracker][issues]. (please **do not** submit new issues to the old
[googlecode tracker][googlecode tracker])
-If you run into problems using yasnippet, or have snippets to contribute, post
-to the [yasnippet google group][forum]. Thank you very much for using yasnippet!
+If you run into problems using YASnippet, or have snippets to contribute, post
+to the [YASnippet google group][forum]. Thank you very much for using YASnippet!
[docs]: http://capitaomorte.github.com/yasnippet/
[issues]: https://github.com/capitaomorte/yasnippet/issues
* Much more powerful menu. See `The YASnippet menu`_.
* New ways to organize snippets. See `Organizing snippets`_.
-* Added ``yas/also-auto-indent-first-line`` customization variable.
+* Added ``yas-also-auto-indent-first-line`` customization variable.
* Renamed directive ``# env:`` to ``# expand-env:``
* Rewrote much of the documentation.
* Added TextMate import tool ``textmate-import.rb`` to to svn
* Fixed `Issue 68
<http://code.google.com/p/yasnippet/issues/detail?id=68>`_ with
mouse-clicking alternatives in ``ido-mode``.
-* Added ``yas/also-auto-indent-first-line`` customization variable.
+* Added ``yas-also-auto-indent-first-line`` customization variable.
0.6.0b / 2009-07-25
* Transformation on a primary field with syntax ``${1:default$(transform)}``
-* Validations on field exit through the ``yas/verify-value``
+* Validations on field exit through the ``yas-verify-value``
primary field transformation.
* Wrapping the region in the exit marker ``$0`` of the snippet. Use
- ``yas/wrap-around-region``.
+ ``yas-wrap-around-region``.
-* Auto-indentation. Use ``yas/indent-line`` set to ``'auto``
+* Auto-indentation. Use ``yas-indent-line`` set to ``'auto``
-* Easier definition of snippets. Use ``yas/find-snippets`` or
- ``yas/visit-snippet-file``. In the new ``snippet-mode`` use
- ``yas/load-snippet-buffer`` and ``yas/tryout-snippet``.
+* Easier definition of snippets. Use ``yas-find-snippets`` or
+ ``yas-visit-snippet-file``. In the new ``snippet-mode`` use
+ ``yas-load-snippet-buffer`` and ``yas-tryout-snippet``.
* Customization group ``yasnippet``.
46 <http://code.google.com/p/yasnippet/issues/detail?id=46>`_).
* Fixed `Issue 45
<http://code.google.com/p/yasnippet/issues/detail?id=45>`_ by
- providing a proper default value for ``yas/buffer-local-condition``.
-* Added helper function ``yas/substr`` for convenient mirror
+ providing a proper default value for ``yas-buffer-local-condition``.
+* Added helper function ``yas-substr`` for convenient mirror
transformation.
-* Make variable ``yas/registered-snippet`` properly initialized.
+* Make variable ``yas-registered-snippet`` properly initialized.
* Fixed the overlay error when overlay becomes empty (`Issue 49
<http://code.google.com/p/yasnippet/issues/detail?id=49>`_ and
`Issue 48
0.5.6 / 2008-08-07
==================
-* Added a buffer local variable ``yas/dont-activate`` to turn off
- ``yas/minor-mode`` in some major modes. See `Issue 29
+* Added a buffer local variable ``yas-dont-activate`` to turn off
+ ``yas-minor-mode`` in some major modes. See `Issue 29
<http://code.google.com/p/yasnippet/issues/detail?id=29>`_.
* Make the environment of elisp evaluation more friendly to
``(current-column)``.
0.5.5 / 2008-05-29
==================
-* Tweak ``yas/extra-mode-hooks`` so that it can be more easily
+* Tweak ``yas-extra-mode-hooks`` so that it can be more easily
customized.
* Add an entry in FAQ about why ``TAB`` key doesn't work in some
modes.
==================
* Added ``ox-mode-hook`` and ``python-mode-hook`` to
- ``yas/extra-mode-hooks`` to fix the problem YASnippet is not enabled
+ ``yas-extra-mode-hooks`` to fix the problem YASnippet is not enabled
in those modes.
0.5.3 / 2008-05-07
0.5.0 / 2008-04-10
==================
-* Integrate with hippie-expand. Just add ``yas/hippie-try-expand`` to
+* Integrate with hippie-expand. Just add ``yas-hippie-try-expand`` to
``hippie-expand-try-functions-list``.
-* If you set ``yas/fall-back-behavior`` to ``'return-nil``, YASnippet
+* If you set ``yas-fall-back-behavior`` to ``'return-nil``, YASnippet
will return nil when it can't find a snippet to expand.
* Defect fix: the condition of a snippet was evaluated twice in
earlier version.
0.4.3 / 2008-03-23
==================
-* Bug fix: failed to recognize user customized yas/trigger-key.
+* Bug fix: failed to recognize user customized yas-trigger-key.
0.4.2 / 2008-03-22
==================
0.4.1 / 2008-03-21
==================
-* Make sure ``yas/minor-mode``'s key bindings always take priority to
+* Make sure ``yas-minor-mode``'s key bindings always take priority to
other minor modes.
0.4.0 / 2008-03-20
* Incorporate ``dropdown-list.el`` and make it default way for
selecting multiple candidates. Thanks to `Jaeyoun Chung
<http://groups.google.com/group/smart-snippet/browse_thread/thread/c869158b76addeb3/e7c6372ba457189e>`_.
-* yas/before-expand-snippet-hook
+* yas-before-expand-snippet-hook
0.3.2 / 2008-03-19
==================
0.3.0 / 2008-03-16
==================
-* Add a ``yas/after-exit-snippet-hook`` so that you can do something like
+* Add a ``yas-after-exit-snippet-hook`` so that you can do something like
``indent-region`` or ``fill-region`` after finish the snippet.
* Use minor-mode instead of ``global-set-key`` to bind the trigger
key. Now the trigger key and fall-back behavior can be more
=================================
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
+``M-x yas-minor-mode`` to manually turn on the minor mode and try to
expand the snippet again. If it works, then, you can add the following
code to your ``.emacs`` *before* loading YASnippet:
.. sourcecode:: lisp
- (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``
+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
+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
+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.
command ...``. Alternatively, you might see ``<tab> runs the command
...``, note the difference between ``TAB`` and ``<tab>`` where the
latter has priority. If you see ``<tab>`` bound to a command other
-than ``yas/expand``, (e.g. in ``org-mode``) you can try the following
+than ``yas-expand``, (e.g. in ``org-mode``) you can try the following
code to work around:
.. sourcecode:: lisp
(add-hook 'org-mode-hook
(let ((original-command (lookup-key org-mode-map [tab])))
`(lambda ()
- (setq yas/fallback-behavior
+ (setq yas-fallback-behavior
'(apply ,original-command))
- (local-set-key [tab] 'yas/expand))))
+ (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
.. sourcecode:: lisp
- (defun yas/advise-indent-function (function-symbol)
- (eval `(defadvice ,function-symbol (around yas/try-expand-first activate)
+ (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))
+ (let ((yas-fallback-behavior nil))
(unless (and (interactive-p)
- (yas/expand))
+ (yas-expand))
ad-do-it)))))
- (yas/advise-indent-function 'ruby-indent-line)
+ (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``.
+``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
+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 <http://groups.google.com/group/smart-snippet>`_. See this
particular `thread
(add-hook 'flyspell-incorrect-hook
#'(lambda (dummy1 dummy2 dymmy3)
- (and yas/active-field-overlay
- (overlay-buffer yas/active-field-overlay))))
+ (and yas-active-field-overlay
+ (overlay-buffer yas-active-field-overlay))))
This is apparently related to overlay priorities. For some reason, the
``keymap`` property of flyspell's overlays always takes priority over
======================================================
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:
+variable ``yas-dont-activate`` to a lambda function like so:
.. sourcecode:: lisp
- (set-default 'yas/dont-activate
+ (set-default 'yas-dont-activate
#'(lambda ()
- (and yas/root-directory
- (null (yas/get-snippet-tables)))))
+ (and yas-root-directory
+ (null (yas-get-snippet-tables)))))
This is also the default value starting for that version. It skips the
minor mode in buffers where it is not applicable (no snippet tables),
-but only once you have setup your yas/root-directory.
+but only once you have setup your yas-root-directory.
How do I define an abbrev key containing characters not supported by the filesystem?
(add-to-list 'load-path
"~/.emacs.d/plugins/yasnippet-x.y.z")
(require 'yasnippet) ;; not yasnippet-bundle
- (yas/initialize)
- (yas/load-directory "~/.emacs.d/plugins/yasnippet-x.y.z/snippets")
+ (yas-initialize)
+ (yas-load-directory "~/.emacs.d/plugins/yasnippet-x.y.z/snippets")
Please refer to the documentation for full customization, or use the
customization group.
There are some ways you can quickly find a snippet file:
-* ``M-x yas/new-snippet``
+* ``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-mode``
so you can write your snippet.
-* ``M-x yas/find-snippets``
+* ``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 to ``M-x yas/new-snippet``.
+ directory searching logic is similar to ``M-x yas-new-snippet``.
-* ``M-x yas/visit-snippet-file``
+* ``M-x yas-visit-snippet-file``
Prompts you for possible snippet expansions like
- ``yas/insert-snippet``, but instead of expanding it, takes you
+ ``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)
Two commands are defined in this mode:
-* ``M-x yas/load-snippet-buffer``
+* ``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-c`` by default while in
``snippet-mode``.
-* ``M-x yas/tryout-snippet``
+* ``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
--------------------------
This is the probably the most important directive, it's the abbreviation you
-type to expand a snippet just before hitting ``yas/trigger-key``. If you don't
+type to expand a snippet just before hitting ``yas-trigger-key``. If you don't
specify this the snippet will not be expandable through the key mechanism.
``# name:`` snippet name
will only be expanded when the condition code evaluate to some non-nil
value.
-See also ``yas/buffer-local-condition`` in `Expanding snippets`_
+See also ``yas-buffer-local-condition`` in `Expanding snippets`_
``# group:`` snippet menu grouping
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`_).
+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
+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 brilliant piece of ASCII art these values would mess up
your hard work. You can then use:
.. sourcecode:: text
# name: ASCII home
- # expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil))
+ # expand-env: ((yas-indent-line 'fixed) (yas-wrap-around-region 'nil))
# --
welcome to my
X humble
keymap named after the major mode the snippet is active
for.
-Additionally a variable ``yas/prefix`` is set to to the prefix
+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>
# binding: C-c C-c C-m
# --
- <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
+ <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 paragraph tag newlines, just
#endif /* $1 */
From version 0.6, snippets expansions are run with some special
-Emacs-lisp variables bound. One of this is ``yas/selected-text``. You
+Emacs-lisp variables bound. One of this is ``yas-selected-text``. You
can therefore define a snippet like:
.. sourcecode:: text
for ($1;$2;$3) {
- `yas/selected-text`$0
+ `yas-selected-text`$0
}
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.
+``yas-wrap-around-region`` to ``t`` which will do this automatically.
Tab stop fields
---------------
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 ``text`` (or ``yas/text``) is bound
+an environment where the variable ``text`` (or ``yas-text``) is bound
to the text content (string) contained in the field ``n``.Here's an
example for Objective-C:
.. sourcecode:: text
- #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
.. sourcecode:: text
- #define "${1:$$(upcase yas/text)}"
+ #define "${1:$$(upcase yas-text)}"
Please note that as soon as a transformation takes place, it changes
the value of the field and sets it its internal modification state to
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
+``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 ``yas/choose-value`` does this work for you. For example:
+The ``yas-choose-value`` does this work for you. For example:
.. sourcecode:: text
- <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
+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``
+you enter snippet field 2. This one makes use of ``yas-modified-p``
directly.
.. sourcecode:: text
\section{${1:"Titel der Tour"}}%
\index{$1}%
- \label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-
+ \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
+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
<http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662>`_
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`` (which executes ``yas/skip-and-clear-or-delete-char``) and go
+``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
Customizable variables
======================
-``yas/trigger-key``
+``yas-trigger-key``
-------------------
-The key bound to ``yas/expand`` when function ``yas/minor-mode`` is
+The key bound to ``yas-expand`` when function ``yas-minor-mode`` is
active.
Value is a string that is converted to the internal Emacs key
Default value is ``"TAB"``.
-``yas/next-field-key``
+``yas-next-field-key``
----------------------
The key to navigate to next field when a snippet is active.
Default value is ``"TAB"``.
-``yas/prev-field-key``
+``yas-prev-field-key``
----------------------
The key to navigate to previous field when a snippet is active.
Default value is ``("<backtab>" "<S-tab>)"``.
-``yas/skip-and-clear-key``
+``yas-skip-and-clear-key``
--------------------------
The key to clear the currently active field.
Default value is ``"C-d"``.
-``yas/good-grace``
+``yas-good-grace``
------------------
If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
snippet definitions. An error string "[yas] error" is returned instead.
-``yas/indent-line``
+``yas-indent-line``
-------------------
-The variable ``yas/indent-line`` controls the indenting. It is bound
+The variable ``yas-indent-line`` controls the indenting. It is bound
to ``'auto`` by default, which causes your snippet to be indented
according to the mode of the buffer it was inserted in.
-Another variable ``yas/also-auto-indent-first-line``, when non-nil
+Another variable ``yas-also-auto-indent-first-line``, when non-nil
does exactly that :-).
To use the hard-coded indentation in your snippet template, set this
For backward compatibility with earlier versions of YASnippet, you can
also place a ``$>`` in your snippet, an ``(indent-according-to-mode)``
will be executed there to indent the line. This only takes effect when
-``yas/indent-line`` is set to something other than ``'auto``.
+``yas-indent-line`` is set to something other than ``'auto``.
.. sourcecode:: text
$0$>
}$>
-``yas/wrap-around-region``
+``yas-wrap-around-region``
--------------------------
If non-nil, YASnippet will try to expand the snippet's exit marker
around the currently selected region. When this variable is set to t,
-this has the same effect has using the ```yas/selected-text``` inline
+this has the same effect has using the ```yas-selected-text``` inline
evaluation.
Because on most systems starting to type deletes the currently
selected region, this works mostly for snippets with direct
-keybindings or with the ``yas/insert-snippet`` command.
+keybindings or with the ``yas-insert-snippet`` command.
However, when the value is of this variable is ``cua`` YASnippet will
additionally look-up any recently selected that you deleted by starting
typing. This allows you select a region, type a snippet key (deleting
-the region), then press ``yas/trigger-key`` to see the deleted region
+the region), then press ``yas-trigger-key`` to see the deleted region
spring back to life inside your new snippet.
-``yas/triggers-in-field``
+``yas-triggers-in-field``
--------------------------
-If non-nil, ``yas/next-field-key`` can trigger stacked expansions,
+If non-nil, ``yas-next-field-key`` can trigger stacked expansions,
that is a snippet expansion inside another snippet
-expansion. Otherwise, ``yas/next-field-key`` just tries to move on to
+expansion. Otherwise, ``yas-next-field-key`` just tries to move on to
the next field.
-``yas/snippet-revival``
+``yas-snippet-revival``
-----------------------
Non-nil means re-activate snippet fields after undo/redo.
-``yas/after-exit-snippet-hook`` and ``yas/before-expand-snippet-hook``
+``yas-after-exit-snippet-hook`` and ``yas-before-expand-snippet-hook``
----------------------------------------------------------------------
These hooks are called, respectively, before the insertion of a
You can use YASnippet to expand snippets in different ways:
* By typing an abbrev, the snippet *trigger key*, and then pressing
- the key defined in ``yas/trigger-key`` (which defaults to
+ the key defined in ``yas-trigger-key`` (which defaults to
"TAB"). This works in buffers where the minor mode
- ``yas/minor-mode`` is active;
+ ``yas-minor-mode`` is active;
-* By invoking the command ``yas/insert-snippet`` (either by typing
- ``M-x yas/insert-snippet`` or its keybinding). This does *not*
- require ``yas/minor-mode`` to be active.
+* By invoking the command ``yas-insert-snippet`` (either by typing
+ ``M-x yas-insert-snippet`` or its keybinding). This does *not*
+ require ``yas-minor-mode`` to be active.
* By using the keybinding associated with an active snippet. This also
- requires ``yas/minor-mode`` to be active;
+ requires ``yas-minor-mode`` to be active;
* By expanding directly from the "YASnippet" menu in the menu-bar
Trigger key
-----------
-When ``yas/minor-mode`` is enabled, the keybinding taken from
-``yas/trigger-key`` will take effect.
+When ``yas-minor-mode`` is enabled, the keybinding taken from
+``yas-trigger-key`` will take effect.
-``yas/trigger-key`` invokes ``yas/expand``, which tries to expand a
+``yas-trigger-key`` invokes ``yas-expand``, which tries to expand a
*snippet abbrev* (also known as *snippet key*) before point.
The default key is ``"TAB"``, however, you can freely set it to some
:align: left
To enable the YASnippet minor mode in all buffers globally use the
-command ``yas/global-mode``.
+command ``yas-global-mode``.
-When you use ``yas/global-mode`` you can also selectively disable
+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.
+``yas-dont-active`` in the buffer's mode hook.
-Trouble when using or understanding the ``yas/trigger-key`` is easily
+Trouble when using or understanding the ``yas-trigger-key`` is easily
the most controversial issue in YASsnippet. See the `FAQ <faq.html>`_.
Fallback bahaviour
~~~~~~~~~~~~~~~~~~
-``yas/fallback-behaviour`` is a customization variable bound to
-``'call-other-command`` by default. If ``yas/expand`` failed to find
+``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 the
-``yas/trigger-key``.
+``yas-trigger-key``.
If found, the command will be called. Usually this works very well --
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
+``yas-fallback-behavior`` variable. If you set this variable to
``'return-nil``, it will return ``nil`` instead of trying to call the
*original* command when no snippet is found.
Insert at point
---------------
-The command ``M-x yas/insert-snippet`` lets you insert snippets at
+The command ``M-x yas-insert-snippet`` lets you insert snippets at
point *for you 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.
``C-u``.
The prompting methods used are again controlled by
-``yas/prompt-functions``.
+``yas-prompt-functions``.
Snippet keybinding
------------------
----------------------------------
To integrate with ``hippie-expand``, just put
-``yas/hippie-try-expand`` in
+``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.
------------------------------
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.
+elisp code. You should call ``yas-expand-snippet`` instead of
+``yas-expand`` in this case.
As with expanding from the menubar, the condition system and multiple
candidates doesn't affect expansion. In fact, expanding from the
.. sourcecode:: common-lisp
- (yas/expand-snippet template)
+ (yas-expand-snippet template)
-See the internal documentation on ``yas/expand-snippet`` for more
+See the internal documentation on ``yas-expand-snippet`` for more
information.
Controlling expansion
are also considered. This works recursively, i.e. parents of parents
of eligible tables are also considered.
-* Buffer-local ``yas/mode-symbol`` variable
+* Buffer-local ``yas-mode-symbol`` variable
This can be used to consider snippet tables whose name does not
correspond to a major mode. If you set this variable to a name ,
;; snippet table "rails-mode"
(add-hook 'rinari-minor-mode-hook
#'(lambda ()
- (setq yas/mode-symbol 'rails-mode)))
+ (setq yas-mode-symbol 'rails-mode)))
-* Buffer-local ``yas/buffer-local-condition`` variable
+* Buffer-local ``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
--------------------
Consider this scenario: you are an old Emacs hacker. You like the
-abbrev-way and set ``yas/trigger-key`` to ``"SPC"``. However,
+abbrev-way and set ``yas-trigger-key`` 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``).
(python-in-string/comment))``. But how about ``while``, ``for``,
etc. ? Writing the same condition for all the snippets is just
boring. So has a buffer local variable
-``yas/buffer-local-condition``. You can set this variable to ``(not
+``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? This is also possible! But let's stop telling the
story and look at the rules:
-* If ``yas/buffer-local-condition`` evaluate to nil, no snippets will
+* If ``yas-buffer-local-condition`` evaluate to nil, no snippets will
be considered for expansion.
* If it evaluates to the a *cons cell* where the ``car`` is the symbol
* Otherwise, it won't be considered.
-In the mentioned scenario, set ``yas/buffer-local-condition`` like
+In the mentioned scenario, set ``yas-buffer-local-condition`` like
this
.. sourcecode:: common-lisp
(add-hook 'python-mode-hook
'(lambda ()
- (setq yas/buffer-local-condition
+ (setq yas-buffer-local-condition
'(if (python-in-string/comment)
'(require-snippet-condition . force-in-comment)
t))))
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
+``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
+yas-prompt-functions RET``. Alternatively you can put in your
emacs-file:
.. sourcecode:: common-lisp
- (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
+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
+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.
.. image:: images/dropdown-menu.png
Use ``dropdown-menu.el``
~~~~~~~~~~~~~~~~~~~~~~~~
-The function ``yas/dropdown-prompt`` can also be placed in the
-``yas/prompt-functions`` list.
+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
Roll your own
~~~~~~~~~~~~~
-See below for the documentation on variable ``yas/prompt-functions``
+See below for the documentation on variable ``yas-prompt-functions``
Customizable Variables
======================
-``yas/prompt-functions``
+``yas-prompt-functions``
------------------------
-You can write a function and add it to the ``yas/prompt-functions``
+You can write a function and add it to the ``yas-prompt-functions``
list. These functions are called with the following arguments:
* PROMPT: A string to prompt the user;
* To signal that the user quit the prompting process, you can signal
``quit`` with ``(signal 'quit "user quit!")``
-``yas/fallback-behavior``
+``yas-fallback-behavior``
-------------------------
-How to act when ``yas/expand`` does *not* expand a snippet.
+How to act when ``yas-expand`` does *not* expand a snippet.
``call-other-command`` means try to temporarily disable YASnippet and
- call the next command bound to ``yas/trigger-key``.
+ call the next command bound to ``yas-trigger-key``.
``return-nil`` means return nil. (i.e. do nothing)
ARGS is non-nil, call COMMAND non-interactively with ARGS as
arguments.
-``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``.
+This affects ``yas-insert-snippet`` and ``yas-visit-snippet-file``.
-``yas/choose-tables-first``
+``yas-choose-tables-first``
---------------------------
If non-nil, and multiple eligible snippet tables, prompts user for
Otherwise, user chooses between the merging together of all
eligible tables.
-This affects ``yas/insert-snippet``, ``yas/visit-snippet-file``
+This affects ``yas-insert-snippet``, ``yas-visit-snippet-file``
-``yas/key-syntaxes``
+``yas-key-syntaxes``
--------------------
The default searching strategy is quite powerful. For example, in
pointed to by ``foo_bar`` and ``"#foobar`` won't be considered.
However, this strategy can also be customized easily from the
-``yas/key-syntaxes`` variable. It is a list of syntax rules, the
+``yas-key-syntaxes`` variable. It is a list of syntax rules, the
default value is ``("w" "w_" "w_." "^ ")``. Which means search the
following thing until found one:
.. contents::
-When ``yas/minor-mode`` is active, YASnippet will setup a menu just
+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
--------------------------
Invoking "Load snippets..." from the menu invokes
-``yas/load-directory`` and prompts you for a snippet directory
+``yas-load-directory`` and prompts you for a snippet directory
hierarchy to load.
Also useful is the "Reload all" options which uncondionally reloads
-all the snippets directories defined in ``yas/root-directory`` and
+all the snippets directories defined in ``yas-root-directory`` and
rebuilds the menus.
Snippet menu behavior
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
+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
+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``.
+active mode, set ``yas-use-menu`` to ``abbreviate``.
These customizations can also be found in the menu itself, under the
"Snippet menu behavior" submenu.
---------------------
The "Indenting" submenu contains options to control the values of
-``yas/indent-line`` and ``yas/also-auto-indent-first-line``. See
+``yas-indent-line`` and ``yas-also-auto-indent-first-line``. See
`Writing snippets <snippet-development.html>`_ .
Prompting method
----------------
The "Prompting method" submenu contains options to control the value
-of ``yas/prompt-functions``. See `Expanding snippets <snippet-expansion.html>`_ .
+of ``yas-prompt-functions``. See `Expanding snippets <snippet-expansion.html>`_ .
Misc
----
also create or download more directories.
Once these directories are in place reference them in the variable
-``yas/root-directory`` and load them with ``yas/load-directory``:
+``yas-root-directory`` and load them with ``yas-load-directory``:
.. sourcecode:: common-lisp
;; Develop and keep personal snippets under ~/emacs.d/mysnippets
- (setq yas/root-directory "~/emacs.d/mysnippets")
+ (setq yas-root-directory "~/emacs.d/mysnippets")
;; Load the snippets
- (yas/load-directory yas/root-directory)
+ (yas-load-directory yas-root-directory)
-The point in using ``yas/root-directory`` (as opposed to calling
-``yas/load-directory`` directly) is considering "~/emacs.d/mysnippets"
+The point in using ``yas-root-directory`` (as opposed to calling
+``yas-load-directory`` directly) is considering "~/emacs.d/mysnippets"
for snippet development, so you can use commands like
-``yas/new-snippet`` and others described in section `Writing
+``yas-new-snippet`` and others described in section `Writing
Snippets`_.
You can make this variable a list and store more items into it:
;; Develop in ~/emacs.d/mysnippets, but also
;; try out snippets in ~/Downloads/interesting-snippets
- (setq yas/root-directory '("~/emacs.d/mysnippets"
+ (setq yas-root-directory '("~/emacs.d/mysnippets"
"~/Downloads/interesting-snippets"))
- ;; Map `yas/load-directory' to every element
- (mapc 'yas/load-directory yas/root-directory)
+ ;; Map `yas-load-directory' to every element
+ (mapc 'yas-load-directory yas-root-directory)
In this last example, the all the directories are loaded and their
snippets considered for expansion. However development still happens
Organizing snippets
===================
-Once you've setup ``yas/root-directory`` , you can store snippets
+Once you've setup ``yas-root-directory`` , you can store snippets
inside sub-directories of these directories.
Snippet definitions are put in plain text files. They are arranged
The most convenient way to define snippets for YASnippet is to put
them in a directory arranged by the mode and use
-``yas/load-directory`` to load them.
+``yas-load-directory`` to load them.
However, this might slow down the Emacs start-up speed if you have many
-snippets. You can use ``yas/define-snippets`` to define a bunch of
+snippets. You can use ``yas-define-snippets`` to define a bunch of
snippets for a particular mode in an Emacs-lisp file.
Since this is hard to maintain, there's a better way: define your
-snippets in directory and then call ``M-x yas/compile-bundle`` to
+snippets in directory and then call ``M-x yas-compile-bundle`` to
compile it into a bundle file when you modified your snippets.
The release bundle of YASnippet is produced by
-``yas/compile-bundle``. The bundle uses ``yas/define-snippets`` to
+``yas-compile-bundle``. The bundle uses ``yas-define-snippets`` to
define snippets. This avoids the IO and parsing overhead when loading
snippets.
See the internal documentation for these functions
-* ``M-x describe-function RET yas/define-snippets RET``
-* ``M-x describe-function RET yas/compile-bundle RET``.
+* ``M-x describe-function RET yas-define-snippets RET``
+* ``M-x describe-function RET yas-compile-bundle RET``.
Customizable variables
======================
-``yas/root-directory``
+``yas-root-directory``
----------------------
Root directory that stores the snippets for each major mode.
for multiple root directories. If you make this a list, the first
element is always the user-created snippets directory. Other
directories are used for bulk reloading of all snippets using
-``yas/reload-all``
+``yas-reload-all``
-``yas/ignore-filenames-as-triggers``
+``yas-ignore-filenames-as-triggers``
------------------------------------
If non-nil, don't derive tab triggers from filenames.