Editing Emacs Lisp (section)

==Example==

The development of Emacs Lisp was guided by the goal of providing data structures and features specific to making a versatile text editor over implementing a general-purpose programming language. For example, Emacs Lisp cannot easily read a file a line at a time—the entire file must be read into an Emacs buffer. However, Emacs Lisp provides many features for navigating and modifying buffer text at a sentence, paragraph, or higher syntactic level as defined by modes.

Here follows a simple example of an Emacs extension written in Emacs Lisp.  In Emacs, the editing area can be split into separate areas called ''windows'', each displaying a different ''buffer''. A buffer is a region of text loaded into Emacs' memory (possibly from a file) which can be saved into a text document.

Users can press the default <kbd>C-x 2</kbd> [[key binding]] to open a new window. This runs the Emacs Lisp function <code>split-window-below</code>. Normally, when the new window appears, it displays the same buffer as the previous one. Suppose we wish to make it display the next available buffer. In order to do this, the user writes the following Emacs Lisp code, in either an existing Emacs Lisp source file or an empty Emacs buffer:

<syntaxhighlight lang="emacs">
(defun my-split-window-func ()
  (interactive)
  (split-window-below)
  (set-window-buffer (next-window) (other-buffer)))

(global-set-key (kbd "C-x 2") #'my-split-window-func)
</syntaxhighlight>

The first statement, <code>(defun ...)</code>, defines a new function, <code>my-split-window-func</code>, which calls <code>split-window-below</code> (the old window-splitting function), then tells the new window to display another (new) buffer. The second statement, <code>(global-set-key ...)</code> re-binds the key sequence "C-x 2" to the new function.

This can also be written using the feature called ''[[Advice (programming)#Use|advice]]'', which allows the user to create [[wrapper (programming)|wrappers]] around existing functions instead of defining their own.  This has the advantage of not requiring keybindings to be changed and working wherever the original function is called, as well as being simpler to write but the disadvantage of making debugging more complicated.  For this reason, ''advice'' is not allowed in the source code of GNU Emacs,<ref name="autogenerated1">{{cite web|url=https://lists.gnu.org/archive/html/emacs-devel/2012-12/msg00146.html |title=Re: [Emacs-diffs&#93; /srv/bzr/emacs/trunk r111086: gmm-utils.el (gmm-flet |publisher=Lists.gnu.org |date=2012-12-05 |access-date=2013-08-18}}</ref> but if a user wishes, the advice feature can be used in their code to reimplement the above code as follows:

<syntaxhighlight lang="emacs">
(defadvice split-window-below
  (after my-window-splitting-advice first () activate)
  (set-window-buffer (next-window) (other-buffer)))
</syntaxhighlight>

This instructs <code>split-window-below</code> to execute the user-supplied code whenever it is called, after executing the rest of the function. Advice can also be specified to execute before the original function, around it (literally wrapping the original), or to conditionally execute the original function based on the results of the advice.

Emacs 24.4 replaces<ref>{{cite web|url=https://www.gnu.org/software/emacs/news/NEWS.24.4|title=NEWS.24.4}}</ref> this <code>defadvice</code> mechanism with <code>advice-add</code>, which is claimed to be more flexible and simpler.<ref>{{cite web|url=https://www.gnu.org/software/emacs/manual/html_node/elisp/Porting-Old-Advice.html#Porting-Old-Advice|title=Porting old advice}}</ref> The advice above could be reimplemented using the new system as:

<syntaxhighlight lang="emacs>
(defun switch-to-next-window-in-split ()
  (set-window-buffer (next-window) (other-buffer)))

(advice-add 'split-window-below :before #'switch-to-next-window-in-split)
</syntaxhighlight>

These changes take effect as soon as the code is [[eval#Lisp|evaluated]]. It is not necessary to recompile, restart Emacs, or even [[rehash]] a configuration file. If the code is saved into an Emacs init file, then Emacs will load the extension the next time it starts. Otherwise, the changes must be reevaluated manually when Emacs is restarted.