compile/grep fix for bug#10594
[bpt/emacs.git] / lisp / custom.el
CommitLineData
55535639
PJ
1;;; custom.el --- tools for declaring and initializing options
2;;
acaf905b 3;; Copyright (C) 1996-1997, 1999, 2001-2012 Free Software Foundation, Inc.
55535639
PJ
4;;
5;; Author: Per Abrahamsen <abraham@dina.kvl.dk>
6;; Maintainer: FSF
7;; Keywords: help, faces
bd78fa1d 8;; Package: emacs
55535639
PJ
9
10;; This file is part of GNU Emacs.
11
eb3fa2cf 12;; GNU Emacs is free software: you can redistribute it and/or modify
55535639 13;; it under the terms of the GNU General Public License as published by
eb3fa2cf
GM
14;; the Free Software Foundation, either version 3 of the License, or
15;; (at your option) any later version.
55535639
PJ
16
17;; GNU Emacs is distributed in the hope that it will be useful,
18;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20;; GNU General Public License for more details.
21
22;; You should have received a copy of the GNU General Public License
eb3fa2cf 23;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
55535639
PJ
24
25;;; Commentary:
26;;
e6bb31f3 27;; This file only contains the code needed to declare and initialize
55535639
PJ
28;; user options. The code to customize options is autoloaded from
29;; `cus-edit.el' and is documented in the Emacs Lisp Reference manual.
30
e6bb31f3 31;; The code implementing face declarations is in `cus-face.el'.
55535639
PJ
32
33;;; Code:
34
35(require 'widget)
36
37(defvar custom-define-hook nil
38 ;; Customize information for this option is in `cus-edit.el'.
39 "Hook called after defining each customize option.")
40
6da43544
RS
41(defvar custom-dont-initialize nil
42 "Non-nil means `defcustom' should not initialize the variable.
43That is used for the sake of `custom-make-dependencies'.
44Users should not set it.")
45
d3b80e9b
SM
46(defvar custom-current-group-alist nil
47 "Alist of (FILE . GROUP) indicating the current group to use for FILE.")
48
55535639
PJ
49;;; The `defcustom' Macro.
50
51(defun custom-initialize-default (symbol value)
52 "Initialize SYMBOL with VALUE.
53This will do nothing if symbol already has a default binding.
54Otherwise, if symbol has a `saved-value' property, it will evaluate
494bcd27 55the car of that and use it as the default binding for symbol.
55535639
PJ
56Otherwise, VALUE will be evaluated and used as the default binding for
57symbol."
d032d5e7
SM
58 (eval `(defvar ,symbol ,(if (get symbol 'saved-value)
59 (car (get symbol 'saved-value))
60 value))))
55535639
PJ
61
62(defun custom-initialize-set (symbol value)
63 "Initialize SYMBOL based on VALUE.
64If the symbol doesn't have a default binding already,
65then set it using its `:set' function (or `set-default' if it has none).
66The value is either the value in the symbol's `saved-value' property,
67if any, or VALUE."
68 (unless (default-boundp symbol)
69 (funcall (or (get symbol 'custom-set) 'set-default)
70 symbol
b3c7c12d
SM
71 (eval (if (get symbol 'saved-value)
72 (car (get symbol 'saved-value))
73 value)))))
55535639
PJ
74
75(defun custom-initialize-reset (symbol value)
76 "Initialize SYMBOL based on VALUE.
77Set the symbol, using its `:set' function (or `set-default' if it has none).
78The value is either the symbol's current value
79 \(as obtained using the `:get' function), if any,
80or the value in the symbol's `saved-value' property if any,
81or (last of all) VALUE."
d032d5e7
SM
82 (funcall (or (get symbol 'custom-set) 'set-default)
83 symbol
84 (cond ((default-boundp symbol)
85 (funcall (or (get symbol 'custom-get) 'default-value)
86 symbol))
87 ((get symbol 'saved-value)
88 (eval (car (get symbol 'saved-value))))
89 (t
90 (eval value)))))
55535639
PJ
91
92(defun custom-initialize-changed (symbol value)
93 "Initialize SYMBOL with VALUE.
94Like `custom-initialize-reset', but only use the `:set' function if
95not using the standard setting.
96For the standard setting, use `set-default'."
97 (cond ((default-boundp symbol)
98 (funcall (or (get symbol 'custom-set) 'set-default)
99 symbol
100 (funcall (or (get symbol 'custom-get) 'default-value)
101 symbol)))
102 ((get symbol 'saved-value)
103 (funcall (or (get symbol 'custom-set) 'set-default)
104 symbol
105 (eval (car (get symbol 'saved-value)))))
106 (t
107 (set-default symbol (eval value)))))
108
790d0270
SM
109(defvar custom-delayed-init-variables nil
110 "List of variables whose initialization is pending.")
111
06b60517 112(defun custom-initialize-delay (symbol _value)
790d0270 113 "Delay initialization of SYMBOL to the next Emacs start.
90a94603
GM
114This is used in files that are preloaded (or for autoloaded
115variables), so that the initialization is done in the run-time
116context rather than the build-time context. This also has the
117side-effect that the (delayed) initialization is performed with
118the :set function.
119
120For variables in preloaded files, you can simply use this
121function for the :initialize property. For autoloaded variables,
122you will also need to add an autoload stanza calling this
f042cfd8
AS
123function, and another one setting the standard-value property."
124 ;; No longer true:
125 ;; "See `send-mail-function' in sendmail.el for an example."
126
adba8116
SM
127 ;; Until the var is actually initialized, it is kept unbound.
128 ;; This seemed to be at least as good as setting it to an arbitrary
129 ;; value like nil (evaluating `value' is not an option because it
130 ;; may have undesirable side-effects).
790d0270
SM
131 (push symbol custom-delayed-init-variables))
132
55535639
PJ
133(defun custom-declare-variable (symbol default doc &rest args)
134 "Like `defcustom', but SYMBOL and DEFAULT are evaluated as normal arguments.
135DEFAULT should be an expression to evaluate to compute the default value,
e1bab181
RS
136not the default value itself.
137
8989771d 138DEFAULT is stored as SYMBOL's standard value, in SYMBOL's property
e1bab181
RS
139`standard-value'. At the same time, SYMBOL's property `force-value' is
140set to nil, as the value is no longer rogue."
b6f8ba09 141 (put symbol 'standard-value (purecopy (list default)))
55535639
PJ
142 ;; Maybe this option was rogue in an earlier version. It no longer is.
143 (when (get symbol 'force-value)
144 (put symbol 'force-value nil))
d032d5e7
SM
145 (if (keywordp doc)
146 (error "Doc string is missing"))
55535639
PJ
147 (let ((initialize 'custom-initialize-reset)
148 (requests nil))
d3b80e9b
SM
149 (unless (memq :group args)
150 (custom-add-to-group (custom-current-group) symbol 'custom-variable))
55535639
PJ
151 (while args
152 (let ((arg (car args)))
153 (setq args (cdr args))
154 (unless (symbolp arg)
155 (error "Junk in args %S" args))
156 (let ((keyword arg)
157 (value (car args)))
158 (unless args
159 (error "Keyword %s is missing an argument" keyword))
160 (setq args (cdr args))
161 (cond ((eq keyword :initialize)
162 (setq initialize value))
163 ((eq keyword :set)
164 (put symbol 'custom-set value))
165 ((eq keyword :get)
166 (put symbol 'custom-get value))
167 ((eq keyword :require)
6f0d61bf 168 (push value requests))
fd045a34
GM
169 ((eq keyword :risky)
170 (put symbol 'risky-local-variable value))
171 ((eq keyword :safe)
172 (put symbol 'safe-local-variable value))
55535639
PJ
173 ((eq keyword :type)
174 (put symbol 'custom-type (purecopy value)))
175 ((eq keyword :options)
176 (if (get symbol 'custom-options)
177 ;; Slow safe code to avoid duplicates.
178 (mapc (lambda (option)
179 (custom-add-option symbol option))
6f0d61bf 180 value)
55535639
PJ
181 ;; Fast code for the common case.
182 (put symbol 'custom-options (copy-sequence value))))
183 (t
184 (custom-handle-keyword symbol keyword value
185 'custom-variable))))))
186 (put symbol 'custom-requests requests)
187 ;; Do the actual initialization.
6da43544
RS
188 (unless custom-dont-initialize
189 (funcall initialize symbol default)))
d032d5e7
SM
190 ;; Use defvar to set the docstring as well as the special-variable-p flag.
191 ;; FIXME: We should reproduce more of `defvar's behavior, such as the warning
192 ;; when the var is currently let-bound.
193 (if (not (default-boundp symbol))
194 ;; Don't use defvar to avoid setting a default-value when undesired.
195 (when doc (put symbol 'variable-documentation doc))
196 (eval `(defvar ,symbol nil ,@(when doc (list doc)))))
80888260 197 (push symbol current-load-list)
55535639
PJ
198 (run-hooks 'custom-define-hook)
199 symbol)
200
201(defmacro defcustom (symbol value doc &rest args)
202 "Declare SYMBOL as a customizable variable that defaults to VALUE.
203DOC is the variable documentation.
204
494bcd27 205Neither SYMBOL nor VALUE need to be quoted.
55535639
PJ
206If SYMBOL is not already bound, initialize it to VALUE.
207The remaining arguments should have the form
208
209 [KEYWORD VALUE]...
210
211The following keywords are meaningful:
212
693d0bd3 213:type VALUE should be a widget type for editing the symbol's value.
55535639 214:options VALUE should be a list of valid members of the widget type.
81117bdd
BW
215:initialize
216 VALUE should be a function used to initialize the
217 variable. It takes two arguments, the symbol and value
218 given in the `defcustom' call. The default is
219 `custom-initialize-reset'.
8a20ca4c
LMI
220:set VALUE should be a function to set the value of the symbol
221 when using the Customize user interface.
81117bdd 222 It takes two arguments, the symbol to set and the value to
f2276b69 223 give it. The default choice of function is `set-default'.
81117bdd
BW
224:get VALUE should be a function to extract the value of symbol.
225 The function takes one argument, a symbol, and should return
226 the current value for that symbol. The default choice of function
f2276b69 227 is `default-value'.
81117bdd
BW
228:require
229 VALUE should be a feature symbol. If you save a value
230 for this option, then when your `.emacs' file loads the value,
231 it does (require VALUE) first.
fd045a34
GM
232:risky Set SYMBOL's `risky-local-variable' property to VALUE.
233:safe Set SYMBOL's `safe-local-variable' property to VALUE.
81117bdd
BW
234
235The following common keywords are also meaningful.
236
55535639 237:group VALUE should be a customization group.
81117bdd 238 Add SYMBOL (or FACE with `defface') to that group.
3dc5f18e 239:link LINK-DATA
00644b82
EZ
240 Include an external link after the documentation string for this
241 item. This is a sentence containing an active field which
242 references some other documentation.
71296446 243
11ee7d4e 244 There are several alternatives you can use for LINK-DATA:
71296446 245
3dc5f18e 246 (custom-manual INFO-NODE)
00644b82 247 Link to an Info node; INFO-NODE is a string which specifies
11ee7d4e 248 the node name, as in \"(emacs)Top\".
71296446 249
3dc5f18e 250 (info-link INFO-NODE)
00644b82
EZ
251 Like `custom-manual' except that the link appears in the
252 customization buffer with the Info node name.
71296446 253
3dc5f18e 254 (url-link URL)
00644b82 255 Link to a web page; URL is a string which specifies the URL.
11ee7d4e
JL
256
257 (emacs-commentary-link LIBRARY)
258 Link to the commentary section of LIBRARY.
259
260 (emacs-library-link LIBRARY)
261 Link to an Emacs Lisp LIBRARY file.
262
263 (file-link FILE)
264 Link to FILE.
265
266 (function-link FUNCTION)
267 Link to the documentation of FUNCTION.
268
269 (variable-link VARIABLE)
270 Link to the documentation of VARIABLE.
271
272 (custom-group-link GROUP)
273 Link to another customization GROUP.
71296446 274
00644b82
EZ
275 You can specify the text to use in the customization buffer by
276 adding `:tag NAME' after the first element of the LINK-DATA; for
3dc5f18e 277 example, (info-link :tag \"foo\" \"(emacs)Top\") makes a link to the
00644b82 278 Emacs manual which appears in the buffer as `foo'.
71296446 279
00644b82
EZ
280 An item can have more than one external link; however, most items
281 have none at all.
55535639
PJ
282:version
283 VALUE should be a string specifying that the variable was
284 first introduced, or its default value was changed, in Emacs
285 version VERSION.
4e9c705e 286:package-version
994019df 287 VALUE should be a list with the form (PACKAGE . VERSION)
4e9c705e
BW
288 specifying that the variable was first introduced, or its
289 default value was changed, in PACKAGE version VERSION. This
290 keyword takes priority over :version. The PACKAGE and VERSION
291 must appear in the alist `customize-package-emacs-version-alist'.
994019df
BW
292 Since PACKAGE must be unique and the user might see it in an
293 error message, a good choice is the official name of the
294 package, such as MH-E or Gnus.
00644b82
EZ
295:tag LABEL
296 Use LABEL, a string, instead of the item's name, to label the item
1c1da418 297 in customization menus and buffers.
00644b82
EZ
298:load FILE
299 Load file FILE (a string) before displaying this customization
29512a0f 300 item. Loading is done with `load', and only if the file is
00644b82 301 not already loaded.
64e9f9d9
DL
302:set-after VARIABLES
303 Specifies that SYMBOL should be set after the list of variables
304 VARIABLES when both have been customized.
55535639 305
19229e5e
LT
306If SYMBOL has a local binding, then this form affects the local
307binding. This is normally not what you want. Thus, if you need
308to load a file defining variables with this form, or with
309`defvar' or `defconst', you should always load that file
310_outside_ any bindings for these variables. \(`defvar' and
311`defconst' behave similarly in this respect.)
312
81117bdd
BW
313See Info node `(elisp) Customization' in the Emacs Lisp manual
314for more information."
98923800 315 (declare (doc-string 3) (debug (name body)))
55535639
PJ
316 ;; It is better not to use backquote in this file,
317 ;; because that makes a bootstrapping problem
318 ;; if you need to recompile all the Lisp files using interpreted code.
850256b5
SM
319 `(custom-declare-variable
320 ',symbol
321 ,(if lexical-binding ;FIXME: This is not reliable, but is all we have.
322 ;; The `default' arg should be an expression that evaluates to
323 ;; the value to use. The use of `eval' for it is spread over
324 ;; many different places and hence difficult to eliminate, yet
325 ;; we want to make sure that the `value' expression is checked by the
326 ;; byte-compiler, and that lexical-binding is obeyed, so quote the
327 ;; expression with `lambda' rather than with `quote'.
328 `(list (lambda () ,value))
329 `',value)
330 ,doc
331 ,@args))
55535639
PJ
332
333;;; The `defface' Macro.
334
335(defmacro defface (face spec doc &rest args)
336 "Declare FACE as a customizable face that defaults to SPEC.
337FACE does not need to be quoted.
338
339Third argument DOC is the face documentation.
340
2a69edce 341If FACE has been set with `custom-set-faces', set the face attributes
55535639
PJ
342as specified by that function, otherwise set the face attributes
343according to SPEC.
344
345The remaining arguments should have the form
346
347 [KEYWORD VALUE]...
348
81117bdd
BW
349For a list of valid keywords, see the common keywords listed in
350`defcustom'.
55535639
PJ
351
352SPEC should be an alist of the form ((DISPLAY ATTS)...).
353
ebdaed17 354In the first element, DISPLAY can be `default'. The ATTS in that
9c27debd
RS
355element then act as defaults for all the following elements.
356
357Aside from that, DISPLAY specifies conditions to match some or
358all frames. For each frame, the first element of SPEC where the
359DISPLAY conditions are satisfied is the one that applies to that
360frame. The ATTRs in this element take effect, and the following
361elements are ignored, on that frame.
362
363In the last element, DISPLAY can be t. That element applies to a
ebdaed17 364frame if none of the previous elements (except the `default' if
9c27debd 365any) did.
55535639
PJ
366
367ATTS is a list of face attributes followed by their values:
368 (ATTR VALUE ATTR VALUE...)
369
370The possible attributes are `:family', `:width', `:height', `:weight',
371`:slant', `:underline', `:overline', `:strike-through', `:box',
3d58b15e 372`:foreground', `:background', `:stipple', `:inverse-video', and `:inherit'.
55535639 373
ebdaed17 374DISPLAY can be `default' (only in the first element), the symbol
9c27debd
RS
375t (only in the last element) to match all frames, or an alist of
376conditions of the form \(REQ ITEM...). For such an alist to
377match a frame, each of the conditions must be satisfied, meaning
378that the REQ property of the frame must match one of the
379corresponding ITEMs. These are the defined REQ values:
55535639
PJ
380
381`type' (the value of `window-system')
382 Under X, in addition to the values `window-system' can take,
9b44aa8b
JD
383 `motif', `lucid', `gtk' and `x-toolkit' are allowed, and match when
384 the Motif toolkit, Lucid toolkit, GTK toolkit or any X toolkit is in use.
55535639
PJ
385
386`class' (the frame's color support)
387 Should be one of `color', `grayscale', or `mono'.
388
389`background' (what color is used for the background text)
390 Should be one of `light' or `dark'.
391
6e166990
EZ
392`min-colors' (the minimum number of colors the frame should support)
393 Should be an integer, it is compared with the result of
394 `display-color-cells'.
395
ec85856c
JL
396`supports' (only match frames that support the specified face attributes)
397 Should be a list of face attributes. See the documentation for
398 the function `display-supports-face-attributes-p' for more
399 information on exactly how testing is done.
400
81117bdd
BW
401See Info node `(elisp) Customization' in the Emacs Lisp manual
402for more information."
67a60caa 403 (declare (doc-string 3))
55535639
PJ
404 ;; It is better not to use backquote in this file,
405 ;; because that makes a bootstrapping problem
406 ;; if you need to recompile all the Lisp files using interpreted code.
407 (nconc (list 'custom-declare-face (list 'quote face) spec doc) args))
408
409;;; The `defgroup' Macro.
410
d3b80e9b
SM
411(defun custom-current-group ()
412 (cdr (assoc load-file-name custom-current-group-alist)))
413
55535639
PJ
414(defun custom-declare-group (symbol members doc &rest args)
415 "Like `defgroup', but SYMBOL is evaluated as a normal argument."
416 (while members
417 (apply 'custom-add-to-group symbol (car members))
418 (setq members (cdr members)))
55535639
PJ
419 (when doc
420 ;; This text doesn't get into DOC.
421 (put symbol 'group-documentation (purecopy doc)))
422 (while args
423 (let ((arg (car args)))
424 (setq args (cdr args))
425 (unless (symbolp arg)
426 (error "Junk in args %S" args))
427 (let ((keyword arg)
428 (value (car args)))
429 (unless args
430 (error "Keyword %s is missing an argument" keyword))
431 (setq args (cdr args))
432 (cond ((eq keyword :prefix)
b6f8ba09 433 (put symbol 'custom-prefix (purecopy value)))
55535639
PJ
434 (t
435 (custom-handle-keyword symbol keyword value
436 'custom-group))))))
d3b80e9b
SM
437 ;; Record the group on the `current' list.
438 (let ((elt (assoc load-file-name custom-current-group-alist)))
439 (if elt (setcdr elt symbol)
af89cf77
DN
440 (push (cons (purecopy load-file-name) symbol)
441 custom-current-group-alist)))
55535639
PJ
442 (run-hooks 'custom-define-hook)
443 symbol)
444
445(defmacro defgroup (symbol members doc &rest args)
446 "Declare SYMBOL as a customization group containing MEMBERS.
447SYMBOL does not need to be quoted.
448
7a41cd7f
GM
449Third argument DOC is the group documentation. This should be a short
450description of the group, beginning with a capital and ending with
451a period. Words other than the first should not be capitalized, if they
452are not usually written so.
55535639
PJ
453
454MEMBERS should be an alist of the form ((NAME WIDGET)...) where
455NAME is a symbol and WIDGET is a widget for editing that symbol.
456Useful widgets are `custom-variable' for editing variables,
457`custom-face' for edit faces, and `custom-group' for editing groups.
458
459The remaining arguments should have the form
460
461 [KEYWORD VALUE]...
462
81117bdd
BW
463For a list of valid keywords, see the common keywords listed in
464`defcustom'.
55535639 465
81117bdd
BW
466See Info node `(elisp) Customization' in the Emacs Lisp manual
467for more information."
45aacac6 468 (declare (doc-string 3))
55535639
PJ
469 ;; It is better not to use backquote in this file,
470 ;; because that makes a bootstrapping problem
471 ;; if you need to recompile all the Lisp files using interpreted code.
472 (nconc (list 'custom-declare-group (list 'quote symbol) members doc) args))
473
474(defun custom-add-to-group (group option widget)
475 "To existing GROUP add a new OPTION of type WIDGET.
476If there already is an entry for OPTION and WIDGET, nothing is done."
477 (let ((members (get group 'custom-group))
478 (entry (list option widget)))
479 (unless (member entry members)
480 (put group 'custom-group (nconc members (list entry))))))
481
29512a0f
SM
482(defun custom-group-of-mode (mode)
483 "Return the custom group corresponding to the major or minor MODE.
484If no such group is found, return nil."
485 (or (get mode 'custom-mode-group)
486 (if (or (get mode 'custom-group)
487 (and (string-match "-mode\\'" (symbol-name mode))
488 (get (setq mode (intern (substring (symbol-name mode)
489 0 (match-beginning 0))))
490 'custom-group)))
491 mode)))
492
55535639
PJ
493;;; Properties.
494
495(defun custom-handle-all-keywords (symbol args type)
496 "For customization option SYMBOL, handle keyword arguments ARGS.
497Third argument TYPE is the custom option type."
d3b80e9b 498 (unless (memq :group args)
9b6098b9 499 (custom-add-to-group (custom-current-group) symbol type))
55535639
PJ
500 (while args
501 (let ((arg (car args)))
502 (setq args (cdr args))
503 (unless (symbolp arg)
504 (error "Junk in args %S" args))
505 (let ((keyword arg)
506 (value (car args)))
507 (unless args
508 (error "Keyword %s is missing an argument" keyword))
509 (setq args (cdr args))
510 (custom-handle-keyword symbol keyword value type)))))
511
512(defun custom-handle-keyword (symbol keyword value type)
513 "For customization option SYMBOL, handle KEYWORD with VALUE.
514Fourth argument TYPE is the custom option type."
515 (if purify-flag
516 (setq value (purecopy value)))
517 (cond ((eq keyword :group)
518 (custom-add-to-group value symbol type))
519 ((eq keyword :version)
520 (custom-add-version symbol value))
4e9c705e
BW
521 ((eq keyword :package-version)
522 (custom-add-package-version symbol value))
55535639
PJ
523 ((eq keyword :link)
524 (custom-add-link symbol value))
525 ((eq keyword :load)
526 (custom-add-load symbol value))
527 ((eq keyword :tag)
528 (put symbol 'custom-tag value))
529 ((eq keyword :set-after)
530 (custom-add-dependencies symbol value))
531 (t
532 (error "Unknown keyword %s" keyword))))
533
534(defun custom-add-dependencies (symbol value)
535 "To the custom option SYMBOL, add dependencies specified by VALUE.
536VALUE should be a list of symbols. For each symbol in that list,
537this specifies that SYMBOL should be set after the specified symbol, if
538both appear in constructs like `custom-set-variables'."
539 (unless (listp value)
540 (error "Invalid custom dependency `%s'" value))
541 (let* ((deps (get symbol 'custom-dependencies))
542 (new-deps deps))
543 (while value
544 (let ((dep (car value)))
545 (unless (symbolp dep)
546 (error "Invalid custom dependency `%s'" dep))
547 (unless (memq dep new-deps)
548 (setq new-deps (cons dep new-deps)))
549 (setq value (cdr value))))
550 (unless (eq deps new-deps)
551 (put symbol 'custom-dependencies new-deps))))
e1bab181 552
55535639
PJ
553(defun custom-add-option (symbol option)
554 "To the variable SYMBOL add OPTION.
555
a4842ffa
RS
556If SYMBOL's custom type is a hook, OPTION should be a hook member.
557If SYMBOL's custom type is an alist, OPTION specifies a symbol
558to offer to the user as a possible key in the alist.
559For other custom types, this has no effect."
55535639
PJ
560 (let ((options (get symbol 'custom-options)))
561 (unless (member option options)
562 (put symbol 'custom-options (cons option options)))))
467064a4 563(defalias 'custom-add-frequent-value 'custom-add-option)
55535639
PJ
564
565(defun custom-add-link (symbol widget)
566 "To the custom option SYMBOL add the link WIDGET."
567 (let ((links (get symbol 'custom-links)))
568 (unless (member widget links)
569 (put symbol 'custom-links (cons (purecopy widget) links)))))
570
571(defun custom-add-version (symbol version)
572 "To the custom option SYMBOL add the version VERSION."
573 (put symbol 'custom-version (purecopy version)))
574
4e9c705e
BW
575(defun custom-add-package-version (symbol version)
576 "To the custom option SYMBOL add the package version VERSION."
577 (put symbol 'custom-package-version (purecopy version)))
578
55535639
PJ
579(defun custom-add-load (symbol load)
580 "To the custom option SYMBOL add the dependency LOAD.
581LOAD should be either a library file name, or a feature name."
582 (let ((loads (get symbol 'custom-loads)))
583 (unless (member load loads)
584 (put symbol 'custom-loads (cons (purecopy load) loads)))))
585
d54fbdfd
SM
586(defun custom-autoload (symbol load &optional noset)
587 "Mark SYMBOL as autoloaded custom variable and add dependency LOAD.
588If NOSET is non-nil, don't bother autoloading LOAD when setting the variable."
589 (put symbol 'custom-autoload (if noset 'noset t))
1669290d
MR
590 (custom-add-load symbol load))
591
592;; This test is also in the C code of `user-variable-p'.
593(defun custom-variable-p (variable)
289e1999
LT
594 "Return non-nil if VARIABLE is a custom variable.
595This recursively follows aliases."
596 (setq variable (indirect-variable variable))
1669290d
MR
597 (or (get variable 'standard-value)
598 (get variable 'custom-autoload)))
599
400b960e
RS
600(defun custom-note-var-changed (variable)
601 "Inform Custom that VARIABLE has been set (changed).
602VARIABLE is a symbol that names a user option.
603The result is that the change is treated as having been made through Custom."
400b960e 604 (put variable 'customized-value (list (custom-quote (eval variable)))))
06f5c483
JL
605
606\f
607;;; Custom Themes
400b960e 608
8f772dfd
RS
609;;; Loading files needed to customize a symbol.
610;;; This is in custom.el because menu-bar.el needs it for toggle cmds.
611
612(defvar custom-load-recursion nil
613 "Hack to avoid recursive dependencies.")
614
615(defun custom-load-symbol (symbol)
616 "Load all dependencies for SYMBOL."
617 (unless custom-load-recursion
29512a0f 618 (let ((custom-load-recursion t))
a8c78057
RS
619 ;; Load these files if not already done,
620 ;; to make sure we know all the dependencies of SYMBOL.
621 (condition-case nil
622 (require 'cus-load)
623 (error nil))
624 (condition-case nil
625 (require 'cus-start)
626 (error nil))
29512a0f
SM
627 (dolist (load (get symbol 'custom-loads))
628 (cond ((symbolp load) (condition-case nil (require load) (error nil)))
629 ;; This is subsumed by the test below, but it's much faster.
8f772dfd
RS
630 ((assoc load load-history))
631 ;; This was just (assoc (locate-library load) load-history)
632 ;; but has been optimized not to load locate-library
633 ;; if not necessary.
29512a0f
SM
634 ((let ((regexp (concat "\\(\\`\\|/\\)" (regexp-quote load)
635 "\\(\\'\\|\\.\\)"))
636 (found nil))
8f772dfd 637 (dolist (loaded load-history)
c3891447
RS
638 (and (stringp (car loaded))
639 (string-match regexp (car loaded))
8f772dfd
RS
640 (setq found t)))
641 found))
642 ;; Without this, we would load cus-edit recursively.
643 ;; We are still loading it when we call this,
644 ;; and it is not in load-history yet.
645 ((equal load "cus-edit"))
29512a0f 646 (t (condition-case nil (load load) (error nil))))))))
46ce5feb 647\f
c2e2f9be
CY
648(defvar custom-local-buffer nil
649 "Non-nil, in a Customization buffer, means customize a specific buffer.
650If this variable is non-nil, it should be a buffer,
651and it means customize the local bindings of that buffer.
652This variable is a permanent local, and it normally has a local binding
653in every Customization buffer.")
654(put 'custom-local-buffer 'permanent-local t)
655
656(defun custom-set-default (variable value)
657 "Default :set function for a customizable variable.
658Normally, this sets the default value of VARIABLE to VALUE,
659but if `custom-local-buffer' is non-nil,
660this sets the local binding in that buffer instead."
661 (if custom-local-buffer
662 (with-current-buffer custom-local-buffer
663 (set variable value))
664 (set-default variable value)))
665
666(defun custom-set-minor-mode (variable value)
667 ":set function for minor mode variables.
668Normally, this sets the default value of VARIABLE to nil if VALUE
669is nil and to t otherwise,
670but if `custom-local-buffer' is non-nil,
671this sets the local binding in that buffer instead."
672 (if custom-local-buffer
673 (with-current-buffer custom-local-buffer
674 (funcall variable (if value 1 0)))
675 (funcall variable (if value 1 0))))
676
677(defun custom-quote (sexp)
4837b516 678 "Quote SEXP if it is not self quoting."
c2e2f9be
CY
679 (if (or (memq sexp '(t nil))
680 (keywordp sexp)
681 (and (listp sexp)
682 (memq (car sexp) '(lambda)))
683 (stringp sexp)
684 (numberp sexp)
685 (vectorp sexp)
686;;; (and (fboundp 'characterp)
687;;; (characterp sexp))
688 )
689 sexp
690 (list 'quote sexp)))
691
692(defun customize-mark-to-save (symbol)
693 "Mark SYMBOL for later saving.
694
695If the default value of SYMBOL is different from the standard value,
696set the `saved-value' property to a list whose car evaluates to the
697default value. Otherwise, set it to nil.
698
699To actually save the value, call `custom-save-all'.
700
4837b516 701Return non-nil if the `saved-value' property actually changed."
ec9f0a62 702 (custom-load-symbol symbol)
c2e2f9be
CY
703 (let* ((get (or (get symbol 'custom-get) 'default-value))
704 (value (funcall get symbol))
705 (saved (get symbol 'saved-value))
706 (standard (get symbol 'standard-value))
707 (comment (get symbol 'customized-variable-comment)))
4837b516 708 ;; Save default value if different from standard value.
c2e2f9be
CY
709 (if (or (null standard)
710 (not (equal value (condition-case nil
711 (eval (car standard))
712 (error nil)))))
713 (put symbol 'saved-value (list (custom-quote value)))
714 (put symbol 'saved-value nil))
715 ;; Clear customized information (set, but not saved).
716 (put symbol 'customized-value nil)
717 ;; Save any comment that might have been set.
718 (when comment
719 (put symbol 'saved-variable-comment comment))
720 (not (equal saved (get symbol 'saved-value)))))
721
722(defun customize-mark-as-set (symbol)
723 "Mark current value of SYMBOL as being set from customize.
724
725If the default value of SYMBOL is different from the saved value if any,
726or else if it is different from the standard value, set the
727`customized-value' property to a list whose car evaluates to the
728default value. Otherwise, set it to nil.
729
4837b516 730Return non-nil if the `customized-value' property actually changed."
ec9f0a62 731 (custom-load-symbol symbol)
c2e2f9be
CY
732 (let* ((get (or (get symbol 'custom-get) 'default-value))
733 (value (funcall get symbol))
734 (customized (get symbol 'customized-value))
735 (old (or (get symbol 'saved-value) (get symbol 'standard-value))))
4837b516 736 ;; Mark default value as set if different from old value.
d54fbdfd
SM
737 (if (not (and old
738 (equal value (condition-case nil
739 (eval (car old))
740 (error nil)))))
fccf2784
CY
741 (progn (put symbol 'customized-value (list (custom-quote value)))
742 (custom-push-theme 'theme-value symbol 'user 'set
743 (custom-quote value)))
c2e2f9be
CY
744 (put symbol 'customized-value nil))
745 ;; Changed?
746 (not (equal customized (get symbol 'customized-value)))))
747
748(defun custom-reevaluate-setting (symbol)
749 "Reset the value of SYMBOL by re-evaluating its saved or standard value.
750Use the :set function to do so. This is useful for customizable options
751that are defined before their standard value can really be computed.
752E.g. dumped variables whose default depends on run-time information."
753 (funcall (or (get symbol 'custom-set) 'set-default)
754 symbol
755 (eval (car (or (get symbol 'saved-value) (get symbol 'standard-value))))))
756
757\f
d358aa10
CY
758;;; Custom Themes
759
760;; Custom themes are collections of settings that can be enabled or
761;; disabled as a unit.
762
763;; Each Custom theme is defined by a symbol, called the theme name.
764;; The `theme-settings' property of the theme name records the
765;; variable and face settings of the theme. This property is a list
766;; of elements, each of the form
767;;
768;; (PROP SYMBOL THEME VALUE)
769;;
770;; - PROP is either `theme-value' or `theme-face'
771;; - SYMBOL is the face or variable name
772;; - THEME is the theme name (redundant, but simplifies the code)
773;; - VALUE is an expression that gives the theme's setting for SYMBOL.
774;;
775;; The theme name also has a `theme-feature' property, whose value is
776;; specified when the theme is defined (see `custom-declare-theme').
777;; Usually, this is just a symbol named THEME-theme. This lets
778;; external libraries call (require 'foo-theme).
779
780;; In addition, each symbol (either a variable or a face) affected by
781;; an *enabled* theme has a `theme-value' or `theme-face' property,
782;; which is a list of elements each of the form
783;;
784;; (THEME VALUE)
785;;
786;; which have the same meanings as in `theme-settings'.
787;;
788;; The `theme-value' and `theme-face' lists are ordered by decreasing
789;; theme precedence. Thus, the first element is always the one that
790;; is in effect.
791
792;; Each theme is stored in a theme file, with filename THEME-theme.el.
793;; Loading a theme basically involves calling (load "THEME-theme")
794;; This is done by the function `load-theme'. Loading a theme
795;; automatically enables it.
796;;
797;; When a theme is enabled, the `theme-value' and `theme-face'
798;; properties for the affected symbols are set. When a theme is
799;; disabled, its settings are removed from the `theme-value' and
800;; `theme-face' properties, but the theme's own `theme-settings'
801;; property remains unchanged.
802
d358aa10 803(defvar custom-known-themes '(user changed)
9c4b6e94 804 "Themes that have been defined with `deftheme'.
d358aa10 805The default value is the list (user changed). The theme `changed'
171fc304
JB
806contains the settings before custom themes are applied. The theme
807`user' contains all the settings the user customized and saved.
808Additional themes declared with the `deftheme' macro will be added
809to the front of this list.")
e1bab181 810
e1bab181
RS
811(defsubst custom-theme-p (theme)
812 "Non-nil when THEME has been defined."
813 (memq theme custom-known-themes))
814
815(defsubst custom-check-theme (theme)
816 "Check whether THEME is valid, and signal an error if it is not."
817 (unless (custom-theme-p theme)
818 (error "Unknown theme `%s'" theme)))
819
d358aa10
CY
820(defun custom-push-theme (prop symbol theme mode &optional value)
821 "Record VALUE for face or variable SYMBOL in custom theme THEME.
822PROP is `theme-face' for a face, `theme-value' for a variable.
e1bab181
RS
823
824MODE can be either the symbol `set' or the symbol `reset'. If it is the
825symbol `set', then VALUE is the value to use. If it is the symbol
d358aa10 826`reset', then SYMBOL will be removed from THEME (VALUE is ignored).
e1bab181 827
e1bab181 828See `custom-known-themes' for a list of known themes."
b2a41d12 829 (unless (memq prop '(theme-value theme-face))
d820f1fb 830 (error "Unknown theme property"))
46ce5feb 831 (let* ((old (get symbol prop))
d358aa10
CY
832 (setting (assq theme old)) ; '(theme value)
833 (theme-settings ; '(prop symbol theme value)
834 (get theme 'theme-settings)))
05d22d02
CY
835 (cond
836 ;; Remove a setting:
837 ((eq mode 'reset)
838 (when setting
839 (let (res)
840 (dolist (theme-setting theme-settings)
841 (if (and (eq (car theme-setting) prop)
842 (eq (cadr theme-setting) symbol))
843 (setq res theme-setting)))
844 (put theme 'theme-settings (delq res theme-settings)))
845 (put symbol prop (delq setting old))))
846 ;; Alter an existing setting:
847 (setting
848 (let (res)
849 (dolist (theme-setting theme-settings)
850 (if (and (eq (car theme-setting) prop)
851 (eq (cadr theme-setting) symbol))
852 (setq res theme-setting)))
853 (put theme 'theme-settings
854 (cons (list prop symbol theme value)
855 (delq res theme-settings)))
856 (setcar (cdr setting) value)))
857 ;; Add a new setting:
858 (t
859 (unless old
1485f4c0
CY
860 ;; If the user changed a variable outside of Customize, save
861 ;; the value to a fake theme, `changed'. If the theme is
862 ;; later disabled, we use this to bring back the old value.
863 ;;
864 ;; For faces, we just use `face-new-frame-defaults' to
865 ;; recompute when the theme is disabled.
866 (when (and (eq prop 'theme-value)
867 (boundp symbol))
868 (let ((sv (get symbol 'standard-value))
869 (val (symbol-value symbol)))
870 (unless (and sv (equal (eval (car sv)) val))
871 (setq old `((changed ,(custom-quote val))))))))
05d22d02
CY
872 (put symbol prop (cons (list theme value) old))
873 (put theme 'theme-settings
874 (cons (list prop symbol theme value) theme-settings))))))
875
876(defun custom-fix-face-spec (spec)
877 "Convert face SPEC, replacing obsolete :bold and :italic attributes.
878Also change :reverse-video to :inverse-video."
879 (when (listp spec)
880 (if (or (memq :bold spec)
881 (memq :italic spec)
882 (memq :inverse-video spec))
883 (let (result)
884 (while spec
885 (let ((key (car spec))
886 (val (car (cdr spec))))
887 (cond ((eq key :italic)
888 (push :slant result)
889 (push (if val 'italic 'normal) result))
890 ((eq key :bold)
891 (push :weight result)
892 (push (if val 'bold 'normal) result))
893 ((eq key :reverse-video)
894 (push :inverse-video result)
895 (push val result))
896 (t
897 (push key result)
898 (push val result))))
899 (setq spec (cddr spec)))
900 (nreverse result))
901 spec)))
c2e2f9be 902\f
55535639 903(defun custom-set-variables (&rest args)
f1a262ed
RS
904 "Install user customizations of variable values specified in ARGS.
905These settings are registered as theme `user'.
64e9f9d9 906The arguments should each be a list of the form:
55535639 907
f1a262ed 908 (SYMBOL EXP [NOW [REQUEST [COMMENT]]])
55535639 909
f1a262ed
RS
910This stores EXP (without evaluating it) as the saved value for SYMBOL.
911If NOW is present and non-nil, then also evaluate EXP and set
912the default value for the SYMBOL to the value of EXP.
e1bab181 913
f1a262ed
RS
914REQUEST is a list of features we must require in order to
915handle SYMBOL properly.
55535639 916COMMENT is a comment string about SYMBOL."
e1bab181
RS
917 (apply 'custom-theme-set-variables 'user args))
918
919(defun custom-theme-set-variables (theme &rest args)
f1a262ed
RS
920 "Initialize variables for theme THEME according to settings in ARGS.
921Each of the arguments in ARGS should be a list of this form:
e1bab181 922
f1a262ed 923 (SYMBOL EXP [NOW [REQUEST [COMMENT]]])
e1bab181 924
f1a262ed
RS
925This stores EXP (without evaluating it) as the saved value for SYMBOL.
926If NOW is present and non-nil, then also evaluate EXP and set
927the default value for the SYMBOL to the value of EXP.
e1bab181 928
f1a262ed
RS
929REQUEST is a list of features we must require in order to
930handle SYMBOL properly.
e1bab181
RS
931COMMENT is a comment string about SYMBOL.
932
f1a262ed 933EXP itself is saved unevaluated as SYMBOL property `saved-value' and
e1bab181
RS
934in SYMBOL's list property `theme-value' \(using `custom-push-theme')."
935 (custom-check-theme theme)
05d22d02 936
9277ee6c
SM
937 ;; Process all the needed autoloads before anything else, so that the
938 ;; subsequent code has all the info it needs (e.g. which var corresponds
939 ;; to a minor mode), regardless of the ordering of the variables.
940 (dolist (entry args)
941 (let* ((symbol (indirect-variable (nth 0 entry))))
942 (unless (or (get symbol 'standard-value)
943 (memq (get symbol 'custom-autoload) '(nil noset)))
944 ;; This symbol needs to be autoloaded, even just for a `set'.
945 (custom-load-symbol symbol))))
1e281896 946
9277ee6c 947 ;; Move minor modes and variables with explicit requires to the end.
059290d6
SM
948 (setq args
949 (sort args
950 (lambda (a1 a2)
951 (let* ((sym1 (car a1))
952 (sym2 (car a2))
953 (1-then-2 (memq sym1 (get sym2 'custom-dependencies)))
954 (2-then-1 (memq sym2 (get sym1 'custom-dependencies))))
955 (cond ((and 1-then-2 2-then-1)
956 (error "Circular custom dependency between `%s' and `%s'"
957 sym1 sym2))
958 (2-then-1 nil)
3d0c2a29
GM
959 ;; 1 is a dependency of 2, so needs to be set first.
960 (1-then-2)
b6790c3e
SM
961 ;; Put minor modes and symbols with :require last.
962 ;; Putting minor modes last ensures that the mode
963 ;; function will see other customized values rather
964 ;; than default values.
965 (t (or (nth 3 a2)
966 (eq (get sym2 'custom-set)
967 'custom-set-minor-mode))))))))
6b09b5d1
CY
968
969 (dolist (entry args)
970 (unless (listp entry)
971 (error "Incompatible Custom theme spec"))
972 (let* ((symbol (indirect-variable (nth 0 entry)))
973 (value (nth 1 entry)))
974 (custom-push-theme 'theme-value symbol theme 'set value)
975 (unless custom--inhibit-theme-enable
976 ;; Now set the variable.
977 (let* ((now (nth 2 entry))
978 (requests (nth 3 entry))
979 (comment (nth 4 entry))
980 set)
981 (when requests
982 (put symbol 'custom-requests requests)
983 (mapc 'require requests))
984 (setq set (or (get symbol 'custom-set) 'custom-set-default))
059290d6 985 (put symbol 'saved-value (list value))
6b09b5d1
CY
986 (put symbol 'saved-variable-comment comment)
987 ;; Allow for errors in the case where the setter has
988 ;; changed between versions, say, but let the user know.
989 (condition-case data
990 (cond (now
991 ;; Rogue variable, set it now.
992 (put symbol 'force-value t)
993 (funcall set symbol (eval value)))
994 ((default-boundp symbol)
995 ;; Something already set this, overwrite it.
996 (funcall set symbol (eval value))))
997 (error
998 (message "Error setting %s: %s" symbol data)))
999 (and (or now (default-boundp symbol))
1000 (put symbol 'variable-comment comment)))))))
55535639 1001
46ce5feb
RS
1002\f
1003;;; Defining themes.
1004
782b5e8d
CY
1005;; A theme file is named `THEME-theme.el' (where THEME is the theme
1006;; name) found in `custom-theme-load-path'. It has this format:
d358aa10
CY
1007;;
1008;; (deftheme THEME
1009;; DOCSTRING)
1010;;
1011;; (custom-theme-set-variables
1012;; 'THEME
1013;; [THEME-VARIABLES])
1014;;
1015;; (custom-theme-set-faces
1016;; 'THEME
1017;; [THEME-FACES])
1018;;
1019;; (provide-theme 'THEME)
46ce5feb 1020
46ce5feb 1021
d358aa10
CY
1022;; The IGNORED arguments to deftheme come from the XEmacs theme code, where
1023;; they were used to supply keyword-value pairs like `:immediate',
1024;; `:variable-reset-string', etc. We don't use any of these, so ignore them.
6d912ee1 1025
d358aa10
CY
1026(defmacro deftheme (theme &optional doc &rest ignored)
1027 "Declare THEME to be a Custom theme.
1028The optional argument DOC is a doc string describing the theme.
46ce5feb
RS
1029
1030Any theme `foo' should be defined in a file called `foo-theme.el';
1031see `custom-make-theme-feature' for more information."
1032 (let ((feature (custom-make-theme-feature theme)))
1033 ;; It is better not to use backquote in this file,
1034 ;; because that makes a bootstrapping problem
1035 ;; if you need to recompile all the Lisp files using interpreted code.
d358aa10 1036 (list 'custom-declare-theme (list 'quote theme) (list 'quote feature) doc)))
46ce5feb 1037
d358aa10 1038(defun custom-declare-theme (theme feature &optional doc &rest ignored)
46ce5feb 1039 "Like `deftheme', but THEME is evaluated as a normal argument.
d358aa10
CY
1040FEATURE is the feature this theme provides. Normally, this is a symbol
1041created from THEME by `custom-make-theme-feature'."
29a4c45b
CY
1042 (unless (custom-theme-name-valid-p theme)
1043 (error "Custom theme cannot be named %S" theme))
46ce5feb
RS
1044 (add-to-list 'custom-known-themes theme)
1045 (put theme 'theme-feature feature)
d358aa10 1046 (when doc (put theme 'theme-documentation doc)))
46ce5feb
RS
1047
1048(defun custom-make-theme-feature (theme)
1049 "Given a symbol THEME, create a new symbol by appending \"-theme\".
1050Store this symbol in the `theme-feature' property of THEME.
1051Calling `provide-theme' to provide THEME actually puts `THEME-theme'
1052into `features'.
1053
1054This allows for a file-name convention for autoloading themes:
1055Every theme X has a property `provide-theme' whose value is \"X-theme\".
87d737ae 1056\(load-theme X) then attempts to load the file `X-theme.el'."
46ce5feb
RS
1057 (intern (concat (symbol-name theme) "-theme")))
1058\f
1059;;; Loading themes.
1060
782b5e8d
CY
1061(defcustom custom-theme-directory user-emacs-directory
1062 "Default user directory for storing custom theme files.
1063The command `customize-create-theme' writes theme files into this
1064directory. By default, Emacs searches for custom themes in this
1065directory first---see `custom-theme-load-path'."
9c4b6e94
LT
1066 :type 'string
1067 :group 'customize
1068 :version "22.1")
1069
782b5e8d
CY
1070(defcustom custom-theme-load-path (list 'custom-theme-directory t)
1071 "List of directories to search for custom theme files.
29a4c45b
CY
1072When loading custom themes (e.g. in `customize-themes' and
1073`load-theme'), Emacs searches for theme files in the specified
782b5e8d 1074order. Each element in the list should be one of the following:
647bc502
CY
1075- the symbol `custom-theme-directory', meaning the value of
1076 `custom-theme-directory'.
1077- the symbol t, meaning the built-in theme directory (a directory
1078 named \"themes\" in `data-directory').
29a4c45b
CY
1079- a directory name (a string).
1080
171fc304 1081Each theme file is named THEME-theme.el, where THEME is the theme
29a4c45b 1082name."
782b5e8d
CY
1083 :type '(repeat (choice (const :tag "custom-theme-directory"
1084 custom-theme-directory)
1085 (const :tag "Built-in theme directory" t)
1086 directory))
1087 :group 'customize
1088 :version "24.1")
1089
6b09b5d1 1090(defvar custom--inhibit-theme-enable nil
fccee4ab
CY
1091 "Whether the custom-theme-set-* functions act immediately.
1092If nil, `custom-theme-set-variables' and `custom-theme-set-faces'
1093change the current values of the given variable or face. If
1094non-nil, they just make a record of the theme settings.")
6b09b5d1 1095
e1bab181 1096(defun provide-theme (theme)
d358aa10
CY
1097 "Indicate that this file provides THEME.
1098This calls `provide' to provide the feature name stored in THEME's
1099property `theme-feature' (which is usually a symbol created by
1100`custom-make-theme-feature')."
29a4c45b
CY
1101 (unless (custom-theme-name-valid-p theme)
1102 (error "Custom theme cannot be named %S" theme))
e1bab181 1103 (custom-check-theme theme)
fccee4ab 1104 (provide (get theme 'theme-feature)))
6b09b5d1 1105
b7617f6d 1106(defcustom custom-safe-themes '(default)
04c52e2f 1107 "Themes that are considered safe to load.
1de76afe 1108If the value is a list, each element should be either the SHA-256
04c52e2f
CY
1109hash of a safe theme file, or the symbol `default', which stands
1110for any theme in the built-in Emacs theme directory (a directory
1111named \"themes\" in `data-directory').
1112
04482335
CY
1113If the value is t, Emacs treats all themes as safe.
1114
1115This variable cannot be set in a Custom theme."
04c52e2f
CY
1116 :type '(choice (repeat :tag "List of safe themes"
1117 (choice string
1118 (const :tag "Built-in themes" default)))
1119 (const :tag "All themes" t))
278f6845 1120 :group 'customize
b7617f6d 1121 :risky t
278f6845
CY
1122 :version "24.1")
1123
658d8eb8 1124(defun load-theme (theme &optional no-confirm no-enable)
928f4e73 1125 "Load Custom theme named THEME from its file.
928f4e73
CY
1126The theme file is named THEME-theme.el, in one of the directories
1127specified by `custom-theme-load-path'.
278f6845 1128
04c52e2f
CY
1129If optional arg NO-CONFIRM is non-nil, and THEME is not
1130considered safe according to `custom-safe-themes', prompt the
1131user for confirmation.
658d8eb8
CY
1132
1133Normally, this function also enables THEME; if optional arg
1134NO-ENABLE is non-nil, load the theme but don't enable it.
1135
1136This function is normally called through Customize when setting
1137`custom-enabled-themes'. If used directly in your init file, it
1138should be called with a non-nil NO-CONFIRM argument, or after
1139`custom-safe-themes' has been loaded.
1140
928f4e73 1141Return t if THEME was successfully loaded, nil otherwise."
05d22d02
CY
1142 (interactive
1143 (list
1144 (intern (completing-read "Load custom theme: "
6b09b5d1 1145 (mapcar 'symbol-name
658d8eb8
CY
1146 (custom-available-themes))))
1147 nil nil))
6b09b5d1
CY
1148 (unless (custom-theme-name-valid-p theme)
1149 (error "Invalid theme name `%s'" theme))
73e60f53
CY
1150 ;; If reloading, clear out the old theme settings.
1151 (when (custom-theme-p theme)
1152 (disable-theme theme)
1153 (put theme 'theme-settings nil)
1154 (put theme 'theme-feature nil)
1155 (put theme 'theme-documentation nil))
6b09b5d1 1156 (let ((fn (locate-file (concat (symbol-name theme) "-theme.el")
782b5e8d 1157 (custom-theme--load-path)
b7617f6d
CY
1158 '("" "c")))
1159 hash)
6b09b5d1 1160 (unless fn
171fc304 1161 (error "Unable to find theme file for `%s'" theme))
b7617f6d
CY
1162 (with-temp-buffer
1163 (insert-file-contents fn)
1de76afe 1164 (setq hash (secure-hash 'sha256 (current-buffer)))
928f4e73
CY
1165 ;; Check file safety with `custom-safe-themes', prompting the
1166 ;; user if necessary.
658d8eb8 1167 (when (or no-confirm
04c52e2f 1168 (eq custom-safe-themes t)
658d8eb8 1169 (and (memq 'default custom-safe-themes)
b7617f6d
CY
1170 (equal (file-name-directory fn)
1171 (expand-file-name "themes/" data-directory)))
1172 (member hash custom-safe-themes)
928f4e73 1173 (custom-theme-load-confirm hash))
fccee4ab
CY
1174 (let ((custom--inhibit-theme-enable t))
1175 (eval-buffer))
3b2ff876
CY
1176 ;; Optimization: if the theme changes the `default' face, put that
1177 ;; entry first. This avoids some `frame-set-background-mode' rigmarole
1178 ;; by assigning the new background immediately.
1179 (let* ((settings (get theme 'theme-settings))
1180 (tail settings)
1181 found)
1182 (while (and tail (not found))
1183 (and (eq (nth 0 (car tail)) 'theme-face)
1184 (eq (nth 1 (car tail)) 'default)
1185 (setq found (car tail)))
1186 (setq tail (cdr tail)))
1187 (if found
1188 (put theme 'theme-settings (cons found (delq found settings)))))
1189 ;; Finally, enable the theme.
fccee4ab
CY
1190 (unless no-enable
1191 (enable-theme theme))
1192 t))))
b7617f6d
CY
1193
1194(defun custom-theme-load-confirm (hash)
1195 "Query the user about loading a Custom theme that may not be safe.
1196The theme should be in the current buffer. If the user agrees,
1197query also about adding HASH to `custom-safe-themes'."
278f6845
CY
1198 (if noninteractive
1199 nil
b7617f6d 1200 (let ((exit-chars '(?y ?n ?\s))
928f4e73 1201 window prompt char)
278f6845 1202 (save-window-excursion
b7617f6d
CY
1203 (rename-buffer "*Custom Theme*" t)
1204 (emacs-lisp-mode)
928f4e73 1205 (setq window (display-buffer (current-buffer)))
b7617f6d 1206 (setq prompt
928f4e73
CY
1207 (format "Loading a theme can run Lisp code. Really load?%s"
1208 (if (and window
1209 (< (line-number-at-pos (point-max))
1210 (window-body-height)))
1211 " (y or n) "
b7617f6d 1212 (push ?\C-v exit-chars)
928f4e73 1213 "\nType y or n, or C-v to scroll: ")))
b7617f6d
CY
1214 (goto-char (point-min))
1215 (while (null char)
1216 (setq char (read-char-choice prompt exit-chars))
1217 (when (eq char ?\C-v)
928f4e73
CY
1218 (if window
1219 (with-selected-window window
1220 (condition-case nil
1221 (scroll-up)
1222 (error (goto-char (point-min))))))
b7617f6d
CY
1223 (setq char nil)))
1224 (when (memq char '(?\s ?y))
b7617f6d
CY
1225 ;; Offer to save to `custom-safe-themes'.
1226 (and (or custom-file user-init-file)
928f4e73 1227 (y-or-n-p "Treat this theme as safe in future sessions? ")
658d8eb8 1228 (customize-push-and-save 'custom-safe-themes (list hash)))
b7617f6d 1229 t)))))
6b09b5d1
CY
1230
1231(defun custom-theme-name-valid-p (name)
1232 "Return t if NAME is a valid name for a Custom theme, nil otherwise.
1233NAME should be a symbol."
1234 (and (symbolp name)
1235 name
1236 (not (or (zerop (length (symbol-name name)))
6b09b5d1
CY
1237 (eq name 'user)
1238 (eq name 'changed)))))
05d22d02
CY
1239
1240(defun custom-available-themes ()
6b09b5d1 1241 "Return a list of available Custom themes (symbols)."
171fc304 1242 (let (sym themes)
782b5e8d
CY
1243 (dolist (dir (custom-theme--load-path))
1244 (when (file-directory-p dir)
1245 (dolist (file (file-expand-wildcards
1246 (expand-file-name "*-theme.el" dir) t))
1247 (setq file (file-name-nondirectory file))
1248 (and (string-match "\\`\\(.+\\)-theme.el\\'" file)
1249 (setq sym (intern (match-string 1 file)))
1250 (custom-theme-name-valid-p sym)
1251 (push sym themes)))))
2bb5649e 1252 (nreverse (delete-dups themes))))
782b5e8d
CY
1253
1254(defun custom-theme--load-path ()
1255 (let (lpath)
1256 (dolist (f custom-theme-load-path)
1257 (cond ((eq f 'custom-theme-directory)
1258 (setq f custom-theme-directory))
1259 ((eq f t)
1260 (setq f (expand-file-name "themes" data-directory))))
1261 (if (file-directory-p f)
1262 (push f lpath)))
1263 (nreverse lpath)))
1264
46ce5feb
RS
1265\f
1266;;; Enabling and disabling loaded themes.
1267
87d737ae 1268(defun enable-theme (theme)
46ce5feb 1269 "Reenable all variable and face settings defined by THEME.
fccee4ab
CY
1270THEME should be either `user', or a theme loaded via `load-theme'.
1271After this function completes, THEME will have the highest
1272precedence (after `user')."
05d22d02
CY
1273 (interactive (list (intern
1274 (completing-read
1275 "Enable custom theme: "
fccee4ab 1276 obarray (lambda (sym) (get sym 'theme-settings)) t))))
d358aa10 1277 (if (not (custom-theme-p theme))
fccee4ab
CY
1278 (error "Undefined Custom theme %s" theme))
1279 (let ((settings (get theme 'theme-settings)))
1280 ;; Loop through theme settings, recalculating vars/faces.
1281 (dolist (s settings)
1282 (let* ((prop (car s))
1283 (symbol (cadr s))
1284 (spec-list (get symbol prop)))
1285 (put symbol prop (cons (cddr s) (assq-delete-all theme spec-list)))
1286 (cond
1287 ((eq prop 'theme-face)
1288 (custom-theme-recalc-face symbol))
1289 ((eq prop 'theme-value)
04482335
CY
1290 ;; Ignore `custom-enabled-themes' and `custom-safe-themes'.
1291 (unless (memq symbol '(custom-enabled-themes custom-safe-themes))
fccee4ab
CY
1292 (custom-theme-recalc-variable symbol)))))))
1293 (unless (eq theme 'user)
1294 (setq custom-enabled-themes
1295 (cons theme (delq theme custom-enabled-themes)))
1296 ;; Give the `user' theme the highest priority.
1297 (enable-theme 'user)))
b2a41d12
CY
1298
1299(defcustom custom-enabled-themes nil
1300 "List of enabled Custom Themes, highest precedence first.
fccee4ab
CY
1301This list does not include the `user' theme, which is set by
1302Customize and always takes precedence over other Custom Themes.
b2a41d12 1303
fccee4ab 1304This variable cannot be defined inside a Custom theme; there, it
658d8eb8
CY
1305is simply ignored.
1306
1307Setting this variable through Customize calls `enable-theme' or
1308`load-theme' for each theme in the list."
b2a41d12
CY
1309 :group 'customize
1310 :type '(repeat symbol)
928f4e73
CY
1311 :set-after '(custom-theme-directory custom-theme-load-path
1312 custom-safe-themes)
7fd8732d 1313 :risky t
b2a41d12 1314 :set (lambda (symbol themes)
fccee4ab
CY
1315 (let (failures)
1316 (setq themes (delq 'user (delete-dups themes)))
1317 ;; Disable all themes not in THEMES.
1318 (if (boundp symbol)
1319 (dolist (theme (symbol-value symbol))
1320 (if (not (memq theme themes))
1321 (disable-theme theme))))
1322 ;; Call `enable-theme' or `load-theme' on each of THEMES.
1323 (dolist (theme (reverse themes))
1324 (condition-case nil
1325 (if (custom-theme-p theme)
1326 (enable-theme theme)
1327 (load-theme theme))
1328 (error (setq failures (cons theme failures)
1329 themes (delq theme themes)))))
1330 (enable-theme 'user)
1331 (custom-set-default symbol themes)
1332 (if failures
1333 (message "Failed to enable theme: %s"
1334 (mapconcat 'symbol-name failures ", "))))))
b2a41d12 1335
d358aa10 1336(defsubst custom-theme-enabled-p (theme)
b2a41d12
CY
1337 "Return non-nil if THEME is enabled."
1338 (memq theme custom-enabled-themes))
46ce5feb 1339
87d737ae 1340(defun disable-theme (theme)
46ce5feb 1341 "Disable all variable and face settings defined by THEME.
b2a41d12 1342See `custom-enabled-themes' for a list of enabled themes."
d358aa10
CY
1343 (interactive (list (intern
1344 (completing-read
05d22d02 1345 "Disable custom theme: "
d358aa10
CY
1346 (mapcar 'symbol-name custom-enabled-themes)
1347 nil t))))
1348 (when (custom-theme-enabled-p theme)
8913f945
RS
1349 (let ((settings (get theme 'theme-settings)))
1350 (dolist (s settings)
05d22d02 1351 (let* ((prop (car s))
8913f945 1352 (symbol (cadr s))
05d22d02
CY
1353 (val (assq-delete-all theme (get symbol prop))))
1354 (put symbol prop val)
1355 (cond
1356 ((eq prop 'theme-value)
1357 (custom-theme-recalc-variable symbol))
1358 ((eq prop 'theme-face)
1359 ;; If the face spec specified by this theme is in the
1360 ;; saved-face property, reset that property.
1361 (when (equal (nth 3 s) (get symbol 'saved-face))
1485f4c0
CY
1362 (put symbol 'saved-face (and val (cadr (car val)))))))))
1363 ;; Recompute faces on all frames.
1364 (dolist (frame (frame-list))
1365 ;; We must reset the fg and bg color frame parameters, or
1366 ;; `face-set-after-frame-default' will use the existing
1367 ;; parameters, which could be from the disabled theme.
1368 (set-frame-parameter frame 'background-color
1369 (custom--frame-color-default
1370 frame :background "background" "Background"
1371 "unspecified-bg" "white"))
1372 (set-frame-parameter frame 'foreground-color
1373 (custom--frame-color-default
1374 frame :foreground "foreground" "Foreground"
1375 "unspecified-fg" "black"))
1376 (face-set-after-frame-default frame))
05d22d02
CY
1377 (setq custom-enabled-themes
1378 (delq theme custom-enabled-themes)))))
46ce5feb 1379
1485f4c0
CY
1380(defun custom--frame-color-default (frame attribute resource-attr resource-class
1381 tty-default x-default)
1382 (let ((col (face-attribute 'default attribute t)))
1383 (cond
1384 ((and col (not (eq col 'unspecified))) col)
1385 ((null (window-system frame)) tty-default)
1386 ((setq col (x-get-resource resource-attr resource-class)) col)
1387 (t x-default))))
1388
46ce5feb
RS
1389(defun custom-variable-theme-value (variable)
1390 "Return (list VALUE) indicating the custom theme value of VARIABLE.
1391That is to say, it specifies what the value should be according to
1392currently enabled custom themes.
1393
1394This function returns nil if no custom theme specifies a value for VARIABLE."
171fc304 1395 (let ((theme-value (get variable 'theme-value)))
46ce5feb 1396 (if theme-value
d358aa10 1397 (cdr (car theme-value)))))
46ce5feb 1398
46ce5feb
RS
1399(defun custom-theme-recalc-variable (variable)
1400 "Set VARIABLE according to currently enabled custom themes."
1401 (let ((valspec (custom-variable-theme-value variable)))
d358aa10
CY
1402 (if valspec
1403 (put variable 'saved-value valspec)
46ce5feb 1404 (setq valspec (get variable 'standard-value)))
d358aa10
CY
1405 (if (and valspec
1406 (or (get variable 'force-value)
1407 (default-boundp variable)))
1408 (funcall (or (get variable 'custom-set) 'set-default) variable
1409 (eval (car valspec))))))
46ce5feb
RS
1410
1411(defun custom-theme-recalc-face (face)
1412 "Set FACE according to currently enabled custom themes."
05d22d02
CY
1413 (if (get face 'face-alias)
1414 (setq face (get face 'face-alias)))
4983ddea
CY
1415 ;; Reset the faces for each frame.
1416 (dolist (frame (frame-list))
1417 (face-spec-recalc face frame)))
05d22d02 1418
46ce5feb 1419\f
9173deec 1420;;; XEmacs compatibility functions
d358aa10
CY
1421
1422;; In XEmacs, when you reset a Custom Theme, you have to specify the
1423;; theme to reset it to. We just apply the next available theme, so
1424;; just ignore the IGNORED arguments.
1425
e1bab181 1426(defun custom-theme-reset-variables (theme &rest args)
d358aa10 1427 "Reset some variable settings in THEME to their values in other themes.
46ce5feb 1428Each of the arguments ARGS has this form:
e1bab181 1429
d358aa10 1430 (VARIABLE IGNORED)
e1bab181 1431
7e8b9dc3 1432This means reset VARIABLE. (The argument IGNORED is ignored)."
e1bab181 1433 (custom-check-theme theme)
46ce5feb 1434 (dolist (arg args)
d358aa10 1435 (custom-push-theme 'theme-value (car arg) theme 'reset)))
e1bab181
RS
1436
1437(defun custom-reset-variables (&rest args)
d358aa10 1438 "Reset the specs of some variables to their values in other themes.
46ce5feb 1439This creates settings in the `user' theme.
e1bab181 1440
46ce5feb 1441Each of the arguments ARGS has this form:
e1bab181 1442
d358aa10 1443 (VARIABLE IGNORED)
e1bab181 1444
7e8b9dc3 1445This means reset VARIABLE. (The argument IGNORED is ignored)."
e1bab181
RS
1446 (apply 'custom-theme-reset-variables 'user args))
1447
55535639
PJ
1448;;; The End.
1449
1450;; Process the defcustoms for variables loaded before this file.
1451(while custom-declare-variable-list
1452 (apply 'custom-declare-variable (car custom-declare-variable-list))
1453 (setq custom-declare-variable-list (cdr custom-declare-variable-list)))
1454
1455(provide 'custom)
1456
1457;;; custom.el ends here