new repository

1 files changed, 46 insertions, 0 deletions

diff --git a/devdocs/elisp/advice-combinators.html b/devdocs/elisp/advice-combinators.html
new file mode 100644
index 00000000..260edfeb
--- /dev/null
+++ b/devdocs/elisp/advice-combinators.html
@@ -0,0 +1,46 @@
+ <h4 class="subsection">Ways to compose advice</h4> <p>Here are the different possible values for the <var>where</var> argument of <code>add-function</code> and <code>advice-add</code>, specifying how the advice <var>function</var> and the original function should be composed. </p> <dl compact> <dt><code>:before</code></dt> <dd>
+<p>Call <var>function</var> before the old function. Both functions receive the same arguments, and the return value of the composition is the return value of the old function. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (apply <var>function</var> r) (apply <var>oldfun</var> r))
+</pre>
+</div> <p><code>(add-function :before <var>funvar</var> <var>function</var>)</code> is comparable for single-function hooks to <code>(add-hook '<var>hookvar</var> <var>function</var>)</code> for normal hooks. </p> </dd> <dt><code>:after</code></dt> <dd>
+<p>Call <var>function</var> after the old function. Both functions receive the same arguments, and the return value of the composition is the return value of the old function. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (prog1 (apply <var>oldfun</var> r) (apply <var>function</var> r)))
+</pre>
+</div> <p><code>(add-function :after <var>funvar</var> <var>function</var>)</code> is comparable for single-function hooks to <code>(add-hook '<var>hookvar</var> <var>function</var>
+'append)</code> for normal hooks. </p> </dd> <dt><code>:override</code></dt> <dd>
+<p>This completely replaces the old function with the new one. The old function can of course be recovered if you later call <code>remove-function</code>. </p> </dd> <dt><code>:around</code></dt> <dd>
+<p>Call <var>function</var> instead of the old function, but provide the old function as an extra argument to <var>function</var>. This is the most flexible composition. For example, it lets you call the old function with different arguments, or many times, or within a let-binding, or you can sometimes delegate the work to the old function and sometimes override it completely. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (apply <var>function</var> <var>oldfun</var> r))
+</pre>
+</div> </dd> <dt><code>:before-while</code></dt> <dd>
+<p>Call <var>function</var> before the old function and don’t call the old function if <var>function</var> returns <code>nil</code>. Both functions receive the same arguments, and the return value of the composition is the return value of the old function. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (and (apply <var>function</var> r) (apply <var>oldfun</var> r)))
+</pre>
+</div> <p><code>(add-function :before-while <var>funvar</var> <var>function</var>)</code> is comparable for single-function hooks to <code>(add-hook '<var>hookvar</var> <var>function</var>)</code> when <var>hookvar</var> is run via <code>run-hook-with-args-until-failure</code>. </p> </dd> <dt><code>:before-until</code></dt> <dd>
+<p>Call <var>function</var> before the old function and only call the old function if <var>function</var> returns <code>nil</code>. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (or (apply <var>function</var> r) (apply <var>oldfun</var> r)))
+</pre>
+</div> <p><code>(add-function :before-until <var>funvar</var> <var>function</var>)</code> is comparable for single-function hooks to <code>(add-hook '<var>hookvar</var> <var>function</var>)</code> when <var>hookvar</var> is run via <code>run-hook-with-args-until-success</code>. </p> </dd> <dt><code>:after-while</code></dt> <dd>
+<p>Call <var>function</var> after the old function and only if the old function returned non-<code>nil</code>. Both functions receive the same arguments, and the return value of the composition is the return value of <var>function</var>. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (and (apply <var>oldfun</var> r) (apply <var>function</var> r)))
+</pre>
+</div> <p><code>(add-function :after-while <var>funvar</var> <var>function</var>)</code> is comparable for single-function hooks to <code>(add-hook '<var>hookvar</var> <var>function</var>
+'append)</code> when <var>hookvar</var> is run via <code>run-hook-with-args-until-failure</code>. </p> </dd> <dt><code>:after-until</code></dt> <dd>
+<p>Call <var>function</var> after the old function and only if the old function returned <code>nil</code>. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (or  (apply <var>oldfun</var> r) (apply <var>function</var> r)))
+</pre>
+</div> <p><code>(add-function :after-until <var>funvar</var> <var>function</var>)</code> is comparable for single-function hooks to <code>(add-hook '<var>hookvar</var> <var>function</var>
+'append)</code> when <var>hookvar</var> is run via <code>run-hook-with-args-until-success</code>. </p> </dd> <dt><code>:filter-args</code></dt> <dd>
+<p>Call <var>function</var> first and use the result (which should be a list) as the new arguments to pass to the old function. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (apply <var>oldfun</var> (funcall <var>function</var> r)))
+</pre>
+</div> </dd> <dt><code>:filter-return</code></dt> <dd>
+<p>Call the old function first and pass the result to <var>function</var>. More specifically, the composition of the two functions behaves like: </p>
+<div class="example"> <pre class="example">(lambda (&amp;rest r) (funcall <var>function</var> (apply <var>oldfun</var> r)))
+</pre>
+</div> </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/Advice-Combinators.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Advice-Combinators.html</a>
+  </p>
+</div>