new repository

1 files changed, 14 insertions, 0 deletions

diff --git a/devdocs/elisp/watching-variables.html b/devdocs/elisp/watching-variables.html
new file mode 100644
index 00000000..f9ae5e0d
--- /dev/null
+++ b/devdocs/elisp/watching-variables.html
@@ -0,0 +1,14 @@
+ <h3 class="section">Running a function when a variable is changed.</h3>   <p>It is sometimes useful to take some action when a variable changes its value. The <em>variable watchpoint</em> facility provides the means to do so. Some possible uses for this feature include keeping display in sync with variable settings, and invoking the debugger to track down unexpected changes to variables (see <a href="variable-debugging">Variable Debugging</a>). </p> <p>The following functions may be used to manipulate and query the watch functions for a variable. </p> <dl> <dt id="add-variable-watcher">Function: <strong>add-variable-watcher</strong> <em>symbol watch-function</em>
+</dt> <dd>
+<p>This function arranges for <var>watch-function</var> to be called whenever <var>symbol</var> is modified. Modifications through aliases (see <a href="variable-aliases">Variable Aliases</a>) will have the same effect. </p> <p><var>watch-function</var> will be called, just before changing the value of <var>symbol</var>, with 4 arguments: <var>symbol</var>, <var>newval</var>, <var>operation</var>, and <var>where</var>. <var>symbol</var> is the variable being changed. <var>newval</var> is the value it will be changed to. (The old value is available to <var>watch-function</var> as the value of <var>symbol</var>, since it was not yet changed to <var>newval</var>.) <var>operation</var> is a symbol representing the kind of change, one of: <code>set</code>, <code>let</code>, <code>unlet</code>, <code>makunbound</code>, or <code>defvaralias</code>. <var>where</var> is a buffer if the buffer-local value of the variable is being changed, <code>nil</code> otherwise. </p>
+</dd>
+</dl> <dl> <dt id="remove-variable-watcher">Function: <strong>remove-variable-watcher</strong> <em>symbol watch-function</em>
+</dt> <dd><p>This function removes <var>watch-function</var> from <var>symbol</var>’s list of watchers. </p></dd>
+</dl> <dl> <dt id="get-variable-watchers">Function: <strong>get-variable-watchers</strong> <em>symbol</em>
+</dt> <dd><p>This function returns the list of <var>symbol</var>’s active watcher functions. </p></dd>
+</dl> <h4 class="subsection">Limitations</h4> <p>There are a couple of ways in which a variable could be modified (or at least appear to be modified) without triggering a watchpoint. </p> <p>Since watchpoints are attached to symbols, modification to the objects contained within variables (e.g., by a list modification function see <a href="modifying-lists">Modifying Lists</a>) is not caught by this mechanism. </p> <p>Additionally, C code can modify the value of variables directly, bypassing the watchpoint mechanism. </p> <p>A minor limitation of this feature, again because it targets symbols, is that only variables of dynamic scope may be watched. This poses little difficulty, since modifications to lexical variables can be discovered easily by inspecting the code within the scope of the variable (unlike dynamic variables, which can be modified by any code at all, see <a href="variable-scoping">Variable Scoping</a>). </p><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/Watching-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Watching-Variables.html</a>
+  </p>
+</div>