mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-14 05:23:04 +00:00
move index.org subsection into snippet-organization.org
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
parent
5acc976712
commit
875ef77dfb
114
doc/index.org
114
doc/index.org
@ -127,120 +127,6 @@
|
|||||||
If you run into problems using YASnippet, or have snippets to contribute,
|
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!
|
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
|
* Expanding Snippets
|
||||||
|
|
||||||
|
|||||||
@ -1,107 +1,119 @@
|
|||||||
* Organizing snippets
|
* Organizing snippets
|
||||||
|
|
||||||
** Loading snippets
|
** Basic structure
|
||||||
|
|
||||||
Snippet definitions are stored in files in the filesystem. Unless you
|
Snippet collections can be stored in plain text files. They are arranged by
|
||||||
use the simpler [[index.html@installation][bundle version]]), these are
|
sub-directories naming *snippet tables*. These mostly name Emacs major names.
|
||||||
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.
|
|
||||||
|
|
||||||
The non-bundle version of YASnippet, once unpacked, comes with a full
|
#+begin_example
|
||||||
directory of snippets, which you can copy somewhere and use. You can
|
.
|
||||||
also create or download more directories.
|
|-- c-mode
|
||||||
|
| `-- printf
|
||||||
|
|-- java-mode
|
||||||
|
| `-- println
|
||||||
|
`-- text-mode
|
||||||
|
|-- email
|
||||||
|
`-- time
|
||||||
|
#+end_example
|
||||||
|
|
||||||
Once these directories are in place reference them in the variable
|
The collections are loaded into *snippet tables* which the
|
||||||
=yas-root-directory= and load them with =yas-load-directory=:
|
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
|
** Setting up =yas-snippet-dirs=
|
||||||
=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]].
|
|
||||||
|
|
||||||
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
|
The default considers:
|
||||||
snippets considered for expansion. However development still happens in
|
|
||||||
the first element, "~/emacs.d/mysnippets".
|
|
||||||
|
|
||||||
** 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
|
When you come across other snippet collections, do the following to try them
|
||||||
sub-directories of these directories.
|
out:
|
||||||
|
|
||||||
Snippet definitions are put in plain text files. They are arranged by
|
#+begin_src emacs-lisp :exports code
|
||||||
sub-directories, and the snippet tables are named after these
|
;; Develop in ~/emacs.d/mysnippets, but also
|
||||||
directories.
|
;; 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
|
;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
|
||||||
place. For example, snippets for =c-mode= are put in the =c-mode=
|
(setq yas-snippet-dirs (append yas-snippet-dirs
|
||||||
sub-directory.
|
'("~/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.
|
||||||
|
|
||||||
It's very useful to have certain modes share snippets between
|
** The =.yas-parents= file
|
||||||
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.
|
|
||||||
|
|
||||||
*** The =.yas-make-groups= 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.
|
||||||
|
|
||||||
[[images/menu-groups.png]]
|
#+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
|
||||||
|
|
||||||
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 alternative way to achieve this is to place a =# group:=
|
** TODO The =.yas-make-groups= file
|
||||||
directive inside the snippet definition. See
|
|
||||||
[[snippet-development.html][Writing Snippets]].
|
|
||||||
|
|
||||||
** YASnippet bundle
|
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:
|
||||||
|
|
||||||
The most convenient way to define snippets for YASnippet is to put them
|
[[images/menu-groups.png]]
|
||||||
in a directory arranged by the mode and use =yas-load-directory= to load
|
|
||||||
them.
|
|
||||||
|
|
||||||
However, this might slow down the Emacs start-up speed if you have many
|
Another way to achieve this is to place a =# group:= directive
|
||||||
snippets. You can use =yas-define-snippets= to define a bunch of
|
inside the snippet definition. See [[snippet-development.org][Writing Snippets]].
|
||||||
snippets for a particular mode in an Emacs-lisp file.
|
|
||||||
|
|
||||||
Since this is hard to maintain, there's a better way: define your
|
#+begin_example
|
||||||
snippets in directory and then call =M-x yas-compile-bundle= to compile
|
$ tree ruby-mode/
|
||||||
it into a bundle file when you modified your snippets.
|
ruby-mode/
|
||||||
|
|-- .yas-make-groups
|
||||||
|
|-- collections
|
||||||
|
| |-- each
|
||||||
|
| `-- ...
|
||||||
|
|-- control structure
|
||||||
|
| |-- forin
|
||||||
|
| `-- ...
|
||||||
|
|-- definitions
|
||||||
|
| `-- ...
|
||||||
|
`-- general
|
||||||
|
`-- ...
|
||||||
|
#+end_example
|
||||||
|
|
||||||
The release bundle of YASnippet is produced by =yas-compile-bundle=. The
|
Yet another way to create a nice snippet menu is to write into
|
||||||
bundle uses =yas-define-snippets= to define snippets. This avoids the IO
|
=.yas-make-groups= a menu definition. TODO
|
||||||
and parsing overhead when loading snippets.
|
|
||||||
|
|
||||||
Further more, the generated bundle is a stand-alone file not depending
|
** TODO The =.yas-setup.el= file
|
||||||
on =yasnippet.el=. The released bundles of YASnippet are all generated
|
|
||||||
this way.
|
|
||||||
|
|
||||||
See the internal documentation for these functions
|
*** TODO
|
||||||
|
|
||||||
- =M-x describe-function RET yas-define-snippets RET=
|
** TODO The =.yas-compiled-snippet.el= file
|
||||||
- =M-x describe-function RET yas-compile-bundle RET=.
|
|
||||||
|
|
||||||
** Customizable variables
|
*** TODO
|
||||||
|
|
||||||
*** =yas-root-directory=
|
** TODO The =.yas-skip= file
|
||||||
|
|
||||||
Root directory that stores the snippets for each major mode.
|
*** TODO
|
||||||
|
|
||||||
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.
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user