diff options
-rw-r--r-- | doc/misc/use-package.texi | 205 | ||||
-rw-r--r-- | etc/USE-PACKAGE-NEWS | 4 | ||||
-rw-r--r-- | lisp/use-package/bind-chord.el | 2 | ||||
-rw-r--r-- | lisp/use-package/bind-key.el | 24 | ||||
-rw-r--r-- | lisp/use-package/use-package-bind-key.el | 4 | ||||
-rw-r--r-- | lisp/use-package/use-package-chords.el | 2 | ||||
-rw-r--r-- | lisp/use-package/use-package-core.el | 112 | ||||
-rw-r--r-- | lisp/use-package/use-package-delight.el | 2 | ||||
-rw-r--r-- | lisp/use-package/use-package-diminish.el | 2 | ||||
-rw-r--r-- | lisp/use-package/use-package-ensure-system-package.el | 6 | ||||
-rw-r--r-- | lisp/use-package/use-package-ensure.el | 8 | ||||
-rw-r--r-- | lisp/use-package/use-package-jump.el | 15 | ||||
-rw-r--r-- | lisp/use-package/use-package-lint.el | 4 | ||||
-rw-r--r-- | lisp/use-package/use-package.el | 4 | ||||
-rw-r--r-- | test/lisp/use-package/use-package-chords-tests.el | 2 | ||||
-rw-r--r-- | test/lisp/use-package/use-package-tests.el | 25 |
16 files changed, 224 insertions, 197 deletions
diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi index 2b868564372..a11416a470c 100644 --- a/doc/misc/use-package.texi +++ b/doc/misc/use-package.texi @@ -8,7 +8,7 @@ @copying @quotation -Copyright (C) 2012-2022 John Wiegley <johnw@@newartisans.com> +Copyright (C) 2012-2022 Free Software Foundation, Inc. You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software @@ -31,7 +31,7 @@ General Public License for more details. @finalout @titlepage @title use-package User Manual -@subtitle for version 2.4.1-81-gb185c6b+1 +@subtitle for version 2.4.1-119-g0be480e+1 @author John Wiegley @page @vskip 0pt plus 1filll @@ -45,9 +45,9 @@ General Public License for more details. @top use-package User Manual The @code{use-package} macro allows you to isolate package configuration in your -@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I +@code{.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 +were getting difficult to manage. Yet with this utility my total load time is around 2 seconds, with no loss of functionality! @insertcopying @@ -67,33 +67,33 @@ around 2 seconds, with no loss of functionality! Installation -* Installing from an Elpa Archive:: +* Installing from GNU ELPA:: * Installing from the Git Repository:: * Post-Installation Tasks:: Keywords -* @code{after}:: -* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. -* @code{bind}, @code{bind*}: @code{bind} @code{bind*}. -* @code{commands}:: -* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. -* @code{custom}:: -* @code{custom-face}:: -* @code{defer}, @code{demand}: @code{defer} @code{demand}. -* @code{defines}, @code{functions}: @code{defines} @code{functions}. -* @code{diminish}, @code{delight}: @code{diminish} @code{delight}. -* @code{disabled}:: -* @code{ensure}, @code{pin}: @code{ensure} @code{pin}. -* @code{hook}:: -* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. -* @code{load-path}:: -* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}. -* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}. -* @code{no-require}:: -* @code{requires}:: - -@code{:bind}, @code{:bind*} +* @code{after}:: @code{:after}. +* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}. +* @code{bind} @code{bind*}:: @code{:bind}, @code{:bind*}. +* @code{commands}:: @code{:commands}. +* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}. +* @code{custom}:: @code{:custom}. +* @code{custom-face}:: @code{:custom-face}. +* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}. +* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}. +* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}. +* @code{disabled}:: @code{:disabled}. +* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}. +* @code{hook}:: @code{:hook}. +* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}. +* @code{load-path}:: @code{:load-path}. +* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}. +* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}. +* @code{no-require}:: @code{:no-require}. +* @code{requires}:: @code{:requires}. + +@code{bind}, @code{bind*} * Binding to local keymaps:: @@ -105,9 +105,9 @@ Keywords @chapter Introduction The @code{use-package} macro allows you to isolate package configuration in your -@code{.emacs} file in a way that is both performance-oriented and, well, tidy. I +@code{.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 +were getting difficult to manage. Yet with this utility my total load time is around 2 seconds, with no loss of functionality! More text to come@dots{} @@ -119,50 +119,27 @@ use-package can be installed using Emacs' package manager or manually from its development repository. @menu -* Installing from an Elpa Archive:: +* Installing from GNU ELPA:: * Installing from the Git Repository:: * Post-Installation Tasks:: @end menu -@node Installing from an Elpa Archive -@section Installing from an Elpa Archive +@node Installing from GNU ELPA +@section Installing from GNU ELPA -use-package is available from Melpa and Melpa-Stable. If you haven't used +use-package is available from GNU ELPA. If you haven't used Emacs' package manager before, then it is high time you familiarize yourself with it by reading the documentation in the Emacs manual, see -@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}: +@ref{Packages,,,emacs,}. Then add one of the archives to @code{package-archives}: -@itemize -@item -To use Melpa: -@end itemize - -@lisp -(require 'package) -(add-to-list 'package-archives - '("melpa" . "https://melpa.org/packages/") t) -@end lisp - -@itemize -@item -To use Melpa-Stable: -@end itemize - -@lisp -(require 'package) -(add-to-list 'package-archives - '("melpa-stable" . "https://stable.melpa.org/packages/") t) -@end lisp - -Once you have added your preferred archive, you need to update the -local package list using: +First, you need to update the local package list using: @example M-x package-refresh-contents RET @end example -Once you have done that, you can install use-package and its dependencies -using: +Once you have done that, you can install use-package and its +dependencies using: @example M-x package-install RET use-package RET @@ -229,7 +206,7 @@ Now see @ref{Post-Installation Tasks}. @section Post-Installation Tasks After installing use-package you should verify that you are indeed using the -use-package release you think you are using. It's best to restart Emacs before +use-package release you think you are using. It's best to restart Emacs before doing so, to make sure you are not using an outdated value for @code{load-path}. @example @@ -239,7 +216,7 @@ C-h v use-package-version RET should display something like @example -use-package-version’s value is "2.4.1" +use-package-version’s value is "2.4.3" @end example If you are completely new to use-package then see @ref{Getting Started}. @@ -249,13 +226,13 @@ If you run into problems, then please see the @ref{Debugging Tools}. @node Getting Started @chapter Getting Started -TODO@. For now, see @code{README.md}. +TODO@. For now, see @code{README.md}. @node Basic Concepts @chapter Basic Concepts @code{use-package} was created for few basic reasons, each of which drove the -design in various ways. Understanding these reasons may help make some of +design in various ways. Understanding these reasons may help make some of those decisions clearer: @itemize @@ -279,7 +256,7 @@ close to a functional Emacs as possible. @item To allow byte-compilation of one's init file so that any warnings or -errors seen are meaningful. In this way, even if byte-compilation is not +errors seen are meaningful. In this way, even if byte-compilation is not used for speed (reason 3), it can still be used as a sanity check. @end itemize @@ -290,25 +267,25 @@ used for speed (reason 3), it can still be used as a sanity check. @chapter Keywords @menu -* @code{after}:: -* @code{bind-keymap}, @code{bind-keymap*}: @code{bind-keymap} @code{bind-keymap*}. -* @code{bind}, @code{bind*}: @code{bind} @code{bind*}. -* @code{commands}:: -* @code{preface}, @code{init}, @code{config}: @code{preface} @code{init} @code{config}. -* @code{custom}:: -* @code{custom-face}:: -* @code{defer}, @code{demand}: @code{defer} @code{demand}. -* @code{defines}, @code{functions}: @code{defines} @code{functions}. -* @code{diminish}, @code{delight}: @code{diminish} @code{delight}. -* @code{disabled}:: -* @code{ensure}, @code{pin}: @code{ensure} @code{pin}. -* @code{hook}:: -* @code{if}, @code{when}, @code{unless}: @code{if} @code{when} @code{unless}. -* @code{load-path}:: -* @code{mode}, @code{interpreter}: @code{mode} @code{interpreter}. -* @code{magic}, @code{magic-fallback}: @code{magic} @code{magic-fallback}. -* @code{no-require}:: -* @code{requires}:: +* @code{after}:: @code{after}. +* @code{bind-keymap} @code{bind-keymap*}:: @code{:bind-keymap}, @code{:bind-keymap*}. +* @code{bind} @code{bind*}:: @code{bind} @code{:bind*}. +* @code{commands}:: @code{:commands}. +* @code{preface} @code{init} @code{config}:: @code{:preface}, @code{:init}, @code{:config}. +* @code{custom}:: @code{:custom}. +* @code{custom-face}:: @code{:custom-face}. +* @code{defer} @code{demand}:: @code{:defer}, @code{:demand}. +* @code{defines} @code{functions}:: @code{:defines}, @code{:functions}. +* @code{diminish} @code{delight}:: @code{:diminish}, @code{:delight}. +* @code{disabled}:: @code{:disabled}. +* @code{ensure} @code{pin}:: @code{:ensure}, @code{:pin}. +* @code{hook}:: @code{:hook}. +* @code{if} @code{when} @code{unless}:: @code{:if}, @code{:when}, @code{:unless}. +* @code{load-path}:: @code{:load-path}. +* @code{mode} @code{interpreter}:: @code{:mode}, @code{:interpreter}. +* @code{magic} @code{magic-fallback}:: @code{:magic}, @code{:magic-fallback}. +* @code{no-require}:: @code{:no-require}. +* @code{requires}:: @code{:requires}. @end menu @node @code{after} @@ -316,8 +293,8 @@ used for speed (reason 3), it can still be used as a sanity check. Sometimes it only makes sense to configure a package after another has been loaded, because certain variables or functions are not in scope until that -time. This can achieved using an @code{:after} keyword that allows a fairly rich -description of the exact conditions when loading should occur. Here is an +time. This can achieved using an @code{:after} keyword that allows a fairly rich +description of the exact conditions when loading should occur. Here is an example: @lisp @@ -332,13 +309,13 @@ example: @end lisp In this case, because all of these packages are demand-loaded in the order -they occur, the use of @code{:after} is not strictly necessary. By using it, +they occur, the use of @code{:after} is not strictly necessary. By using it, however, the above code becomes order-independent, without an implicit depedence on the nature of your init file. By default, @code{:after (foo bar)} is the same as @code{:after (:all foo bar)}, meaning that loading of the given package will not happen until both @code{foo} and @code{bar} -have been loaded. Here are some of the other possibilities: +have been loaded. Here are some of the other possibilities: @lisp :after (foo bar) @@ -354,7 +331,7 @@ been loaded, or both @code{baz} and @code{quux} have been loaded. @strong{NOTE}: Pay attention if you set @code{use-package-always-defer} to t, and also use the @code{:after} keyword, as you will need to specify how the declared package is -to be loaded: e.g., by some @code{:bind}. If you're not using one of the mechanisms +to be loaded: e.g., by some @code{:bind}. If you're not using one of the mechanisms that registers autoloads, such as @code{:bind} or @code{:hook}, and your package manager does not provide autoloads, it's possible that without adding @code{:demand t} to those declarations, your package will never be loaded. @@ -363,14 +340,14 @@ those declarations, your package will never be loaded. @section @code{:bind-keymap}, @code{:bind-keymap*} Normally @code{:bind} expects that commands are functions that will be autoloaded -from the given package. However, this does not work if one of those commands +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' @code{autoload} mechanism. To handle this case, @code{use-package} offers a special, limited variant of -@code{:bind} called @code{:bind-keymap}. The only difference is that the "commands" +@code{:bind} called @code{:bind-keymap}. The only difference is that the "commands" bound to by @code{:bind-keymap} must be keymaps defined in the package, rather than -command functions. This is handled behind the scenes by generating custom code +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. @@ -409,7 +386,7 @@ A more literal way to do the exact same thing is: @end lisp When you use the @code{:commands} keyword, it creates autoloads for those commands -and defers loading of the module until they are used. Since the @code{:init} form +and defers loading of the module until they are used. Since the @code{:init} form is always run---even if @code{ace-jump-mode} might not be on your system---remember to restrict @code{:init} code to only what would succeed either way. @@ -425,7 +402,7 @@ The @code{:bind} keyword takes either a cons or a list of conses: The @code{:commands} keyword likewise takes either a symbol or a list of symbols. NOTE: Special keys like @code{tab} or @code{F1}-@code{Fn} can be written in square brackets, -i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is similar to +i.e. @code{[tab]} instead of @code{"tab"}. The syntax for the keybindings is similar to the "kbd" syntax: see @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-Rebinding.html, the Emacs Manual} for more information. Examples: @@ -459,7 +436,7 @@ The effect of this statement is to wait until @code{helm} has loaded, and then t bind the key @code{C-c h} to @code{helm-execute-persistent-action} within Helm's local keymap, @code{helm-mode-map}. -Multiple uses of @code{:map} may be specified. Any binding occurring before the +Multiple uses of @code{:map} may be specified. Any binding occurring before the first use of @code{:map} are applied to the global keymap: @lisp @@ -493,7 +470,7 @@ Here is the simplest @code{use-package} declaration: @end lisp This loads in the package @code{foo}, but only if @code{foo} is available on your -system. If not, a warning is logged to the @code{*Messages*} buffer. If it +system. If not, a warning is logged to the @code{*Messages*} buffer. If it succeeds, a message about @code{"Loading foo"} is logged, along with the time it took to load, if it took over 0.1 seconds. @@ -567,14 +544,14 @@ The @code{:custom-face} keyword allows customization of package custom faces. @node @code{defer} @code{demand} @section @code{:defer}, @code{:demand} -In almost all cases you don't need to manually specify @code{:defer t}. This is -implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used. Typically, you +In almost all cases you don't need to manually specify @code{:defer t}. This is +implied whenever @code{:bind} or @code{:mode} or @code{:interpreter} is used. Typically, you only need to specify @code{: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 @code{:demand} keyword. Thus, even if +You can override package deferral with the @code{:demand} keyword. Thus, even if you use @code{:bind}, using @code{:demand} will force loading to occur immediately and not establish an autoload for the bound key. @@ -616,7 +593,7 @@ If you need to silence a missing function warning, you can use @code{:functions} @section @code{:diminish}, @code{:delight} @code{use-package} also provides built-in support for the diminish and delight -utilities---if you have them installed. Their purpose is to remove or change +utilities---if you have them installed. Their purpose is to remove or change minor mode strings in your mode-line. @uref{https://github.com/myrjola/diminish.el, diminish} is invoked with the @code{:diminish} keyword, which is passed either a @@ -635,7 +612,7 @@ package name with "-mode" appended at the end: @uref{https://elpa.gnu.org/packages/delight.html, delight} is invoked with the @code{:delight} keyword, which is passed a minor mode symbol, a replacement string or quoted @uref{https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html, mode-line data} (in which case the minor mode symbol is guessed to be the package name with "-mode" appended at the -end), both of these, or several lists of both. If no arguments are provided, +end), both of these, or several lists of both. If no arguments are provided, the default mode name is hidden completely. @lisp @@ -677,7 +654,7 @@ from the output entirely, to accelerate startup times. @node @code{ensure} @code{pin} @section @code{:ensure}, @code{:pin} -You can use @code{use-package} to load packages from ELPA with @code{package.el}. This +You can use @code{use-package} to load packages from ELPA with @code{package.el}. This is particularly useful if you share your @code{.emacs} among several machines; the relevant packages are downloaded automatically once declared in your @code{.emacs}. The @code{:ensure} keyword causes the package(s) to be installed automatically if @@ -707,7 +684,7 @@ archives is also a valid use-case. By default @code{package.el} prefers @code{melpa} over @code{melpa-stable} due to the versioning @code{(> evil-20141208.623 evil-1.0.9)}, so even if you are tracking only a single package from @code{melpa}, you will need to tag all the non-@code{melpa} -packages with the appropriate archive. If this really annoys you, then you can +packages with the appropriate archive. If this really annoys you, then you can set @code{use-package-always-pin} to set a default. If you want to manually keep a package updated and ignore upstream updates, @@ -752,7 +729,7 @@ Example: @section @code{:hook} The @code{:hook} keyword allows adding functions onto hooks, here only the basename -of the hook is required. Thus, all of the following are equivalent: +of the hook is required. Thus, all of the following are equivalent: @lisp (use-package ace-jump-mode @@ -827,8 +804,8 @@ the same thing as @code{:if (not foo)}. @section @code{:load-path} If your package needs a directory added to the @code{load-path} in order to load, -use @code{:load-path}. This takes a symbol, a function, a string or a list of -strings. If the path is relative, it is expanded within +use @code{:load-path}. This takes a symbol, a function, a string or a list of +strings. If the path is relative, it is expanded within @code{user-emacs-directory}: @lisp @@ -839,8 +816,8 @@ strings. If the path is relative, it is expanded within 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 @code{eval-and-compile} (as opposed to @code{eval-when-compile}). Further, this +value is available at byte-compilation time. This is done by using the special +form @code{eval-and-compile} (as opposed to @code{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: @@ -859,7 +836,7 @@ up the same information again on each startup: Similar to @code{:bind}, you can use @code{:mode} and @code{:interpreter} to establish a deferred binding within the @code{auto-mode-alist} and @code{interpreter-mode-alist} -variables. The specifier to either keyword can be a cons cell, a list of cons +variables. The specifier to either keyword can be a cons cell, a list of cons cells, or a string or regexp: @lisp @@ -898,8 +875,8 @@ This does exactly the same thing as the following: Similar to @code{:mode} and @code{:interpreter}, you can also use @code{:magic} and @code{:magic-fallback} to cause certain function to be run if the beginning of a -file matches a given regular expression. The difference between the two is -that @code{:magic-fallback} has a lower priority than @code{:mode}. For example: +file matches a given regular expression. The difference between the two is +that @code{:magic-fallback} has a lower priority than @code{:mode}. For example: @lisp (use-package pdf-tools @@ -918,9 +895,9 @@ string @code{"%PDF"}. Normally, @code{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 +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 -@code{use-package} for is to add a configuration to the @code{eval-after-load} hook. In +@code{use-package} for is to add a configuration to the @code{eval-after-load} hook. In such cases, use the @code{:no-require} keyword: @lisp @@ -936,8 +913,8 @@ such cases, use the @code{:no-require} keyword: While the @code{:after} keyword delays loading until the dependencies are loaded, the somewhat simpler @code{:requires} keyword simply never loads the package if the dependencies are not available at the time the @code{use-package} declaration is -encountered. By "available" in this context it means that @code{foo} is available -of @code{(featurep 'foo)} evaluates to a non-nil value. For example: +encountered. By "available" in this context it means that @code{foo} is available +of @code{(featurep 'foo)} evaluates to a non-nil value. For example: @lisp (use-package abbrev diff --git a/etc/USE-PACKAGE-NEWS b/etc/USE-PACKAGE-NEWS index 1f516966980..c499820755f 100644 --- a/etc/USE-PACKAGE-NEWS +++ b/etc/USE-PACKAGE-NEWS @@ -1,5 +1,9 @@ # Changes +## 2.4.4 + +This release prepares for inclusion to GNU ELPA and includes no other changes + ## 2.4.1 This is mostly a bug-fix release: diff --git a/lisp/use-package/bind-chord.el b/lisp/use-package/bind-chord.el index d69a724df66..d592736e227 100644 --- a/lisp/use-package/bind-chord.el +++ b/lisp/use-package/bind-chord.el @@ -1,6 +1,6 @@ ;;; bind-chord.el --- key-chord binding helper for use-package-chords -*- lexical-binding: t; -*- -;; Copyright (C) 2015-2019 Justin Talbott +;; Copyright (C) 2015-2022 Free Software Foundation, Inc. ;; Author: Justin Talbott <justin@waymondo.com> ;; Keywords: convenience, tools, extensions diff --git a/lisp/use-package/bind-key.el b/lisp/use-package/bind-key.el index 5060e16ddf9..b02b7a4ad9f 100644 --- a/lisp/use-package/bind-key.el +++ b/lisp/use-package/bind-key.el @@ -1,12 +1,12 @@ ;;; bind-key.el --- A simple way to manage personal keybindings -*- lexical-binding: t; -*- -;; Copyright (c) 2012-2017 John Wiegley +;; Copyright (c) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> ;; Created: 16 Jun 2012 ;; Modified: 29 Nov 2017 -;; Version: 2.4 +;; Version: 2.4.1 ;; Keywords: keys keybinding config dotemacs ;; URL: https://github.com/jwiegley/use-package @@ -29,7 +29,7 @@ ;; If you have lots of keybindings set in your .emacs file, it can be hard to ;; know which ones you haven't set yet, and which may now be overriding some -;; new default in a new emacs version. This module aims to solve that +;; new default in a new Emacs version. This module aims to solve that ;; problem. ;; ;; Bind keys as follows in your .emacs: @@ -104,7 +104,7 @@ (require 'easy-mmode) (defgroup bind-key nil - "A simple way to manage personal keybindings" + "A simple way to manage personal keybindings." :group 'emacs) (defcustom bind-key-column-widths '(18 . 40) @@ -127,7 +127,7 @@ ;; Create override-global-mode to force key remappings (defvar override-global-map (make-keymap) - "override-global-mode keymap") + "Keymap for `override-global-mode'.") (define-minor-mode override-global-mode "A minor mode so that keymap settings override other modes." @@ -150,7 +150,7 @@ Elements have the form ((KEY . [MAP]) CMD ORIGINAL-CMD)") KEY-NAME may be a vector, in which case it is passed straight to `define-key'. Or it may be a string to be interpreted as -spelled-out keystrokes, e.g., \"C-c C-z\". See documentation of +spelled-out keystrokes, e.g., `C-c C-z'. See documentation of `edmacro-mode' for details. COMMAND must be an interactive function or lambda form. @@ -223,11 +223,11 @@ See `bind-key' for more details." In contrast to `define-key', this function removes the binding from the keymap." (define-key keymap key nil) ;; Split M-key in ESC key - (setq key (mapcan (lambda (k) - (if (and (integerp k) (/= (logand k ?\M-\0) 0)) - (list ?\e (logxor k ?\M-\0)) - (list k))) - key)) + (setq key (cl-mapcan (lambda (k) + (if (and (integerp k) (/= (logand k ?\M-\0) 0)) + (list ?\e (logxor k ?\M-\0)) + (list k))) + key)) ;; Delete single keys directly (if (= (length key) 1) (delete key keymap) @@ -241,7 +241,7 @@ In contrast to `define-key', this function removes the binding from the keymap." (delete (last key) submap) ;; Delete submap if it is empty (when (= 1 (length submap)) - (bind-key--remove prefix keymap))))) + (bind-key--remove prefix keymap))))) ;;;###autoload (defmacro bind-key* (key-name command &optional predicate) diff --git a/lisp/use-package/use-package-bind-key.el b/lisp/use-package/use-package-bind-key.el index 7c79f450831..460d6255e93 100644 --- a/lisp/use-package/use-package-bind-key.el +++ b/lisp/use-package/use-package-bind-key.el @@ -1,6 +1,6 @@ ;;; use-package-bind-key.el --- Support for the :bind/:bind-keymap keywords -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> @@ -29,7 +29,7 @@ ;;; Commentary: ;; Provides support for the :bind, :bind*, :bind-keymap and :bind-keymap* -;; keywords. Note that these are currently still baked into +;; keywords. Note that these are currently still baked into ;; `use-package-keywords' and `use-package-deferring-keywords', although this ;; is harmless if they are never used. diff --git a/lisp/use-package/use-package-chords.el b/lisp/use-package/use-package-chords.el index cf390dbe593..4a4d9e7fea7 100644 --- a/lisp/use-package/use-package-chords.el +++ b/lisp/use-package/use-package-chords.el @@ -1,6 +1,6 @@ ;;; use-package-chords.el --- key-chord keyword for use-package -*- lexical-binding: t; -*- -;; Copyright (C) 2015-2019 Justin Talbott +;; Copyright (C) 2015-2022 Free Software Foundation, Inc. ;; Author: Justin Talbott <justin@waymondo.com> ;; Keywords: convenience, tools, extensions diff --git a/lisp/use-package/use-package-core.el b/lisp/use-package/use-package-core.el index dc9b77bc5bf..429b108ac71 100644 --- a/lisp/use-package/use-package-core.el +++ b/lisp/use-package/use-package-core.el @@ -1,12 +1,12 @@ ;;; use-package-core.el --- A configuration macro for simplifying your .emacs -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> ;; Created: 17 Jun 2012 ;; Modified: 29 Nov 2017 -;; Version: 2.4.1 +;; Version: 2.4.4 ;; Package-Requires: ((emacs "24.3")) ;; Keywords: dotemacs startup speed config package ;; URL: https://github.com/jwiegley/use-package @@ -53,21 +53,28 @@ ;; iterating over them to "disable all themes" won't disable it. (setq custom-enabled-themes (remq 'use-package custom-enabled-themes)) -(if (and (eq emacs-major-version 24) (eq emacs-minor-version 3)) - (defsubst hash-table-keys (hash-table) - "Return a list of keys in HASH-TABLE." - (cl-loop for k being the hash-keys of hash-table collect k)) - (eval-when-compile (require 'subr-x))) +(eval-when-compile + (if (and (eq emacs-major-version 24) (eq emacs-minor-version 3)) + (progn + (defsubst hash-table-keys (hash-table) + "Return a list of keys in HASH-TABLE." + (cl-loop for k being the hash-keys of hash-table collect k)) + (defsubst string-suffix-p (suffix string &optional ignore-case) + (let ((start-pos (- (length string) (length suffix)))) + (and (>= start-pos 0) + (eq t (compare-strings suffix nil nil + string start-pos nil ignore-case)))))) + (require 'subr-x))) (eval-when-compile (require 'regexp-opt)) (defgroup use-package nil - "A use-package declaration for simplifying your `.emacs'." + "A `use-package' declaration for simplifying your `.emacs'." :group 'startup) -(defconst use-package-version "2.4.1" - "This version of use-package.") +(defconst use-package-version "2.4.4" + "This version of `use-package'.") (defcustom use-package-keywords '(:disabled @@ -94,6 +101,7 @@ ;; Any other keyword that also declares commands to be autoloaded (such as ;; :bind) must appear before this keyword. :commands + :autoload :init :defer :demand @@ -105,13 +113,13 @@ "The set of valid keywords, in the order they are processed in. The order of this list is *very important*, so it is only advisable to insert new keywords, never to delete or reorder -them. Further, attention should be paid to the NEWS.md if the +them. Further, attention should be paid to the NEWS.md if the default order ever changes, as they may have subtle effects on -the semantics of use-package declarations and may necessitate +the semantics of `use-package' declarations and may necessitate changing where you had inserted a new keyword earlier. Note that `:disabled' is special in this list, as it causes -nothing at all to happen, even if the rest of the use-package +nothing at all to happen, even if the rest of the `use-package' declaration is incorrect." :type '(repeat symbol) :group 'use-package) @@ -119,7 +127,8 @@ declaration is incorrect." (defcustom use-package-deferring-keywords '(:bind-keymap :bind-keymap* - :commands) + :commands + :autoload) "Unless `:demand' is used, keywords in this list imply deferred loading. The reason keywords like `:hook' are not in this list is that they only imply deferred loading if they reference actual @@ -130,9 +139,9 @@ otherwise requested." :group 'use-package) (defcustom use-package-ignore-unknown-keywords nil - "If non-nil, issue warning instead of error when unknown -keyword is encountered. The unknown keyword and its associated -arguments will be ignored in the `use-package' expansion." + "If non-nil, warn instead of signaling error for unknown keywords. +The unknown keyword and its associated arguments will be ignored +in the `use-package' expansion." :type 'boolean :group 'use-package) @@ -147,7 +156,7 @@ call)." "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, +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, without catching errors" errors) (const :tag "Quiet" nil) @@ -194,9 +203,9 @@ Each entry in the alist is a list of three elements: The first element is the `use-package' keyword. The second is a form that can be evaluated to get the default -value. It can also be a function that will receive the name of -the use-package declaration and the keyword plist given to -`use-package', in normalized form. The value it returns should +value. It can also be a function that will receive the name of +the `use-package' declaration and the keyword plist given to +`use-package', in normalized form. The value it returns should also be in normalized form (which is sometimes *not* what one would normally write in a `use-package' declaration, so use caution). @@ -204,9 +213,9 @@ caution). The third element is a form that can be evaluated to determine whether or not to assign a default value; if it evaluates to nil, then the default value is not assigned even if the keyword is not -present in the `use-package' form. This third element may also be +present in the `use-package' form. This third element may also be a function, in which case it receives the name of the package (as -a symbol) and a list of keywords (in normalized form). It should +a symbol) and a list of keywords (in normalized form). It should return nil or non-nil depending on whether defaulting should be attempted." :type `(repeat @@ -291,7 +300,7 @@ This disables: The main advantage to this variable is that, if you know your configuration works, it will make the byte-compiled file as -minimal as possible. It can also help with reading macro-expanded +minimal as possible. It can also help with reading macro-expanded definitions, to understand the main intent of what's happening." :type 'boolean :group 'use-package) @@ -303,7 +312,7 @@ definitions, to understand the main intent of what's happening." "\\s-+\\(")) (or (bound-and-true-p lisp-mode-symbol-regexp) "\\(?:\\sw\\|\\s_\\|\\\\.\\)+") "\\)") - "Sexp providing regexp for finding use-package forms in user files. + "Sexp providing regexp for finding `use-package' forms in user files. This is used by `use-package-jump-to-package-form' and `use-package-enable-imenu-support'." :type 'sexp @@ -314,7 +323,7 @@ This is used by `use-package-jump-to-package-form' and This is done by adjusting `lisp-imenu-generic-expression' to include support for finding `use-package' and `require' forms. -Must be set before loading use-package." +Must be set before loading `use-package'." :type 'boolean :set #'(lambda (sym value) @@ -336,8 +345,8 @@ Must be set before loading use-package." (font-lock-add-keywords 'emacs-lisp-mode use-package-font-lock-keywords) (defcustom use-package-compute-statistics nil - "If non-nil, compute statistics concerned use-package declarations. -View the statistical report using `use-package-report'. Note that + "If non-nil, compute statistics concerned `use-package' declarations. +View the statistical report using `use-package-report'. Note that if this option is enabled, you must require `use-package' in your user init file at loadup time, or you will see errors concerning undefined variables." @@ -363,14 +372,14 @@ undefined variables." (and sym (symbolp sym))) (defsubst 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 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))) (defsubst 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 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))) @@ -736,8 +745,8 @@ one. If AFTER is non-nil, insert KEYWORD either at the end of the keywords list, or after the ANCHOR if one has been provided. If TEST is non-nil, it is the test used to compare ELEM to list -elements. The default is `eq'. -The modified list is returned. The original list is not modified." +elements. The default is `eq'. +The modified list is returned. The original list is not modified." (let (result) (dolist (k xs) (if (funcall (or test #'eq) k anchor) @@ -987,6 +996,8 @@ If RECURSED is non-nil, recurse into sublists." ;; (defun use-package-reset-statistics () + "Reset statistics for `use-package'. +See also `use-package-statistics'." (interactive) (setq use-package-statistics (make-hash-table))) @@ -1029,7 +1040,7 @@ The information is formatted in a way suitable for (format "%.2f" (use-package-statistics-time statistics)))))) (defun use-package-report () - "Show current statistics gathered about use-package declarations. + "Show current statistics gathered about `use-package' declarations. In the table that's generated, the status field has the following meaning: Configured :config has been processed (the package is loaded!) @@ -1053,7 +1064,7 @@ meaning: (define-derived-mode use-package-statistics-mode tabulated-list-mode "use-package statistics" - "Show current statistics gathered about use-package declarations." + "Show current statistics gathered about `use-package' declarations." (setq tabulated-list-format ;; The sum of column width is 80 characters: [("Package" 25 t) @@ -1347,6 +1358,28 @@ meaning: (delete-dups arg))) (use-package-process-keywords name rest state))) +;;;; :autoload + +(defalias 'use-package-normalize/:autoload 'use-package-normalize/:commands) + +(defun use-package-handler/:autoload (name _keyword arg rest state) + (use-package-concat + ;; Since we deferring load, establish any necessary autoloads, and also + ;; keep the byte-compiler happy. + (let ((name-string (use-package-as-string name))) + (cl-mapcan + #'(lambda (command) + (when (symbolp command) + (append + (unless (plist-get state :demand) + `((unless (fboundp ',command) + (autoload #',command ,name-string)))) + (when (bound-and-true-p byte-compile-current-file) + `((eval-when-compile + (declare-function ,command ,name-string))))))) + (delete-dups arg))) + (use-package-process-keywords name rest state))) + ;;;; :defer (defalias 'use-package-normalize/:defer 'use-package-normalize-predicate) @@ -1477,7 +1510,7 @@ no keyword implies `:all'." (defun use-package-normalize/:custom-face (name-symbol _keyword arg) "Normalize use-package custom-face keyword." (let ((error-msg - (format "%s wants a (<symbol> <face-spec>) or list of these" + (format "%s wants a (<symbol> <face-spec> [spec-type]) or list of these" name-symbol))) (unless (listp arg) (use-package-error error-msg)) @@ -1488,13 +1521,13 @@ no keyword implies `:all'." (spec (nth 1 def))) (when (or (not face) (not spec) - (> (length def) 2)) + (> (length def) 3)) (use-package-error error-msg)))))) (defun use-package-handler/:custom-face (name _keyword args rest state) "Generate use-package custom-face keyword code." (use-package-concat - (mapcar #'(lambda (def) `(custom-set-faces (backquote ,def))) args) + (mapcar #'(lambda (def) `(apply #'face-spec-set (backquote ,def))) args) (use-package-process-keywords name rest state))) ;;;; :init @@ -1633,6 +1666,7 @@ this file. Usage: 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. +:autoload Similar to :commands, but it for no-interactive one. :hook Specify hook(s) to attach this package to. :bind Bind keys, and define autoloads for the bound commands. diff --git a/lisp/use-package/use-package-delight.el b/lisp/use-package/use-package-delight.el index 85d5c7cb4d6..558be5e4706 100644 --- a/lisp/use-package/use-package-delight.el +++ b/lisp/use-package/use-package-delight.el @@ -1,6 +1,6 @@ ;;; use-package-delight.el --- Support for the :delight keyword -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> diff --git a/lisp/use-package/use-package-diminish.el b/lisp/use-package/use-package-diminish.el index 1f3895f42cd..5b20830ee6a 100644 --- a/lisp/use-package/use-package-diminish.el +++ b/lisp/use-package/use-package-diminish.el @@ -1,6 +1,6 @@ ;;; use-package-diminish.el --- Support for the :diminish keyword -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> diff --git a/lisp/use-package/use-package-ensure-system-package.el b/lisp/use-package/use-package-ensure-system-package.el index 7c591af7d9b..c42996f9d2a 100644 --- a/lisp/use-package/use-package-ensure-system-package.el +++ b/lisp/use-package/use-package-ensure-system-package.el @@ -1,6 +1,6 @@ ;;; use-package-ensure-system-package.el --- auto install system packages -*- lexical-binding: t; -*- -;; Copyright (C) 2017 Justin Talbott +;; Copyright (C) 2022 Free Software Foundation, Inc. ;; Author: Justin Talbott <justin@waymondo.com> ;; Keywords: convenience, tools, extensions @@ -29,7 +29,7 @@ "List of custom packages installed.") (defun use-package-ensure-system-package-consify (arg) - "Turn `arg' into a cons of (`package-name' . `install-command')." + "Turn ARG into a cons of (`package-name' . `install-command')." (cond ((stringp arg) (cons arg `(system-packages-install ,arg))) @@ -54,7 +54,7 @@ ;;;###autoload (defun use-package-normalize/:ensure-system-package (_name-symbol keyword args) - "Turn `arg' into a list of cons-es of (`package-name' . `install-command')." + "Turn ARGS into a list of conses of (`package-name' . `install-command')." (use-package-as-one (symbol-name keyword) args (lambda (_label arg) (cond diff --git a/lisp/use-package/use-package-ensure.el b/lisp/use-package/use-package-ensure.el index cb31b4b7dd4..a879c294dc3 100644 --- a/lisp/use-package/use-package-ensure.el +++ b/lisp/use-package/use-package-ensure.el @@ -1,6 +1,6 @@ ;;; use-package-ensure.el --- Support for the :ensure and :pin keywords -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> @@ -37,7 +37,7 @@ (require 'use-package-core) (defgroup use-package-ensure nil - "Support for :ensure and :pin keywords in use-package declarations." + "Support for :ensure and :pin keywords in `use-package' declarations." :group 'use-package) (eval-when-compile @@ -64,7 +64,7 @@ to all `:ensure' keywords (always a list, even if only one); and the current `state' plist created by previous handlers. Note that this function is called whenever `:ensure' is provided, -even if it is nil. It is up to the function to decide on the +even if it is nil. It is up to the function to decide on the semantics of the various values for `:ensure'. This function should return non-nil if the package is installed. @@ -111,7 +111,7 @@ manually updated package." (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." + (error "Archive '%s' requested for package '%s' is not available" archive-name package)) (unless (bound-and-true-p package--initialized) (package-initialize t)))) diff --git a/lisp/use-package/use-package-jump.el b/lisp/use-package/use-package-jump.el index 4044ad16564..6b9c02808e1 100644 --- a/lisp/use-package/use-package-jump.el +++ b/lisp/use-package/use-package-jump.el @@ -1,6 +1,6 @@ ;;; use-package-jump.el --- Attempt to jump to a use-package declaration -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> @@ -30,8 +30,8 @@ ;; Provides the command `M-x use-package-jump-to-package-form', however it ;; only works if the package being jumped to was required during -;; initialization. If it was delay-loaded, it will not work. Improvements are -;; needed. +;; initialization. If it was delay-loaded, it will not work. +;; Improvements are needed. ;;; Code: @@ -48,11 +48,10 @@ Returns an absolute file path or nil if none is found." ;;;###autoload (defun use-package-jump-to-package-form (package) - "Attempt to find and jump to the `use-package' form that loaded -PACKAGE. This will only find the form if that form actually -required PACKAGE. If PACKAGE was previously required then this -function will jump to the file that originally required PACKAGE -instead." + "Attempt to find and jump to the `use-package' form that loaded PACKAGE. +This will only find the form if that form actually required +PACKAGE. If PACKAGE was previously required then this function +will jump to the file that originally required PACKAGE instead." (interactive (list (completing-read "Package: " features))) (let* ((package (if (stringp package) (intern package) package)) (requiring-file (use-package-find-require package)) diff --git a/lisp/use-package/use-package-lint.el b/lisp/use-package/use-package-lint.el index c6e7c3c0ce2..12974ab15e4 100644 --- a/lisp/use-package/use-package-lint.el +++ b/lisp/use-package/use-package-lint.el @@ -1,6 +1,6 @@ ;;; use-package-lint.el --- Attempt to find errors in use-package declarations -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> @@ -63,7 +63,7 @@ ;;;###autoload (defun use-package-lint () - "Check for errors in use-package declarations. + "Check for errors in `use-package' declarations. For example, if the module's `:if' condition is met, but even with the specified `:load-path' the module cannot be found." (interactive) diff --git a/lisp/use-package/use-package.el b/lisp/use-package/use-package.el index 0e194d5f182..9d046e0b149 100644 --- a/lisp/use-package/use-package.el +++ b/lisp/use-package/use-package.el @@ -1,12 +1,12 @@ ;;; use-package.el --- A configuration macro for simplifying your .emacs -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2017 John Wiegley +;; Copyright (C) 2012-2022 Free Software Foundation, Inc. ;; Author: John Wiegley <johnw@newartisans.com> ;; Maintainer: John Wiegley <johnw@newartisans.com> ;; Created: 17 Jun 2012 ;; Modified: 29 Nov 2017 -;; Version: 2.4.1 +;; Version: 2.4.4 ;; Package-Requires: ((emacs "24.3") (bind-key "2.4")) ;; Keywords: dotemacs startup speed config package ;; URL: https://github.com/jwiegley/use-package diff --git a/test/lisp/use-package/use-package-chords-tests.el b/test/lisp/use-package/use-package-chords-tests.el index 3c3dc4b4fe0..2b7588dd807 100644 --- a/test/lisp/use-package/use-package-chords-tests.el +++ b/test/lisp/use-package/use-package-chords-tests.el @@ -158,4 +158,4 @@ ;; no-update-autoloads: t ;; End: -;;; use-package-tests.el ends here +;;; use-package-chords-tests.el ends here diff --git a/test/lisp/use-package/use-package-tests.el b/test/lisp/use-package/use-package-tests.el index 007d2b07ac8..709c1988ffb 100644 --- a/test/lisp/use-package/use-package-tests.el +++ b/test/lisp/use-package/use-package-tests.el @@ -875,6 +875,12 @@ (gnus-harvest-install)) t)))) +(ert-deftest use-package-test/:autoload-1 () + (match-expansion + (use-package foo :autoload bar) + `(unless (fboundp 'bar) + (autoload #'bar "foo")))) + (ert-deftest use-package-test/:defines-1 () (match-expansion (use-package foo :defines bar) @@ -1150,7 +1156,7 @@ (match-expansion (use-package foo :custom-face (foo ((t (:background "#e4edfc"))))) `(progn - (custom-set-faces (backquote (foo ((t (:background "#e4edfc")))))) + (apply #'face-spec-set (backquote (foo ((t (:background "#e4edfc")))))) (require 'foo nil nil)))) (ert-deftest use-package-test/:custom-face-2 () @@ -1160,11 +1166,18 @@ (example-1-face ((t (:foreground "LightPink")))) (example-2-face ((t (:foreground "LightGreen"))))) `(progn - (custom-set-faces - (backquote (example-1-face ((t (:foreground "LightPink")))))) - (custom-set-faces - (backquote (example-2-face ((t (:foreground "LightGreen")))))) - (require 'example nil nil)))) + (apply #'face-spec-set + (backquote (example-1-face ((t (:foreground "LightPink")))))) + (apply #'face-spec-set + (backquote (example-2-face ((t (:foreground "LightGreen")))))) + (require 'example nil nil)))) + +(ert-deftest use-package-test/:custom-face-3 () + (match-expansion + (use-package foo :custom-face (foo ((t (:background "#e4edfc"))) face-defspec-spec)) + `(progn + (apply #'face-spec-set (backquote (foo ((t (:background "#e4edfc"))) face-defspec-spec))) + (require 'foo nil nil)))) (ert-deftest use-package-test/:init-1 () (match-expansion |