1 /* Generic specifier list implementation
2 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
3 Copyright (C) 1995 Ben Wing
5 This file is part of XEmacs.
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
9 Free Software Foundation; either version 2, or (at your option) any
12 XEmacs is distributed in the hope that it will be useful, but WITHOUT
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 You should have received a copy of the GNU General Public License
18 along with XEmacs; see the file COPYING. If not, write to
19 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 Boston, MA 02111-1307, USA. */
22 /* Synched up with: Not in FSF. */
24 #ifndef INCLUDED_specifier_h_
25 #define INCLUDED_specifier_h_
31 Magic specifiers are used to provide fallback values for window
32 system provided specifications, reflecting user preferences on the
33 window system, such as default fonts, colors, scrollbar thickness
36 A magic specifier consists of two specifier objects. The first one
37 behaves like a normal specifier in all senses. The second one, a
38 ghost specifier, is a fallback value for the first one, and contains
39 values provided by window system, resources etc. which reflect
40 default settings for values being specified.
42 A magic specifier has an "ultimate" fallback value, as any usual
43 specifier does. This value, an inst-list, is stored in the fallback
44 slot of the ghost specifier object.
46 Ghost specifiers have the following properties:
47 - Have back pointers to their parent specifiers.
48 - Do not have instance data. Instead, they share parent's instance
50 - Have the same methods structure pointer.
51 - Share parent's caching scheme.
52 - Store fallback value instead of their parents.
54 Ghost specifiers normally are not modifiable at the lisp level, and
55 only used to supply fallback instance values. They are accessible
56 via (specifier-fallback), but are read-only. Although, under
57 certain rare conditions, modification of ghost objects is allowed.
58 This behavior is controlled by the global variable
59 Vunlock_ghost_specifiers. It is not exposed to lisp, and is set
60 during calls to lisp functions which initialize global, device and
61 frame defaults, such as
62 init-{global,frame,device}-{faces,toolbars,etc}.
64 Thus, values supplied by resources or other means of a window system
65 stored in externally unmodifiable ghost objects. Regular lisp code
66 may thus freely modify the normal part of a magic specifier, and
67 removing a specification for a particular domain causes the
68 specification to consider ghost-provided fallback values, or its own
71 Rules of conduct for magic specifiers
72 -------------------------------------
73 1. recompute_*() functions always operate on the whole specifier
74 when passed only a ghost object, by substituting it with their
76 2. All specifier methods, except for instantiate method, are passed
77 the bodily object of the magic specifier. Instantiate method is
78 passed the specifier being instantiated.
79 3. Only bodily objects are passed to set_specifier_caching function,
80 and only these may be cached.
81 4. All specifiers are added to Vall_specifiers list, both bodily and
82 ghost. The pair of objects is always removed from the list at the
86 extern const struct struct_description specifier_methods_description;
88 struct specifier_methods
91 Lisp_Object predicate_symbol;
93 /* Implementation specific methods: */
95 /* Create method: Initialize specifier data. Optional. */
96 void (*create_method) (Lisp_Object specifier);
98 /* Mark method: Mark any lisp object within specifier data
99 structure. Not required if no specifier data are Lisp_Objects. */
100 void (*mark_method) (Lisp_Object specifier);
102 /* Equal method: Compare two specifiers. This is called after
103 ensuring that the two specifiers are of the same type, and have
104 the same specs. Quit is inhibited during the call so it is safe
105 to call internal_equal().
107 If this function is not present, specifiers considered equal when
108 the above conditions are met, i.e. as if the method returned
110 int (*equal_method) (Lisp_Object sp1, Lisp_Object sp2, int depth);
112 /* Hash method: Hash specifier instance data. This has to hash only
113 data structure of the specifier, as specs are hashed by the core
116 If this function is not present, hashing behaves as if it
118 unsigned long (*hash_method) (Lisp_Object specifier, int depth);
120 /* Validate method: Given an instantiator, verify that it's
121 valid for this specifier type. If not, signal an error.
123 If this function is not present, all instantiators are considered
125 void (*validate_method) (Lisp_Object instantiator);
128 /* Copy method: Given an instantiator, copy the bits that we need to
129 for this specifier type.
131 If this function is not present, then Fcopy_tree is used. */
132 Lisp_Object (*copy_instantiator_method) (Lisp_Object instantiator);
134 /* Validate-matchspec method: Given a matchspec, verify that it's
135 valid for this specifier type. If not, signal an error.
137 If this function is not present, *no* matchspecs are considered
138 valid. Note that this differs from validate_method(). */
139 void (*validate_matchspec_method) (Lisp_Object matchspec);
141 /* Instantiate method: Return SPECIFIER instance in DOMAIN,
142 specified by INSTANTIATOR. MATCHSPEC specifies an additional
143 constraints on the instance value (see the docstring for
144 Fspecifier_matching_instance function). MATCHSPEC is passed
145 Qunbound when no matching constraints are imposed. The method is
146 called via call_with_suspended_errors(), so allowed to eval
149 DEPTH is a lisp integer denoting current depth of instantiation
150 calls. This parameter should be passed as the initial depth value
151 to functions which also instantiate specifiers (of which I can
152 name specifier_instance) to avoid creating "external"
155 This method must presume that both INSTANTIATOR and MATCHSPEC are
156 already validated by the corresponding validate_* methods, and
157 may abort if they are invalid.
159 Return value is an instance, which is returned immediately to the
160 caller, or Qunbound to continue instantiation lookup chain.
162 If this function is not present, INSTANTIATOR is used as the
163 specifier instance. This is the usual case for "simple"
164 specifiers, like integer and boolean. */
165 Lisp_Object (*instantiate_method) (Lisp_Object specifier,
166 Lisp_Object matchspec,
168 Lisp_Object instantiator,
171 /* Going-to-add method: Called when an instantiator is about
172 to be added to a specifier. This function can specify
173 that different instantiators should be used instead by
174 returning an inst-list (possibly containing zero elements).
175 If the instantiator is fine as-is, return Qt. The
176 instantiator has been copied with copy-tree, so feel
177 free to reuse parts of it to create a new instantiator.
178 The tag-set, however, is not copied and is not canonicalized
179 (that will be done on the result of this function). */
180 Lisp_Object (*going_to_add_method) (Lisp_Object specifier,
183 Lisp_Object instantiator);
185 /* After-change method: Called when the SPECIFIER has just been
186 changed in LOCALE. The method is called upon:
187 * Removing and adding specs to/from the specifier;
188 * Changing the specifier fallback.
190 #### The method may have called more than once per each specifier
193 #### Do not still know if this can safely eval. */
194 void (*after_change_method) (Lisp_Object specifier,
197 const struct lrecord_description *extra_description;
201 struct Lisp_Specifier
203 struct lcrecord_header header;
204 struct specifier_methods *methods;
206 /* we keep a chained list of all current specifiers, for GC cleanup
207 purposes. Do NOT mark through this, or specifiers will never
209 Lisp_Object next_specifier;
211 /* This is a straight list of instantiators. */
212 Lisp_Object global_specs;
214 /* These are all assoc lists where the key is the type of object the
215 list represents (buffer, window, etc.) and the associated list is
216 the actual list of instantiators. */
217 Lisp_Object device_specs;
218 Lisp_Object frame_specs;
219 /* window_specs is actually a key-assoc weak list. See specifier.c
220 for an explanation of why (it boils down to the fact that
221 dead windows can become live again through window configurations).
223 Lisp_Object window_specs;
224 Lisp_Object buffer_specs;
226 struct specifier_caching *caching;
228 /* This can be either nil, for a plain, non-magic specifier object,
229 t for the normal part of the magic specifier, or #<specifier> for
230 the ghost part of the magic specifier, a pointer to its parent
232 Lisp_Object magic_parent;
234 /* Fallback value. For magic specifiers, it is a pointer to the ghost. */
235 Lisp_Object fallback;
237 /* type-specific extra data attached to a specifier */
240 typedef struct Lisp_Specifier Lisp_Specifier;
242 DECLARE_LRECORD (specifier, Lisp_Specifier);
243 #define XSPECIFIER(x) XRECORD (x, specifier, Lisp_Specifier)
244 #define XSETSPECIFIER(x, p) XSETRECORD (x, p, specifier)
245 #define SPECIFIERP(x) RECORDP (x, specifier)
246 #define CHECK_SPECIFIER(x) CHECK_RECORD (x, specifier)
247 #define CONCHECK_SPECIFIER(x) CONCHECK_RECORD (x, specifier)
249 /***** Calling a specifier method *****/
251 #define RAW_SPECMETH(sp, m) ((sp)->methods->m##_method)
252 #define HAS_SPECMETH_P(sp, m) (!!RAW_SPECMETH (sp, m))
253 #define SPECMETH(sp, m, args) (((sp)->methods->m##_method) args)
255 /* Call a void-returning specifier method, if it exists. */
256 #define MAYBE_SPECMETH(sp, m, args) do { \
257 Lisp_Specifier *maybe_specmeth_sp = (sp); \
258 if (HAS_SPECMETH_P (maybe_specmeth_sp, m)) \
259 SPECMETH (maybe_specmeth_sp, m, args); \
262 /***** Defining new specifier types *****/
264 #define specifier_data_offset (offsetof (Lisp_Specifier, data))
265 extern const struct lrecord_description specifier_empty_extra_description[];
267 #ifdef ERROR_CHECK_TYPECHECK
268 #define DECLARE_SPECIFIER_TYPE(type) \
269 extern struct specifier_methods * type##_specifier_methods; \
270 INLINE_HEADER struct type##_specifier * \
271 error_check_##type##_specifier_data (Lisp_Specifier *sp); \
272 INLINE_HEADER struct type##_specifier * \
273 error_check_##type##_specifier_data (Lisp_Specifier *sp) \
275 if (SPECIFIERP (sp->magic_parent)) \
277 assert (SPECIFIER_TYPE_P (sp, type)); \
278 sp = XSPECIFIER (sp->magic_parent); \
281 assert (NILP (sp->magic_parent) || EQ (sp->magic_parent, Qt)); \
282 assert (SPECIFIER_TYPE_P (sp, type)); \
283 return (struct type##_specifier *) sp->data; \
285 INLINE_HEADER Lisp_Specifier * \
286 error_check_##type##_specifier_type (Lisp_Object obj); \
287 INLINE_HEADER Lisp_Specifier * \
288 error_check_##type##_specifier_type (Lisp_Object obj) \
290 Lisp_Specifier *sp = XSPECIFIER (obj); \
291 assert (SPECIFIER_TYPE_P (sp, type)); \
296 #define DECLARE_SPECIFIER_TYPE(type) \
297 extern struct specifier_methods * type##_specifier_methods
298 #endif /* ERROR_CHECK_TYPECHECK */
300 #define DEFINE_SPECIFIER_TYPE(type) \
301 struct specifier_methods * type##_specifier_methods
303 #define INITIALIZE_SPECIFIER_TYPE(type, obj_name, pred_sym) do { \
304 type##_specifier_methods = xnew_and_zero (struct specifier_methods); \
305 type##_specifier_methods->name = obj_name; \
306 type##_specifier_methods->extra_description = \
307 specifier_empty_extra_description; \
308 defsymbol_nodump (&type##_specifier_methods->predicate_symbol, pred_sym); \
309 add_entry_to_specifier_type_list (Q##type, type##_specifier_methods); \
310 dump_add_root_struct_ptr (&type##_specifier_methods, \
311 &specifier_methods_description); \
314 #define REINITIALIZE_SPECIFIER_TYPE(type) do { \
315 staticpro_nodump (&type##_specifier_methods->predicate_symbol); \
318 #define INITIALIZE_SPECIFIER_TYPE_WITH_DATA(type, obj_name, pred_sym) \
320 INITIALIZE_SPECIFIER_TYPE (type, obj_name, pred_sym); \
321 type##_specifier_methods->extra_data_size = \
322 sizeof (struct type##_specifier); \
323 type##_specifier_methods->extra_description = \
324 type##_specifier_description; \
327 /* Declare that specifier-type TYPE has method METH; used in
328 initialization routines */
329 #define SPECIFIER_HAS_METHOD(type, meth) \
330 (type##_specifier_methods->meth##_method = type##_##meth)
332 /***** Macros for accessing specifier types *****/
334 #define SPECIFIER_TYPE_P(sp, type) \
335 ((sp)->methods == type##_specifier_methods)
337 /* Any of the two of the magic spec */
338 #define MAGIC_SPECIFIER_P(sp) (!NILP((sp)->magic_parent))
339 /* Normal part of the magic specifier */
340 #define BODILY_SPECIFIER_P(sp) EQ ((sp)->magic_parent, Qt)
341 /* Ghost part of the magic specifier */
342 #define GHOST_SPECIFIER_P(sp) SPECIFIERP((sp)->magic_parent)
344 #define GHOST_SPECIFIER(sp) XSPECIFIER ((sp)->fallback)
346 #ifdef ERROR_CHECK_TYPECHECK
347 # define SPECIFIER_TYPE_DATA(sp, type) \
348 error_check_##type##_specifier_data (sp)
350 # define SPECIFIER_TYPE_DATA(sp, type) \
351 ((struct type##_specifier *) \
352 (GHOST_SPECIFIER_P(sp) \
353 ? XSPECIFIER((sp)->magic_parent)->data \
357 #ifdef ERROR_CHECK_TYPECHECK
358 # define XSPECIFIER_TYPE(x, type) \
359 error_check_##type##_specifier_type (x)
360 # define XSETSPECIFIER_TYPE(x, p, type) do \
362 XSETSPECIFIER (x, p); \
363 assert (SPECIFIER_TYPEP (XSPECIFIER(x), type)); \
366 # define XSPECIFIER_TYPE(x, type) XSPECIFIER (x)
367 # define XSETSPECIFIER_TYPE(x, p, type) XSETSPECIFIER (x, p)
368 #endif /* ERROR_CHECK_TYPE_CHECK */
370 #define SPECIFIER_TYPEP(x, type) \
371 (SPECIFIERP (x) && SPECIFIER_TYPE_P (XSPECIFIER (x), type))
372 #define CHECK_SPECIFIER_TYPE(x, type) do { \
373 CHECK_SPECIFIER (x); \
374 if (!SPECIFIER_TYPE_P (XSPECIFIER (x), type)) \
375 dead_wrong_type_argument \
376 (type##_specifier_methods->predicate_symbol, x); \
378 #define CONCHECK_SPECIFIER_TYPE(x, type) do { \
379 CONCHECK_SPECIFIER (x); \
380 if (!(SPECIFIER_TYPEP (x, type))) \
381 x = wrong_type_argument \
382 (type##_specifier_methods->predicate_symbol, x); \
385 /***** Miscellaneous structures *****/
387 enum spec_locale_type
400 SPEC_REMOVE_TAG_SET_PREPEND,
401 SPEC_REMOVE_TAG_SET_APPEND,
403 SPEC_REMOVE_LOCALE_TYPE,
407 struct specifier_caching
409 int offset_into_struct_window;
410 void (*value_changed_in_window) (Lisp_Object specifier, struct window *w,
412 int offset_into_struct_frame;
413 void (*value_changed_in_frame) (Lisp_Object specifier, struct frame *f,
415 int always_recompute;
418 /* #### get image instances out of domains! */
420 /* #### I think the following should abort() rather than return nil
421 when an invalid domain is given; much more likely we'll catch design
422 errors early. --ben */
424 /* This turns out to be used heavily so we make it a macro to make it
425 inline. Also, the majority of the time the object will turn out to
426 be a window so we move it from being checked last to being checked
428 #define DOMAIN_DEVICE(obj) \
429 (WINDOWP (obj) ? WINDOW_DEVICE (XWINDOW (obj)) \
430 : (FRAMEP (obj) ? FRAME_DEVICE (XFRAME (obj)) \
431 : (DEVICEP (obj) ? obj \
432 : (IMAGE_INSTANCEP (obj) ? image_instance_device (obj) \
435 #define DOMAIN_FRAME(obj) \
436 (WINDOWP (obj) ? WINDOW_FRAME (XWINDOW (obj)) \
437 : (FRAMEP (obj) ? obj \
438 : (IMAGE_INSTANCEP (obj) ? image_instance_frame (obj) \
441 #define DOMAIN_WINDOW(obj) \
442 (WINDOWP (obj) ? obj \
443 : (IMAGE_INSTANCEP (obj) ? image_instance_window (obj) \
446 #define DOMAIN_LIVE_P(obj) \
447 (WINDOWP (obj) ? WINDOW_LIVE_P (XWINDOW (obj)) \
448 : (FRAMEP (obj) ? FRAME_LIVE_P (XFRAME (obj)) \
449 : (DEVICEP (obj) ? DEVICE_LIVE_P (XDEVICE (obj)) \
450 : (IMAGE_INSTANCEP (obj) ? image_instance_live_p (obj) \
453 #define DOMAIN_XDEVICE(obj) \
454 (XDEVICE (DOMAIN_DEVICE (obj)))
455 #define DOMAIN_XFRAME(obj) \
456 (XFRAME (DOMAIN_FRAME (obj)))
457 #define DOMAIN_XWINDOW(obj) \
458 (XWINDOW (DOMAIN_WINDOW (obj)))
460 EXFUN (Fcopy_specifier, 6);
461 EXFUN (Fmake_specifier, 1);
462 EXFUN (Fset_specifier_dirty_flag, 1);
463 EXFUN (Fspecifier_instance, 4);
464 EXFUN (Fvalid_specifier_locale_p, 1);
466 extern Lisp_Object Qfallback, Qnatnum;
468 Lisp_Object make_magic_specifier (Lisp_Object type);
469 Lisp_Object decode_locale_list (Lisp_Object locale);
470 extern enum spec_add_meth
471 decode_how_to_add_specification (Lisp_Object how_to_add);
472 Lisp_Object decode_specifier_tag_set (Lisp_Object tag_set);
473 Lisp_Object decode_domain (Lisp_Object domain);
475 void add_entry_to_specifier_type_list (Lisp_Object symbol,
476 struct specifier_methods *meths);
477 void set_specifier_caching (Lisp_Object specifier,
478 int struct_window_offset,
479 void (*value_changed_in_window)
480 (Lisp_Object specifier, struct window *w,
482 int struct_frame_offset,
483 void (*value_changed_in_frame)
484 (Lisp_Object specifier, struct frame *f,
486 int always_recompute);
487 void set_specifier_fallback (Lisp_Object specifier,
488 Lisp_Object fallback);
489 void recompute_all_cached_specifiers_in_window (struct window *w);
490 void recompute_all_cached_specifiers_in_frame (struct frame *f);
492 /* Counterparts of Fadd_spec_to_specifier and Fremove_specifier, which
493 operate directly on ghost objects given a magic specifier. */
494 void add_spec_to_ghost_specifier (Lisp_Object specifier, Lisp_Object instantiator,
495 Lisp_Object locale, Lisp_Object tag_set,
496 Lisp_Object how_to_add);
497 void remove_ghost_specifier (Lisp_Object specifier, Lisp_Object locale,
498 Lisp_Object tag_set, Lisp_Object exact_p);
500 int unlock_ghost_specifiers_protected (void);
502 void cleanup_specifiers (void);
503 void prune_specifiers (void);
504 void setup_device_initial_specifier_tags (struct device *d);
505 void kill_specifier_buffer_locals (Lisp_Object buffer);
507 DECLARE_SPECIFIER_TYPE (generic);
508 #define XGENERIC_SPECIFIER(x) XSPECIFIER_TYPE (x, generic)
509 #define XSETGENERIC_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, generic)
510 #define GENERIC_SPECIFIERP(x) SPECIFIER_TYPEP (x, generic)
511 #define CHECK_GENERIC_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, generic)
512 #define CONCHECK_GENERIC_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, generic)
514 DECLARE_SPECIFIER_TYPE (integer);
515 #define XINTEGER_SPECIFIER(x) XSPECIFIER_TYPE (x, integer)
516 #define XSETINTEGER_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, integer)
517 #define INTEGER_SPECIFIERP(x) SPECIFIER_TYPEP (x, integer)
518 #define CHECK_INTEGER_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, integer)
519 #define CONCHECK_INTEGER_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, integer)
521 DECLARE_SPECIFIER_TYPE (natnum);
522 #define XNATNUM_SPECIFIER(x) XSPECIFIER_TYPE (x, natnum)
523 #define XSETNATNUM_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, natnum)
524 #define NATNUM_SPECIFIERP(x) SPECIFIER_TYPEP (x, natnum)
525 #define CHECK_NATNUM_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, natnum)
526 #define CONCHECK_NATNUM_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, natnum)
528 DECLARE_SPECIFIER_TYPE (boolean);
529 #define XBOOLEAN_SPECIFIER(x) XSPECIFIER_TYPE (x, boolean)
530 #define XSETBOOLEAN_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, boolean)
531 #define BOOLEAN_SPECIFIERP(x) SPECIFIER_TYPEP (x, boolean)
532 #define CHECK_BOOLEAN_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, boolean)
533 #define CONCHECK_BOOLEAN_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, boolean)
535 DECLARE_SPECIFIER_TYPE (display_table);
536 #define XDISPLAYTABLE_SPECIFIER(x) XSPECIFIER_TYPE (x, display_table)
537 #define XSETDISPLAYTABLE_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, display_table)
538 #define DISPLAYTABLE_SPECIFIERP(x) SPECIFIER_TYPEP (x, display_table)
539 #define CHECK_DISPLAYTABLE_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, display_table)
540 #define CONCHECK_DISPLAYTABLE_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, display_table)
542 #endif /* INCLUDED_specifier_h_ */