Mercurial > hg > xemacs-beta

comparison src/specifier.c @ 2953:c7d4a681eb2c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2005-09-26 08:41:45 by ben] add specifier-instantiator and friends specifier.c: Add `specifier-instantiator' and related primitives. lispref/glyphs.texi, lispref/lispref.texi, lispref/specifiers.texi: Use "instantiation" not "instancing". Fix some places where "specifier" is used to mean "instantiator".
author ben
date Mon, 26 Sep 2005 08:41:57 +0000
parents 6fa9919a9a0b
children 1e7cc382eb16
comparison
equal deleted inserted replaced
2952:861a7995b9fe 2953:c7d4a681eb2c
1 /* Specifier implementation 1 /* Specifier implementation
2 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois. 2 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
3 Copyright (C) 1995, 1996, 2002 Ben Wing. 3 Copyright (C) 1995, 1996, 2002, 2005 Ben Wing.
4 Copyright (C) 1995 Sun Microsystems, Inc. 4 Copyright (C) 1995 Sun Microsystems, Inc.
5 5
6 This file is part of XEmacs. 6 This file is part of XEmacs.
7 7
8 XEmacs is free software; you can redistribute it and/or modify it 8 XEmacs is free software; you can redistribute it and/or modify it
21 Boston, MA 02111-1307, USA. */ 21 Boston, MA 02111-1307, USA. */
22 22
23 /* Synched up with: Not in FSF. */ 23 /* Synched up with: Not in FSF. */
24 24
25 /* Design by Ben Wing; 25 /* Design by Ben Wing;
26 Original version by Chuck Thompson; 26 Written by Ben Wing based on prototype for 19.12 by Chuck Thompson.
27 rewritten by Ben Wing; 27 Magic specifiers by Kirill Katsnelson.
28 Magic specifiers by Kirill Katsnelson;
29 */ 28 */
30 29
31 #include <config.h> 30 #include <config.h>
32 #include "lisp.h" 31 #include "lisp.h"
33 32
458 return decode_specifier_type (type, ERROR_ME_NOT) != 0; 457 return decode_specifier_type (type, ERROR_ME_NOT) != 0;
459 } 458 }
460 459
461 DEFUN ("valid-specifier-type-p", Fvalid_specifier_type_p, 1, 1, 0, /* 460 DEFUN ("valid-specifier-type-p", Fvalid_specifier_type_p, 1, 1, 0, /*
462 Given a SPECIFIER-TYPE, return non-nil if it is valid. 461 Given a SPECIFIER-TYPE, return non-nil if it is valid.
463 Valid types are 'generic, 'integer, 'boolean, 'color, 'font, 'image, 462 Valid types are `generic', `integer', `boolean', `color', `font', `image',
464 'face-boolean, and 'toolbar. 463 `face-boolean', and `toolbar'.
465 */ 464 */
466 (specifier_type)) 465 (specifier_type))
467 { 466 {
468 return valid_specifier_type_p (specifier_type) ? Qt : Qnil; 467 return valid_specifier_type_p (specifier_type) ? Qt : Qnil;
469 } 468 }
576 To put settings into a specifier, use `set-specifier', or the 575 To put settings into a specifier, use `set-specifier', or the
577 lower-level functions `add-spec-to-specifier' and 576 lower-level functions `add-spec-to-specifier' and
578 `add-spec-list-to-specifier'. You can also temporarily bind a setting 577 `add-spec-list-to-specifier'. You can also temporarily bind a setting
579 to a specifier using `let-specifier'. To retrieve settings, use 578 to a specifier using `let-specifier'. To retrieve settings, use
580 `specifier-specs', or its lower-level counterpart 579 `specifier-specs', or its lower-level counterpart
581 `specifier-spec-list'. To determine the actual value, use 580 `specifier-spec-list'.
582 `specifier-instance'. 581
582 To determine the actual value (i.e. the instance) in a particular domain, use
583 `specifier-instance'. To determine the corresponding setting that yielded
584 the value (i.e. the instantiator), use `specifier-instantiator'.
583 585
584 For more information, see `set-specifier', `specifier-instance', 586 For more information, see `set-specifier', `specifier-instance',
585 `specifier-specs', and `add-spec-to-specifier'; or, for a detailed 587 `specifier-specs', and `add-spec-to-specifier'; or, for a detailed
586 description of specifiers, including how exactly the instantiation 588 description of specifiers, including how exactly the instantiation
587 process works, see the chapter on specifiers in the XEmacs Lisp 589 process works, see the chapter on specifiers in the XEmacs Lisp
588 Reference Manual. 590 Reference Manual.
589 591
590 TYPE specifies the particular type of specifier, and should be one of 592 TYPE specifies the particular type of specifier, and should be one of
591 the symbols 'generic, 'integer, 'natnum, 'boolean, 'color, 'font, 593 the symbols `generic', `integer', `natnum', `boolean', `color', `font',
592 'image, 'face-boolean, 'display-table, 'gutter, 'gutter-size, 594 `image', `face-boolean', `display-table', `gutter', `gutter-size',
593 'gutter-visible or 'toolbar. 595 `gutter-visible' or `toolbar'.
594 596
595 For more information on particular types of specifiers, see the 597 For more information on particular types of specifiers, see the
596 functions `make-generic-specifier', `make-integer-specifier', 598 functions `make-generic-specifier', `make-integer-specifier',
597 `make-natnum-specifier', `make-boolean-specifier', 599 `make-natnum-specifier', `make-boolean-specifier',
598 `make-color-specifier', `make-font-specifier', `make-image-specifier', 600 `make-color-specifier', `make-font-specifier', `make-image-specifier',
635 /* Locales and domains */ 637 /* Locales and domains */
636 /************************************************************************/ 638 /************************************************************************/
637 639
638 DEFUN ("valid-specifier-locale-p", Fvalid_specifier_locale_p, 1, 1, 0, /* 640 DEFUN ("valid-specifier-locale-p", Fvalid_specifier_locale_p, 1, 1, 0, /*
639 Return t if LOCALE is a valid specifier locale. 641 Return t if LOCALE is a valid specifier locale.
640 Valid locales are devices, frames, windows, buffers, and 'global. 642 Valid locales are devices, frames, windows, buffers, and `global'.
641 \(nil is not valid.) 643 \(nil is not valid.)
642 */ 644 */
643 (locale)) 645 (locale))
644 { 646 {
645 /* This cannot GC. */ 647 /* This cannot GC. */
653 ? Qt : Qnil; 655 ? Qt : Qnil;
654 } 656 }
655 657
656 DEFUN ("valid-specifier-domain-p", Fvalid_specifier_domain_p, 1, 1, 0, /* 658 DEFUN ("valid-specifier-domain-p", Fvalid_specifier_domain_p, 1, 1, 0, /*
657 Return t if DOMAIN is a valid specifier domain. 659 Return t if DOMAIN is a valid specifier domain.
658 A domain is used to instance a specifier (i.e. determine the specifier's 660 A domain is used to instantiate a specifier (i.e. determine the specifier's
659 value in that domain). Valid domains are image instances, windows, frames, 661 value in that domain). Valid domains are image instances, windows, frames,
660 and devices. \(nil is not valid.) image instances are pseudo-domains since 662 and devices. \(nil is not valid.) image instances are pseudo-domains since
661 instantiation will actually occur in the window the image instance itself is 663 instantiation will actually occur in the window the image instance itself is
662 instantiated in. 664 instantiated in.
663 */ 665 */
673 } 675 }
674 676
675 DEFUN ("valid-specifier-locale-type-p", Fvalid_specifier_locale_type_p, 1, 1, 0, 677 DEFUN ("valid-specifier-locale-type-p", Fvalid_specifier_locale_type_p, 1, 1, 0,
676 /* 678 /*
677 Given a specifier LOCALE-TYPE, return non-nil if it is valid. 679 Given a specifier LOCALE-TYPE, return non-nil if it is valid.
678 Valid locale types are 'global, 'device, 'frame, 'window, and 'buffer. 680 Valid locale types are `global', `device', `frame', `window', and `buffer'.
679 \(Note, however, that in functions that accept either a locale or a locale 681 \(Note, however, that in functions that accept either a locale or a locale
680 type, 'global is considered an individual locale.) 682 type, `global' is considered an individual locale.)
681 */ 683 */
682 (locale_type)) 684 (locale_type))
683 { 685 {
684 /* This cannot GC. */ 686 /* This cannot GC. */
685 return (EQ (locale_type, Qglobal) || 687 return (EQ (locale_type, Qglobal) ||
826 828
827 Each tag has a predicate associated with it, which specifies whether 829 Each tag has a predicate associated with it, which specifies whether
828 that tag applies to a particular device. The tags which are device types 830 that tag applies to a particular device. The tags which are device types
829 and classes match devices of that type or class. User-defined tags can 831 and classes match devices of that type or class. User-defined tags can
830 have any predicate, or none (meaning that all devices match). When 832 have any predicate, or none (meaning that all devices match). When
831 attempting to instance a specifier, a particular instantiator is only 833 attempting to instantiate a specifier, a particular instantiator is only
832 considered if the device of the domain being instanced over matches 834 considered if the device of the domain being instantiated over matches
833 all tags in the tag set attached to that instantiator. 835 all tags in the tag set attached to that instantiator.
834 836
835 Most of the time, a tag set is not specified, and the instantiator 837 Most of the time, a tag set is not specified, and the instantiator
836 gets a null tag set, which matches all devices. 838 gets a null tag set, which matches all devices.
837 */ 839 */
974 \(a device) that specifies whether the tag matches that particular 976 \(a device) that specifies whether the tag matches that particular
975 device. If PREDICATE is omitted, the tag matches all devices. 977 device. If PREDICATE is omitted, the tag matches all devices.
976 978
977 You can redefine an existing user-defined specifier tag. However, 979 You can redefine an existing user-defined specifier tag. However,
978 you cannot redefine the built-in specifier tags (the device types 980 you cannot redefine the built-in specifier tags (the device types
979 and classes) or the symbols nil, t, 'all, or 'global. 981 and classes) or the symbols nil, t, `all', or `global'.
980 */ 982 */
981 (tag, predicate)) 983 (tag, predicate))
982 { 984 {
983 Lisp_Object assoc, devcons, concons; 985 Lisp_Object assoc, devcons, concons;
984 int recompute = 0; 986 int recompute = 0;
988 valid_console_type_p (tag)) 990 valid_console_type_p (tag))
989 invalid_change ("Cannot redefine built-in specifier tags", tag); 991 invalid_change ("Cannot redefine built-in specifier tags", tag);
990 /* Try to prevent common instantiators and locales from being 992 /* Try to prevent common instantiators and locales from being
991 redefined, to reduce ambiguity */ 993 redefined, to reduce ambiguity */
992 if (NILP (tag) || EQ (tag, Qt) || EQ (tag, Qall) || EQ (tag, Qglobal)) 994 if (NILP (tag) || EQ (tag, Qt) || EQ (tag, Qall) || EQ (tag, Qglobal))
993 invalid_change ("Cannot define nil, t, 'all, or 'global", tag); 995 invalid_change ("Cannot define nil, t, `all', or `global'", tag);
994 assoc = assq_no_quit (tag, Vuser_defined_tags); 996 assoc = assq_no_quit (tag, Vuser_defined_tags);
995 if (NILP (assoc)) 997 if (NILP (assoc))
996 { 998 {
997 recompute = 1; 999 recompute = 1;
998 Vuser_defined_tags = Fcons (Fcons (tag, predicate), Vuser_defined_tags); 1000 Vuser_defined_tags = Fcons (Fcons (tag, predicate), Vuser_defined_tags);
1474 { 1476 {
1475 Lisp_Object *inst_list = specifier_get_inst_list (specifier, locale, 1477 Lisp_Object *inst_list = specifier_get_inst_list (specifier, locale,
1476 type); 1478 type);
1477 if (!inst_list || NILP (*inst_list)) 1479 if (!inst_list || NILP (*inst_list))
1478 { 1480 {
1479 /* nil for *inst_list should only occur in 'global */ 1481 /* nil for *inst_list should only occur in `global' */
1480 assert (!inst_list || EQ (locale, Qglobal)); 1482 assert (!inst_list || EQ (locale, Qglobal));
1481 return Qnil; 1483 return Qnil;
1482 } 1484 }
1483 1485
1484 return specifier_process_inst_list (*inst_list, tag_set, exact_p, 1486 return specifier_process_inst_list (*inst_list, tag_set, exact_p,
1832 } 1834 }
1833 1835
1834 /* map MAPFUN over the locales in SPECIFIER that are given in LOCALE. 1836 /* map MAPFUN over the locales in SPECIFIER that are given in LOCALE.
1835 CLOSURE is passed unchanged to MAPFUN. LOCALE can be one of 1837 CLOSURE is passed unchanged to MAPFUN. LOCALE can be one of
1836 1838
1837 -- nil (same as 'all) 1839 -- nil (same as `all')
1838 -- a single locale, locale type, or 'all 1840 -- a single locale, locale type, or `all'
1839 -- a list of locales, locale types, and/or 'all 1841 -- a list of locales, locale types, and/or `all'
1840 1842
1841 MAPFUN is called for each locale and locale type given; for 'all, 1843 MAPFUN is called for each locale and locale type given; for `all',
1842 it is called for the locale 'global and for the four possible 1844 it is called for the locale `global' and for the four possible
1843 locale types. In each invocation, either LOCALE will be a locale 1845 locale types. In each invocation, either LOCALE will be a locale
1844 and LOCALE_TYPE will be the locale type of this locale, 1846 and LOCALE_TYPE will be the locale type of this locale,
1845 or LOCALE will be nil and LOCALE_TYPE will be a locale type. 1847 or LOCALE will be nil and LOCALE_TYPE will be a locale type.
1846 If MAPFUN ever returns non-zero, the mapping is halted and the 1848 If MAPFUN ever returns non-zero, the mapping is halted and the
1847 value returned is returned from map_specifier(). Otherwise, the 1849 value returned is returned from map_specifier(). Otherwise, the
1918 } 1920 }
1919 1921
1920 DEFUN ("add-spec-to-specifier", Fadd_spec_to_specifier, 2, 5, 0, /* 1922 DEFUN ("add-spec-to-specifier", Fadd_spec_to_specifier, 2, 5, 0, /*
1921 Add a specification to SPECIFIER. 1923 Add a specification to SPECIFIER.
1922 The specification maps from LOCALE (which should be a window, buffer, 1924 The specification maps from LOCALE (which should be a window, buffer,
1923 frame, device, or 'global, and defaults to 'global) to INSTANTIATOR, 1925 frame, device, or `global', and defaults to `global') to INSTANTIATOR,
1924 whose allowed values depend on the type of the specifier. Optional 1926 whose allowed values depend on the type of the specifier. Optional
1925 argument TAG-SET limits the instantiator to apply only to the specified 1927 argument TAG-SET limits the instantiator to apply only to the specified
1926 tag set, which should be a list of tags all of which must match the 1928 tag set, which should be a list of tags all of which must match the
1927 device being instantiated over (tags are a device type, a device class, 1929 device being instantiated over (tags are a device type, a device class,
1928 or tags defined with `define-specifier-tag'). Specifying a single 1930 or tags defined with `define-specifier-tag'). Specifying a single
1929 symbol for TAG-SET is equivalent to specifying a one-element list 1931 symbol for TAG-SET is equivalent to specifying a one-element list
1930 containing that symbol. Optional argument HOW-TO-ADD specifies what to 1932 containing that symbol. Optional argument HOW-TO-ADD specifies what to
1931 do if there are already specifications in the specifier. 1933 do if there are already specifications in the specifier.
1932 It should be one of 1934 It should be one of
1933 1935
1934 'prepend Put at the beginning of the current list of 1936 `prepend' Put at the beginning of the current list of
1935 instantiators for LOCALE. 1937 instantiators for LOCALE.
1936 'append Add to the end of the current list of 1938 `append' Add to the end of the current list of
1937 instantiators for LOCALE. 1939 instantiators for LOCALE.
1938 'remove-tag-set-prepend (this is the default) 1940 `remove-tag-set-prepend' (this is the default)
1939 Remove any existing instantiators whose tag set is 1941 Remove any existing instantiators whose tag set is
1940 the same as TAG-SET; then put the new instantiator 1942 the same as TAG-SET; then put the new instantiator
1941 at the beginning of the current list. ("Same tag 1943 at the beginning of the current list. ("Same tag
1942 set" means that they contain the same elements. 1944 set" means that they contain the same elements.
1943 The order may be different.) 1945 The order may be different.)
1944 'remove-tag-set-append 1946 `remove-tag-set-append'
1945 Remove any existing instantiators whose tag set is 1947 Remove any existing instantiators whose tag set is
1946 the same as TAG-SET; then put the new instantiator 1948 the same as TAG-SET; then put the new instantiator
1947 at the end of the current list. 1949 at the end of the current list.
1948 'remove-locale Remove all previous instantiators for this locale 1950 `remove-locale' Remove all previous instantiators for this locale
1949 before adding the new spec. 1951 before adding the new spec.
1950 'remove-locale-type Remove all specifications for all locales of the 1952 `remove-locale-type' Remove all specifications for all locales of the
1951 same type as LOCALE (this includes LOCALE itself) 1953 same type as LOCALE (this includes LOCALE itself)
1952 before adding the new spec. 1954 before adding the new spec.
1953 'remove-all Remove all specifications from the specifier 1955 `remove-all' Remove all specifications from the specifier
1954 before adding the new spec. 1956 before adding the new spec.
1955 1957
1956 You can retrieve the specifications for a particular locale or locale type 1958 You can retrieve the specifications for a particular locale or locale type
1957 with the function `specifier-spec-list' or `specifier-specs'. 1959 with the function `specifier-spec-list' or `specifier-specs'.
1958 */ 1960 */
1987 The format of SPEC-LIST is 1989 The format of SPEC-LIST is
1988 1990
1989 ((LOCALE (TAG-SET . INSTANTIATOR) ...) ...) 1991 ((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)
1990 1992
1991 where 1993 where
1992 LOCALE := a window, a buffer, a frame, a device, or 'global 1994 LOCALE := a window, a buffer, a frame, a device, or `global'
1993 TAG-SET := an unordered list of zero or more TAGS, each of which 1995 TAG-SET := an unordered list of zero or more TAGS, each of which
1994 is a symbol 1996 is a symbol
1995 TAG := a device class (see `valid-device-class-p'), a device type 1997 TAG := a device class (see `valid-device-class-p'), a device type
1996 (see `valid-console-type-p'), or a tag defined with 1998 (see `valid-console-type-p'), or a tag defined with
1997 `define-specifier-tag' 1999 `define-specifier-tag'
2103 2105
2104 DEFUN ("specifier-spec-list", Fspecifier_spec_list, 1, 4, 0, /* 2106 DEFUN ("specifier-spec-list", Fspecifier_spec_list, 1, 4, 0, /*
2105 Return the spec-list of specifications for SPECIFIER in LOCALE. 2107 Return the spec-list of specifications for SPECIFIER in LOCALE.
2106 2108
2107 If LOCALE is a particular locale (a buffer, window, frame, device, 2109 If LOCALE is a particular locale (a buffer, window, frame, device,
2108 or 'global), a spec-list consisting of the specification for that 2110 or `global'), a spec-list consisting of the specification for that
2109 locale will be returned. 2111 locale will be returned.
2110 2112
2111 If LOCALE is a locale type (i.e. 'buffer, 'window, 'frame, or 'device), 2113 If LOCALE is a locale type (i.e. `buffer', `window', `frame', or `device'),
2112 a spec-list of the specifications for all locales of that type will be 2114 a spec-list of the specifications for all locales of that type will be
2113 returned. 2115 returned.
2114 2116
2115 If LOCALE is nil or 'all, a spec-list of all specifications in SPECIFIER 2117 If LOCALE is nil or `all', a spec-list of all specifications in SPECIFIER
2116 will be returned. 2118 will be returned.
2117 2119
2118 LOCALE can also be a list of locales, locale types, and/or 'all; the 2120 LOCALE can also be a list of locales, locale types, and/or `all'; the
2119 result is as if `specifier-spec-list' were called on each element of the 2121 result is as if `specifier-spec-list' were called on each element of the
2120 list and the results concatenated together. 2122 list and the results concatenated together.
2121 2123
2122 Only instantiators where TAG-SET (a list of zero or more tags) is a 2124 Only instantiators where TAG-SET (a list of zero or more tags) is a
2123 subset of (or possibly equal to) the instantiator's tag set are returned. 2125 subset of (or possibly equal to) the instantiator's tag set are returned.
2153 in Lisp programs, and is as follows: 2155 in Lisp programs, and is as follows:
2154 2156
2155 1. If there is only one instantiator, then an inst-pair (i.e. cons of 2157 1. If there is only one instantiator, then an inst-pair (i.e. cons of
2156 tag and instantiator) will be returned; otherwise a list of 2158 tag and instantiator) will be returned; otherwise a list of
2157 inst-pairs will be returned. 2159 inst-pairs will be returned.
2158 2. For each inst-pair returned, if the instantiator's tag is 'any, 2160 2. For each inst-pair returned, if the instantiator's tag is `any',
2159 the tag will be removed and the instantiator itself will be returned 2161 the tag will be removed and the instantiator itself will be returned
2160 instead of the inst-pair. 2162 instead of the inst-pair.
2161 3. If there is only one instantiator, its value is nil, and its tag is 2163 3. If there is only one instantiator, its value is nil, and its tag is
2162 'any, a one-element list containing nil will be returned rather 2164 `any', a one-element list containing nil will be returned rather
2163 than just nil, to distinguish this case from there being no 2165 than just nil, to distinguish this case from there being no
2164 instantiators at all. 2166 instantiators at all.
2165 */ 2167 */
2166 (specifier, locale, tag_set, exact_p)) 2168 (specifier, locale, tag_set, exact_p))
2167 { 2169 {
2203 2205
2204 DEFUN ("remove-specifier", Fremove_specifier, 1, 4, 0, /* 2206 DEFUN ("remove-specifier", Fremove_specifier, 1, 4, 0, /*
2205 Remove specification(s) for SPECIFIER. 2207 Remove specification(s) for SPECIFIER.
2206 2208
2207 If LOCALE is a particular locale (a window, buffer, frame, device, 2209 If LOCALE is a particular locale (a window, buffer, frame, device,
2208 or 'global), the specification for that locale will be removed. 2210 or `global'), the specification for that locale will be removed.
2209 2211
2210 If instead, LOCALE is a locale type (i.e. 'window, 'buffer, 'frame, 2212 If instead, LOCALE is a locale type (i.e. `window', `buffer', `frame',
2211 or 'device), the specifications for all locales of that type will be 2213 or `device'), the specifications for all locales of that type will be
2212 removed. 2214 removed.
2213 2215
2214 If LOCALE is nil or 'all, all specifications will be removed. 2216 If LOCALE is nil or `all', all specifications will be removed.
2215 2217
2216 LOCALE can also be a list of locales, locale types, and/or 'all; this 2218 LOCALE can also be a list of locales, locale types, and/or `all'; this
2217 is equivalent to calling `remove-specifier' for each of the elements 2219 is equivalent to calling `remove-specifier' for each of the elements
2218 in the list. 2220 in the list.
2219 2221
2220 Only instantiators where TAG-SET (a list of zero or more tags) is a 2222 Only instantiators where TAG-SET (a list of zero or more tags) is a
2221 subset of (or possibly equal to) the instantiator's tag set are removed. 2223 subset of (or possibly equal to) the instantiator's tag set are removed.
2282 2284
2283 If DEST is nil or omitted, a new specifier will be created and the 2285 If DEST is nil or omitted, a new specifier will be created and the
2284 specifications copied into it. Otherwise, the specifications will be 2286 specifications copied into it. Otherwise, the specifications will be
2285 copied into the existing specifier in DEST. 2287 copied into the existing specifier in DEST.
2286 2288
2287 If LOCALE is nil or 'all, all specifications will be copied. If LOCALE 2289 If LOCALE is nil or `all', all specifications will be copied. If LOCALE
2288 is a particular locale, the specification for that particular locale will 2290 is a particular locale, the specification for that particular locale will
2289 be copied. If LOCALE is a locale type, the specifications for all locales 2291 be copied. If LOCALE is a locale type, the specifications for all locales
2290 of that type will be copied. LOCALE can also be a list of locales, 2292 of that type will be copied. LOCALE can also be a list of locales,
2291 locale types, and/or 'all; this is equivalent to calling `copy-specifier' 2293 locale types, and/or `all'; this is equivalent to calling `copy-specifier'
2292 for each of the elements of the list. See `specifier-spec-list' for more 2294 for each of the elements of the list. See `specifier-spec-list' for more
2293 information about LOCALE. 2295 information about LOCALE.
2294 2296
2295 Only instantiators where TAG-SET (a list of zero or more tags) is a 2297 Only instantiators where TAG-SET (a list of zero or more tags) is a
2296 subset of (or possibly equal to) the instantiator's tag set are copied. 2298 subset of (or possibly equal to) the instantiator's tag set are copied.
2337 return dest; 2339 return dest;
2338 } 2340 }
2339 2341
2340 2342
2341 /************************************************************************/ 2343 /************************************************************************/
2342 /* Instancing */ 2344 /* Instantiation */
2343 /************************************************************************/ 2345 /************************************************************************/
2344 2346
2345 static Lisp_Object 2347 static Lisp_Object
2346 call_validate_matchspec_method (Lisp_Object boxed_method, 2348 call_validate_matchspec_method (Lisp_Object boxed_method,
2347 Lisp_Object matchspec) 2349 Lisp_Object matchspec)
2438 } 2440 }
2439 2441
2440 DEFUN ("specifier-fallback", Fspecifier_fallback, 1, 1, 0, /* 2442 DEFUN ("specifier-fallback", Fspecifier_fallback, 1, 1, 0, /*
2441 Return the fallback value for SPECIFIER. 2443 Return the fallback value for SPECIFIER.
2442 Fallback values are provided by the C code for certain built-in 2444 Fallback values are provided by the C code for certain built-in
2443 specifiers to make sure that instancing won't fail even if all 2445 specifiers to make sure that instantiation won't fail even if all
2444 specs are removed from the specifier, or to implement simple 2446 specs are removed from the specifier, or to implement simple
2445 inheritance behavior (e.g. this method is used to ensure that 2447 inheritance behavior (e.g. this method is used to ensure that
2446 faces other than 'default inherit their attributes from 'default). 2448 faces other than `default' inherit their attributes from `default').
2447 By design, you cannot change the fallback value, and specifiers 2449 By design, you cannot change the fallback value, and specifiers
2448 created with `make-specifier' will never have a fallback (although 2450 created with `make-specifier' will never have a fallback (although
2449 a similar, Lisp-accessible capability may be provided in the future 2451 a similar, Lisp-accessible capability may be provided in the future
2450 to allow for inheritance). 2452 to allow for inheritance).
2451 2453
2452 The fallback value will be an inst-list that is instanced like 2454 The fallback value will be an inst-list that is instantiated like
2453 any other inst-list, a specifier of the same type as SPECIFIER 2455 any other inst-list, a specifier of the same type as SPECIFIER
2454 \(results in inheritance), or nil for no fallback. 2456 \(results in inheritance), or nil for no fallback.
2455 2457
2456 When you instance a specifier, you can explicitly request that the 2458 When you instantiate a specifier, you can explicitly request that the
2457 fallback not be consulted. (The C code does this, for example, when 2459 fallback not be consulted. (The C code does this, for example, when
2458 merging faces.) See `specifier-instance'. 2460 merging faces.) See `specifier-instance'.
2459 */ 2461 */
2460 (specifier)) 2462 (specifier))
2461 { 2463 {
2467 specifier_instance_from_inst_list (Lisp_Object specifier, 2469 specifier_instance_from_inst_list (Lisp_Object specifier,
2468 Lisp_Object matchspec, 2470 Lisp_Object matchspec,
2469 Lisp_Object domain, 2471 Lisp_Object domain,
2470 Lisp_Object inst_list, 2472 Lisp_Object inst_list,
2471 Error_Behavior errb, int no_quit, 2473 Error_Behavior errb, int no_quit,
2472 Lisp_Object depth) 2474 Lisp_Object depth,
2475 Lisp_Object *instantiator)
2473 { 2476 {
2474 /* This function can GC */ 2477 /* This function can GC */
2475 Lisp_Specifier *sp; 2478 Lisp_Specifier *sp;
2476 Lisp_Object device; 2479 Lisp_Object device;
2477 Lisp_Object rest; 2480 Lisp_Object rest;
2496 Lisp_Object tag_set = XCAR (tagged_inst); 2499 Lisp_Object tag_set = XCAR (tagged_inst);
2497 2500
2498 if (device_matches_specifier_tag_set_p (device, tag_set)) 2501 if (device_matches_specifier_tag_set_p (device, tag_set))
2499 { 2502 {
2500 Lisp_Object val = XCDR (tagged_inst); 2503 Lisp_Object val = XCDR (tagged_inst);
2504 Lisp_Object the_instantiator = val;
2505
2501 2506
2502 if (HAS_SPECMETH_P (sp, instantiate)) 2507 if (HAS_SPECMETH_P (sp, instantiate))
2503 val = call_with_suspended_errors 2508 val = call_with_suspended_errors
2504 ((lisp_fn_t) RAW_SPECMETH (sp, instantiate), 2509 ((lisp_fn_t) RAW_SPECMETH (sp, instantiate),
2505 Qunbound, Qspecifier, errb, 5, specifier, 2510 Qunbound, Qspecifier, errb, 5, specifier,
2507 2512
2508 if (!UNBOUNDP (val)) 2513 if (!UNBOUNDP (val))
2509 { 2514 {
2510 unbind_to (count); 2515 unbind_to (count);
2511 UNGCPRO; 2516 UNGCPRO;
2517 if (instantiator)
2518 *instantiator = the_instantiator;
2512 return val; 2519 return val;
2513 } 2520 }
2514 } 2521 }
2515 } 2522 }
2516 2523
2530 if (CIE_inst_list) \ 2537 if (CIE_inst_list) \
2531 { \ 2538 { \
2532 Lisp_Object CIE_val = \ 2539 Lisp_Object CIE_val = \
2533 specifier_instance_from_inst_list (specifier, matchspec, \ 2540 specifier_instance_from_inst_list (specifier, matchspec, \
2534 domain, *CIE_inst_list, \ 2541 domain, *CIE_inst_list, \
2535 errb, no_quit, depth); \ 2542 errb, no_quit, depth, \
2543 instantiator); \
2536 if (!UNBOUNDP (CIE_val)) \ 2544 if (!UNBOUNDP (CIE_val)) \
2537 return CIE_val; \ 2545 return CIE_val; \
2538 } \ 2546 } \
2539 } while (0) 2547 } while (0)
2540 2548
2542 starting from as specific a locale type as we can determine from the 2550 starting from as specific a locale type as we can determine from the
2543 domain we are passed and going on up through as many other locale types 2551 domain we are passed and going on up through as many other locale types
2544 as we can determine. In practice, when called from redisplay the 2552 as we can determine. In practice, when called from redisplay the
2545 arg will usually be a window and occasionally a frame. If 2553 arg will usually be a window and occasionally a frame. If
2546 triggered by a user call, who knows what it will usually be. */ 2554 triggered by a user call, who knows what it will usually be. */
2547 Lisp_Object 2555
2548 specifier_instance (Lisp_Object specifier, Lisp_Object matchspec, 2556 static Lisp_Object
2549 Lisp_Object domain, Error_Behavior errb, int no_quit, 2557 specifier_instance_1 (Lisp_Object specifier, Lisp_Object matchspec,
2550 int no_fallback, Lisp_Object depth) 2558 Lisp_Object domain, Error_Behavior errb, int no_quit,
2559 int no_fallback, Lisp_Object depth,
2560 Lisp_Object *instantiator)
2551 { 2561 {
2552 Lisp_Object buffer = Qnil; 2562 Lisp_Object buffer = Qnil;
2553 Lisp_Object window = Qnil; 2563 Lisp_Object window = Qnil;
2554 Lisp_Object frame = Qnil; 2564 Lisp_Object frame = Qnil;
2555 Lisp_Object device = Qnil; 2565 Lisp_Object device = Qnil;
2556 Lisp_Specifier *sp = XSPECIFIER (specifier); 2566 Lisp_Specifier *sp = XSPECIFIER (specifier);
2567
2568 if (instantiator)
2569 *instantiator = Qunbound;
2557 2570
2558 /* Attempt to determine buffer, window, frame, and device from the 2571 /* Attempt to determine buffer, window, frame, and device from the
2559 domain. */ 2572 domain. */
2560 /* #### get image instances out of domains! */ 2573 /* #### get image instances out of domains! */
2561 if (IMAGE_INSTANCEP (domain)) 2574 if (IMAGE_INSTANCEP (domain))
2637 } 2650 }
2638 2651
2639 assert (CONSP (sp->fallback)); 2652 assert (CONSP (sp->fallback));
2640 return specifier_instance_from_inst_list (specifier, matchspec, domain, 2653 return specifier_instance_from_inst_list (specifier, matchspec, domain,
2641 sp->fallback, errb, no_quit, 2654 sp->fallback, errb, no_quit,
2642 depth); 2655 depth, instantiator);
2643 } 2656 }
2644 #undef CHECK_INSTANCE_ENTRY 2657 #undef CHECK_INSTANCE_ENTRY
2658
2659 Lisp_Object
2660 specifier_instance (Lisp_Object specifier, Lisp_Object matchspec,
2661 Lisp_Object domain, Error_Behavior errb, int no_quit,
2662 int no_fallback, Lisp_Object depth)
2663 {
2664 return specifier_instance_1 (specifier, matchspec, domain, errb,
2665 no_quit, no_fallback, depth, NULL);
2666 }
2645 2667
2646 Lisp_Object 2668 Lisp_Object
2647 specifier_instance_no_quit (Lisp_Object specifier, Lisp_Object matchspec, 2669 specifier_instance_no_quit (Lisp_Object specifier, Lisp_Object matchspec,
2648 Lisp_Object domain, Error_Behavior errb, 2670 Lisp_Object domain, Error_Behavior errb,
2649 int no_fallback, Lisp_Object depth) 2671 int no_fallback, Lisp_Object depth)
2650 { 2672 {
2651 return specifier_instance (specifier, matchspec, domain, errb, 2673 return specifier_instance_1 (specifier, matchspec, domain, errb,
2652 1, no_fallback, depth); 2674 1, no_fallback, depth, NULL);
2675 }
2676
2677 static Lisp_Object
2678 specifier_matching_foo (Lisp_Object specifier,
2679 Lisp_Object matchspec,
2680 Lisp_Object domain,
2681 Lisp_Object default_,
2682 Lisp_Object no_fallback,
2683 int want_instantiator)
2684 {
2685 Lisp_Object instance, instantiator;
2686
2687 CHECK_SPECIFIER (specifier);
2688 if (!UNBOUNDP (matchspec))
2689 check_valid_specifier_matchspec (matchspec,
2690 XSPECIFIER (specifier)->methods,
2691 ERROR_ME);
2692 domain = decode_domain (domain);
2693
2694 instance = specifier_instance_1 (specifier, matchspec, domain, ERROR_ME,
2695 0, !NILP (no_fallback), Qzero,
2696 &instantiator);
2697 return UNBOUNDP (instance) ? default_ : want_instantiator ? instantiator :
2698 instance;
2653 } 2699 }
2654 2700
2655 DEFUN ("specifier-instance", Fspecifier_instance, 1, 4, 0, /* 2701 DEFUN ("specifier-instance", Fspecifier_instance, 1, 4, 0, /*
2656 Instantiate SPECIFIER (return its value) in DOMAIN. 2702 Instantiate SPECIFIER (return its value) in DOMAIN.
2657 If no instance can be generated for this domain, return DEFAULT. 2703 If no instance can be generated for this domain, return DEFAULT.
2658 2704
2659 DOMAIN should be a window, frame, or device. Other values that are legal 2705 DOMAIN is nearly always a window (defaulting to the selected window if
2706 omitted), but can be a window, frame, or device. Other values that are legal
2660 as a locale (e.g. a buffer) are not valid as a domain because they do not 2707 as a locale (e.g. a buffer) are not valid as a domain because they do not
2661 provide enough information to identify a particular device (see 2708 provide enough information to identify a particular device (see
2662 `valid-specifier-domain-p'). DOMAIN defaults to the selected window 2709 `valid-specifier-domain-p'). Window domains are used internally in nearly
2663 if omitted. 2710 all circumstances when computing specifier instances of display properties.
2711 Frame domains are used in a few circumstances (such as when computing the
2712 geometry of a frame based on properties such as the toolbar widths), and
2713 device domains are rarely if ever used internally.
2714
2715 This function looks through the specifications in SPECIFIER that correspond
2716 to DOMAIN, from most specific (specifications for DOMAIN itself) to most
2717 general (global specifications), for matching instantiators, and attempts
2718 to compute an instance value for each instantiator found. The first
2719 successfully computed value is returned. The corresponding instantiator
2720 can be returned using `specifier-instantiator'.
2721
2722 A specifier is a generalized object for controlling the value of a property --
2723 typically, but not necessarily, a display-related property -- that can vary
2724 over particular buffers, frames, device types, etc.
2725
2726 A fundamental distinction must be made between the specification of a
2727 property's value, and the resulting value itself. This distinction is
2728 clearest in the case of an image -- the specification describes the source
2729 of the image (for example, a file of JPEG data), and the resulting value
2730 encapsulates a window-system object describing the image as displayed on a
2731 particular device (for example, a particular X display). The specification
2732 might also be an instruction of the form "use the background pixmap of the
2733 `modeline' face". A similar mapping exists between color strings and
2734 color-instance objects, and font strings and font-instance objects. In
2735 some cases, the specification and the resulting value are of the same type,
2736 but the distinction is still logically made.
2737
2738 The specification of a value is called an instantiator, and the resulting
2739 value the instance.
2664 2740
2665 "Instantiating" a specifier in a particular domain means determining 2741 "Instantiating" a specifier in a particular domain means determining
2666 the specifier's "value" in that domain. This is accomplished by 2742 the specifier's "value" in that domain. This is accomplished by
2667 searching through the specifications in the specifier that correspond 2743 searching through the specifications in the specifier that correspond
2668 to all locales that can be derived from the given domain, from specific 2744 to all locales that can be derived from the given domain, from specific
2671 2747
2672 1. A specification whose locale is the window itself; 2748 1. A specification whose locale is the window itself;
2673 2. A specification whose locale is the window's buffer; 2749 2. A specification whose locale is the window's buffer;
2674 3. A specification whose locale is the window's frame; 2750 3. A specification whose locale is the window's frame;
2675 4. A specification whose locale is the window's frame's device; 2751 4. A specification whose locale is the window's frame's device;
2676 5. A specification whose locale is 'global. 2752 5. A specification whose locale is `global'.
2677 2753
2678 If all of those fail, then the C-code-provided fallback value for 2754 If all of those fail, then the C-code-provided fallback value for
2679 this specifier is consulted (see `specifier-fallback'). If it is 2755 this specifier is consulted (see `specifier-fallback'). If it is
2680 an inst-list, then this function attempts to instantiate that list 2756 an inst-list, then this function attempts to instantiate that list
2681 just as when a specification is located in the first five steps above. 2757 just as when a specification is located in the first five steps above.
2699 trying to debug why particular instantiators are not being processed. 2775 trying to debug why particular instantiators are not being processed.
2700 2776
2701 The returned value is dependent on the type of specifier. For example, 2777 The returned value is dependent on the type of specifier. For example,
2702 for a font specifier (as returned by the `face-font' function), the returned 2778 for a font specifier (as returned by the `face-font' function), the returned
2703 value will be a font-instance object. For glyphs, the returned value 2779 value will be a font-instance object. For glyphs, the returned value
2704 will be a string, pixmap, or subwindow. 2780 will be an image-instance object.
2705 2781
2706 See also `specifier-matching-instance'. 2782 See also `specifier-matching-instance'.
2707 */ 2783 */
2708 (specifier, domain, default_, no_fallback)) 2784 (specifier, domain, default_, no_fallback))
2709 { 2785 {
2710 Lisp_Object instance; 2786 return specifier_matching_foo (specifier, Qunbound, domain, default_,
2711 2787 no_fallback, 0);
2712 CHECK_SPECIFIER (specifier); 2788 }
2713 domain = decode_domain (domain); 2789
2714 2790 DEFUN ("specifier-instantiator", Fspecifier_instantiator, 1, 4, 0, /*
2715 instance = specifier_instance (specifier, Qunbound, domain, ERROR_ME, 0, 2791 Return instantiator that would be used to instantiate SPECIFIER in DOMAIN.
2716 !NILP (no_fallback), Qzero); 2792 If no instance can be generated for this domain, return DEFAULT.
2717 return UNBOUNDP (instance) ? default_ : instance; 2793
2794 DOMAIN should be a window, frame, or device. Other values that are legal
2795 as a locale (e.g. a buffer) are not valid as a domain because they do not
2796 provide enough information to identify a particular device (see
2797 `valid-specifier-domain-p'). DOMAIN defaults to the selected window
2798 if omitted.
2799
2800 See `specifier-instance' for more information about the instantiation process.
2801 */
2802 (specifier, domain, default_, no_fallback))
2803 {
2804 return specifier_matching_foo (specifier, Qunbound, domain, default_,
2805 no_fallback, 1);
2718 } 2806 }
2719 2807
2720 DEFUN ("specifier-matching-instance", Fspecifier_matching_instance, 2, 5, 0, /* 2808 DEFUN ("specifier-matching-instance", Fspecifier_matching_instance, 2, 5, 0, /*
2721 Return an instance for SPECIFIER in DOMAIN that matches MATCHSPEC. 2809 Return an instance for SPECIFIER in DOMAIN that matches MATCHSPEC.
2722 If no instance can be generated for this domain, return DEFAULT. 2810 If no instance can be generated for this domain, return DEFAULT.
2743 font to see if the font can support the charset. This currently only makes 2831 font to see if the font can support the charset. This currently only makes
2744 sense under MS Windows. 2832 sense under MS Windows.
2745 */ 2833 */
2746 (specifier, matchspec, domain, default_, no_fallback)) 2834 (specifier, matchspec, domain, default_, no_fallback))
2747 { 2835 {
2748 Lisp_Object instance; 2836 return specifier_matching_foo (specifier, matchspec, domain, default_,
2837 no_fallback, 0);
2838 }
2839
2840 DEFUN ("specifier-matching-instantiator", Fspecifier_matching_instantiator,
2841 2, 5, 0, /*
2842 Return instantiator for instance of SPECIFIER in DOMAIN that matches MATCHSPEC.
2843 If no instance can be generated for this domain, return DEFAULT.
2844
2845 This function is identical to `specifier-matching-instance' but returns
2846 the instantiator used to generate the instance, rather than the actual
2847 instance.
2848 */
2849 (specifier, matchspec, domain, default_, no_fallback))
2850 {
2851 return specifier_matching_foo (specifier, matchspec, domain, default_,
2852 no_fallback, 1);
2853 }
2854
2855 static Lisp_Object
2856 specifier_matching_foo_from_inst_list (Lisp_Object specifier,
2857 Lisp_Object matchspec,
2858 Lisp_Object domain,
2859 Lisp_Object inst_list,
2860 Lisp_Object default_,
2861 int want_instantiator)
2862 {
2863 Lisp_Object val = Qunbound;
2864 Lisp_Specifier *sp = XSPECIFIER (specifier);
2865 struct gcpro gcpro1;
2866 Lisp_Object built_up_list = Qnil;
2867 Lisp_Object instantiator;
2749 2868
2750 CHECK_SPECIFIER (specifier); 2869 CHECK_SPECIFIER (specifier);
2751 check_valid_specifier_matchspec (matchspec, XSPECIFIER (specifier)->methods, 2870 if (!UNBOUNDP (matchspec))
2752 ERROR_ME); 2871 check_valid_specifier_matchspec (matchspec,
2753 domain = decode_domain (domain); 2872 XSPECIFIER (specifier)->methods,
2754 2873 ERROR_ME);
2755 instance = specifier_instance (specifier, matchspec, domain, ERROR_ME, 2874 check_valid_domain (domain);
2756 0, !NILP (no_fallback), Qzero); 2875 check_valid_inst_list (inst_list, sp->methods, ERROR_ME);
2757 return UNBOUNDP (instance) ? default_ : instance; 2876 GCPRO1 (built_up_list);
2877 built_up_list = build_up_processed_list (specifier, domain, inst_list);
2878 if (!NILP (built_up_list))
2879 val = specifier_instance_from_inst_list (specifier, matchspec, domain,
2880 built_up_list, ERROR_ME,
2881 0, Qzero, &instantiator);
2882 UNGCPRO;
2883 return UNBOUNDP (val) ? default_ : want_instantiator ? instantiator : val;
2884
2758 } 2885 }
2759 2886
2760 DEFUN ("specifier-instance-from-inst-list", Fspecifier_instance_from_inst_list, 2887 DEFUN ("specifier-instance-from-inst-list", Fspecifier_instance_from_inst_list,
2761 3, 4, 0, /* 2888 3, 4, 0, /*
2762 Attempt to convert a particular inst-list into an instance. 2889 Attempt to convert a particular inst-list into an instance.
2765 the instantiation fails, DEFAULT is returned. In most circumstances, 2892 the instantiation fails, DEFAULT is returned. In most circumstances,
2766 you should not use this function; use `specifier-instance' instead. 2893 you should not use this function; use `specifier-instance' instead.
2767 */ 2894 */
2768 (specifier, domain, inst_list, default_)) 2895 (specifier, domain, inst_list, default_))
2769 { 2896 {
2770 Lisp_Object val = Qunbound; 2897 return specifier_matching_foo_from_inst_list (specifier, Qunbound,
2771 Lisp_Specifier *sp = XSPECIFIER (specifier); 2898 domain, inst_list, default_,
2772 struct gcpro gcpro1; 2899 0);
2773 Lisp_Object built_up_list = Qnil; 2900 }
2774 2901
2775 CHECK_SPECIFIER (specifier); 2902 DEFUN ("specifier-instantiator-from-inst-list", Fspecifier_instantiator_from_inst_list,
2776 check_valid_domain (domain); 2903 3, 4, 0, /*
2777 check_valid_inst_list (inst_list, sp->methods, ERROR_ME); 2904 Attempt to convert an inst-list into an instance; return instantiator.
2778 GCPRO1 (built_up_list); 2905 This is identical to `specifier-instance-from-inst-list' but returns
2779 built_up_list = build_up_processed_list (specifier, domain, inst_list); 2906 the instantiator used to generate the instance, rather than the instance
2780 if (!NILP (built_up_list)) 2907 itself.
2781 val = specifier_instance_from_inst_list (specifier, Qunbound, domain, 2908 */
2782 built_up_list, ERROR_ME, 2909 (specifier, domain, inst_list, default_))
2783 0, Qzero); 2910 {
2784 UNGCPRO; 2911 return specifier_matching_foo_from_inst_list (specifier, Qunbound,
2785 return UNBOUNDP (val) ? default_ : val; 2912 domain, inst_list, default_,
2913 1);
2786 } 2914 }
2787 2915
2788 DEFUN ("specifier-matching-instance-from-inst-list", 2916 DEFUN ("specifier-matching-instance-from-inst-list",
2789 Fspecifier_matching_instance_from_inst_list, 2917 Fspecifier_matching_instance_from_inst_list,
2790 4, 5, 0, /* 2918 4, 5, 0, /*
2798 See that function for a description of exactly how the matching process 2926 See that function for a description of exactly how the matching process
2799 works. 2927 works.
2800 */ 2928 */
2801 (specifier, matchspec, domain, inst_list, default_)) 2929 (specifier, matchspec, domain, inst_list, default_))
2802 { 2930 {
2803 Lisp_Object val = Qunbound; 2931 return specifier_matching_foo_from_inst_list (specifier, matchspec,
2804 Lisp_Specifier *sp = XSPECIFIER (specifier); 2932 domain, inst_list, default_,
2805 struct gcpro gcpro1; 2933 0);
2806 Lisp_Object built_up_list = Qnil; 2934 }
2807 2935
2808 CHECK_SPECIFIER (specifier); 2936 DEFUN ("specifier-matching-instantiator-from-inst-list",
2809 check_valid_specifier_matchspec (matchspec, XSPECIFIER (specifier)->methods, 2937 Fspecifier_matching_instantiator_from_inst_list,
2810 ERROR_ME); 2938 4, 5, 0, /*
2811 check_valid_domain (domain); 2939 Attempt to convert an inst-list into an instance; return instantiator.
2812 check_valid_inst_list (inst_list, sp->methods, ERROR_ME); 2940 This is identical to `specifier-matching-instance-from-inst-list' but returns
2813 GCPRO1 (built_up_list); 2941 the instantiator used to generate the instance, rather than the instance
2814 built_up_list = build_up_processed_list (specifier, domain, inst_list); 2942 itself.
2815 if (!NILP (built_up_list)) 2943 */
2816 val = specifier_instance_from_inst_list (specifier, matchspec, domain, 2944 (specifier, matchspec, domain, inst_list, default_))
2817 built_up_list, ERROR_ME, 2945 {
2818 0, Qzero); 2946 return specifier_matching_foo_from_inst_list (specifier, matchspec,
2819 UNGCPRO; 2947 domain, inst_list, default_,
2820 return UNBOUNDP (val) ? default_ : val; 2948 1);
2821 } 2949 }
2822 2950
2823 2951
2824 /************************************************************************/ 2952 /************************************************************************/
2825 /* Caching in the struct window or frame */ 2953 /* Caching in the struct window or frame */
3056 "A generic specifier is a generalized kind of specifier with user-defined\n" 3184 "A generic specifier is a generalized kind of specifier with user-defined\n"
3057 "semantics. The instantiator can be any kind of Lisp object, and the\n" 3185 "semantics. The instantiator can be any kind of Lisp object, and the\n"
3058 "instance computed from it is likewise any kind of Lisp object. The\n" 3186 "instance computed from it is likewise any kind of Lisp object. The\n"
3059 "SPECIFIER-DATA should be an alist of methods governing how the specifier\n" 3187 "SPECIFIER-DATA should be an alist of methods governing how the specifier\n"
3060 "works. All methods are optional, and reasonable default methods will be\n" 3188 "works. All methods are optional, and reasonable default methods will be\n"
3061 "provided. Currently there are two defined methods: 'instantiate and\n" 3189 "provided. Currently there are two defined methods: `instantiate' and\n"
3062 "'validate.\n" 3190 "`validate'.\n"
3063 "\n" 3191 "\n"
3064 "'instantiate specifies how to do the instantiation; if omitted, the\n" 3192 "`instantiate' specifies how to do the instantiation; if omitted, the\n"
3065 "instantiator itself is simply returned as the instance. The method\n" 3193 "instantiator itself is simply returned as the instance. The method\n"
3066 "should be a function that accepts three parameters (a specifier, the\n" 3194 "should be a function that accepts three parameters (a specifier, the\n"
3067 "instantiator that matched the domain being instantiated over, and that\n" 3195 "instantiator that matched the domain being instantiated over, and that\n"
3068 "domain), and should return a one-element list containing the instance,\n" 3196 "domain), and should return a one-element list containing the instance,\n"
3069 "or nil if no instance exists. Note that the domain passed to this function\n" 3197 "or nil if no instance exists. Note that the domain passed to this function\n"
3071 "locale contained in the specification corresponding to the instantiator\n" 3199 "locale contained in the specification corresponding to the instantiator\n"
3072 "(for example, the domain being instantiated over could be a window, but\n" 3200 "(for example, the domain being instantiated over could be a window, but\n"
3073 "the locale corresponding to the passed instantiator could be the window's\n" 3201 "the locale corresponding to the passed instantiator could be the window's\n"
3074 "buffer or frame).\n" 3202 "buffer or frame).\n"
3075 "\n" 3203 "\n"
3076 "'validate specifies whether a given instantiator is valid; if omitted,\n" 3204 "`validate' specifies whether a given instantiator is valid; if omitted,\n"
3077 "all instantiators are considered valid. It should be a function of\n" 3205 "all instantiators are considered valid. It should be a function of\n"
3078 "two arguments: an instantiator and a flag CAN-SIGNAL-ERROR. If this\n" 3206 "two arguments: an instantiator and a flag CAN-SIGNAL-ERROR. If this\n"
3079 "flag is false, the function must simply return t or nil indicating\n" 3207 "flag is false, the function must simply return t or nil indicating\n"
3080 "whether the instantiator is valid. If this flag is true, the function\n" 3208 "whether the instantiator is valid. If this flag is true, the function\n"
3081 "is free to signal an error if it encounters an invalid instantiator\n" 3209 "is free to signal an error if it encounters an invalid instantiator\n"
3269 3397
3270 DEFSUBR (Fcheck_valid_specifier_matchspec); 3398 DEFSUBR (Fcheck_valid_specifier_matchspec);
3271 DEFSUBR (Fvalid_specifier_matchspec_p); 3399 DEFSUBR (Fvalid_specifier_matchspec_p);
3272 DEFSUBR (Fspecifier_fallback); 3400 DEFSUBR (Fspecifier_fallback);
3273 DEFSUBR (Fspecifier_instance); 3401 DEFSUBR (Fspecifier_instance);
3402 DEFSUBR (Fspecifier_instantiator);
3274 DEFSUBR (Fspecifier_matching_instance); 3403 DEFSUBR (Fspecifier_matching_instance);
3404 DEFSUBR (Fspecifier_matching_instantiator);
3275 DEFSUBR (Fspecifier_instance_from_inst_list); 3405 DEFSUBR (Fspecifier_instance_from_inst_list);
3406 DEFSUBR (Fspecifier_instantiator_from_inst_list);
3276 DEFSUBR (Fspecifier_matching_instance_from_inst_list); 3407 DEFSUBR (Fspecifier_matching_instance_from_inst_list);
3408 DEFSUBR (Fspecifier_matching_instantiator_from_inst_list);
3277 DEFSUBR (Fset_specifier_dirty_flag); 3409 DEFSUBR (Fset_specifier_dirty_flag);
3278 3410
3279 DEFSUBR (Fgeneric_specifier_p); 3411 DEFSUBR (Fgeneric_specifier_p);
3280 DEFSUBR (Finteger_specifier_p); 3412 DEFSUBR (Finteger_specifier_p);
3281 DEFSUBR (Fnatnum_specifier_p); 3413 DEFSUBR (Fnatnum_specifier_p);