refactor!: module API

BREAKING CHANGE: This backports some architectural choices from v3.0.
This changes Doom's module API, renaming some functions and removing
others, in order to facilitate some new features, prepare to move Doom's
modules into separate repos, and make way for two, much larger breaking
commits coming in the next few days.

This commit won't break anything for users unless they're tinkering with
Doom's internals/using its `doom-module-*` API directly. I am avoiding
broader backwards incompatibilities until the 3.0 release.

What's new:

- Negated flags. (modulep! :editor evil -everywhere) will return non-nil
  if :editor evil is active without its +everywhere flag.
- `modulep!` now takes multiple flags to simplify AND checks. E.g.

    (and (modulep! +foo)
         (modulep! +bar)
         (not (modulep! +baz)))

  Can now be expressed with:

    (modulep! +foo +bar -baz)
- Adds pcase matchers for `doom-module-context` and `doom-module`
  structs, making the following destructuring binds possible:

    (pcase-dolist ((doom-module group name flags features)
                   (hash-table-values doom-modules))
      ...)

  This will be used more in v3.0.
- Adds file cookie support to module init.el and config.el files.

Here's a summary of breaking changes made in this commit:

- `doom-module-context` was changed from a vector to a struct (record).
- `doom-modules` is now a table of `doom-module` structs, rather than
  free-form plists.
- The following macros have been renamed:
  - `doom-context-with` -> `with-doom-context`
  - `doom-module-context-with` -> `with-doom-module`
- The followings functions have been replaced/removed:
  - `doom-module-context`+`doom-module-context-get` -> `doom-module`
  - `doom-module-set` -> `doom-module--put`
  - `doom-module-p` -> `doom-module-active-p`
  - `doom-module-context-key` (is now a getter with the same name)
  - `doom-module-put` (removed)
  - `doom-module--context-field` (removed)
- The signatures for these functions have changed:
  - `doom-module-get CATEGORY &optional MODULE PROP` ->
    `doom-module-get (GROUP . MODULE) &optional PROP`
  - `doom-module-locate-path CATEGORY &optional MODULE FILE` ->
    `doom-module-locate-path (GROUP . MODULE) &optional FILE`
  - `doom-module-expand-path CATEGORY MODULE &optional FILE` ->
    `doom-module-expand-path (GROUP . MODULE) &optional FILE`
- Adds the following functions
  - `doom-module-exists-p`
  - `doom-module-key`
  - `doom-module->context`
  - `doom-module<-context`
- Removes the following variables
  - `doom-module--empty-context`

This commit results in a little redundancy, which I will address in
parts 2/3 and/or v3.0.
This commit is contained in:
Henrik Lissner
2024-10-19 15:29:56 -04:00
parent b9deb35aab
commit 15904349cf
24 changed files with 443 additions and 320 deletions

View File

@@ -148,9 +148,13 @@ hoist buggy forms into autoloads.")
;; So `autoload-generate-file-autoloads' knows where to write it
(target-buffer (current-buffer))
(module (doom-module-from-path file))
(generated-autoload-load-name (abbreviate-file-name (file-name-sans-extension file)))
(module-enabled-p (and (doom-module-p (car module) (cdr module))
(doom-file-cookie-p file "if" t))))
(generated-autoload-load-name
(abbreviate-file-name (file-name-sans-extension file)))
(module-enabled-p
(and (doom-module-active-p (car module) (cdr module))
(doom-file-cookie-p file "if" t)))
;; (load-path (cons doom-modules-dir load-path))
)
(save-excursion
(when module-enabled-p
(quiet! (autoload-generate-file-autoloads file target-buffer)))

View File

@@ -104,7 +104,7 @@ Runs `doom-after-reload-hook' afterwards."
(interactive)
(mapc #'require (cdr doom-incremental-packages))
(doom--if-compile doom-reload-command
(doom-context-with '(reload modules)
(with-doom-context '(reload modules)
(doom-run-hooks 'doom-before-reload-hook)
(doom-load (file-name-concat doom-user-dir doom-module-init-file) t)
(with-demoted-errors "PRIVATE CONFIG ERROR: %s"
@@ -129,7 +129,7 @@ line."
(interactive)
(require 'doom-profiles)
;; TODO: Make this more robust
(doom-context-with 'reload
(with-doom-context 'reload
(dolist (file (mapcar #'car doom-profile-generators))
(when (string-match-p "/[0-9]+-loaddefs[.-]" file)
(load (doom-path doom-profile-dir doom-profile-init-dir-name file)
@@ -145,7 +145,7 @@ Doing so from within Emacs will taint your shell environment.
An envvar file contains a snapshot of your shell environment, which can be
imported into Emacs."
(interactive)
(doom-context-with 'reload
(with-doom-context 'reload
(let ((default-directory doom-emacs-dir))
(with-temp-buffer
(doom-load-envvars-file doom-env-file)

View File

@@ -317,8 +317,8 @@ ready to be pasted in a bug report on github."
do (setq lastcat cat)
and collect lastcat
collect
(let* ((flags (doom-module-get lastcat mod :flags))
(path (doom-module-get lastcat mod :path))
(let* ((flags (doom-module-get (cons lastcat mod) :flags))
(path (doom-module-get (cons lastcat mod) :path))
(module
(append
(cond ((null path)

View File

@@ -144,7 +144,7 @@ MATCH is a string regexp. Only entries that match it will be included."
result)))
;;;###autoload
(defun doom-file-cookie-p (file &optional cookie null-value)
(defun doom-file-cookie (file &optional cookie null-value)
"Returns the evaluated result of FORM in a ;;;###COOKIE FORM at the top of
FILE.
@@ -158,11 +158,24 @@ return NULL-VALUE."
(insert-file-contents file nil 0 256)
(if (re-search-forward (format "^;;;###%s " (regexp-quote (or cookie "if")))
nil t)
(doom-module-context-with (doom-module-from-path file)
(let ((load-file-name file))
(eval (sexp-at-point) t)))
(sexp-at-point)
null-value)))
;;;###autoload
(defun doom-file-cookie-p (file &optional cookie null-value)
"Returns the evaluated result of FORM in a ;;;###COOKIE FORM at the top of
FILE.
If COOKIE doesn't exist, or cookie isn't within the first 256 bytes of FILE,
return NULL-VALUE."
(let ((sexp (doom-file-cookie file cookie null-value)))
(if (equal sexp null-value)
null-value
(with-temp-buffer
(with-doom-module (doom-module-from-path file)
(let ((load-file-name file))
(eval (doom-file-cookie file cookie null-value) t)))))))
;;;###autoload
(defmacro file-exists-p! (files &optional directory)
"Returns non-nil if the FILES in DIRECTORY all exist.

View File

@@ -344,10 +344,10 @@ without needing to check if they are available."
(defun doom--help-modules-list ()
(cl-loop for (cat . mod) in (doom-module-list 'all)
for readme-path = (or (doom-module-locate-path cat mod "README.org")
(doom-module-locate-path cat mod))
for readme-path = (or (doom-module-locate-path (cons cat mod) "README.org")
(doom-module-locate-path (cons cat mod)))
for format = (if mod (format "%s %s" cat mod) (format "%s" cat))
if (doom-module-p cat mod)
if (doom-module-active-p cat mod)
collect (list format readme-path)
else if (and cat mod)
collect (list (propertize format 'face 'font-lock-comment-face)
@@ -630,8 +630,7 @@ If prefix arg is present, refresh the cache."
(:core doom-core-dir)
(:user doom-user-dir)
(category
(doom-module-locate-path category
(cdr m)))))
(doom-module-locate-path (cons category (cdr m))))))
(readme-path (expand-file-name "README.org" module-path)))
(insert indent)
(doom--help-insert-button

View File

@@ -49,8 +49,8 @@
(or buffer-file-name
(bound-and-true-p org-src-source-file-name)))
(package
(doom-context-with 'packages
(doom-module-context-with (doom-module-from-path buffer-file-name)
(with-doom-context 'packages
(with-doom-module (doom-module-from-path buffer-file-name)
(eval (sexp-at-point) t)))))
(list :beg beg
:end end
@@ -164,14 +164,14 @@ each package."
(list (intern (car module))
(ignore-errors (intern (cadr module)))
current-prefix-arg)))
(mapc (lambda! ((cat . mod))
(if-let (packages-file (doom-module-locate-path cat mod doom-module-packages-file))
(mapc (lambda! (key)
(if-let (packages-file (doom-module-locate-path key doom-module-packages-file))
(with-current-buffer
(or (get-file-buffer packages-file)
(find-file-noselect packages-file))
(doom/bump-packages-in-buffer select)
(save-buffer))
(message "Module %s has no packages.el file" (cons cat mod))))
(message "Module %s has no packages.el file" key)))
(if module
(list (cons category module))
(cl-remove-if-not (lambda (m) (eq (car m) category))
@@ -188,7 +188,7 @@ each package."
(unless modules
(user-error "This package isn't installed by any Doom module"))
(dolist (module modules)
(when (doom-module-locate-path (car module) (cdr module) doom-module-packages-file)
(when (doom-module-locate-path module doom-module-packages-file)
(doom/bump-module (car module) (cdr module))))))

View File

@@ -151,7 +151,7 @@ If DIR is not a project, it will be indexed (but not cached)."
;; Intentionally avoid `helm-projectile-find-file', because it runs
;; asynchronously, and thus doesn't see the lexical
;; `default-directory'
(if (doom-module-p :completion 'ivy)
(if (doom-module-active-p :completion 'ivy)
#'counsel-projectile-find-file
#'projectile-find-file)))
((and (bound-and-true-p ivy-mode)
@@ -175,9 +175,9 @@ If DIR is not a project, it will be indexed (but not cached)."
"Traverse a file structure starting linearly from DIR."
(let ((default-directory (file-truename (expand-file-name dir))))
(call-interactively
(cond ((doom-module-p :completion 'ivy)
(cond ((doom-module-active-p :completion 'ivy)
#'counsel-find-file)
((doom-module-p :completion 'helm)
((doom-module-active-p :completion 'helm)
#'helm-find-files)
(#'find-file)))))