use-package-x

use-package-x is an extension for use-package which provides additional keywords for a simple and cleaner configuration.

Warning

This package is still under development, some keywords may change their name and behavior

This package provides the following extra keywords for use-package:

:setopt

Similar to :custom, but can also bind plain variables.

This uses the setopt function, for bind the variables.

(use-package test
  :setopt
  (number-var 2)
  (list-var '(a b c d))
  (function-var (lambda () ...))
  ;; If you omit the value, it will be set to nil
  (auto-revert-verbose)
  (dired-omit-verbose))

:hook+

An enchanted :hook which supports hooks depths and set multiple functions in a single hook (or for each hook).

• :depth

The hook depth is provided using the sub-keyword :depth

(use-package test
  :hook+
  (:depth 10
    (text-mode . auto-fill-mode)
    (prog-mode . (lambda () (test 1)))
    (a1 b1 c1))
  (:depth 5
    (text-mode . auto-fill-mode)))

• :multi

To set multiple functions (including lambdas) into a single hook (or list of hooks), :hook+ provides to :multi keyword, which you can use to set multiple functions without repeating the same :hook form.

(use-package test
  :hook+
  ((text-mode prog-mode)
   . (:multi auto-fill-mode
             show-paren-mode))
  (org-mode
   . (:multi (lambda () something)
             org-indent-mode))
  ;; This also supports the `:depth' keyword
  (:depth -4
          (outline-mode
           . (:multi (lambda () (print "-4 depth!"))
                     outline-hide-body))))

Also can work as another :hook:

(use-package test
  :hook+
  (a2 b2 c2)
  (text-mode . auto-fill-mode)
  (text-mode . (lambda () (test 2))))

And combine both forms together:

(use-package test
  :hook+
  (:depth 10
    (text-mode . auto-fill-mode)
    (prog-mode . (lambda () (test 1)))
    (a1 b1 c1))
  (:depth 5
    (text-mode-2 . auto-fill-mode))
  (:depth -8 my-mode-hook)
  (lisp-mode . (:multi fn1 fn2 (lambda () ...))
  (a2 b2 c2)
  (prog-mode . auto-fill-mode)
  (prog-mode . (lambda () (test 2))))

:hook-suffix

Allows to change use-package-hook-name-suffix value to the use-package declaration where this is used. This is also supports :hook+ and :hook keywords.

(use-package test
  :hook-suffix "functions"
  :hook+ (enable-theme . my/change-faces-function))

:which-key-replacement

A simple way to set your which-key replacement keybindings The form can be a any of these options:

A cons-cell for which-key-add-key-based-replacements

(use-package test
  :which-key-replacement
  ("C-c d" . "foo")
  ("C-x 8" . '("unicode" . "Unicode keys"))
  ...)

A list which specifies a keymap, for which-key-add-keymap-based-replacements

(use-package test
  :which-key-replacement
  (:keymap map
           ("g" "foo" command-name)
           ("a" "bar" (prefix-map))
           ...))

Or a list which specifies a major mode, for which-key-add-major-mode-key-based-replacements

(use-package test
  :which-key-replacement
  (:mode major-mode
         ("C-x f" . "foo")
         ...))

Any of these forms can be added together in the :which-key-replacement keyword:

(use-package test
  :which-key-replacement
  ("C-x 8" . '("unicode" . "Unicode keys"))
  ("C-c c" . "bar")
  (:keymap map
           ("C-x e" "foo" command-name)
           ("C-c g" "bar" command-name)
           ("p" "mode-prefix" (prefix-map)))
  (:mode major-mode
         ("C-c h" . "zzz")))

:custom-face*

Like :custom-face but override the face specs.

Note

In emacs 31 the :custom-face behavior was changed making impossible to override the face specs, this keyword is intended for Emacs 31 users.

(use-package test
  :custom-face*
  (test-face ((t :inherit error))))

:keymap-define

Define a new keymap or override an existent one.

The value must be a single list with a keymap as car following the key and definition, similar to defvar-keymap.

(use-package test
  :keymap-define
  (mode-map
   "C-x foo" #'bar
   "C-x foo2" #'bar2))

:keymap-set

Like :bind, but uses keymap-set* functions family (or ~define-key*~ for Emacs versions prior 29.1) to bind the variables instead of bind-key macros and family.

Compared to :bind, the key definitions are plain lists instead of cons-cells.

(use-package test
  :keymap-set
  ;; Bind to the Current global map,
  ;; analogous to `keymap-global-set'
  ("C-x foo" #'command)
  ("C-c bar" #'another-command))

If you want to use it for modify a menu, add a 3rd element to the list.

(use-package test
  :keymap-set
  ;; Global
  ;; analogous to `keymap-set-after'
  ("<drink>" '("Drink" . drink-command) 'eat)
  ("<menu-bar> <signals> <work>" '("Work" . work-command) 'break))

You can specify a keymap to bind the keys, use the :map keyword for that.

(use-package test
  :keymap-set
  (:map shell-mode-map
        ("TAB" 'completion-at-point)
        ("<menu-bar> <signals> <work>"
         '("Work" . work-command) 'break)))

Additionally you can use a list of keymaps for bind the keys for each keymap in that list:

(use-package test
  :keymap-set
  (:map (bar-mode-map baz-mode-map)
        ("C-c x" . cmd1)
        ("C-c y" . cmd2)))

:emacs< :emacs<= :emacs= :emacs> :emacs>=

Shorthands for :if (version-* emacs-version <version>), the version can be number or a string.

• :emacs<

(use-package test
  :emacs< 31)

• :emacs<=

(use-package test
  :emacs<= 32)

• :emacs=

(use-package test
  :emacs= "31.0.50")

• :emacs>

(use-package test
  :emacs> 29.1)

• :emacs>=

(use-package test
  :emacs>= "31")

This also have compatibility with other use-package conditional keywords

(use-package test
  :if (display-graphic-p)
  :emacs< 31)

:doc :tag

Document or categorize your use-package declaration instead using comments (does nothing)

The documentation and tags can be anything:

(use-package flymake
  :doc
  "Flymake is an Emacs minor mode for on-the-fly syntax checking.
Flymake collects diagnostic information from multiple sources,
called backends, and visually annotates the buffer with the
results."
  :tag "built-in" "prog-mode"
  :config ...)

Even symbols:

(use-package flymake
  :doc
  Flymake is an Emacs minor mode for on-the-fly syntax checking.
  Flymake collects diagnostic information from multiple sources,
  called backends, and visually annotates the buffer with the
  results.
  :tag built-in prog-mode
  :config ...)

:advice-add :advice-remove

Shorthands for :init (advice-[add|remove] ...)

• :advice-add

Allows to set multiple functions for the same `advice-add` context.

(use-package test
  :advice-add
  (:override (my-function other-function))
  (:around (function-a function-b)
           (function-c function-d))
  ;; This also supports lambdas
  (:around
   (my-other-function
    (lambda (...) ...))))

• :advice-remove

(use-package test
  :advice-remove (my-function other-function))

:local-set

Bind variables locally in some hooks. This is a shorthand for :hook (my-hook . (lambda (&rest _) (setq-local ...)))

The variables will be stored in a single lambda, by default it will be set to the package mode hook:

(use-package org
  :local-set
  ;; This will be stored in the `org-mode-hook' hook
  (variable 1
   another_variable 2
   ...)

Alternatively you can specify a hook to bind the variables:

(use-package org
  :local-set
  (variable #'value
   variable 2
   ...)
  (:hook org-agenda-mode-hook ; <- or a list of hooks
         variable 'symbol
         variable '(a list)
         ...))

Installation and Usage

use-package-x is not available in any ELPA, but you can install it using package-vc-install:

M-x package-vc-install RET https://github.com/DevelopmentCool2449/use-package-x RET

Alternatively using use-package :vc keyword:

(use-package use-package-x
  :ensure t
  :vc ( :url "https://github.com/DevelopmentCool2449/use-package-x"
        :rev :newest))

After it is already installed you can add the keywords to use-package-keywords calling use-package-x-add-keywords:

(use-package use-package-x
  :config
  (use-package-x-add-keywords))

All the keywords are autoloaded, no need to use (require 'use-package-x-...)