yasnippet/doc/manual.org

#+TITLE: Yet another snippet extension
#+OPTIONS: toc:1
#+STARTUP: showall

#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheets/styles.css" />

# External links
#
#+LINK: smart-snippet http://code.google.com/p/smart-snippet
#+LINK: pluskid       http://pluskid.lifegoo.org

#+LINK: screencast         http://www.youtube.com/watch?v=ZCGmZK4V7Sg
#+LINK: docs               http://capitaomorte.github.com/yasnippet
#+LINK: issues             https://github.com/capitaomorte/yasnippet/issues
#+LINK: googlecode-tracker http://code.google.com/p/yasnippet/issues/list
#+LINK: forum              http://groups.google.com/group/smart-snippet


* Quick start

  *YASnippet* is a template system for Emacs. It allows you to type an
  abbreviation and automatically expand it into function templates. Bundled
  language templates includes: 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-textmate][import most TextMate snippets]]

  YASnippet is an original creation of [[pluskid]] who also wrote its predecessor
  [[smart-snippet]].

** Watch a demo

   [[youtube]]

** Installation

   Clone this repository somewhere

   #+begin_example
   $ cd ~/.emacs.d/plugins
   $ git clone https://github.com/capitaomorte/yasnippet
   #+end_example

   Add the following in your =.emacs= file:

   #+begin_src emacs-lisp :exports code
   (add-to-list 'load-path
                 "~/.emacs.d/plugins/yasnippet")
   (require 'yasnippet)
   (yas/global-mode 1)
   #+end_src

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

** Import textmate snippets (rails example)
   :PROPERTIES:
   :CUSTOM_ID: import-textmate
   :END:

   YASnippet lets you use TextMate bundles directly:

   #+begin_example
   $ cd ~/.emacs.d/plugins
   $ git clone https://github.com/capitaomorte/yasnippet
   $ cd yasnippet
   $ git submodule init
   $ git submodule update
   $ gem install plist trollop
   $ rake convert_bundles             # will convert ruby, rails and html bundles from drnic
   #+end_example

   Then, in your =.emacs= file

   #+begin_example
   (add-to-list 'load-path
                 "~/.emacs.d/plugins/yasnippet")
   (require 'yasnippet)
   (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))
   (yas/global-mode 1)
   #+end_example

   Open some rails file (model, app, etc) and start using the textmate
   snippets. Consider that this is a work-in-progress and many snippets/commands
   might not work. Patches welcome!

** Contributing snippets

   Please *do not ask me* to add snippets to the default collection under
   =/snippets=. This collection is considered frozen. By customizing
   [[#yas-snippet-dirs][=yas-snippet-dirs=]] you can point yasnippet to good
   snippet collections out there.

   The =extras/textmate-import.rb= tool can import many actual Textmate
   snippets.  I'm focusing on developing it and the accompanying =yas-setup.el=
   files that guide it with more difficult importations. The idea is to deprecate
   =/snippets=  and replace it with =extras/imported=.

** Documentation, issues, etc

   Please refer to the comprehensive [[docs][documentation]] for full
   customization and support.  If you think you've found a bug, please report it
   on [[issues][the GitHub issue tracker]].  (please **do not** submit new
   issues to the old [[googlecode-tracker][googlecode tracker]])

   If you run into problems using YASnippet, or have snippets to contribute,
   post to the [[forum][yasnippet forum]]. Thank you very much for using
   YASnippet!

* Organizing snippets

** Basic structure

   Snippet collections can be stored in plain text files. They are arranged by
   sub-directories naming *snippet tables*. These mostly name Emacs major names.

   #+begin_example
   .
   |-- c-mode
   |   `-- printf
   |-- java-mode
   |   `-- println
   `-- text-mode
       |-- email
       `-- time
   #+end_example

   The collections are loaded into *snippet tables* which the triggering
   mechanism (see [[#expand-snippets][Expanding snippets]]) looks up and
   (hopefully) cause the right snippet to be expanded for you.

** Setting up =yas-snippet-dirs=

   The emacs variable [[#yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
   which collections to consider. It's used when you activate
   [[#yas-global-mode][=yas-global-mode=]] or call
   [[#yas-reload-all][=yas-reload-all=]] interactively.

   The default considers:

    - a personal collection that lives in =~/.emacs.d/snippets=
    - the bundled collection, taken as a relative path to =yasnippet.el= localtion

   When you come across other snippet collections, do the following to try them
   out:

   #+begin_src emacs-lisp :exports code
   ;; Develop in ~/emacs.d/mysnippets, but also
   ;; try out snippets in ~/Downloads/interesting-snippets
   (setq yas/snippet-dirs '("~/emacs.d/mysnippets"
                              "~/Downloads/interesting-snippets"))

   ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
   (setq yas/snippet-dirs (append yas/snippet-dirs
                                  '("~/Downloads/interesting-snippets")))
   #+end_src

   Collections appearing earlier in the list shadow snippets with same names
   appearing in collections later in the list. [[#yas-new-snippet][=yas-new-snippet=]] always stores
   snippets in the first collection.

** The =.yas.parents= file

   It's very useful to have certain modes share snippets between themselves. To do
   this, choose a mode subdirectory and place a =.yas-parents= containing a
   whitespace-separated list of other mode names. When you reload those modes
   become parents of the original mode.

   #+begin_example
   .
   |-- c-mode
   |   |-- .yas-parents    # contains "cc-mode text-mode"
   |   `-- printf
   |-- cc-mode
   |   |-- for
   |   `-- while
   |-- java-mode
   |   |-- .yas-parents    # contains "cc-mode text-mode"
   |   `-- println
   `-- text-mode
       |-- email
       `-- time
   #+end_example

** TODO The =.yas-make-groups= file

   If you place an empty plain text file =.yas-make-groups= inside one of the
   mode directories, the names of these sub-directories are considered groups of
   snippets and [[snippet-menu][the menu]] is organized much more cleanly:

   (TODO image)

   Another alternative way to achieve this is to place a =# group:= directive
   inside the snippet definition. See [[#writing-snippets][Writing Snippets]]

   #+begin_example
   $ tree ruby-mode/
   ruby-mode/
   |-- .yas-make-groups
   |-- collections
   |   |-- each
   |   `-- ...
   |-- control structure
   |   |-- forin
   |   `-- ...
   |-- definitions
   |   `-- ...
   `-- general
      `-- ...
   #+end_example

   Yet another way to create a nice snippet menu is to write into
   =.yas-make-groups= a menu definition. TODO

** TODO The =.yas-setup.el= file

*** TODO

** TODO The =.yas-compiled-snippet.el= file

*** TODO

** The =.yas-skip= file

* Expanding Snippets

   :PROPERTIES:
   :CUSTOM_ID: expand-snippets
   :END:

  This section describes how YASnippet chooses snippets for expansion at point.

  Maybe, you'll want some snippets to be expanded in a particular
  mode, or only under certain conditions, or be prompted using

** Triggering expansion

   To make a snippet expand after the cursor:

   * Type an the snippet's *trigger key* then press the key defined in
     [[#yas-trigger-key][=yas-trigger-key=]] (usually to "TAB").

   * Use the snippet's *keybinding*.

   * Call [[#yas-insert-snippet][=yas-insert-snippet=]] (use =M-x
     yas-insert-snippet== or its keybinding =C-c & C-s=).

   * By expanding directly from the "YASnippet" menu in the menu-bar

   * Using hippie-expand

   * Use m2m's excellent auto-complete

* Reference
#+BEGIN_SRC emacs-lisp :exports results :results value raw
(yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
                         `("Customization variables" . ,#'(lambda (sym)
                                                            (and (boundp sym)
                                                                 (get sym 'standard-value))))
                         `("Useful functions" . ,#'fboundp)
                         `("Useful variables" . ,#'boundp))
#+END_SRC
# Local Variables:
# mode: org
# fill-column: 80
# coding: utf-8
# End: