yasnippet/README.mdown

[![Build Status](https://travis-ci.org/capitaomorte/yasnippet.png)](https://travis-ci.org/capitaomorte/yasnippet)

# 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][textmate-snippets] syntax, you can
even [import](#import) most TextMate templates to
YASnippet. Watch [a demo on YouTube][youtube-demo] or download a
[higher resolution version][high-res-demo].

[textmate-snippets]: http://manual.macromates.com/en/snippets
[youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
[high-res-demo]: http://yasnippet.googlecode.com/files/yas_demo.avi

# 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][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?

<a name="import"></a>

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][yasnippet-snippets] the snippet
    collection of [AndreaCrotti](https://github.com/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][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][yasmate]), 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.

# Manual, issues etc

Please refer to the comprehensive [documentation][docs] for full
customization and support.  If you find a bug in the code or in the
documentation, please report it on [the GitHub issue tracker][issues].

## Important note regarding bug reporting

Your bug reports are very valuable.

The most important thing when reporting bugs is making sure that the
developer has a way to reproduce the problem exactly like it happened
to you.

To do this, he needs to rule out interference from external factors
like other Emacs extensions or other Lisp-side code.

Here's an example that "sandboxes" an emacs just for reproducing the
bug.

```
$ emacs --version
Emacs 24.3
$ cd /tmp/
$ git clone https://github.com/capitaomorte/yasnippet.git yasnippet-bug
$ cd yasnippet-bug
$ git log -1 --oneline
6053db0 Closes #527: Unbreak case where yas-fallback-behaviour is a list
$ HOME=$PWD emacs -L  # This "sandboxes" your emacs, melpa configuration, etc

(require 'yasnippet)
(yas-global-mode 1)

When I open a foo-mode file I can't expand foo-mode snippets! 
OR
I can't get yasnippet to load because frankinbogen!
```

Here's a
[another example](https://github.com/capitaomorte/yasnippet/issues/318)
of a bug report. It has everything needed for a sucessfull analysis
and speedy resolution.

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, unless we ask for it.


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

Finally, thank you very much for using YASnippet!

[docs]: http://capitaomorte.github.com/yasnippet/
[issues]: https://github.com/capitaomorte/yasnippet/issues
[googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
[forum]: http://groups.google.com/group/smart-snippet
[melpa]: http://melpa.milkbox.net/
[yasmate]: http://github.com/capitaomorte/yasmate
[yasnippet-snippets]: http://github.com/AndreaCrotti/yasnippet-snippets