# -*- mode: org -*-
#+export_file_name: use-package-x.texi
#+texinfo_dir_category: Emacs misc features
#+texinfo_dir_title: use-package-x.
#+texinfo_dir_desc: use-package-x User Manual.

#+title: use-package-x
#+author: Elias G. Perez

#+begin_quote
[!NOTE]

The Maintenance of this package in on pause due to its possible
inclusion to Emacs core or GNU ELPA, thus some keywords and its syntax
may change.

I apologize for the inconvenience.
#+end_quote

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

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.

#+begin_src emacs-lisp
(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))
#+end_src

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

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

#+begin_src emacs-lisp
(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)))
#+end_src

To set multiple functions (including lambdas) into a single hook (or
list of hooks) without repeating the same ~:hook~ form, you can use a
list of functions.

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

Also can work as another ~:hook~:

#+begin_src emacs-lisp
(use-package test
  :hook+
  (a2 b2 c2)
  (text-mode . auto-fill-mode)
  (text-mode . (lambda () (test 2))))
#+end_src

And combine both forms together:

#+begin_src emacs-lisp
(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 (fn1 fn2 (lambda () ...))
  (a2 b2 c2)
  (prog-mode . auto-fill-mode)
  (prog-mode . (lambda () (test 2))))
#+end_src

* :hook-suffix
Allows to change ~use-package-hook-name-suffix~ value to the current
use-package declaration where this is used.

This is also supports ~:hook+~ and ~:hook~ keywords.

#+begin_src emacs-lisp
(use-package test
  :hook-suffix nil
  :hook+
  (c-mode-hook . my/function)
  (enable-theme-functions . my/change-faces-function))
#+end_src

* :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~

#+begin_src emacs-lisp
(use-package test
  :which-key-replacement
  ("C-c d" . "foo")
  ("C-x 8" . '("unicode" . "Unicode keys"))
  ...)
#+end_src

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

#+begin_src emacs-lisp
(use-package test
  :which-key-replacement
  (:keymap map
           ("g" "foo" command-name)
           ("a" "bar" (prefix-map))
           ...))
#+end_src

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

#+begin_src emacs-lisp
(use-package test
  :which-key-replacement
  (:mode major-mode
         ("C-x f" . "foo")
         ...))
#+end_src

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

#+begin_src emacs-lisp
(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")))
#+end_src

* :custom-face*
Like :custom-face but override the face specs.

#+begin_quote
[!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.
#+end_quote

#+begin_src emacs-lisp
(use-package test
  :custom-face*
  (test-face ((t :inherit error))))
#+end_src

* :custom-icon
Like ~:custom~ but for setting/changing custom icons, this uses a
~:custom-face~-like spec for set the icons (See ~custom-set-icons~
function for how to use this spec).

#+begin_src emacs-lisp
(use-package tab-line
  :custom-icon
  (tab-line-new ((symbol "•")))
  (tab-line-close-modified ((text " x " :face shadow))))
#+end_src

* :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~.

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

* :keymap-set
Like ~:bind~, but uses ~keymap-*~ functions to bind the variables instead
of ~bind-key~ macros.

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

#+begin_src emacs-lisp
(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))
#+end_src

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

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


For specify a keymap to bind the keys, use the ~:map~ sub-keyword.

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

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

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

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

+ ~:emacs<~
#+begin_src emacs-lisp
(use-package test
  :emacs< 31)
#+end_src

+ ~:emacs<=~
#+begin_src emacs-lisp
(use-package test
  :emacs<= 32)
#+end_src

+ ~:emacs=~
#+begin_src emacs-lisp
(use-package test
  :emacs= "31.0.50")
#+end_src

+ ~:emacs>~
#+begin_src emacs-lisp
(use-package test
  :emacs> 29.1)
#+end_src

+ ~:emacs>=~
#+begin_src emacs-lisp
(use-package test
  :emacs>= "31")
#+end_src

This also have compatibility with other ~use-package~ conditional keywords

#+begin_src emacs-lisp
(use-package test
  :if (display-graphic-p)
  :emacs< 31)
#+end_src

* :doc, :tag
Document or categorize your use-package declaration instead using
comments (does nothing)

The documentation and tags can be anything:
#+begin_src emacs-lisp
(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 ...)
#+end_src

Even symbols:
#+begin_src emacs-lisp
(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 ...)
#+end_src

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

+ ~:advice-add~
Allows to set multiple functions for the same ~advice-add~
context.

#+begin_src emacs-lisp
(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 (...) ...))))
#+end_src

+ ~:advice-remove~

#+begin_src emacs-lisp
(use-package test
  :advice-remove (my-function other-function))
#+end_src

* :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:

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

Alternatively you can specify a hook to bind the variables:

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

* :mark
Include package to ~package-selected-packages~.

#+begin_quote
[!WARNING]
This should only be used with third-party packages.
#+end_quote

#+begin_src emacs-lisp
(use-package gptel
  ;; Install the package
  :ensure t
  ;; and include it in `package-selected-packages',
  ;; so it will not get removed by `package-autoremove'
  :mark t
  ...)
#+end_src


* 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:

#+begin_src emacs-lisp
(use-package use-package-x
  :ensure t
  :vc ( :url "https://github.com/DevelopmentCool2449/use-package-x"
        :rev :newest))
#+end_src

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

#+begin_src emacs-lisp
(use-package use-package-x
  :config
  (use-package-x-add-keywords))
#+end_src

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

#+html: <img src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/powered_by_org_mode.svg" align="right" width="10%" alt="Powered by Org Mode">