ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2025-10-14 05:23:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

move index.org subsection into snippet-organization.org

Browse Source 
This almost completely overwrites the existing snippet-organization.org
which was imported from snippet-organization.rst via pandoc.
This commit is contained in:
Noam Postavsky 2013-11-24 16:00:04 -05:00
parent 5acc976712
commit 875ef77dfb
2 changed files with 90 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
doc/index.org
View File

@ -127,120 +127,6 @@
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 [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
which collections to consider. It's used when you activate
[[sym:yas-global-mode][=yas-global-mode=]] or call
[[sym: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. [[sym: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

168
doc/snippet-organization.org
View File

@ -1,107 +1,119 @@
* Organizing snippets
** Loading snippets
** Basic structure
Snippet definitions are stored in files in the filesystem. Unless you
use the simpler [[index.html@installation][bundle version]]), these are
arranged so that YASnippet can load them into /snippet tables/. The
triggering mechanisms (see [[snippet-expansion.html][Expanding
snippets]]) will look up these snippet tables and (hopefully) expand the
snippet you intended.
Snippet collections can be stored in plain text files. They are arranged by
sub-directories naming *snippet tables*. These mostly name Emacs major names.
The non-bundle version of YASnippet, once unpacked, comes with a full
directory of snippets, which you can copy somewhere and use. You can
also create or download more directories.
#+begin_example
.
|-- c-mode
| `-- printf
|-- java-mode
| `-- println
`-- text-mode
|-- email
`-- time
#+end_example
Once these directories are in place reference them in the variable
=yas-root-directory= and load them with =yas-load-directory=:
The collections are loaded into *snippet tables* which the
triggering mechanism (see [[file:snippet-expansion.org][Expanding Snippets]]) looks up and
(hopefully) causes the right snippet to be expanded for you.
The point in using =yas-root-directory= (as opposed to calling
=yas-load-directory= directly) is considering "~/emacs.d/mysnippets" for
snippet development, so you can use commands like =yas-new-snippet= and
others described in section [[snippet-development.html][Writing
Snippets]].
** Setting up =yas-snippet-dirs=
You can make this variable a list and store more items into it:
The emacs variable [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
which collections to consider. It's used when you activate
[[sym:yas-global-mode][=yas-global-mode=]] or call
[[sym:yas-reload-all][=yas-reload-all=]] interactively.
In this last example, the all the directories are loaded and their
snippets considered for expansion. However development still happens in
the first element, "~/emacs.d/mysnippets".
The default considers:
** Organizing snippets
- a personal collection that lives in =~/.emacs.d/snippets=
- the bundled collection, taken as a relative path to =yasnippet.el= localtion
Once you've setup =yas-root-directory= , you can store snippets inside
sub-directories of these directories.
When you come across other snippet collections, do the following to try them
out:
Snippet definitions are put in plain text files. They are arranged by
sub-directories, and the snippet tables are named after these
directories.
#+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"))
The name corresponds to the Emacs mode where you want expansion to take
place. For example, snippets for =c-mode= are put in the =c-mode=
sub-directory.
;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
(setq yas-snippet-dirs (append yas-snippet-dirs
'("~/Downloads/interesting-snippets")))
#+end_src
*** The =.yas.parents= file
Collections appearing earlier in the list shadow snippets with same names
appearing in collections later in the list. [[sym: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.
names. When you reload those modes become parents of the original
mode.
*** The =.yas-make-groups= file
#+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.org][the menu]] is organized much more
cleanly:
[[images/menu-groups.png]]
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.html][The YASnippet Menu]] is
organized much more cleanly, as you can see in the image.
Another way to achieve this is to place a =# group:= directive
inside the snippet definition. See [[snippet-development.org][Writing Snippets]].
Another alternative way to achieve this is to place a =# group:=
directive inside the snippet definition. See
[[snippet-development.html][Writing Snippets]].
#+begin_example
$ tree ruby-mode/
ruby-mode/
|-- .yas-make-groups
|-- collections
| |-- each
| `-- ...
|-- control structure
| |-- forin
| `-- ...
|-- definitions
| `-- ...
`-- general
`-- ...
#+end_example
** YASnippet bundle
Yet another way to create a nice snippet menu is to write into
=.yas-make-groups= a menu definition. TODO
The most convenient way to define snippets for YASnippet is to put them
in a directory arranged by the mode and use =yas-load-directory= to load
them.
** TODO The =.yas-setup.el= file
However, this might slow down the Emacs start-up speed if you have many
snippets. You can use =yas-define-snippets= to define a bunch of
snippets for a particular mode in an Emacs-lisp file.
*** TODO
Since this is hard to maintain, there's a better way: define your
snippets in directory and then call =M-x yas-compile-bundle= to compile
it into a bundle file when you modified your snippets.
** TODO The =.yas-compiled-snippet.el= file
The release bundle of YASnippet is produced by =yas-compile-bundle=. The
bundle uses =yas-define-snippets= to define snippets. This avoids the IO
and parsing overhead when loading snippets.
*** TODO
Further more, the generated bundle is a stand-alone file not depending
on =yasnippet.el=. The released bundles of YASnippet are all generated
this way.
** TODO The =.yas-skip= file
See the internal documentation for these functions
- =M-x describe-function RET yas-define-snippets RET=
- =M-x describe-function RET yas-compile-bundle RET=.
** Customizable variables
*** =yas-root-directory=
Root directory that stores the snippets for each major mode.
If you set this from your .emacs, can also be a list of strings, for
multiple root directories. If you make this a list, the first element is
always the user-created snippets directory. Other directories are used
for bulk reloading of all snippets using =yas-reload-all=
*** =yas-ignore-filenames-as-triggers=
If non-nil, don't derive tab triggers from filenames.
This means a snippet without a =# key:= directive wont have a tab
trigger.
*** TODO