#summary Design of yasnippet.
#labels Phase-Design,Deprecated

= How to trigger =
== Explicit trigger key ==
I won't use the build-in abbrev of Emacs this time. As the experience with smart-snippet, many people hate expanding whenever you press a non-word key, even if it can be sometimes smart. I'll provide an explicit key binding to trigger expansion of a snippet, e.g. TAB.

== Menu support ==
One can also select a snippet from the menu and expand it.

== Snippet won't store in the build-in abbrev-table ==
Snippets won't store in the build-in abbrev-table either. Some mode even have no abbrev-table. 
 * Each major-mode have its own snippet-table.
 * Each snippet-table is a `key -> snippet` hash table.
 * All tables are stored in `yas/snippet-tables` which is a hash of `major-mode -> snippet-table`.

= How to define a snippet =
== Single snippet a time with elisp ==
Provide something like `yas/define` to define a snippet a time. But also provide mechanize to import from a msf-abbrev like directory structure or directly from Textmate bundle and dump to a .elc file.

= Fields =
== Syntax ==
Valid syntaxes:
 * `$\d+` *e.g.*: `$1` , `$5` , however, `$0` have special meaning of the exit position.
 * `${\d+:[^}]*}` *e.g.*: `${1:default value}` , `${3:}` , `${5:\$var}` (`\$` is safely escaped).
 * `${[^}]*}` *e.g.*: `${value}` .

|| Example        || number || value   ||
|| `$1`           || 1      || `nil`   ||
|| `${2:foo}`     || 2      || `foo`   ||
|| `${foo:bar}`   || `nil`  || `foo:bar` ||
|| `${10}`        || `nil`  || `10`    ||
|| `$10`          || 10     || `nil`   ||
|| `${foobar}`    || `nil`  || `foobar`||

== Order ==
The number for each field indicate the travel order. Unnumbered field are put after numbered field, sorted by the occurred position.

== Mirrors ==
Numbered fields can have mirrors. For example:
{{{
\begin{${1:enumerate}}
    $0
\end{$1}
}}}
Here `$1` is mirror. It can get updated when editing `${1:enumerate}`. Mirror won't be in the TAB-traversal list. Unnumbered field won't have mirrors.

= Support Elisp =
== Syntax ==
Textmate snippet support shell command, with the syntax of command being enclosed in backquote. I don't want shell command so I make use of this syntax to support elisp. e.g:
{{{
Write to `user-full-name` <`user-mail-address`>
}}}

== When ==
Elisp are evaluated before interpreting the fields. So you can even create fields in this phase:
{{{
Write to `(concat "${" user-full-name "}")` <`(concat "${" user-mail-address "}")`>
}}}
Or simply:
{{{
Write to ${`user-full-name`} <${`user-mail-address`}>
}}}

== Where ==
~~Currently the elisp is evaluated in a temp buffer. Unless I see there's critical reason it need to be evaluated in the original buffer, I'll stick to this.~~ The elisp is evaluated in the same buffer where the snippet is being expanded.

= Data Structure =
== snippet ==
 * `overlay`: the overlay of the snippet.
 * ~~`id`: the id of the snippet.~~
 * `fields`: an alist of fields of the snippet. Associated with field number.
 * `exit-marker`: go to this marker when snippet exits.

== snippet-field ==
 * `overlay`: the overlay of the field.
 * ~~`snippet`: to which snippet the field belongs.~~
 * `state`: whether initial default value has been typed to replaced.