ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2025-10-13 13:13:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rename symbol references to from yas/* to yas-* in docs as well

Browse Source
This commit is contained in:
João Távora 2012-07-19 02:31:48 +01:00
parent 1c90e08a39
commit e12a8bf188
8 changed files with 194 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
README.mdown
View File

@ -1,13 +1,13 @@
# 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]
@ -30,15 +30,14 @@ Add the following in your `.emacs` file:
(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
@ -56,37 +55,37 @@ Consider using this "local" recipe.
: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
@ -119,8 +118,8 @@ Then, in your `.emacs` file
(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
@ -134,8 +133,8 @@ and support. If you find a bug, please report it on
[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

42
doc/changelog.rst
View File

@ -30,7 +30,7 @@ ChangeLog
* 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
@ -53,7 +53,7 @@ ChangeLog
* 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
@ -67,17 +67,17 @@ ChangeLog
* 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``.
@ -114,10 +114,10 @@ ChangeLog
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
@ -145,8 +145,8 @@ ChangeLog
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)``.
@ -157,7 +157,7 @@ ChangeLog
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.
@ -166,7 +166,7 @@ ChangeLog
==================
* 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
@ -192,9 +192,9 @@ ChangeLog
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.
@ -220,7 +220,7 @@ ChangeLog
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
==================
@ -231,7 +231,7 @@ ChangeLog
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
@ -243,7 +243,7 @@ ChangeLog
* 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
==================
@ -262,7 +262,7 @@ ChangeLog
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

44
doc/faq.rst
View File

@ -18,22 +18,22 @@ 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
``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.
@ -41,7 +41,7 @@ You'll see a buffer prompted by Emacs saying that ``TAB runs the
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
@ -49,9 +49,9 @@ code to work around:
(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
@ -61,23 +61,23 @@ As an alternative, you can also try
.. 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
@ -96,8 +96,8 @@ 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))))
(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
@ -110,18 +110,18 @@ 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:
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?

4
doc/index.rst
View File

@ -78,8 +78,8 @@ the latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named
(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.

100
doc/snippet-development.rst
View File

@ -17,23 +17,23 @@ Quickly finding snippets
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)
@ -49,13 +49,13 @@ reasonably useful syntax highlighting.
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
@ -92,7 +92,7 @@ Here's a list of currently supported directives:
--------------------------
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
@ -111,7 +111,7 @@ 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`_
See also ``yas-buffer-local-condition`` in `Expanding snippets`_
``# group:`` snippet menu grouping
@ -141,18 +141,18 @@ This is another piece of Emacs-lisp code in the form of a ``let``
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
@ -173,7 +173,7 @@ 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
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.
@ -183,7 +183,7 @@ 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
@ -231,18 +231,18 @@ dynamically:
#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
---------------
@ -308,7 +308,7 @@ If the value of an ``${n:``-construct starts with and contains ``$(``,
then it is interpreted as a mirror for field ``n`` with a
transformation. The mirror's text content is calculated according to
this transformation, which is Emacs-lisp code that gets evaluated in
an environment where the variable ``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:
@ -375,7 +375,7 @@ distinguish between fields and mirrors. In the following example
.. 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
@ -388,7 +388,7 @@ two ``$``'s instead.
.. 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
@ -400,34 +400,34 @@ Choosing fields value from a list and other tricks
As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
``yas/modified-p`` and ``yas/moving-away-p``. Because of this
``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>`_
@ -443,7 +443,7 @@ From version 0.6 on, you can also have nested placeholders of the type:
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
@ -453,10 +453,10 @@ performs the normal Emacs ``delete-char`` command.
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
@ -464,7 +464,7 @@ representation using ``read-kbd-macro``.
Default value is ``"TAB"``.
``yas/next-field-key``
``yas-next-field-key``
----------------------
The key to navigate to next field when a snippet is active.
@ -476,7 +476,7 @@ Can also be a list of keys.
Default value is ``"TAB"``.
``yas/prev-field-key``
``yas-prev-field-key``
----------------------
The key to navigate to previous field when a snippet is active.
@ -488,7 +488,7 @@ Can also be a list of keys.
Default value is ``("<backtab>" "<S-tab>)"``.
``yas/skip-and-clear-key``
``yas-skip-and-clear-key``
--------------------------
The key to clear the currently active field.
@ -500,20 +500,20 @@ Can also be a list of keys.
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
@ -525,7 +525,7 @@ To control indentation on a per-snippet basis, see also the directive
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
@ -534,38 +534,38 @@ will be executed there to indent the line. This only takes effect when
$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

104
doc/snippet-expansion.rst
View File

@ -16,16 +16,16 @@ Triggering expansion
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
@ -36,10 +36,10 @@ You can use YASnippet to expand snippets in different ways:
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
@ -49,37 +49,37 @@ other key.
: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.
@ -90,7 +90,7 @@ applicable snippets for the major mode, prefix this command with
``C-u``.
The prompting methods used are again controlled by
``yas/prompt-functions``.
``yas-prompt-functions``.
Snippet keybinding
------------------
@ -108,7 +108,7 @@ Expanding with ``hippie-expand``
----------------------------------
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.
@ -117,8 +117,8 @@ 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.
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
@ -126,9 +126,9 @@ YASnippet menu has the same effect of evaluating the follow code:
.. 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
@ -161,7 +161,7 @@ In particular, the following things matter:
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 ,
@ -176,9 +176,9 @@ In particular, the following things matter:
;; 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
@ -189,7 +189,7 @@ The condition system
--------------------
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``).
@ -198,14 +198,14 @@ you could just specify the condition for ``if`` to be ``(not
(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
@ -238,14 +238,14 @@ story and look at the rules:
* 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))))
@ -263,16 +263,16 @@ 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
``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.
@ -282,7 +282,7 @@ 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:
@ -298,8 +298,8 @@ 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
@ -308,8 +308,8 @@ 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.
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
@ -318,15 +318,15 @@ 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;
@ -346,13 +346,13 @@ that is passed).
* 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)
@ -360,16 +360,16 @@ An entry (apply COMMAND . ARGS) means interactively call COMMAND, if
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
@ -378,9 +378,9 @@ tables first.
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
@ -391,7 +391,7 @@ then that snippet is expanded and replaces the ``bar``. Snippets
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:

16
doc/snippet-menu.rst
View File

@ -4,7 +4,7 @@ YASnippet menu
.. 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
@ -26,11 +26,11 @@ Loading snippets from menu
--------------------------
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
@ -43,16 +43,16 @@ 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
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.
@ -62,14 +62,14 @@ Controlling indenting
---------------------
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
----

38
doc/snippet-organization.rst
View File

@ -24,20 +24,20 @@ directory of snippets, which you can copy somewhere and use. You can
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:
@ -46,11 +46,11 @@ 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
@ -59,7 +59,7 @@ in the first element, "~/emacs.d/mysnippets".
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
@ -132,18 +132,18 @@ YASnippet bundle
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.
@ -153,13 +153,13 @@ generated this way.
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.
@ -168,9 +168,9 @@ If you set this from your .emacs, can also be a list of strings,
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.