Mercurial > hg > xemacs-beta

comparison src/symbols.c @ 4940:9113c5044de8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
(for main branch) add long comment about types of magic symbols -------------------- ChangeLog entries follow: -------------------- src/ChangeLog addition: 2010-01-20 Ben Wing <ben@xemacs.org> * symbols.c: Add long comment about the types of magic symbols, and the various declarations that go along with them.
author Ben Wing <ben@xemacs.org>
date Wed, 20 Jan 2010 22:30:33 -0600
parents 8b50bee3c88c
children 19a72041c5ed
comparison
equal deleted inserted replaced
4939:349f01075eb7 4940:9113c5044de8
1 /* "intern" and friends -- moved here from lread.c and data.c 1 /* "intern" and friends -- moved here from lread.c and data.c
2 Copyright (C) 1985-1989, 1992-1994 Free Software Foundation, Inc. 2 Copyright (C) 1985-1989, 1992-1994 Free Software Foundation, Inc.
3 Copyright (C) 1995, 2000, 2001, 2002 Ben Wing. 3 Copyright (C) 1995, 2000, 2001, 2002, 2010 Ben Wing.
4 4
5 This file is part of XEmacs. 5 This file is part of XEmacs.
6 6
7 XEmacs is free software; you can redistribute it and/or modify it 7 XEmacs is free software; you can redistribute it and/or modify it
8 under the terms of the GNU General Public License as published by the 8 under the terms of the GNU General Public License as published by the
771 771
772 772
773 /**********************************************************************/ 773 /**********************************************************************/
774 /* symbol-value */ 774 /* symbol-value */
775 /**********************************************************************/ 775 /**********************************************************************/
776
777 /*
778 NOTE NOTE NOTE:
779 ---------------
780
781 There are various different uses of "magic" with regard to symbols,
782 and they need to be distinguished:
783
784 1. `symbol-value-magic' class of objects (struct symbol_value_magic):
785 A set of Lisp object types used as the value of a variable with any
786 behavior other than just a plain repository of a value. This
787 includes buffer-local variables, console-local variables, read-only
788 variables, variable aliases, variables that are linked to a C
789 variable, etc. The more specific types are:
790
791 -- `symbol-value-forward': Variables that forward to a C variable.
792 NOTE:This includes built-in buffer-local and console-local
793 variables, since they forward to an element in a buffer or
794 console structure.
795
796 -- `symbol-value-buffer-local': Variables on which
797 `make-local-variable' or `make-variable-buffer-local' have
798 been called.
799
800 -- `symbol-value-lisp-magic': See below.
801
802 -- `symbol-value-varalias': Variable aliases.
803
804 2. `symbol-value-lisp-magic': Variables on which
805 `dontusethis-set-symbol-value-handler' have been called. These
806 variables are extra-magic in that operations that would normally
807 change their value instead get forwarded out to Lisp handlers,
808 which can do anything they want. (NOTE: Handlers for getting a
809 variable's value aren't implemented yet.)
810
811 3. "magicfun" handlers on C-forwarding variables, declared with any
812 of the following:
813
814 -- DEFVAR_LISP_MAGIC
815 -- DEFVAR_INT_MAGIC
816 -- DEFVAR_BOOL_MAGIC,
817 -- DEFVAR_BUFFER_LOCAL_MAGIC
818 -- DEFVAR_BUFFER_DEFAULTS_MAGIC
819 -- DEFVAR_CONSOLE_LOCAL_MAGIC
820 -- DEFVAR_CONSOLE_DEFAULTS_MAGIC
821
822 Here, the "magic function" is a handler that is notified whenever the
823 value of a variable is changed, so that some other updating can take
824 place (e.g. setting redisplay-related dirty bits, updating a cache,
825 etc.).
826
827 Note that DEFVAR_LISP_MAGIC does *NOT* have anything to do with
828 `symbol-value-lisp-magic'. The former refers to variables that can
829 hold an arbitrary Lisp object and forward to a C variable declared
830 `Lisp_Object foo', and have a "magicfun" as just described; the
831 latter are variables that have Lisp-level handlers that function
832 in *PLACE* of normal variable-setting mechanisms, and are established
833 with `dontusethis-set-symbol-value-handler', as described above.
834 */
776 835
777 /* If the contents of the value cell of a symbol is one of the following 836 /* If the contents of the value cell of a symbol is one of the following
778 three types of objects, then the symbol is "magic" in that setting 837 three types of objects, then the symbol is "magic" in that setting
779 and retrieving its value doesn't just set or retrieve the raw 838 and retrieving its value doesn't just set or retrieve the raw
780 contents of the value cell. None of these objects can escape to 839 contents of the value cell. None of these objects can escape to