Function: add-variable-watcher

add-variable-watcher is a function defined in data.c.

Signature

(add-variable-watcher SYMBOL WATCH-FUNCTION)

Documentation

Cause WATCH-FUNCTION to be called when SYMBOL is about to be set.

It will be called with 4 arguments: (SYMBOL NEWVAL OPERATION WHERE). SYMBOL is the variable being changed. NEWVAL is the value it will be changed to. (The variable still has the old value when WATCH-FUNCTION is called.) OPERATION is a symbol representing the kind of change, one of: set, let, unlet, makunbound, and defvaralias. WHERE is a buffer if the buffer-local value of the variable is being changed, nil otherwise.

All writes to aliases of SYMBOL will call WATCH-FUNCTION too.

View in manual

Probably introduced at or before Emacs version 26.1.

Source Code

// Defined in /usr/src/emacs/src/data.c
{
  symbol = Findirect_variable (symbol);
  CHECK_SYMBOL (symbol);
  set_symbol_trapped_write (symbol, SYMBOL_TRAPPED_WRITE);
  map_obarray (Vobarray, harmonize_variable_watchers, symbol);

  Lisp_Object watchers = Fget (symbol, Qwatchers);
  Lisp_Object member = Fmember (watch_function, watchers);
  if (NILP (member))
    Fput (symbol, Qwatchers, Fcons (watch_function, watchers));
  return Qnil;
}