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 el-get
  38
  39 El-get is a nice way to get the most recent version, too. See
  40 https://github.com/dimitri/el-get for instructions. Be sure to install the
  41 "master" branch since the 3.x series still use the old googlecode code, base.
  42 Consider using this "local" recipe.
  43
  44     (push '(:name yasnippet
  45                   :website "https://github.com/capitaomorte/yasnippet.git"
  46                   :description "YASnippet is a template system for Emacs."
  47                   :type github
  48                   :pkgname "capitaomorte/yasnippet"
  49                   :features "yasnippet"
  50                   :compile "yasnippet.el"
  51                   :submodule nil)
  52           el-get-sources)
  53
  54 ## Install with MELPA
  55
  56 If you're using the latest emacs, with `package.el`, a very recent yasnippet is
  57 also available on http://melpa.milkbox.net/.
  58
  59 ## Use `yas/minor-mode` on a per-buffer basis
  60
  61 To use yasnippet as a non-global minor mode, replace `(yas/global-mode 1)` with
  62 `(yas/reload-all)` to load the snippet tables. Then add a call to
  63 `(yas/minor-mode)` to the major-modes where you to enable yasnippet.
  64
  65     (add-hook 'prog-mode-hook
  66               '(lambda ()
  67                  (yas/minor-mode)))
  68
  69 # Contributing snippets
  70
  71 Please **do not** ask me to add snippets to the default collection under
  72 `/snippets`. This is considered frozen and by customizing
  73 `yas/snippet-dirs` you can point yasnippet to good snippet collections
  74 out there.
  75
  76 There is a tool `extras/textmate-import.rb` than can import many
  77 actual Textmate snippets and there are
  78 `extras/imported/*-mode/.yas-setup.el` files that can help it with the
  79 more difficult importation.
  80
  81 I'm focusing on developping `textmate-import.rb` tool and the
  82 `yas-setup.el` files. In the future `/snippets` snippets will be
  83 deprecated and replaced with `extras/imported`.
  84
  85 Follow through the following example to start using these snippets for
  86 rails development. It will convert `ruby`, `rails` and `html` bundles
  87 from drnic's github repositories based on corresponding
  88 `.yas-setup.el` files.
  89
  90 ## Using imported textmate snippets (rails example)
  91
  92 After cloning this repository to `~/.emacs.d/plugins/yasnippet`
  93
  94     cd ~/.emacs.d/plugins/yasnippet
  95     git submodule init
  96     git submodule update
  97     gem install plist trollop
  98     rake convert_bundles             # will convert ruby, rails and html bundles from drnic
  99
 100 Then, in your .emacs file
 101
 102     (add-to-list 'load-path
 103                   "~/.emacs.d/plugins/yasnippet")
 104     (require 'yasnippet)
 105     (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported"))
 106     (yas/global-mode 1)
 107
 108 Open some rails file (model, app, etc) and start using the textmate snippets.
 109 Note thqt in the example above we abandon the default snippet collection on
 110 `~/.emacs.d/plugins/yasnippet/snippets`
 111
 112 # Documentation, issues, etc
 113
 114 Please refer to the comprehensive (albeit slightly outdated)
 115 [documentation][docs] for full customization
 116 and support.  If you find a bug, please report it on
 117 [the GitHub issue tracker][issues].  (please **do not** submit new issues to the old
 118 [googlecode tracker][googlecode tracker])
 119
 120 If you run into problems using yasnippet, or have snippets to contribute, post
 121 to the [yasnippet google group][forum]. Thank you very much for using yasnippet!
 122
 123 [docs]: http://capitaomorte.github.com/yasnippet/
 124 [issues]: https://github.com/capitaomorte/yasnippet/issues
 125 [googlecode tracker]: http://code.google.com/p/yasnippet/issues/list
 126 [forum]: http://groups.google.com/group/smart-snippet