# Reference

## Table of Contents

- Interactive functions
  - `yas-abort-snippet` (&optional `snippet`)
  - `yas-visit-snippet-file` ()
  - `yas-load-snippet-buffer` (`table` &optional `interactive`)
  - `yas-global-mode` (&optional `arg`)
  - `yas-skip-and-clear-or-delete-char` (&optional `field`)
  - `yas-next-field` (&optional `arg`)
  - `yas-insert-snippet` (&optional `no-condition`)
  - `yas-activate-extra-mode` (`mode`)
  - `yas-recompile-all` ()
  - `yas-compile-directory` (`top-level-dir`)
  - `yas-direct-keymaps-reload` ()
  - `yas-exit-all-snippets` ()
  - `yas-tryout-snippet` (&optional `debug`)
  - `yas-exit-snippet` (`snippet`)
  - `yas-expand` (&optional `field`)
  - `yas-expand-from-keymap` ()
  - `yas-minor-mode` (&optional `arg`)
  - `yas-minor-mode-on` ()
  - `yas-reload-all` (&optional `no-jit` `interactive`)
  - `yas-load-directory` (`top-level-dir` &optional `use-jit` `interactive`)
  - `yas-new-snippet` (&optional `no-template`)
  - `yas-load-snippet-buffer-and-close` (`table` &optional `kill`)
  - `yas-describe-tables` (&optional `choose`)
  - `yas-deactivate-extra-mode` (`mode`)
  - `yas-next-field-or-maybe-expand` ()
  - `yas-about` ()
  - `yas-prev-field` ()
  - `yas-expand-from-trigger-key` (&optional `field`)
- Customization variables
  - `yas-choose-tables-first`
  - `yas-snippet-revival`
  - `yas-also-auto-indent-first-line`
  - `yas-new-snippet-default`
  - `yas-choose-keys-first`
  - `yas-fallback-behavior`
  - `yas-wrap-around-region`
  - `yas-prompt-functions`
  - `yas-visit-from-menu`
  - `yas-triggers-in-field`
  - `yas-trigger-symbol`
  - `yas-use-menu`
  - `yas-indent-line`
  - `yas-expand-only-for-last-commands`
  - `yas-snippet-dirs` ()
  - `yas-good-grace`
- Useful functions
  - `yas-default-from-field` (`number`)
  - `yas-completing-prompt` (`prompt` `choices` &optional `display-fn` `completion-fn`)
  - `yas-selected-text` ()
  - `yas-hippie-try-expand` (`first-time?`)
  - `yas-global-mode-cmhh` ()
  - `yas-throw` (`text`)
  - `yas-inside-string` ()
  - `yas-x-prompt` (`prompt` `choices` &optional `display-fn`)
  - `yas-shortest-key-until-whitespace` (`_start-point`)
  - `yas-longest-key-from-whitespace` (`start-point`)
  - `yas-text` ()
  - `yas-ido-prompt` (`prompt` `choices` &optional `display-fn`)
  - `yas-try-key-from-whitespace` (`_start-point`)
  - `yas-dropdown-prompt` (`_prompt` `choices` &optional `display-fn`)
  - `yas-define-snippets` (`mode` `snippets`)
  - `yas-global-mode-enable-in-buffers` ()
  - `yas-no-prompt` (`_prompt` `choices` &optional `_display-fn`)
  - `yas-active-keys` ()
  - `yas-define-condition-cache` (`func` `doc` &rest `body`)
  - `yas-global-mode-check-buffers` ()
  - `yas-define-menu` (`mode` `menu` &optional `omit-items`)
  - `yas-field-value` (`number`)
  - `yas-verify-value` (`possibilities`)
  - `yas-key-to-value` (`alist`)
  - `yas-choose-value` (&rest `possibilities`)
  - `yas-substr` (`str` `pattern` &optional `subexp`)
  - `yas-unimplemented` (&optional `missing-feature`)
  - `yas-expand-snippet` (`content` &optional `start` `end` `expand-env`)
  - `yas-minor-mode-set-explicitly` ()
- Useful variables
  - `yas-global-mode-buffers`
  - `yas-after-reload-hook`
  - `yas-snippet-beg`
  - `yas-after-exit-snippet-hook`
  - `yas-global-mode-hook`
  - `yas-dont-activate`
  - `yas-minor-mode-map`
  - `yas-moving-away-p`
  - `yas-buffer-local-condition`
  - `yas-modified-p`
  - `yas-before-expand-snippet-hook`
  - `yas-keymap`
  - `yas-key-syntaxes`
  - `yas-snippet-end`
  - `yas-minor-mode-hook`
  - `yas-verbosity`
  - `yas-minor-mode-major-mode`
  - `yas-installed-snippets-dir`

## Interactive functions

### `yas-abort-snippet` (&optional `snippet`)

warning: no doc for symbol `yas-abort-snippet`

### `yas-visit-snippet-file` ()

Choose a snippet to edit, selection like `yas-insert-snippet`.

Only success if selected snippet was loaded from a file. Put the visited file in `snippet-mode`.

### `yas-load-snippet-buffer` (`table` &optional `interactive`)

Parse and load current buffer's snippet definition into `table`.

`table` is a symbol naming a passed to `yas--table-get-create`.

When called interactively, prompt for the table name.

### `yas-global-mode` (&optional `arg`)

Toggle Yas minor mode in all buffers. With prefix `arg`, enable Yas-Global mode if `arg` is positive; otherwise, disable it. If called from Lisp, enable the mode if `arg` is omitted or nil.

Yas minor mode is enabled in all buffers where `yas-minor-mode-on` would do it. See `yas-minor-mode` for more information on Yas minor mode.

### `yas-skip-and-clear-or-delete-char` (&optional `field`)

Clears unmodified field if at field start, skips to next tab.

Otherwise deletes a character normally by calling `delete-char`.

### `yas-next-field` (&optional `arg`)

Navigate to the `arg`th next field.

If there's none, exit the snippet.

### `yas-insert-snippet` (&optional `no-condition`)

Choose a snippet to expand, pop-up a list of choices according to `yas-prompt-functions`.

With prefix argument `no-condition`, bypass filtering of snippets by condition.

### `yas-activate-extra-mode` (`mode`)

Activates the snippets for the given `mode` in the buffer.

The function can be called in the hook of a minor mode to activate snippets associated with that mode.

### `yas-recompile-all` ()

Compile every dir in `yas-snippet-dirs`.

### `yas-compile-directory` (`top-level-dir`)

Create .yas-compiled-snippets.el files under subdirs of `top-level-dir`.

This works by stubbing a few functions, then calling `yas-load-directory`.

### `yas-direct-keymaps-reload` ()

Force reload the direct keybinding for active snippet tables.

### `yas-exit-all-snippets` ()

Exit all snippets.

### `yas-tryout-snippet` (&optional `debug`)

Test current buffer's snippet template in other buffer.

### `yas-exit-snippet` (`snippet`)

Goto exit-marker of `snippet`.

### `yas-expand` (&optional `field`)

Expand a snippet before point. If no snippet expansion is possible, defer to `yas-fallback-behavior` (which see).

Optional argument `field` is for non-interactive use and is an object satisfying `yas--field-p` to restrict the expansion to.

### `yas-expand-from-keymap` ()

Expand/run snippets from keymaps, possibly falling back to original binding.

### `yas-minor-mode` (&optional `arg`)

Toggle YASnippet mode.

When YASnippet mode is enabled, `yas-expand`, normally bound to the tab key, expands snippets of code depending on the major mode.

With no argument, this command toggles the mode. positive prefix argument turns on the mode. Negative prefix argument turns off the mode.

Key bindings: \{yas-minor-mode-map}

### `yas-minor-mode-on` ()

Turn on YASnippet minor mode.

Honour `yas-dont-activate`, which see.

### `yas-reload-all` (&optional `no-jit` `interactive`)

Reload all snippets and rebuild the YASnippet menu.

When `no-jit` is non-nil force immediate reload of all known snippets under `yas-snippet-dirs`, otherwise use just-in-time loading.

When called interactively, use just-in-time loading when given a prefix argument.

### `yas-load-directory` (`top-level-dir` &optional `use-jit` `interactive`)

Load snippets in directory hierarchy `top-level-dir`.

Below `top-level-dir` each directory should be a mode name.

With prefix argument `use-jit` do jit-loading of snippets.

### `yas-new-snippet` (&optional `no-template`)

Pops a new buffer for writing a snippet.

Expands a snippet-writing snippet, unless the optional prefix arg `no-template` is non-nil.

### `yas-load-snippet-buffer-and-close` (`table` &optional `kill`)

Load the snippet with `yas-load-snippet-buffer`, possibly save, then `quit-window` if saved.

If the snippet is new, ask the user whether (and where) to save it. If the snippet already has a file, just save it.

The prefix argument `kill` is passed to `quit-window`.

Don't use this from a Lisp program, call `yas-load-snippet-buffer` and `kill-buffer` instead.

### `yas-describe-tables` (&optional `choose`)

Display snippets for each table.

### `yas-deactivate-extra-mode` (`mode`)

Deactivates the snippets for the given `mode` in the buffer.

### `yas-next-field-or-maybe-expand` ()

Try to expand a snippet at a key before point.

Otherwise delegate to `yas-next-field`.

### `yas-about` ()

warning: no doc for symbol `yas-about`

### `yas-prev-field` ()

Navigate to prev field. If there's none, exit the snippet.

### `yas-expand-from-trigger-key` (&optional `field`)

Expand a snippet before point.

If no snippet expansion is possible, fall back to the behaviour defined in `yas-fallback-behavior`.

Optional argument `field` is for non-interactive use and is an object satisfying `yas--field-p` to restrict the expansion to.

## Customization variables

### `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-snippet-revival`

Non-nil means re-activate snippet fields after undo/redo.

### `yas-also-auto-indent-first-line`

Non-nil means also auto indent first line according to mode.

Naturally this is only valid when `yas-indent-line` is `auto`

### `yas-new-snippet-default`

Default snippet to use when creating a new snippet. If nil, don't use any snippet.

### `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-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 whatever key was used to invoke `yas-expand`.
- nil or the symbol `return-nil` mean do nothing. (and `yas-expand` returns nil)
- A Lisp form (apply command . args) means interactively call command, if args is non-nil, call command non-interactively with args as arguments.

### `yas-wrap-around-region`

If non-nil, snippet expansion wraps around selected region.

The wrapping occurs just before the snippet's exit marker. This can be overridden on a per-snippet basis.

### `yas-prompt-functions`

Functions to prompt for keys, templates, etc interactively.

These functions are called with the following arguments:

- prompt: A string to prompt the user
- choices: a list of strings or objects.
- optional display-fn : A function that, when applied to each of

the objects in choices will return a string.

The return value of any function you put here should be one of the objects in choices, properly formatted with display-fn (if that is passed).

- To signal that your particular style of prompting is

unavailable at the moment, you can also have the function return nil.

- To signal that the user quit the prompting process, you can

signal `quit` with

(signal 'quit "user quit!").

### `yas-visit-from-menu`

### `yas-triggers-in-field`

If non-nil, allow stacked expansions (snippets inside snippets).

Otherwise `yas-next-field-or-maybe-expand` just moves on to the next field

### `yas-trigger-symbol`

The text that will be used in menu to represent the trigger.

### `yas-use-menu`

### `yas-indent-line`

Controls indenting applied to a recent snippet expansion.

The following values are possible:

- `fixed` Indent the snippet to the current column;
- `auto` Indent each line of the snippet with `indent-according-to-mode`

Every other value means don't apply any snippet-side indentation after expansion (the manual per-line "$>" indentation still applies).

### `yas-expand-only-for-last-commands`

List of `last-command` values to restrict tab-triggering to, or nil.

Leave this set at nil (the default) to be able to trigger an expansion simply by placing the cursor after a valid tab trigger, using whichever commands.

Optionally, set this to something like '(self-insert-command) if you to wish restrict expansion to only happen when the last letter of the snippet tab trigger was typed immediately before the trigger key itself.

### `yas-snippet-dirs` ()

Return variable `yas-snippet-dirs` as list of strings.

### `yas-good-grace`

If non-nil, don't raise errors in inline elisp evaluation.

An error string "[yas] error" is returned instead.

## Useful functions

### `yas-default-from-field` (`number`)

warning: no doc for symbol `yas-default-from-field`

### `yas-completing-prompt` (`prompt` `choices` &optional `display-fn` `completion-fn`)

warning: no doc for symbol `yas-completing-prompt`

### `yas-selected-text` ()

Return `yas-selected-text` if that exists and is non-empty, else nil.

### `yas-hippie-try-expand` (`first-time?`)

Integrate with hippie expand.

Just put this function in `hippie-expand-try-functions-list`.

### `yas-global-mode-cmhh` ()

warning: no doc for symbol `yas-global-mode-cmhh`

### `yas-throw` (`text`)

Throw a yas–exception with `text` as the reason.

### `yas-inside-string` ()

Return non-nil if the point is inside a string according to font-lock.

### `yas-x-prompt` (`prompt` `choices` &optional `display-fn`)

Display choices in a x-window prompt.

### `yas-shortest-key-until-whitespace` (`_start-point`)

Like `yas-longest-key-from-whitespace` but take the shortest key.

### `yas-longest-key-from-whitespace` (`start-point`)

As `yas-key-syntaxes` element, look for longest key between point and whitespace.

A newline will be considered whitespace even if the mode syntax marks it as something else (typically comment ender).

### `yas-text` ()

Return `yas-text` if that exists and is non-empty, else nil.

### `yas-ido-prompt` (`prompt` `choices` &optional `display-fn`)

warning: no doc for symbol `yas-ido-prompt`

### `yas-try-key-from-whitespace` (`_start-point`)

As `yas-key-syntaxes` element, look for whitespace delimited key.

A newline will be considered whitespace even if the mode syntax marks it as something else (typically comment ender).

### `yas-dropdown-prompt` (`_prompt` `choices` &optional `display-fn`)

warning: no doc for symbol `yas-dropdown-prompt`

### `yas-define-snippets` (`mode` `snippets`)

Define `snippets` for `mode`.

`snippets` is a list of snippet definitions, each taking the following form

(key template name condition group expand-env file keybinding uuid)

Within these, only key and template are actually mandatory.

template might be a Lisp form or a string, depending on whether this is a snippet or a snippet-command.

condition, expand-env and keybinding are Lisp forms, they have been `yas--read-lisp`-ed and will eventually be `yas--eval-lisp`-ed.

The remaining elements are strings.

file is probably of very little use if you're programatically defining snippets.

uuid is the snippet's "unique-id". Loading a second snippet file with the same uuid would replace the previous snippet.

You can use `yas--parse-template` to return such lists based on the current buffers contents.

### `yas-global-mode-enable-in-buffers` ()

warning: no doc for symbol `yas-global-mode-enable-in-buffers`

### `yas-no-prompt` (`_prompt` `choices` &optional `_display-fn`)

warning: no doc for symbol `yas-no-prompt`

### `yas-active-keys` ()

Return all active trigger keys for current buffer and point.

### `yas-define-condition-cache` (`func` `doc` &rest `body`)

Define a function `func` with doc `doc` and body `body`. `body` is executed at most once every snippet expansion attempt, to check expansion conditions.

It doesn't make any sense to call `func` programatically.

### `yas-global-mode-check-buffers` ()

warning: no doc for symbol `yas-global-mode-check-buffers`

### `yas-define-menu` (`mode` `menu` &optional `omit-items`)

### `yas-field-value` (`number`)

Get the string for field with `number`.

Use this in primary and mirror transformations to tget.

### `yas-verify-value` (`possibilities`)

Verify that the current field value is in `possibilities`.

Otherwise throw exception.

### `yas-key-to-value` (`alist`)

warning: no doc for symbol `yas-key-to-value`

### `yas-choose-value` (&rest `possibilities`)

Prompt for a string in `possibilities` and return it.

The last element of `possibilities` may be a list of strings.

### `yas-substr` (`str` `pattern` &optional `subexp`)

Search `pattern` in `str` and return `subexp`th match.

If found, the content of subexp group `subexp` (default 0) is returned, or else the original `str` will be returned.

### `yas-unimplemented` (&optional `missing-feature`)

warning: no doc for symbol `yas-unimplemented`

### `yas-expand-snippet` (`content` &optional `start` `end` `expand-env`)

Expand snippet `content` at current point.

Text between `start` and `end` will be deleted before inserting template. `expand-env` is are let-style variable to value bindings considered when expanding the snippet.

### `yas-minor-mode-set-explicitly` ()

warning: no doc for symbol `yas-minor-mode-set-explicitly`

## Useful variables

### `yas-global-mode-buffers`

warning: no doc for symbol `yas-global-mode-buffers`

### `yas-after-reload-hook`

Hooks run after `yas-reload-all`.

### `yas-snippet-beg`

Beginning position of the last snippet committed.

### `yas-after-exit-snippet-hook`

Hooks to run after a snippet exited.

The hooks will be run in an environment where some variables bound to proper values:

`yas-snippet-beg` : The beginning of the region of the snippet.

`yas-snippet-end` : Similar to beg.

Attention: These hooks are not run when exiting nested/stacked snippet expansion!

### `yas-global-mode-hook`

Hook run after entering or leaving `yas-global-mode`. No problems result if this variable is not bound. `add-hook` automatically binds it. (This is true for all hook variables.)

### `yas-dont-activate`

If non-nil don't let `yas-global-mode` affect some buffers.

If a function of zero arguments, then its result is used.

If a list of functions, then all functions must return nil to activate yas for this buffer.

In Emacsen <= 23, this variable is buffer-local. Because `yas-minor-mode-on` is called by `yas-global-mode` after executing the buffer's major mode hook, setting this variable there is an effective way to define exceptions to the "global" activation behaviour.

In Emacsen > 23, only the global value is used. To define per-mode exceptions to the "global" activation behaviour, call `yas-minor-mode` with a negative argument directily in the major mode's hook.

### `yas-minor-mode-map`

The keymap used when `yas-minor-mode` is active.

### `yas-moving-away-p`

Non-nil if user is about to exit field.

### `yas-buffer-local-condition`

Snippet expanding condition.

This variable is a Lisp form which is evaluated every time a snippet expansion is attempted:

- If it evaluates to nil, no snippets can be expanded.
- If it evaluates to the a cons (require-snippet-condition . requirement)
  - Snippets bearing no "# condition:" directive are not considered
  - Snippets bearing conditions that evaluate to nil (or produce an error) won't be considered.
  - If the snippet has a condition that evaluates to non-nil result:
    - If requirement is t, the snippet is considered
    - If requirement is `eq` result, the snippet is considered
    - Otherwise, the snippet is not considered.
- If it evaluates to the symbol 'always, all snippets are considered for expansion, regardless of any conditions.
- If it evaluates to t or some other non-nil value
  - Snippet bearing no conditions, or conditions that evaluate to non-nil, are considered for expansion.
  - Otherwise, the snippet is not considered.

Here's an example preventing snippets from being expanded from inside comments, in `python-mode` only, with the exception of snippets returning the symbol 'force-in-comment in their conditions.

(add-hook 'python-mode-hook '(lambda () (setq yas-buffer-local-condition '(if (python-in-string/comment) '(require-snippet-condition . force-in-comment) t))))

The default value is similar, it filters out potential snippet expansions inside comments and string literals, unless the snippet itself contains a condition that returns the symbol `force-in-comment`.

### `yas-modified-p`

Non-nil if field has been modified by user or transformation.

### `yas-before-expand-snippet-hook`

Hooks to run just before expanding a snippet.

### `yas-keymap`

The active keymap while a snippet expansion is in progress.

### `yas-key-syntaxes`

Syntaxes and functions to help look for trigger keys before point.

Each element in this list specifies how to skip buffer positions backwards and look for the start of a trigger key.

Each element can be either a string or a function receiving the original point as an argument. A string element is simply passed to `skip-syntax-backward` whereas a function element is called with no arguments and should also place point before the original position.

The string between the resulting buffer position and the original point is matched against the trigger keys in the active snippet tables.

If no expandable snippets are found, the next element is the list is tried, unless a function element returned the symbol `again`, in which case it is called again from the previous position and may once more reposition point.

For example, if `yas-key-syntaxes`' value is '("w" "w_"), trigger keys composed exclusively of "word"-syntax characters are looked for first. Failing that, longer keys composed of "word" or "symbol" syntax are looked for. Therefore, triggering after

foo-bar

will, according to the "w" element first try "barbaz". If that isn't a trigger key, "foo-barbaz" is tried, respecting the second "w_" element. Notice that even if "baz" is a trigger key for an active snippet, it won't be expanded, unless a function is added to `yas-key-syntaxes` that eventually places point between "bar" and "baz".

See also Info node `(elisp) Syntax Descriptors'.

### `yas-snippet-end`

End position of the last snippet committed.

### `yas-minor-mode-hook`

Hook run after entering or leaving `yas-minor-mode`. No problems result if this variable is not bound. `add-hook` automatically binds it. (This is true for all hook variables.)

### `yas-verbosity`

Log level for `yas--message` 4 means trace most anything, 0 means nothing.

### `yas-minor-mode-major-mode`

warning: no doc for symbol `yas-minor-mode-major-mode`

### `yas-installed-snippets-dir`

warning: no doc for symbol `yas-installed-snippets-dir`

Generated by Emacs 24.5.1 (Org mode 8.2.10) on from 0.9.0-beta

Validate