X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/da9852a43f2d6011094e12d813dcb7eab6851e69..e9406f51266f9b9179f475886fa4ec78f1ccba44:/doc/snippet-development.org diff --git a/doc/snippet-development.org b/doc/snippet-development.org index f0ab1320c..c79248376 100644 --- a/doc/snippet-development.org +++ b/doc/snippet-development.org @@ -1,19 +1,23 @@ #+SETUPFILE: org-setup.inc -* Writing snippets +#+TITLE: Writing snippets -** Snippet development +* Snippet development -*** Quickly finding snippets +** Quickly finding snippets -There are some ways you can quickly find a snippet file: +There are some ways you can quickly find a snippet file or create a new one: - =M-x yas-new-snippet= - Prompts you for a snippet name, then tries to guess a suitable - directory to store it, prompting you for creation if it does not - exist. Finally, places you in a new buffer set to =snippet-mode= so - you can write your snippet. + Creates a new buffer with a template for making a new snippet. + The buffer is in =snippet-mode= (see below). When you are done + editing the new snippet, use =C-c C-c= to save it. This will + prompt for a directory two steps: first, the snippet table + (with a default based on the major mode you started in), and then + then snippet collection directory (defaults to the first directory + in =yas-snippet-dirs=. (See [[file:snippet-organization.org][Organizing Snippets]] + for more detail on how snippets are organized.) - =M-x yas-find-snippets= @@ -30,7 +34,7 @@ There are some ways you can quickly find a snippet file: Once you find this file it will be set to =snippet-mode= (see ahead) and you can start editing your snippet. -*** Using the =snippet-mode= major mode +** Using the =snippet-mode= major mode There is a major mode =snippet-mode= to edit snippets. You can set the buffer to this mode with =M-x snippet-mode=. It provides reasonably @@ -40,25 +44,21 @@ Two commands are defined in this mode: - =M-x yas-load-snippet-buffer= - #+BEGIN_QUOTE When editing a snippet, this loads the snippet into the correct mode and menu. Bound to =C-c C-c= by default while in =snippet-mode=. - #+END_QUOTE - =M-x yas-tryout-snippet= - #+BEGIN_QUOTE When editing a snippet, this opens a new empty buffer, sets it to the appropriate major mode and inserts the snippet there, so you can see what it looks like. This is bound to =C-c C-t= while in =snippet-mode=. - #+END_QUOTE There are also /snippets for writing snippets/: =vars=, =$f= and =$m= :-). -** File content +* File content A file defining a snippet generally contains the template to be expanded. @@ -80,14 +80,14 @@ Here's a typical example: Here's a list of currently supported directives: -*** =# key:= snippet abbrev +** =# key:= snippet abbrev -This is the probably the most important directive, it's the abbreviation -you type to expand a snippet just before hitting [[sym:yas-trigger-key][=yas-trigger-key=]]. If -you don't specify this the snippet will not be expandable through the -key mechanism. +This is the probably the most important directive, it's the +abbreviation you type to expand a snippet just before hitting the key +that runs [[sym:yas-expand][=yas-expand=]]. If you don't specify this +the snippet will not be expandable through the trigger mechanism. -*** =# name:= snippet name +** =# name:= snippet name This is a one-line description of the snippet. It will be displayed in the menu. It's a good idea to select a descriptive name for a snippet -- @@ -96,7 +96,7 @@ especially distinguishable among similar snippets. If you omit this name it will default to the file name the snippet was loaded from. -*** =# condition:= snippet condition +** =# condition:= snippet condition This is a piece of Emacs-lisp code. If a snippet has a condition, then it will only be expanded when the condition code evaluate to some @@ -105,7 +105,7 @@ non-nil value. See also [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] in [[./snippet-expansion.org][Expanding snippets]] -*** =# group:= snippet menu grouping +** =# group:= snippet menu grouping When expanding/visiting snippets from the menu-bar menu, snippets for a given mode can be grouped into sub-menus . This is useful if one has too @@ -122,7 +122,7 @@ Refer to the bundled snippets for =ruby-mode= for examples on the =control structure.loops= tells that the snippet is under the =loops= group which is under the =control structure= group. -*** =# expand-env:= expand environment +** =# expand-env:= expand environment This is another piece of Emacs-lisp code in the form of a =let= /varlist form/, i.e. a list of lists assigning values to variables. It can be @@ -152,7 +152,7 @@ You can then use: +--+-+--+ #+END_SRC -*** =# binding:= direct keybinding +** =# binding:= direct keybinding You can use this directive to expand a snippet directly from a normal Emacs keybinding. The keybinding will be registered in the Emacs keymap @@ -173,29 +173,45 @@ This binding will be recorded in the keymap =html-mode-map=. To expand a paragraph tag newlines, just press =C-u C-c C-c C-m=. Omitting the =C-u= will expand the paragraph tag without newlines. -*** =# contributor:= snippet author +** =# type:= =snippet= or =command= + +If the =type= directive is set to =command=, the body of the snippet +is interpreted as lisp code to be evaluated when the snippet is +triggered. + +If it's =snippet= (the default when there is no =type= directive), the +snippet body will be parsed according to the [[Template Syntax]], +described below. + +** =# uuid:= unique identifier + +This provides to a way to identify a snippet, independent of its name. +Loading a second snippet file with the same uuid would replace the +previous snippet. + +** =# contributor:= snippet author This is optional and has no effect whatsoever on snippet functionality, but it looks nice. -** Template syntax +* Template Syntax The syntax of the snippet template is simple but powerful, very similar to TextMate's. -*** Plain Text +** Plain Text Arbitrary text can be included as the content of a template. They are -usually interpreted as plain text, except =$= and ==. You need to -use \` to escape them: =\$= and =\=. The \` itself may also needed to be +usually interpreted as plain text, except =$= and =`=. You need to +use =\= to escape them: =\$= and =\`=. The =\= itself may also needed to be escaped as =\\= sometimes. -*** Embedded Emacs-lisp code +** Embedded Emacs-lisp code Emacs-Lisp code can be embedded inside the template, written inside -back-quotes (==). The lisp forms are evaluated when the snippet is +back-quotes (=`=). The lisp forms are evaluated when the snippet is being expanded. The evaluation is done in the same buffer as the -snippet being expanded. +snippet being expanded. Here's an example for c-mode` to calculate the header file guard dynamically: @@ -203,9 +219,9 @@ dynamically: #+BEGIN_SRC snippet #ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_} #define $1 - + $0 - + #endif /* $1 */ #+END_SRC @@ -223,7 +239,7 @@ to "wrap" the selected region inside your recently inserted snippet. Alternatively, you can also customize the variable [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] to =t= which will do this automatically. -*** Tab stop fields +** Tab stop fields Tab stops are fields that you can navigate back and forth by =TAB= and =S-TAB=. They are written by =$= followed with a number. =$0= has the @@ -235,7 +251,7 @@ to go when you've traveled all the fields. Here's a typical example: $0 #+END_SRC -*** Placeholder fields +** Placeholder fields Tab stops can have default values -- a.k.a placeholders. The syntax is like this: @@ -246,10 +262,10 @@ like this: They acts as the default value for a tab stop. But when you firstly type at a tab stop, the default value will be replaced by your typing. -The number can be omitted if you don't want to create [[mirrors]] or -[[transformations]] for this field. +The number can be omitted if you don't want to create [[mirrors-fields][mirrors]] or +[[mirror-transformations][transformations]] for this field. -*** <> +** Mirrors <> We refer the tab stops with placeholders as a /field/. A field can have mirrors. Its mirrors will get updated when you change the text of a @@ -269,22 +285,23 @@ The tab stops with the same number to the field act as its mirrors. If none of the tab stops has an initial value, the first one is selected as the field and others mirrors. -*** Mirrors with <> +** Mirrors with transformations <> -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 [[sym:yas-text][=yas-text=]]) is bound to the text content (string) -contained in the field =n=.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 [[sym:yas-text][=yas-text=]] is bound to the text +content (string) contained in the field =n=. Here's an example for +Objective-C: #+BEGIN_SRC snippet - (${1:id})${2:foo} { return $2; } - - - (void)set${2:$(capitalize text)}:($1)aValue + + - (void)set${2:$(capitalize yas-text)}:($1)aValue { [$2 autorelease]; $2 = [aValue retain]; @@ -292,12 +309,13 @@ contained in the field =n=.Here's an example for Objective-C: $0 #+END_SRC -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. +Look at =${2:$(capitalize yas-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 "===" @@ -320,14 +338,14 @@ is a valid title but is not. Here's an snippet for rst title: #+BEGIN_SRC snippet - ${1:$(make-string (string-width text) ?\=)} + ${1:$(make-string (string-width yas-text) ?\=)} ${1:Title} - ${1:$(make-string (string-width text) ?\=)} - + ${1:$(make-string (string-width yas-text) ?\=)} + $0 #+END_SRC -*** Fields with transformations +** Fields with transformations From version 0.6 on, you can also have lisp transformation inside fields. These work mostly mirror transformations but are evaluated when @@ -355,7 +373,7 @@ value of the field and sets it its internal modification state to =true=. As a consequence, the auto-deletion behaviour of normal fields does not take place. This is by design. -*** Choosing fields value from a list and other tricks +** Choosing fields value from a list and other tricks As mentioned, the field transformation is invoked just after you enter the field, and with some useful variables bound, notably @@ -381,14 +399,13 @@ enter snippet field 2. This one makes use of [[sym:yas-modified-p][=yas-modified \section{${1:"Titel der Tour"}}% \index{$1}% \label{{2:"waiting for reftex-label call..."$(unless yas-modified-p (reftex-label nil 'dont- - insert))}}% + insert))}}% #+END_SRC -The function [[sym:yas-verify-value][=yas-verify-value=]] has another neat trick, and makes use of -[[sym:yas-moving-away-p][=yas-moving-away-p=]]. Try it and see! Also, check out this -[[http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662][thread]] +The function [[sym:yas-verify-value][=yas-verify-value=]] has another neat trick, and makes use +of [[sym:yas-moving-away-p][=yas-moving-away-p=]]. Try it and see! Also, check out this [[http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662][thread]] -*** Nested placeholder fields +** Nested placeholder fields From version 0.6 on, you can also have nested placeholders of the type: @@ -406,51 +423,8 @@ By the way, =C-d= will only clear the field if you cursor is at the beginning of the field /and/ it hasn't been changed yet. Otherwise, it performs the normal Emacs =delete-char= command. -** Importing TextMate snippets - -There are a couple of tools that take TextMate's ".tmSnippet" xml files -and create YASnippet definitions: - -#+BEGIN_QUOTE - - - [[http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py][a python script by Jeff Wheeler]] - - - a [[http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb][ruby tool]] , =textmate_import.rb= adapted from [[http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/][Rob Christie's]], - which I have uploaded to the repository. - -#+END_QUOTE - -In this section, i'll shortly cover the *second* option. - -Download the =textmate_import.rb= tool and the TextMate bundle you're -interested in. - -#+BEGIN_EXAMPLE - $ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb - $ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/ -#+END_EXAMPLE - -Then invoke =textmate_import.rb= like this: - -#+BEGIN_EXAMPLE - $ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist -#+END_EXAMPLE - -You should end up with a =html-mode= subdir containing snippets exported -from textmate. - -#+BEGIN_EXAMPLE - $ tree html-mode # to view dir contents, if you have 'tree' installed -#+END_EXAMPLE - -The =-g= is optional but helps the tool figure out the grouping. -According to [[./snippet-organization.org][Organizing Snippets]], don't forget to touch -=.yas-make-groups= and =.yas-ignore-filename-triggers= inside the -=html-mode= dir. - -Also try =textmate_import.rb --help= for a list of options. +** Indentation markers -Please note that snippet importation is not yet perfect. You'll probably -have some adjustments to some/many snippets. Please contribute these -adjustments to the google group or, better yet, patch the -=textmate_import.rb= to automatically perform them and submit that. +If [[sym:yas-indent-line][=yas-indent-line=]] is *not* set to '=auto=, it's still possible to +indent specific lines by adding an indentation marker, =$>=, somewhere +on the line.