Mercurial > hg > xemacs-beta

comparison src/specifier.h @ 428:3ecd8885ac67 r21-2-22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-22
author cvs
date Mon, 13 Aug 2007 11:28:15 +0200
parents
children 9d177e8d4150
comparison
equal deleted inserted replaced
427:0a0253eac470 428:3ecd8885ac67
1 /* Generic specifier list implementation
2 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
3 Copyright (C) 1995 Ben Wing
4
5 This file is part of XEmacs.
6
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
10 later version.
11
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
15 for more details.
16
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. */
21
22 /* Synched up with: Not in FSF. */
23
24 #ifndef _XEMACS_SPECIFIER_H_
25 #define _XEMACS_SPECIFIER_H_
26
27 /*
28 MAGIC SPECIFIERS
29 ================
30
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
34 etc.
35
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.
41
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.
45
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
49 data.
50 - Have the same methods structure pointer.
51 - Share parent's caching scheme.
52 - Store fallback value instead of their parents.
53
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}.
63
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
69 fallback value.
70
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
75 parent bodily object.
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
83 same time.
84 */
85
86 extern const struct struct_description specifier_methods_description;
87
88 struct specifier_methods
89 {
90 CONST char *name;
91 Lisp_Object predicate_symbol;
92
93 /* Implementation specific methods: */
94
95 /* Create method: Initialize specifier data. Optional. */
96 void (*create_method) (Lisp_Object specifier);
97
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);
101
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().
106
107 If this function is not present, specifiers considered equal when
108 the above conditions are met, i.e. as if the method returned
109 non-zero. */
110 int (*equal_method) (Lisp_Object sp1, Lisp_Object sp2, int depth);
111
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
114 code.
115
116 If this function is not present, hashing behaves as if it
117 returned zero. */
118 unsigned long (*hash_method) (Lisp_Object specifier, int depth);
119
120 /* Validate method: Given an instantiator, verify that it's
121 valid for this specifier type. If not, signal an error.
122
123 If this function is not present, all instantiators are considered
124 valid. */
125 void (*validate_method) (Lisp_Object instantiator);
126
127 /* Validate-matchspec method: Given a matchspec, verify that it's
128 valid for this specifier type. If not, signal an error.
129
130 If this function is not present, *no* matchspecs are considered
131 valid. Note that this differs from validate_method(). */
132 void (*validate_matchspec_method) (Lisp_Object matchspec);
133
134 /* Instantiate method: Return SPECIFIER instance in DOMAIN,
135 specified by INSTANTIATOR. MATCHSPEC specifies an additional
136 constraints on the instance value (see the docstring for
137 Fspecifier_matching_instance function). MATCHSPEC is passed
138 Qunbound when no matching constraints are imposed. The method is
139 called via call_with_suspended_errors(), so allowed to eval
140 safely.
141
142 DEPTH is a lisp integer denoting current depth of instantiation
143 calls. This parameter should be passed as the initial depth value
144 to functions which also instantiate specifiers (of which I can
145 name specifier_instance) to avoid creating "external"
146 specification loops.
147
148 This method must presume that both INSTANTIATOR and MATCSPEC are
149 already validated by the corresponding validate_* methods, and
150 may abort if they are invalid.
151
152 Return value is an instance, which is returned immediately to the
153 caller, or Qunbound to continue instantiation lookup chain.
154
155 If this function is not present, INSTANTIATOR is used as the
156 specifier instance. This is the usual case for "simple"
157 specifiers, like integer and boolean. */
158 Lisp_Object (*instantiate_method) (Lisp_Object specifier,
159 Lisp_Object matchspec,
160 Lisp_Object domain,
161 Lisp_Object instantiator,
162 Lisp_Object depth);
163
164 /* Going-to-add method: Called when an instantiator is about
165 to be added to a specifier. This function can specify
166 that different instantiators should be used instead by
167 returning an inst-list (possibly containing zero elements).
168 If the instantiator is fine as-is, return Qt. The
169 instantiator has been copied with copy-tree, so feel
170 free to reuse parts of it to create a new instantiator.
171 The tag-set, however, is not copied and is not canonicalized
172 (that will be done on the result of this function). */
173 Lisp_Object (*going_to_add_method) (Lisp_Object specifier,
174 Lisp_Object locale,
175 Lisp_Object tag_set,
176 Lisp_Object instantiator);
177
178 /* After-change method: Called when the SPECIFIER has just been
179 changed in LOCALE. The method is called upon:
180 * Removing and adding specs to/from the specifier;
181 * Changing the specifier fallback.
182
183 #### The method may have called more than once per each specifier
184 change.
185
186 #### Do not still know if this can safely eval. */
187 void (*after_change_method) (Lisp_Object specifier,
188 Lisp_Object locale);
189
190 const struct lrecord_description *extra_description;
191 int extra_data_size;
192 };
193
194 struct Lisp_Specifier
195 {
196 struct lcrecord_header header;
197 struct specifier_methods *methods;
198
199 /* we keep a chained list of all current specifiers, for GC cleanup
200 purposes. Do NOT mark through this, or specifiers will never
201 be GC'd. */
202 Lisp_Object next_specifier;
203
204 /* This is a straight list of instantiators. */
205 Lisp_Object global_specs;
206
207 /* These are all assoc lists where the key is the type of object the
208 list represents (buffer, window, etc.) and the associated list is
209 the actual list of instantiators. */
210 Lisp_Object device_specs;
211 Lisp_Object frame_specs;
212 /* window_specs is actually a key-assoc weak list. See specifier.c
213 for an explanation of why (it boils down to the fact that
214 dead windows can become live again through window configurations).
215 */
216 Lisp_Object window_specs;
217 Lisp_Object buffer_specs;
218
219 struct specifier_caching *caching;
220
221 /* This can be either nil, for a plain, non-magic specifier object,
222 t for the normal part of the magic specifier, or #<specifier> for
223 the ghost part of the magic specifier, a pointer to its parent
224 object */
225 Lisp_Object magic_parent;
226
227 /* Fallback value. For magic specifiers, it is a pointer to the ghost. */
228 Lisp_Object fallback;
229
230 /* type-specific extra data attached to a specifier */
231 char data[1];
232 };
233
234 DECLARE_LRECORD (specifier, struct Lisp_Specifier);
235 #define XSPECIFIER(x) XRECORD (x, specifier, struct Lisp_Specifier)
236 #define XSETSPECIFIER(x, p) XSETRECORD (x, p, specifier)
237 #define SPECIFIERP(x) RECORDP (x, specifier)
238 #define CHECK_SPECIFIER(x) CHECK_RECORD (x, specifier)
239 #define CONCHECK_SPECIFIER(x) CONCHECK_RECORD (x, specifier)
240
241 /***** Calling a specifier method *****/
242
243 #define RAW_SPECMETH(sp, m) ((sp)->methods->m##_method)
244 #define HAS_SPECMETH_P(sp, m) (!!RAW_SPECMETH (sp, m))
245 #define SPECMETH(sp, m, args) (((sp)->methods->m##_method) args)
246
247 /* Call a void-returning specifier method, if it exists. */
248 #define MAYBE_SPECMETH(sp, m, args) do { \
249 struct Lisp_Specifier *maybe_specmeth_sp = (sp); \
250 if (HAS_SPECMETH_P (maybe_specmeth_sp, m)) \
251 SPECMETH (maybe_specmeth_sp, m, args); \
252 } while (0)
253
254 /***** Defining new specifier types *****/
255
256 #define specifier_data_offset (offsetof(struct Lisp_Specifier, data))
257 extern const struct lrecord_description specifier_empty_extra_description[];
258
259 #ifdef ERROR_CHECK_TYPECHECK
260 #define DECLARE_SPECIFIER_TYPE(type) \
261 extern struct specifier_methods * type##_specifier_methods; \
262 INLINE struct type##_specifier * \
263 error_check_##type##_specifier_data (struct Lisp_Specifier *sp); \
264 INLINE struct type##_specifier * \
265 error_check_##type##_specifier_data (struct Lisp_Specifier *sp) \
266 { \
267 if (SPECIFIERP (sp->magic_parent)) \
268 { \
269 assert (SPECIFIER_TYPE_P (sp, type)); \
270 sp = XSPECIFIER (sp->magic_parent); \
271 } \
272 else \
273 assert (NILP (sp->magic_parent) || EQ (sp->magic_parent, Qt)); \
274 assert (SPECIFIER_TYPE_P (sp, type)); \
275 return (struct type##_specifier *) sp->data; \
276 } \
277 DECLARE_NOTHING
278 #else
279 #define DECLARE_SPECIFIER_TYPE(type) \
280 extern struct specifier_methods * type##_specifier_methods
281 #endif /* ERROR_CHECK_TYPECHECK */
282
283 #define DEFINE_SPECIFIER_TYPE(type) \
284 struct specifier_methods * type##_specifier_methods
285
286 #define INITIALIZE_SPECIFIER_TYPE(type, obj_name, pred_sym) do { \
287 type##_specifier_methods = xnew_and_zero (struct specifier_methods); \
288 type##_specifier_methods->name = obj_name; \
289 type##_specifier_methods->extra_description = \
290 specifier_empty_extra_description; \
291 defsymbol_nodump (&type##_specifier_methods->predicate_symbol, pred_sym); \
292 add_entry_to_specifier_type_list (Q##type, type##_specifier_methods); \
293 dumpstruct (&type##_specifier_methods, &specifier_methods_description); \
294 } while (0)
295
296 #define REINITIALIZE_SPECIFIER_TYPE(type) do { \
297 staticpro_nodump (&type##_specifier_methods->predicate_symbol); \
298 } while (0)
299
300 #define INITIALIZE_SPECIFIER_TYPE_WITH_DATA(type, obj_name, pred_sym) \
301 do { \
302 INITIALIZE_SPECIFIER_TYPE (type, obj_name, pred_sym); \
303 type##_specifier_methods->extra_data_size = \
304 sizeof (struct type##_specifier); \
305 type##_specifier_methods->extra_description = \
306 type##_specifier_description; \
307 } while (0)
308
309 /* Declare that specifier-type TYPE has method METH; used in
310 initialization routines */
311 #define SPECIFIER_HAS_METHOD(type, meth) \
312 (type##_specifier_methods->meth##_method = type##_##meth)
313
314 /***** Macros for accessing specifier types *****/
315
316 #define SPECIFIER_TYPE_P(sp, type) \
317 ((sp)->methods == type##_specifier_methods)
318
319 /* Any of the two of the magic spec */
320 #define MAGIC_SPECIFIER_P(sp) (!NILP((sp)->magic_parent))
321 /* Normal part of the magic specifier */
322 #define BODILY_SPECIFIER_P(sp) EQ ((sp)->magic_parent, Qt)
323 /* Ghost part of the magic specifier */
324 #define GHOST_SPECIFIER_P(sp) SPECIFIERP((sp)->magic_parent)
325
326 #define GHOST_SPECIFIER(sp) XSPECIFIER ((sp)->fallback)
327
328 #ifdef ERROR_CHECK_TYPECHECK
329 # define SPECIFIER_TYPE_DATA(sp, type) \
330 error_check_##type##_specifier_data (sp)
331 #else
332 # define SPECIFIER_TYPE_DATA(sp, type) \
333 ((struct type##_specifier *) \
334 (GHOST_SPECIFIER_P(sp) \
335 ? XSPECIFIER((sp)->magic_parent)->data \
336 : (sp)->data))
337 #endif
338
339 /* #### Need to create ERROR_CHECKING versions of these. */
340
341 #define XSPECIFIER_TYPE(x, type) XSPECIFIER (x)
342 #define XSETSPECIFIER_TYPE(x, p, type) XSETSPECIFIER (x, p)
343 #define SPECIFIER_TYPEP(x, type) \
344 (SPECIFIERP (x) && SPECIFIER_TYPE_P (XSPECIFIER (x), type))
345 #define CHECK_SPECIFIER_TYPE(x, type) do { \
346 CHECK_SPECIFIER (x); \
347 if (!SPECIFIER_TYPE_P (XSPECIFIER (x), type)) \
348 dead_wrong_type_argument \
349 (type##_specifier_methods->predicate_symbol, x); \
350 } while (0)
351 #define CONCHECK_SPECIFIER_TYPE(x, type) do { \
352 CONCHECK_SPECIFIER (x); \
353 if (!(SPECIFIER_TYPEP (x, type))) \
354 x = wrong_type_argument \
355 (type##_specifier_methods->predicate_symbol, x); \
356 } while (0)
357
358 /***** Miscellaneous structures *****/
359
360 enum spec_locale_type
361 {
362 LOCALE_GLOBAL,
363 LOCALE_DEVICE,
364 LOCALE_FRAME,
365 LOCALE_WINDOW,
366 LOCALE_BUFFER
367 };
368
369 enum spec_add_meth
370 {
371 SPEC_PREPEND,
372 SPEC_APPEND,
373 SPEC_REMOVE_TAG_SET_PREPEND,
374 SPEC_REMOVE_TAG_SET_APPEND,
375 SPEC_REMOVE_LOCALE,
376 SPEC_REMOVE_LOCALE_TYPE,
377 SPEC_REMOVE_ALL
378 };
379
380 struct specifier_caching
381 {
382 int offset_into_struct_window;
383 void (*value_changed_in_window) (Lisp_Object specifier, struct window *w,
384 Lisp_Object oldval);
385 int offset_into_struct_frame;
386 void (*value_changed_in_frame) (Lisp_Object specifier, struct frame *f,
387 Lisp_Object oldval);
388 };
389
390 EXFUN (Fcopy_specifier, 6);
391 EXFUN (Fmake_specifier, 1);
392 EXFUN (Fset_specifier_dirty_flag, 1);
393 EXFUN (Fspecifier_instance, 4);
394 EXFUN (Fvalid_specifier_locale_p, 1);
395
396 extern Lisp_Object Qfallback, Qnatnum;
397
398 Lisp_Object make_magic_specifier (Lisp_Object type);
399 Lisp_Object decode_locale_list (Lisp_Object locale);
400 extern enum spec_add_meth
401 decode_how_to_add_specification (Lisp_Object how_to_add);
402 Lisp_Object decode_specifier_tag_set (Lisp_Object tag_set);
403
404 void add_entry_to_specifier_type_list (Lisp_Object symbol,
405 struct specifier_methods *meths);
406 void set_specifier_caching (Lisp_Object specifier,
407 int struct_window_offset,
408 void (*value_changed_in_window)
409 (Lisp_Object specifier, struct window *w,
410 Lisp_Object oldval),
411 int struct_frame_offset,
412 void (*value_changed_in_frame)
413 (Lisp_Object specifier, struct frame *f,
414 Lisp_Object oldval));
415 void set_specifier_fallback (Lisp_Object specifier,
416 Lisp_Object fallback);
417 void recompute_all_cached_specifiers_in_window (struct window *w);
418 void recompute_all_cached_specifiers_in_frame (struct frame *f);
419
420 /* Counterparts of Fadd_spec_to_specifier and Fremove_specifier, which
421 operate directly on ghost objects given a magic specifier. */
422 void add_spec_to_ghost_specifier (Lisp_Object specifier, Lisp_Object instantiator,
423 Lisp_Object locale, Lisp_Object tag_set,
424 Lisp_Object how_to_add);
425 void remove_ghost_specifier (Lisp_Object specifier, Lisp_Object locale,
426 Lisp_Object tag_set, Lisp_Object exact_p);
427
428 int unlock_ghost_specifiers_protected (void);
429
430 void cleanup_specifiers (void);
431 void prune_specifiers (void);
432 void setup_device_initial_specifier_tags (struct device *d);
433 void kill_specifier_buffer_locals (Lisp_Object buffer);
434
435 DECLARE_SPECIFIER_TYPE (generic);
436 #define XGENERIC_SPECIFIER(x) XSPECIFIER_TYPE (x, generic)
437 #define XSETGENERIC_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, generic)
438 #define GENERIC_SPECIFIERP(x) SPECIFIER_TYPEP (x, generic)
439 #define CHECK_GENERIC_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, generic)
440 #define CONCHECK_GENERIC_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, generic)
441
442 DECLARE_SPECIFIER_TYPE (integer);
443 #define XINTEGER_SPECIFIER(x) XSPECIFIER_TYPE (x, integer)
444 #define XSETINTEGER_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, integer)
445 #define INTEGER_SPECIFIERP(x) SPECIFIER_TYPEP (x, integer)
446 #define CHECK_INTEGER_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, integer)
447 #define CONCHECK_INTEGER_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, integer)
448
449 DECLARE_SPECIFIER_TYPE (natnum);
450 #define XNATNUM_SPECIFIER(x) XSPECIFIER_TYPE (x, natnum)
451 #define XSETNATNUM_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, natnum)
452 #define NATNUM_SPECIFIERP(x) SPECIFIER_TYPEP (x, natnum)
453 #define CHECK_NATNUM_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, natnum)
454 #define CONCHECK_NATNUM_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, natnum)
455
456 DECLARE_SPECIFIER_TYPE (boolean);
457 #define XBOOLEAN_SPECIFIER(x) XSPECIFIER_TYPE (x, boolean)
458 #define XSETBOOLEAN_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, boolean)
459 #define BOOLEAN_SPECIFIERP(x) SPECIFIER_TYPEP (x, boolean)
460 #define CHECK_BOOLEAN_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, boolean)
461 #define CONCHECK_BOOLEAN_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, boolean)
462
463 DECLARE_SPECIFIER_TYPE (display_table);
464 #define XDISPLAYTABLE_SPECIFIER(x) XSPECIFIER_TYPE (x, display_table)
465 #define XSETDISPLAYTABLE_SPECIFIER(x, p) XSETSPECIFIER_TYPE (x, p, display_table)
466 #define DISPLAYTABLE_SPECIFIERP(x) SPECIFIER_TYPEP (x, display_table)
467 #define CHECK_DISPLAYTABLE_SPECIFIER(x) CHECK_SPECIFIER_TYPE (x, display_table)
468 #define CONCHECK_DISPLAYTABLE_SPECIFIER(x) CONCHECK_SPECIFIER_TYPE (x, display_table)
469
470 #endif /* _XEMACS_SPECIFIER_H_ */