path: root/devdocs/elisp/setting-hooks.html

 <h4 class="subsection">Setting Hooks</h4> <p>Here’s an example that adds a function to a mode hook to turn on Auto Fill mode when in Lisp Interaction mode: </p> <div class="example"> <pre class="example">(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
</pre>
</div> <p>The value of a hook variable should be a list of functions. You can manipulate that list using the normal Lisp facilities, but the modular way is to use the functions <code>add-hook</code> and <code>remove-hook</code>, defined below. They take care to handle some unusual situations and avoid problems. </p> <p>It works to put a <code>lambda</code>-expression function on a hook, but we recommend avoiding this because it can lead to confusion. If you add the same <code>lambda</code>-expression a second time but write it slightly differently, you will get two equivalent but distinct functions on the hook. If you then remove one of them, the other will still be on it. </p> <dl> <dt id="add-hook">Function: <strong>add-hook</strong> <em>hook function &amp;optional depth local</em>
</dt> <dd>
<p>This function is the handy way to add function <var>function</var> to hook variable <var>hook</var>. You can use it for abnormal hooks as well as for normal hooks. <var>function</var> can be any Lisp function that can accept the proper number of arguments for <var>hook</var>. For example, </p> <div class="example"> <pre class="example">(add-hook 'text-mode-hook 'my-text-hook-function)
</pre>
</div> <p>adds <code>my-text-hook-function</code> to the hook called <code>text-mode-hook</code>. </p> <p>If <var>function</var> is already present in <var>hook</var> (comparing using <code>equal</code>), then <code>add-hook</code> does not add it a second time. </p> <p>If <var>function</var> has a non-<code>nil</code> property <code>permanent-local-hook</code>, then <code>kill-all-local-variables</code> (or changing major modes) won’t delete it from the hook variable’s local value. </p> <p>For a normal hook, hook functions should be designed so that the order in which they are executed does not matter. Any dependence on the order is asking for trouble. However, the order is predictable: normally, <var>function</var> goes at the front of the hook list, so it is executed first (barring another <code>add-hook</code> call). </p> <p>In some cases, it is important to control the relative ordering of functions on the hook. The optional argument <var>depth</var> lets you indicate where the function should be inserted in the list: it should then be a number between -100 and 100 where the higher the value, the closer to the end of the list the function should go. The <var>depth</var> defaults to 0 and for backward compatibility when <var>depth</var> is a non-nil symbol it is interpreted as a depth of 90. Furthermore, when <var>depth</var> is strictly greater than 0 the function is added <em>after</em> rather than before functions of the same depth. One should never use a depth of 100 (or -100), because one can never be sure that no other function will ever need to come before (or after) us. </p> <p><code>add-hook</code> can handle the cases where <var>hook</var> is void or its value is a single function; it sets or changes the value to a list of functions. </p> <p>If <var>local</var> is non-<code>nil</code>, that says to add <var>function</var> to the buffer-local hook list instead of to the global hook list. This makes the hook buffer-local and adds <code>t</code> to the buffer-local value. The latter acts as a flag to run the hook functions in the default value as well as in the local value. </p>
</dd>
</dl> <dl> <dt id="remove-hook">Function: <strong>remove-hook</strong> <em>hook function &amp;optional local</em>
</dt> <dd>
<p>This function removes <var>function</var> from the hook variable <var>hook</var>. It compares <var>function</var> with elements of <var>hook</var> using <code>equal</code>, so it works for both symbols and lambda expressions. </p> <p>If <var>local</var> is non-<code>nil</code>, that says to remove <var>function</var> from the buffer-local hook list instead of from the global hook list. </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Setting-Hooks.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Setting-Hooks.html</a>
  </p>
</div>