update
[emacs.git] / .emacs.d / elisp / local / use-package.el
1 ;;; use-package.el --- A use-package declaration for simplifying your .emacs
2
3 ;; Copyright (C) 2012 John Wiegley
4
5 ;; Author: John Wiegley <jwiegley@gmail.com>
6 ;; Maintainer: John Wiegley <jwiegley@gmail.com>
7 ;; Created: 17 Jun 2012
8 ;; Modified: 6 Jul 2016
9 ;; Version: 2.2
10 ;; Package-Requires: ((bind-key "1.0") (diminish "0.44"))
11 ;; Keywords: dotemacs startup speed config package
12 ;; URL: https://github.com/jwiegley/use-package
13
14 ;; This program is free software; you can redistribute it and/or
15 ;; modify it under the terms of the GNU General Public License as
16 ;; published by the Free Software Foundation; either version 2, or (at
17 ;; your option) any later version.
18
19 ;; This program is distributed in the hope that it will be useful, but
20 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 ;; General Public License for more details.
23
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs; see the file COPYING. If not, write to the
26 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
27 ;; Boston, MA 02111-1307, USA.
28
29 ;;; Commentary:
30
31 ;; The `use-package' declaration macro allows you to isolate package
32 ;; configuration in your ".emacs" in a way that is performance-oriented and,
33 ;; well, just tidy. I created it because I have over 80 packages that I use
34 ;; in Emacs, and things were getting difficult to manage. Yet with this
35 ;; utility my total load time is just under 1 second, with no loss of
36 ;; functionality!
37 ;;
38 ;; Please see README.md from the same repository for documentation.
39
40 ;;; Code:
41
42 (require 'bind-key)
43 (require 'bytecomp)
44 (require 'diminish nil t)
45 (require 'bytecomp)
46 (eval-when-compile (require 'cl))
47 (eval-when-compile (require 'regexp-opt))
48
49 (declare-function package-installed-p "package")
50
51 (defgroup use-package nil
52 "A use-package declaration for simplifying your `.emacs'."
53 :group 'startup)
54
55 (defcustom use-package-verbose nil
56 "Whether to report about loading and configuration details.
57
58 If you customize this, then you should require the `use-package'
59 feature in files that use `use-package', even if these files only
60 contain compiled expansions of the macros. If you don't do so,
61 then the expanded macros do their job silently."
62 :type '(choice (const :tag "Quiet" nil) (const :tag "Verbose" t)
63 (const :tag "Debug" debug))
64 :group 'use-package)
65
66 (defcustom use-package-debug nil
67 "Whether to display use-package expansions in a *use-package* buffer."
68 :type 'boolean
69 :group 'use-package)
70
71 (defcustom use-package-check-before-init nil
72 "If non-nil, check that package exists before executing its `:init' block.
73 The check is performed by looking for the module using `locate-library'."
74 :type 'boolean
75 :group 'use-package)
76
77 (defcustom use-package-always-defer nil
78 "If non-nil, assume `:defer t` unless `:demand t` is given."
79 :type 'boolean
80 :group 'use-package)
81
82 (defcustom use-package-always-ensure nil
83 "Treat every package as though it had specified `:ensure SEXP`."
84 :type 'sexp
85 :group 'use-package)
86
87 (defcustom use-package-always-pin nil
88 "Treat every package as though it had specified `:pin SYM."
89 :type 'symbol
90 :group 'use-package)
91
92 (defcustom use-package-minimum-reported-time 0.1
93 "Minimal load time that will be reported.
94
95 Note that `use-package-verbose' has to be set to t, for anything
96 to be reported at all.
97
98 If you customize this, then you should require the `use-package'
99 feature in files that use `use-package', even if these files only
100 contain compiled expansions of the macros. If you don't do so,
101 then the expanded macros do their job silently."
102 :type 'number
103 :group 'use-package)
104
105 (defcustom use-package-inject-hooks nil
106 "If non-nil, add hooks to the `:init' and `:config' sections.
107 In particular, for a given package `foo', the following hooks
108 become available:
109
110 `use-package--foo--pre-init-hook'
111 `use-package--foo--post-init-hook'
112 `use-package--foo--pre-config-hook'
113 `use-package--foo--post-config-hook'
114
115 This way, you can add to these hooks before evalaution of a
116 `use-package` declaration, and exercise some control over what
117 happens.
118
119 Note that if either `pre-init' hooks returns a nil value, that
120 block's user-supplied configuration is not evaluated, so be
121 certain to return `t' if you only wish to add behavior to what
122 the user specified."
123 :type 'boolean
124 :group 'use-package)
125
126 (defcustom use-package-keywords
127 '(:disabled
128 :pin
129 :ensure
130 :if
131 :when
132 :unless
133 :requires
134 :load-path
135 :preface
136 :no-require
137 :bind
138 :bind*
139 :bind-keymap
140 :bind-keymap*
141 :interpreter
142 :mode
143 :commands
144 :defines
145 :functions
146 :defer
147 :init
148 :after
149 :demand
150 :config
151 :diminish
152 :delight)
153 "Establish which keywords are valid, and the order they are processed in.
154
155 Note that `:disabled' is special, in that it causes nothing at all to happen,
156 even if the rest of the use-package declaration is incorrect."
157 :type '(repeat symbol)
158 :group 'use-package)
159
160 (defcustom use-package-expand-minimally nil
161 "If non-nil, make the expanded code as minimal as possible.
162 This disables:
163 - Printing to the *Messages* buffer of slowly-evaluating forms
164 - Capture of load errors (normally redisplayed as warnings)
165 - Conditional loading of packages (load failures become errors)
166 The only advantage is that, if you know your configuration works,
167 then your byte-compiled init file is as minimal as possible."
168 :type 'boolean
169 :group 'use-package)
170
171 (defcustom use-package-enable-imenu-support nil
172 "If non-nil, adjust `lisp-imenu-generic-expression' to include
173 support for finding `use-package' and `require' forms.
174
175 Must be set before loading use-package."
176 :type 'boolean
177 :group 'use-package)
178
179 (when use-package-enable-imenu-support
180 ;; Not defined in Emacs 24
181 (defvar lisp-mode-symbol-regexp
182 "\\(?:\\sw\\|\\s_\\|\\\\.\\)+")
183 (add-to-list
184 'lisp-imenu-generic-expression
185 (list "Package"
186 (purecopy (concat "^\\s-*("
187 (eval-when-compile
188 (regexp-opt
189 '("use-package" "require")
190 t))
191 "\\s-+\\(" lisp-mode-symbol-regexp "\\)"))
192 2)))
193
194 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
195 ;;
196 ;; Utility functions
197 ;;
198
199 (defun use-package-as-symbol (string-or-symbol)
200 "If STRING-OR-SYMBOL is already a symbol, return it. Otherwise
201 convert it to a symbol and return that."
202 (if (symbolp string-or-symbol) string-or-symbol
203 (intern string-or-symbol)))
204
205 (defun use-package-as-string (string-or-symbol)
206 "If STRING-OR-SYMBOL is already a string, return it. Otherwise
207 convert it to a string and return that."
208 (if (stringp string-or-symbol) string-or-symbol
209 (symbol-name string-or-symbol)))
210
211 (defun use-package-load-name (name &optional noerror)
212 "Return a form which will load or require NAME depending on
213 whether it's a string or symbol."
214 (if (stringp name)
215 `(load ,name ',noerror)
216 `(require ',name nil ',noerror)))
217
218 (defun use-package-expand (name label form)
219 "FORM is a list of forms, so `((foo))' if only `foo' is being called."
220 (declare (indent 1))
221 (when form
222 (if use-package-expand-minimally
223 form
224 (let ((err (make-symbol "err")))
225 (list
226 `(condition-case-unless-debug ,err
227 ,(macroexp-progn form)
228 (error
229 (ignore
230 (display-warning 'use-package
231 (format "%s %s: %s"
232 ,name ,label (error-message-string ,err))
233 :error)))))))))
234
235 (put 'use-package-expand 'lisp-indent-function 'defun)
236
237 (defun use-package-hook-injector (name-string keyword body)
238 "Wrap pre/post hook injections around a given keyword form.
239 ARGS is a list of forms, so `((foo))' if only `foo' is being called."
240 (if (not use-package-inject-hooks)
241 (use-package-expand name-string (format "%s" keyword) body)
242 (let ((keyword-name (substring (format "%s" keyword) 1)))
243 (when body
244 `((when ,(macroexp-progn
245 (use-package-expand name-string (format "pre-%s hook" keyword)
246 `((run-hook-with-args-until-failure
247 ',(intern (concat "use-package--" name-string
248 "--pre-" keyword-name "-hook"))))))
249 ,(macroexp-progn
250 (use-package-expand name-string (format "%s" keyword) body))
251 ,(macroexp-progn
252 (use-package-expand name-string (format "post-%s hook" keyword)
253 `((run-hooks
254 ',(intern (concat "use-package--" name-string
255 "--post-" keyword-name "-hook"))))))))))))
256
257 (defun use-package--with-elapsed-timer (text body)
258 "BODY is a list of forms, so `((foo))' if only `foo' is being called."
259 (declare (indent 1))
260 (if use-package-expand-minimally
261 body
262 (let ((nowvar (make-symbol "now")))
263 (if (bound-and-true-p use-package-verbose)
264 `((let ((,nowvar (current-time)))
265 (message "%s..." ,text)
266 (prog1
267 ,(macroexp-progn body)
268 (let ((elapsed
269 (float-time (time-subtract (current-time) ,nowvar))))
270 (if (> elapsed ,use-package-minimum-reported-time)
271 (message "%s...done (%.3fs)" ,text elapsed)
272 (message "%s...done" ,text))))))
273 body))))
274
275 (put 'use-package--with-elapsed-timer 'lisp-indent-function 1)
276
277 (defsubst use-package-error (msg)
278 "Report MSG as an error, so the user knows it came from this package."
279 (error "use-package: %s" msg))
280
281 (defsubst use-package-plist-maybe-put (plist property value)
282 "Add a VALUE for PROPERTY to PLIST, if it does not already exist."
283 (if (plist-member plist property)
284 plist
285 (plist-put plist property value)))
286
287 (defsubst use-package-plist-cons (plist property value)
288 "Cons VALUE onto the head of the list at PROPERTY in PLIST."
289 (plist-put plist property (cons value (plist-get plist property))))
290
291 (defsubst use-package-plist-append (plist property value)
292 "Append VALUE onto the front of the list at PROPERTY in PLIST."
293 (plist-put plist property (append value (plist-get plist property))))
294
295 (defun use-package-plist-delete (plist property)
296 "Delete PROPERTY from PLIST.
297 This is in contrast to merely setting it to 0."
298 (let (p)
299 (while plist
300 (if (not (eq property (car plist)))
301 (setq p (plist-put p (car plist) (nth 1 plist))))
302 (setq plist (cddr plist)))
303 p))
304
305 (defun use-package-split-list (pred xs)
306 (let ((ys (list nil)) (zs (list nil)) flip)
307 (dolist (x xs)
308 (if flip
309 (nconc zs (list x))
310 (if (funcall pred x)
311 (progn
312 (setq flip t)
313 (nconc zs (list x)))
314 (nconc ys (list x)))))
315 (cons (cdr ys) (cdr zs))))
316
317 (defun use-package-keyword-index (keyword)
318 (loop named outer
319 with index = 0
320 for k in use-package-keywords do
321 (if (eq k keyword)
322 (return-from outer index))
323 (incf index)))
324
325 (defun use-package-sort-keywords (plist)
326 (let (plist-grouped)
327 (while plist
328 (push (cons (car plist) (cadr plist))
329 plist-grouped)
330 (setq plist (cddr plist)))
331 (let (result)
332 (dolist (x
333 (nreverse
334 (sort plist-grouped
335 #'(lambda (l r) (< (use-package-keyword-index (car l))
336 (use-package-keyword-index (car r)))))))
337 (setq result (cons (car x) (cons (cdr x) result))))
338 result)))
339
340 (defsubst use-package-concat (&rest elems)
341 "Delete all empty lists from ELEMS (nil or (list nil)), and append them."
342 (apply #'nconc (delete nil (delete (list nil) elems))))
343
344 (defconst use-package-font-lock-keywords
345 '(("(\\(use-package\\)\\_>[ \t']*\\(\\(?:\\sw\\|\\s_\\)+\\)?"
346 (1 font-lock-keyword-face)
347 (2 font-lock-constant-face nil t))))
348
349 (font-lock-add-keywords 'emacs-lisp-mode use-package-font-lock-keywords)
350
351 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
352 ;;
353 ;; Keyword processing
354 ;;
355
356 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
357 ;;
358 ;; Normalization functions
359 ;;
360
361 (defun use-package-normalize-plist (name input)
362 "Given a pseudo-plist, normalize it to a regular plist."
363 (unless (null input)
364 (let* ((keyword (car input))
365 (xs (use-package-split-list #'keywordp (cdr input)))
366 (args (car xs))
367 (tail (cdr xs))
368 (normalizer (intern (concat "use-package-normalize/"
369 (symbol-name keyword))))
370 (arg
371 (cond
372 ((eq keyword :disabled)
373 (use-package-normalize-plist name tail))
374 ((functionp normalizer)
375 (funcall normalizer name keyword args))
376 ((= (length args) 1)
377 (car args))
378 (t
379 args))))
380 (if (memq keyword use-package-keywords)
381 (cons keyword
382 (cons arg (use-package-normalize-plist name tail)))
383 (use-package-error (format "Unrecognized keyword: %s" keyword))))))
384
385 (defun use-package-process-keywords (name plist &optional state)
386 "Process the next keyword in the free-form property list PLIST.
387 The values in the PLIST have each been normalized by the function
388 use-package-normalize/KEYWORD (minus the colon).
389
390 STATE is a property list that the function may modify and/or
391 query. This is useful if a package defines multiple keywords and
392 wishes them to have some kind of stateful interaction.
393
394 Unless the KEYWORD being processed intends to ignore remaining
395 keywords, it must call this function recursively, passing in the
396 plist with its keyword and argument removed, and passing in the
397 next value for the STATE."
398 (declare (indent 1))
399 (unless (null plist)
400 (let* ((keyword (car plist))
401 (arg (cadr plist))
402 (rest (cddr plist)))
403 (unless (keywordp keyword)
404 (use-package-error (format "%s is not a keyword" keyword)))
405 (let* ((handler (concat "use-package-handler/" (symbol-name keyword)))
406 (handler-sym (intern handler)))
407 (if (functionp handler-sym)
408 (funcall handler-sym name keyword arg rest state)
409 (use-package-error
410 (format "Keyword handler not defined: %s" handler)))))))
411
412 (put 'use-package-process-keywords 'lisp-indent-function 'defun)
413
414 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
415 ;;
416 ;; :pin
417 ;;
418
419 (defun use-package-only-one (label args f)
420 "Call F on the first member of ARGS if it has exactly one element."
421 (declare (indent 1))
422 (cond
423 ((and (listp args) (listp (cdr args))
424 (= (length args) 1))
425 (funcall f label (car args)))
426 (t
427 (use-package-error
428 (concat label " wants exactly one argument")))))
429
430 (put 'use-package-only-one 'lisp-indent-function 'defun)
431
432 (defun use-package-normalize/:pin (name keyword args)
433 (use-package-only-one (symbol-name keyword) args
434 (lambda (label arg)
435 (cond
436 ((stringp arg) arg)
437 ((symbolp arg) (symbol-name arg))
438 (t
439 (use-package-error
440 ":pin wants an archive name (a string)"))))))
441
442 (eval-when-compile
443 (defvar package-pinned-packages)
444 (defvar package-archives))
445
446 (defun use-package--archive-exists-p (archive)
447 "Check if a given ARCHIVE is enabled.
448
449 ARCHIVE can be a string or a symbol or 'manual to indicate a
450 manually updated package."
451 (if (member archive '(manual "manual"))
452 't
453 (let ((valid nil))
454 (dolist (pa package-archives)
455 (when (member archive (list (car pa) (intern (car pa))))
456 (setq valid 't)))
457 valid)))
458
459 (defun use-package-pin-package (package archive)
460 "Pin PACKAGE to ARCHIVE."
461 (unless (boundp 'package-pinned-packages)
462 (setq package-pinned-packages ()))
463 (let ((archive-symbol (if (symbolp archive) archive (intern archive)))
464 (archive-name (if (stringp archive) archive (symbol-name archive))))
465 (if (use-package--archive-exists-p archive-symbol)
466 (add-to-list 'package-pinned-packages (cons package archive-name))
467 (error "Archive '%s' requested for package '%s' is not available."
468 archive-name package))
469 (unless (bound-and-true-p package--initialized)
470 (package-initialize t))))
471
472 (defun use-package-handler/:pin (name keyword archive-name rest state)
473 (let ((body (use-package-process-keywords name rest state))
474 (pin-form (if archive-name
475 `(use-package-pin-package ',(use-package-as-symbol name)
476 ,archive-name))))
477 ;; Pinning should occur just before ensuring
478 ;; See `use-package-handler/:ensure'.
479 (if (bound-and-true-p byte-compile-current-file)
480 (eval pin-form) ; Eval when byte-compiling,
481 (push pin-form body)) ; or else wait until runtime.
482 body))
483
484 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
485 ;;
486 ;; :ensure
487 ;;
488 (defvar package-archive-contents)
489 (defun use-package-normalize/:ensure (name keyword args)
490 (if (null args)
491 t
492 (use-package-only-one (symbol-name keyword) args
493 (lambda (label arg)
494 (if (symbolp arg)
495 arg
496 (use-package-error
497 (concat ":ensure wants an optional package name "
498 "(an unquoted symbol name)")))))))
499
500 (defun use-package-ensure-elpa (package &optional no-refresh)
501 (if (package-installed-p package)
502 t
503 (if (and (not no-refresh)
504 (assoc package (bound-and-true-p package-pinned-packages)))
505 (package-read-all-archive-contents))
506 (if (or (assoc package package-archive-contents) no-refresh)
507 (package-install package)
508 (progn
509 (package-refresh-contents)
510 (use-package-ensure-elpa package t)))))
511
512 (defun use-package-handler/:ensure (name keyword ensure rest state)
513 (let* ((body (use-package-process-keywords name rest state))
514 (package-name (or (and (eq ensure t) (use-package-as-symbol name)) ensure))
515 (ensure-form (if package-name
516 `(progn (require 'package)
517 (use-package-ensure-elpa ',package-name)))))
518 ;; We want to avoid installing packages when the `use-package'
519 ;; macro is being macro-expanded by elisp completion (see
520 ;; `lisp--local-variables'), but still do install packages when
521 ;; byte-compiling to avoid requiring `package' at runtime.
522 (if (bound-and-true-p byte-compile-current-file)
523 (eval ensure-form) ; Eval when byte-compiling,
524 (push ensure-form body)) ; or else wait until runtime.
525 body))
526
527 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
528 ;;
529 ;; :if, :when and :unless
530 ;;
531
532 (defsubst use-package-normalize-value (label arg)
533 "Normalize a value."
534 (cond ((symbolp arg)
535 `(symbol-value ',arg))
536 ((functionp arg)
537 `(funcall #',arg))
538 (t arg)))
539
540 (defun use-package-normalize-test (name keyword args)
541 (use-package-only-one (symbol-name keyword) args
542 #'use-package-normalize-value))
543
544 (defalias 'use-package-normalize/:if 'use-package-normalize-test)
545 (defalias 'use-package-normalize/:when 'use-package-normalize-test)
546 (defalias 'use-package-normalize/:unless 'use-package-normalize-test)
547
548 (defun use-package-handler/:if (name keyword pred rest state)
549 (let ((body (use-package-process-keywords name rest state)))
550 `((when ,pred ,@body))))
551
552 (defalias 'use-package-handler/:when 'use-package-handler/:if)
553
554 (defun use-package-handler/:unless (name keyword pred rest state)
555 (let ((body (use-package-process-keywords name rest state)))
556 `((unless ,pred ,@body))))
557
558 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
559 ;;
560 ;; :requires
561 ;;
562
563 (defun use-package-as-one (label args f)
564 "Call F on the first element of ARGS if it has one element, or all of ARGS."
565 (declare (indent 1))
566 (if (and (listp args) (listp (cdr args)))
567 (if (= (length args) 1)
568 (funcall f label (car args))
569 (funcall f label args))
570 (use-package-error
571 (concat label " wants a list"))))
572
573 (put 'use-package-as-one 'lisp-indent-function 'defun)
574
575 (defun use-package-normalize-symbols (label arg &optional recursed)
576 "Normalize a list of symbols."
577 (cond
578 ((symbolp arg)
579 (list arg))
580 ((and (not recursed) (listp arg) (listp (cdr arg)))
581 (mapcar #'(lambda (x) (car (use-package-normalize-symbols label x t))) arg))
582 (t
583 (use-package-error
584 (concat label " wants a symbol, or list of symbols")))))
585
586 (defun use-package-normalize-symlist (name keyword args)
587 (use-package-as-one (symbol-name keyword) args
588 #'use-package-normalize-symbols))
589
590 (defalias 'use-package-normalize/:requires 'use-package-normalize-symlist)
591
592 (defun use-package-handler/:requires (name keyword requires rest state)
593 (let ((body (use-package-process-keywords name rest state)))
594 (if (null requires)
595 body
596 `((when ,(if (listp requires)
597 `(not (member nil (mapcar #'featurep ',requires)))
598 `(featurep ',requires))
599 ,@body)))))
600
601 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
602 ;;
603 ;; :load-path
604 ;;
605
606 (defun use-package-normalize-paths (label arg &optional recursed)
607 "Normalize a list of filesystem paths."
608 (cond
609 ((and arg (or (symbolp arg) (functionp arg)))
610 (let ((value (use-package-normalize-value label arg)))
611 (use-package-normalize-paths label (eval value))))
612 ((stringp arg)
613 (let ((path (if (file-name-absolute-p arg)
614 arg
615 (expand-file-name arg user-emacs-directory))))
616 (list path)))
617 ((and (not recursed) (listp arg) (listp (cdr arg)))
618 (mapcar #'(lambda (x)
619 (car (use-package-normalize-paths label x t))) arg))
620 (t
621 (use-package-error
622 (concat label " wants a directory path, or list of paths")))))
623
624 (defun use-package-normalize/:load-path (name keyword args)
625 (use-package-as-one (symbol-name keyword) args
626 #'use-package-normalize-paths))
627
628 (defun use-package-handler/:load-path (name keyword arg rest state)
629 (let ((body (use-package-process-keywords name rest state)))
630 (use-package-concat
631 (mapcar #'(lambda (path)
632 `(eval-and-compile (add-to-list 'load-path ,path))) arg)
633 body)))
634
635 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
636 ;;
637 ;; :no-require
638 ;;
639
640 (defun use-package-normalize-predicate (name keyword args)
641 (if (null args)
642 t
643 (use-package-only-one (symbol-name keyword) args
644 #'use-package-normalize-value)))
645
646 (defalias 'use-package-normalize/:no-require 'use-package-normalize-predicate)
647
648 (defun use-package-handler/:no-require (name keyword arg rest state)
649 ;; This keyword has no functional meaning.
650 (use-package-process-keywords name rest state))
651
652 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
653 ;;
654 ;; :preface
655 ;;
656
657 (defun use-package-normalize-form (label args)
658 "Given a list of forms, return it wrapped in `progn'."
659 (unless (listp (car args))
660 (use-package-error (concat label " wants a sexp or list of sexps")))
661 (mapcar #'(lambda (form)
662 (if (and (consp form)
663 (eq (car form) 'use-package))
664 (macroexpand form)
665 form)) args))
666
667 (defun use-package-normalize-forms (name keyword args)
668 (use-package-normalize-form (symbol-name keyword) args))
669
670 (defalias 'use-package-normalize/:preface 'use-package-normalize-forms)
671
672 (defun use-package-handler/:preface (name keyword arg rest state)
673 (let ((body (use-package-process-keywords name rest state)))
674 (use-package-concat
675 (unless (null arg)
676 `((eval-and-compile ,@arg)))
677 body)))
678
679 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
680 ;;
681 ;; :bind, :bind*
682 ;;
683
684 (defsubst use-package-is-sympair (x &optional allow-vector)
685 "Return t if X has the type (STRING . SYMBOL)."
686 (and (consp x)
687 (or (stringp (car x))
688 (and allow-vector (vectorp (car x))))
689 (symbolp (cdr x))))
690
691 (defsubst use-package-is-string-pair (x)
692 "Return t if X has the type (STRING . STRING)."
693 (and (consp x)
694 (stringp (car x))
695 (stringp (cdr x))))
696
697 (defun use-package-normalize-pairs
698 (name label arg &optional recursed allow-vector allow-string-cdrs)
699 "Normalize a list of string/symbol pairs.
700 If RECURSED is non-nil, recurse into sublists.
701 If ALLOW-VECTOR is non-nil, then the key to bind may specify a
702 vector of keys, as accepted by `define-key'.
703 If ALLOW-STRING-CDRS is non-nil, then the command name to bind to
704 may also be a string, as accepted by `define-key'."
705 (cond
706 ((or (stringp arg) (and allow-vector (vectorp arg)))
707 (list (cons arg (use-package-as-symbol name))))
708 ((use-package-is-sympair arg allow-vector)
709 (list arg))
710 ((and (not recursed) (listp arg) (listp (cdr arg)))
711 (mapcar #'(lambda (x)
712 (let ((ret (use-package-normalize-pairs
713 name label x t allow-vector allow-string-cdrs)))
714 (if (listp ret)
715 (car ret)
716 ret))) arg))
717 ((and allow-string-cdrs (use-package-is-string-pair arg))
718 (list arg))
719 (t arg)))
720
721 (defun use-package-normalize-binder (name keyword args)
722 (use-package-as-one (symbol-name keyword) args
723 (lambda (label arg)
724 (use-package-normalize-pairs name label arg nil t t))))
725
726 (defalias 'use-package-normalize/:bind 'use-package-normalize-binder)
727 (defalias 'use-package-normalize/:bind* 'use-package-normalize-binder)
728
729 (defun use-package-handler/:bind
730 (name keyword arg rest state &optional bind-macro)
731 (let ((commands (remq nil (mapcar #'(lambda (arg)
732 (if (listp arg)
733 (cdr arg)
734 nil)) arg))))
735 (use-package-concat
736 (use-package-process-keywords name
737 (use-package-sort-keywords
738 (use-package-plist-maybe-put rest :defer t))
739 (use-package-plist-append state :commands commands))
740 `((ignore
741 ,(macroexpand
742 `(,(if bind-macro bind-macro 'bind-keys)
743 :package ,name ,@arg)))))))
744
745 (defun use-package-handler/:bind* (name keyword arg rest state)
746 (use-package-handler/:bind name keyword arg rest state 'bind-keys*))
747
748 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
749 ;;
750 ;; :bind-keymap, :bind-keymap*
751 ;;
752
753 (defalias 'use-package-normalize/:bind-keymap 'use-package-normalize-binder)
754 (defalias 'use-package-normalize/:bind-keymap* 'use-package-normalize-binder)
755
756 (defun use-package-autoload-keymap (keymap-symbol package override)
757 "Loads PACKAGE and then binds the key sequence used to invoke
758 this function to KEYMAP-SYMBOL. It then simulates pressing the
759 same key sequence a again, so that the next key pressed is routed
760 to the newly loaded keymap.
761
762 This function supports use-package's :bind-keymap keyword. It
763 works by binding the given key sequence to an invocation of this
764 function for a particular keymap. The keymap is expected to be
765 defined by the package. In this way, loading the package is
766 deferred until the prefix key sequence is pressed."
767 (if (not (require package nil t))
768 (use-package-error (format "Cannot load package.el: %s" package))
769 (if (and (boundp keymap-symbol)
770 (keymapp (symbol-value keymap-symbol)))
771 (let* ((kv (this-command-keys-vector))
772 (key (key-description kv))
773 (keymap (symbol-value keymap-symbol)))
774 (if override
775 (bind-key* key keymap)
776 (bind-key key keymap))
777 (setq unread-command-events
778 (listify-key-sequence kv)))
779 (use-package-error
780 (format "use-package: package.el %s failed to define keymap %s"
781 package keymap-symbol)))))
782
783 (defun use-package-handler/:bind-keymap
784 (name keyword arg rest state &optional override)
785 (let ((form (mapcar
786 #'(lambda (binding)
787 `(,(if override
788 'bind-key*
789 'bind-key)
790 ,(car binding)
791 #'(lambda ()
792 (interactive)
793 (use-package-autoload-keymap
794 ',(cdr binding) ',(use-package-as-symbol name) ,override)))) arg)))
795 (use-package-concat
796 (use-package-process-keywords name
797 (use-package-sort-keywords
798 (use-package-plist-maybe-put rest :defer t))
799 state)
800 `((ignore ,@form)))))
801
802 (defun use-package-handler/:bind-keymap* (name keyword arg rest state)
803 (use-package-handler/:bind-keymap name keyword arg rest state t))
804
805 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
806 ;;
807 ;; :interpreter
808 ;;
809
810 (defun use-package-normalize-mode (name keyword args)
811 (use-package-as-one (symbol-name keyword) args
812 (apply-partially #'use-package-normalize-pairs name)))
813
814 (defalias 'use-package-normalize/:interpreter 'use-package-normalize-mode)
815
816 (defun use-package-handler/:interpreter (name keyword arg rest state)
817 (let* (commands
818 (form (mapcar #'(lambda (interpreter)
819 (push (cdr interpreter) commands)
820 `(add-to-list 'interpreter-mode-alist ',interpreter)) arg)))
821 (use-package-concat
822 (use-package-process-keywords name
823 (use-package-sort-keywords
824 (use-package-plist-maybe-put rest :defer t))
825 (use-package-plist-append state :commands commands))
826 `((ignore ,@form)))))
827
828 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
829 ;;
830 ;; :mode
831 ;;
832
833 (defalias 'use-package-normalize/:mode 'use-package-normalize-mode)
834
835 (defun use-package-handler/:mode (name keyword arg rest state)
836 (let* (commands
837 (form (mapcar #'(lambda (mode)
838 (push (cdr mode) commands)
839 `(add-to-list 'auto-mode-alist ',mode)) arg)))
840 (use-package-concat
841 (use-package-process-keywords name
842 (use-package-sort-keywords
843 (use-package-plist-maybe-put rest :defer t))
844 (use-package-plist-append state :commands commands))
845 `((ignore ,@form)))))
846
847 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
848 ;;
849 ;; :commands
850 ;;
851
852 (defalias 'use-package-normalize/:commands 'use-package-normalize-symlist)
853
854 (defun use-package-handler/:commands (name keyword arg rest state)
855 ;; The actual processing for commands is done in :defer
856 (use-package-process-keywords name
857 (use-package-sort-keywords
858 (use-package-plist-maybe-put rest :defer t))
859 (use-package-plist-append state :commands arg)))
860
861 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
862 ;;
863 ;; :defines
864 ;;
865
866 (defalias 'use-package-normalize/:defines 'use-package-normalize-symlist)
867
868 (defun use-package-handler/:defines (name keyword arg rest state)
869 (let ((body (use-package-process-keywords name rest state)))
870 body))
871
872 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
873 ;;
874 ;; :functions
875 ;;
876
877 (defalias 'use-package-normalize/:functions 'use-package-normalize-symlist)
878
879 (defun use-package-handler/:functions (name keyword arg rest state)
880 (let ((body (use-package-process-keywords name rest state)))
881 (if (not (bound-and-true-p byte-compile-current-file))
882 body
883 (use-package-concat
884 (unless (null arg)
885 `((eval-when-compile
886 ,@(mapcar
887 #'(lambda (fn)
888 `(declare-function ,fn ,(use-package-as-string name))) arg))))
889 body))))
890
891 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
892 ;;
893 ;; :defer
894 ;;
895
896 (defalias 'use-package-normalize/:defer 'use-package-normalize-predicate)
897
898 (defun use-package-handler/:defer (name keyword arg rest state)
899 (let ((body (use-package-process-keywords name rest
900 (plist-put state :deferred t)))
901 (name-string (use-package-as-string name)))
902 (use-package-concat
903 ;; Load the package after a set amount of idle time, if the argument to
904 ;; `:defer' was a number.
905 (when (numberp arg)
906 `((run-with-idle-timer ,arg nil #'require ',(use-package-as-symbol name) nil t)))
907
908 ;; Since we deferring load, establish any necessary autoloads, and also
909 ;; keep the byte-compiler happy.
910 (apply
911 #'nconc
912 (mapcar #'(lambda (command)
913 (when (not (stringp command))
914 (append
915 `((unless (fboundp ',command)
916 (autoload #',command ,name-string nil t)))
917 (when (bound-and-true-p byte-compile-current-file)
918 `((eval-when-compile
919 (declare-function ,command ,name-string)))))))
920 (delete-dups (plist-get state :commands))))
921
922 body)))
923
924
925 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
926 ;;
927 ;; :after
928 ;;
929
930 (defalias 'use-package-normalize/:after 'use-package-normalize-symlist)
931
932 (defun use-package-require-after-load (features name)
933 "Return form for after any of FEATURES require NAME."
934 `(progn
935 ,@(mapcar
936 (lambda (feat)
937 `(eval-after-load
938 (quote ,feat)
939 (quote (require (quote ,name) nil t))))
940 features)))
941
942 (defun use-package-handler/:after (name keyword arg rest state)
943 (let ((body (use-package-process-keywords name rest
944 (plist-put state :deferred t)))
945 (name-string (use-package-as-string name)))
946 (use-package-concat
947 (when arg
948 (list (use-package-require-after-load arg name)))
949 body)))
950
951 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
952 ;;
953 ;; :demand
954 ;;
955
956 (defalias 'use-package-normalize/:demand 'use-package-normalize-predicate)
957
958 (defun use-package-handler/:demand (name keyword arg rest state)
959 (use-package-process-keywords name rest
960 (use-package-plist-delete state :deferred)))
961
962 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
963 ;;
964 ;; :init
965 ;;
966
967 (defalias 'use-package-normalize/:init 'use-package-normalize-forms)
968
969 (defun use-package-handler/:init (name keyword arg rest state)
970 (let ((body (use-package-process-keywords name rest state)))
971 (use-package-concat
972 ;; The user's initializations
973 (let ((init-body
974 (use-package-hook-injector (use-package-as-string name)
975 :init arg)))
976 (if use-package-check-before-init
977 `((if (locate-library ,(use-package-as-string name))
978 ,(macroexp-progn init-body)))
979 init-body))
980 body)))
981
982 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
983 ;;
984 ;; :config
985 ;;
986
987 (defalias 'use-package-normalize/:config 'use-package-normalize-forms)
988
989 (defun use-package-handler/:config (name keyword arg rest state)
990 (let* ((body (use-package-process-keywords name rest state))
991 (name-symbol (use-package-as-symbol name))
992 (config-body
993 (if (equal arg '(t))
994 body
995 (use-package--with-elapsed-timer
996 (format "Configuring package %s" name-symbol)
997 (use-package-concat
998 (use-package-hook-injector (symbol-name name-symbol)
999 :config arg)
1000 body
1001 (list t))))))
1002 (if (plist-get state :deferred)
1003 (unless (or (null config-body) (equal config-body '(t)))
1004 `((eval-after-load ,(if (symbolp name) `',name name)
1005 ',(macroexp-progn config-body))))
1006 (use-package--with-elapsed-timer
1007 (format "Loading package %s" name)
1008 (if use-package-expand-minimally
1009 (use-package-concat
1010 (list (use-package-load-name name))
1011 config-body)
1012 `((if (not ,(use-package-load-name name t))
1013 (ignore
1014 (message (format "Cannot load %s" ',name)))
1015 ,@config-body)))))))
1016
1017 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
1018 ;;
1019 ;; :diminish
1020
1021 (defun use-package-normalize-diminish (name label arg &optional recursed)
1022 "Normalize the arguments to diminish down to a list of one of two forms:
1023 SYMBOL
1024 (SYMBOL . STRING)"
1025 (cond
1026 ((symbolp arg)
1027 (list arg))
1028 ((stringp arg)
1029 (list (cons (intern (concat (use-package-as-string name) "-mode")) arg)))
1030 ((and (consp arg) (stringp (cdr arg)))
1031 (list arg))
1032 ((and (not recursed) (listp arg) (listp (cdr arg)))
1033 (mapcar #'(lambda (x) (car (use-package-normalize-diminish
1034 name label x t))) arg))
1035 (t
1036 (use-package-error
1037 (concat label " wants a string, symbol, "
1038 "(symbol . string) or list of these")))))
1039
1040 (defun use-package-normalize/:diminish (name keyword args)
1041 (use-package-as-one (symbol-name keyword) args
1042 (apply-partially #'use-package-normalize-diminish name)))
1043
1044 (defun use-package-handler/:diminish (name keyword arg rest state)
1045 (let ((body (use-package-process-keywords name rest state)))
1046 (use-package-concat
1047 (mapcar #'(lambda (var)
1048 `(if (fboundp 'diminish)
1049 ,(if (consp var)
1050 `(diminish ',(car var) ,(cdr var))
1051 `(diminish ',var))))
1052 arg)
1053 body)))
1054
1055 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
1056 ;;
1057 ;; :delight
1058 ;;
1059
1060 (defun use-package-normalize/:delight (name keyword args)
1061 "Normalize arguments to delight."
1062 (cond
1063 ((and (= (length args) 1)
1064 (symbolp (car args)))
1065 (list (car args) nil name))
1066 ((and (= (length args) 2)
1067 (symbolp (car args)))
1068 (list (car args) (cadr args) (use-package-as-symbol name)))
1069 ((and (= (length args) 3)
1070 (symbolp (car args)))
1071 args)
1072 (t
1073 (use-package-error ":delight expects same args as delight function"))))
1074
1075 (defun use-package-handler/:delight (name keyword args rest state)
1076 (let ((body (use-package-process-keywords name rest state)))
1077 (use-package-concat
1078 body
1079 `((delight (quote ,(nth 0 args)) ,(nth 1 args) (quote ,(nth 2 args))) t))))
1080
1081 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
1082 ;;
1083 ;; The main macro
1084 ;;
1085
1086 ;;;###autoload
1087 (defmacro use-package (name &rest args)
1088 "Declare an Emacs package by specifying a group of configuration options.
1089
1090 For full documentation, please see the README file that came with
1091 this file. Usage:
1092
1093 (use-package package-name
1094 [:keyword [option]]...)
1095
1096 :init Code to run before PACKAGE-NAME has been loaded.
1097 :config Code to run after PACKAGE-NAME has been loaded. Note that if
1098 loading is deferred for any reason, this code does not execute
1099 until the lazy load has occurred.
1100 :preface Code to be run before everything except `:disabled'; this can
1101 be used to define functions for use in `:if', or that should be
1102 seen by the byte-compiler.
1103
1104 :mode Form to be added to `auto-mode-alist'.
1105 :interpreter Form to be added to `interpreter-mode-alist'.
1106
1107 :commands Define autoloads for commands that will be defined by the
1108 package. This is useful if the package is being lazily loaded,
1109 and you wish to conditionally call functions in your `:init'
1110 block that are defined in the package.
1111
1112 :bind Bind keys, and define autoloads for the bound commands.
1113 :bind* Bind keys, and define autoloads for the bound commands,
1114 *overriding all minor mode bindings*.
1115 :bind-keymap Bind a key prefix to an auto-loaded keymap defined in the
1116 package. This is like `:bind', but for keymaps.
1117 :bind-keymap* Like `:bind-keymap', but overrides all minor mode bindings
1118
1119 :defer Defer loading of a package -- this is implied when using
1120 `:commands', `:bind', `:bind*', `:mode' or `:interpreter'.
1121 This can be an integer, to force loading after N seconds of
1122 idle time, if the package has not already been loaded.
1123
1124 :after Defer loading of a package until after any of the named
1125 features are loaded.
1126
1127 :demand Prevent deferred loading in all cases.
1128
1129 :if EXPR Initialize and load only if EXPR evaluates to a non-nil value.
1130 :disabled The package is ignored completely if this keyword is present.
1131 :defines Declare certain variables to silence the byte-compiler.
1132 :functions Declare certain functions to silence the byte-compiler.
1133 :load-path Add to the `load-path' before attempting to load the package.
1134 :diminish Support for diminish.el (if installed).
1135 :ensure Loads the package using package.el if necessary.
1136 :pin Pin the package to an archive."
1137 (declare (indent 1))
1138 (unless (member :disabled args)
1139 (let* ((name-symbol (if (stringp name) (intern name) name))
1140 (args0 (use-package-plist-maybe-put
1141 (use-package-normalize-plist name args)
1142 :config '(t)))
1143 (args* (use-package-sort-keywords
1144 (if use-package-always-ensure
1145 (use-package-plist-maybe-put
1146 args0 :ensure use-package-always-ensure)
1147 args0)))
1148 (args* (use-package-sort-keywords
1149 (if use-package-always-pin
1150 (use-package-plist-maybe-put
1151 args* :pin use-package-always-pin)
1152 args*))))
1153
1154 ;; When byte-compiling, pre-load the package so all its symbols are in
1155 ;; scope.
1156 (if (bound-and-true-p byte-compile-current-file)
1157 (setq args*
1158 (use-package-plist-cons
1159 args* :preface
1160 `(eval-when-compile
1161 ,@(mapcar #'(lambda (var) `(defvar ,var))
1162 (plist-get args* :defines))
1163 (with-demoted-errors
1164 ,(format "Cannot load %s: %%S" name)
1165 ,(if (eq use-package-verbose 'debug)
1166 `(message "Compiling package %s" ',name-symbol))
1167 ,(unless (plist-get args* :no-require)
1168 (use-package-load-name name)))))))
1169
1170 (let ((body
1171 (macroexp-progn
1172 (use-package-process-keywords name args*
1173 (and use-package-always-defer (list :deferred t))))))
1174 (if use-package-debug
1175 (display-buffer
1176 (save-current-buffer
1177 (let ((buf (get-buffer-create "*use-package*")))
1178 (with-current-buffer buf
1179 (delete-region (point-min) (point-max))
1180 (emacs-lisp-mode)
1181 (insert (pp-to-string body)))
1182 buf))))
1183 body))))
1184
1185
1186 (put 'use-package 'lisp-indent-function 'defun)
1187
1188 (provide 'use-package)
1189
1190 ;; Local Variables:
1191 ;; indent-tabs-mode: nil
1192 ;; End:
1193
1194 ;;; use-package.el ends here