From bcf7a8a554bedac28cfb3d5e1c4c3630967f1e34 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Sat, 10 Sep 2022 23:23:29 +0200 Subject: [PATCH] refactor!(cli): rename cli definers for consistency BREAKING CHANGE: If anyone is using Doom's CLI framework and are defining their own CLIs with any of the following macros, they'll need to be updated to their new names: - defautoload! -> defcli-autoload! - defgroup! -> defcli-group! - defstub! -> defcli-stub! - defalias! -> defcli-alias! - defobsolete! -> defcli-obsolete! These were renamed to make their relationship with CLIs more obvious; they were too ambiguous otherwise. --- bin/doom | 44 ++++++++++++++++++++++---------------------- lisp/cli/help.el | 2 +- lisp/cli/make.el | 2 +- lisp/cli/packages.el | 2 +- lisp/cli/sync.el | 2 +- lisp/cli/test.el | 2 +- lisp/doom-cli.el | 16 ++++++++-------- 7 files changed, 35 insertions(+), 35 deletions(-) diff --git a/bin/doom b/bin/doom index d7aae6ce8..c70586f53 100755 --- a/bin/doom +++ b/bin/doom @@ -246,22 +246,22 @@ SEE ALSO: ;; Library for generating autoloads files for Doom modules & packages. (load! "autoloads" dir) - (defgroup! + (defcli-group! :prefix 'doom ;; Import this for implicit 'X help' commands for your script: - (defalias! ((help h)) (:root :help)) + (defcli-alias! ((help h)) (:root :help)) ;; And suggest its use when errors occur. (add-to-list 'doom-help-commands "%p h[elp] %c") - (defgroup! "Config Management" + (defcli-group! "Config Management" :docs "Commands for maintaining your Doom Emacs configuration." - (defautoload! ((sync s))) - (defautoload! ((upgrade up))) - (defautoload! (env)) - (defautoload! ((build b purge p rollback)) "packages") - (defautoload! ((install i))) - (defautoload! ((compile c))) - (defautoload! (clean) "compile") + (defcli-autoload! ((sync s))) + (defcli-autoload! ((upgrade up))) + (defcli-autoload! (env)) + (defcli-autoload! ((build b purge p rollback)) "packages") + (defcli-autoload! ((install i))) + (defcli-autoload! ((compile c))) + (defcli-autoload! (clean) "compile") ;; TODO Post-3.0 commands ;; (load! "gc" dir) @@ -269,31 +269,31 @@ SEE ALSO: ;; (load! "nuke" dir) ;; (load! "package" dir) ;; (load! "profile" dir) - ;; (defobsolete! ((compile c)) (sync "--compile") "v3.0.0") - ;; (defobsolete! ((build b)) (sync "--rebuild") "v3.0.0") + ;; (defcli-obsolete! ((compile c)) (sync "--compile") "v3.0.0") + ;; (defcli-obsolete! ((build b)) (sync "--rebuild") "v3.0.0") ) - (defgroup! "Diagnostics" + (defcli-group! "Diagnostics" :docs "Commands for troubleshooting and debugging Doom." - (defautoload! ((doctor doc))) - (defautoload! (info)) - (defalias! ((version v)) (:root :version))) + (defcli-autoload! ((doctor doc))) + (defcli-autoload! (info)) + (defcli-alias! ((version v)) (:root :version))) - (defgroup! "Development" + (defcli-group! "Development" :docs "Commands for developing or launching Doom." - (defautoload! (ci)) - (defautoload! (make)) - (defautoload! (run)) + (defcli-autoload! (ci)) + (defcli-autoload! (make)) + (defcli-autoload! (run)) ;; FIXME Test framework ;; (load! "test" dir) ) (let ((cli-file "cli")) - (defgroup! "Module commands" + (defcli-group! "Module commands" (dolist (key (hash-table-keys doom-modules)) (when-let (path (plist-get (gethash key doom-modules) :path)) - (defgroup! :prefix (format "+%s" (cdr key)) + (defcli-group! :prefix (format "+%s" (cdr key)) (load! cli-file path t))))) (doom-log "Loading $DOOMDIR/cli.el") diff --git a/lisp/cli/help.el b/lisp/cli/help.el index 1c367577a..ef3a539d4 100644 --- a/lisp/cli/help.el +++ b/lisp/cli/help.el @@ -5,7 +5,7 @@ ;; command is passed with -?, --help, or --version. They can also be aliased to ;; a sub-command to make more of its capabilities accessible to users, with: ;; -;; (defalias! (myscript (help h)) (:help)) +;; (defcli-alias! (myscript (help h)) (:help)) ;; ;; You can define your own command-specific help handlers, e.g. ;; diff --git a/lisp/cli/make.el b/lisp/cli/make.el index b489a10ed..879f527b9 100644 --- a/lisp/cli/make.el +++ b/lisp/cli/make.el @@ -68,7 +68,7 @@ OPTIONS: (write-region (buffer-string) nil codeowners-file))))) ;; TODO Finish me -(defstub! (make changelog)) +(defcli-stub! (make changelog)) diff --git a/lisp/cli/packages.el b/lisp/cli/packages.el index 39a8f0d70..02baa55b6 100644 --- a/lisp/cli/packages.el +++ b/lisp/cli/packages.el @@ -60,7 +60,7 @@ list remains lean." (doom-autoloads-reload)) t) -(defstub! rollback) ; TODO Implement me post-3.0 +(defcli-stub! rollback) ; TODO Implement me post-3.0 ;; diff --git a/lisp/cli/sync.el b/lisp/cli/sync.el index fb3b764de..6559f2049 100644 --- a/lisp/cli/sync.el +++ b/lisp/cli/sync.el @@ -18,7 +18,7 @@ ;; ;;; Commands -(defalias! (:before (sync s)) (:before build)) +(defcli-alias! (:before (sync s)) (:before build)) (defcli! ((sync s)) ((noenvvar? ("-e") "Don't regenerate the envvar file") diff --git a/lisp/cli/test.el b/lisp/cli/test.el index d4023c48b..87c878aed 100644 --- a/lisp/cli/test.el +++ b/lisp/cli/test.el @@ -32,7 +32,7 @@ Should be one of: ;;; Commands ;; FIXME Will be fixed in v3.1 -(defstub! test +(defcli-stub! test ((backend ("--ert" "--buttercup")) (jobs ("-j" "--jobs" int)) &rest targets) diff --git a/lisp/doom-cli.el b/lisp/doom-cli.el index 8c5a78caa..badd7a375 100644 --- a/lisp/doom-cli.el +++ b/lisp/doom-cli.el @@ -347,7 +347,7 @@ struct." (defun doom-cli-get (command &optional noresolve? noload?) "Return CLI at COMMAND. -Will autoload COMMAND if it was deferred with `defautoload!'. +Will autoload COMMAND if it was deferred with `defcli-autoload!'. If NORESOLVE?, don't follow aliases." (when-let* ((command (doom-cli--command command)) @@ -1475,7 +1475,7 @@ treated as a list of aliases for the command. For example: COMMANDSPEC may be prefixed with any of these special keywords: :root ... - This command will ignore any :prefix set by a parent `defgroup!'. + This command will ignore any :prefix set by a parent `defcli-group!'. :before ... This command will run before the specified command(s). :after ... @@ -1655,7 +1655,7 @@ properties: an 'unknown command' error. :prefix (STR...) A command path to prepend to the command name. This is more useful as part - of `defgroup!'s inheritance. + of `defcli-group!'s inheritance. The BODY of commands with a non-nil :alias, :disable, or :partial will be ignored. @@ -1747,14 +1747,14 @@ ignored. doom-cli--table))))) target)))))) -(defmacro defalias! (commandspec target &rest plist) +(defmacro defcli-alias! (commandspec target &rest plist) "Define a CLI alias for TARGET at COMMANDSPEC. See `defcli!' for information about COMMANDSPEC. TARGET is not a command specification, and should be a command list." `(defcli! ,commandspec () :alias ',target ,@plist)) -(defmacro defobsolete! (commandspec target when) +(defmacro defcli-obsolete! (commandspec target when) "Define an obsolete CLI COMMANDSPEC that refers users to NEW-COMMAND. See `defcli!' for information about COMMANDSPEC. @@ -1771,7 +1771,7 @@ WHEN specifies what version this command was rendered obsolete." (doom-cli-command-string ncommand)) (call! ',target args)))) -(defmacro defstub! (commandspec &optional _argspec &rest body) +(defmacro defcli-stub! (commandspec &optional _argspec &rest body) "Define a stub CLI, which will throw an error if invoked. Use this to define commands that will eventually be implemented, but haven't @@ -1783,7 +1783,7 @@ yet. They won't be included in command listings (by help documentation)." :hide t (user-error "Command not implemented yet"))) -(defmacro defautoload! (commandspec &optional path &rest plist) +(defmacro defcli-autoload! (commandspec &optional path &rest plist) "Defer loading of PATHS until PREFIX is called." `(let* ((doom-cli--plist (append (list ,@plist) doom-cli--plist)) (commandspec (doom-cli-command-normalize ',commandspec)) @@ -1799,7 +1799,7 @@ yet. They won't be included in command listings (by help documentation)." (doom-cli-autoload cli)) (defcli! ,commandspec () :autoload path)))) -(defmacro defgroup! (&rest body) +(defmacro defcli-group! (&rest body) "Declare common properties for any CLI commands defined in BODY." (when (stringp (car body)) (push :group body))