# Writing snippets

## Table of Contents

- Snippet development
  - Quickly finding snippets
  - Using the `snippet-mode` major mode
- File content
  - `# key:` snippet abbrev
  - `# name:` snippet name
  - `# condition:` snippet condition
  - `# group:` snippet menu grouping
  - `# expand-env:` expand environment
  - `# binding:` direct keybinding
  - `# type:` `snippet` or `command`
  - `# uuid:` unique identifier
  - `# contributor:` snippet author
- Template Syntax
  - Plain Text
  - Embedded Emacs Lisp code
    - Note: backquote expressions should not modify the buffer
  - Tab stop fields
  - Placeholder fields
  - Mirrors
  - Mirrors with transformations
  - Fields with transformations
  - Choosing fields value from a list and other tricks
  - Nested placeholder fields
  - Indentation markers

## Snippet development

### Quickly finding snippets

There are some ways you can quickly find a snippet file or create a new one:

- `M-x yas-new-snippet`, key binding: `C-c & C-n`

  Creates a new buffer with a template for making a new snippet. The buffer is in `snippet-mode` (see below). When you are done editing the new snippet, use `C-c C-c` to save it.

- `M-x yas-visit-snippet-file`, key binding: `C-c & C-v`

  Prompts you for possible snippet expansions like `yas-insert-snippet`, but instead of expanding it, takes you directly to the snippet definition's file, if it exists.

Once you find this file it will be set to `snippet-mode` (see ahead) and you can start editing your snippet.

### Using the `snippet-mode` major mode

There is a major mode `snippet-mode` to edit snippets. You can set the buffer to this mode with `M-x snippet-mode`. It provides reasonably useful syntax highlighting.

Three commands are defined in this mode:

- `M-x yas-load-snippet-buffer`, key binding: `C-c C-l`

  Prompts for a snippet table (with a default based on snippet's major mode) and loads the snippet currently being edited.

- `M-x yas-load-snippet-buffer-and-close`, key binding: `C-c C-c`

  Like `yas-load-snippet-buffer`, but also saves the snippet and calls `quit-window`. The destination is decided based on the chosen snippet table and snippet collection directly (defaulting to the first directory in `yas-snippet-dirs` (see Organizing Snippets for more detail on how snippets are organized).

- `M-x yas-tryout-snippet`, key binding: `C-c C-t`

  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.

There are also snippets for writing snippets: `vars`, `$f` and `$m` :-).

## File content

A file defining a snippet generally contains the template to be expanded.

Optionally, if the file contains a line of `# --`, the lines above it count as comments, some of which can be directives (or meta data). Snippet directives look like `# property: value` and tweak certain snippet properties described below. If no `# --` is found, the whole file is considered the snippet template.

Here's a typical example:

    # contributor: pluskid <pluskid@gmail.com>
    # name: __...__
    # --
    __${init}__

Here's a list of currently supported directives:

### `# key:` snippet abbrev

This is the probably the most important directive, it's the abbreviation you type to expand a snippet just before hitting the key that runs `yas-expand`. If you don't specify this, the snippet will not be expandable through the trigger mechanism.

### `# name:` snippet name

This is a one-line description of the snippet. It will be displayed in the menu. It's a good idea to select a descriptive name for a snippet – especially distinguishable among similar snippets.

If you omit this name, it will default to the file name the snippet was loaded from.

### `# condition:` snippet condition

This is a piece of Emacs Lisp code. If a snippet has a condition, then it will only be expanded when the condition code evaluate to some non-nil value.

See also `yas-buffer-local-condition` in Expanding snippets

### `# group:` snippet menu grouping

When expanding/visiting snippets from the menu-bar menu, snippets for a given mode can be grouped into sub-menus. This is useful if one has too many snippets for a mode which will make the menu too long.

The `# group:` property only affect menu construction (See the YASnippet menu) and the same effect can be achieved by grouping snippets into sub-directories and using the `.yas-make-groups` special file (for this see Organizing Snippets

Refer to the bundled snippets for `ruby-mode` for examples of the `# group:` directive. Group can also be nested, e.g. `control structure.loops` indicates 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 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.

### `# type:` `snippet` or `command`

If the `type` directive is set to `command`, the body of the snippet is interpreted as Lisp code to be evaluated when the snippet is triggered.

If it's `snippet` (the default when there is no `type` directive), the snippet body will be parsed according to the Template Syntax, described below.

### `# uuid:` unique identifier

This provides to a way to identify a snippet, independent of its name. Loading a second snippet file with the same uuid would replace the previous snippet.

### `# contributor:` snippet author

This is optional and has no effect whatsoever on snippet functionality, but it looks nice.

## Template Syntax

The syntax of the snippet template is simple but powerful, very similar to TextMate's.

### Plain Text

Arbitrary text can be included as the content of a template. They are usually interpreted as plain text, except `$` and ```. You need to use `\` to escape them: `\$` and `\``. The `\` itself may also needed to be escaped as `\\` sometimes.

### Embedded Emacs Lisp code

Emacs Lisp code can be embedded inside the template, written inside back-quotes (```). The Lisp forms are evaluated when the snippet is being expanded. The evaluation is done in the same buffer as the snippet being expanded.

Here's an example for `c-mode` to calculate the header file guard dynamically:

    #ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
    #define $1

    $0

    #endif /* $1 */

From version 0.6, snippet expansions are run with some special Emacs Lisp variables bound. One of these is `yas-selected-text`. You can therefore define a snippet like:

    for ($1;$2;$3) {
      `yas-selected-text`$0
    }

to "wrap" the selected region inside your recently inserted snippet. Alternatively, you can also customize the variable `yas-wrap-around-region` to `t` which will do this automatically.

#### Note: backquote expressions should not modify the buffer

Please note that the Lisp forms in backquotes should not modify the buffer, doing so will trigger a warning. For example, instead of doing

    Timestamp: `(insert (current-time-string))`

do this:

    Timestamp: `(current-time-string)`

The warning may be suppressed with the following code in your init file:

    (add-to-list 'warning-suppress-types '(yasnippet backquote-change))

### Tab stop fields

Tab stops are fields that you can navigate back and forth by `TAB` and `S-TAB`. They are written by `$` followed with a number. `$0` has the special meaning of the exit point of a snippet. That is the last place to go when you've traveled all the fields. Here's a typical example:

    <div$1>
        $0
    </div>

### Placeholder fields

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

    ${N:default value}

They act as the default value for a tab stop. But when you first type at a tab stop, the default value will be replaced by your typing. The number can be omitted if you don't want to create mirrors or transformations for this field.

### Mirrors

We refer to tab stops with placeholders as a field. A field can have mirrors. All mirrors get updated whenever you update any field text. Here's an example:

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

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

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

### Mirrors with transformations

If the value of an `${n:`-construct starts with and contains `$(`, then it is interpreted as a mirror for field `n` with a transformation. The mirror's text content is calculated according to this transformation, which is Emacs Lisp code that gets evaluated in an environment where the variable `yas-text` is bound to the text content (string) contained in the field `n`. Here's an example for Objective-C:

    - (${1:id})${2:foo}
    {
        return $2;
    }

    - (void)set${2:$(capitalize yas-text)}:($1)aValue
    {
        [$2 autorelease];
        $2 = [aValue retain];
    }
    $0

Look at `${2:$(capitalize yas-text)}`, it is a mirror with transformation instead of a field. The actual field is at the first line: `${2:foo}`. When you type text in `${2:foo}`, the transformation will be evaluated and the result will be placed there as the transformed text. So in this example, if you type "baz" in the field, the transformed text will be "Baz". This example is also available in the screencast.

Another example is for `rst-mode`. In reStructuredText, the document title can be some text surrounded by "`=`" below and above. The "`=`" should be at least as long as the text. So

    =====
    Title
    =====

is a valid title but

    ===
    Title
    ===

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

    ${1:$(make-string (string-width yas-text) ?\=)}
    ${1:Title}
    ${1:$(make-string (string-width yas-text) ?\=)}

    $0

Note that a mirror with a transform is not restricted to the text of the field it is mirroring. By making use of `yas-field-value`, a mirror can look at any of the snippet's field (as mentioned above, all mirrors are updated when any field is updated). Here is an example which shows a "live" result of calling format:

    (format "${1:formatted %s}" "${2:value}")
    => "${1:$(ignore-errors (format (yas-field-value 1) (yas-field-value 2)))}"

To keep the example simple, it uses `ignore-errors` to suppress errors due to incomplete format codes.

### Fields with transformations

From version 0.6 on, you can also have Lisp transformation inside fields. These work mostly like mirror transformations. However, they are evaluated when you first enter the field, after each change you make to the field and also just before you exit the field.

The syntax is also a tiny bit different, so that the parser can distinguish between fields and mirrors. In the following example

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

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

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

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

Please note that as soon as a transformation takes place, it changes the value of the field and sets it its internal modification state to `true`. As a consequence, the auto-deletion behaviour of normal fields does not take place. This is by design.

### Choosing fields value from a list and other tricks

As mentioned, the field transformation is invoked just after you enter the field, and with some useful variables bound, notably `yas-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.

For example, the `yas-completing-read` function is version of `completing-read` which checks these variables. For example, asking the user for the initial value of a field:

    <div align="${2:$$(yas-completing-read "Alignment? " '("right" "center" "left"))}">
      $0
    </div>

See the definition of `yas-completing-read` to see how it was written using the two variables. If you're really lazy :) and can't spare a tab keypress, you can automatically move to the next field (or exit) after choosing the value with `yas-auto-next`. The snippet above becomes:

    <div align="${2:$$(yas-auto-next
                        (yas-completing-read
                          "Alignment? "
                          '("right" "center" "left")))}">
      $0
    </div>

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

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

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

### Nested placeholder fields

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

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

This allows you to choose if you want to give this `div` an `id` attribute. If you tab forward after expanding, it will let you change "some\id" to whatever you like. Alternatively, you can just press `C-d` (which executes `yas-skip-and-clear-or-delete-char`) and go straight to the exit marker.

By the way, `C-d` will only clear the field if you cursor is at the beginning of the field and it hasn't been changed yet. Otherwise, it performs the normal Emacs `delete-char` command.

### Indentation markers

If `yas-indent-line` is not set to '`auto`, it's still possible to indent specific lines by adding an indentation marker, `$>`, somewhere on the line.

Generated by Emacs 29.1 (Org mode 9.6.6) from 0.14.0 (2023-10-08 15:34:57)

Validate