0.6.1b / 2009-08-23
+-
+
- 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.rb to svn repository. +
- Many random bugs fixed. +
- Fixed Issue 72 (thanks +rmartin.k...@gmail.com) +
- Fixed Issue 74 +
- Fixed Issue 70 +
- Fixed Issue 69 +
0.6.0c / 2009-07-27
- Now byte compiles correctly with no warnings. diff --git a/doc/changelog.rst b/doc/changelog.rst index a91b91a..72028e4 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -2,9 +2,31 @@ ChangeLog ========= -:Author: pluskid -:Contact: pluskid@gmail.com -:Date: 2008-03-22 +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html + +0.6.1b / 2009-08-23 +=================== + +* 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.rb`` to svn repository. +* Many random bugs fixed. +* Fixed `Issue 72 +
Contents
Yasnippet is a template system for emacs. It allows you to type a -abbrevation and automatically expand the abbreviation into function +
YASnippet is a template system for Emacs. It allows you to type a +abbreviation and automatically expand the abbreviation into function templates.
Bundled language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML, CSS and more.
-Yasnippet system is inspired from TextMate's template system. You can +
YASnippet system is inspired from TextMate's template system. You can use a tool -to import any TextMate template you have to Yasnippet. It is a -re-design and re-write of my original extension smart-snippet. It -is much cleaner and more powerful than smart-snippet.
+to import any TextMate template you have to YASnippet. +YASnippet is a re-write of the extension smart-snippet. Both are +original creations of pluskid.
Video Demo
+Watch the demo at YouTube (download a higher resolution version: yasnippet.avi).
Brief Install Instruction
+Installation
There are two archives of YASnippet. One is a single file compiled “bundle”, and the other is normal. If all you need is to use the -builtin templates, download the bundle one. If you want to add your +built-in templates, download the bundle one. If you want to add your own templates, download the normal one.
Bundle Install
@@ -95,7 +101,7 @@ own templates, download the normal one.That's it. Now open any one of your language file, you'll see a menu YASnippet. you can pull the menu to insert a template. Or, you can type the pre-defined abbrev and press TAB to expand it.
-To have emacs load YASnippet automatically when it starts, put the +
To have Emacs load YASnippet automatically when it starts, put the following in your ~/.emacs file:
(add-to-list 'load-path @@ -120,62 +126,52 @@ following in your .emacsPlease refer to the documentation for full customization, or use the customization group.
-
How to use YASnippet
Since version 0.6, YASnippet contains more functionality. You don't -need to know all of it to use it sucessfully, but you it can improve +need to know all of it to use it successfully, but you it can improve your snippeting experience.
Hence this section has been split into separate documents:
-Describes ways to organize your snippets in the hard disk, or not -organize them at all and just use plain old elisp.
-Also explains how to use the YASnippet menu to explore and learn new -snippets.
++Describes ways to organize your snippets in the hard disk (or not +organize them at all and just use yasnippet-bundle.el.-
Maybe, you'll want some snippets to be expanded in a particular mode, -or only under certain conditions. Also you might want snippets to wrap -themselves around a region of selected text, use a direct keybinding, -control indenting, etc...
++-Describes how YASnippet chooses snippets for expansion at point.
+Maybe, you'll want some snippets to be expanded in a particular +mode, or only under certain conditions, or be prompted using +ido, etc...
+
Describes the YASnippet definition syntax, which is similar, but not -equivalent to Textmate's. Includes a section about converting Textmate -snippets.
-Customization group
-From version 0.6 onwards, there is a customization group that you can -access with:
-M-x customize-group RET yasnippet RET
-Each customization variable affects how some part of YASnippet works, -for example automatic snippet indentation, what prompting method to -use, whether to expand snippets inside snippets, etc...
-Inside the customization group, each variable is reasonably documented -to explain what it does.
++Describes the YASnippet definition syntax, which is very close (but +not equivalent) to Textmate's. Includes a section about converting +TextMate snippets.+ +
+Explains how to use the YASnippet menu to explore and learn new +snippets.
Bugs, Contribution and Support
+Bugs, Contribution and Support
- If you find a bug, please report it at Issue List. -
- If you have problem using YASnippet, or have some new ideas, please -post to the discussion group. Especially, there's a wish list -wiki page. I'll collect ideas from the discussion group to the -wish list. So you might want to look at the wish list before -you post something. -
- If you want to contribute some snippets, you can also post them to -the discussion group. Some common snippets may be added to -YASnippet, while others will be collected at the -UserContributedSnippets wiki page. +
- If you have problem using YASnippet, or have some new ideas, +including snippets, please post to the discussion group.
Thank you very much for using YASnippet!
+Contents
-
-
- Quickly finding/defining snippets -
- Using the snippet-mode major mode
-
-
- The Syntax of the Template +
- Snippet development + +
- File content + +
- Template syntax + +
- Customizable variables -
- Plain Text -
- Embedded elisp code -
- Tab stop fields -
- Placeholder fields -
- Mirrors -
- Mirrors with transformations -
- Fields with transformations -
- Choosing fields value from a list -
- Nested placeholder fields
Quickly finding/defining snippets
-From version 0.6 upwards there are two ways you can quickly find a -snippet file. Once you find this file it will be set to -snippet-mode (see ahead)
+Snippet development
+Quickly finding snippets
+There are some ways you can quickly find a snippet file. Once you find +this file it will be set to snippet-mode (see ahead) and you can +start editing your snippet.
-
+
M-x yas/new-snippet
+Prompts you for a snippet name, then tries to guess a suitable +directory to store it, prompting you for creation if it does not +exist. Finally, places you in a new buffer set to snippet-mode +so you can write your snippet.
+M-x yas/find-snippets
Lets you find the snippet file in the directory the snippet was loaded from (if it exists) like find-file-other-window.
@@ -86,10 +117,10 @@ directly to the snippet definition's file, if it exists.
Using the snippet-mode major mode
-From version 0.6 upwards 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.
+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
@@ -110,22 +141,148 @@ can see what it looks like. This is bound toThere are also snippets for making snippets: vars, field and mirror.
- +
File content
+A file defining a snippet may just contain the template for the +snippet. Optionally it can also contains some meta data for the +snippet as well as comments.
+Generally speaking, if the file contains a line of # --, then all +contents above that line are considered directives (meta data) and +comments; below that line lies the snippet template.
+If no # -- is found, the whole file content is considered as the +template.
+Here's a typical example:
+#contributor : pluskid <pluskid@gmail.com>
+#name : __...__
+# --
+__${init}__
+Meta data are specified in the syntax of
+#data-name : data value
+Any other text above # -- is considered as comment and +ignored. 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 it will default to the name of the file the +snippet is being loaded from, unless YASnippet is ignoring file names +as triggers (see yas/ignore-filenames-as-triggers in Organizing +snippets), in which case this snippet +will not be expandable through the key mechanism.
+Sometimes the key of a snippet is non-ASCII or not valid filename +(e.g. contains /). One can then define the key property which +will overwrite the filename as the key to expand the snippet.
+# 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.
+To override the keymap choice based on the major mode name. Use a cons +cell where the first element specifies the name of the keymap where +you want to record the keybinding.
+
+Note that this feature is still experimental and should be used with +caution: It is easy to override important keybindings for many basic +modes and it is hard to undefine them. In particular, the variable +yas/active-keybinding can tell you what snippet keybindings are +active and the function yas/kill-snippet-keybindings will try to +undefine all the keybindings.
+# 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
+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 elisp code
-Elisp code can be embedded inside the template. They are written +
Embedded Emacs-lisp code
+Emacs-Lisp code can be embedded inside the template. They are written inside back-quotes (`):
They are evaluated when the snippet is being expanded. The evaluation is done in the same buffer as the snippet being expanded. Here's an @@ -138,7 +295,7 @@ $0 #endif /* $1 */
From version 0.6.0, snippets expansions are run with some special -emacs-lisp variables bound. One of this is yas/selected-text. You +Emacs-lisp variables bound. One of this is yas/selected-text. You can therefore define a snippet like:
for ($1;$2;$3) {
`yas/selected-text`$0
@@ -149,9 +306,9 @@ snippet. Alternatively, you can also customize the variable
yas/wrap-around-region to t which will do this automatically.
Tab stop fields
+Tab stop fields
Tab stops are fields that you can navigate back and forth by TAB -and S-TAB [3]. They are written by $ followed with a +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:
@@ -161,7 +318,7 @@ fields. Here's a typical example:Placeholder fields
+Placeholder fields
Tab stops can have default values -- a.k.a placeholders. The syntax is like this:
${N:default value}
@@ -172,7 +329,7 @@ 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:
@@ -188,10 +345,10 @@ none of the tab stops has an initial value, the first one is selected as the field and others mirrors.Mirrors with transformations
+Mirrors with transformations
If the default value of a field starts with $, then it is interpreted as the transformation code instead of default value. A transformation -is some arbitrary elisp code that will get evaluated in an environment +is some arbitrary Emacs-lisp code that will get evaluated in an environment when the variable text is bind to the inputted text of the field. Here's an example for Objective-C:
- (${1:id})${2:foo}
@@ -210,8 +367,8 @@ $0
a placeholder. The actual placeholder 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
-transformated text. So in this example, if you type baz in the field,
-the transformed text will be Baz. This example is also available in
+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 "==="
@@ -232,27 +389,9 @@ ${1:$(make-string (string-width text) ?\=)}
$0
| [1] | With some minor change, mainly for fixing some trivial bugs. |
| [2] | This is done when you call yas/initialize. |
| [3] | Of course, this can be customized. |
Fields with transformations
+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 @@ -264,8 +403,8 @@ distinguish between fields and mirrors. In the following example
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 this is differentiated from a mirror with a transformation -by the existance of extra text between the : and the +
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)}"
@@ -276,7 +415,7 @@ the value of the field and sets it its internal modification state to
fields does not take place. This is by design.
Choosing fields value from a list
+Choosing fields value from a list
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 @@ -292,7 +431,7 @@ using the two variables. Also check out
Nested placeholder fields
+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>
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 region, +this works mostly 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.
+ + + +...
+ #binding: "C-c C-c C-m" + # -- +`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`
+ +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. + +To override the keymap choice based on the major mode name. Use a cons +cell where the first element specifies the name of the keymap where +you want to record the keybinding. + +.. sourcecode:: text + #name :...
+ #binding: (rinari-minor-mode-map . "C-c C-c C-m") + # -- +`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`
+ +Note that this feature is still experimental and should be used with +caution: It is easy to override important keybindings for many basic +modes and it is hard to undefine them. In particular, the variable +``yas/active-keybinding`` can tell you what snippet keybindings are +active and the function ``yas/kill-snippet-keybindings`` will try to +undefine all the keybindings. + +``# 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. @@ -68,10 +246,10 @@ 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 elisp code -------------------- +Embedded Emacs-lisp code +------------------------ -Elisp code can be embedded inside the template. They are written +Emacs-Lisp code can be embedded inside the template. They are written inside back-quotes (`````): They are evaluated when the snippet is being expanded. The evaluation @@ -82,13 +260,13 @@ 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.0, snippets expansions are run with some special -emacs-lisp variables bound. One of this is ``yas/selected-text``. You +Emacs-lisp variables bound. One of this is ``yas/selected-text``. You can therefore define a snippet like: .. sourcecode:: text @@ -105,7 +283,7 @@ Tab stop fields --------------- Tab stops are fields that you can navigate back and forth by ``TAB`` -and ``S-TAB`` [3]_. They are written by ``$`` followed with a +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: @@ -163,7 +341,7 @@ Mirrors with transformations If the default value of a field starts with ``$``, then it is interpreted as the transformation code instead of default value. A transformation -is some arbitrary elisp code that will get evaluated in an environment +is some arbitrary Emacs-lisp code that will get evaluated in an environment when the variable text is bind to the inputted text of the field. Here's an example for Objective-C: @@ -173,7 +351,7 @@ field. Here's an example for Objective-C: { return $2; } - + - (void)set${2:$(capitalize text)}:($1)aValue { [$2 autorelease]; @@ -185,8 +363,8 @@ Look at ``${2:$(capitalize text)}``, it is a transformation instead of a placeholder. The actual placeholder 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 -transformated text. So in this example, if you type baz in the field, -the transformed text will be Baz. This example is also available in +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 @@ -207,19 +385,15 @@ is a valid title but Title === -is not. Here's an snippet for rst 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 -.. [1] With some minor change, mainly for fixing some trivial bugs. -.. [2] This is done when you call ``yas/initialize``. -.. [3] Of course, this can be customized. + $0 Fields with transformations --------------------------- @@ -240,8 +414,8 @@ distinguish between fields and mirrors. In the following example the field. As you type text, it gets filtered through the transformation every time. -Note that this is differentiated from a mirror with a transformation -by the existance of extra text between the ``:`` and the +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. @@ -261,16 +435,16 @@ 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. +you select default values for it. The ``yas/choose-value`` does this work for you. For example: - + .. sourcecode:: textContents
-
-
- Some stuff
-
-
- File content +
- Triggering expansion
-
+
- Trigger key -
- The strategy to select a snippet
-
-
- Finding the key -
- The condition system -
- Multiple snippet with the same key -
- The Trigger Key
Some stuff
-File content
-A file defining a snippet may just contain the template for the -snippet. Optionally it can also contains some meta data for the -snippet as well as comments.
-Generally speaking, if the file contains a line of # --, then all -contents above that line are considered as meta data and comments; -below are template. Or else the whole file content is considered as -the template.
-Here's a typical example:
-#contributor : pluskid <pluskid@gmail.com>
-#name : __...__
-# --
-__${init}__
-Meta data are specified in the syntax of
-#data-name : data value
-Any other text above # -- is considered as comment and -ignored. Here's a list of currently supported meta data:
-
+Triggering expansion
+You can use YASnippet to expand snippets in different ways:
-
-
- name: The name of the snippet. This is a one-line description of -the snippet. It will be displayed in the menu. So it's a good idea -to select a descriptive name fo a snippet -- especially -distinguishable among similar snippets. -
- contributor: The contributor of the snippet. -
- condition: The condition of the snippet. This is a piece of -elisp code. If a snippet has a condition, then it will only be -expanded when the condition code evaluate to some non-nil value. -
- key: The key to expand the snippet. Sometimes the key of a -snippet is non-ASCII or not valid filename (e.g. contains -/). One can then define the key property which will -overwrite the filename as the key to expand the snippet. -
- group: The snippets for a mode can be grouped. Grouped snippets -will be grouped in sub-menu. This is useful if one has too many -snippets for a mode which will make the menu too long. group -property only affect menu construction (See Organizing snippets). Refer to -the snippets for ruby-mode for examples. 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. +
- By typing a snippet abbrev and then pressing the key defined in +yas/trigger-key (which defaults to "TAB"). This works in a +buffer 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.
+
+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 by calling a +functin from elisp code. You should call yas/expand-snippet +instead of yas/expand in this case.
+As with expanding from the menubar, condition system and multiple +candidates won't exists here. In fact, expanding from menubar 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 point.
+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 it 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 mode you +are in currently.
+
+Parent tables
+Snippet tables defined as parent of some other table considered in +the previous step 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, 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 more fine 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.
The strategy to select a snippet
-When user press the yas/trigger-key, YASnippet try to find a -proper snippet to expand. The strategy to find such a snippet is -explained here.
-Finding the key
-YASnippet search from current point backward trying to find the -snippet to be expanded. The default searching strategy is quite -powerful. For example, in c-mode, "bar", "foo_bar", -"#foo_bar" can all be recognized as a template key. Further more, -the searching is in that order. In other words, if "bar" is found -to be a key to some valid snippet, then "foo_bar" and -"#foobar" won't be searched.
+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. A +customization variable, called yas/prompt-functions defines your +preferred method 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.
+
+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. +
- Emacs have little control over it. E.g. you can't use C-n, +C-p to navigate. +
- This function can't be used when in a terminal. +
+Use built-in Emacs selection methods
+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.
+
+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 "foo_bar" and "#foobar" won't be +searched.
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 @@ -155,255 +401,6 @@ following thing until found one:
But you'd better keep the default value unless you understand what Emacs's syntax rule mean.
The condition system
-I write forked snippet.el to make the smart-snippet.el. I call it -smart-snippet because a condition can be attached to a snippet. This -is really a good idea. However, writing condition for a snippet -usually needs good elisp and Emacs knowledge, so it is strange to many -user.
-Later I write YASnippet and persuade people to use it instead of -smart-snippet.el. However, some user still love smart-snippet because -it is smart. So I make YASnippet smart. Even smarter than -smart-snippet.el. :p
-Consider this scenario: you are an old Emacs hacker. You like the -abbrev-way and set yas/trigger-key to (kbd "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).
-It's OK, 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 YASnippet introduce a buffer local variable -yas/buffer-local-condition. You can set this variable to (not -(python-in-string/comment)) in python-mode-hook. There's no way -to do this in smart-snippet.el!
-Then, what if you really want some snippet even in 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, snippet won't be -expanded. -
- If it evaluate 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):
-
-
- If the snippet has no condition, then it won't be expanded. -
- If the snippet has a condition but evaluate to nil or error -occured during evaluation, it won't be expanded. -
- If the snippet has a condition that evaluate 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 expanded. -
-
- - If it evaluate to 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 expanded. -
-
So 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.
-Multiple snippet with the same key
-There can be multiple snippet bind to the same key. If you define a -snippet with a key that is already used, you'll overwrite the original -snippet definition. However, you can add a different postfix to the -key.
-In general, the extension (consider a file name) is ignored when -defining a snippet. So def, def.1 and def.mine will all be -valid candidates when the key is def.
-When there are multiple candidates, YASnippet will let you select -one. The UI for selecting multiple candidate can be -customized. There're two variable related:
-From version 0.6 of YASnippet this has changed significantly. A new -customization variable, called yas/prompt-functions defines your -preferred method 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.
-
-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. -
- Emacs have little control over it. E.g. you can't use C-n, -C-p to navigate. -
- This function can't be used when in a terminal. -
Use built-in Emacs selection methods
-You can use functions yas/completing-prompt for the classic emacs -completion method or yas/ido-prompt for a much nicer looking -method. The best way is to try it. This works in a terminal.
-
Use dropdown-menu.el
-The function yas/dropdown-prompt can also be placed in the -yas/prompt-functions list.
-
-Originally, only the above two function is available in -YASnippet. They are difficult to use -- especially in a -terminal. Until later Jaeyoun Chung show me his dropdown-menu.el, -I say wow! It's wonderful!
--
-
- It works in both window system and terminal. -
- It is customizable, you can use C-n, C-p to navigate, q -to quite and even press 6 as a shortcut to select the 6th -candidate. -
So I added yas/dropdown-list-popup-for-template to support -dropdown-list.el. And upload dropdown-list.el to YASnippet -hompage for an optional download (since Jaeyoun didn't provide a URL).
-Then finally, in 0.4.0, I included a copy of the content of -dropdown-list.el in yasnippet.el and made it the default -way for selecting multiple candidates.
-However, the original functions are still there, you can still use this
-(setq yas/window-system-popup-function
- 'yas/x-popup-menu-for-template)
-if you prefer a modern UI. :)
-The Trigger Key
-YASnippet is implemented as a minor-mode (yas/minor-mode). The -trigger key yas/trigger-key is defined in yas/minor-mode-map -to call yas/expand to try to expand a snippet.
-The Minor Mode
-
-When yas/minor-mode is enabled, the trigger key will take -effect. The default key is (kbd "TAB"), however, you can freely -set it to some other key.
-In version 0.5, YASnippet add a hook to -after-change-major-mode-hook to enable yas/minor-mode in -every buffer. This works fine for most modes, however, some mode -doesn't follow the Emacs convention and doens't call this hook. You -can either explicitly hook for those mode or just add it to -yas/extra-mode-hooks to let YASnippet do it for you:
-(require 'yasnippet)
-(add-to-list 'yas/extra-mode-hooks
- 'ruby-mode-hook)
-(yas/initialize)
-Note that should be put after (require 'yasnippet) and before -(yas/initialize). Further more, you may report it to me, I'll add -that to the default value.
-In version 0.6, just use yas/global-mode to enable YASnippet in -all major modes. Or put yas/minor-mode-on in that modes hook. See -the FAQ.
-The Fallback
-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 bind 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. This is useful when you -would like YASnippet to work with other extensions, -e.g. hippie-expand. I'm also glad to tell you that integration -with hippie-expand is already included in YASnippet.
-Integration with hippie-expand
-To integrate with hippie-expand, just put -yas/hippie-try-expand in -hippie-expand-try-functions-list. Personally I would like to put -in front of the list, but it can be put anywhere you prefer.
-Other way to select a snippet
-When you use the trigger key (so yas/expand) to expand a snippet, -the key for the snippet is deleted before the template for the snippet -is inserted.
-However, there're other ways to insert a snippet.
-yas/insert-snippet
-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.
-Expanding From Elisp Code
-Sometimes you might want to expand a snippet directly by calling a -functin from elisp code. You should call yas/expand-snippet -instead of yas/expand in this case.
-As with expanding from the menubar, condition system and multiple -candidates won't exists here. In fact, expanding from menubar has the -same effect of evaluating the follow code:
-(yas/expand-snippet (point) (point) template)
-Where template is the template of a snippet. It is never required -to belong to any snippet -- you can even make up it on the fly. The -1st and 2nd parameter defines the region to be deleted after YASnippet -inserted the template. It is used by yas/expand to indicate the -region of the key. There's usually no need to delete any region when -we are expanding a snippet from elisp code, so passing two (point) -is fine. Note only (point) will be fine because the 1st parameter -also indicate where to insert and expand the template.
-Indenting
-Many people miss the indenting feature of smart-snippet: when you -place a $> in your snippet, an (indent-according-to-mode) will -be executed there to indent the line. So you'll not need to hard-code -the indenting in the snippet template, and it will be very convenient -when you need to work with several different project where coding -styles are different.
-The reason why this feature wasn't added to YASnippet until after -0.5.6 is that it doesn't work well for all modes. In some cases -(e.g. python-mode), calling indent-according-to-mode will break -the overlays created by YASnippet.
-However, since many people asked for this feature, I finally added -this to YASnippet. Here's an example of the usage:
-for (${int i = 0}; ${i < 10}; ${++i})
-{$>
-$0$>
-}$>
-In 0.6.0 You should not need to use this feature although it's -supported for backward compatibility. Just set yas/indent-line to -'auto.
-The menu
+YASnippet menu
-
@@ -49,35 +47,72 @@
diff --git a/doc/snippet-menu.rst b/doc/snippet-menu.rst new file mode 100644 index 0000000..40b367d --- /dev/null +++ b/doc/snippet-menu.rst @@ -0,0 +1,85 @@ +============== +YASnippet menu +============== + +.. contents:: + +When ``yas/minor-mode`` is active, YASnippet will setup a menu just +after the Buffers Menu in the menubar. + +In this menu, you can find + +* 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. + +.. image:: images/menu-1.png + :align: right + +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-
YASnippet will setup a menu just after the Buffers Menu in the -menubar. The snippets for all real modes are listed there under the -menu. You can select a snippet from the menu to expand it. Since you -select manually from the menu, you can expand any snippet. For -example, you can expand a snippet defined for python-mode in a -c-mode buffer by selecting it from the menu:
-
+ ++Contents
-
-
- Condition system is ignored since you select to expand it -explicitly. -
- There will be no muliple candidates since they are listed in the -menu as different items. +
- Loading snippets from menu +
- Snippet menu behavior +
- Controlling indenting +
- Prompting method +
- Misc
This can be convenient sometimes. However, if you don't like the -menubar of Emacs and never use it. You can tell YASnippet don't boring -to build a menu by setting yas/use-menu to nil.
-Another thing to note is that only real modes are listed under the -menu. As you know, common snippets can be shared by making up a -virtual parent mode. It's too bad if the menu is floored by those -virtual modes. So YASnippet only show menus for those real -modes. But the snippets fo the virtual modes can still be accessed -through the parent submenu of some real mode.
-YASnippet use a simple way to check whether a mode is real or -virtual: (fboundp mode). For example, the symbol c-mode is -bound to a function while cc-mode is not. But this is not enough, -some modes aren't part of Emacs, and maybe when initializing -YASnippet, those modes haven't been initialized. So YASnippet also -maintain a list of known modes (yas/known-modes). You can add item -to that list if you need.
+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. +
+
+
+++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.
+`_ . + +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/doc/snippet-organization.html b/doc/snippet-organization.html index 924a18f..ab409b0 100644 --- a/doc/snippet-organization.html +++ b/doc/snippet-organization.html @@ -3,10 +3,8 @@ - + Organizing snippets - - @@ -52,26 +50,33 @@Contents
-Loading snippets
+Loading snippets
Snippet definitions are stored in files in the filesystem and you have to arrange for YASnippet to load them (unless you use a YASnippet -bundle (see No storage (bundle)),
-The non-bundle version of YASsnippet, once unpacked, comes with a full +bundle) into snippet tables.
+The triggering mechanisms (see Expanding snippets) will look up +these snippet tables and (hopefully) expand your intended snippet.
+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, one or more directories.
-Once these are in place reference them in the variable +
Once these directories are in place reference them in the variable yas/root-directory and then load them with yas/load-directory:
;; Develop and keep personal snippets under ~/emacs.d/mysnippets (setq yas/root-directory "~/emacs.d/mysnippets") @@ -82,32 +87,33 @@ also create or download, one or more directories.
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 here)
-If you 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")) +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) +;; Map `yas/load-directory' to every element +(mapc 'yas/load-directory yas/root-directory)
, the directories after the first are loaded, their snippets +
Here the directories after the first are loaded, their snippets considered for expansion, but development still happens in "~/emacs.d/mysnippets"
-diff --git a/doc/snippet-organization.rst b/doc/snippet-organization.rst index c4e5367..909bef4 100644 --- a/doc/snippet-organization.rst +++ b/doc/snippet-organization.rst @@ -2,9 +2,10 @@ Organizing snippets =================== -:Author: pluskid, joaotavora -:Contact: pluskid@gmail.com -:Date: 2009-08-18 +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html .. contents:: @@ -13,13 +14,16 @@ Loading snippets Snippet definitions are stored in files in the filesystem and you have to arrange for YASnippet to load them (unless you use a `YASnippet -bundleOrganizing snippets
++-Organizing snippets
Once you've setup yas/root-directory , you can store snippets -inside subdirectories of these directories.
-Common to both cases, snippet definitions are put in plain text -files. They are arranged by subdirectories, and the name of these -directories correspond to the Emacs mode where you want expansion to +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 subdirectory. You can also skip snippet storage altogether -and use the bundle (see No storage (bundle)).
+c-mode sub-directory. You can also skip snippet storage altogether +and use the bundle (see YASnippet bundle).-Nested organization
+Nested organization
Here is an excerpt of a directory hierarchy containing snippets for some modes:
-$ tree @@ -126,18 +132,20 @@ for some modes: | `-- for `-- timeThe parent directory acts as the parent mode. This is the way of -YASnippet to share snippet definitions among different modes. As you -can see above, c-mode and java-mode share the same parents -cc-mode, while all modes are derived from text-mode. This can -be also used to as an alias -- cperl-mode is an empty directory -whose parent is perl-mode.
+A parent directory acts as a parent table of any of its +sub-directories. This is one of the ways YASnippet can share snippet +definitions among different modes. As you can see above, c-mode +and java-mode share the same parents cc-mode, while all modes +are derived from text-mode.
+This can be also used to as an alias -- cperl-mode is an empty +directory whose parent is perl-mode.
+
-The .yas-parents file
+The .yas-parents file
If you place a plain text file .yas-parents inside one of the -subdirectories you can bypass nesting and still have parent modes. In -this file you just write whitespace-separated names of modes. This +sub-directories you can bypass nesting and still have parent modes. In +this file you just write white-space-separated names of modes. This allows more flexibility and readability of your snippet hierarchy.
$ tree . @@ -156,14 +164,14 @@ allows more flexibility and readability of your snippet hierarchy.
-The .yas-make-groups file
-
+The .yas-make-groups file
+
If you place an empty plain text file .yas-make-groups inside one -of the mode directories, the names of these subdirectories are -considered groups of snippets and the YASsnippet menu is organized +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
+directive inside the snippet definition. See Writing Snippets.$ tree ruby-mode/ ruby-mode/ |-- .yas-make-groups @@ -180,13 +188,15 @@ ruby-mode/
-Using plain file names
-Normally, file names act as the snippet trigger key, see Expanding -snippets. However, if you customize the -variable yas/ignore-filenames-as-triggers to be true or place an -empty file .yas-ignore-filename-triggers you can use much more -descriptive file names. This is useful (but not mandatory) if many -snippets within a mode share the same trigger key.
+Using plain file names
+Normally, file names act as the snippet expansion abbreviation (also +known as the snippet key or snippet trigger, see Expanding +Snippets).
+However, if you customize the variable +yas/ignore-filenames-as-triggers to be true or place an empty +file .yas-ignore-filename-triggers you can use much more +descriptive file names. This is useful if many snippets within a mode +share the same trigger key.
$ tree rails-mode/ rails-mode/ |-- .yas-make-groups @@ -205,14 +215,14 @@ rails-mode/
-No storage (bundle)
+++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 startup speed if you have many +
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.
+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.
@@ -223,8 +233,32 @@ 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 the functions -yas/define-snippets and yas/compile-bundle.
+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.
+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.
+ + + +`_) +``yas/new-snippet`` and others described in section `Writing +Snippets`_. -If you make this variable a list and store more items into it... +You can make this variable a list and store more items into it: .. sourcecode:: common-lisp - :align: right ;; Develop in ~/emacs.d/mysnippets, but also ;; try out snippets in ~/Downloads/interesting-snippets @@ -49,7 +52,7 @@ If you make this variable a list and store more items into it... ;; Map `yas/load-directory' to every element (mapc 'yas/load-directory yas/root-directory) -, the directories after the first are loaded, their snippets +Here the directories after the first are loaded, their snippets considered for expansion, but development still happens in "~/emacs.d/mysnippets" @@ -57,14 +60,15 @@ Organizing snippets =================== Once you've setup ``yas/root-directory`` , you can store snippets -inside subdirectories of these directories. +inside sub-directories of these directories. -Common to *both* cases, snippet definitions are put in plain text -files. They are arranged by subdirectories, and the name of these -directories correspond to the Emacs mode where you want expansion to +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`` subdirectory. You can also skip snippet storage altogether -and use the bundle (see `No storage (bundle)`_). +``c-mode`` sub-directory. You can also skip snippet storage altogether +and use the bundle (see `YASnippet bundle`_). Nested organization ------------------- @@ -90,19 +94,24 @@ for some modes: | `-- for `-- time -The parent directory acts as the *parent mode*. This is the way of -YASnippet to share snippet definitions among different modes. As you -can see above, ``c-mode`` and ``java-mode`` share the same parents -``cc-mode``, while all modes are derived from ``text-mode``. This can -be also used to as an *alias* -- ``cperl-mode`` is an empty directory -whose parent is ``perl-mode``. +A parent directory acts as a *parent table* of any of its +sub-directories. This is one of the ways YASnippet can share snippet +definitions among different modes. As you can see above, ``c-mode`` +and ``java-mode`` share the same parents ``cc-mode``, while all modes +are derived from ``text-mode``. + +This can be also used to as an *alias* -- ``cperl-mode`` is an empty +directory whose parent is ``perl-mode``. + +.. image:: images/menu-parent.png + :align: right The ``.yas-parents`` file ------------------------------ If you place a plain text file ``.yas-parents`` inside one of the -subdirectories you can bypass nesting and still have parent modes. In -this file you just write whitespace-separated names of modes. This +sub-directories you can bypass nesting and still have parent modes. In +this file you just write white-space-separated names of modes. This allows more flexibility and readability of your snippet hierarchy. .. sourcecode:: text @@ -125,17 +134,16 @@ allows more flexibility and readability of your snippet hierarchy. The ``.yas-make-groups`` file ----------------------------- -.. image:: images/group.png +.. image:: images/menu-groups.png :align: right If you place an empty plain text file ``.yas-make-groups`` inside one -of the mode directories, the names of these subdirectories are -considered groups of snippets and the `YASsnippet menu` is organized +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 - `_ +directive inside the snippet definition. See `Writing Snippets`_. .. sourcecode:: text @@ -157,12 +165,15 @@ directive inside the snippet definition. See `Writing snippets Using plain file names ---------------------- -Normally, file names act as the snippet trigger *key*, see `Expanding -snippets `_. However, if you customize the -variable ``yas/ignore-filenames-as-triggers`` to be true *or* place an -empty file ``.yas-ignore-filename-triggers`` you can use much more -descriptive file names. This is useful (but not mandatory) if many -snippets within a mode share the same trigger key. +Normally, file names act as the snippet expansion *abbreviation* (also +known as the *snippet key* or *snippet trigger*, see `Expanding +Snippets`_). + +However, if you customize the variable +``yas/ignore-filenames-as-triggers`` to be true *or* place an empty +file ``.yas-ignore-filename-triggers`` you can use much more +descriptive file names. This is useful if many snippets within a mode +share the same trigger key. .. sourcecode:: text @@ -183,17 +194,16 @@ snippets within a mode share the same trigger key. | `-- assert_select.yasnippet - -No storage (bundle) -=================== +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 startup speed if you have many +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. +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 @@ -208,5 +218,34 @@ 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 the functions -``yas/define-snippets`` and ``yas/compile-bundle``. +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. + +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. + +.. LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl +.. LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el +.. LocalWords: rjs RET diff --git a/snippet_copier.rb b/textmate_import.rb similarity index 100% rename from snippet_copier.rb rename to textmate_import.rb diff --git a/yasnippet.el b/yasnippet.el index 4558677..b258071 100644 --- a/yasnippet.el +++ b/yasnippet.el @@ -160,7 +160,29 @@ bulk reloading of all snippets using `yas/reload-all'" yas/completing-prompt yas/ido-prompt yas/no-prompt) - "Functions to prompt for keys, templates, etc interactively." + "Functions to prompt for keys, templates, etc interactively. + +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 that, when applied to each of +the objects in CHOICES will return a string. + +The return value of any function you put here should be one of +the objects in CHOICES, properly formatted with DISPLAY-FN (if +that is passed). + +* 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!\")." :type 'list :group 'yasnippet) @@ -238,9 +260,6 @@ field" (defcustom yas/fallback-behavior 'call-other-command "How to act when `yas/trigger-key' does *not* expand a snippet. -The fall back behavior of YASnippet when it can't find a snippet -to expand. - `call-other-command' means try to temporarily disable YASnippet and call the next command bound to `yas/trigger-key'. @@ -528,7 +547,7 @@ Here's an example: :active t :style radio :selected (eq yas/use-menu 'real-modes)] ["Show all modes" (setq yas/use-menu 't) :help "Show one snippet submenu for each loaded table" - :active t :style radio :selected (eq yas/use-menu 'y)] + :active t :style radio :selected (eq yas/use-menu 't)] ["Abbreviate according to current mode" (setq yas/use-menu 'abbreviate) :help "Show only snippet submenus for the current active modes" :active t :style radio :selected (eq yas/use-menu 'abbreviate)]) @@ -1271,6 +1290,8 @@ TEMPLATES is a list of `yas/template'." (yas/compute-major-mode-and-parents (concat directory "/dummy") nil no-hierarchy-parents))) + (yas/ignore-filenames-as-triggers (or yas/ignore-filenames-as-triggers + (file-exists-p (concat directory "/" ".yas-ignore-filenames-as-triggers")))) (mode-sym (and major-mode-and-parents (car major-mode-and-parents))) (parents (if making-groups-sym @@ -1397,18 +1418,21 @@ YASNIPPET-BUNDLE is the output file of the compile result. SNIPPET-ROOTS is a list of root directories that contains the snippets definition. -CODE is the code you would like to used to initialize yasnippet. +CODE is the code to be placed at the end of the generated file +and that can initialize the YASnippet bundle. Last optional argument DROPDOWN is the filename of the dropdown-list.el library. Here's the default value for all the parameters: - (yas/compile-bundle \"yasnippet.el\" - \"./yasnippet-bundle.el\" - '(\"snippets\") - \"(yas/initialize-bundle)\" - \"dropdown-list.el\") + (yas/compile-bundle \"yasnippet.el\" + \"yasnippet-bundle.el\" + \"snippets\") + \"(yas/initialize-bundle) + ### autoload + (require 'yasnippet-bundle)`\" + \"dropdown-list.el\") " (interactive "ffind the yasnippet.el file: \nFTarget bundle file: \nDSnippet directory to bundle: \nMExtra code? \nfdropdown-library: ") @@ -1503,16 +1527,22 @@ Here's the default value for all the parameters: SNIPPETS is a list of snippet definitions, each taking the following form: - (KEY TEMPLATE NAME CONDITION GROUP VARS FILE KEYBINDING) + (KEY TEMPLATE NAME CONDITION GROUP EXPAND-ENV FILE KEYBINDING) Within these, only TEMPLATE is actually mandatory. -Optional PARENT-MODE can be used to specify the parent modes of -MODE. It can be a mode symbol of a list of mode symbols. It does -not need to be a real mode. +All the elelements are strings, including CONDITION, EXPAND-ENV +and KEYBINDING which will be `read' and eventually `eval'-ed. -That is, when looking a snippet in MODE failed, it can refer to -its parent modes." +FILE is probably of very little use if you're programatically +defining snippets. + +You can use `yas/parse-template' to return such lists based on +the current buffers contents. + +Optional PARENT-MODE can be used to specify the parent tables of +MODE. It can be a mode symbol of a list of mode symbols. It does +not need to be a real mode." (let ((snippet-table (yas/snippet-table-get-create mode)) (parent-tables (mapcar #'yas/snippet-table-get-create (if (listp parent-mode)