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

* Fixed issue 98, issue 93 and issues related to the customization group

Browse Source 
* Added workaround for issue 97 in the FAQ
* Minor updates in the documentation
This commit is contained in:
capitaomorte 2009-09-05 14:44:18 +00:00
parent 7022af00f4
commit 0564b35647
5 changed files with 136 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
doc/faq.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Frequently Asked Questions</title>
<link rel="stylesheet" href="styles.css" type="text/css" />
</head>
@ -54,8 +54,8 @@
for other versions can be found <a title=""
href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
</p>
<div class="section" id="why-there-s-an-extra-newline">
<h1>Why there's an extra newline?</h1>
<div class="section" id="why-is-there-an-extra-newline">
<h1>Why is there an extra newline?</h1>
<p>If you have a newline at the end of the snippet definition file, then
YASnippet will add a newline when you expanding a snippet. Please
don't add a newline at the end if you don't want it when you saving
@ -64,8 +64,8 @@ the snippet file.</p>
if you set <tt class="docutils literal"><span class="pre">require-final-newline</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt>, it will add the final
newline for you automatically.</p>
</div>
<div class="section" id="why-tab-key-doesn-t-expand-a-snippet">
<h1>Why TAB key doesn't expand a snippet?</h1>
<div class="section" id="why-doesn-t-tab-expand-a-snippet">
<h1>Why doesn't TAB expand a snippet?</h1>
<p>First check the mode line to see if there's <tt class="docutils literal"><span class="pre">yas</span></tt>. If not, then try
<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/minor-mode</span></tt> to manually turn on the minor mode and try to
expand the snippet again. If it works, then, you can add the following
@ -88,11 +88,14 @@ than <tt class="docutils literal"><span class="pre">yas/expand</span></tt>, (e.g
code to work around:</p>
<div class="highlight"><pre>(add-hook &#39;org-mode-hook
#&#39;(lambda ()
(setq yas/fallback-behavior
`(apply ,(lookup-key org-mode-map [tab])))
(local-set-key [tab] &#39;yas/expand)))
</pre></div>
<p>replace <tt class="docutils literal"><span class="pre">org-mode-hook</span></tt> with the major mode hook you are dealing
with (<tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">m</span></tt> to see what major mode you are in).</p>
<p>If this doesn't work, you can also try</p>
<p>replace <tt class="docutils literal"><span class="pre">org-mode-hook</span></tt> and <tt class="docutils literal"><span class="pre">org-mode-map</span></tt> with the major mode
hook you are dealing with (<tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">m</span></tt> to see what major mode you are
in).</p>
<p>As an alternative, you can also try</p>
<div class="highlight"><pre>(defun yas/advise-indent-function (function-symbol)
(eval `(defadvice ,function-symbol (around yas/try-expand-first activate)
,(format
@ -114,15 +117,30 @@ group</a>.</p>
<p>Don't forget to attach the information on what command is bound to TAB
as well as the mode information (Can be obtained by <tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">m</span></tt>).</p>
</div>
<div class="section" id="how-to-define-snippets-with-named-by-characters-not-supported-by-the-filesystem">
<h1>How to define snippets with named by characters not supported by the filesystem?</h1>
<p>For example, you want to define a snippet by the key <tt class="docutils literal"><span class="pre">&lt;</span></tt> which is not a
valid character for filename on Windows. In this case, you may use
<tt class="docutils literal"><span class="pre">yas/define</span></tt> to define the snippet. If you want to enjoy defining
snippets in a file, you can use the <tt class="docutils literal"><span class="pre">key</span></tt> property to specify the key of
the defined snippet explicitly.</p>
<p>Just name your snippet with an arbitrary valid filename, <tt class="docutils literal"><span class="pre">lt</span></tt> for
example. and specify <tt class="docutils literal"><span class="pre">&lt;</span></tt> for the <tt class="docutils literal"><span class="pre">key</span></tt> property:</p>
<div class="section" id="why-doesn-t-tab-navigation-work-with-flyspell">
<h1>Why doesn't TAB navigation work with flyspell</h1>
<p>A workaround is to inhibit flyspell overlays while the snippet is active:</p>
<div class="highlight"><pre>(add-hook &#39;flyspell-incorrect-hook
#&#39;(lambda (dummy1 dummy2 dymmy3)
(and yas/active-field-overlay
(overlay-buffer yas/active-field-overlay))))
</pre></div>
<p>This is apparently related to overlay priorities. For some reason, the
<tt class="docutils literal"><span class="pre">keymap</span></tt> property of flyspell's overlays always takes priority over
the same property in yasnippet's overlays, even if one sets the
latter's <tt class="docutils literal"><span class="pre">priority</span></tt> property to something big. If you know
emacs-lisp and can solve this problem, drop a line in the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion
group</a>.</p>
</div>
<div class="section" id="how-do-i-define-an-abbrev-key-containing-characters-not-supported-by-the-filesystem">
<h1>How do I define an abbrev key containing characters not supported by the filesystem?</h1>
<p>For example, you want to define a snippet by the key <tt class="docutils literal"><span class="pre">&lt;</span></tt> which is
not a valid character for filename on Windows. This means you can't
use the filename as a trigger key in this case.</p>
<p>You should rather use the <tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive to specify the key of
the defined snippet explicitly and name your snippet with an arbitrary
valid filename, <tt class="docutils literal"><span class="pre">lt.yasnippet</span></tt> for example, using <tt class="docutils literal"><span class="pre">&lt;</span></tt> for the
<tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive:</p>
<div class="highlight"><pre>#key: &lt;
#name: &lt;...&gt;&lt;/...&gt;
# --

58
doc/faq.rst
View File

@ -2,8 +2,8 @@
Frequently Asked Questions
==========================
Why there's an extra newline?
=============================
Why is there an extra newline?
==============================
If you have a newline at the end of the snippet definition file, then
YASnippet will add a newline when you expanding a snippet. Please
@ -14,8 +14,8 @@ Note some editors will automatically add a newline for you. In Emacs,
if you set ``require-final-newline`` to ``t``, it will add the final
newline for you automatically.
Why TAB key doesn't expand a snippet?
=====================================
Why doesn't TAB expand a snippet?
=================================
First check the mode line to see if there's ``yas``. If not, then try
``M-x yas/minor-mode`` to manually turn on the minor mode and try to
@ -48,12 +48,15 @@ code to work around:
(add-hook 'org-mode-hook
#'(lambda ()
(local-set-key [tab] 'yas/expand)))
(setq yas/fallback-behavior
`(apply ,(lookup-key org-mode-map [tab])))
(local-set-key [tab] 'yas/expand)))
replace ``org-mode-hook`` with the major mode hook you are dealing
with (``C-h m`` to see what major mode you are in).
replace ``org-mode-hook`` and ``org-mode-map`` with the major mode
hook you are dealing with (``C-h m`` to see what major mode you are
in).
If this doesn't work, you can also try
As an alternative, you can also try
.. sourcecode:: lisp
@ -80,16 +83,36 @@ group <http://groups.google.com/group/smart-snippet>`_.
Don't forget to attach the information on what command is bound to TAB
as well as the mode information (Can be obtained by ``C-h m``).
How to define snippets with named by characters not supported by the filesystem?
================================================================================
For example, you want to define a snippet by the key ``<`` which is not a
valid character for filename on Windows. In this case, you may use
``yas/define`` to define the snippet. If you want to enjoy defining
snippets in a file, you can use the ``key`` property to specify the key of
the defined snippet explicitly.
Why doesn't TAB navigation work with flyspell
=============================================
Just name your snippet with an arbitrary valid filename, ``lt`` for
example. and specify ``<`` for the ``key`` property:
A workaround is to inhibit flyspell overlays while the snippet is active:
.. sourcecode:: lisp
(add-hook 'flyspell-incorrect-hook
#'(lambda (dummy1 dummy2 dymmy3)
(and yas/active-field-overlay
(overlay-buffer yas/active-field-overlay))))
This is apparently related to overlay priorities. For some reason, the
``keymap`` property of flyspell's overlays always takes priority over
the same property in yasnippet's overlays, even if one sets the
latter's ``priority`` property to something big. If you know
emacs-lisp and can solve this problem, drop a line in the `discussion
group`_.
How do I define an abbrev key containing characters not supported by the filesystem?
====================================================================================
For example, you want to define a snippet by the key ``<`` which is
not a valid character for filename on Windows. This means you can't
use the filename as a trigger key in this case.
You should rather use the ``# key:`` directive to specify the key of
the defined snippet explicitly and name your snippet with an arbitrary
valid filename, ``lt.yasnippet`` for example, using ``<`` for the
``# key:`` directive:
.. sourcecode:: text
@ -98,3 +121,4 @@ example. and specify ``<`` for the ``key`` property:
# --
<${1:div}>$0</$1>
.. _discussion group: http://groups.google.com/group/smart-snippet

42
doc/snippet-development.html
View File

@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Writing snippets</title>
<link rel="stylesheet" href="styles.css" type="text/css" />
</head>
@ -262,13 +262,17 @@ newlines.</p>
<p>To override the keymap choice based on the major mode name. Use a cons
cell where the first element specifies the name of the keymap where
you want to record the keybinding.</p>
<div class="highlight"><pre>
<div class="highlight"><pre>#name : &lt;p&gt;...&lt;/p&gt;
#binding: (rinari-minor-mode-map . &quot;C-c C-c C-m&quot;)
# --
&lt;p&gt;`(when yas/prefix &quot;\n&quot;)`$0`(when yas/prefix &quot;\n&quot;)`&lt;/p&gt;
</pre></div>
<p>Note that this feature is still experimental and should be used with
caution: It is easy to override important keybindings for many basic
modes and it is hard to undefine them. In particular, the variable
<p><em>Note</em> that this feature is still <strong>experimental</strong>, it might go away,
be changed in future release, and should be used with caution: It is
easy to override important keybindings for many basic modes and it is
hard to undefine them. For the moment, the variable
<tt class="docutils literal"><span class="pre">yas/active-keybinding</span></tt> can tell you what snippet keybindings are
active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will try to
active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt to
undefine all the keybindings.</p>
</div>
<div class="section" id="contributor-snippet-author">
@ -354,11 +358,13 @@ as the field and others mirrors.</p>
</div>
<div class="section" id="mirrors-with-transformations">
<span id="transformations"></span><h2><a class="toc-backref" href="#id19">Mirrors with transformations</a></h2>
<p>If the default value of a field starts with <tt class="docutils literal"><span class="pre">$</span></tt>, then it is interpreted
as the transformation code instead of default value. A transformation
is some arbitrary Emacs-lisp code that will get evaluated in an environment
when the variable text is bind to the inputted text of the
field. Here's an example for Objective-C:</p>
<p>If the value of an <tt class="docutils literal"><span class="pre">${n:</span></tt>-construct starts with and contains <tt class="docutils literal"><span class="pre">$(</span></tt>,
then it is interpreted as a mirror for field <tt class="docutils literal"><span class="pre">n</span></tt> with a
transformation. The mirror's text content is calculated according to
this transformation, which is Emacs-lisp code that gets evaluated in
an environment where the variable <tt class="docutils literal"><span class="pre">text</span></tt> (or <tt class="docutils literal"><span class="pre">yas/text</span></tt>) is bound
to the text content (string) contained in the field <tt class="docutils literal"><span class="pre">n</span></tt>.Here's an
example for Objective-C:</p>
<div class="highlight"><pre>- (${1:id})${2:foo}
{
return $2;
@ -371,13 +377,13 @@ field. Here's an example for Objective-C:</p>
}
$0
</pre></div>
<p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a transformation instead of
a placeholder. The actual placeholder is at the first line:
<tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the transformation
will be evaluated and the result will be placed there as the
transformed text. So in this example, if you type &quot;baz&quot; in the field,
the transformed text will be &quot;Baz&quot;. This example is also available in
the screencast.</p>
<p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a mirror with
transformation instead of a field. The actual field is at the first
line: <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the
transformation will be evaluated and the result will be placed there
as the transformed text. So in this example, if you type &quot;baz&quot; in the
field, the transformed text will be &quot;Baz&quot;. This example is also
available in the screencast.</p>
<p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document
title can be some text surrounded by &quot;===&quot; below and above. The &quot;===&quot;
should be at least as long as the text. So</p>

36
doc/snippet-development.rst
View File

@ -213,16 +213,18 @@ cell where the first element specifies the name of the keymap where
you want to record the keybinding.
.. sourcecode:: text
#name : <p>...</p>
#binding: (rinari-minor-mode-map . "C-c C-c C-m")
# --
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
Note that this feature is still experimental and should be used with
caution: It is easy to override important keybindings for many basic
modes and it is hard to undefine them. In particular, the variable
*Note* that this feature is still **experimental**, it might go away,
be changed in future release, and should be used with caution: It is
easy to override important keybindings for many basic modes and it is
hard to undefine them. For the moment, the variable
``yas/active-keybinding`` can tell you what snippet keybindings are
active and the function ``yas/kill-snippet-keybindings`` will try to
active and the function ``yas/kill-snippet-keybindings`` will attempt to
undefine all the keybindings.
``# contributor:`` snippet author
@ -339,11 +341,13 @@ as the field and others mirrors.
Mirrors with transformations
----------------------------
If the default value of a field starts with ``$``, then it is interpreted
as the transformation code instead of default value. A transformation
is some arbitrary Emacs-lisp code that will get evaluated in an environment
when the variable text is bind to the inputted text of the
field. Here's an example for Objective-C:
If the value of an ``${n:``-construct starts with and contains ``$(``,
then it is interpreted as a mirror for field ``n`` with a
transformation. The mirror's text content is calculated according to
this transformation, which is Emacs-lisp code that gets evaluated in
an environment where the variable ``text`` (or ``yas/text``) is bound
to the text content (string) contained in the field ``n``.Here's an
example for Objective-C:
.. sourcecode:: text
@ -359,13 +363,13 @@ field. Here's an example for Objective-C:
}
$0
Look at ``${2:$(capitalize text)}``, it is a transformation instead of
a placeholder. The actual placeholder is at the first line:
``${2:foo}``. When you type text in ``${2:foo}``, the transformation
will be evaluated and the result will be placed there as the
transformed text. So in this example, if you type "baz" in the field,
the transformed text will be "Baz". This example is also available in
the screencast.
Look at ``${2:$(capitalize text)}``, it is a mirror with
transformation instead of a field. The actual field is at the first
line: ``${2:foo}``. When you type text in ``${2:foo}``, the
transformation will be evaluated and the result will be placed there
as the transformed text. So in this example, if you type "baz" in the
field, the transformed text will be "Baz". This example is also
available in the screencast.
Another example is for ``rst-mode``. In reStructuredText, the document
title can be some text surrounded by "===" below and above. The "==="

24
yasnippet.el
View File

@ -314,6 +314,7 @@ field"
:type '(choice (const :tag "Call previous command" call-other-command)
(const :tag "Do nothing" return-nil))
:group 'yasnippet)
(make-variable-buffer-local 'yas/fallback-behavior)
(defcustom yas/choose-keys-first nil
"If non-nil, prompt for snippet key first, then for template.
@ -700,7 +701,8 @@ With optional UNBIND-KEY, try to unbind that key from
(stringp yas/trigger-key)
(not (string= yas/trigger-key "")))
(define-key yas/minor-mode-map (read-kbd-macro yas/trigger-key) 'yas/expand)))
;;;###autoload
(define-minor-mode yas/minor-mode
"Toggle YASnippet mode.
@ -741,6 +743,7 @@ this effectively lets you define exceptions to the \"global\"
behaviour.")
(make-variable-buffer-local 'yas/dont-activate)
(defun yas/minor-mode-on ()
"Turn on YASnippet minor mode.
@ -1846,11 +1849,15 @@ defined in `yas/fallback-behavior'"
nil)
((eq yas/fallback-behavior 'call-other-command)
(let* ((yas/minor-mode nil)
(keys (or (and yas/trigger-key
(stringp yas/trigger-key)
(read-kbd-macro yas/trigger-key))
(this-command-keys-vector)))
(command (key-binding keys)))
(keys-1 (this-command-keys-vector))
(keys-2 (and yas/trigger-key
(stringp yas/trigger-key)
(read-kbd-macro yas/trigger-key)))
(command-1 (and keys-1 (key-binding keys-1)))
(command-2 (and keys-2(key-binding keys-2)))
(command (or (and (not (eq' command-1 'yas/expand))
command-1)
command2)))
(when (and (commandp command)
(not (eq 'yas/expand command)))
(setq this-command command)
@ -2680,6 +2687,7 @@ Move the overlay, or create it if it does not exit."
(make-overlay (yas/field-start field)
(yas/field-end field)
nil nil t))
(overlay-put yas/active-field-overlay 'priority 100)
(overlay-put yas/active-field-overlay 'face 'yas/field-highlight-face)
(overlay-put yas/active-field-overlay 'yas/snippet snippet)
(overlay-put yas/active-field-overlay 'modification-hooks '(yas/on-field-overlay-modification))
@ -3067,9 +3075,9 @@ Meant to be called in a narrowed buffer, does various passes"
;; Reset the yas/dollar-regions
;;
(setq yas/dollar-regions nil)
;; protect quote and backquote escapes
;; protect escaped quote, backquotes and backslashes
;;
(yas/protect-escapes nil '(?` ?'))
(yas/protect-escapes nil '(?\\ ?` ?'))
;; replace all backquoted expressions
;;
(goto-char parse-start)