kidd / yasnippet

A template system for Emacs

Intro

YASnippet is a template system for Emacs. It allows you to type an abbreviation and automatically expand it into function templates. Bundled language templates include: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax is inspired from TextMate's syntax, you can even import most TextMate templates to YASnippet. Watch a demo on YouTube or download a higher resolution version.

Installation

Install the most recent version

Clone this repository somewhere

$ cd ~/.emacs.d/plugins
$ git clone --recursive https://github.com/capitaomorte/yasnippet

Add the following in your .emacs file:

(add-to-list 'load-path
              "~/.emacs.d/plugins/yasnippet")
(require 'yasnippet)
(yas-global-mode 1)

Add your own snippets to ~/.emacs.d/snippets by placing files there or invoking yas-new-snippet.

Install with package-install

In a recent emacs M-x list-packages is the recommended way to list and install packages. MELPA keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing.

Install with el-get

El-get is a nice way to get the most recent version, too. See https://github.com/dimitri/el-get for instructions. Be sure to install the "master" branch since the 3.x series still use the old googlecode code, base. Consider using this "local" recipe.

(push '(:name yasnippet
              :website "https://github.com/capitaomorte/yasnippet.git"
              :description "YASnippet is a template system for Emacs."
              :type github
              :pkgname "capitaomorte/yasnippet"
              :features "yasnippet"
              :compile "yasnippet.el")
      el-get-sources)

Use yas-minor-mode on a per-buffer basis

To use YASnippet as a non-global minor mode, replace (yas-global-mode 1) with (yas-reload-all) to load the snippet tables. Then add a call to (yas-minor-mode) to the major-modes where you to enable YASnippet.

(add-hook 'prog-mode-hook
          '(lambda ()
             (yas-minor-mode)))

Where are the snippets?

Yasnippet no longer bundles snippets directly, but it's very easy to get some!

If you git-cloned yasnippet with the --recursive option you'll also download "git submodules" and find two subdirs under the main tree.

1. snippets/

   Points to yasnippet-snippets the snippet collection of AndreaCrotti.

   The default configuraiton already points to this dir, so to use them, just make sure the submodule really was downloaded (i.e. there are some files under snippets/)

2. yasmate/

   Points to a github repo of the yasmate tool, which is dedicated to converting textmate bundles into yasnippet snippets.

   To use these snippets you have to run the tool first, so see its doc), and then point the yas-snippet-dirs variable to the .../yasmate/snippets subdir.

   If you have a working ruby environment, you can probably get lucky directly with rake convert-bundles.

Naturally, you can point yas-snippet-dirs to good snippet collections out there. If you have created snippets for a mode, or multiple modes, consider creating a repository to host them, then tell users that it should be added like this to yas-snippet-dirs:

(setq yas-snippet-dirs
      '("~/.emacs.d/snippets"                 ;; personal snippets
        "/path/to/some/collection/"           ;; foo-mode and bar-mode snippet collection
        "/path/to/yasnippet/yasmate/snippets" ;; the yasmate collection
        "/path/to/yasnippet/snippets"         ;; the default collection
        ))

(yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.

Documentation, issues, etc

Please refer to the comprehensive (albeit slightly outdated) documentation for full customization and support. If you find a bug, please report it on the GitHub issue tracker. (please do not submit new issues to the old googlecode tracker)

Important note regarding bug reporting

If you think have found a bug, please report it clearly. Yasnippet does have (lots of) bugs and your reports are very valuable. Here's a great example of a bug report. It has everything needed for a sucessfull analysis and speedy resolution:

Before reporting try to reproduce the bug without your usual .emacs (or whatever startup file you use). Do so either by starting emacs from the command line with the -Q switch, or by temporarily moving away your .emacs and creating a new smaller one just for reproducing the bug. Paste that file in your bug report. Paste any sequence of relevant shell commands before you launch Emacs.

Then, describe steps taken to reproduce from an end-user perspective. Try to be as unambiguous as possible.

Also, don't forget to state the Emacs version (use M-x emacs-version) and the yasnippet version you are using (if using the latest from github, do git log -1 in the dir).

Any more info is welcome, but don't just paste a backtrace or an error message string you got. I'm not saying your analysis might not be useful but following the instructions above immediately gives me a clear picture of what is happening.

There is also a YASnippet google group. I will keep the group open for reference and for discussion among users, unfortunately I can't guarantee a timely response, so maybe creating a github issue clearly marking your intent (user support/bug/feature request).

Finally, thank you very much for using YASnippet!