use_package-2.3/0000755000175000017500000000000013004444223013453 5ustar dogslegdogsleguse_package-2.3/use-package-tests.el0000644000175000017500000000312113001260555017320 0ustar dogslegdogsleg;;; use-package-tests.el --- Tests for use-package.el ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2, or (at ;; your option) any later version. ;; This program is distributed in the hope that it will be useful, but ;; WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ;; General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs; see the file COPYING. If not, write to the ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, ;; Boston, MA 02111-1307, USA. ;;; Commentary: ;; ;;; Code: (require 'ert) (require 'use-package) (ert-deftest use-package-mplist-get () (let ((mplist '(:foo bar baz bal :blob plap plup :blam)) (tests '((:foo . (bar baz bal)) (:blob . (plap plup)) (:blam . t) (:blow . nil)))) (mapc (lambda (test) (should (equal (use-package-mplist-get mplist (car test)) (cdr test)))) tests))) (ert-deftest use-package-mplist-keys () (should (equal (use-package-mplist-keys '(:foo bar baz bal :blob plap plup :blam)) '(:foo :blob :blam)))) ;; Local Variables: ;; indent-tabs-mode: nil ;; no-byte-compile: t ;; no-update-autoloads: t ;; End: ;;; use-package-tests.el ends here use_package-2.3/use-package.el0000644000175000017500000012461113001260555016170 0ustar dogslegdogsleg;;; use-package.el --- A use-package declaration for simplifying your .emacs ;; Copyright (C) 2012 John Wiegley ;; Author: John Wiegley ;; Maintainer: John Wiegley ;; Created: 17 Jun 2012 ;; Modified: 17 Oct 2016 ;; Version: 2.3 ;; Package-Requires: ((bind-key "1.0") (diminish "0.44")) ;; Keywords: dotemacs startup speed config package ;; URL: https://github.com/jwiegley/use-package ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2, or (at ;; your option) any later version. ;; This program is distributed in the hope that it will be useful, but ;; WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ;; General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs; see the file COPYING. If not, write to the ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, ;; Boston, MA 02111-1307, USA. ;;; Commentary: ;; The `use-package' declaration macro allows you to isolate package ;; configuration in your ".emacs" in a way that is performance-oriented and, ;; well, just tidy. I created it because I have over 80 packages that I use ;; in Emacs, and things were getting difficult to manage. Yet with this ;; utility my total load time is just under 1 second, with no loss of ;; functionality! ;; ;; Please see README.md from the same repository for documentation. ;;; Code: (require 'bind-key) (require 'bytecomp) (require 'diminish nil t) (require 'bytecomp) (eval-when-compile (require 'cl)) (eval-when-compile (require 'regexp-opt)) (declare-function package-installed-p "package") (defgroup use-package nil "A use-package declaration for simplifying your `.emacs'." :group 'startup) (defcustom use-package-verbose nil "Whether to report about loading and configuration details. If you customize this, then you should require the `use-package' feature in files that use `use-package', even if these files only contain compiled expansions of the macros. If you don't do so, then the expanded macros do their job silently." :type '(choice (const :tag "Quiet" nil) (const :tag "Verbose" t) (const :tag "Debug" debug)) :group 'use-package) (defcustom use-package-debug nil "Whether to display use-package expansions in a *use-package* buffer." :type 'boolean :group 'use-package) (defcustom use-package-check-before-init nil "If non-nil, check that package exists before executing its `:init' block. The check is performed by looking for the module using `locate-library'." :type 'boolean :group 'use-package) (defcustom use-package-always-defer nil "If non-nil, assume `:defer t` unless `:demand t` is given." :type 'boolean :group 'use-package) (defcustom use-package-always-ensure nil "Treat every package as though it had specified `:ensure SEXP`." :type 'sexp :group 'use-package) (defcustom use-package-always-pin nil "Treat every package as though it had specified `:pin SYM." :type 'symbol :group 'use-package) (defcustom use-package-minimum-reported-time 0.1 "Minimal load time that will be reported. Note that `use-package-verbose' has to be set to t, for anything to be reported at all. If you customize this, then you should require the `use-package' feature in files that use `use-package', even if these files only contain compiled expansions of the macros. If you don't do so, then the expanded macros do their job silently." :type 'number :group 'use-package) (defcustom use-package-inject-hooks nil "If non-nil, add hooks to the `:init' and `:config' sections. In particular, for a given package `foo', the following hooks become available: `use-package--foo--pre-init-hook' `use-package--foo--post-init-hook' `use-package--foo--pre-config-hook' `use-package--foo--post-config-hook' This way, you can add to these hooks before evalaution of a `use-package` declaration, and exercise some control over what happens. Note that if either `pre-init' hooks returns a nil value, that block's user-supplied configuration is not evaluated, so be certain to return `t' if you only wish to add behavior to what the user specified." :type 'boolean :group 'use-package) (defcustom use-package-keywords '(:disabled :pin :ensure :if :when :unless :requires :load-path :preface :no-require :bind :bind* :bind-keymap :bind-keymap* :interpreter :mode :commands :defines :functions :defer :init :after :demand :config :diminish :delight) "Establish which keywords are valid, and the order they are processed in. Note that `:disabled' is special, in that it causes nothing at all to happen, even if the rest of the use-package declaration is incorrect." :type '(repeat symbol) :group 'use-package) (defcustom use-package-expand-minimally nil "If non-nil, make the expanded code as minimal as possible. This disables: - Printing to the *Messages* buffer of slowly-evaluating forms - Capture of load errors (normally redisplayed as warnings) - Conditional loading of packages (load failures become errors) The only advantage is that, if you know your configuration works, then your byte-compiled init file is as minimal as possible." :type 'boolean :group 'use-package) (defcustom use-package-enable-imenu-support nil "If non-nil, adjust `lisp-imenu-generic-expression' to include support for finding `use-package' and `require' forms. Must be set before loading use-package." :type 'boolean :group 'use-package) (when use-package-enable-imenu-support ;; Not defined in Emacs 24 (defvar lisp-mode-symbol-regexp "\\(?:\\sw\\|\\s_\\|\\\\.\\)+") (add-to-list 'lisp-imenu-generic-expression (list "Package" (purecopy (concat "^\\s-*(" (eval-when-compile (regexp-opt '("use-package" "require") t)) "\\s-+\\(" lisp-mode-symbol-regexp "\\)")) 2))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; Utility functions ;; (defun use-package-as-symbol (string-or-symbol) "If STRING-OR-SYMBOL is already a symbol, return it. Otherwise convert it to a symbol and return that." (if (symbolp string-or-symbol) string-or-symbol (intern string-or-symbol))) (defun use-package-as-string (string-or-symbol) "If STRING-OR-SYMBOL is already a string, return it. Otherwise convert it to a string and return that." (if (stringp string-or-symbol) string-or-symbol (symbol-name string-or-symbol))) (defun use-package-load-name (name &optional noerror) "Return a form which will load or require NAME depending on whether it's a string or symbol." (if (stringp name) `(load ,name ',noerror) `(require ',name nil ',noerror))) (defun use-package-expand (name label form) "FORM is a list of forms, so `((foo))' if only `foo' is being called." (declare (indent 1)) (when form (if use-package-expand-minimally form (let ((err (make-symbol "err"))) (list `(condition-case-unless-debug ,err ,(macroexp-progn form) (error (ignore (display-warning 'use-package (format "%s %s: %s" ,name ,label (error-message-string ,err)) :error))))))))) (put 'use-package-expand 'lisp-indent-function 'defun) (defun use-package-hook-injector (name-string keyword body) "Wrap pre/post hook injections around a given keyword form. ARGS is a list of forms, so `((foo))' if only `foo' is being called." (if (not use-package-inject-hooks) (use-package-expand name-string (format "%s" keyword) body) (let ((keyword-name (substring (format "%s" keyword) 1))) (when body `((when ,(macroexp-progn (use-package-expand name-string (format "pre-%s hook" keyword) `((run-hook-with-args-until-failure ',(intern (concat "use-package--" name-string "--pre-" keyword-name "-hook")))))) ,(macroexp-progn (use-package-expand name-string (format "%s" keyword) body)) ,(macroexp-progn (use-package-expand name-string (format "post-%s hook" keyword) `((run-hooks ',(intern (concat "use-package--" name-string "--post-" keyword-name "-hook")))))))))))) (defun use-package--with-elapsed-timer (text body) "BODY is a list of forms, so `((foo))' if only `foo' is being called." (declare (indent 1)) (if use-package-expand-minimally body (let ((nowvar (make-symbol "now"))) (if (bound-and-true-p use-package-verbose) `((let ((,nowvar (current-time))) (message "%s..." ,text) (prog1 ,(macroexp-progn body) (let ((elapsed (float-time (time-subtract (current-time) ,nowvar)))) (if (> elapsed ,use-package-minimum-reported-time) (message "%s...done (%.3fs)" ,text elapsed) (message "%s...done" ,text)))))) body)))) (put 'use-package--with-elapsed-timer 'lisp-indent-function 1) (defsubst use-package-error (msg) "Report MSG as an error, so the user knows it came from this package." (error "use-package: %s" msg)) (defsubst use-package-plist-maybe-put (plist property value) "Add a VALUE for PROPERTY to PLIST, if it does not already exist." (if (plist-member plist property) plist (plist-put plist property value))) (defsubst use-package-plist-cons (plist property value) "Cons VALUE onto the head of the list at PROPERTY in PLIST." (plist-put plist property (cons value (plist-get plist property)))) (defsubst use-package-plist-append (plist property value) "Append VALUE onto the front of the list at PROPERTY in PLIST." (plist-put plist property (append value (plist-get plist property)))) (defun use-package-plist-delete (plist property) "Delete PROPERTY from PLIST. This is in contrast to merely setting it to 0." (let (p) (while plist (if (not (eq property (car plist))) (setq p (plist-put p (car plist) (nth 1 plist)))) (setq plist (cddr plist))) p)) (defun use-package-split-list (pred xs) (let ((ys (list nil)) (zs (list nil)) flip) (dolist (x xs) (if flip (nconc zs (list x)) (if (funcall pred x) (progn (setq flip t) (nconc zs (list x))) (nconc ys (list x))))) (cons (cdr ys) (cdr zs)))) (defun use-package-keyword-index (keyword) (loop named outer with index = 0 for k in use-package-keywords do (if (eq k keyword) (return-from outer index)) (incf index))) (defun use-package-sort-keywords (plist) (let (plist-grouped) (while plist (push (cons (car plist) (cadr plist)) plist-grouped) (setq plist (cddr plist))) (let (result) (dolist (x (nreverse (sort plist-grouped #'(lambda (l r) (< (use-package-keyword-index (car l)) (use-package-keyword-index (car r))))))) (setq result (cons (car x) (cons (cdr x) result)))) result))) (defsubst use-package-concat (&rest elems) "Delete all empty lists from ELEMS (nil or (list nil)), and append them." (apply #'nconc (delete nil (delete (list nil) elems)))) (defconst use-package-font-lock-keywords '(("(\\(use-package\\)\\_>[ \t']*\\(\\(?:\\sw\\|\\s_\\)+\\)?" (1 font-lock-keyword-face) (2 font-lock-constant-face nil t)))) (font-lock-add-keywords 'emacs-lisp-mode use-package-font-lock-keywords) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; Keyword processing ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; Normalization functions ;; (defun use-package-normalize-plist (name input) "Given a pseudo-plist, normalize it to a regular plist." (unless (null input) (let* ((keyword (car input)) (xs (use-package-split-list #'keywordp (cdr input))) (args (car xs)) (tail (cdr xs)) (normalizer (intern (concat "use-package-normalize/" (symbol-name keyword)))) (arg (cond ((eq keyword :disabled) (use-package-normalize-plist name tail)) ((functionp normalizer) (funcall normalizer name keyword args)) ((= (length args) 1) (car args)) (t args)))) (if (memq keyword use-package-keywords) (cons keyword (cons arg (use-package-normalize-plist name tail))) (use-package-error (format "Unrecognized keyword: %s" keyword)))))) (defun use-package-process-keywords (name plist &optional state) "Process the next keyword in the free-form property list PLIST. The values in the PLIST have each been normalized by the function use-package-normalize/KEYWORD (minus the colon). STATE is a property list that the function may modify and/or query. This is useful if a package defines multiple keywords and wishes them to have some kind of stateful interaction. Unless the KEYWORD being processed intends to ignore remaining keywords, it must call this function recursively, passing in the plist with its keyword and argument removed, and passing in the next value for the STATE." (declare (indent 1)) (unless (null plist) (let* ((keyword (car plist)) (arg (cadr plist)) (rest (cddr plist))) (unless (keywordp keyword) (use-package-error (format "%s is not a keyword" keyword))) (let* ((handler (concat "use-package-handler/" (symbol-name keyword))) (handler-sym (intern handler))) (if (functionp handler-sym) (funcall handler-sym name keyword arg rest state) (use-package-error (format "Keyword handler not defined: %s" handler))))))) (put 'use-package-process-keywords 'lisp-indent-function 'defun) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :pin ;; (defun use-package-only-one (label args f) "Call F on the first member of ARGS if it has exactly one element." (declare (indent 1)) (cond ((and (listp args) (listp (cdr args)) (= (length args) 1)) (funcall f label (car args))) (t (use-package-error (concat label " wants exactly one argument"))))) (put 'use-package-only-one 'lisp-indent-function 'defun) (defun use-package-normalize/:pin (name keyword args) (use-package-only-one (symbol-name keyword) args (lambda (label arg) (cond ((stringp arg) arg) ((symbolp arg) (symbol-name arg)) (t (use-package-error ":pin wants an archive name (a string)")))))) (eval-when-compile (defvar package-pinned-packages) (defvar package-archives)) (defun use-package--archive-exists-p (archive) "Check if a given ARCHIVE is enabled. ARCHIVE can be a string or a symbol or 'manual to indicate a manually updated package." (if (member archive '(manual "manual")) 't (let ((valid nil)) (dolist (pa package-archives) (when (member archive (list (car pa) (intern (car pa)))) (setq valid 't))) valid))) (defun use-package-pin-package (package archive) "Pin PACKAGE to ARCHIVE." (unless (boundp 'package-pinned-packages) (setq package-pinned-packages ())) (let ((archive-symbol (if (symbolp archive) archive (intern archive))) (archive-name (if (stringp archive) archive (symbol-name archive)))) (if (use-package--archive-exists-p archive-symbol) (add-to-list 'package-pinned-packages (cons package archive-name)) (error "Archive '%s' requested for package '%s' is not available." archive-name package)) (unless (bound-and-true-p package--initialized) (package-initialize t)))) (defun use-package-handler/:pin (name keyword archive-name rest state) (let ((body (use-package-process-keywords name rest state)) (pin-form (if archive-name `(use-package-pin-package ',(use-package-as-symbol name) ,archive-name)))) ;; Pinning should occur just before ensuring ;; See `use-package-handler/:ensure'. (if (bound-and-true-p byte-compile-current-file) (eval pin-form) ; Eval when byte-compiling, (push pin-form body)) ; or else wait until runtime. body)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :ensure ;; (defvar package-archive-contents) (defun use-package-normalize/:ensure (name keyword args) (if (null args) t (use-package-only-one (symbol-name keyword) args (lambda (label arg) (if (symbolp arg) arg (use-package-error (concat ":ensure wants an optional package name " "(an unquoted symbol name)"))))))) (defun use-package-ensure-elpa (package &optional no-refresh) (if (package-installed-p package) t (if (and (not no-refresh) (assoc package (bound-and-true-p package-pinned-packages))) (package-read-all-archive-contents)) (if (or (assoc package package-archive-contents) no-refresh) (package-install package) (progn (package-refresh-contents) (use-package-ensure-elpa package t))))) (defun use-package-handler/:ensure (name keyword ensure rest state) (let* ((body (use-package-process-keywords name rest state)) (package-name (or (and (eq ensure t) (use-package-as-symbol name)) ensure)) (ensure-form (if package-name `(progn (require 'package) (use-package-ensure-elpa ',package-name))))) ;; We want to avoid installing packages when the `use-package' ;; macro is being macro-expanded by elisp completion (see ;; `lisp--local-variables'), but still do install packages when ;; byte-compiling to avoid requiring `package' at runtime. (if (bound-and-true-p byte-compile-current-file) (eval ensure-form) ; Eval when byte-compiling, (push ensure-form body)) ; or else wait until runtime. body)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :if, :when and :unless ;; (defsubst use-package-normalize-value (label arg) "Normalize a value." (cond ((symbolp arg) `(symbol-value ',arg)) ((functionp arg) `(funcall #',arg)) (t arg))) (defun use-package-normalize-test (name keyword args) (use-package-only-one (symbol-name keyword) args #'use-package-normalize-value)) (defalias 'use-package-normalize/:if 'use-package-normalize-test) (defalias 'use-package-normalize/:when 'use-package-normalize-test) (defalias 'use-package-normalize/:unless 'use-package-normalize-test) (defun use-package-handler/:if (name keyword pred rest state) (let ((body (use-package-process-keywords name rest state))) `((when ,pred ,@body)))) (defalias 'use-package-handler/:when 'use-package-handler/:if) (defun use-package-handler/:unless (name keyword pred rest state) (let ((body (use-package-process-keywords name rest state))) `((unless ,pred ,@body)))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :requires ;; (defun use-package-as-one (label args f) "Call F on the first element of ARGS if it has one element, or all of ARGS." (declare (indent 1)) (if (and (listp args) (listp (cdr args))) (if (= (length args) 1) (funcall f label (car args)) (funcall f label args)) (use-package-error (concat label " wants a list")))) (put 'use-package-as-one 'lisp-indent-function 'defun) (defun use-package-normalize-symbols (label arg &optional recursed) "Normalize a list of symbols." (cond ((symbolp arg) (list arg)) ((and (not recursed) (listp arg) (listp (cdr arg))) (mapcar #'(lambda (x) (car (use-package-normalize-symbols label x t))) arg)) (t (use-package-error (concat label " wants a symbol, or list of symbols"))))) (defun use-package-normalize-symlist (name keyword args) (use-package-as-one (symbol-name keyword) args #'use-package-normalize-symbols)) (defalias 'use-package-normalize/:requires 'use-package-normalize-symlist) (defun use-package-handler/:requires (name keyword requires rest state) (let ((body (use-package-process-keywords name rest state))) (if (null requires) body `((when ,(if (listp requires) `(not (member nil (mapcar #'featurep ',requires))) `(featurep ',requires)) ,@body))))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :load-path ;; (defun use-package-normalize-paths (label arg &optional recursed) "Normalize a list of filesystem paths." (cond ((and arg (or (symbolp arg) (functionp arg))) (let ((value (use-package-normalize-value label arg))) (use-package-normalize-paths label (eval value)))) ((stringp arg) (let ((path (if (file-name-absolute-p arg) arg (expand-file-name arg user-emacs-directory)))) (list path))) ((and (not recursed) (listp arg) (listp (cdr arg))) (mapcar #'(lambda (x) (car (use-package-normalize-paths label x t))) arg)) (t (use-package-error (concat label " wants a directory path, or list of paths"))))) (defun use-package-normalize/:load-path (name keyword args) (use-package-as-one (symbol-name keyword) args #'use-package-normalize-paths)) (defun use-package-handler/:load-path (name keyword arg rest state) (let ((body (use-package-process-keywords name rest state))) (use-package-concat (mapcar #'(lambda (path) `(eval-and-compile (add-to-list 'load-path ,path))) arg) body))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :no-require ;; (defun use-package-normalize-predicate (name keyword args) (if (null args) t (use-package-only-one (symbol-name keyword) args #'use-package-normalize-value))) (defalias 'use-package-normalize/:no-require 'use-package-normalize-predicate) (defun use-package-handler/:no-require (name keyword arg rest state) ;; This keyword has no functional meaning. (use-package-process-keywords name rest state)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :preface ;; (defun use-package-normalize-form (label args) "Given a list of forms, return it wrapped in `progn'." (unless (listp (car args)) (use-package-error (concat label " wants a sexp or list of sexps"))) (mapcar #'(lambda (form) (if (and (consp form) (eq (car form) 'use-package)) (macroexpand form) form)) args)) (defun use-package-normalize-forms (name keyword args) (use-package-normalize-form (symbol-name keyword) args)) (defalias 'use-package-normalize/:preface 'use-package-normalize-forms) (defun use-package-handler/:preface (name keyword arg rest state) (let ((body (use-package-process-keywords name rest state))) (use-package-concat (unless (null arg) `((eval-and-compile ,@arg))) body))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :bind, :bind* ;; (defsubst use-package-is-sympair (x &optional allow-vector) "Return t if X has the type (STRING . SYMBOL)." (and (consp x) (or (stringp (car x)) (and allow-vector (vectorp (car x)))) (symbolp (cdr x)))) (defsubst use-package-is-string-pair (x) "Return t if X has the type (STRING . STRING)." (and (consp x) (stringp (car x)) (stringp (cdr x)))) (defun use-package-normalize-pairs (name label arg &optional recursed allow-vector allow-string-cdrs) "Normalize a list of string/symbol pairs. If RECURSED is non-nil, recurse into sublists. If ALLOW-VECTOR is non-nil, then the key to bind may specify a vector of keys, as accepted by `define-key'. If ALLOW-STRING-CDRS is non-nil, then the command name to bind to may also be a string, as accepted by `define-key'." (cond ((or (stringp arg) (and allow-vector (vectorp arg))) (list (cons arg (use-package-as-symbol name)))) ((use-package-is-sympair arg allow-vector) (list arg)) ((and (not recursed) (listp arg) (listp (cdr arg))) (mapcar #'(lambda (x) (let ((ret (use-package-normalize-pairs name label x t allow-vector allow-string-cdrs))) (if (listp ret) (car ret) ret))) arg)) ((and allow-string-cdrs (use-package-is-string-pair arg)) (list arg)) (t arg))) (defun use-package-normalize-binder (name keyword args) (use-package-as-one (symbol-name keyword) args (lambda (label arg) (use-package-normalize-pairs name label arg nil t t)))) (defalias 'use-package-normalize/:bind 'use-package-normalize-binder) (defalias 'use-package-normalize/:bind* 'use-package-normalize-binder) (defun use-package-handler/:bind (name keyword arg rest state &optional bind-macro) (let ((commands (remq nil (mapcar #'(lambda (arg) (if (listp arg) (cdr arg) nil)) arg)))) (use-package-concat (use-package-process-keywords name (use-package-sort-keywords (use-package-plist-maybe-put rest :defer t)) (use-package-plist-append state :commands commands)) `((ignore ,(macroexpand `(,(if bind-macro bind-macro 'bind-keys) :package ,name ,@arg))))))) (defun use-package-handler/:bind* (name keyword arg rest state) (use-package-handler/:bind name keyword arg rest state 'bind-keys*)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :bind-keymap, :bind-keymap* ;; (defalias 'use-package-normalize/:bind-keymap 'use-package-normalize-binder) (defalias 'use-package-normalize/:bind-keymap* 'use-package-normalize-binder) (defun use-package-autoload-keymap (keymap-symbol package override) "Loads PACKAGE and then binds the key sequence used to invoke this function to KEYMAP-SYMBOL. It then simulates pressing the same key sequence a again, so that the next key pressed is routed to the newly loaded keymap. This function supports use-package's :bind-keymap keyword. It works by binding the given key sequence to an invocation of this function for a particular keymap. The keymap is expected to be defined by the package. In this way, loading the package is deferred until the prefix key sequence is pressed." (if (not (require package nil t)) (use-package-error (format "Cannot load package.el: %s" package)) (if (and (boundp keymap-symbol) (keymapp (symbol-value keymap-symbol))) (let* ((kv (this-command-keys-vector)) (key (key-description kv)) (keymap (symbol-value keymap-symbol))) (if override (bind-key* key keymap) (bind-key key keymap)) (setq unread-command-events (listify-key-sequence kv))) (use-package-error (format "use-package: package.el %s failed to define keymap %s" package keymap-symbol))))) (defun use-package-handler/:bind-keymap (name keyword arg rest state &optional override) (let ((form (mapcar #'(lambda (binding) `(,(if override 'bind-key* 'bind-key) ,(car binding) #'(lambda () (interactive) (use-package-autoload-keymap ',(cdr binding) ',(use-package-as-symbol name) ,override)))) arg))) (use-package-concat (use-package-process-keywords name (use-package-sort-keywords (use-package-plist-maybe-put rest :defer t)) state) `((ignore ,@form))))) (defun use-package-handler/:bind-keymap* (name keyword arg rest state) (use-package-handler/:bind-keymap name keyword arg rest state t)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :interpreter ;; (defun use-package-normalize-mode (name keyword args) (use-package-as-one (symbol-name keyword) args (apply-partially #'use-package-normalize-pairs name))) (defalias 'use-package-normalize/:interpreter 'use-package-normalize-mode) (defun use-package-handler/:interpreter (name keyword arg rest state) (let* (commands (form (mapcar #'(lambda (interpreter) (push (cdr interpreter) commands) `(add-to-list 'interpreter-mode-alist ',interpreter)) arg))) (use-package-concat (use-package-process-keywords name (use-package-sort-keywords (use-package-plist-maybe-put rest :defer t)) (use-package-plist-append state :commands commands)) `((ignore ,@form))))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :mode ;; (defalias 'use-package-normalize/:mode 'use-package-normalize-mode) (defun use-package-handler/:mode (name keyword arg rest state) (let* (commands (form (mapcar #'(lambda (mode) (push (cdr mode) commands) `(add-to-list 'auto-mode-alist ',mode)) arg))) (use-package-concat (use-package-process-keywords name (use-package-sort-keywords (use-package-plist-maybe-put rest :defer t)) (use-package-plist-append state :commands commands)) `((ignore ,@form))))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :commands ;; (defalias 'use-package-normalize/:commands 'use-package-normalize-symlist) (defun use-package-handler/:commands (name keyword arg rest state) ;; The actual processing for commands is done in :defer (use-package-process-keywords name (use-package-sort-keywords (use-package-plist-maybe-put rest :defer t)) (use-package-plist-append state :commands arg))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :defines ;; (defalias 'use-package-normalize/:defines 'use-package-normalize-symlist) (defun use-package-handler/:defines (name keyword arg rest state) (let ((body (use-package-process-keywords name rest state))) body)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :functions ;; (defalias 'use-package-normalize/:functions 'use-package-normalize-symlist) (defun use-package-handler/:functions (name keyword arg rest state) (let ((body (use-package-process-keywords name rest state))) (if (not (bound-and-true-p byte-compile-current-file)) body (use-package-concat (unless (null arg) `((eval-when-compile ,@(mapcar #'(lambda (fn) `(declare-function ,fn ,(use-package-as-string name))) arg)))) body)))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :defer ;; (defalias 'use-package-normalize/:defer 'use-package-normalize-predicate) (defun use-package-handler/:defer (name keyword arg rest state) (let ((body (use-package-process-keywords name rest (plist-put state :deferred t))) (name-string (use-package-as-string name))) (use-package-concat ;; Load the package after a set amount of idle time, if the argument to ;; `:defer' was a number. (when (numberp arg) `((run-with-idle-timer ,arg nil #'require ',(use-package-as-symbol name) nil t))) ;; Since we deferring load, establish any necessary autoloads, and also ;; keep the byte-compiler happy. (apply #'nconc (mapcar #'(lambda (command) (when (not (stringp command)) (append `((unless (fboundp ',command) (autoload #',command ,name-string nil t))) (when (bound-and-true-p byte-compile-current-file) `((eval-when-compile (declare-function ,command ,name-string))))))) (delete-dups (plist-get state :commands)))) body))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :after ;; (defalias 'use-package-normalize/:after 'use-package-normalize-symlist) (defun use-package-require-after-load (features name) "Return form for after any of FEATURES require NAME." `(progn ,@(mapcar (lambda (feat) `(eval-after-load (quote ,feat) (quote (require (quote ,name) nil t)))) features))) (defun use-package-handler/:after (name keyword arg rest state) (let ((body (use-package-process-keywords name rest (plist-put state :deferred t))) (name-string (use-package-as-string name))) (use-package-concat (when arg (list (use-package-require-after-load arg name))) body))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :demand ;; (defalias 'use-package-normalize/:demand 'use-package-normalize-predicate) (defun use-package-handler/:demand (name keyword arg rest state) (use-package-process-keywords name rest (use-package-plist-delete state :deferred))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :init ;; (defalias 'use-package-normalize/:init 'use-package-normalize-forms) (defun use-package-handler/:init (name keyword arg rest state) (let ((body (use-package-process-keywords name rest state))) (use-package-concat ;; The user's initializations (let ((init-body (use-package-hook-injector (use-package-as-string name) :init arg))) (if use-package-check-before-init `((if (locate-library ,(use-package-as-string name)) ,(macroexp-progn init-body))) init-body)) body))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :config ;; (defalias 'use-package-normalize/:config 'use-package-normalize-forms) (defun use-package-handler/:config (name keyword arg rest state) (let* ((body (use-package-process-keywords name rest state)) (name-symbol (use-package-as-symbol name)) (config-body (if (equal arg '(t)) body (use-package--with-elapsed-timer (format "Configuring package %s" name-symbol) (use-package-concat (use-package-hook-injector (symbol-name name-symbol) :config arg) body (list t)))))) (if (plist-get state :deferred) (unless (or (null config-body) (equal config-body '(t))) `((eval-after-load ,(if (symbolp name) `',name name) ',(macroexp-progn config-body)))) (use-package--with-elapsed-timer (format "Loading package %s" name) (if use-package-expand-minimally (use-package-concat (list (use-package-load-name name)) config-body) `((if (not ,(use-package-load-name name t)) (ignore (message (format "Cannot load %s" ',name))) ,@config-body))))))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :diminish (defun use-package-normalize-diminish (name label arg &optional recursed) "Normalize the arguments to diminish down to a list of one of two forms: SYMBOL (SYMBOL . STRING)" (cond ((symbolp arg) (list arg)) ((stringp arg) (list (cons (intern (concat (use-package-as-string name) "-mode")) arg))) ((and (consp arg) (stringp (cdr arg))) (list arg)) ((and (not recursed) (listp arg) (listp (cdr arg))) (mapcar #'(lambda (x) (car (use-package-normalize-diminish name label x t))) arg)) (t (use-package-error (concat label " wants a string, symbol, " "(symbol . string) or list of these"))))) (defun use-package-normalize/:diminish (name keyword args) (use-package-as-one (symbol-name keyword) args (apply-partially #'use-package-normalize-diminish name))) (defun use-package-handler/:diminish (name keyword arg rest state) (let ((body (use-package-process-keywords name rest state))) (use-package-concat (mapcar #'(lambda (var) `(if (fboundp 'diminish) ,(if (consp var) `(diminish ',(car var) ,(cdr var)) `(diminish ',var)))) arg) body))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; :delight ;; (defun use-package-normalize/:delight (name keyword args) "Normalize arguments to delight." (cond ((and (= (length args) 1) (symbolp (car args))) (list (car args) nil name)) ((and (= (length args) 2) (symbolp (car args))) (list (car args) (cadr args) (use-package-as-symbol name))) ((and (= (length args) 3) (symbolp (car args))) args) (t (use-package-error ":delight expects same args as delight function")))) (defun use-package-handler/:delight (name keyword args rest state) (let ((body (use-package-process-keywords name rest state))) (use-package-concat body `((delight (quote ,(nth 0 args)) ,(nth 1 args) (quote ,(nth 2 args))) t)))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; The main macro ;; ;;;###autoload (defmacro use-package (name &rest args) "Declare an Emacs package by specifying a group of configuration options. For full documentation, please see the README file that came with this file. Usage: (use-package package-name [:keyword [option]]...) :init Code to run before PACKAGE-NAME has been loaded. :config Code to run after PACKAGE-NAME has been loaded. Note that if loading is deferred for any reason, this code does not execute until the lazy load has occurred. :preface Code to be run before everything except `:disabled'; this can be used to define functions for use in `:if', or that should be seen by the byte-compiler. :mode Form to be added to `auto-mode-alist'. :interpreter Form to be added to `interpreter-mode-alist'. :commands Define autoloads for commands that will be defined by the package. This is useful if the package is being lazily loaded, and you wish to conditionally call functions in your `:init' block that are defined in the package. :bind Bind keys, and define autoloads for the bound commands. :bind* Bind keys, and define autoloads for the bound commands, *overriding all minor mode bindings*. :bind-keymap Bind a key prefix to an auto-loaded keymap defined in the package. This is like `:bind', but for keymaps. :bind-keymap* Like `:bind-keymap', but overrides all minor mode bindings :defer Defer loading of a package -- this is implied when using `:commands', `:bind', `:bind*', `:mode' or `:interpreter'. This can be an integer, to force loading after N seconds of idle time, if the package has not already been loaded. :after Defer loading of a package until after any of the named features are loaded. :demand Prevent deferred loading in all cases. :if EXPR Initialize and load only if EXPR evaluates to a non-nil value. :disabled The package is ignored completely if this keyword is present. :defines Declare certain variables to silence the byte-compiler. :functions Declare certain functions to silence the byte-compiler. :load-path Add to the `load-path' before attempting to load the package. :diminish Support for diminish.el (if installed). :ensure Loads the package using package.el if necessary. :pin Pin the package to an archive." (declare (indent 1)) (unless (member :disabled args) (let* ((name-symbol (if (stringp name) (intern name) name)) (args0 (use-package-plist-maybe-put (use-package-normalize-plist name args) :config '(t))) (args* (use-package-sort-keywords (if use-package-always-ensure (use-package-plist-maybe-put args0 :ensure use-package-always-ensure) args0))) (args* (use-package-sort-keywords (if use-package-always-pin (use-package-plist-maybe-put args* :pin use-package-always-pin) args*)))) ;; When byte-compiling, pre-load the package so all its symbols are in ;; scope. (if (bound-and-true-p byte-compile-current-file) (setq args* (use-package-plist-cons args* :preface `(eval-when-compile ,@(mapcar #'(lambda (var) `(defvar ,var)) (plist-get args* :defines)) (with-demoted-errors ,(format "Cannot load %s: %%S" name) ,(if (eq use-package-verbose 'debug) `(message "Compiling package %s" ',name-symbol)) ,(unless (plist-get args* :no-require) (use-package-load-name name))))))) (let ((body (macroexp-progn (use-package-process-keywords name args* (and use-package-always-defer (list :deferred t)))))) (if use-package-debug (display-buffer (save-current-buffer (let ((buf (get-buffer-create "*use-package*"))) (with-current-buffer buf (delete-region (point-min) (point-max)) (emacs-lisp-mode) (insert (pp-to-string body))) buf)))) body)))) (put 'use-package 'lisp-indent-function 'defun) (provide 'use-package) ;; Local Variables: ;; indent-tabs-mode: nil ;; End: ;;; use-package.el ends here use_package-2.3/README.md0000644000175000017500000005172313001260555014743 0ustar dogslegdogsleg# `use-package` The `use-package` macro allows you to isolate package configuration in your `.emacs` file in a way that is both performance-oriented and, well, tidy. I created it because I have over 80 packages that I use in Emacs, and things were getting difficult to manage. Yet with this utility my total load time is around 2 seconds, with no loss of functionality! Notes for users upgrading to 2.x are located [at the bottom](#upgrading-to-2x). ## The basics Here is the simplest `use-package` declaration: ``` elisp (use-package foo) ``` This loads in the package `foo`, but only if `foo` is available on your system. If not, a warning is logged to the `*Messages*` buffer. If it succeeds, a message about `"Loading foo"` is logged, along with the time it took to load, if it took over 0.1s. Use the `:init` keyword to execute code before a package is loaded. It accepts one or more forms, up until the next keyword: ``` elisp (use-package foo :init (setq foo-variable t)) ``` Similarly, `:config` can be used to execute code after a package is loaded. In cases where loading is done lazily (see more about autoloading below), this execution is deferred until after the autoload occurs: ``` elisp (use-package foo :init (setq foo-variable t) :config (foo-mode 1)) ``` As you might expect, you can use `:init` and `:config` together: ``` elisp (use-package color-moccur :commands (isearch-moccur isearch-all) :bind (("M-s O" . moccur) :map isearch-mode-map ("M-o" . isearch-moccur) ("M-O" . isearch-moccur-all)) :init (setq isearch-lazy-highlight t) :config (use-package moccur-edit)) ``` In this case, I want to autoload the commands `isearch-moccur` and `isearch-all` from `color-moccur.el`, and bind keys both at the global level and within the `isearch-mode-map` (see next section). When the package is actually loaded (by using one of these commands), `moccur-edit` is also loaded, to allow editing of the `moccur` buffer. ## Key-binding Another common thing to do when loading a module is to bind a key to primary commands within that module: ``` elisp (use-package ace-jump-mode :bind ("C-." . ace-jump-mode)) ``` This does two things: first, it creates an autoload for the `ace-jump-mode` command and defers loading of `ace-jump-mode` until you actually use it. Second, it binds the key `C-.` to that command. After loading, you can use `M-x describe-personal-keybindings` to see all such keybindings you've set throughout your `.emacs` file. A more literal way to do the exact same thing is: ``` elisp (use-package ace-jump-mode :commands ace-jump-mode :init (bind-key "C-." 'ace-jump-mode)) ``` When you use the `:commands` keyword, it creates autoloads for those commands and defers loading of the module until they are used. Since the `:init` form is always run -- even if `ace-jump-mode` might not be on your system -- remember to restrict `:init` code to only what would succeed either way. The `:bind` keyword takes either a cons or a list of conses: ``` elisp (use-package hi-lock :bind (("M-o l" . highlight-lines-matching-regexp) ("M-o r" . highlight-regexp) ("M-o w" . highlight-phrase))) ``` The `:commands` keyword likewise takes either a symbol or a list of symbols. NOTE: Special keys like `tab` or `F1`-`Fn` can be written in square brackets, i.e. `[tab]` instead of `"tab"`. The syntax for the keybindings is similar to the "kbd" syntax: see [https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html](https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html) for more information. Examples: ``` elisp (use-package helm :bind (("M-x" . helm-M-x) ("M-" . helm-find-files) ([f10] . helm-buffers-list) ([S-f10] . helm-recentf))) ``` ### Binding to keymaps Normally `:bind` expects that commands are functions that will be autoloaded from the given package. However, this does not work if one of those commands is actually a keymap, since keymaps are not functions, and cannot be autoloaded using Emacs' `autoload` mechanism. To handle this case, `use-package` offers a special, limited variant of `:bind` called `:bind-keymap`. The only difference is that the "commands" bound to by `:bind-keymap` must be keymaps defined in the package, rather than command functions. This is handled behind the scenes by generating custom code that loads the package containing the keymap, and then re-executes your keypress after the first load, to reinterpret that keypress as a prefix key. ### Binding within local keymaps Slightly different from binding a key to a keymap, is binding a key *within* a local keymap that only exists after the package is loaded. `use-package` supports this with a `:map` modifier, taking the local keymap to bind to: ``` elisp (use-package helm :bind (:map helm-mode-map ("C-c h" . helm-execute-persistent-action))) ``` The effect of this statement is to wait until `helm` has loaded, and then to bind the key `C-c h` to `helm-execute-persistent-action` within Helm's local keymap, `helm-mode-map`. Multiple uses of `:map` may be specified. Any binding occurring before the first use of `:map` are applied to the global keymap: ``` elisp (use-package term :bind (("C-c t" . term) :map term-mode-map ("M-p" . term-send-up) ("M-n" . term-send-down) :map term-raw-map ("M-o" . other-window) ("M-p" . term-send-up) ("M-n" . term-send-down))) ``` ## Modes and interpreters Similar to `:bind`, you can use `:mode` and `:interpreter` to establish a deferred binding within the `auto-mode-alist` and `interpreter-mode-alist` variables. The specifier to either keyword can be a cons cell, a list, or just a string: ``` elisp (use-package ruby-mode :mode "\\.rb\\'" :interpreter "ruby") ;; The package is "python" but the mode is "python-mode": (use-package python :mode ("\\.py\\'" . python-mode) :interpreter ("python" . python-mode)) ``` If you aren't using `:commands`, `:bind`, `:bind*`, `:bind-keymap`, `:bind-keymap*`, `:mode`, or `:interpreter` (all of which imply `:defer`; see the docstring for `use-package` for a brief description of each), you can still defer loading with the `:defer` keyword: ``` elisp (use-package ace-jump-mode :defer t :init (autoload 'ace-jump-mode "ace-jump-mode" nil t) (bind-key "C-." 'ace-jump-mode)) ``` This does exactly the same thing as the following: ``` elisp (use-package ace-jump-mode :bind ("C-." . ace-jump-mode)) ``` ## Notes about lazy loading In almost all cases you don't need to manually specify `:defer t`. This is implied whenever `:bind` or `:mode` or `:interpreter` is used. Typically, you only need to specify `:defer` if you know for a fact that some other package will do something to cause your package to load at the appropriate time, and thus you would like to defer loading even though use-package isn't creating any autoloads for you. You can override package deferral with the `:demand` keyword. Thus, even if you use `:bind`, using `:demand` will force loading to occur immediately and not establish an autoload for the bound key. ## Information about package loads When a package is loaded, and if you have `use-package-verbose` set to `t`, or if the package takes longer than 0.1s to load, you will see a message to indicate this loading activity in the `*Messages*` buffer. The same will happen for configuration, or `:config` blocks that take longer than 0.1s to execute. In general, you should keep `:init` forms as simple and quick as possible, and put as much as you can get away with into the `:config` block. This way, deferred loading can help your Emacs to start as quickly as possible. Additionally, if an error occurs while initializing or configuring a package, this will not stop your Emacs from loading. Rather, the error will be captured by `use-package`, and reported to a special `*Warnings*` popup buffer, so that you can debug the situation in an otherwise functional Emacs. ## Conditional loading You can use the `:if` keyword to predicate the loading and initialization of modules. For example, I only want `edit-server` running for my main, graphical Emacs, not for other Emacsen I may start at the command line: ``` elisp (use-package edit-server :if window-system :init (add-hook 'after-init-hook 'server-start t) (add-hook 'after-init-hook 'edit-server-start t)) ``` The `:disabled` keyword can turn off a module you're having difficulties with, or stop loading something you're not using at the present time: ``` elisp (use-package ess-site :disabled t :commands R) ``` When byte-compiling your `.emacs` file, disabled declarations are ommitted from the output entirely, to accelerate startup times. ## Byte-compiling your .emacs Another feature of `use-package` is that it always loads every file that it can when `.emacs` is being byte-compiled. This helps to silence spurious warnings about unknown variables and functions. However, there are times when this is just not enough. For those times, use the `:defines` and `:functions` keywords to introduce dummy variable and function declarations solely for the sake of the byte-compiler: ``` elisp (use-package texinfo :defines texinfo-section-list :commands texinfo-mode :init (add-to-list 'auto-mode-alist '("\\.texi$" . texinfo-mode))) ``` If you need to silence a missing function warning, you can use `:functions`: ``` elisp (use-package ruby-mode :mode "\\.rb\\'" :interpreter "ruby" :functions inf-ruby-keys :config (defun my-ruby-mode-hook () (require 'inf-ruby) (inf-ruby-keys)) (add-hook 'ruby-mode-hook 'my-ruby-mode-hook)) ``` ### Prevent a package from loading at compile-time Normally, `use-package` will load each package at compile time before compiling the configuration, to ensure that any necessary symbols are in scope to satisfy the byte-compiler. At times this can cause problems, since a package may have special loading requirements, and all that you want to use `use-package` for is to add a configuration to the `eval-after-load` hook. In such cases, use the `:no-require` keyword, which implies `:defer`: ``` elisp (use-package foo :no-require t :config (message "This is evaluated when `foo' is loaded")) ``` ## Extending the load-path If your package needs a directory added to the `load-path` in order to load, use `:load-path`. This takes a symbol, a function, a string or a list of strings. If the path is relative, it is expanded within `user-emacs-directory`: ``` elisp (use-package ess-site :load-path "site-lisp/ess/lisp/" :commands R) ``` Note that when using a symbol or a function to provide a dynamically generated list of paths, you must inform the byte-compiler of this definition so the value is available at byte-compilation time. This is done by using the special form `eval-and-compile` (as opposed to `eval-when-compile`). Further, this value is fixed at whatever was determined during compilation, to avoid looking up the same information again on each startup: ``` elisp (eval-and-compile (defun ess-site-load-path () (shell-command "find ~ -path ess/lisp"))) (use-package ess-site :load-path (lambda () (list (ess-site-load-path))) :commands R) ``` ## Diminishing minor modes `use-package` also provides built-in support for the diminish utility -- if you have that installed. Its purpose is to remove strings from your mode-line that provide no useful information. It is invoked with the `:diminish` keyword, which is passed either a minor mode symbol, a cons of the symbol and its replacement string, or just a replacement string, in which case the minor mode symbol is guessed to be the package name with "-mode" appended at the end: ``` elisp (use-package abbrev :diminish abbrev-mode :config (if (file-exists-p abbrev-file-name) (quietly-read-abbrev-file))) ``` ## For `package.el` users You can use `use-package` to load packages from ELPA with `package.el`. This is particularly useful if you share your `.emacs` among several machines; the relevant packages are downloaded automatically once declared in your `.emacs`. The `:ensure` keyword causes the package(s) to be installed automatically if not already present on your system (set `(setq use-package-always-ensure t)` if you wish this behavior to be global for all packages): ``` elisp (use-package magit :ensure t) ``` If you need to install a different package from the one named by `use-package`, you can specify it like this: ``` elisp (use-package tex :ensure auctex) ``` Lastly, when running on Emacs 24.4 or later, use-package can pin a package to a specific archive, allowing you to mix and match packages from different archives. The primary use-case for this is preferring packages from the `melpa-stable` and `gnu` archives, but using specific packages from `melpa` when you need to track newer versions than what is available in the `stable` archives is also a valid use-case. By default `package.el` prefers `melpa` over `melpa-stable` due to the versioning `(> evil-20141208.623 evil-1.0.9)`, so even if you are tracking only a single package from `melpa`, you will need to tag all the non-`melpa` packages with the appropriate archive. If this really annoys you, then you can set `use-package-always-pin` to set a default. If you want to manually keep a package updated and ignore upstream updates, you can pin it to `manual`, which as long as there is no repository by that name, will Just Work(tm). `use-package` throws an error if you try to pin a package to an archive that has not been configured using `package-archives` (apart from the magic `manual` archive mentioned above): ``` Archive 'foo' requested for package 'bar' is not available. ``` Example: ``` elisp (use-package company :ensure t :pin melpa-stable) (use-package evil :ensure t) ;; no :pin needed, as package.el will choose the version in melpa (use-package adaptive-wrap :ensure t ;; as this package is available only in the gnu archive, this is ;; technically not needed, but it helps to highlight where it ;; comes from :pin gnu) (use-package org :ensure t ;; ignore org-mode from upstream and use a manually installed version :pin manual) ``` **NOTE**: the `:pin` argument has no effect on emacs versions < 24.4. ## Extending use-package with new or modified keywords Starting with version 2.0, `use-package` is based on an extensible framework that makes it easy for package authors to add new keywords, or modify the behavior of existing keywords. ### First step: Add the keyword The first step is to add your keyword at the right place in `use-package-keywords`. This list determines the order in which things will happen in the expanded code. You should never change this order, but it gives you a framework within which to decide when your keyword should fire. ### Second step: Create a normalizer Define a normalizer for your keyword by defining a function named after the keyword, for example: ``` elisp (defun use-package-normalize/:pin (name-symbol keyword args) (use-package-only-one (symbol-name keyword) args (lambda (label arg) (cond ((stringp arg) arg) ((symbolp arg) (symbol-name arg)) (t (use-package-error ":pin wants an archive name (a string)")))))) ``` The job of the normalizer is take a list of arguments (possibly nil), and turn it into the single argument (which could still be a list) that should appear in the final property list used by `use-package`. ### Third step: Create a handler Once you have a normalizer, you must create a handler for the keyword: ``` elisp (defun use-package-handler/:pin (name-symbol keyword archive-name rest state) (let ((body (use-package-process-keywords name-symbol rest state))) ;; This happens at macro expansion time, not when the expanded code is ;; compiled or evaluated. (if (null archive-name) body (use-package-pin-package name-symbol archive-name) (use-package-concat body `((push '(,name-symbol . ,archive-name) package-pinned-packages)))))) ``` Handlers can affect the handling of keywords in two ways. First, it can modify the `state` plist before recursively processing the remaining keywords, to influence keywords that pay attention to the state (one example is the state keyword `:deferred`, not to be confused with the `use-package` keyword `:defer`). Then, once the remaining keywords have been handled and their resulting forms returned, the handler may manipulate, extend, or just ignore those forms. The task of each handler is to return a *list of forms* representing code to be inserted. It does not need to be a `progn` list, as this is handled automatically in other places. Thus it is very common to see the idiom of using `use-package-concat` to add new functionality before or after a code body, so that only the minimum code necessary is emitted as the result of a `use-package` expansion. ### Fourth step: Test it out After the keyword has been inserted into `use-package-keywords`, and a normalizer and a handler defined, you can now test it by seeing how usages of the keyword will expand. For this, temporarily set `use-package-debug` to `t`, and just evaluate the `use-package` declaration. The expansion will be shown in a special buffer called `*use-package*`. ## Some timing results On my Retina iMac, the "Mac port" variant of Emacs 24.4 loads in 0.57s, with around 218 packages configured (nearly all of them lazy-loaded). However, I experience no loss of functionality, just a bit of latency when I'm first starting to use Emacs (due to the autoloading). Since I also use idle-loading for many packages, perceived latency is typically reduced overall. On Linux, the same configuration loads in 0.32s. If I don't use Emacs graphically, I can test the absolute minimum times. This is done by running: ``` bash time emacs -l init.elc -batch --eval '(message "Hello, world!")' ``` On the Mac I see an average of 0.36s for the same configuration, and on Linux 0.26s. # Upgrading to 2.x ## Semantics of :init is now consistent The meaning of `:init` has been changed: It now *always* happens before package load, whether `:config` has been deferred or not. This means that some uses of `:init` in your configuration may need to be changed to `:config` (in the non-deferred case). For the deferred case, the behavior is unchanged from before. Also, because `:init` and `:config` now mean "before" and "after", the `:pre-` and `:post-` keywords are gone, as they should no longer be necessary. Lastly, an effort has been made to make your Emacs start even in the presence of use-package configuration failures. So after this change, be sure to check your `*Messages*` buffer. Most likely, you will have several instances where you are using `:init`, but should be using `:config` (this was the case for me in a number of places). ## :idle has been removed I am removing this feature for now because it can result in a nasty inconsistency. Consider the following definition: ``` elisp (use-package vkill :commands vkill :idle (some-important-configuration-here) :bind ("C-x L" . vkill-and-helm-occur) :init (defun vkill-and-helm-occur () (interactive) (vkill) (call-interactively #'helm-occur)) :config (setq vkill-show-all-processes t)) ``` If I load my Emacs and wait until the idle timer fires, then this is the sequence of events: :init :idle :config But if I load Emacs and immediately type C-x L without waiting for the idle timer to fire, this is the sequence of events: :init :config :idle It's possible that the user could use `featurep` in their idle to test for this case, but that's a subtlety I'd rather avoid. ## :defer now accepts an optional integer argument `:defer [N]` causes the package to be loaded -- if it has not already been -- after `N` seconds of idle time. ``` (use-package back-button :commands (back-button-mode) :defer 2 :init (setq back-button-show-toolbar-buttons nil) :config (back-button-mode 1)) ``` ## Add :preface, occurring before everything except :disabled `:preface` can be used to establish function and variable definitions that will 1) make the byte-compiler happy (it won't complain about functions whose definitions are unknown because you have them within a guard block), and 2) allow you to define code that can be used in an `:if` test. Note that whatever is specified within `:preface` is evaluated both at load time and at byte-compilation time, in order to ensure that definitions are seen by both the Lisp evaluator and the byte-compiler, so you should avoid having any side-effects in your preface, and restrict it merely to symbol declarations and definitions. ## Add :functions, for declaring functions to the byte-compiler What `:defines` does for variables, `:functions` does for functions. ## use-package.el is no longer needed at runtime This means you should put the following at the top of your Emacs, to further reduce load time: ``` elisp (eval-when-compile (require 'use-package)) (require 'diminish) ;; if you use :diminish (require 'bind-key) ;; if you use any :bind variant ```