From 6c88b24bf86a86728a4f76939484955bdf7edec8 Mon Sep 17 00:00:00 2001 From: capitaomorte Date: Sun, 23 Aug 2009 19:52:33 +0000 Subject: [PATCH] doc almost complete. Drawing closer to 0.6.1b --- doc/changelog.html | 23 +- doc/changelog.rst | 28 +- doc/compile-doc.py | 50 ++ doc/images/customization-group.png | Bin 54785 -> 60007 bytes doc/images/dropdown-menu.png | Bin 40488 -> 31811 bytes doc/images/group.png | Bin 80647 -> 0 bytes doc/images/ido-menu.png | Bin 0 -> 58102 bytes doc/images/idrop-menu.png | Bin 10294 -> 0 bytes doc/images/menu-1.png | Bin 0 -> 68953 bytes doc/images/menu-2.png | Bin 0 -> 60421 bytes doc/images/menu-groups.png | Bin 0 -> 84358 bytes doc/images/menu-parent.png | Bin 0 -> 73275 bytes doc/images/menubar.png | Bin 14917 -> 0 bytes doc/images/popup-menu.png | Bin 25430 -> 0 bytes doc/images/x-menu.png | Bin 0 -> 34263 bytes doc/index.html | 102 ++-- doc/index.rst | 94 ++-- doc/snippet-development.html | 364 ++++++++++--- doc/snippet-development.rst | 386 ++++++++++++-- doc/snippet-expansion.html | 649 ++++++++++++------------ doc/snippet-expansion.rst | 571 +++++++++++---------- doc/snippet-menu.html | 101 ++-- doc/snippet-menu.rst | 85 ++++ doc/snippet-organization.html | 152 +++--- doc/snippet-organization.rst | 125 +++-- snippet_copier.rb => textmate_import.rb | 0 yasnippet.el | 64 ++- 27 files changed, 1806 insertions(+), 988 deletions(-) delete mode 100644 doc/images/group.png create mode 100644 doc/images/ido-menu.png delete mode 100644 doc/images/idrop-menu.png create mode 100644 doc/images/menu-1.png create mode 100644 doc/images/menu-2.png create mode 100644 doc/images/menu-groups.png create mode 100644 doc/images/menu-parent.png delete mode 100644 doc/images/menubar.png delete mode 100644 doc/images/popup-menu.png create mode 100644 doc/images/x-menu.png create mode 100644 doc/snippet-menu.rst rename snippet_copier.rb => textmate_import.rb (100%) diff --git a/doc/changelog.html b/doc/changelog.html index 73dc5a3..19a9009 100644 --- a/doc/changelog.html +++ b/doc/changelog.html @@ -3,10 +3,8 @@ - + ChangeLog - - @@ -49,7 +47,24 @@
-
+
+

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

-

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 .emacs
 
Please refer to the documentation for full customization, or use the
 customization group.

-images/customization-group.png

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:

    -
  1. Organizing snippets
    2. +
  2. Organizing Snippets
-

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.
    -
  1. Controlling snippet expansion
    2. +
  2. Expanding Snippets
-

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

+
    -
  1. Defining your own snippets
    2. +
  2. Writing Snippets
-

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.
+
    +
  1. The YASnippet menu
    2. +
+
+Explains how to use the YASnippet menu to explore and learn new +snippets.
-

Bugs, Contribution and Support

+

Bugs, Contribution and Support

Thank you very much for using YASnippet!

+
diff --git a/doc/index.rst b/doc/index.rst index 439406a..94a8cee 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,42 +2,47 @@ Yet Another Snippet extension ============================= -:Author: pluskid -:Contact: pluskid@gmail.com -:Date: 2008-03-20 +.. _Organizing Snippets: snippet-organization.html +.. _Expanding Snippets: snippet-expansion.html +.. _Writing Snippets: snippet-development.html +.. _The YASnippet Menu: snippet-menu.html .. 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 most TextMate templates to YASnippet. + +YASnippet is a re-write of the extension `smart-snippet`_. Both are +original creations of `pluskid `_. .. _smart-snippet: http://code.google.com/p/smart-snippet/ Video Demo ========== +.. youtube:: vOj7btx3ATg + :align: right + 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 @@ -52,7 +57,7 @@ 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: .. sourcecode:: common-lisp @@ -80,71 +85,50 @@ following in your ``.emacs`` file: Please refer to the documentation for full customization, or use the customization group. -.. image:: images/customization-group.png - :align: right - 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: -1. `Organizing snippets `_ +1. `Organizing Snippets`_ -Describes ways to organize your snippets in the hard disk, or not -organize them at all and just use plain old elisp. + Describes ways to organize your snippets in the hard disk (or not + organize them at all and just use ``yasnippet-bundle.el``. -Also explains how to use the YASnippet menu to explore and learn new -snippets. +2. `Expanding Snippets`_ -2. `Controlling snippet expansion `_ + 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. Also you might want snippets to wrap -themselves around a region of selected text, use a direct keybinding, -control indenting, etc... + Maybe, you'll want some snippets to be expanded in a particular + mode, or only under certain conditions, or be prompted using + ``ido``, etc... -3. `Defining your own snippets `_ +3. `Writing Snippets`_ -Describes the YASnippet definition syntax, which is similar, but not -equivalent to Textmate's. Includes a section about converting Textmate -snippets. + Describes the YASnippet definition syntax, which is very close (but + not equivalent) to Textmate's. Includes a section about converting + TextMate snippets. -Customization group -=================== +4. `The YASnippet menu`_ -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. + Explains how to use the YASnippet menu to explore and learn new + snippets. 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`_. .. _discussion group: http://groups.google.com/group/smart-snippet .. _wish list: http://code.google.com/p/yasnippet/wiki/WishList Thank you very much for using YASnippet! + +.. LocalWords: YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki diff --git a/doc/snippet-development.html b/doc/snippet-development.html index aea88ca..96cf209 100644 --- a/doc/snippet-development.html +++ b/doc/snippet-development.html @@ -3,10 +3,8 @@ - + Writing snippets - - @@ -52,28 +50,61 @@ -
-

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 to

    There 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>
@@ -304,6 +443,103 @@ 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 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.

+ + + +
diff --git a/doc/snippet-development.rst b/doc/snippet-development.rst index 780f585..a8e3b66 100644 --- a/doc/snippet-development.rst +++ b/doc/snippet-development.rst @@ -2,23 +2,34 @@ Writing 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:: -Quickly finding/defining snippets ---------------------------------- +Snippet development +=================== -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) +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``. + loaded from (if it exists) like ``find-file-other-window``. * ``M-x yas/visit-snippet-file`` @@ -30,32 +41,199 @@ snippet file. Once you find this file it will be set to 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. +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`` - +* ``M-x yas/load-snippet-buffer`` + When editing a snippet, this loads the snippet into the correct mode and menu. Bound to ``C-c C-c`` by default while in ``snippet-mode``. - -* ``M-x yas/tryout-snippet`` - + +* ``M-x yas/tryout-snippet`` + When editing a snippet, this opens a new empty buffer, sets it to the appropriate major mode and inserts the snippet there, so you can see what it looks like. This is bound to ``C-c C-t`` while in ``snippet-mode``. - + There 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: + +.. sourcecode:: text + + #contributor : pluskid + #name : __...__ + # -- + __${init}__ + +Meta data are specified in the syntax of + +.. sourcecode:: text + + #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. -The Syntax of the Template -========================== +``# condition:`` snippet condition +---------------------------------- +This is a piece of Emacs-lisp code. If a snippet has a condition, then it +will only be expanded when the condition code evaluate to some non-nil +value. + +See also ``yas/buffer-local-condition`` in `Expanding snippets`_ + + + +``# group`` snippet menu grouping + +When expanding/visiting snippets from the menu-bar menu, snippets for a +given mode can be grouped into sub-menus . This is useful if one has +too many snippets for a mode which will make the menu too +long. + +The ``# group:`` property only affect menu construction (See `the +YASnippet menu`_) and the same effect can be achieved by grouping +snippets into sub-directories and using the ``.yas-make-groups`` +special file (for this see `Organizing Snippets`_ + + +Refer to the bundled snippets for ``ruby-mode`` for examples on the +``# group:`` directive. Group can also be nested, e.g. ``control +structure.loops`` tells that the snippet is under the ``loops`` group +which is under the ``control structure`` group. + +``# expand-env:`` expand environment +------------------------------------ + +This is another piece of Emacs-lisp code in the form of a ``let`` *varlist* +form, i.e. a list of lists assigning values to variables. It can be +used to override variable values while the snippet is being expanded. + +Interesting variables to override are ``yas/wrap-around-region`` and +``yas/indent-line`` (see `Expanding Snippets`_). + + +As an example, you might normally have ``yas/indent-line`` set to +``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this +particularly brilliant piece of ASCII art these values would mess up +your hard work. You can then use: + +.. sourcecode:: text + + # name : ASCII home + # expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil)) + # -- + welcome to my + X humble + / \ home, + / \ $0 + / \ + /-------\ + | | + | +-+ | + | | | | + +--+-+--+ + +``# binding:``: direct keybinding +--------------------------------- + +You can use this directive to expand a snippet directly from a normal +Emacs keybinding. The keybinding will be registered in the Emacs +keymap named after the major mode the snippet is active +for. + +Additionally a variable ``yas/prefix`` is set to to the prefix +argument you normally use for a command. This allows for small +variations on the same snippet, for example in this "html-mode" +snippet. + +.. sourcecode:: text + + #name :

...

+ #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:: text
$0
- + See the definition of ``yas/choose-value`` to see how it was written using the two variables. Also check out ``yas/verify-value`` for another neat trick. @@ -288,8 +462,134 @@ 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. +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 ``("" ")"``. + +``yas/skip-and-clear-key`` +-------------------------- + +The key to clear the currently active field. + +Value is a string that is converted to the internal Emacs key +representation using ``read-kbd-macro``. + +Can also be a list of keys. + +Default value is ``"C-d"``. + +``yas/good-grace`` +------------------ + +If non-nil, don't raise errors in inline Emacs-lisp evaluation inside +snippet definitions. An error string "[yas] error" is returned instead. + +``yas/indent-line`` +------------------- + +The variable ``yas/indent-line`` controls the indenting. It is bound +to ``'auto`` by default, which causes your snippet to be indented +according to the mode of the buffer it was inserted in. + +Another variable ``yas/also-auto-indent-first-line``, when non-nil +does exactly that :-). + +To use the hard-coded indentation in your snippet template, set this +variable to ``fixed``. + +To control indentation on a per-snippet basis, see also the directive +``# expand-env:`` in `Writing Snippets`_. + +For backward compatibility with earlier versions of YASnippet, you can +also place a ``$>`` in your snippet, an ``(indent-according-to-mode)`` +will be executed there to indent the line. This only takes effect when +``yas/indent-line`` is set to something other than ``'auto``. + +.. sourcecode:: text + + for (${int i = 0}; ${i < 10}; ${++i}) + {$> + $0$> + }$> + +``yas/wrap-around-region`` +-------------------------- + +If non-nil, YASnippet will try to expand the snippet's exit marker +around the currently selected region. When this variable is set to t, +this has the same effect has using the ```yas/selected-text``` inline +evaluation. + +Because on most systems starting to type deletes the currently 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. + +.. LocalWords: html YASnippet yas sourcecode pluskid init filenames filename +.. LocalWords: env varlist keybinding keymap rinari ifndef upcase endif +.. LocalWords: nondirectory autorelease aValue inline diff --git a/doc/snippet-expansion.html b/doc/snippet-expansion.html index 6d346f6..9ebcade 100644 --- a/doc/snippet-expansion.html +++ b/doc/snippet-expansion.html @@ -3,10 +3,8 @@ - + Expanding snippets - - @@ -52,96 +50,344 @@ -
-

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:

-images/group.png +
+

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.

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

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

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.

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

-images/popup-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.
    • -
  • 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.

-
images/idrop-menu.png
-
-
-

Use dropdown-menu.el

-

The function yas/dropdown-prompt can also be placed in the -yas/prompt-functions list.

-images/dropdown-menu.png -

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

-images/minor-mode-indicator.png -

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.

-
diff --git a/doc/snippet-expansion.rst b/doc/snippet-expansion.rst index dfc5300..67e7d6c 100644 --- a/doc/snippet-expansion.rst +++ b/doc/snippet-expansion.rst @@ -2,157 +2,242 @@ Expanding 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:: -Some stuff -========== -File content ------------- +Triggering expansion +==================== -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. +You can use YASnippet to expand snippets in different ways: -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. +* 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; -Here's a typical example: +* 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. -.. sourcecode:: text +* By using the keybinding associated with an active snippet. This also + requires ``yas/minor-mode`` to be active; - #contributor : pluskid - #name : __...__ - # -- - __${init}__ +* By expanding directly from the "YASnippet" menu in the menu-bar -Meta data are specified in the syntax of +* By using hippie-expand -.. sourcecode:: text +* Expanding from emacs-lisp code - #data-name : data value +Trigger key +----------- -Any other text above ``# --`` is considered as comment and -ignored. Here's a list of currently supported meta data: +When ``yas/minor-mode`` is enabled, the keybinding taken from +``yas/trigger-key`` will take effect. -.. image:: images/group.png - :align: right +``yas/trigger-key`` invokes ``yas/expand``, which tries to expand a +*snippet abbrev* (also known as *snippet key*) before point. -* ``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. +The default key is ``"TAB"``, however, you can freely set it to some +other key. +.. image:: images/minor-mode-indicator.png + :align: left +To enable the YASnippet minor mode in all buffers globally use the +command ``yas/global-mode``. -The strategy to select a snippet -================================ +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. -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. +Trouble when using or understanding the ``yas/trigger-key`` is easily +the most controversial issue in YASsnippet. See the `FAQ `_. -Finding the key +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 --------------- -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. +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. -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: +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``. -* 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. +The prompting methods used are again controlled by +``yas/prompt-functions``. -But you'd better keep the default value unless you understand what -Emacs's syntax rule mean. +Snippet keybinding +------------------ + +See the section of the ``# binding:`` directive in `Writing +Snippets`_. + + +Expanding from the menu +----------------------- + +See `the YASnippet Menu`_. + +Expanding with ``hippie-expand`` +---------------------------------- + +To integrate with ``hippie-expand``, just put +``yas/hippie-try-expand`` in +``hippie-expand-try-functions-list``. This probably makes more sense +when placed at the top of the list, but it can be put anywhere you +prefer. + +Expanding from emacs-lisp code +------------------------------ + +Sometimes you might want to expand a snippet directly 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: + +.. sourcecode:: common-lisp + + (yas/expand-snippet template) + +See the internal documentation on ``yas/expand-snippet`` for more +information. + +Controlling expansion +===================== + +Eligible snippets +----------------- + +YASnippet does quite a bit of filtering to find out which snippets are +eligible for expanding at 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. + +.. sourcecode:: common-lisp + + ;; When entering rinari-minor-mode, consider also the snippets in the + ;; snippet table "rails-mode" + (add-hook 'rinari-minor-mode-hook + #'(lambda () + (setq yas/mode-symbol 'rails-mode))) + +* Buffer-local ``yas/buffer-local-condition`` variable + + This variable provides 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 -------------------- -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, +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``). +in a comment block or a string (e.g. in ``python-mode``). -It's OK, just specify the condition for ``if`` to be ``(not +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 YASnippet introduce a buffer local variable +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``. There's no way -to do this in smart-snippet.el! +(python-in-string/comment))`` in ``python-mode-hook``. -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: +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, snippet won't be - expanded. -* If it evaluate to the a cons cell where the ``car`` is the symbol +* 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``): + call it ``requirement``), then: - * 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 + * 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. + expanded; + * If ``requirement`` is ``eq`` to ``result``, the snippet is ready - to be expanded. - * Otherwise the snippet won't be expanded. + to be expanded; + + * Otherwise the snippet won't be considered. -* If it evaluate to other non-nil value: +* 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 expanded. + + * Otherwise, it won't be considered. -So set ``yas/buffer-local-condition`` like this +In the mentioned scenario, set ``yas/buffer-local-condition`` like +this .. sourcecode:: common-lisp @@ -163,28 +248,19 @@ So set ``yas/buffer-local-condition`` like this '(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. +... 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 ----------------------------------- +Multiples 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``. +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. There're two variable related: - -From version 0.6 of YASnippet this has changed significantly. A new +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. @@ -198,7 +274,7 @@ emacs-file: Currently there are some alternatives solution with YASnippet. -.. image:: images/popup-menu.png +.. image:: images/x-menu.png :align: right Use the X window system @@ -214,6 +290,9 @@ which means: ``C-p`` to navigate. * This function can't be used when in a terminal. +.. image:: images/ido-menu.png + :align: right + Use built-in Emacs selection methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -221,8 +300,8 @@ You can use functions ``yas/completing-prompt`` for the classic emacs completion method or ``yas/ido-prompt`` for a much nicer looking method. The best way is to try it. This works in a terminal. -.. image:: images/idrop-menu.png - :align: center +.. image:: images/dropdown-menu.png + :align: right Use ``dropdown-menu.el`` ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -230,181 +309,97 @@ Use ``dropdown-menu.el`` The function ``yas/dropdown-prompt`` can also be placed in the ``yas/prompt-functions`` list. -.. image:: images/dropdown-menu.png - :align: right +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. -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! +Roll your own +~~~~~~~~~~~~~ -* 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. +See below for the documentation on variable ``yas/prompt-functions`` -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). +Customizable Variables +====================== -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 - -.. sourcecode:: common-lisp - - (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 -~~~~~~~~~~~~~~ - -.. image:: images/minor-mode-indicator.png - :align: left - -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: - -.. sourcecode:: common-lisp - - (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``. +``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: -Expanding From Elisp Code -~~~~~~~~~~~~~~~~~~~~~~~~~ +* PROMPT: A string to prompt the user; -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. +* CHOICES: A list of strings or objects; -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: +* optional DISPLAY-FN : A function. When applied to each of the + objects in CHOICES it will return a string; -.. sourcecode:: common-lisp +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). - (yas/expand-snippet (point) (point) template) +* To signal that your particular style of prompting is unavailable at + the moment, you can also have the function return nil. -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: - -.. sourcecode:: text - - 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``. +* 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 +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 understand what +Emacs's syntax rule mean. diff --git a/doc/snippet-menu.html b/doc/snippet-menu.html index 32b0bdb..d85464f 100644 --- a/doc/snippet-menu.html +++ b/doc/snippet-menu.html @@ -3,20 +3,18 @@ - -The menu - - + +YASnippet menu -
+