diff --git a/README.mdown b/README.mdown index a84b665..f003bcb 100644 --- a/README.mdown +++ b/README.mdown @@ -1,13 +1,13 @@ # Intro -**yasnippet** is a template system for Emacs. It allows you to type an +**YASnippet** is a template system for Emacs. It allows you to type an abbreviation and automatically expand it into function templates. Bundled language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML, CSS and more. The snippet syntax is inspired from [TextMate's][textmate-snippets] syntax, you can even -[import][import-docs] most TextMate templates to yasnippet. Watch +[import][import-docs] most TextMate templates to YASnippet. Watch [a demo on YouTube][youtube-demo] or download a [higher resolution version][high-res-demo] @@ -30,15 +30,14 @@ Add the following in your `.emacs` file: (add-to-list 'load-path "~/.emacs.d/plugins/yasnippet") (require 'yasnippet) - (yas/global-mode 1) - -Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas/new-snippet`. + (yas-global-mode 1) +Add your own snippets to `~/.emacs.d/snippets` by placing files there or invoking `yas-new-snippet`. ## Install with `package-install` -In a recent emacs `M-x list-packages` is the recommended way to list and install packages. -[MELPA][melpa] keeps a very recent snapshot of yasnippet, see http://melpa.milkbox.net/#installing. +In a recent emacs `M-x list-packages` is the recommended way to list and install packages. +[MELPA][melpa] keeps a very recent snapshot of YASnippet, see http://melpa.milkbox.net/#installing. ## Install with el-get @@ -56,37 +55,37 @@ Consider using this "local" recipe. :compile "yasnippet.el") el-get-sources) -## Use `yas/minor-mode` on a per-buffer basis +## Use `yas-minor-mode` on a per-buffer basis -To use yasnippet as a non-global minor mode, replace `(yas/global-mode 1)` with -`(yas/reload-all)` to load the snippet tables. Then add a call to -`(yas/minor-mode)` to the major-modes where you to enable yasnippet. +To use YASnippet as a non-global minor mode, replace `(yas-global-mode 1)` with +`(yas-reload-all)` to load the snippet tables. Then add a call to +`(yas-minor-mode)` to the major-modes where you to enable YASnippet. (add-hook 'prog-mode-hook '(lambda () - (yas/minor-mode))) + (yas-minor-mode))) # (NOT) Contributing snippets Please **do not** open pull requests or ask me to add snippets to -yasnippet. +YASnippet. The bundled collection under `/snippets` is considered frozen: **I will not add more snippets to it**. -You can point `yas/snippet-dirs` to good snippet collections out +You can point `yas-snippet-dirs` to good snippet collections out there. If you have created snippets for a mode, or multiple modes, consider creating a repository to host them, then tell users that it -should be added like this to `yas/snippet-dirs`: +should be added like this to `yas-snippet-dirs`: - (setq yas/snippet-dirs + (setq yas-snippet-dirs '("~/.emacs.d/snippets" ;; personal snippets "/path/to/some/collection/" ;; just some foo-mode snippets "/path/to/some/othercollection/" ;; some more foo-mode and a complete baz-mode "/path/to/yasnippet/snippets" ;; the default collection )) - (yas/global-mode 1) ;; or M-x yas/reload-all if you've started yasnippet already. + (yas-global-mode 1) ;; or M-x yas-reload-all if you've started YASnippet already. # Importing TextMate snippets @@ -119,8 +118,8 @@ Then, in your `.emacs` file (add-to-list 'load-path "~/.emacs.d/plugins/yasnippet") (require 'yasnippet) - (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported")) - (yas/global-mode 1) + (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/plugins/yasnippet/extras/imported")) + (yas-global-mode 1) Open some rails file (model, app, etc) and start using the textmate snippets. Note that in the example above we have abandoned the @@ -134,8 +133,8 @@ and support. If you find a bug, please report it on [the GitHub issue tracker][issues]. (please **do not** submit new issues to the old [googlecode tracker][googlecode tracker]) -If you run into problems using yasnippet, or have snippets to contribute, post -to the [yasnippet google group][forum]. Thank you very much for using yasnippet! +If you run into problems using YASnippet, or have snippets to contribute, post +to the [YASnippet google group][forum]. Thank you very much for using YASnippet! [docs]: http://capitaomorte.github.com/yasnippet/ [issues]: https://github.com/capitaomorte/yasnippet/issues diff --git a/doc/changelog.rst b/doc/changelog.rst index 0c090f8..d830743 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -30,7 +30,7 @@ ChangeLog * Much more powerful menu. See `The YASnippet menu`_. * New ways to organize snippets. See `Organizing snippets`_. -* Added ``yas/also-auto-indent-first-line`` customization variable. +* Added ``yas-also-auto-indent-first-line`` customization variable. * Renamed directive ``# env:`` to ``# expand-env:`` * Rewrote much of the documentation. * Added TextMate import tool ``textmate-import.rb`` to to svn @@ -53,7 +53,7 @@ ChangeLog * Fixed `Issue 68 `_ with mouse-clicking alternatives in ``ido-mode``. -* Added ``yas/also-auto-indent-first-line`` customization variable. +* Added ``yas-also-auto-indent-first-line`` customization variable. 0.6.0b / 2009-07-25 @@ -67,17 +67,17 @@ ChangeLog * Transformation on a primary field with syntax ``${1:default$(transform)}`` -* Validations on field exit through the ``yas/verify-value`` +* Validations on field exit through the ``yas-verify-value`` primary field transformation. * Wrapping the region in the exit marker ``$0`` of the snippet. Use - ``yas/wrap-around-region``. + ``yas-wrap-around-region``. -* Auto-indentation. Use ``yas/indent-line`` set to ``'auto`` +* Auto-indentation. Use ``yas-indent-line`` set to ``'auto`` -* Easier definition of snippets. Use ``yas/find-snippets`` or - ``yas/visit-snippet-file``. In the new ``snippet-mode`` use - ``yas/load-snippet-buffer`` and ``yas/tryout-snippet``. +* Easier definition of snippets. Use ``yas-find-snippets`` or + ``yas-visit-snippet-file``. In the new ``snippet-mode`` use + ``yas-load-snippet-buffer`` and ``yas-tryout-snippet``. * Customization group ``yasnippet``. @@ -114,10 +114,10 @@ ChangeLog 46 `_). * Fixed `Issue 45 `_ by - providing a proper default value for ``yas/buffer-local-condition``. -* Added helper function ``yas/substr`` for convenient mirror + providing a proper default value for ``yas-buffer-local-condition``. +* Added helper function ``yas-substr`` for convenient mirror transformation. -* Make variable ``yas/registered-snippet`` properly initialized. +* Make variable ``yas-registered-snippet`` properly initialized. * Fixed the overlay error when overlay becomes empty (`Issue 49 `_ and `Issue 48 @@ -145,8 +145,8 @@ ChangeLog 0.5.6 / 2008-08-07 ================== -* Added a buffer local variable ``yas/dont-activate`` to turn off - ``yas/minor-mode`` in some major modes. See `Issue 29 +* Added a buffer local variable ``yas-dont-activate`` to turn off + ``yas-minor-mode`` in some major modes. See `Issue 29 `_. * Make the environment of elisp evaluation more friendly to ``(current-column)``. @@ -157,7 +157,7 @@ ChangeLog 0.5.5 / 2008-05-29 ================== -* Tweak ``yas/extra-mode-hooks`` so that it can be more easily +* Tweak ``yas-extra-mode-hooks`` so that it can be more easily customized. * Add an entry in FAQ about why ``TAB`` key doesn't work in some modes. @@ -166,7 +166,7 @@ ChangeLog ================== * Added ``ox-mode-hook`` and ``python-mode-hook`` to - ``yas/extra-mode-hooks`` to fix the problem YASnippet is not enabled + ``yas-extra-mode-hooks`` to fix the problem YASnippet is not enabled in those modes. 0.5.3 / 2008-05-07 @@ -192,9 +192,9 @@ ChangeLog 0.5.0 / 2008-04-10 ================== -* Integrate with hippie-expand. Just add ``yas/hippie-try-expand`` to +* Integrate with hippie-expand. Just add ``yas-hippie-try-expand`` to ``hippie-expand-try-functions-list``. -* If you set ``yas/fall-back-behavior`` to ``'return-nil``, YASnippet +* If you set ``yas-fall-back-behavior`` to ``'return-nil``, YASnippet will return nil when it can't find a snippet to expand. * Defect fix: the condition of a snippet was evaluated twice in earlier version. @@ -220,7 +220,7 @@ ChangeLog 0.4.3 / 2008-03-23 ================== -* Bug fix: failed to recognize user customized yas/trigger-key. +* Bug fix: failed to recognize user customized yas-trigger-key. 0.4.2 / 2008-03-22 ================== @@ -231,7 +231,7 @@ ChangeLog 0.4.1 / 2008-03-21 ================== -* Make sure ``yas/minor-mode``'s key bindings always take priority to +* Make sure ``yas-minor-mode``'s key bindings always take priority to other minor modes. 0.4.0 / 2008-03-20 @@ -243,7 +243,7 @@ ChangeLog * Incorporate ``dropdown-list.el`` and make it default way for selecting multiple candidates. Thanks to `Jaeyoun Chung `_. -* yas/before-expand-snippet-hook +* yas-before-expand-snippet-hook 0.3.2 / 2008-03-19 ================== @@ -262,7 +262,7 @@ ChangeLog 0.3.0 / 2008-03-16 ================== -* Add a ``yas/after-exit-snippet-hook`` so that you can do something like +* Add a ``yas-after-exit-snippet-hook`` so that you can do something like ``indent-region`` or ``fill-region`` after finish the snippet. * Use minor-mode instead of ``global-set-key`` to bind the trigger key. Now the trigger key and fall-back behavior can be more diff --git a/doc/faq.rst b/doc/faq.rst index 6eec677..93db686 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -18,22 +18,22 @@ 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 +``M-x yas-minor-mode`` to manually turn on the minor mode and try to expand the snippet again. If it works, then, you can add the following code to your ``.emacs`` *before* loading YASnippet: .. sourcecode:: lisp - (add-hook 'the-major-mode-hook 'yas/minor-mode-on) + (add-hook 'the-major-mode-hook 'yas-minor-mode-on) -where ``the-major-mode`` is the major mode in which ``yas/minor-mode`` +where ``the-major-mode`` is the major mode in which ``yas-minor-mode`` isn't enabled by default. From YASnippet 0.6 you can also use the command ``M-x -yas/global-mode`` to turn on YASnippet automatically for *all* major +yas-global-mode`` to turn on YASnippet automatically for *all* major modes. -If ``yas/minor-mode`` is on but the snippet still not expanded. Then +If ``yas-minor-mode`` is on but the snippet still not expanded. Then try to see what command is bound to the ``TAB`` key: press ``C-h k`` and then press ``TAB``. Emacs will show you the result. @@ -41,7 +41,7 @@ You'll see a buffer prompted by Emacs saying that ``TAB runs the command ...``. Alternatively, you might see `` runs the command ...``, note the difference between ``TAB`` and ```` where the latter has priority. If you see ```` bound to a command other -than ``yas/expand``, (e.g. in ``org-mode``) you can try the following +than ``yas-expand``, (e.g. in ``org-mode``) you can try the following code to work around: .. sourcecode:: lisp @@ -49,9 +49,9 @@ code to work around: (add-hook 'org-mode-hook (let ((original-command (lookup-key org-mode-map [tab]))) `(lambda () - (setq yas/fallback-behavior + (setq yas-fallback-behavior '(apply ,original-command)) - (local-set-key [tab] 'yas/expand)))) + (local-set-key [tab] 'yas-expand)))) replace ``org-mode-hook`` and ``org-mode-map`` with the major mode hook you are dealing with (Use ``C-h m`` to see what major mode you @@ -61,23 +61,23 @@ As an alternative, you can also try .. sourcecode:: lisp - (defun yas/advise-indent-function (function-symbol) - (eval `(defadvice ,function-symbol (around yas/try-expand-first activate) + (defun yas-advise-indent-function (function-symbol) + (eval `(defadvice ,function-symbol (around yas-try-expand-first activate) ,(format "Try to expand a snippet before point, then call `%s' as usual" function-symbol) - (let ((yas/fallback-behavior nil)) + (let ((yas-fallback-behavior nil)) (unless (and (interactive-p) - (yas/expand)) + (yas-expand)) ad-do-it))))) - (yas/advise-indent-function 'ruby-indent-line) + (yas-advise-indent-function 'ruby-indent-line) To *advise* the modes indentation function bound to TAB, (in this case -``ruby-indent-line``) to first try to run ``yas/expand``. +``ruby-indent-line``) to first try to run ``yas-expand``. If the output of ``C-h k RET `` tells you that ```` is -indeed bound to ``yas/expand`` but YASnippet still doesn't work, check +indeed bound to ``yas-expand`` but YASnippet still doesn't work, check your configuration and you may also ask for help on the `discussion group `_. See this particular `thread @@ -96,8 +96,8 @@ A workaround is to inhibit flyspell overlays while the snippet is active: (add-hook 'flyspell-incorrect-hook #'(lambda (dummy1 dummy2 dymmy3) - (and yas/active-field-overlay - (overlay-buffer yas/active-field-overlay)))) + (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 @@ -110,18 +110,18 @@ How do I turn off the minor mode where in some buffers ====================================================== The best way, since version 0.6.1c, is to set the default value of the -variable ``yas/dont-activate`` to a lambda function like so: +variable ``yas-dont-activate`` to a lambda function like so: .. sourcecode:: lisp - (set-default 'yas/dont-activate + (set-default 'yas-dont-activate #'(lambda () - (and yas/root-directory - (null (yas/get-snippet-tables))))) + (and yas-root-directory + (null (yas-get-snippet-tables))))) This is also the default value starting for that version. It skips the minor mode in buffers where it is not applicable (no snippet tables), -but only once you have setup your yas/root-directory. +but only once you have setup your yas-root-directory. How do I define an abbrev key containing characters not supported by the filesystem? diff --git a/doc/index.rst b/doc/index.rst index 7415186..a04367c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -78,8 +78,8 @@ the latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named (add-to-list 'load-path "~/.emacs.d/plugins/yasnippet-x.y.z") (require 'yasnippet) ;; not yasnippet-bundle - (yas/initialize) - (yas/load-directory "~/.emacs.d/plugins/yasnippet-x.y.z/snippets") + (yas-initialize) + (yas-load-directory "~/.emacs.d/plugins/yasnippet-x.y.z/snippets") Please refer to the documentation for full customization, or use the customization group. diff --git a/doc/snippet-development.rst b/doc/snippet-development.rst index bb3c7a5..8197371 100644 --- a/doc/snippet-development.rst +++ b/doc/snippet-development.rst @@ -17,23 +17,23 @@ Quickly finding snippets There are some ways you can quickly find a snippet file: -* ``M-x yas/new-snippet`` +* ``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. -* ``M-x yas/find-snippets`` +* ``M-x yas-find-snippets`` Lets you find the snippet file in the directory the snippet was loaded from (if it exists) like ``find-file-other-window``. The - directory searching logic is similar to ``M-x yas/new-snippet``. + directory searching logic is similar to ``M-x yas-new-snippet``. -* ``M-x yas/visit-snippet-file`` +* ``M-x yas-visit-snippet-file`` Prompts you for possible snippet expansions like - ``yas/insert-snippet``, but instead of expanding it, takes you + ``yas-insert-snippet``, but instead of expanding it, takes you directly to the snippet definition's file, if it exists. Once you find this file it will be set to ``snippet-mode`` (see ahead) @@ -49,13 +49,13 @@ reasonably useful syntax highlighting. Two commands are defined in this mode: -* ``M-x yas/load-snippet-buffer`` +* ``M-x yas-load-snippet-buffer`` 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``. -* ``M-x yas/tryout-snippet`` +* ``M-x yas-tryout-snippet`` When editing a snippet, this opens a new empty buffer, sets it to the appropriate major mode and inserts the snippet there, so you @@ -92,7 +92,7 @@ Here's a list of currently supported directives: -------------------------- This is the probably the most important directive, it's the abbreviation you -type to expand a snippet just before hitting ``yas/trigger-key``. If you don't +type to expand a snippet just before hitting ``yas-trigger-key``. If you don't specify this the snippet will not be expandable through the key mechanism. ``# name:`` snippet name @@ -111,7 +111,7 @@ 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 non-nil value. -See also ``yas/buffer-local-condition`` in `Expanding snippets`_ +See also ``yas-buffer-local-condition`` in `Expanding snippets`_ ``# group:`` snippet menu grouping @@ -141,18 +141,18 @@ This is another piece of Emacs-lisp code in the form of a ``let`` can be used to override variable values while the snippet is being expanded. -Interesting variables to override are ``yas/wrap-around-region`` and -``yas/indent-line`` (see `Expanding Snippets`_). +Interesting variables to override are ``yas-wrap-around-region`` and +``yas-indent-line`` (see `Expanding Snippets`_). -As an example, you might normally have ``yas/indent-line`` set to -``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this +As an example, you might normally have ``yas-indent-line`` set to +``'auto`` and ``yas-wrap-around-region`` set to ``t``, but for this particularly brilliant piece of ASCII art these values would mess up your hard work. You can then use: .. sourcecode:: text # name: ASCII home - # expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil)) + # expand-env: ((yas-indent-line 'fixed) (yas-wrap-around-region 'nil)) # -- welcome to my X humble @@ -173,7 +173,7 @@ Emacs keybinding. The keybinding will be registered in the Emacs keymap named after the major mode the snippet is active for. -Additionally a variable ``yas/prefix`` is set to to the prefix +Additionally a variable ``yas-prefix`` is set to to the prefix argument you normally use for a command. This allows for small variations on the same snippet, for example in this "html-mode" snippet. @@ -183,7 +183,7 @@ snippet. # name:

...

# binding: C-c C-c C-m # -- -

`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`

+

`(when yas-prefix "\n")`$0`(when yas-prefix "\n")`

This binding will be recorded in the keymap ``html-mode-map``. To expand a paragraph tag newlines, just @@ -231,18 +231,18 @@ dynamically: #endif /* $1 */ From version 0.6, snippets expansions are run with some special -Emacs-lisp variables bound. One of this is ``yas/selected-text``. You +Emacs-lisp variables bound. One of this is ``yas-selected-text``. You can therefore define a snippet like: .. sourcecode:: text for ($1;$2;$3) { - `yas/selected-text`$0 + `yas-selected-text`$0 } to "wrap" the selected region inside your recently inserted snippet. Alternatively, you can also customize the variable -``yas/wrap-around-region`` to ``t`` which will do this automatically. +``yas-wrap-around-region`` to ``t`` which will do this automatically. Tab stop fields --------------- @@ -308,7 +308,7 @@ 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 +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: @@ -375,7 +375,7 @@ distinguish between fields and mirrors. In the following example .. sourcecode:: text - #define "${1:mydefine$(upcase yas/text)}" + #define "${1:mydefine$(upcase yas-text)}" ``mydefine`` gets automatically upcased to ``MYDEFINE`` once you enter the field. As you type text, it gets filtered through the @@ -388,7 +388,7 @@ two ``$``'s instead. .. sourcecode:: text - #define "${1:$$(upcase yas/text)}" + #define "${1:$$(upcase yas-text)}" Please note that as soon as a transformation takes place, it changes the value of the field and sets it its internal modification state to @@ -400,34 +400,34 @@ 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 -``yas/modified-p`` and ``yas/moving-away-p``. Because of this +``yas-modified-p`` and ``yas-moving-away-p``. Because of this feature you can place a transformation in the primary field that lets you select default values for it. -The ``yas/choose-value`` does this work for you. For example: +The ``yas-choose-value`` does this work for you. For example: .. sourcecode:: text -
+
$0
-See the definition of ``yas/choose-value`` to see how it was written +See the definition of ``yas-choose-value`` to see how it was written using the two variables. Here's another use, for LaTeX-mode, which calls reftex-label just as -you enter snippet field 2. This one makes use of ``yas/modified-p`` +you enter snippet field 2. This one makes use of ``yas-modified-p`` directly. .. sourcecode:: text \section{${1:"Titel der Tour"}}% \index{$1}% - \label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont- + \label{{2:"waiting for reftex-label call..."$(unless yas-modified-p (reftex-label nil 'dont- insert))}}% -The function ``yas/verify-value`` has another neat trick, and makes -use of ``yas/moving-away-p``. Try it and see! Also, check out this +The function ``yas-verify-value`` has another neat trick, and makes +use of ``yas-moving-away-p``. Try it and see! Also, check out this `thread `_ @@ -443,7 +443,7 @@ From version 0.6 on, you can also have nested placeholders of the type: This allows you to choose if you want to give this ``div`` an ``id`` attribute. If you tab forward after expanding it will let you change "some_id" to whatever you like. Alternatively, you can just press -``C-d`` (which executes ``yas/skip-and-clear-or-delete-char``) and go +``C-d`` (which executes ``yas-skip-and-clear-or-delete-char``) and go straight to the exit marker. By the way, ``C-d`` will only clear the field if you cursor is at the @@ -453,10 +453,10 @@ performs the normal Emacs ``delete-char`` command. Customizable variables ====================== -``yas/trigger-key`` +``yas-trigger-key`` ------------------- -The key bound to ``yas/expand`` when function ``yas/minor-mode`` is +The key bound to ``yas-expand`` when function ``yas-minor-mode`` is active. Value is a string that is converted to the internal Emacs key @@ -464,7 +464,7 @@ representation using ``read-kbd-macro``. Default value is ``"TAB"``. -``yas/next-field-key`` +``yas-next-field-key`` ---------------------- The key to navigate to next field when a snippet is active. @@ -476,7 +476,7 @@ Can also be a list of keys. Default value is ``"TAB"``. -``yas/prev-field-key`` +``yas-prev-field-key`` ---------------------- The key to navigate to previous field when a snippet is active. @@ -488,7 +488,7 @@ Can also be a list of keys. Default value is ``("" ")"``. -``yas/skip-and-clear-key`` +``yas-skip-and-clear-key`` -------------------------- The key to clear the currently active field. @@ -500,20 +500,20 @@ Can also be a list of keys. Default value is ``"C-d"``. -``yas/good-grace`` +``yas-good-grace`` ------------------ If non-nil, don't raise errors in inline Emacs-lisp evaluation inside snippet definitions. An error string "[yas] error" is returned instead. -``yas/indent-line`` +``yas-indent-line`` ------------------- -The variable ``yas/indent-line`` controls the indenting. It is bound +The variable ``yas-indent-line`` controls the indenting. It is bound to ``'auto`` by default, which causes your snippet to be indented according to the mode of the buffer it was inserted in. -Another variable ``yas/also-auto-indent-first-line``, when non-nil +Another variable ``yas-also-auto-indent-first-line``, when non-nil does exactly that :-). To use the hard-coded indentation in your snippet template, set this @@ -525,7 +525,7 @@ To control indentation on a per-snippet basis, see also the directive For backward compatibility with earlier versions of YASnippet, you can also place a ``$>`` in your snippet, an ``(indent-according-to-mode)`` will be executed there to indent the line. This only takes effect when -``yas/indent-line`` is set to something other than ``'auto``. +``yas-indent-line`` is set to something other than ``'auto``. .. sourcecode:: text @@ -534,38 +534,38 @@ will be executed there to indent the line. This only takes effect when $0$> }$> -``yas/wrap-around-region`` +``yas-wrap-around-region`` -------------------------- If non-nil, YASnippet will try to expand the snippet's exit marker around the currently selected region. When this variable is set to t, -this has the same effect has using the ```yas/selected-text``` inline +this has the same effect has using the ```yas-selected-text``` inline evaluation. Because on most systems starting to type deletes the currently selected region, this works mostly for snippets with direct -keybindings or with the ``yas/insert-snippet`` command. +keybindings or with the ``yas-insert-snippet`` command. However, when the value is of this variable is ``cua`` YASnippet will additionally look-up any recently selected that you deleted by starting typing. This allows you select a region, type a snippet key (deleting -the region), then press ``yas/trigger-key`` to see the deleted region +the region), then press ``yas-trigger-key`` to see the deleted region spring back to life inside your new snippet. -``yas/triggers-in-field`` +``yas-triggers-in-field`` -------------------------- -If non-nil, ``yas/next-field-key`` can trigger stacked expansions, +If non-nil, ``yas-next-field-key`` can trigger stacked expansions, that is a snippet expansion inside another snippet -expansion. Otherwise, ``yas/next-field-key`` just tries to move on to +expansion. Otherwise, ``yas-next-field-key`` just tries to move on to the next field. -``yas/snippet-revival`` +``yas-snippet-revival`` ----------------------- Non-nil means re-activate snippet fields after undo/redo. -``yas/after-exit-snippet-hook`` and ``yas/before-expand-snippet-hook`` +``yas-after-exit-snippet-hook`` and ``yas-before-expand-snippet-hook`` ---------------------------------------------------------------------- These hooks are called, respectively, before the insertion of a diff --git a/doc/snippet-expansion.rst b/doc/snippet-expansion.rst index 8b64807..e6c03ed 100644 --- a/doc/snippet-expansion.rst +++ b/doc/snippet-expansion.rst @@ -16,16 +16,16 @@ Triggering expansion You can use YASnippet to expand snippets in different ways: * By typing an abbrev, the snippet *trigger key*, and then pressing - the key defined in ``yas/trigger-key`` (which defaults to + the key defined in ``yas-trigger-key`` (which defaults to "TAB"). This works in buffers where the minor mode - ``yas/minor-mode`` is active; + ``yas-minor-mode`` is active; -* By invoking the command ``yas/insert-snippet`` (either by typing - ``M-x yas/insert-snippet`` or its keybinding). This does *not* - require ``yas/minor-mode`` to be active. +* By invoking the command ``yas-insert-snippet`` (either by typing + ``M-x yas-insert-snippet`` or its keybinding). This does *not* + require ``yas-minor-mode`` to be active. * By using the keybinding associated with an active snippet. This also - requires ``yas/minor-mode`` to be active; + requires ``yas-minor-mode`` to be active; * By expanding directly from the "YASnippet" menu in the menu-bar @@ -36,10 +36,10 @@ You can use YASnippet to expand snippets in different ways: Trigger key ----------- -When ``yas/minor-mode`` is enabled, the keybinding taken from -``yas/trigger-key`` will take effect. +When ``yas-minor-mode`` is enabled, the keybinding taken from +``yas-trigger-key`` will take effect. -``yas/trigger-key`` invokes ``yas/expand``, which tries to expand a +``yas-trigger-key`` invokes ``yas-expand``, which tries to expand a *snippet abbrev* (also known as *snippet key*) before point. The default key is ``"TAB"``, however, you can freely set it to some @@ -49,37 +49,37 @@ other key. :align: left To enable the YASnippet minor mode in all buffers globally use the -command ``yas/global-mode``. +command ``yas-global-mode``. -When you use ``yas/global-mode`` you can also selectively disable +When you use ``yas-global-mode`` you can also selectively disable YASnippet in some buffers by setting the buffer-local variable -``yas/dont-active`` in the buffer's mode hook. +``yas-dont-active`` in the buffer's mode hook. -Trouble when using or understanding the ``yas/trigger-key`` is easily +Trouble when using or understanding the ``yas-trigger-key`` is easily the most controversial issue in YASsnippet. See the `FAQ `_. Fallback bahaviour ~~~~~~~~~~~~~~~~~~ -``yas/fallback-behaviour`` is a customization variable bound to -``'call-other-command`` by default. If ``yas/expand`` failed to find +``yas-fallback-behaviour`` is a customization variable bound to +``'call-other-command`` by default. If ``yas-expand`` failed to find any suitable snippet to expand, it will disable the minor mode temporarily and find if there's any other command bound the -``yas/trigger-key``. +``yas-trigger-key``. If found, the command will be called. Usually this works very well -- when there's a snippet, expand it, otherwise, call whatever command originally bind to the trigger key. However, you can change this behavior by customizing the -``yas/fallback-behavior`` variable. If you set this variable to +``yas-fallback-behavior`` variable. If you set this variable to ``'return-nil``, it will return ``nil`` instead of trying to call the *original* command when no snippet is found. Insert at point --------------- -The command ``M-x yas/insert-snippet`` lets you insert snippets at +The command ``M-x yas-insert-snippet`` lets you insert snippets at point *for you current major mode*. It prompts you for the snippet key first, and then for a snippet template if more than one template exists for the same key. @@ -90,7 +90,7 @@ applicable snippets for the major mode, prefix this command with ``C-u``. The prompting methods used are again controlled by -``yas/prompt-functions``. +``yas-prompt-functions``. Snippet keybinding ------------------ @@ -108,7 +108,7 @@ Expanding with ``hippie-expand`` ---------------------------------- To integrate with ``hippie-expand``, just put -``yas/hippie-try-expand`` in +``yas-hippie-try-expand`` in ``hippie-expand-try-functions-list``. This probably makes more sense when placed at the top of the list, but it can be put anywhere you prefer. @@ -117,8 +117,8 @@ Expanding from emacs-lisp code ------------------------------ Sometimes you might want to expand a snippet directly from you own -elisp code. You should call ``yas/expand-snippet`` instead of -``yas/expand`` in this case. +elisp code. You should call ``yas-expand-snippet`` instead of +``yas-expand`` in this case. As with expanding from the menubar, the condition system and multiple candidates doesn't affect expansion. In fact, expanding from the @@ -126,9 +126,9 @@ YASnippet menu has the same effect of evaluating the follow code: .. sourcecode:: common-lisp - (yas/expand-snippet template) + (yas-expand-snippet template) -See the internal documentation on ``yas/expand-snippet`` for more +See the internal documentation on ``yas-expand-snippet`` for more information. Controlling expansion @@ -161,7 +161,7 @@ In particular, the following things matter: are also considered. This works recursively, i.e. parents of parents of eligible tables are also considered. -* Buffer-local ``yas/mode-symbol`` variable +* Buffer-local ``yas-mode-symbol`` variable This can be used to consider snippet tables whose name does not correspond to a major mode. If you set this variable to a name , @@ -176,9 +176,9 @@ In particular, the following things matter: ;; snippet table "rails-mode" (add-hook 'rinari-minor-mode-hook #'(lambda () - (setq yas/mode-symbol 'rails-mode))) + (setq yas-mode-symbol 'rails-mode))) -* Buffer-local ``yas/buffer-local-condition`` variable +* Buffer-local ``yas-buffer-local-condition`` variable This variable provides finer grained control over what snippets can be expanded in the current buffer. The default value won't let you @@ -189,7 +189,7 @@ The condition system -------------------- Consider this scenario: you are an old Emacs hacker. You like the -abbrev-way and set ``yas/trigger-key`` to ``"SPC"``. However, +abbrev-way and set ``yas-trigger-key`` to ``"SPC"``. However, you don't want ``if`` to be expanded as a snippet when you are typing in a comment block or a string (e.g. in ``python-mode``). @@ -198,14 +198,14 @@ you could just specify the condition for ``if`` to be ``(not (python-in-string/comment))``. But how about ``while``, ``for``, etc. ? Writing the same condition for all the snippets is just boring. So has a buffer local variable -``yas/buffer-local-condition``. You can set this variable to ``(not +``yas-buffer-local-condition``. You can set this variable to ``(not (python-in-string/comment))`` in ``python-mode-hook``. Then, what if you really want some particular snippet to expand even inside a comment? This is also possible! But let's stop telling the story and look at the rules: -* If ``yas/buffer-local-condition`` evaluate to nil, no snippets will +* If ``yas-buffer-local-condition`` evaluate to nil, no snippets will be considered for expansion. * If it evaluates to the a *cons cell* where the ``car`` is the symbol @@ -238,14 +238,14 @@ story and look at the rules: * Otherwise, it won't be considered. -In the mentioned scenario, set ``yas/buffer-local-condition`` like +In the mentioned scenario, set ``yas-buffer-local-condition`` like this .. sourcecode:: common-lisp (add-hook 'python-mode-hook '(lambda () - (setq yas/buffer-local-condition + (setq yas-buffer-local-condition '(if (python-in-string/comment) '(require-snippet-condition . force-in-comment) t)))) @@ -263,16 +263,16 @@ one snippet to be expanded at point. When there are multiple candidates, YASnippet will let you select one. The UI for selecting multiple candidate can be customized through -``yas/prompt-functions`` , which defines your preferred methods of +``yas-prompt-functions`` , which defines your preferred methods of being prompted for snippets. You can customize it with ``M-x customize-variable RET -yas/prompt-functions RET``. Alternatively you can put in your +yas-prompt-functions RET``. Alternatively you can put in your emacs-file: .. sourcecode:: common-lisp - (setq yas/prompt-functions '(yas/x-prompt yas/dropdown-prompt)) + (setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt)) Currently there are some alternatives solution with YASnippet. @@ -282,7 +282,7 @@ Currently there are some alternatives solution with YASnippet. Use the X window system ~~~~~~~~~~~~~~~~~~~~~~~ -The function ``yas/x-prompt`` can be used to show a popup menu for you +The function ``yas-x-prompt`` can be used to show a popup menu for you to select. This menu will be part of you native window system widget, which means: @@ -298,8 +298,8 @@ which means: Minibuffer prompting ~~~~~~~~~~~~~~~~~~~~ -You can use functions ``yas/completing-prompt`` for the classic emacs -completion method or ``yas/ido-prompt`` for a much nicer looking +You can use functions ``yas-completing-prompt`` for the classic emacs +completion method or ``yas-ido-prompt`` for a much nicer looking method. The best way is to try it. This works in a terminal. .. image:: images/dropdown-menu.png @@ -308,8 +308,8 @@ method. The best way is to try it. This works in a terminal. Use ``dropdown-menu.el`` ~~~~~~~~~~~~~~~~~~~~~~~~ -The function ``yas/dropdown-prompt`` can also be placed in the -``yas/prompt-functions`` list. +The function ``yas-dropdown-prompt`` can also be placed in the +``yas-prompt-functions`` list. This works in both window system and terminal and is customizable, you can use ``C-n``, ``C-p`` to navigate, ``q`` to quit and even press @@ -318,15 +318,15 @@ can use ``C-n``, ``C-p`` to navigate, ``q`` to quit and even press Roll your own ~~~~~~~~~~~~~ -See below for the documentation on variable ``yas/prompt-functions`` +See below for the documentation on variable ``yas-prompt-functions`` Customizable Variables ====================== -``yas/prompt-functions`` +``yas-prompt-functions`` ------------------------ -You can write a function and add it to the ``yas/prompt-functions`` +You can write a function and add it to the ``yas-prompt-functions`` list. These functions are called with the following arguments: * PROMPT: A string to prompt the user; @@ -346,13 +346,13 @@ that is passed). * To signal that the user quit the prompting process, you can signal ``quit`` with ``(signal 'quit "user quit!")`` -``yas/fallback-behavior`` +``yas-fallback-behavior`` ------------------------- -How to act when ``yas/expand`` does *not* expand a snippet. +How to act when ``yas-expand`` does *not* expand a snippet. ``call-other-command`` means try to temporarily disable YASnippet and - call the next command bound to ``yas/trigger-key``. + call the next command bound to ``yas-trigger-key``. ``return-nil`` means return nil. (i.e. do nothing) @@ -360,16 +360,16 @@ An entry (apply COMMAND . ARGS) means interactively call COMMAND, if ARGS is non-nil, call COMMAND non-interactively with ARGS as arguments. -``yas/choose-keys-first`` +``yas-choose-keys-first`` ------------------------- If non-nil, prompt for snippet key first, then for template. Otherwise prompts for all possible snippet names. -This affects ``yas/insert-snippet`` and ``yas/visit-snippet-file``. +This affects ``yas-insert-snippet`` and ``yas-visit-snippet-file``. -``yas/choose-tables-first`` +``yas-choose-tables-first`` --------------------------- If non-nil, and multiple eligible snippet tables, prompts user for @@ -378,9 +378,9 @@ tables first. Otherwise, user chooses between the merging together of all eligible tables. -This affects ``yas/insert-snippet``, ``yas/visit-snippet-file`` +This affects ``yas-insert-snippet``, ``yas-visit-snippet-file`` -``yas/key-syntaxes`` +``yas-key-syntaxes`` -------------------- The default searching strategy is quite powerful. For example, in @@ -391,7 +391,7 @@ then that snippet is expanded and replaces the ``bar``. Snippets pointed to by ``foo_bar`` and ``"#foobar`` won't be considered. However, this strategy can also be customized easily from the -``yas/key-syntaxes`` variable. It is a list of syntax rules, the +``yas-key-syntaxes`` variable. It is a list of syntax rules, the default value is ``("w" "w_" "w_." "^ ")``. Which means search the following thing until found one: diff --git a/doc/snippet-menu.rst b/doc/snippet-menu.rst index a40c5a8..7a6b0e5 100644 --- a/doc/snippet-menu.rst +++ b/doc/snippet-menu.rst @@ -4,7 +4,7 @@ YASnippet menu .. contents:: -When ``yas/minor-mode`` is active, YASnippet will setup a menu just +When ``yas-minor-mode`` is active, YASnippet will setup a menu just after the "Buffers" menu in the menubar. In this menu, you can find @@ -26,11 +26,11 @@ Loading snippets from menu -------------------------- Invoking "Load snippets..." from the menu invokes -``yas/load-directory`` and prompts you for a snippet directory +``yas-load-directory`` and prompts you for a snippet directory hierarchy to load. Also useful is the "Reload all" options which uncondionally reloads -all the snippets directories defined in ``yas/root-directory`` and +all the snippets directories defined in ``yas-root-directory`` and rebuilds the menus. Snippet menu behavior @@ -43,16 +43,16 @@ You can use this section to explore currently loaded snippets. If you click on one of them, the default behavior is to expand it, unconditionally, inside the current buffer. -You can however, customize variable ``yas/visit-from-menu`` to be +You can however, customize variable ``yas-visit-from-menu`` to be ``t`` which will take you to the snippet definition file when you select it from the menu. If you want the menu show only snippet tables whose name corresponds -to a "real" major mode. You do this by setting ``yas/use-menu`` to +to a "real" major mode. You do this by setting ``yas-use-menu`` to ``'real-modes``. Finally, to have the menu show only the tables for the currently -active mode, set ``yas/use-menu`` to ``abbreviate``. +active mode, set ``yas-use-menu`` to ``abbreviate``. These customizations can also be found in the menu itself, under the "Snippet menu behavior" submenu. @@ -62,14 +62,14 @@ Controlling indenting --------------------- The "Indenting" submenu contains options to control the values of -``yas/indent-line`` and ``yas/also-auto-indent-first-line``. See +``yas-indent-line`` and ``yas-also-auto-indent-first-line``. See `Writing snippets `_ . Prompting method ---------------- The "Prompting method" submenu contains options to control the value -of ``yas/prompt-functions``. See `Expanding snippets `_ . +of ``yas-prompt-functions``. See `Expanding snippets `_ . Misc ---- diff --git a/doc/snippet-organization.rst b/doc/snippet-organization.rst index bed3acb..64d3bf3 100644 --- a/doc/snippet-organization.rst +++ b/doc/snippet-organization.rst @@ -24,20 +24,20 @@ directory of snippets, which you can copy somewhere and use. You can also create or download more directories. Once these directories are in place reference them in the variable -``yas/root-directory`` and load them with ``yas/load-directory``: +``yas-root-directory`` and load them with ``yas-load-directory``: .. sourcecode:: common-lisp ;; Develop and keep personal snippets under ~/emacs.d/mysnippets - (setq yas/root-directory "~/emacs.d/mysnippets") + (setq yas-root-directory "~/emacs.d/mysnippets") ;; Load the snippets - (yas/load-directory yas/root-directory) + (yas-load-directory yas-root-directory) -The point in using ``yas/root-directory`` (as opposed to calling -``yas/load-directory`` directly) is considering "~/emacs.d/mysnippets" +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 `Writing +``yas-new-snippet`` and others described in section `Writing Snippets`_. You can make this variable a list and store more items into it: @@ -46,11 +46,11 @@ You can make this variable a list and store more items into it: ;; Develop in ~/emacs.d/mysnippets, but also ;; try out snippets in ~/Downloads/interesting-snippets - (setq yas/root-directory '("~/emacs.d/mysnippets" + (setq yas-root-directory '("~/emacs.d/mysnippets" "~/Downloads/interesting-snippets")) - ;; Map `yas/load-directory' to every element - (mapc 'yas/load-directory yas/root-directory) + ;; Map `yas-load-directory' to every element + (mapc 'yas-load-directory yas-root-directory) In this last example, the all the directories are loaded and their snippets considered for expansion. However development still happens @@ -59,7 +59,7 @@ in the first element, "~/emacs.d/mysnippets". Organizing snippets =================== -Once you've setup ``yas/root-directory`` , you can store snippets +Once you've setup ``yas-root-directory`` , you can store snippets inside sub-directories of these directories. Snippet definitions are put in plain text files. They are arranged @@ -132,18 +132,18 @@ YASnippet bundle 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. +``yas-load-directory`` to load them. 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. You can use ``yas-define-snippets`` to define a bunch of snippets for a particular mode in an Emacs-lisp file. 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 +snippets in directory and then call ``M-x yas-compile-bundle`` to compile it into a bundle file when you modified your snippets. The release bundle of YASnippet is produced by -``yas/compile-bundle``. The bundle uses ``yas/define-snippets`` to +``yas-compile-bundle``. The bundle uses ``yas-define-snippets`` to define snippets. This avoids the IO and parsing overhead when loading snippets. @@ -153,13 +153,13 @@ generated this way. 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``. +* ``M-x describe-function RET yas-define-snippets RET`` +* ``M-x describe-function RET yas-compile-bundle RET``. Customizable variables ====================== -``yas/root-directory`` +``yas-root-directory`` ---------------------- Root directory that stores the snippets for each major mode. @@ -168,9 +168,9 @@ 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-reload-all`` -``yas/ignore-filenames-as-triggers`` +``yas-ignore-filenames-as-triggers`` ------------------------------------ If non-nil, don't derive tab triggers from filenames.