diff --git a/changelog.html b/changelog.html new file mode 100644 index 0000000..b6e1dfa --- /dev/null +++ b/changelog.html @@ -0,0 +1,388 @@ + + + + + + +ChangeLog + + + +
+
+
+
+ +
+
+
+
+

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

+
+

0.7.0b / ????-??-??

+
    +
  • Filenames can no longer be snippet triggers. Please upgrade your snippet +collections.
    • +
+
+
+

0.6.1c / 2009-08-13

+
    +
  • Fixed issues 99, 98, 93, +90, 91, 88, 87. Thanks everybody.
    • +
  • More compliant customization group Issue94, (thanks +wyuenho).
    • +
  • Added workaround for issue 97 in the FAQ
    • +
  • Small updates to documentation.
    • +
+
+
+

0.6.1b / 2009-08-29

+
    +
  • Much more powerful menu. See The YASnippet menu.
    • +
  • New ways to organize snippets. See Organizing snippets.
    • +
  • Added yas/also-auto-indent-first-line customization variable.
    • +
  • Renamed directive # env: to # expand-env:
    • +
  • Rewrote much of the documentation.
    • +
  • Added TextMate import tool textmate-import.rb to to svn +repository (see "extras/")
    • +
  • Added experimental bundle of textmate snippets +yasnippet-textmate-bundle.el
    • +
  • Fixed Issue 74 (thanks +rmartin.k...@gmail.com)
    • +
  • Fixed Issues 80 through 84 (thanks +Moritz Bunkus)
    • +
  • Fixed many more issues...
    • +
+
+
+

0.6.0c / 2009-07-27

+
    +
  • Now byte compiles correctly with no warnings.
    • +
  • Fixed Issue 68 with +mouse-clicking alternatives in ido-mode.
    • +
  • Added yas/also-auto-indent-first-line customization variable.
    • +
+
+
+

0.6.0b / 2009-07-25

+
    +
  • Nested placeholders of the type <div${1: id="${2:someid}"}> $0.
    • +
  • More robust undo/redo support.
    • +
  • Stacked snippet expansion (snippet in snippet).
    • +
  • Transformation on a primary field with syntax ${1:default$(transform)}
    • +
  • Validations on field exit through the yas/verify-value +primary field transformation.
    • +
  • Wrapping the region in the exit marker $0 of the snippet. Use +yas/wrap-around-region.
    • +
  • Auto-indentation. Use yas/indent-line set to 'auto
    • +
  • Easier definition of snippets. Use yas/find-snippets or +yas/visit-snippet-file. In the new snippet-mode use +yas/load-snippet-buffer and yas/tryout-snippet.
    • +
  • Customization group yasnippet.
    • +
  • Overriding customization variables in snippets. Use the env: +let-form template keyword.
    • +
  • Fixed Issue 60
    • +
  • Fixed Issue 65
    • +
  • Fixed Issue 56
    • +
+
+
+

0.5.10 / 2009-02-11

+
    +
  • Added grouping support so that the snippets in the menu can be +groupped together.
    • +
  • Make the bundle ELPA +compatible.
    • +
+
+
+

0.5.9 / 2009-01-21

+
    +
  • Fixed the bug of disabling the auto-indenting of cc-mode.
    • +
+
+
+

0.5.8 / 2009-01-15

+
    +
  • Added a key property in snippet definition for snippet names +that are not valid path name.
    • +
  • Fixed some bugs of indenting (Issue 44, Issue +46).
    • +
  • Fixed Issue 45 by +providing a proper default value for yas/buffer-local-condition.
    • +
  • Added helper function yas/substr for convenient mirror +transformation.
    • +
  • Make variable yas/registered-snippet properly initialized.
    • +
  • Fixed the overlay error when overlay becomes empty (Issue 49 and +Issue 48). This +bug has occurred and been fixed earlier, and should not have +happened if we have proper regression test.
    • +
  • Added a workaround for c-electric- serial commands (Issue 27).
    • +
+
+
+

0.5.7 / 2008-12-03

+
    +
  • Fixed Issue 28 of +properly clean up snippet (by joaotavora).
    • +
  • Added a new section "Field-level undo functionality" to correct +Issue 33 +(by joaotavora).
    • +
  • Added some snippets from users for sql, erlang, scala, html, xml, latex, etc.
    • +
  • Fixed Issue 16 by adding +$> support. Here's the doc for $> indenting.
    • +
+
+
+

0.5.6 / 2008-08-07

+
    +
  • Added a buffer local variable yas/dont-activate to turn off +yas/minor-mode in some major modes. See Issue 29.
    • +
  • Make the environment of elisp evaluation more friendly to +(current-column).
    • +
  • Fixed the regular expression bug in python-mode snippets.
    • +
  • Use filename or full key extension for snippet name if no name +property is defined.
    • +
+
+
+

0.5.5 / 2008-05-29

+
    +
  • Tweak yas/extra-mode-hooks so that it can be more easily +customized.
    • +
  • Add an entry in FAQ about why TAB key doesn't work in some +modes.
    • +
+
+
+

0.5.4 / 2008-05-15

+
    +
  • Added ox-mode-hook and python-mode-hook to +yas/extra-mode-hooks to fix the problem YASnippet is not enabled +in those modes.
    • +
+
+
+

0.5.3 / 2008-05-07

+
    +
  • Fix indent of python-mode snippets.
    • +
  • Fix a bug of dropdown-list: conflicts with color-theme (Issue 23). Thanks +Mike.
    • +
  • Fix a bug of condition system.
    • +
+
+
+

0.5.2 / 2008-04-20

+
    +
  • Fix a bug for comparing string to symbol using string= (which +will fire an error).
    • +
+
+
+

0.5.1 / 2008-04-14

+
    +
  • Use a beautiful css style in the document.
    • +
+
+
+

0.5.0 / 2008-04-10

+
    +
  • Integrate with hippie-expand. Just add yas/hippie-try-expand to +hippie-expand-try-functions-list.
    • +
  • If you set yas/fall-back-behavior to 'return-nil, YASnippet +will return nil when it can't find a snippet to expand.
    • +
  • Defect fix: the condition of a snippet was evaluated twice in +earlier version.
    • +
  • Deleting snippet (using C-w or C-k) won't cause serious +problem now.
    • +
  • Several complex snippet for python-mode from Yasser included in the +distribution.
    • +
+
+
+

0.4.5 / 2008-04-07

+
    +
  • Merge the latest dropdown-list.el.
    • +
  • Add snippets for f90-mode from Li Zhu.
    • +
  • Bug fix: l-safe-expr-p: Lisp nesting exceeds max-lisp-eval-depth +error when several (more than two) snippets overlaps. Thanks +sunwaybupt@newsmth for reporting this bug.
    • +
+
+
+

0.4.4 / 2008-03-24

+
    +
  • Bug fix: dropdown-list.el doesn't recognize [return] properly.
    • +
+
+
+

0.4.3 / 2008-03-23

+
    +
  • Bug fix: failed to recognize user customized yas/trigger-key.
    • +
+
+
+

0.4.2 / 2008-03-22

+
    +
  • Make a separate document package for release. Also make document +available online.
    • +
+
+
+

0.4.1 / 2008-03-21

+
    +
  • Make sure yas/minor-mode's key bindings always take priority to +other minor modes.
    • +
+
+
+

0.4.0 / 2008-03-20

+
    +
  • Document refinement and released with YASnippet. Most of the Online +wiki document will be deprecated soon.
    • +
  • Powerful condition system added to yasnippet!
    • +
  • Incorporate dropdown-list.el and make it default way for +selecting multiple candidates. Thanks to Jaeyoun Chung.
    • +
  • yas/before-expand-snippet-hook
    • +
+
+
+

0.3.2 / 2008-03-19

+
    +
  • Enhancement: A better way to define minor-mode. Thanks to Kentaro +Kuribayashi. See this thread +for more details.
    • +
+
+
+

0.3.1 / 2008-03-17

+
    +
  • Bug fix: Emacs get confused when a field is deleted. See issue 10.
    • +
+
+
+

0.3.0 / 2008-03-16

+
    +
  • Add a yas/after-exit-snippet-hook so that you can do something like +indent-region or fill-region after finish the snippet.
    • +
  • Use minor-mode instead of global-set-key to bind the trigger +key. Now the trigger key and fall-back behavior can be more +flexible. Not constrained to <tab>. Thanks to Trey Jackson. See +this thread +for more details.
    • +
  • Now user can customize the popup function for selecting multiple +candidate for the same snippet key.
    • +
  • Support dropdown-list.el to be a better way to select multiple +candidate when in text mode.
    • +
+
+
+

0.2.3 / 2008-03-15

+
    +
  • Bug in non-window (-nw) mode when there's multiple candidate to +expand. See issue 7.
    • +
  • Allow expanding another snippet as long as not currently inside a +field.
    • +
+
+
+

0.2.2 / 2008-03-13

+
    +
  • Added customized face for fields and mirrors. Better in dark +background. And users can customize it.
    • +
+
+
+

0.2.1 / 2008-03-10

+
    +
  • Fix the insert-behind problem under both Emacs 22 and Emacs 23.
    • +
+
+
+

0.2.0 / 2008-03-10

+
    +
  • Use big keymap overlay to detect insert-behind event manually to +avoid sometimes missed hook calls. See issue 3 for more +details.
    • +
  • Support parent snippet table. Now you can set (for example) +cc-mode as common mode for c++-mode, c-mode and +java-mode. They'll share snippets defined for cc-mode.
    • +
+
+
+

0.1.1 / 2008-03-08

+
    +
  • Add a rake task to upload to google code.
    • +
  • Use elisp compile-bundle function instead of python scrip
    • +
+
+
+

0.1.0 / 2008-03-07

+
    +
  • Embedded elisp support.
    • +
  • Fields navigation support.
    • +
  • Mirror of fields support.
    • +
  • Menu-bar support.
    • +
  • Multiple snippets with same name support.
    • +
  • Popup menu for multiple snippet with same name support.
    • +
  • Transformation of fields support.
    • +
  • Load directory support.
    • +
  • Compile bundle support.
    • +
+
+
+
+
+
+
+
+ + +
+ + diff --git a/define_snippet.html b/define_snippet.html new file mode 100644 index 0000000..fadfa0d --- /dev/null +++ b/define_snippet.html @@ -0,0 +1,78 @@ + + + + + + +Moved + + + + +
+
+
+
+ +
+
+
+
+

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

+

This page has been moved. Click here if your browser +does not automatically redirect you

+
+
+
+
+
+
+ + +
+ + diff --git a/faq.html b/faq.html new file mode 100644 index 0000000..c1c3cf9 --- /dev/null +++ b/faq.html @@ -0,0 +1,189 @@ + + + + + + +Frequently Asked Questions + + + +
+
+
+
+ +
+
+
+
+

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

+
+

Why is there an extra newline?

+

If you have a newline at the end of the snippet definition file, then +YASnippet will add a newline when you expanding a snippet. Please +don't add a newline at the end if you don't want it when you saving +the snippet file.

+

Note some editors will automatically add a newline for you. In Emacs, +if you set require-final-newline to t, it will add the final +newline for you automatically.

+
+
+

Why doesn't TAB expand a snippet?

+

First check the mode line to see if there's yas. If not, then try +M-x yas/minor-mode to manually turn on the minor mode and try to +expand the snippet again. If it works, then, you can add the following +code to your .emacs before loading YASnippet:

+
(add-hook 'the-major-mode-hook 'yas/minor-mode-on)
+
+

where the-major-mode is the major mode in which yas/minor-mode +isn't enabled by default.

+

From YASnippet 0.6 you can also use the command M-x +yas/global-mode to turn on YASnippet automatically for all major +modes.

+

If yas/minor-mode is on but the snippet still not expanded. Then +try to see what command is bound to the TAB key: press C-h k +and then press TAB. Emacs will show you the result.

+

You'll see a buffer prompted by Emacs saying that TAB runs the +command .... Alternatively, you might see <tab> runs the command +..., note the difference between TAB and <tab> where the +latter has priority. If you see <tab> bound to a command other +than yas/expand, (e.g. in org-mode) you can try the following +code to work around:

+
(add-hook 'org-mode-hook
+          (let ((original-command (lookup-key org-mode-map [tab])))
+            `(lambda ()
+               (setq yas/fallback-behavior
+                     '(apply ,original-command))
+               (local-set-key [tab] 'yas/expand))))
+
+

replace org-mode-hook and org-mode-map with the major mode +hook you are dealing with (Use C-h m to see what major mode you +are in).

+

As an alternative, you can also try

+
(defun yas/advise-indent-function (function-symbol)
+  (eval `(defadvice ,function-symbol (around yas/try-expand-first activate)
+           ,(format
+             "Try to expand a snippet before point, then call `%s' as usual"
+             function-symbol)
+           (let ((yas/fallback-behavior nil))
+             (unless (and (interactive-p)
+                          (yas/expand))
+               ad-do-it)))))
+
+(yas/advise-indent-function 'ruby-indent-line)
+
+

To advise the modes indentation function bound to TAB, (in this case +ruby-indent-line) to first try to run yas/expand.

+

If the output of C-h k RET <tab> tells you that <tab> is +indeed bound to yas/expand but YASnippet still doesn't work, check +your configuration and you may also ask for help on the discussion +group. See this +particular thread for +quite some solutions and alternatives.

+

Don't forget to attach the information on what command is bound to TAB +as well as the mode information (Can be obtained by C-h m).

+
+
+

Why doesn't TAB navigation work with flyspell

+

A workaround is to inhibit flyspell overlays while the snippet is active:

+
(add-hook 'flyspell-incorrect-hook
+        #'(lambda (dummy1 dummy2 dymmy3)
+            (and yas/active-field-overlay
+                 (overlay-buffer yas/active-field-overlay))))
+
+

This is apparently related to overlay priorities. For some reason, the +keymap property of flyspell's overlays always takes priority over +the same property in yasnippet's overlays, even if one sets the +latter's priority property to something big. If you know +emacs-lisp and can solve this problem, drop a line in the discussion +group.

+
+
+

How do I turn off the minor mode where in some buffers

+

The best way, since version 0.6.1c, is to set the default value of the +variable yas/dont-activate to a lambda function like so:

+
(set-default 'yas/dont-activate
+           #'(lambda ()
+               (and yas/root-directory
+                    (null (yas/get-snippet-tables)))))
+
+

This is also the default value starting for that version. It skips the +minor mode in buffers where it is not applicable (no snippet tables), +but only once you have setup your yas/root-directory.

+
+
+

How do I define an abbrev key containing characters not supported by the filesystem?

+
+
Note: This question applies if you're still defining snippets
+
whose key is the filename. This is behavior stil provided by +version 0.6 for backward compatibilty, but is somewhat deprecated...
+
+

For example, you want to define a snippet by the key < which is +not a valid character for filename on Windows. This means you can't +use the filename as a trigger key in this case.

+

You should rather use the # key: directive to specify the key of +the defined snippet explicitly and name your snippet with an arbitrary +valid filename, lt.yasnippet for example, using < for the +# key: directive:

+
#key: <
+#name: <...></...>
+# --
+<${1:div}>$0</$1>
+
+
+
+
+
+
+
+
+ + +
+ + diff --git a/images/bg-content-left.png b/images/bg-content-left.png new file mode 100644 index 0000000..a64b346 Binary files /dev/null and b/images/bg-content-left.png differ diff --git a/images/bg-content-right.png b/images/bg-content-right.png new file mode 100644 index 0000000..f07ebb5 Binary files /dev/null and b/images/bg-content-right.png differ diff --git a/images/bg-content.png b/images/bg-content.png new file mode 100644 index 0000000..d55828e Binary files /dev/null and b/images/bg-content.png differ diff --git a/images/bg-navigation-item-hover.png b/images/bg-navigation-item-hover.png new file mode 100644 index 0000000..c783d71 Binary files /dev/null and b/images/bg-navigation-item-hover.png differ diff --git a/images/bg-navigation-item.png b/images/bg-navigation-item.png new file mode 100644 index 0000000..d2452ac Binary files /dev/null and b/images/bg-navigation-item.png differ diff --git a/images/bg-navigation.png b/images/bg-navigation.png new file mode 100644 index 0000000..18b9559 Binary files /dev/null and b/images/bg-navigation.png differ diff --git a/images/body.png b/images/body.png new file mode 100644 index 0000000..b361e7b Binary files /dev/null and b/images/body.png differ diff --git a/images/customization-group.png b/images/customization-group.png new file mode 100644 index 0000000..b10827f Binary files /dev/null and b/images/customization-group.png differ diff --git a/images/dropdown-menu.png b/images/dropdown-menu.png new file mode 100644 index 0000000..57d482e Binary files /dev/null and b/images/dropdown-menu.png differ diff --git a/images/external.png b/images/external.png new file mode 100644 index 0000000..419c06f Binary files /dev/null and b/images/external.png differ diff --git a/images/ido-menu.png b/images/ido-menu.png new file mode 100644 index 0000000..df392c5 Binary files /dev/null and b/images/ido-menu.png differ diff --git a/images/menu-1.png b/images/menu-1.png new file mode 100644 index 0000000..d2e6a51 Binary files /dev/null and b/images/menu-1.png differ diff --git a/images/menu-2.png b/images/menu-2.png new file mode 100644 index 0000000..abb8a72 Binary files /dev/null and b/images/menu-2.png differ diff --git a/images/menu-groups.png b/images/menu-groups.png new file mode 100644 index 0000000..fcedda8 Binary files /dev/null and b/images/menu-groups.png differ diff --git a/images/menu-parent.png b/images/menu-parent.png new file mode 100644 index 0000000..f0fa10c Binary files /dev/null and b/images/menu-parent.png differ diff --git a/images/minor-mode-indicator.png b/images/minor-mode-indicator.png new file mode 100644 index 0000000..3743455 Binary files /dev/null and b/images/minor-mode-indicator.png differ diff --git a/images/x-menu.png b/images/x-menu.png new file mode 100644 index 0000000..3bc9a15 Binary files /dev/null and b/images/x-menu.png differ diff --git a/snippet-development.html b/snippet-development.html new file mode 100644 index 0000000..b61da91 --- /dev/null +++ b/snippet-development.html @@ -0,0 +1,601 @@ + + + + + + +Writing snippets + + + +
+
+
+
+ +
+
+
+
+

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

+ +
+

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:

+
#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:

+
# 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.

+
#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:

+
#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:

+
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:

+
<div$1>
+    $0
+</div>
+
+
+
+

Placeholder fields

+

Tab stops can have default values -- a.k.a placeholders. The syntax is +like this:

+
${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

+

We refer the tab stops with placeholders as a field. A field can have +mirrors. Its mirrors will get updated when you change the text of a +field. Here's an example:

+
\begin{${1:enumerate}}
+    $0
+\end{$1}
+
+

When you type "document" at ${1:enumerate}, the word +"document" will also be inserted at \end{$1}. The best +explanation is to see the screencast(YouTube or avi video).

+

The tab stops with the same number to the field act as its mirrors. If +none of the tab stops has an initial value, the first one is selected +as the field and others mirrors.

+
+
+

Mirrors with transformations

+

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:

+
- (${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

+
=====
+Title
+=====
+
+

is a valid title but

+
===
+Title
+===
+
+

is not. Here's an snippet for rst title:

+
${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

+
#define "${1:mydefine$(upcase yas/text)}"
+
+

mydefine gets automatically upcased to MYDEFINE once you enter +the field. As you type text, it gets filtered through the +transformation every time.

+

Note that to tell this kind of expression from a mirror with a +transformation, YASnippet needs extra text between the : and the +transformation's $. If you don't want this extra-text, you can use +two $'s instead.

+
#define "${1:$$(upcase yas/text)}"
+
+

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/field-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:

+
<div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
+  $0
+</div>
+
+

See the definition of yas/choose-value to see how it was written +using the two variables.

+

Here's another use, for LaTeX-mode, which calls reftex-label just as +you enter snippet field 2. This one makes use of yas/modified-p +directly.

+
\section{${1:"Titel der Tour"}}%
+\index{$1}%
+\label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-
+insert))}}%
+
+

The function yas/verify-value has another neat trick, and makes +use of yas/moving-away-p. Try it and see! Also, check out this +thread

+
+
+

Nested placeholder fields

+

From version 0.6 on, you can also have nested placeholders of the type:

+
<div${1: id="${2:some_id}"}>$0</div>
+
+

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.

+
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:

+
+ +
+

In this section, i'll shortly cover the second option.

+

Download the textmate_import.rb tool and the TextMate +bundle you're interested in.

+
$ 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:

+
$ ./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.

+
$ 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.

+ + + +
+
+
+
+
+
+
+ + +
+ + diff --git a/snippet-expansion.html b/snippet-expansion.html new file mode 100644 index 0000000..3dcd564 --- /dev/null +++ b/snippet-expansion.html @@ -0,0 +1,432 @@ + + + + + + +Expanding snippets + + + +
+
+
+
+ +
+
+
+
+

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

+ +
+

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.

+images/minor-mode-indicator.png +

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.

+
+

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 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:

+
(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.

    +
    • +
+
;; 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

+
(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 can return more than +one snippet to be expanded at point.

+

When there are multiple candidates, YASnippet will let you select +one. The UI for selecting multiple candidate can be customized through +yas/prompt-functions , which defines your preferred methods of +being prompted for snippets.

+

You can customize it with M-x customize-variable RET +yas/prompt-functions RET. Alternatively you can put in your +emacs-file:

+
(setq yas/prompt-functions '(yas/x-prompt yas/dropdown-prompt))
+
+

Currently there are some alternatives solution with YASnippet.

+images/x-menu.png +
+

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.
    • +
+images/ido-menu.png +
+
+

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.

+images/dropdown-menu.png +
+
+

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...

+
+
+
+
+
+
+
+
+ + +
+ + diff --git a/snippet-menu.html b/snippet-menu.html new file mode 100644 index 0000000..ebfdb09 --- /dev/null +++ b/snippet-menu.html @@ -0,0 +1,141 @@ + + + + + + +YASnippet menu + + + +
+
+
+
+ +
+
+
+
+

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

+ +

When yas/minor-mode is active, YASnippet will setup a menu just +after the "Buffers" menu in the menubar.

+

In this menu, you can find

+
    +
  • The currently loaded snippet definitions, organized by major mode, +and optional grouping.
    • +
  • A rundown of the most common commands, (followed by their +keybindings) including commands to load directories and reload all +snippet definitions.
    • +
  • A series of submenus for customizing and exploring YASnippet +behavior.
    • +
+images/menu-1.png +
+

Loading snippets from menu

+

Invoking "Load snippets..." from the menu invokes +yas/load-directory and prompts you for a snippet directory +hierarchy to load.

+

Also useful is the "Reload all" options which uncondionally reloads +all the snippets directories defined in yas/root-directory and +rebuilds the menus.

+
+
+

Snippet menu behavior

+

YASnippet will list in this section all the loaded snippet definitions +organized by snippet table name.

+

You can use this section to explore currently loaded snippets. If you +click on one of them, the default behavior is to expand it, +unconditionally, inside the current buffer.

+

You can however, customize variable yas/visit-from-menu to be +t which will take you to the snippet definition file when you +select it from the menu.

+

If you want the menu show only snippet tables whose name corresponds +to a "real" major mode. You do this by setting yas/use-menu to +'real-modes.

+

Finally, to have the menu show only the tables for the currently +active mode, set yas/use-menu to abbreviate.

+

These customizations can also be found in the menu itself, under the +"Snippet menu behavior" submenu.

+
+
+

Controlling indenting

+

The "Indenting" submenu contains options to control the values of +yas/indent-line and yas/also-auto-indent-first-line. See +Writing snippets .

+
+
+

Prompting method

+

The "Prompting method" submenu contains options to control the value +of yas/prompt-functions. See Expanding snippets .

+
+
+

Misc

+

The "Misc" submenu contains options to control the values of more +variables.

+
+
+
+
+
+
+
+ + +
+ + diff --git a/snippet-organization.html b/snippet-organization.html new file mode 100644 index 0000000..020389d --- /dev/null +++ b/snippet-organization.html @@ -0,0 +1,232 @@ + + + + + + +Organizing snippets + + + +
+
+
+
+ +
+
+
+
+

+ Important: This documentation applies to + the SVN trunk of YASnippet, which you + get here. Documentation + for other versions can be found here. +

+ +
+

Loading snippets

+

Snippet definitions are stored in files in the filesystem. Unless you +use the simpler bundle version), these +are arranged so that YASnippet can load them into snippet +tables. The triggering mechanisms (see Expanding snippets) will +look up these snippet tables and (hopefully) expand the snippet you +intended.

+

The non-bundle version of YASnippet, once unpacked, comes with a full +directory of snippets, which you can copy somewhere and use. You can +also create or download more directories.

+

Once these directories are in place reference them in the variable +yas/root-directory and load them with yas/load-directory:

+
;; Develop and keep personal snippets under ~/emacs.d/mysnippets
+(setq yas/root-directory "~/emacs.d/mysnippets")
+
+;; Load the snippets
+(yas/load-directory yas/root-directory)
+
+

The point in using yas/root-directory (as opposed to calling +yas/load-directory directly) is considering "~/emacs.d/mysnippets" +for snippet development, so you can use commands like +yas/new-snippet and others described in section Writing +Snippets.

+

You can make this variable a list and store more items into it:

+
;; Develop in ~/emacs.d/mysnippets, but also
+;; try out snippets in ~/Downloads/interesting-snippets
+(setq yas/root-directory '("~/emacs.d/mysnippets"
+                           "~/Downloads/interesting-snippets"))
+
+;; Map `yas/load-directory' to every element
+(mapc 'yas/load-directory yas/root-directory)
+
+

In this last example, the all the directories are loaded and their +snippets considered for expansion. However development still happens +in the first element, "~/emacs.d/mysnippets".

+
+
+

Organizing snippets

+

Once you've setup yas/root-directory , you can store snippets +inside sub-directories of these directories.

+

Snippet definitions are put in plain text files. They are arranged +by sub-directories, and the snippet tables are named after these +directories.

+

The name corresponds to the Emacs mode where you want expansion to +take place. For example, snippets for c-mode are put in the +c-mode sub-directory.

+
+

The .yas.parents file

+

It's very useful to have certain modes share snippets between +themselves. To do this, choose a mode subdirectory and place a +.yas-parents containing a whitespace-separated list of other +mode names. When you reload those modes become parents of the +original mode.

+
$ tree
+.
+|-- c-mode
+|   |-- .yas-parents    # contains "cc-mode text-mode"
+|   `-- printf
+|-- cc-mode
+|   |-- for
+|   `-- while
+|-- java-mode
+|   |-- .yas-parents    # contains "cc-mode text-mode"
+|   `-- println
+`-- text-mode
+    |-- email
+    `-- time
+
+
+
+

The .yas-make-groups file

+images/menu-groups.png +

If you place an empty plain text file .yas-make-groups inside one +of the mode directories, the names of these sub-directories are +considered groups of snippets and The YASnippet Menu is organized +much more cleanly, as you can see in the image.

+

Another alternative way to achieve this is to place a # group: +directive inside the snippet definition. See Writing Snippets.

+
$ tree ruby-mode/
+ruby-mode/
+|-- .yas-make-groups
+|-- collections
+|   |-- each
+|   `-- ...
+|-- control structure
+|   |-- forin
+|   `-- ...
+|-- definitions
+|   `-- ...
+`-- general
+    `-- ...
+
+
+
+
+

YASnippet bundle

+

The most convenient way to define snippets for YASnippet is to put +them in a directory arranged by the mode and use +yas/load-directory to load them.

+

However, this might slow down the Emacs start-up speed if you have many +snippets. You can use yas/define-snippets to define a bunch of +snippets for a particular mode in an Emacs-lisp file.

+

Since this is hard to maintain, there's a better way: define your +snippets in directory and then call M-x yas/compile-bundle to +compile it into a bundle file when you modified your snippets.

+

The release bundle of YASnippet is produced by +yas/compile-bundle. The bundle uses yas/define-snippets to +define snippets. This avoids the IO and parsing overhead when loading +snippets.

+

Further more, the generated bundle is a stand-alone file not depending +on yasnippet.el. The released bundles of YASnippet are all +generated this way.

+

See the internal documentation for these functions

+
    +
  • M-x describe-function RET yas/define-snippets RET
    • +
  • M-x describe-function RET yas/compile-bundle RET.
    • +
+
+
+

Customizable variables

+
+

yas/root-directory

+

Root directory that stores the snippets for each major mode.

+

If you set this from your .emacs, can also be a list of strings, +for multiple root directories. If you make this a list, the first +element is always the user-created snippets directory. Other +directories are used for bulk reloading of all snippets using +yas/reload-all

+
+
+

yas/ignore-filenames-as-triggers

+

If non-nil, don't derive tab triggers from filenames.

+

This means a snippet without a # key: directive wont have a tab +trigger.

+ + + +
+
+
+
+
+
+
+
+ + +
+ +