Reference

Table of Contents

Interactive functions

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

Load and save the snippet, then quit-window if saved. Loading is performed by yas-load-snippet-buffer. 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-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.

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-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-recompile-all ()

Compile every dir in yas-snippet-dirs.

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-deactivate-extra-mode (mode)

Deactivates the snippets for the given mode in the buffer.

yas-prev-field ()

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

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

Parse and load current buffer's snippet definition into table. table is a symbol name passed to yas--table-get-create. When called interactively, prompt for the table name. Return the yas--template object created

yas-exit-all-snippets ()

Exit all snippets.

yas-next-field (&optional arg)

Navigate to the argth next field.

If there's none, exit the snippet.

yas-abort-snippet (&optional snippet)

warning: no doc for symbol yas-abort-snippet

yas-describe-tables (&optional with-nonactive)

Display snippets for each table.

yas-expand-from-keymap ()

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

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-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-next-field-or-maybe-expand ()

Try to expand a snippet at a key before point.

Otherwise delegate to yas-next-field.

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

key             binding
---             -------

C-c		Prefix Command

C-c &		Prefix Command

C-c & C-n	yas-new-snippet
C-c & C-s	yas-insert-snippet
C-c & C-v	yas-visit-snippet-file

yas-direct-keymaps-reload ()

Force reload the direct keybinding for active snippet tables.

yas-exit-snippet (snippet)

Goto exit-marker of snippet.

yas-about ()

warning: no doc for symbol yas-about

yas-minor-mode-on ()

Turn on YASnippet minor mode.

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

yas-skip-and-clear-field (&optional field)

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

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-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-describe-table-by-namehash ()

Display snippet tables by namehash.

yas-tryout-snippet (&optional debug)

Test current buffer's snippet template in other buffer. debug is for debugging the YASnippet engine itself.

Customization variables

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-wrap-around-region

What to insert for snippet's $0 field.

If set to a character, insert contents of corresponding register. If non-nil insert region contents. This can be overridden on a per-snippet basis. A value of cua is considered equivalent to `?0' for backwards compatibility.

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-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-use-menu

Display a YASnippet menu in the menu bar.

When non-nil, submenus for each snippet table will be listed under the menu "Yasnippet".

  • If set to abbreviate, only the current major-mode

menu and the modes set in yas--extra-modes are listed.

  • If set to full, every submenu is listed
  • If set to nil, hide the menu.

Any other non-nil value, every submenu is listed.

yas-snippet-dirs ()

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

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-syntax-comment-or-string-p) '(require-snippet-condition . force-in-comment) t))))

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-overlay-priority

Priority to use for yasnippets overlays. This is useful to control whether snippet navigation bindings override bindings from other packages (e.g., company-mode).

yas-snippet-revival

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

yas-good-grace

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

This affects both the inline elisp in snippets and the hook variables such as yas-after-exit-snippet-hook.

If this variable's value is inline, an error string "[yas] error" is returned instead of raising the error. If this variable's value is hooks, a message is output to according to yas-verbosity-level. If this variable's value is t, both are active.

yas-visit-from-menu

If non-nil visit snippets's files from menu, instead of expanding them.

This can only work when snippets are loaded from files.

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-trigger-symbol

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

yas-also-indent-empty-lines

Non-nil means also indent empty lines according to mode.

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-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-alias-to-yas/prefix-p

If non-nil make aliases for the old style yas/ prefixed symbols. It must be set to nil before loading yasnippet to take effect.

Useful functions

yas-expand-snippet (snippet &optional start end expand-env)

Expand snippet at current point.

Text between start and end will be deleted before inserting template. expand-env is a list of (sym value) let-style dynamic bindings considered when expanding the snippet. If omitted, use snippet's expand-env field.

snippet may be a snippet structure (e.g., as returned by yas-lookup-snippet), or just a snippet body (which is a string for normal snippets, and a list for command snippets).

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 load-file keybinding uuid save-file)

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-for-string-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-completing-prompt (prompt choices &optional display-fn completion-fn)

warning: no doc for symbol yas-completing-prompt

yas-inside-string ()

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

yas-lookup-snippet (name &optional mode noerror)

Get the snippet named name in mode's tables.

mode defaults to the current buffer's major-mode. If noerror is non-nil, then don't signal an error if there isn't any snippet called name.

Honours yas-buffer-local-condition.

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

Display choices in a x-window prompt.

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

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

yas-selected-text ()

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

yas-field-value (number)

Get the string for field with number.

Use this in primary and mirror transformations to get the text of other fields.

yas-global-mode-cmhh ()

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

yas-escape-text (text)

Escape text for snippet.

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

warning: no doc for symbol yas-dropdown-prompt

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

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

yas-substr (str pattern &optional subexp)

Search pattern in str and return subexpth match.

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

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

warning: no doc for symbol yas-ido-prompt

yas-maybe-ido-prompt (prompt choices &optional display-fn)

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

yas-snippet-mode-buffer-p ()

Return non-nil if current buffer should be in snippet-mode. Meaning it's visiting a file under one of the mode directories in yas-snippet-dirs.

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

warning: no doc for symbol yas-no-prompt

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-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-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-global-mode-check-buffers ()

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

yas-minor-mode-set-explicitly ()

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

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

Define a snippet menu for mode according to menu, omitting omit-items.

menu is a list, its elements can be:

  • (yas-item uuid) : Creates an entry the snippet identified with uuid. The menu entry for a snippet thus identified is permanent, i.e. it will never move (be reordered) in the menu.
  • (yas-separator) : Creates a separator
  • (yas-submenu name submenu) : Creates a submenu with name, submenu has the same form as menu. name is also added to the list of groups of the snippets defined thereafter.

omit-items is a list of snippet uuids that will always be omitted from mode's menu, even if they're manually loaded.

yas-current-field ()

Return the currently active field.

yas-unimplemented (&optional missing-feature)

warning: no doc for symbol yas-unimplemented

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-active-keys ()

Return all active trigger keys for current buffer and point.

yas-text ()

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

yas-next-field-will-exit-p (&optional arg)

Return non-nil if (yas-next-field arg) would exit the current snippet.

yas-active-snippets (&optional beg end)

Return a sorted list of active snippets. The most recently-inserted snippets are returned first.

Only snippets overlapping the region begend are returned. Overlapping has the same meaning as described in overlays-in. If end is omitted, it defaults to (1+ beg). If beg is omitted, it defaults to point. A non-nil, non-buffer position beg is equivalent to a range covering the whole buffer.

yas-verify-value (possibilities)

Verify that the current field value is in possibilities. Otherwise signal yas-exception.

yas-default-from-field (number)

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

yas-key-to-value (alist)

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

yas-throw (text)

Signal yas-exception with text as the reason.

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

Integrate with hippie expand.

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

yas-maybe-load-snippet-buffer ()

Added to after-save-hook in snippet-mode.

Useful variables

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 has the value ("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-modified-p

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

yas-dont-activate-functions

Special hook to control which buffers yas-global-mode affects. Functions are called with no argument, and should return non-nil to prevent yas-global-mode from enabling yasnippet in this buffer.

In Emacsen < 24, 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 >= 24, 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-before-expand-snippet-hook

Hooks to run just before expanding a snippet.

yas-maybe-skip-and-clear-field

A conditional key definition. This can be used as a key definition in keymaps to bind a key to yas-skip-and-clear-field only when at the beginning of an unmodified snippey field.

yas-keymap

The active keymap while a snippet expansion is in progress.

yas-verbosity

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

yas-minor-mode-hook

Hook run when yas-minor-mode is turned on.

yas-minor-mode-major-mode

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

yas-not-string-or-comment-condition

Disables snippet expansion in strings and comments. To use, set yas-buffer-local-condition to this value.

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-maybe-expand

A conditional key definition. This can be used as a key definition in keymaps to bind a key to yas-expand only when there is a snippet available to be expanded.

yas-after-reload-hook

Hooks run after yas-reload-all.

yas-new-snippet-buffer-name

warning: no doc for symbol yas-new-snippet-buffer-name

yas-snippet-end

End position of the last snippet committed.

yas-minor-mode-map

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

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-snippet-beg

Beginning position of the last snippet committed.

yas-moving-away-p

Non-nil if user is about to exit field.

yas-maybe-expand-from-keymap

warning: no doc for symbol yas-maybe-expand-from-keymap

yas-global-mode-buffers

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


Generated by Emacs 26.1 (Org mode 9.1.9) from 0.13.0 (2018-05-13 16:12:51)

Validate