--- /dev/null
+# -*- mode: org; fill-column: 80 -*-\r
+#+TITLE: Yet another snippet extension\r
+#+OPTIONS: toc:1\r
+#+STARTUP: showall\r
+\r
+#+STYLE: <link rel="stylesheet" type="text/css" href="assets/stylesheet.css" />\r
+\r
+# External links\r
+#\r
+#+LINK: smart-snippet http://code.google.com/p/smart-snippet\r
+#+LINK: pluskid http://pluskid.lifegoo.org\r
+\r
+\r
+#+LINK: screencast http://www.youtube.com/watch?v=ZCGmZK4V7Sg\r
+#+LINK: docs http://capitaomorte.github.com/yasnippet\r
+#+LINK: issues https://github.com/capitaomorte/yasnippet/issues\r
+#+LINK: googlecode-tracker http://code.google.com/p/yasnippet/issues/list\r
+#+LINK: forum http://groups.google.com/group/smart-snippet\r
+\r
+\r
+# Internal links\r
+\r
+.. _Organizing Snippets: snippet-organization.html\r
+.. _Expanding Snippets: snippet-expansion.html\r
+.. _Writing Snippets: snippet-development.html\r
+.. _The YASnippet Menu: snippet-menu.html\r
+\r
+*YASnippet* is a template system for Emacs. It allows you to type an\r
+abbreviation and automatically expand it into function templates. Bundled\r
+language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML,\r
+CSS and more. The snippet syntax is inspired from TextMate's syntax, you can\r
+even [[#import-textmate][import most TextMate snippets]]\r
+\r
+YASnippet is an original creation of [[pluskid]] who also wrote its predecessor\r
+[[smart-snippet]].\r
+\r
+* Quick start\r
+\r
+** Watch a demo [[screencast]]\r
+\r
+*YASnippet* is a template system for Emacs. It allows you to type an\r
+\r
+** Install the most recent version with git\r
+\r
+Clone this repository somewhere\r
+\r
+ $ cd ~/.emacs.d/plugins\r
+ $ git clone https://github.com/capitaomorte/yasnippet\r
+\r
+Add the following in your =.emacs= file:\r
+\r
+example\r
+ (add-to-list 'load-path\r
+ "~/.emacs.d/plugins/yasnippet")\r
+ (require 'yasnippet)\r
+ (yas/global-mode 1)\r
+\r
+Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas/new-snippet`.\r
+\r
+## Install yasnippet with el-get\r
+\r
+El-get is a nice way to get the most recent version, too\r
+\r
+** Import textmate snippets (rails example)\r
+:PROPERTIES:\r
+:CUSTOM_ID: import-textmate\r
+:END:\r
+\r
+Clone the yasnippet repository to `~/.emacs.d/plugins/yasnippet`\r
+\r
+ cd ~/.emacs.d/plugins/yasnippet\r
+ git submodule init\r
+ git submodule update\r
+ gem install plist trollop\r
+ rake convert_bundles # will convert ruby, rails and html bundles from drnic\r
+\r
+Then, in your .emacs file\r
+\r
+ (add-to-list 'load-path\r
+ "~/.emacs.d/plugins/yasnippet")\r
+ (require 'yasnippet)\r
+ (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))\r
+ (yas/global-mode 1)\r
+\r
+Open some rails file (model, app, etc) and start using the textmate snippets.\r
+\r
+** Contributing snippets\r
+\r
+Please do not ask me to add snippets to the default collection under\r
+=/snippets=. This is considered frozen and by customizing =yas/snippet-dirs= you\r
+can point yasnippet to good snippet collections out there.\r
+\r
+The =extras/textmate-import.rb= tool can import many actual Textmate\r
+snippets. See [[import-textmate]].\r
+\r
+I'm focusing on developping =textmate-import.rb= tool and the =yas-setup.el=\r
+files that guide it with more difficult importation. In the future =/snippets=\r
+snippets will be deprecated and replaced with =extras/imported=.\r
+\r
+** Documentation, issues, etc\r
+\r
+Please refer to the comprehensive [[docs][documentation]] for full customization and\r
+support. If you think you've found a bug, please report it on [[issues][the GitHub issue\r
+tracker]]. (please **do not** submit new issues to the old [[googlecode-tracker][googlecode tracker]])\r
+\r
+If you run into problems using YASnippet, or have snippets to contribute, post\r
+to the [[forum][yasnippet forum]]. Thank you very much for using YASnippet!\r
+\r
+* Organizing snippets\r
+** Setting up =yas/snippet-dirs= before calling =yas/global-mode=\r
+\r
+Snippet collections are stored in specially organized file hierarchies. These\r
+are loaded by YASnippet into *snippet tables* which the triggering mechanism\r
+(see [[expand-snippets][Expanding snippets]]) looks up and (hopefully) cause the right snippet to be\r
+expanded for you.\r
+\r
+An emacs variable =yas/snippet-dirs= tells YASnippet which collections to\r
+consider.\r
+\r
+If you don't tweak it the default value of =yas/snippet-dirs= considers:\r
+\r
+ - a personal collection that YASnippet decides lives in =~/.emacs.d/snippets=\r
+ - the bundled collection, taken as a relative path to =yasnippet.el= localtion\r
+\r
+You might and probably want to try out more snippet collections though:\r
+\r
+#+begin_src emacs-lisp :exports both\r
+ ;; Develop in ~/emacs.d/mysnippets, but also\r
+ ;; try out snippets in ~/Downloads/interesting-snippets\r
+ (setq yas/snippet-dirs '("~/emacs.d/mysnippets"\r
+ "~/Downloads/interesting-snippets"))\r
+\r
+ ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets\r
+ (setq yas/snippet-dirs (append yas/snippet-dirs\r
+ '("~/Downloads/interesting-snippets")))\r
+#+end_src\r
+\r
+Collections appearing earlier in the list shadow any conflicting snippets from\r
+collections later in the list. =yas/new-snippet= always stores snippets in the\r
+first collection.\r
+\r
+# Snippet definitions are put in plain text files. They are arranged\r
+# by sub-directories, and the snippet tables are named after these\r
+# directories.\r
+\r
+# The name corresponds to the Emacs mode where you want expansion to\r
+# take place. For example, snippets for ``c-mode`` are put in the\r
+# ``c-mode`` sub-directory.\r
+\r
+\r
+\r
+# 2. `Expanding Snippets`_\r
+\r
+# Describes how YASnippet chooses snippets for expansion at point.\r
+\r
+# Maybe, you'll want some snippets to be expanded in a particular\r
+# mode, or only under certain conditions, or be prompted using\r
+# ``ido``, etc...\r
+\r
+# 3. `Writing Snippets`_\r
+\r
+# Describes the YASnippet definition syntax, which is very close (but\r
+# not equivalent) to Textmate's. Includes a section about converting\r
+# TextMate snippets.\r
+\r
+# 4. `The YASnippet menu`_\r
+\r
+# Explains how to use the YASnippet menu to explore, learn and modify\r
+# snippets.\r
+\r
+\r
+\r
+# Loading snippets\r
+# ================\r
+\r
+\r
+\r
+# Organizing snippets\r
+# ===================\r
+\r
+# Once you've setup ``yas/root-directory`` , you can store snippets\r
+# inside sub-directories of these directories.\r
+\r
+\r
+\r
+# The ``.yas.parents`` file\r
+# -------------------------\r
+\r
+# It's very useful to have certain modes share snippets between\r
+# themselves. To do this, choose a mode subdirectory and place a\r
+# ``.yas-parents`` containing a whitespace-separated list of other\r
+# mode names. When you reload those modes become parents of the\r
+# original mode.\r
+\r
+# .. sourcecode:: text\r
+\r
+# $ tree\r
+# .\r
+# |-- c-mode\r
+# | |-- .yas-parents # contains "cc-mode text-mode"\r
+# | `-- printf\r
+# |-- cc-mode\r
+# | |-- for\r
+# | `-- while\r
+# |-- java-mode\r
+# | |-- .yas-parents # contains "cc-mode text-mode"\r
+# | `-- println\r
+# `-- text-mode\r
+# |-- email\r
+# `-- time\r
+\r
+# The ``.yas-make-groups`` file\r
+# -----------------------------\r
+\r
+# .. image:: images/menu-groups.png\r
+# :align: right\r
+\r
+# If you place an empty plain text file ``.yas-make-groups`` inside one\r
+# of the mode directories, the names of these sub-directories are\r
+# considered groups of snippets and `The YASnippet Menu`_ is organized\r
+# much more cleanly, as you can see in the image.\r
+\r
+# Another alternative way to achieve this is to place a ``# group:``\r
+# directive inside the snippet definition. See `Writing Snippets`_.\r
+\r
+# .. sourcecode:: text\r
+\r
+# $ tree ruby-mode/\r
+# ruby-mode/\r
+# |-- .yas-make-groups\r
+# |-- collections\r
+# | |-- each\r
+# | `-- ...\r
+# |-- control structure\r
+# | |-- forin\r
+# | `-- ...\r
+# |-- definitions\r
+# | `-- ...\r
+# `-- general\r
+# `-- ...\r
+\r
+\r
+# YASnippet bundle\r
+# ================\r
+\r
+# The most convenient way to define snippets for YASnippet is to put\r
+# them in a directory arranged by the mode and use\r
+# ``yas/load-directory`` to load them.\r
+\r
+# However, this might slow down the Emacs start-up speed if you have many\r
+# snippets. You can use ``yas/define-snippets`` to define a bunch of\r
+# snippets for a particular mode in an Emacs-lisp file.\r
+\r
+# Since this is hard to maintain, there's a better way: define your\r
+# snippets in directory and then call ``M-x yas/compile-bundle`` to\r
+# compile it into a bundle file when you modified your snippets.\r
+\r
+# The release bundle of YASnippet is produced by\r
+# ``yas/compile-bundle``. The bundle uses ``yas/define-snippets`` to\r
+# define snippets. This avoids the IO and parsing overhead when loading\r
+# snippets.\r
+\r
+# Further more, the generated bundle is a stand-alone file not depending\r
+# on ``yasnippet.el``. The released bundles of YASnippet are all\r
+# generated this way.\r
+\r
+# See the internal documentation for these functions\r
+\r
+# \* ``M-x describe-function RET yas/define-snippets RET``\r
+# \* ``M-x describe-function RET yas/compile-bundle RET``.\r
+\r
+# Customizable variables\r
+# ======================\r
+\r
+# ``yas/root-directory``\r
+# ----------------------\r
+\r
+# Root directory that stores the snippets for each major mode.\r
+\r
+# If you set this from your .emacs, can also be a list of strings,\r
+# for multiple root directories. If you make this a list, the first\r
+# element is always the user-created snippets directory. Other\r
+# directories are used for bulk reloading of all snippets using\r
+# ``yas/reload-all``\r
+\r
+# ``yas/ignore-filenames-as-triggers``\r
+# ------------------------------------\r
+\r
+# If non-nil, don't derive tab triggers from filenames.\r
+\r
+# This means a snippet without a ``# key:`` directive wont have a tab\r
+# trigger.\r
+\r
+# .. LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl\r
+# .. LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el\r
+# .. LocalWords: rjs RET\r
+\r
+# * snippet-expansion.org\r
+# ==================\r
+# Expanding snippets\r
+# ==================\r
+\r
+# .. _Organizing Snippets: snippet-organization.html\r
+# .. _Expanding Snippets: snippet-expansion.html\r
+# .. _Writing Snippets: snippet-development.html\r
+# .. _The YASnippet Menu: snippet-menu.html\r
+\r
+# .. contents::\r
+\r
+\r
+# Triggering expansion\r
+# ====================\r
+\r
+# You can use YASnippet to expand snippets in different ways:\r
+\r
+# \* By typing an abbrev, the snippet *trigger key*, and then pressing\r
+# the key defined in ``yas/trigger-key`` (which defaults to\r
+# "TAB"). This works in buffers where the minor mode\r
+# ``yas/minor-mode`` is active;\r
+\r
+# \* By invoking the command ``yas/insert-snippet`` (either by typing\r
+# ``M-x yas/insert-snippet`` or its keybinding). This does *not*\r
+# require ``yas/minor-mode`` to be active.\r
+\r
+# \* By using the keybinding associated with an active snippet. This also\r
+# requires ``yas/minor-mode`` to be active;\r
+\r
+# \* By expanding directly from the "YASnippet" menu in the menu-bar\r
+\r
+# \* By using hippie-expand\r
+\r
+# \* Expanding from emacs-lisp code\r
+\r
+# Trigger key\r
+# -----------\r
+\r
+# When ``yas/minor-mode`` is enabled, the keybinding taken from\r
+# ``yas/trigger-key`` will take effect.\r
+\r
+# ``yas/trigger-key`` invokes ``yas/expand``, which tries to expand a\r
+# \*snippet abbrev* (also known as *snippet key*) before point.\r
+\r
+# The default key is ``"TAB"``, however, you can freely set it to some\r
+# other key.\r
+\r
+# .. image:: images/minor-mode-indicator.png\r
+# :align: left\r
+\r
+# To enable the YASnippet minor mode in all buffers globally use the\r
+# command ``yas/global-mode``.\r
+\r
+# When you use ``yas/global-mode`` you can also selectively disable\r
+# YASnippet in some buffers by setting the buffer-local variable\r
+# ``yas/dont-active`` in the buffer's mode hook.\r
+\r
+# Trouble when using or understanding the ``yas/trigger-key`` is easily\r
+# the most controversial issue in YASsnippet. See the `FAQ <faq.html>`_.\r
+\r
+# Fallback bahaviour\r
+# ~~~~~~~~~~~~~~~~~~\r
+\r
+# ``yas/fallback-behaviour`` is a customization variable bound to\r
+# ``'call-other-command`` by default. If ``yas/expand`` failed to find\r
+# any suitable snippet to expand, it will disable the minor mode\r
+# temporarily and find if there's any other command bound the\r
+# ``yas/trigger-key``.\r
+\r
+# If found, the command will be called. Usually this works very well --\r
+# when there's a snippet, expand it, otherwise, call whatever command\r
+# originally bind to the trigger key.\r
+\r
+# However, you can change this behavior by customizing the\r
+# ``yas/fallback-behavior`` variable. If you set this variable to\r
+# ``'return-nil``, it will return ``nil`` instead of trying to call the\r
+# \*original* command when no snippet is found.\r
+\r
+# Insert at point\r
+# ---------------\r
+\r
+# The command ``M-x yas/insert-snippet`` lets you insert snippets at\r
+# point *for you current major mode*. It prompts you for the snippet\r
+# key first, and then for a snippet template if more than one template\r
+# exists for the same key.\r
+\r
+# The list presented contains the snippets that can be inserted at\r
+# point, according to the condition system. If you want to see all\r
+# applicable snippets for the major mode, prefix this command with\r
+# ``C-u``.\r
+\r
+# The prompting methods used are again controlled by\r
+# ``yas/prompt-functions``.\r
+\r
+# Snippet keybinding\r
+# ------------------\r
+\r
+# See the section of the ``# binding:`` directive in `Writing\r
+# Snippets`_.\r
+\r
+\r
+# Expanding from the menu\r
+# -----------------------\r
+\r
+# See `the YASnippet Menu`_.\r
+\r
+# Expanding with ``hippie-expand``\r
+# ----------------------------------\r
+\r
+# To integrate with ``hippie-expand``, just put\r
+# ``yas/hippie-try-expand`` in\r
+# ``hippie-expand-try-functions-list``. This probably makes more sense\r
+# when placed at the top of the list, but it can be put anywhere you\r
+# prefer.\r
+\r
+# Expanding from emacs-lisp code\r
+# ------------------------------\r
+\r
+# Sometimes you might want to expand a snippet directly from you own\r
+# elisp code. You should call ``yas/expand-snippet`` instead of\r
+# ``yas/expand`` in this case.\r
+\r
+# As with expanding from the menubar, the condition system and multiple\r
+# candidates doesn't affect expansion. In fact, expanding from the\r
+# YASnippet menu has the same effect of evaluating the follow code:\r
+\r
+# .. sourcecode:: common-lisp\r
+\r
+# (yas/expand-snippet template)\r
+\r
+# See the internal documentation on ``yas/expand-snippet`` for more\r
+# information.\r
+\r
+# Controlling expansion\r
+# =====================\r
+\r
+# Eligible snippets\r
+# -----------------\r
+\r
+# YASnippet does quite a bit of filtering to find out which snippets are\r
+# eligible for expanding at the current cursor position.\r
+\r
+# In particular, the following things matter:\r
+\r
+# \* Currently loaded snippets tables\r
+\r
+# These are loaded from a directory hierarchy in your file system. See\r
+# `Organizing Snippets`_. They are named after major modes like\r
+# ``html-mode``, ``ruby-mode``, etc...\r
+\r
+# \* Major mode of the current buffer\r
+\r
+# If the currrent major mode matches one of the loaded snippet tables,\r
+# then all that table's snippets are considered for expansion. Use\r
+# ``M-x describe-variable RET major-mode RET`` to find out which major\r
+# mode you are in currently.\r
+\r
+# \* Parent tables\r
+\r
+# Snippet tables defined as the parent of some other eligible table\r
+# are also considered. This works recursively, i.e. parents of parents\r
+# of eligible tables are also considered.\r
+\r
+# \* Buffer-local ``yas/mode-symbol`` variable\r
+\r
+# This can be used to consider snippet tables whose name does not\r
+# correspond to a major mode. If you set this variable to a name ,\r
+# like ``rinari-minor-mode``, you can have some snippets expand only\r
+# in that minor mode. Naturally, you want to set this conditionally,\r
+# i.e. only when entering that minor mode, so using a hook is a good\r
+# idea.\r
+\r
+# .. sourcecode:: common-lisp\r
+\r
+# ;; When entering rinari-minor-mode, consider also the snippets in the\r
+# ;; snippet table "rails-mode"\r
+# (add-hook 'rinari-minor-mode-hook\r
+# #'(lambda ()\r
+# (setq yas/mode-symbol 'rails-mode)))\r
+\r
+# \* Buffer-local ``yas/buffer-local-condition`` variable\r
+\r
+# This variable provides finer grained control over what snippets can\r
+# be expanded in the current buffer. The default value won't let you\r
+# expand snippets inside comments or string literals for example. See\r
+# `The condition system`_ for more info.\r
+\r
+# The condition system\r
+# --------------------\r
+\r
+# Consider this scenario: you are an old Emacs hacker. You like the\r
+# abbrev-way and set ``yas/trigger-key`` to ``"SPC"``. However,\r
+# you don't want ``if`` to be expanded as a snippet when you are typing\r
+# in a comment block or a string (e.g. in ``python-mode``).\r
+\r
+# If you use the ``# condition :`` directive (see `Writing Snippets`_)\r
+# you could just specify the condition for ``if`` to be ``(not\r
+# (python-in-string/comment))``. But how about ``while``, ``for``,\r
+# etc. ? Writing the same condition for all the snippets is just\r
+# boring. So has a buffer local variable\r
+# ``yas/buffer-local-condition``. You can set this variable to ``(not\r
+# (python-in-string/comment))`` in ``python-mode-hook``.\r
+\r
+# Then, what if you really want some particular snippet to expand even\r
+# inside a comment? This is also possible! But let's stop telling the\r
+# story and look at the rules:\r
+\r
+# \* If ``yas/buffer-local-condition`` evaluate to nil, no snippets will\r
+# be considered for expansion.\r
+\r
+# \* If it evaluates to the a *cons cell* where the ``car`` is the symbol\r
+# ``require-snippet-condition`` and the ``cdr`` is a symbol (let's\r
+# call it ``requirement``), then:\r
+\r
+# * Snippets having no ``# condition:`` directive won't be considered;\r
+\r
+# * Snippets with conditions that evaluate to nil (or produce an\r
+# error) won't be considered;\r
+\r
+# * If the snippet has a condition that evaluates to non-nil (let's\r
+# call it ``result``):\r
+\r
+# * If ``requirement`` is ``t``, the snippet is ready to be\r
+# expanded;\r
+\r
+# * If ``requirement`` is ``eq`` to ``result``, the snippet is ready\r
+# to be expanded;\r
+\r
+# * Otherwise the snippet won't be considered.\r
+\r
+# \* If it evaluates to the symbol ``always``, all snippets are\r
+# considered for expansion, regardless of any conditions.\r
+\r
+# \* If it evaluate to ``t`` or some other non-nil value:\r
+\r
+# * If the snippet has no condition, or has a condition that evaluate\r
+# to non-nil, it is ready to be expanded.\r
+\r
+# * Otherwise, it won't be considered.\r
+\r
+# In the mentioned scenario, set ``yas/buffer-local-condition`` like\r
+# this\r
+\r
+# .. sourcecode:: common-lisp\r
+\r
+# (add-hook 'python-mode-hook\r
+# '(lambda ()\r
+# (setq yas/buffer-local-condition\r
+# '(if (python-in-string/comment)\r
+# '(require-snippet-condition . force-in-comment)\r
+# t))))\r
+\r
+# ... and specify the condition for a snippet that you're going to\r
+# expand in comment to be evaluated to the symbol\r
+# ``force-in-comment``. Then it can be expanded as you expected, while\r
+# other snippets like ``if`` still can't expanded in comment.\r
+\r
+# Multiples snippet with the same key\r
+# -----------------------------------\r
+\r
+# The rules outlined `above <Eligible snippets>`_ can return more than\r
+# one snippet to be expanded at point.\r
+\r
+# When there are multiple candidates, YASnippet will let you select\r
+# one. The UI for selecting multiple candidate can be customized through\r
+# ``yas/prompt-functions`` , which defines your preferred methods of\r
+# being prompted for snippets.\r
+\r
+# You can customize it with ``M-x customize-variable RET\r
+# yas/prompt-functions RET``. Alternatively you can put in your\r
+# emacs-file:\r
+\r
+# .. sourcecode:: common-lisp\r
+\r
+# (setq yas/prompt-functions '(yas/x-prompt yas/dropdown-prompt))\r
+\r
+# Currently there are some alternatives solution with YASnippet.\r
+\r
+# .. image:: images/x-menu.png\r
+# :align: right\r
+\r
+# Use the X window system\r
+# ~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+# The function ``yas/x-prompt`` can be used to show a popup menu for you\r
+# to select. This menu will be part of you native window system widget,\r
+# which means:\r
+\r
+# \* It usually looks beautiful. E.g. when you compile Emacs with gtk\r
+# support, this menu will be rendered with your gtk theme.\r
+# \* Your window system may or may not allow to you use ``C-n``, ``C-p``\r
+# to navigate this menu.\r
+# \* This function can't be used when in a terminal.\r
+\r
+# .. image:: images/ido-menu.png\r
+# :align: right\r
+\r
+# Minibuffer prompting\r
+# ~~~~~~~~~~~~~~~~~~~~\r
+\r
+# You can use functions ``yas/completing-prompt`` for the classic emacs\r
+# completion method or ``yas/ido-prompt`` for a much nicer looking\r
+# method. The best way is to try it. This works in a terminal.\r
+\r
+# .. image:: images/dropdown-menu.png\r
+# :align: right\r
+\r
+# Use ``dropdown-menu.el``\r
+# ~~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+# The function ``yas/dropdown-prompt`` can also be placed in the\r
+# ``yas/prompt-functions`` list.\r
+\r
+# This works in both window system and terminal and is customizable, you\r
+# can use ``C-n``, ``C-p`` to navigate, ``q`` to quit and even press\r
+# ``6`` as a shortcut to select the 6th candidate.\r
+\r
+# Roll your own\r
+# ~~~~~~~~~~~~~\r
+\r
+# See below for the documentation on variable ``yas/prompt-functions``\r
+\r
+# Customizable Variables\r
+# ======================\r
+\r
+# ``yas/prompt-functions``\r
+# ------------------------\r
+\r
+# You can write a function and add it to the ``yas/prompt-functions``\r
+# list. These functions are called with the following arguments:\r
+\r
+# \* PROMPT: A string to prompt the user;\r
+\r
+# \* CHOICES: A list of strings or objects;\r
+\r
+# \* optional DISPLAY-FN : A function. When applied to each of the\r
+# objects in CHOICES it will return a string;\r
+\r
+# The return value of any function you put here should be one of\r
+# the objects in CHOICES, properly formatted with DISPLAY-FN (if\r
+# that is passed).\r
+\r
+# \* To signal that your particular style of prompting is unavailable at\r
+# the moment, you can also have the function return nil.\r
+\r
+# \* To signal that the user quit the prompting process, you can signal\r
+# ``quit`` with ``(signal 'quit "user quit!")``\r
+\r
+# ``yas/fallback-behavior``\r
+# -------------------------\r
+\r
+# How to act when ``yas/expand`` does *not* expand a snippet.\r
+\r
+# ``call-other-command`` means try to temporarily disable YASnippet and\r
+# call the next command bound to ``yas/trigger-key``.\r
+\r
+# ``return-nil`` means return nil. (i.e. do nothing)\r
+\r
+# An entry (apply COMMAND . ARGS) means interactively call COMMAND, if\r
+# ARGS is non-nil, call COMMAND non-interactively with ARGS as\r
+# arguments.\r
+\r
+# ``yas/choose-keys-first``\r
+# -------------------------\r
+\r
+# If non-nil, prompt for snippet key first, then for template.\r
+\r
+# Otherwise prompts for all possible snippet names.\r
+\r
+# This affects ``yas/insert-snippet`` and ``yas/visit-snippet-file``.\r
+\r
+# ``yas/choose-tables-first``\r
+# ---------------------------\r
+\r
+# If non-nil, and multiple eligible snippet tables, prompts user for\r
+# tables first.\r
+\r
+# Otherwise, user chooses between the merging together of all\r
+# eligible tables.\r
+\r
+# This affects ``yas/insert-snippet``, ``yas/visit-snippet-file``\r
+\r
+# ``yas/key-syntaxes``\r
+# --------------------\r
+\r
+# The default searching strategy is quite powerful. For example, in\r
+# ``c-mode``, ``bar``, ``foo_bar``, ``"#foo_bar"`` can all be recognized\r
+# as a snippet key. Furthermore, the searching is in that order. In\r
+# other words, if ``bar`` is found to be a key to some *valid* snippet,\r
+# then that snippet is expanded and replaces the ``bar``. Snippets\r
+# pointed to by ``foo_bar`` and ``"#foobar`` won't be considered.\r
+\r
+# However, this strategy can also be customized easily from the\r
+# ``yas/key-syntaxes`` variable. It is a list of syntax rules, the\r
+# default value is ``("w" "w_" "w_." "^ ")``. Which means search the\r
+# following thing until found one:\r
+\r
+# \* a word.\r
+# \* a symbol. In lisp, ``-`` and ``?`` can all be part of a symbol.\r
+# \* a sequence of characters of either word, symbol or punctuation.\r
+# \* a sequence of characters of non-whitespace characters.\r
+\r
+# But you'd better keep the default value unless you want to understand\r
+# how Emacs's syntax rules work...\r
+\r
+\r
+\r
+# * snippet-development.org\r
+# ================\r
+# Writing snippets\r
+# ================\r
+\r
+# .. _Organizing Snippets: snippet-organization.html\r
+# .. _Expanding Snippets: snippet-expansion.html\r
+# .. _Writing Snippets: snippet-development.html\r
+# .. _The YASnippet Menu: snippet-menu.html\r
+\r
+# .. contents::\r
+\r
+# Snippet development\r
+# ===================\r
+\r
+# Quickly finding snippets\r
+# ------------------------\r
+\r
+# There are some ways you can quickly find a snippet file:\r
+\r
+# \* ``M-x yas/new-snippet``\r
+\r
+# Prompts you for a snippet name, then tries to guess a suitable\r
+# directory to store it, prompting you for creation if it does not\r
+# exist. Finally, places you in a new buffer set to ``snippet-mode``\r
+# so you can write your snippet.\r
+\r
+# \* ``M-x yas/find-snippets``\r
+\r
+# Lets you find the snippet file in the directory the snippet was\r
+# loaded from (if it exists) like ``find-file-other-window``. The\r
+# directory searching logic is similar to ``M-x yas/new-snippet``.\r
+\r
+# \* ``M-x yas/visit-snippet-file``\r
+\r
+# Prompts you for possible snippet expansions like\r
+# ``yas/insert-snippet``, but instead of expanding it, takes you\r
+# directly to the snippet definition's file, if it exists.\r
+\r
+# Once you find this file it will be set to ``snippet-mode`` (see ahead)\r
+# and you can start editing your snippet.\r
+\r
+\r
+# Using the ``snippet-mode`` major mode\r
+# -------------------------------------\r
+\r
+# There is a major mode ``snippet-mode`` to edit snippets. You can set\r
+# the buffer to this mode with ``M-x snippet-mode``. It provides\r
+# reasonably useful syntax highlighting.\r
+\r
+# Two commands are defined in this mode:\r
+\r
+# \* ``M-x yas/load-snippet-buffer``\r
+\r
+# When editing a snippet, this loads the snippet into the correct\r
+# mode and menu. Bound to ``C-c C-c`` by default while in\r
+# ``snippet-mode``.\r
+\r
+# \* ``M-x yas/tryout-snippet``\r
+\r
+# When editing a snippet, this opens a new empty buffer, sets it to\r
+# the appropriate major mode and inserts the snippet there, so you\r
+# can see what it looks like. This is bound to ``C-c C-t`` while in\r
+# ``snippet-mode``.\r
+\r
+# There are also *snippets for writing snippets*: ``vars``, ``$f`` and\r
+# ``$m`` :-).\r
+\r
+# File content\r
+# ============\r
+\r
+# A file defining a snippet generally contains the template to be\r
+# expanded.\r
+\r
+# Optionally, if the file contains a line of ``# --``, the lines above\r
+# it count as comments, some of which can be *directives* (or meta\r
+# data). Snippet directives look like ``# property: value`` and tweak\r
+# certain snippets properties described below. If no ``# --`` is found,\r
+# the whole file is considered the snippet template.\r
+\r
+# Here's a typical example:\r
+\r
+# .. sourcecode:: text\r
+\r
+# # contributor: pluskid <pluskid@gmail.com>\r
+# # name: __...__\r
+# # --\r
+# __${init}__\r
+\r
+# Here's a list of currently supported directives:\r
+\r
+# ``# key:`` snippet abbrev\r
+# --------------------------\r
+\r
+# This is the probably the most important directive, it's the abbreviation you\r
+# type to expand a snippet just before hitting ``yas/trigger-key``. If you don't\r
+# specify this the snippet will not be expandable through the key mechanism.\r
+\r
+# ``# name:`` snippet name\r
+# ------------------------\r
+\r
+# This is a one-line description of the snippet. It will be displayed in\r
+# the menu. It's a good idea to select a descriptive name for a\r
+# snippet -- especially distinguishable among similar snippets.\r
+\r
+# If you omit this name it will default to the file name the snippet was\r
+# loaded from.\r
+\r
+# ``# condition:`` snippet condition\r
+# ----------------------------------\r
+# This is a piece of Emacs-lisp code. If a snippet has a condition, then it\r
+# will only be expanded when the condition code evaluate to some non-nil\r
+# value.\r
+\r
+# See also ``yas/buffer-local-condition`` in `Expanding snippets`_\r
+\r
+\r
+# ``# group:`` snippet menu grouping\r
+# ----------------------------------\r
+\r
+# When expanding/visiting snippets from the menu-bar menu, snippets for a\r
+# given mode can be grouped into sub-menus . This is useful if one has\r
+# too many snippets for a mode which will make the menu too\r
+# long.\r
+\r
+# The ``# group:`` property only affect menu construction (See `the\r
+# YASnippet menu`_) and the same effect can be achieved by grouping\r
+# snippets into sub-directories and using the ``.yas-make-groups``\r
+# special file (for this see `Organizing Snippets`_\r
+\r
+\r
+# Refer to the bundled snippets for ``ruby-mode`` for examples on the\r
+# ``# group:`` directive. Group can also be nested, e.g. ``control\r
+# structure.loops`` tells that the snippet is under the ``loops`` group\r
+# which is under the ``control structure`` group.\r
+\r
+# ``# expand-env:`` expand environment\r
+# ------------------------------------\r
+\r
+# This is another piece of Emacs-lisp code in the form of a ``let``\r
+# \*varlist form*, i.e. a list of lists assigning values to variables. It\r
+# can be used to override variable values while the snippet is being\r
+# expanded.\r
+\r
+# Interesting variables to override are ``yas/wrap-around-region`` and\r
+# ``yas/indent-line`` (see `Expanding Snippets`_).\r
+\r
+# As an example, you might normally have ``yas/indent-line`` set to\r
+# ``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this\r
+# particularly brilliant piece of ASCII art these values would mess up\r
+# your hard work. You can then use:\r
+\r
+# .. sourcecode:: text\r
+\r
+# # name: ASCII home\r
+# # expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil))\r
+# # --\r
+# welcome to my\r
+# X humble\r
+# / \ home,\r
+# / \ $0\r
+# / \\r
+# /-------\\r
+# | |\r
+# | +-+ |\r
+# | | | |\r
+# +--+-+--+\r
+\r
+# ``# binding:`` direct keybinding\r
+# ---------------------------------\r
+\r
+# You can use this directive to expand a snippet directly from a normal\r
+# Emacs keybinding. The keybinding will be registered in the Emacs\r
+# keymap named after the major mode the snippet is active\r
+# for.\r
+\r
+# Additionally a variable ``yas/prefix`` is set to to the prefix\r
+# argument you normally use for a command. This allows for small\r
+# variations on the same snippet, for example in this "html-mode"\r
+# snippet.\r
+\r
+# .. sourcecode:: text\r
+\r
+# # name: <p>...</p>\r
+# # binding: C-c C-c C-m\r
+# # --\r
+# <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>\r
+\r
+# This binding will be recorded in the keymap\r
+# ``html-mode-map``. To expand a paragraph tag newlines, just\r
+# press ``C-u C-c C-c C-m``. Omitting the ``C-u`` will expand the\r
+# paragraph tag without newlines.\r
+\r
+# ``# contributor:`` snippet author\r
+# ---------------------------------------------------\r
+\r
+# This is optional and has no effect whatsoever on snippet\r
+# functionality, but it looks nice.\r
+\r
+# Template syntax\r
+# ===============\r
+\r
+# The syntax of the snippet template is simple but powerful, very\r
+# similar to TextMate's.\r
+\r
+# Plain Text\r
+# ----------\r
+\r
+# Arbitrary text can be included as the content of a template. They are\r
+# usually interpreted as plain text, except ``$`` and `````. You need to\r
+# use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also\r
+# needed to be escaped as ``\\`` sometimes.\r
+\r
+# Embedded Emacs-lisp code\r
+# ------------------------\r
+\r
+# Emacs-Lisp code can be embedded inside the template, written inside\r
+# back-quotes (`````). The lisp forms are evaluated when the snippet is\r
+# being expanded. The evaluation is done in the same buffer as the\r
+# snippet being expanded.\r
+\r
+# Here's an example for ``c-mode`` to calculate the header file guard\r
+# dynamically:\r
+\r
+# .. sourcecode:: text\r
+\r
+# #ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}\r
+# #define $1\r
+\r
+# $0\r
+\r
+# #endif /* $1 */\r
+\r
+# From version 0.6, snippets expansions are run with some special\r
+# Emacs-lisp variables bound. One of this is ``yas/selected-text``. You\r
+# can therefore define a snippet like:\r
+\r
+# .. sourcecode:: text\r
+\r
+# for ($1;$2;$3) {\r
+# `yas/selected-text`$0\r
+# }\r
+\r
+# to "wrap" the selected region inside your recently inserted\r
+# snippet. Alternatively, you can also customize the variable\r
+# ``yas/wrap-around-region`` to ``t`` which will do this automatically.\r
+\r
+# Tab stop fields\r
+# ---------------\r
+\r
+# Tab stops are fields that you can navigate back and forth by ``TAB``\r
+# and ``S-TAB``. They are written by ``$`` followed with a\r
+# number. ``$0`` has the special meaning of the *exit point* of a\r
+# snippet. That is the last place to go when you've traveled all the\r
+# fields. Here's a typical example:\r
+\r
+# .. sourcecode:: text\r
+\r
+# <div$1>\r
+# $0\r
+# </div>\r
+\r
+# Placeholder fields\r
+# ------------------\r
+\r
+# Tab stops can have default values -- a.k.a placeholders. The syntax is\r
+# like this:\r
+\r
+# .. sourcecode:: text\r
+\r
+# ${N:default value}\r
+\r
+# They acts as the default value for a tab stop. But when you firstly\r
+# type at a tab stop, the default value will be replaced by your\r
+# typing. The number can be omitted if you don't want to create\r
+# `mirrors`_ or `transformations`_ for this field.\r
+\r
+# .. _mirrors:\r
+\r
+# Mirrors\r
+# -------\r
+\r
+# We refer the tab stops with placeholders as a *field*. A field can have\r
+# mirrors. Its mirrors will get updated when you change the text of a\r
+# field. Here's an example:\r
+\r
+# .. sourcecode:: text\r
+\r
+# \begin{${1:enumerate}}\r
+# $0\r
+# \end{$1}\r
+\r
+# When you type ``"document"`` at ``${1:enumerate}``, the word\r
+# ``"document"`` will also be inserted at ``\end{$1}``. The best\r
+# explanation is to see the screencast(`YouTube\r
+# <http://www.youtube.com/watch?v=vOj7btx3ATg>`_ or `avi video\r
+# <http://yasnippet.googlecode.com/files/yasnippet.avi>`_).\r
+\r
+# The tab stops with the same number to the field act as its mirrors. If\r
+# none of the tab stops has an initial value, the first one is selected\r
+# as the field and others mirrors.\r
+\r
+# .. _transformations:\r
+\r
+# Mirrors with transformations\r
+# ----------------------------\r
+\r
+# If the value of an ``${n:``-construct starts with and contains ``$(``,\r
+# then it is interpreted as a mirror for field ``n`` with a\r
+# transformation. The mirror's text content is calculated according to\r
+# this transformation, which is Emacs-lisp code that gets evaluated in\r
+# an environment where the variable ``text`` (or ``yas/text``) is bound\r
+# to the text content (string) contained in the field ``n``.Here's an\r
+# example for Objective-C:\r
+\r
+# .. sourcecode:: text\r
+\r
+# - (${1:id})${2:foo}\r
+# {\r
+# return $2;\r
+# }\r
+\r
+# - (void)set${2:$(capitalize text)}:($1)aValue\r
+# {\r
+# [$2 autorelease];\r
+# $2 = [aValue retain];\r
+# }\r
+# $0\r
+\r
+# Look at ``${2:$(capitalize text)}``, it is a mirror with\r
+# transformation instead of a field. The actual field is at the first\r
+# line: ``${2:foo}``. When you type text in ``${2:foo}``, the\r
+# transformation will be evaluated and the result will be placed there\r
+# as the transformed text. So in this example, if you type "baz" in the\r
+# field, the transformed text will be "Baz". This example is also\r
+# available in the screencast.\r
+\r
+# Another example is for ``rst-mode``. In reStructuredText, the document\r
+# title can be some text surrounded by "===" below and above. The "==="\r
+# should be at least as long as the text. So\r
+\r
+# .. sourcecode:: text\r
+\r
+# =====\r
+# Title\r
+# =====\r
+\r
+# is a valid title but\r
+\r
+# .. sourcecode:: text\r
+\r
+# ===\r
+# Title\r
+# ===\r
+\r
+# is not. Here's an snippet for rst title:\r
+\r
+# .. sourcecode:: text\r
+\r
+# ${1:$(make-string (string-width text) ?\=)}\r
+# ${1:Title}\r
+# ${1:$(make-string (string-width text) ?\=)}\r
+\r
+# $0\r
+\r
+# Fields with transformations\r
+# ---------------------------\r
+\r
+# From version 0.6 on, you can also have lisp transformation inside\r
+# fields. These work mostly mirror transformations but are evaluated\r
+# when you first enter the field, after each change you make to the\r
+# field and also just before you exit the field.\r
+\r
+# The syntax is also a tiny bit different, so that the parser can\r
+# distinguish between fields and mirrors. In the following example\r
+\r
+# .. sourcecode:: text\r
+\r
+# #define "${1:mydefine$(upcase yas/text)}"\r
+\r
+# ``mydefine`` gets automatically upcased to ``MYDEFINE`` once you enter\r
+# the field. As you type text, it gets filtered through the\r
+# transformation every time.\r
+\r
+# Note that to tell this kind of expression from a mirror with a\r
+# transformation, YASnippet needs extra text between the ``:`` and the\r
+# transformation's ``$``. If you don't want this extra-text, you can use\r
+# two ``$``'s instead.\r
+\r
+# .. sourcecode:: text\r
+\r
+# #define "${1:$$(upcase yas/text)}"\r
+\r
+# Please note that as soon as a transformation takes place, it changes\r
+# the value of the field and sets it its internal modification state to\r
+# ``true``. As a consequence, the auto-deletion behaviour of normal\r
+# fields does not take place. This is by design.\r
+\r
+# Choosing fields value from a list and other tricks\r
+# --------------------------------------------------\r
+\r
+# As mentioned, the field transformation is invoked just after you enter\r
+# the field, and with some useful variables bound, notably\r
+# ``yas/modified-p`` and ``yas/moving-away-p``. Because of this\r
+# feature you can place a transformation in the primary field that lets\r
+# you select default values for it.\r
+\r
+# The ``yas/choose-value`` does this work for you. For example:\r
+\r
+# .. sourcecode:: text\r
+\r
+# <div align="${2:$$(yas/choose-value '("right" "center" "left"))}">\r
+# $0\r
+# </div>\r
+\r
+# See the definition of ``yas/choose-value`` to see how it was written\r
+# using the two variables.\r
+\r
+# Here's another use, for LaTeX-mode, which calls reftex-label just as\r
+# you enter snippet field 2. This one makes use of ``yas/modified-p``\r
+# directly.\r
+\r
+# .. sourcecode:: text\r
+\r
+# \section{${1:"Titel der Tour"}}%\r
+# \index{$1}%\r
+# \label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-\r
+# insert))}}%\r
+\r
+# The function ``yas/verify-value`` has another neat trick, and makes\r
+# use of ``yas/moving-away-p``. Try it and see! Also, check out this\r
+# `thread\r
+# <http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662>`_\r
+\r
+# Nested placeholder fields\r
+# -------------------------\r
+\r
+# From version 0.6 on, you can also have nested placeholders of the type:\r
+\r
+# .. sourcecode:: text\r
+\r
+# <div${1: id="${2:some_id}"}>$0</div>\r
+\r
+# This allows you to choose if you want to give this ``div`` an ``id``\r
+# attribute. If you tab forward after expanding it will let you change\r
+# "some_id" to whatever you like. Alternatively, you can just press\r
+# ``C-d`` (which executes ``yas/skip-and-clear-or-delete-char``) and go\r
+# straight to the exit marker.\r
+\r
+# By the way, ``C-d`` will only clear the field if you cursor is at the\r
+# beginning of the field *and* it hasn't been changed yet. Otherwise, it\r
+# performs the normal Emacs ``delete-char`` command.\r
+\r
+# Customizable variables\r
+# ======================\r
+\r
+# ``yas/trigger-key``\r
+# -------------------\r
+\r
+# The key bound to ``yas/expand`` when function ``yas/minor-mode`` is\r
+# active.\r
+\r
+# Value is a string that is converted to the internal Emacs key\r
+# representation using ``read-kbd-macro``.\r
+\r
+# Default value is ``"TAB"``.\r
+\r
+# ``yas/next-field-key``\r
+# ----------------------\r
+\r
+# The key to navigate to next field when a snippet is active.\r
+\r
+# Value is a string that is converted to the internal Emacs key\r
+# representation using ``read-kbd-macro``.\r
+\r
+# Can also be a list of keys.\r
+\r
+# Default value is ``"TAB"``.\r
+\r
+# ``yas/prev-field-key``\r
+# ----------------------\r
+\r
+# The key to navigate to previous field when a snippet is active.\r
+\r
+# Value is a string that is converted to the internal Emacs key\r
+# representation using ``read-kbd-macro``.\r
+\r
+# Can also be a list of keys.\r
+\r
+# Default value is ``("<backtab>" "<S-tab>)"``.\r
+\r
+# ``yas/skip-and-clear-key``\r
+# --------------------------\r
+\r
+# The key to clear the currently active field.\r
+\r
+# Value is a string that is converted to the internal Emacs key\r
+# representation using ``read-kbd-macro``.\r
+\r
+# Can also be a list of keys.\r
+\r
+# Default value is ``"C-d"``.\r
+\r
+# ``yas/good-grace``\r
+# ------------------\r
+\r
+# If non-nil, don't raise errors in inline Emacs-lisp evaluation inside\r
+# snippet definitions. An error string "[yas] error" is returned instead.\r
+\r
+# ``yas/indent-line``\r
+# -------------------\r
+\r
+# The variable ``yas/indent-line`` controls the indenting. It is bound\r
+# to ``'auto`` by default, which causes your snippet to be indented\r
+# according to the mode of the buffer it was inserted in.\r
+\r
+# Another variable ``yas/also-auto-indent-first-line``, when non-nil\r
+# does exactly that :-).\r
+\r
+# To use the hard-coded indentation in your snippet template, set this\r
+# variable to ``fixed``.\r
+\r
+# To control indentation on a per-snippet basis, see also the directive\r
+# ``# expand-env:`` in `Writing Snippets`_.\r
+\r
+# For backward compatibility with earlier versions of YASnippet, you can\r
+# also place a ``$>`` in your snippet, an ``(indent-according-to-mode)``\r
+# will be executed there to indent the line. This only takes effect when\r
+# ``yas/indent-line`` is set to something other than ``'auto``.\r
+\r
+# .. sourcecode:: text\r
+\r
+# for (${int i = 0}; ${i < 10}; ${++i})\r
+# {$>\r
+# $0$>\r
+# }$>\r
+\r
+# ``yas/wrap-around-region``\r
+# --------------------------\r
+\r
+# If non-nil, YASnippet will try to expand the snippet's exit marker\r
+# around the currently selected region. When this variable is set to t,\r
+# this has the same effect has using the ```yas/selected-text``` inline\r
+# evaluation.\r
+\r
+# Because on most systems starting to type deletes the currently\r
+# selected region, this works mostly for snippets with direct\r
+# keybindings or with the ``yas/insert-snippet`` command.\r
+\r
+# However, when the value is of this variable is ``cua`` YASnippet will\r
+# additionally look-up any recently selected that you deleted by starting\r
+# typing. This allows you select a region, type a snippet key (deleting\r
+# the region), then press ``yas/trigger-key`` to see the deleted region\r
+# spring back to life inside your new snippet.\r
+\r
+# ``yas/triggers-in-field``\r
+# --------------------------\r
+\r
+# If non-nil, ``yas/next-field-key`` can trigger stacked expansions,\r
+# that is a snippet expansion inside another snippet\r
+# expansion. Otherwise, ``yas/next-field-key`` just tries to move on to\r
+# the next field.\r
+\r
+# ``yas/snippet-revival``\r
+# -----------------------\r
+\r
+# Non-nil means re-activate snippet fields after undo/redo.\r
+\r
+# ``yas/after-exit-snippet-hook`` and ``yas/before-expand-snippet-hook``\r
+# ----------------------------------------------------------------------\r
+\r
+# These hooks are called, respectively, before the insertion of a\r
+# snippet and after exiting the snippet. If you find any strange but\r
+# functional use for them, that's probably a design flaw in YASnippet,\r
+# so let us know.\r
+\r
+# Importing TextMate snippets\r
+# ===========================\r
+\r
+# There are a couple of tools that take TextMate's ".tmSnippet" xml\r
+# files and create YASnippet definitions:\r
+\r
+# * `a python script by Jeff Wheeler\r
+# <http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py>`_\r
+\r
+# * a `ruby tool\r
+# <http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb>`_\r
+# , ``textmate_import.rb`` adapted from `Rob Christie's\r
+# <http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/>`_,\r
+# which I have uploaded to the repository.\r
+\r
+# In this section, i'll shortly cover the **second** option.\r
+\r
+# Download the ``textmate_import.rb`` tool and the TextMate\r
+# bundle you're interested in.\r
+\r
+# .. sourcecode:: text\r
+\r
+# $ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb\r
+# $ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/\r
+\r
+\r
+# Then invoke ``textmate_import.rb`` like this:\r
+\r
+# .. sourcecode:: text\r
+\r
+# $ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist\r
+\r
+# You should end up with a ``html-mode`` subdir containing snippets\r
+# exported from textmate.\r
+\r
+# .. sourcecode:: text\r
+\r
+# $ tree html-mode # to view dir contents, if you have 'tree' installed\r
+\r
+# The ``-g`` is optional but helps the tool figure out the grouping.\r
+# According to `Organizing Snippets`_, don't forget to touch\r
+# ``.yas-make-groups`` and ``.yas-ignore-filename-triggers`` inside the\r
+# ``html-mode`` dir.\r
+\r
+# Also try ``textmate_import.rb --help`` for a list of options.\r
+\r
+# Please note that snippet importation is not yet perfect. You'll\r
+# probably have some adjustments to some/many snippets. Please\r
+# contribute these adjustments to the google group or, better yet, patch\r
+# the ``textmate_import.rb`` to automatically perform them and submit\r
+# that.\r
+\r
+# .. LocalWords: html YASnippet yas sourcecode pluskid init filenames filename\r
+# .. LocalWords: env varlist keybinding keymap rinari ifndef upcase endif\r
+# .. LocalWords: nondirectory autorelease aValue inline\r
+\r
+# * snippet-menu.org\r
+# ==============\r
+# YASnippet menu\r
+# ==============\r
+\r
+# .. contents::\r
+\r
+# When ``yas/minor-mode`` is active, YASnippet will setup a menu just\r
+# after the "Buffers" menu in the menubar.\r
+\r
+# In this menu, you can find\r
+\r
+# \* The currently loaded snippet definitions, organized by major mode,\r
+# and optional grouping.\r
+\r
+# \* A rundown of the most common commands, (followed by their\r
+# keybindings) including commands to load directories and reload all\r
+# snippet definitions.\r
+\r
+# \* A series of submenus for customizing and exploring YASnippet\r
+# behavior.\r
+\r
+# .. image:: images/menu-1.png\r
+# :align: right\r
+\r
+# Loading snippets from menu\r
+# --------------------------\r
+\r
+# Invoking "Load snippets..." from the menu invokes\r
+# ``yas/load-directory`` and prompts you for a snippet directory\r
+# hierarchy to load.\r
+\r
+# Also useful is the "Reload all" options which uncondionally reloads\r
+# all the snippets directories defined in ``yas/root-directory`` and\r
+# rebuilds the menus.\r
+\r
+# Snippet menu behavior\r
+# ---------------------\r
+\r
+# YASnippet will list in this section all the loaded snippet definitions\r
+# organized by snippet table name.\r
+\r
+# You can use this section to explore currently loaded snippets. If you\r
+# click on one of them, the default behavior is to expand it,\r
+# unconditionally, inside the current buffer.\r
+\r
+# You can however, customize variable ``yas/visit-from-menu`` to be\r
+# ``t`` which will take you to the snippet definition file when you\r
+# select it from the menu.\r
+\r
+# If you want the menu show only snippet tables whose name corresponds\r
+# to a "real" major mode. You do this by setting ``yas/use-menu`` to\r
+# ``'real-modes``.\r
+\r
+# Finally, to have the menu show only the tables for the currently\r
+# active mode, set ``yas/use-menu`` to ``abbreviate``.\r
+\r
+# These customizations can also be found in the menu itself, under the\r
+# "Snippet menu behavior" submenu.\r
+\r
+\r
+# Controlling indenting\r
+# ---------------------\r
+\r
+# The "Indenting" submenu contains options to control the values of\r
+# ``yas/indent-line`` and ``yas/also-auto-indent-first-line``. See\r
+# `Writing snippets <snippet-development.html>`_ .\r
+\r
+# Prompting method\r
+# ----------------\r
+\r
+# The "Prompting method" submenu contains options to control the value\r
+# of ``yas/prompt-functions``. See `Expanding snippets <snippet-expansion.html>`_ .\r
+\r
+# Misc\r
+# ----\r
+\r
+# The "Misc" submenu contains options to control the values of more\r
+# variables.\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+# * faq.org\r
+# ============================\r
+# Frequently Asked Questions\r
+# ============================\r
+\r
+# Why is there an extra newline?\r
+# ==============================\r
+\r
+# If you have a newline at the end of the snippet definition file, then\r
+# YASnippet will add a newline when you expanding a snippet. Please\r
+# don't add a newline at the end if you don't want it when you saving\r
+# the snippet file.\r
+\r
+# Note some editors will automatically add a newline for you. In Emacs,\r
+# if you set ``require-final-newline`` to ``t``, it will add the final\r
+# newline for you automatically.\r
+\r
+# Why doesn't TAB expand a snippet?\r
+# =================================\r
+\r
+# First check the mode line to see if there's ``yas``. If not, then try\r
+# ``M-x yas/minor-mode`` to manually turn on the minor mode and try to\r
+# expand the snippet again. If it works, then, you can add the following\r
+# code to your ``.emacs`` *before* loading YASnippet:\r
+\r
+# .. sourcecode:: lisp\r
+\r
+# (add-hook 'the-major-mode-hook 'yas/minor-mode-on)\r
+\r
+# where ``the-major-mode`` is the major mode in which ``yas/minor-mode``\r
+# isn't enabled by default.\r
+\r
+# From YASnippet 0.6 you can also use the command ``M-x\r
+# yas/global-mode`` to turn on YASnippet automatically for *all* major\r
+# modes.\r
+\r
+# If ``yas/minor-mode`` is on but the snippet still not expanded. Then\r
+# try to see what command is bound to the ``TAB`` key: press ``C-h k``\r
+# and then press ``TAB``. Emacs will show you the result.\r
+\r
+# You'll see a buffer prompted by Emacs saying that ``TAB runs the\r
+# command ...``. Alternatively, you might see ``<tab> runs the command\r
+# ...``, note the difference between ``TAB`` and ``<tab>`` where the\r
+# latter has priority. If you see ``<tab>`` bound to a command other\r
+# than ``yas/expand``, (e.g. in ``org-mode``) you can try the following\r
+# code to work around:\r
+\r
+# .. sourcecode:: lisp\r
+\r
+# (add-hook 'org-mode-hook\r
+# (let ((original-command (lookup-key org-mode-map [tab])))\r
+# `(lambda ()\r
+# (setq yas/fallback-behavior\r
+# '(apply ,original-command))\r
+# (local-set-key [tab] 'yas/expand))))\r
+\r
+# replace ``org-mode-hook`` and ``org-mode-map`` with the major mode\r
+# hook you are dealing with (Use ``C-h m`` to see what major mode you\r
+# are in).\r
+\r
+# As an alternative, you can also try\r
+\r
+# .. sourcecode:: lisp\r
+\r
+# (defun yas/advise-indent-function (function-symbol)\r
+# (eval `(defadvice ,function-symbol (around yas/try-expand-first activate)\r
+# ,(format\r
+# "Try to expand a snippet before point, then call `%s' as usual"\r
+# function-symbol)\r
+# (let ((yas/fallback-behavior nil))\r
+# (unless (and (interactive-p)\r
+# (yas/expand))\r
+# ad-do-it)))))\r
+\r
+# (yas/advise-indent-function 'ruby-indent-line)\r
+\r
+# To *advise* the modes indentation function bound to TAB, (in this case\r
+# ``ruby-indent-line``) to first try to run ``yas/expand``.\r
+\r
+# If the output of ``C-h k RET <tab>`` tells you that ``<tab>`` is\r
+# indeed bound to ``yas/expand`` but YASnippet still doesn't work, check\r
+# your configuration and you may also ask for help on the `discussion\r
+# group <http://groups.google.com/group/smart-snippet>`_. See this\r
+# particular `thread\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=93&can=1>`_ for\r
+# quite some solutions and alternatives.\r
+\r
+# Don't forget to attach the information on what command is bound to TAB\r
+# as well as the mode information (Can be obtained by ``C-h m``).\r
+\r
+# Why doesn't TAB navigation work with flyspell\r
+# =============================================\r
+\r
+# A workaround is to inhibit flyspell overlays while the snippet is active:\r
+\r
+# .. sourcecode:: lisp\r
+\r
+# (add-hook 'flyspell-incorrect-hook\r
+# #'(lambda (dummy1 dummy2 dymmy3)\r
+# (and yas/active-field-overlay\r
+# (overlay-buffer yas/active-field-overlay))))\r
+\r
+# This is apparently related to overlay priorities. For some reason, the\r
+# ``keymap`` property of flyspell's overlays always takes priority over\r
+# the same property in yasnippet's overlays, even if one sets the\r
+# latter's ``priority`` property to something big. If you know\r
+# emacs-lisp and can solve this problem, drop a line in the `discussion\r
+# group`_.\r
+\r
+# How do I turn off the minor mode where in some buffers\r
+# ======================================================\r
+\r
+# The best way, since version 0.6.1c, is to set the default value of the\r
+# variable ``yas/dont-activate`` to a lambda function like so:\r
+\r
+# .. sourcecode:: lisp\r
+\r
+# (set-default 'yas/dont-activate\r
+# #'(lambda ()\r
+# (and yas/root-directory\r
+# (null (yas/get-snippet-tables)))))\r
+\r
+# This is also the default value starting for that version. It skips the\r
+# minor mode in buffers where it is not applicable (no snippet tables),\r
+# but only once you have setup your yas/root-directory.\r
+\r
+\r
+# How do I define an abbrev key containing characters not supported by the filesystem?\r
+# ====================================================================================\r
+\r
+# \**Note**: This question applies if you're still defining snippets\r
+# whose key *is* the filename. This is behavior stil provided by\r
+# version 0.6 for backward compatibilty, but is somewhat deprecated...\r
+\r
+# For example, you want to define a snippet by the key ``<`` which is\r
+# not a valid character for filename on Windows. This means you can't\r
+# use the filename as a trigger key in this case.\r
+\r
+# You should rather use the ``# key:`` directive to specify the key of\r
+# the defined snippet explicitly and name your snippet with an arbitrary\r
+# valid filename, ``lt.yasnippet`` for example, using ``<`` for the\r
+# ``# key:`` directive:\r
+\r
+# .. sourcecode:: text\r
+\r
+# # key: <\r
+# # name: <...></...>\r
+# # --\r
+# <${1:div}>$0</$1>\r
+\r
+# .. _discussion group: http://groups.google.com/group/smart-snippet\r
+\r
+# * changelog.org\r
+# =========\r
+# ChangeLog\r
+# =========\r
+\r
+# .. _Organizing Snippets: snippet-organization.html\r
+# .. _Expanding Snippets: snippet-expansion.html\r
+# .. _Writing Snippets: snippet-development.html\r
+# .. _The YASnippet Menu: snippet-menu.html\r
+\r
+# 0.7.0b / ????-??-??\r
+# ===================\r
+\r
+# \* Filenames can no longer be snippet triggers. Please upgrade your snippet\r
+# collections.\r
+\r
+\r
+# 0.6.1c / 2009-08-13\r
+# ===================\r
+\r
+# \* Fixed `issues <http://code.google.com/p/yasnippet/issues>`_ 99, 98, 93,\r
+# 90, 91, 88, 87. Thanks everybody.\r
+# \* More compliant customization group `Issue94\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=94>`_, (thanks\r
+# wyuenho).\r
+# \* Added workaround for issue 97 in the FAQ\r
+# \* Small updates to documentation.\r
+\r
+# 0.6.1b / 2009-08-29\r
+# ===================\r
+\r
+# \* Much more powerful menu. See `The YASnippet menu`_.\r
+# \* New ways to organize snippets. See `Organizing snippets`_.\r
+# \* Added ``yas/also-auto-indent-first-line`` customization variable.\r
+# \* Renamed directive ``# env:`` to ``# expand-env:``\r
+# \* Rewrote much of the documentation.\r
+# \* Added TextMate import tool ``textmate-import.rb`` to to svn\r
+# repository (see "extras/")\r
+# \* Added *experimental* bundle of textmate snippets\r
+# ``yasnippet-textmate-bundle.el``\r
+# \* Fixed `Issue 74\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=74>`_ (thanks\r
+# rmartin.k...@gmail.com)\r
+# \* Fixed `Issues 80 through 84\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=80>`_ (thanks\r
+# Moritz Bunkus)\r
+# \* Fixed many more issues...\r
+\r
+\r
+# 0.6.0c / 2009-07-27\r
+# ===================\r
+\r
+# \* Now byte compiles correctly with no warnings.\r
+# \* Fixed `Issue 68\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=68>`_ with\r
+# mouse-clicking alternatives in ``ido-mode``.\r
+# \* Added ``yas/also-auto-indent-first-line`` customization variable.\r
+\r
+\r
+# 0.6.0b / 2009-07-25\r
+# ===================\r
+\r
+# \* Nested placeholders of the type ``<div${1: id="${2:someid}"}> $0``.\r
+\r
+# \* More robust undo/redo support.\r
+\r
+# \* Stacked snippet expansion (*snippet in snippet*).\r
+\r
+# \* Transformation on a primary field with syntax ``${1:default$(transform)}``\r
+\r
+# \* Validations on field exit through the ``yas/verify-value``\r
+# primary field transformation.\r
+\r
+# \* Wrapping the region in the exit marker ``$0`` of the snippet. Use\r
+# ``yas/wrap-around-region``.\r
+\r
+# \* Auto-indentation. Use ``yas/indent-line`` set to ``'auto``\r
+\r
+# \* Easier definition of snippets. Use ``yas/find-snippets`` or\r
+# ``yas/visit-snippet-file``. In the new ``snippet-mode`` use\r
+# ``yas/load-snippet-buffer`` and ``yas/tryout-snippet``.\r
+\r
+# \* Customization group ``yasnippet``.\r
+\r
+# \* Overriding customization variables in snippets. Use the ``env:\r
+# let-form`` template keyword.\r
+\r
+# \* Fixed `Issue 60\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=60>`_\r
+# \* Fixed `Issue 65\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=65>`_\r
+# \* Fixed `Issue 56\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=56>`_\r
+\r
+# 0.5.10 / 2009-02-11\r
+# ===================\r
+\r
+# \* Added *grouping* support so that the snippets in the menu can be\r
+# groupped together.\r
+# \* Make the bundle `ELPA <http://tromey.com/elpa/index.html>`_\r
+# compatible.\r
+\r
+# 0.5.9 / 2009-01-21\r
+# ==================\r
+\r
+# \* Fixed the bug of disabling the auto-indenting of ``cc-mode``.\r
+\r
+# 0.5.8 / 2009-01-15\r
+# ==================\r
+\r
+# \* Added a ``key`` property in snippet definition for snippet names\r
+# that are not valid path name.\r
+# \* Fixed some bugs of indenting (`Issue 44\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=44>`_, `Issue\r
+# 46 <http://code.google.com/p/yasnippet/issues/detail?id=46>`_).\r
+# \* Fixed `Issue 45\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=45>`_ by\r
+# providing a proper default value for ``yas/buffer-local-condition``.\r
+# \* Added helper function ``yas/substr`` for convenient mirror\r
+# transformation.\r
+# \* Make variable ``yas/registered-snippet`` properly initialized.\r
+# \* Fixed the overlay error when overlay becomes empty (`Issue 49\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=49>`_ and\r
+# `Issue 48\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=48>`_). This\r
+# bug has occurred and been fixed earlier, and should not have\r
+# happened if we have proper regression test.\r
+# \* Added a workaround for ``c-electric-`` serial commands (`Issue 27\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=27>`_).\r
+\r
+# 0.5.7 / 2008-12-03\r
+# ==================\r
+\r
+# \* Fixed `Issue 28\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=28>`_ of\r
+# properly clean up snippet (by joaotavora).\r
+# \* Added a new section "Field-level undo functionality" to correct\r
+# `Issue 33 <http://code.google.com/p/yasnippet/issues/detail?id=33>`_\r
+# (by joaotavora).\r
+# \* Added some snippets from users for sql, erlang, scala, html, xml, latex, etc.\r
+# \* Fixed `Issue 16\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=16>`_ by adding\r
+# ``$>`` support. Here's the `doc for $> indenting\r
+# <http://pluskid.lifegoo.com/upload/project/yasnippet/doc/define_snippet.html#indenting>`_.\r
+\r
+# 0.5.6 / 2008-08-07\r
+# ==================\r
+\r
+# \* Added a buffer local variable ``yas/dont-activate`` to turn off\r
+# ``yas/minor-mode`` in some major modes. See `Issue 29\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=29>`_.\r
+# \* Make the environment of elisp evaluation more friendly to\r
+# ``(current-column)``.\r
+# \* Fixed the regular expression bug in python-mode snippets.\r
+# \* Use filename or full key extension for snippet name if no ``name``\r
+# property is defined.\r
+\r
+# 0.5.5 / 2008-05-29\r
+# ==================\r
+\r
+# \* Tweak ``yas/extra-mode-hooks`` so that it can be more easily\r
+# customized.\r
+# \* Add an entry in FAQ about why ``TAB`` key doesn't work in some\r
+# modes.\r
+\r
+# 0.5.4 / 2008-05-15\r
+# ==================\r
+\r
+# \* Added ``ox-mode-hook`` and ``python-mode-hook`` to\r
+# ``yas/extra-mode-hooks`` to fix the problem YASnippet is not enabled\r
+# in those modes.\r
+\r
+# 0.5.3 / 2008-05-07\r
+# ==================\r
+\r
+# \* Fix indent of python-mode snippets.\r
+# \* Fix a bug of dropdown-list: conflicts with color-theme (`Issue 23\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=23>`_). Thanks\r
+# Mike.\r
+# \* Fix a bug of condition system.\r
+\r
+# 0.5.2 / 2008-04-20\r
+# ==================\r
+\r
+# \* Fix a bug for comparing string to symbol using ``string=`` (which\r
+# will fire an error).\r
+\r
+# 0.5.1 / 2008-04-14\r
+# ==================\r
+\r
+# \* Use a beautiful css style in the document.\r
+\r
+# 0.5.0 / 2008-04-10\r
+# ==================\r
+\r
+# \* Integrate with hippie-expand. Just add ``yas/hippie-try-expand`` to\r
+# ``hippie-expand-try-functions-list``.\r
+# \* If you set ``yas/fall-back-behavior`` to ``'return-nil``, YASnippet\r
+# will return nil when it can't find a snippet to expand.\r
+# \* Defect fix: the condition of a snippet was evaluated twice in\r
+# earlier version.\r
+# \* Deleting snippet (using ``C-w`` or ``C-k``) won't cause serious\r
+# problem now.\r
+# \* Several complex snippet for python-mode from Yasser included in the\r
+# distribution.\r
+\r
+# 0.4.5 / 2008-04-07\r
+# ==================\r
+\r
+# \* Merge the latest dropdown-list.el.\r
+# \* Add snippets for f90-mode from Li Zhu.\r
+# \* Bug fix: l-safe-expr-p: Lisp nesting exceeds ``max-lisp-eval-depth``\r
+# error when several (more than two) snippets overlaps. Thanks\r
+# sunwaybupt@newsmth for reporting this bug.\r
+\r
+# 0.4.4 / 2008-03-24\r
+# ==================\r
+\r
+# \* Bug fix: dropdown-list.el doesn't recognize [return] properly.\r
+\r
+# 0.4.3 / 2008-03-23\r
+# ==================\r
+\r
+# \* Bug fix: failed to recognize user customized yas/trigger-key.\r
+\r
+# 0.4.2 / 2008-03-22\r
+# ==================\r
+\r
+# \* Make a separate document package for release. Also make document\r
+# available online.\r
+\r
+# 0.4.1 / 2008-03-21\r
+# ==================\r
+\r
+# \* Make sure ``yas/minor-mode``'s key bindings always take priority to\r
+# other minor modes.\r
+\r
+# 0.4.0 / 2008-03-20\r
+# ==================\r
+\r
+# \* Document refinement and released with YASnippet. Most of the Online\r
+# wiki document will be deprecated soon.\r
+# \* Powerful condition system added to yasnippet!\r
+# \* Incorporate ``dropdown-list.el`` and make it default way for\r
+# selecting multiple candidates. Thanks to `Jaeyoun Chung\r
+# <http://groups.google.com/group/smart-snippet/browse_thread/thread/c869158b76addeb3/e7c6372ba457189e>`_.\r
+# \* yas/before-expand-snippet-hook\r
+\r
+# 0.3.2 / 2008-03-19\r
+# ==================\r
+\r
+# \* Enhancement: A better way to define minor-mode. Thanks to Kentaro\r
+# Kuribayashi. See `this thread\r
+# <https://groups.google.com/group/smart-snippet/browse_thread/thread/65cb3b5583eda887?hl=en>`_\r
+# for more details.\r
+\r
+# 0.3.1 / 2008-03-17\r
+# ==================\r
+\r
+# \* Bug fix: Emacs get confused when a field is deleted. See `issue 10\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=10>`_.\r
+\r
+# 0.3.0 / 2008-03-16\r
+# ==================\r
+\r
+# \* Add a ``yas/after-exit-snippet-hook`` so that you can do something like\r
+# ``indent-region`` or ``fill-region`` after finish the snippet.\r
+# \* Use minor-mode instead of ``global-set-key`` to bind the trigger\r
+# key. Now the trigger key and fall-back behavior can be more\r
+# flexible. Not constrained to ``<tab>``. Thanks to Trey Jackson. See\r
+# this `thread\r
+# <https://groups.google.com/group/smart-snippet/browse_thread/thread/937f32a2a6dea4f2?hl=en>`_\r
+# for more details.\r
+# \* Now user can customize the popup function for selecting multiple\r
+# candidate for the same snippet key.\r
+# \* Support ``dropdown-list.el`` to be a better way to select multiple\r
+# candidate when in text mode.\r
+\r
+# 0.2.3 / 2008-03-15\r
+# ==================\r
+\r
+# \* Bug in non-window (-nw) mode when there's multiple candidate to\r
+# expand. See `issue 7\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=7>`_.\r
+# \* Allow expanding another snippet as long as not currently inside a\r
+# field.\r
+\r
+# 0.2.2 / 2008-03-13\r
+# ==================\r
+\r
+# \* Added customized face for fields and mirrors. Better in dark\r
+# background. And users can customize it.\r
+\r
+# 0.2.1 / 2008-03-10\r
+# ==================\r
+\r
+# \* Fix the insert-behind problem under both Emacs 22 and Emacs 23.\r
+\r
+# 0.2.0 / 2008-03-10\r
+# ==================\r
+\r
+# \* Use big keymap overlay to detect ``insert-behind`` event manually to\r
+# avoid sometimes missed hook calls. See `issue 3\r
+# <http://code.google.com/p/yasnippet/issues/detail?id=3>`_ for more\r
+# details.\r
+# \* Support parent snippet table. Now you can set (for example)\r
+# ``cc-mode`` as common mode for ``c++-mode``, ``c-mode`` and\r
+# ``java-mode``. They'll share snippets defined for ``cc-mode``.\r
+\r
+# 0.1.1 / 2008-03-08\r
+# ==================\r
+\r
+# \* Add a rake task to upload to google code.\r
+# \* Use elisp compile-bundle function instead of python scrip\r
+\r
+# 0.1.0 / 2008-03-07\r
+# ==================\r
+\r
+# \* Embedded elisp support.\r
+# \* Fields navigation support.\r
+# \* Mirror of fields support.\r
+# \* Menu-bar support.\r
+# \* Multiple snippets with same name support.\r
+# \* Popup menu for multiple snippet with same name support.\r
+# \* Transformation of fields support.\r
+# \* Load directory support.\r
+# \* Compile bundle support.\r
+++ /dev/null
-================
-Writing snippets
-================
-
-.. _Organizing Snippets: snippet-organization.html
-.. _Expanding Snippets: snippet-expansion.html
-.. _Writing Snippets: snippet-development.html
-.. _The YASnippet Menu: snippet-menu.html
-
-.. contents::
-
-Snippet development
-===================
-
-Quickly finding snippets
-------------------------
-
-There are some ways you can quickly find a snippet file:
-
-* ``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``
-
- 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``.
-
-* ``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.
-
-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-c`` by 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-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). 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:
-
-.. sourcecode:: text
-
- # 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 ``yas/trigger-key``. If you don't
-specify this the snippet will not be expandable through the key mechanism.
-
-``# name:`` snippet name
-------------------------
-
-This is a one-line description of the snippet. It will be displayed in
-the menu. It's a good idea to select a descriptive name for a
-snippet -- especially distinguishable among similar snippets.
-
-If you omit this name it will default to the file name the snippet was
-loaded from.
-
-``# condition:`` snippet condition
-----------------------------------
-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 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. ``control
-structure.loops`` tells that the snippet is under the ``loops`` 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 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 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))
- # --
- 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.
-
-.. sourcecode:: text
-
- # 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 paragraph tag newlines, just
-press ``C-u C-c C-c C-m``. Omitting the ``C-u`` will expand the
-paragraph tag without newlines.
-
-``# 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
-use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also
-needed to be escaped as ``\\`` sometimes.
-
-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:
-
-.. sourcecode:: text
-
- #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
-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
- }
-
-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.
-
-Tab stop fields
----------------
-
-Tab stops are fields that you can navigate back and forth by ``TAB``
-and ``S-TAB``. They are written by ``$`` followed with a
-number. ``$0`` has the special meaning of the *exit point* of a
-snippet. That is the last place to go when you've traveled all the
-fields. Here's a typical example:
-
-.. sourcecode:: text
-
- <div$1>
- $0
- </div>
-
-Placeholder fields
-------------------
-
-Tab stops can have default values -- a.k.a placeholders. The syntax is
-like this:
-
-.. sourcecode:: text
-
- ${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.
-
-.. _mirrors:
-
-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:
-
-.. sourcecode:: text
-
- \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
-<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ or `avi video
-<http://yasnippet.googlecode.com/files/yasnippet.avi>`_).
-
-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.
-
-.. _transformations:
-
-Mirrors with transformations
-----------------------------
-
-If the value of an ``${n:``-construct starts with and contains ``$(``,
-then it is interpreted as a mirror for field ``n`` with a
-transformation. The mirror's text content is calculated according to
-this transformation, which is Emacs-lisp code that gets evaluated in
-an environment where the variable ``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
-
- - (${1:id})${2:foo}
- {
- return $2;
- }
-
- - (void)set${2:$(capitalize text)}:($1)aValue
- {
- [$2 autorelease];
- $2 = [aValue retain];
- }
- $0
-
-Look at ``${2:$(capitalize text)}``, it is a mirror with
-transformation instead of a field. The actual field is at the first
-line: ``${2:foo}``. When you type text in ``${2:foo}``, the
-transformation will be evaluated and the result will be placed there
-as the 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 "==="
-should be at least as long as the text. So
-
-.. sourcecode:: text
-
- =====
- Title
- =====
-
-is a valid title but
-
-.. sourcecode:: text
-
- ===
- Title
- ===
-
-is not. Here's an snippet for rst title:
-
-.. sourcecode:: text
-
- ${1:$(make-string (string-width text) ?\=)}
- ${1:Title}
- ${1:$(make-string (string-width 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
-
-.. sourcecode:: 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.
-
-.. sourcecode:: 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
-``true``. As a consequence, the auto-deletion behaviour of normal
-fields does not take place. This is by design.
-
-Choosing fields value from a list and other tricks
---------------------------------------------------
-
-As mentioned, the field transformation is invoked just after you enter
-the field, and with some useful variables bound, notably
-``yas/modified-p`` and ``yas/moving-away-p``. Because of this
-feature you can place a transformation in the primary field that lets
-you select default values for it.
-
-The ``yas/choose-value`` does this work for you. For example:
-
-.. sourcecode:: text
-
- <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.
-
-.. sourcecode:: text
-
- \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
-<http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662>`_
-
-Nested placeholder fields
--------------------------
-
-From version 0.6 on, you can also have nested placeholders of the type:
-
-.. sourcecode:: text
-
- <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`` (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.
-
-Customizable variables
-======================
-
-``yas/trigger-key``
--------------------
-
-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
-representation using ``read-kbd-macro``.
-
-Default value is ``"TAB"``.
-
-``yas/next-field-key``
-----------------------
-
-The key to navigate to next field when a snippet is active.
-
-Value is a string that is converted to the internal Emacs key
-representation using ``read-kbd-macro``.
-
-Can also be a list of keys.
-
-Default value is ``"TAB"``.
-
-``yas/prev-field-key``
-----------------------
-
-The key to navigate to previous field when a snippet is active.
-
-Value is a string that is converted to the internal Emacs key
-representation using ``read-kbd-macro``.
-
-Can also be a list of keys.
-
-Default value is ``("<backtab>" "<S-tab>)"``.
-
-``yas/skip-and-clear-key``
---------------------------
-
-The key to clear the currently active field.
-
-Value is a string that is converted to the internal Emacs key
-representation using ``read-kbd-macro``.
-
-Can also be a list of keys.
-
-Default value is ``"C-d"``.
-
-``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``
--------------------
-
-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
-does exactly that :-).
-
-To use the hard-coded indentation in your snippet template, set this
-variable to ``fixed``.
-
-To control indentation on a per-snippet basis, see also the directive
-``# expand-env:`` in `Writing Snippets`_.
-
-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``.
-
-.. sourcecode:: text
-
- for (${int i = 0}; ${i < 10}; ${++i})
- {$>
- $0$>
- }$>
-
-``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
-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.
-
-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
-spring back to life inside your new snippet.
-
-``yas/triggers-in-field``
---------------------------
-
-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
-the next field.
-
-``yas/snippet-revival``
------------------------
-
-Non-nil means re-activate snippet fields after undo/redo.
-
-``yas/after-exit-snippet-hook`` and ``yas/before-expand-snippet-hook``
-----------------------------------------------------------------------
-
-These hooks are called, respectively, before the insertion of a
-snippet and after exiting the snippet. If you find any strange but
-functional use for them, that's probably a design flaw in YASnippet,
-so let us know.
-
-Importing TextMate snippets
-===========================
-
-There are a couple of tools that take TextMate's ".tmSnippet" xml
-files and create YASnippet definitions:
-
- * `a python script by Jeff Wheeler
- <http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py>`_
-
- * a `ruby tool
- <http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb>`_
- , ``textmate_import.rb`` adapted from `Rob Christie's
- <http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/>`_,
- which I have uploaded to the repository.
-
-In this section, i'll shortly cover the **second** option.
-
-Download the ``textmate_import.rb`` tool and the TextMate
-bundle you're interested in.
-
-.. sourcecode:: text
-
- $ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb
- $ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/
-
-
-Then invoke ``textmate_import.rb`` like this:
-
-.. sourcecode:: text
-
- $ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist
-
-You should end up with a ``html-mode`` subdir containing snippets
-exported from textmate.
-
-.. sourcecode:: text
-
- $ tree html-mode # to view dir contents, if you have 'tree' installed
-
-The ``-g`` is optional but helps the tool figure out the grouping.
-According to `Organizing Snippets`_, don't forget to touch
-``.yas-make-groups`` and ``.yas-ignore-filename-triggers`` inside the
-``html-mode`` dir.
-
-Also try ``textmate_import.rb --help`` for a list of options.
-
-Please note that snippet importation is not yet perfect. You'll
-probably have some adjustments to some/many snippets. Please
-contribute these adjustments to the google group or, better yet, patch
-the ``textmate_import.rb`` to automatically perform them and submit
-that.
-
-.. LocalWords: html YASnippet yas sourcecode pluskid init filenames filename
-.. LocalWords: env varlist keybinding keymap rinari ifndef upcase endif
-.. LocalWords: nondirectory autorelease aValue inline
+++ /dev/null
-==================
-Expanding snippets
-==================
-
-.. _Organizing Snippets: snippet-organization.html
-.. _Expanding Snippets: snippet-expansion.html
-.. _Writing Snippets: snippet-development.html
-.. _The YASnippet Menu: snippet-menu.html
-
-.. contents::
-
-
-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
- "TAB"). This works in buffers where the minor mode
- ``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 using the keybinding associated with an active snippet. This also
- requires ``yas/minor-mode`` to be active;
-
-* By expanding directly from the "YASnippet" menu in the menu-bar
-
-* By using hippie-expand
-
-* Expanding from emacs-lisp code
-
-Trigger key
------------
-
-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
-*snippet abbrev* (also known as *snippet key*) before point.
-
-The default key is ``"TAB"``, however, you can freely set it to some
-other key.
-
-.. image:: images/minor-mode-indicator.png
- :align: left
-
-To enable the YASnippet minor mode in all buffers globally use the
-command ``yas/global-mode``.
-
-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.
-
-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
-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``.
-
-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
-``'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
-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.
-
-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
-``hippie-expand-try-functions-list``. This probably makes more sense
-when placed at the top of the list, but it can be put anywhere you
-prefer.
-
-Expanding from emacs-lisp code
-------------------------------
-
-Sometimes you might want to expand a snippet directly from you own
-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
-YASnippet menu has the same effect of evaluating the follow code:
-
-.. sourcecode:: common-lisp
-
- (yas/expand-snippet template)
-
-See the internal documentation on ``yas/expand-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:
-
-* 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...
-
-* Major mode of the current buffer
-
- If the currrent major mode matches one of the loaded snippet tables,
- then all that table's snippets are considered for expansion. Use
- ``M-x describe-variable RET major-mode RET`` to find out which major
- mode you are in currently.
-
-* Parent tables
-
- Snippet tables defined as the parent of some other eligible table
- are also considered. This works recursively, i.e. parents of parents
- of eligible tables are also considered.
-
-* 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 ,
- like ``rinari-minor-mode``, you can have some snippets expand only
- in that minor mode. Naturally, you want to set this conditionally,
- i.e. only when entering that minor mode, so using a hook is a good
- idea.
-
-.. sourcecode:: common-lisp
-
- ;; When entering rinari-minor-mode, consider also the snippets in the
- ;; snippet table "rails-mode"
- (add-hook 'rinari-minor-mode-hook
- #'(lambda ()
- (setq yas/mode-symbol 'rails-mode)))
-
-* 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
- expand snippets inside comments or string literals for example. See
- `The condition system`_ for more info.
-
-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,
-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 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
-(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
- be considered for expansion.
-
-* If it evaluates to the a *cons cell* where the ``car`` is the symbol
- ``require-snippet-condition`` and the ``cdr`` is a symbol (let's
- call it ``requirement``), then:
-
- * Snippets having no ``# condition:`` directive won't be considered;
-
- * Snippets with conditions that evaluate to nil (or produce an
- error) won't be considered;
-
- * If the snippet has a condition that evaluates to non-nil (let's
- call it ``result``):
-
- * If ``requirement`` is ``t``, the snippet is ready to be
- expanded;
-
- * If ``requirement`` is ``eq`` to ``result``, the snippet is ready
- to be expanded;
-
- * Otherwise the snippet won't be considered.
-
-* If it evaluates to the symbol ``always``, all snippets are
- considered for expansion, regardless of any conditions.
-
-* If it evaluate to ``t`` or some other non-nil value:
-
- * If the snippet has no condition, or has a condition that evaluate
- to non-nil, it is ready to be expanded.
-
- * Otherwise, it won't be considered.
-
-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
- '(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 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.
-
-Multiples snippet with the same key
------------------------------------
-
-The rules outlined `above <Eligible snippets>`_ 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:
-
-.. sourcecode:: common-lisp
-
- (setq yas/prompt-functions '(yas/x-prompt yas/dropdown-prompt))
-
-Currently there are some alternatives solution with YASnippet.
-
-.. image:: images/x-menu.png
- :align: right
-
-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:
-
-* It usually looks beautiful. E.g. when you compile Emacs with gtk
- support, this menu will be rendered with your gtk theme.
-* Your window system may or may not allow to you use ``C-n``, ``C-p``
- to navigate this menu.
-* This function can't be used when in a terminal.
-
-.. image:: images/ido-menu.png
- :align: right
-
-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.
-
-.. image:: images/dropdown-menu.png
- :align: right
-
-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 below for the documentation on variable ``yas/prompt-functions``
-
-Customizable Variables
-======================
-
-``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;
-
-* CHOICES: A list of strings or objects;
-
-* optional DISPLAY-FN : A function. When applied to each of the
- objects in CHOICES it 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).
-
-* To signal that your particular style of prompting is unavailable at
- the moment, you can also have the function return nil.
-
-* To signal that the user quit the prompting process, you can signal
- ``quit`` with ``(signal 'quit "user quit!")``
-
-``yas/fallback-behavior``
--------------------------
-
-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``.
-
-``return-nil`` means return nil. (i.e. do nothing)
-
-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``
--------------------------
-
-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/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/key-syntaxes``
---------------------
-
-The default searching strategy is quite powerful. For example, in
-``c-mode``, ``bar``, ``foo_bar``, ``"#foo_bar"`` can all be recognized
-as a snippet key. Furthermore, the searching is in that order. In
-other words, if ``bar`` is found to be a key to some *valid* snippet,
-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
-default value is ``("w" "w_" "w_." "^ ")``. Which means search the
-following thing until found one:
-
-* a word.
-* a symbol. In lisp, ``-`` and ``?`` can all be part of a symbol.
-* a sequence of characters of either word, symbol or punctuation.
-* a sequence of characters of non-whitespace characters.
-
-But you'd better keep the default value unless you want to understand
-how Emacs's syntax rules work...
-
-