code.delx.au - gnu-emacs-elpa/blob - README.mdown

   1 # Intro
   2
   3 **YASnippet** is a template system for Emacs. It allows you to type an
   4 abbreviation and automatically expand it into function
   5 templates. Bundled language templates includes: C, C++, C#, Perl,
   6 Python, Ruby,
   7
   8 SQL, LaTeX, HTML, CSS and more. The snippet syntax is inspired from
   9 [TextMate's][textmate-snippets] syntax, you can even
  10 [import][import-docs] most TextMate templates to YASnippet. Watch
  11 [a demo on YouTube][youtube-demo] or download a
  12 [higher resolution version][high-res-demo]
  13
  14 [textmate-snippets]: http://manual.macromates.com/en/snippets
  15 [import-docs]: http://yasnippet.googlecode.com/svn/trunk/doc/snippet-development.html#importing-textmate-snippets
  16 [youtube-demo]: http://www.youtube.com/watch?v=ZCGmZK4V7Sg
  17 [high-res-demo]: http://yasnippet.googlecode.com/files/yas_demo.avi
  18
  19 # Installation
  20
  21 ## Install the most recent version
  22
  23 Clone this repository somewhere
  24
  25     $ cd ~/.emacs.d/plugins
  26     $ git clone https://github.com/capitaomorte/yasnippet
  27
  28 Add the following in your `.emacs` file:
  29
  30     (add-to-list 'load-path
  31                   "~/.emacs.d/plugins/yasnippet")
  32     (require 'yasnippet)
  33     (yas-global-mode 1)
  34
  35 Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`.
  36
  37 ## Install with `package-install`
  38
  39 In a recent emacs `M-x list-packages` is the recommended way to list and install packages.
  40 [MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing.
  41
  42 ## Install with el-get
  43
  44 El-get is a nice way to get the most recent version, too. See
  45 https://github.com/dimitri/el-get for instructions. Be sure to install the
  46 "master" branch since the 3.x series still use the old googlecode code, base.
  47 Consider using this "local" recipe.
  48
  49     (push '(:name yasnippet
  50                   :website "https://github.com/capitaomorte/yasnippet.git"
  51                   :description "YASnippet is a template system for Emacs."
  52                   :type github
  53                   :pkgname "capitaomorte/yasnippet"
  54                   :features "yasnippet"
  55                   :compile "yasnippet.el")
  56           el-get-sources)
  57
  58 ## Use `yas-minor-mode` on a per-buffer basis
  59
  60 To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with
  61 `(yas-reload-all)` to load the snippet tables. Then add a call to
  62 `(yas-minor-mode)` to the major-modes where you to enable YASnippet.
  63
  64     (add-hook 'prog-mode-hook
  65               '(lambda ()
  66                  (yas-minor-mode)))
  67
  68 # (NOT) Contributing snippets
  69
  70 Please **do not** open pull requests or ask me to add snippets to
  71 YASnippet.
  72
  73 The bundled collection under `/snippets` is considered frozen: **I
  74 will not add more snippets to it**.
  75
  76 You can point `yas-snippet-dirs` to good snippet collections out
  77 there. If you have created snippets for a mode, or multiple modes,
  78 consider creating a repository to host them, then tell users that it
  79 should be added like this to `yas-snippet-dirs`:
  80
  81     (setq yas-snippet-dirs
  82           '("~/.emacs.d/snippets"            ;; personal snippets
  83             "/path/to/some/collection/"      ;; just some foo-mode snippets
  84             "/path/to/some/othercollection/" ;; some more foo-mode and a complete baz-mode
  85             "/path/to/yasnippet/snippets"    ;; the default collection
  86             ))
  87
  88     (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already.
  89
  90 # Importing TextMate snippets
  91
  92 There is a tool `extras/textmate-import.rb` than can import many
  93 actual TextMate snippets. These can be quite complex so the
  94 `extras/imported/*-mode/.yas-setup.el` files help it with the more
  95 difficult importation.
  96
  97 I'm focusing on developing `textmate-import.rb` tool and some
  98 `yas-setup.el` files. In the future `/snippets` snippets will be
  99 deprecated and might be replaced with `extras/imported`.
 100
 101 ## Example importation of rails snippets
 102
 103 To start using [drnic's](https://github.com/drnic) snippets for rails
 104 development, follow this example. It will convert `ruby`, `rails` and
 105 `html` bundles from github repositories. The importation will be
 106 guided by the `.yas-setup.el` files.
 107
 108 After cloning this repository to `~/.emacs.d/plugins/yasnippet`
 109
 110     cd ~/.emacs.d/plugins/yasnippet
 111     git submodule init
 112     git submodule update
 113     gem install plist trollop
 114     rake convert_bundles             # will convert ruby, rails and html bundles
 115
 116 Then, in your `.emacs` file
 117
 118     (add-to-list 'load-path
 119                   "~/.emacs.d/plugins/yasnippet")
 120     (require 'yasnippet)
 121     (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported"))
 122     (yas-global-mode 1)
 123
 124 Open some rails file (model, app, etc) and start using the textmate
 125 snippets.  Note that in the example above we have abandoned the
 126 default snippet collection on `~/.emacs.d/plugins/yasnippet/snippets`
 127
 128 # Documentation, issues, etc
 129
 130 Please refer to the comprehensive (albeit slightly outdated)
 131 [documentation][docs] for full customization
 132 and support.  If you find a bug, please report it on
 133 [the GitHub issue tracker][issues].  (please **do not** submit new issues to the old
 134 [googlecode tracker][googlecode tracker])
 135
 136 If you run into problems using YASnippet, or have snippets to contribute, post
 137 to the [YASnippet google group][forum]. Thank you very much for using YASnippet!
 138
 139 [docs]: http://capitaomorte.github.com/yasnippet/
 140 [issues]: https://github.com/capitaomorte/yasnippet/issues
 141 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 142 [forum]: http://groups.google.com/group/smart-snippet
 143 [melpa]: http://melpa.milkbox.net/