mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 21:13:04 +00:00
f6cace08f3
This is just the initial conversion with pandoc, they still need to be fixed up. Also define new org files as a project in yas-doc-helper.el.
286 lines
9.1 KiB
Org Mode
286 lines
9.1 KiB
Org Mode
#+TITLE: Yet another snippet extension
|
|
#+OPTIONS: toc:1
|
|
#+STARTUP: showall
|
|
|
|
* 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 [[http://pluskid.lifegoo.org][pluskid]] who also wrote its predecessor
|
|
[[http://code.google.com/p/smart-snippet][smart-snippet]].
|
|
|
|
** Watch a demo
|
|
|
|
On [[http://www.youtube.com/watch?v=ZCGmZK4V7Sg][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
|
|
|
|
The documentation has been split into separate parts:
|
|
|
|
1. [[file:snippet-organization.org][Organizing Snippets]]
|
|
#+BEGIN_QUOTE
|
|
Describes ways to organize your snippets in the hard disk.
|
|
#+END_QUOTE
|
|
|
|
2. [[file:snippet-expansion.org][Expanding Snippets]]
|
|
#+BEGIN_QUOTE
|
|
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 =ido=, etc...
|
|
#+END_QUOTE
|
|
|
|
3. [[file:snippet-development.org][Writing Snippets]]
|
|
#+BEGIN_QUOTE
|
|
Describes the YASnippet definition syntax, which is very close (but
|
|
not equivalent) to Textmate's. Includes a section about converting
|
|
TextMate snippets.
|
|
#+END_QUOTE
|
|
|
|
4. [[file:snippet-menu.org][The YASnippet menu]]
|
|
#+BEGIN_QUOTE
|
|
Explains how to use the YASnippet menu to explore, learn and modify
|
|
snippets.
|
|
#+END_QUOTE
|
|
|
|
** Bugs, discussion, contributions, etc
|
|
|
|
If you think you've found a bug, please report it on [[https://github.com/capitaomorte/yasnippet/issues][the GitHub issue tracker]]
|
|
(please **do not** submit new issues to the old [[http://code.google.com/p/yasnippet/issues/list][googlecode tracker]]).
|
|
|
|
If you run into problems using YASnippet, or have snippets to contribute,
|
|
post to the [[http://groups.google.com/group/smart-snippet][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 the snippet's *trigger key* then calling [[#yas-expand][=yas-expand=]]. It's bound to
|
|
=TAB= and =<tab>= by default, to change it use
|
|
|
|
#+begin_src emacs-lisp :exports code
|
|
(define-key yas-minor-mode-map (kbd "<tab>") nil)
|
|
(define-key yas-minor-mode-map (kbd "TAB") nil)
|
|
(define-key yas-minor-mode-map (kbd "<the new key>") 'yas-expand)
|
|
#+end_src
|
|
|
|
* 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:
|