feat(command): Add custom command (#195)

* feat(command): Add custom command

* Changelog

* Fix desc

* add doc

* fix options

CHANGELOG.md

@@ -33,6 +33,7 @@ Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how
 * Enter docker directly when no arguments (#191)
 * Add command to generate recipe (#192)
 * Add option to init from `Eldev`-file (#193)
+* Add command `commnad` for custom commands (#195)
 
 ## 0.8.x
 > Released Mar 08, 2023

cmds/core/command.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright (C) 2023 Jen-Chieh Shen
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with GNU Emacs; see the file COPYING.  If not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ */
+
+"use strict";
+
+exports.command = ['command [names..]', 'cmd [names..]'];
+exports.desc = 'Run custom command';
+exports.builder = yargs => yargs
+  .positional(
+    '[names..]', {
+      description: 'list of function commands to execute',
+      type: 'array',
+    });
+
+exports.handler = async (argv) => {
+  await UTIL.e_call(argv, 'core/command'
+                    , argv.names);
+};

docs/content/en/Getting-Started/Advanced-Usage.md

@@ -3,6 +3,8 @@ title: 🔧 Advanced Usage
 weight: 400
 ---
 
+{{< toc >}}
+
 `Eask` is just a regular Emacs Lisp file and should be read from Emacs itself!
 You can do:
 
@@ -12,6 +14,8 @@ You can do:
 (setq byte-compile-error-on-warn t)  ; Signal error if warning occurred
 ```
 
+# 🪝 Hooks
+
 `eask` provides some hooks which enable you to execute code before and after
 each command. The hooks look like so:
 
@@ -58,3 +62,13 @@ therefore,
              ;; do stuff before checkdoc linting...
              ))
 ```
+
+# 📇 Adding your own command
+
+You can add your own command through our command interface:
+
+```elisp
+(eask-defcommand my-test-command
+  "A test command that prints out useless message."
+  (message "This is a test command!"))
+```

docs/content/en/Getting-Started/Basic-Usage/_index.md

@@ -34,6 +34,7 @@ Usage: eask <command> [options..]
 Commands:
   archives                   List out all package archives                                                                                                                                     [aliases: sources]
   clean <type>               Delete various files produced during building
+  command [names..]          Run custom command                                                                                                                                                    [aliases: cmd]
   compile [names..]          Byte compile all Emacs Lisp files in the package
   create <type>              Create a new elisp project
   docker <version> [args..]  Launch specified Emacs version in a Docker container

docs/content/en/Getting-Started/Commands-and-options.md

@@ -278,16 +278,6 @@ Concatenate all Emacs Lisp files into one file.
 $ eask [GLOBAL-OPTIONS] concate [FILES..]
 ```
 
-## 🔍 eask run
-
-Run the script.
-
-```sh
-$ eask [GLOBAL-OPTIONS] run [FILES..]
-```
-
-Alias: `run-script`
-
 # 🚩 Execution
 
 Commands allow you execute on top of Eask core.
@@ -326,6 +316,26 @@ Evaluate `FORM` as a lisp form.
 $ eask [GLOBAL-OPTIONS] eval [FORM]
 ```
 
+## 🔍 eask run
+
+Run the script.
+
+```sh
+$ eask [GLOBAL-OPTIONS] run [NAMES..]
+```
+
+Alias: `run-script`
+
+## 🔍 eask command
+
+Run the command.
+
+```sh
+$ eask [GLOBAL-OPTIONS] command [NAMES..]
+```
+
+Alias: `cmd`
+
 ## 🔍 eask docker
 
 Launch specified Emacs version in a Docker container.

docs/content/zh-TW/Getting-Started/Advanced-Usage.md

@@ -3,6 +3,8 @@ title: 🔧 進階用法
 weight: 400
 ---
 
+{{< toc >}}
+
 `Eask` 只是一個普通的 Emacs Lisp 文件，應該從 Emacs 本身讀取！ 你可以做：
 
 ```elisp
@@ -11,6 +13,8 @@ weight: 400
 (setq byte-compile-error-on-warn t)  ; 出現警告時信號錯誤
 ```
 
+# 🪝 Hooks
+
 `eask` 提供了一些 hooks，使您能夠在每個命令之前和之後執行代碼。 hook 看起來像這樣：
 
 - `eask-before-COMMAND-hook`
@@ -55,3 +59,13 @@ $ eask generate license  # generate/license
              ;; 在 checkdoc linting 之前做一些事情...
              ))
 ```
+
+# 📇 加入你自己的指令
+
+您可以透過我們的 command 介面添加自己的命令：
+
+```elisp
+(eask-defcommand my-test-command
+  "測試指令印出無用的訊息。"
+  (message "這是一個測試指令!"))
+```

docs/content/zh-TW/Getting-Started/Basic-Usage/_index.md

@@ -31,6 +31,7 @@ Usage: eask <command> [options..]
 Commands:
   archives                   List out all package archives                                                                                                                                     [aliases: sources]
   clean <type>               Delete various files produced during building
+  command [names..]          Run custom command                                                                                                                                                    [aliases: cmd]
   compile [names..]          Byte compile all Emacs Lisp files in the package
   create <type>              Create a new elisp project
   docker <version> [args..]  Launch specified Emacs version in a Docker container

docs/content/zh-TW/Getting-Started/Commands-and-options.md

@@ -274,16 +274,6 @@ $ eask [GLOBAL-OPTIONS] cat [PATTERNS..]
 $ eask [GLOBAL-OPTIONS] concate [FILES..]
 ```
 
-## 🔍 eask run
-
-運行腳本。
-
-```sh
-$ eask [GLOBAL-OPTIONS] run [FILES..]
-```
-
-別名: `run-script`
-
 # 🚩 執行
 
 指令允許執行在 Eask 核心之上。
@@ -322,6 +312,26 @@ $ eask [GLOBAL-OPTIONS] emacs [ARGUMENTS ...]
 $ eask [GLOBAL-OPTIONS] eval [FORM]
 ```
 
+## 🔍 eask run
+
+運行腳本。
+
+```sh
+$ eask [GLOBAL-OPTIONS] run [NAMES..]
+```
+
+別名: `run-script`
+
+## 🔍 eask command
+
+運行指令。
+
+```sh
+$ eask [GLOBAL-OPTIONS] command [NAMES..]
+```
+
+別名: `cmd`
+
 ## 🔍 eask docker
 
 在 Docker 容器中啟動指定的 Emacs 版本

lisp/_prepare.el

@@ -2,6 +2,15 @@
 ;;; Commentary: Prepare to setup Eask environment for sandboxing
 ;;; Code:
 
+;;
+;;; Requirement
+
+(when (version< emacs-version "26.1")
+  (error "Eask requires Emacs 26.1 and above!"))
+
+;;
+;;; Includes
+
 (require 'ansi-color)
 (require 'package)
 (require 'project)
@@ -1844,9 +1853,17 @@ variable we use to test validation."
 (eask-load "extern/package-build")
 
 ;;
-;;; Requirement
-
-(when (version< emacs-version "26.1")
-  (eask-error "Eask requires Emacs 26.1 and above!"))
+;;; API
+
+(defvar eask-commands nil
+  "List of defined commands.")
+
+(defmacro eask-defcommand (name &rest body)
+  "Define an Eask command."
+  (declare (doc-string 2) (indent 1))
+  (or name (error "Cannot define '%s' as a command" name))
+  (push name eask-commands)
+  (setq eask-commands (delete-dups eask-commands))
+  `(defun ,name nil ,@body))
 
 ;;; _prepare.el ends here

lisp/core/command.el

@@ -0,0 +1,72 @@
+;;; core/command.el --- Run custom command  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;;
+;; Command use to run custom command
+;;
+;;   $ eask command [names..]
+;;
+;;
+;;  Positionals:
+;;
+;;    [names..]     name of the function command
+;;
+
+;;; Code:
+
+(let ((dir (file-name-directory (nth 1 (member "-scriptload" command-line-args)))))
+  (load (expand-file-name "_prepare.el"
+                          (locate-dominating-file dir "_prepare.el"))
+        nil t))
+
+(defun eask--command-desc (name)
+  "Return command's description by its command's NAME."
+  (car (split-string (documentation name) "\n")))
+
+(defun eask--print-commands ()
+  "Print all available commands."
+  (eask-msg "available via `eask command`")
+  (eask-msg "")
+  (let* ((keys (reverse eask-commands))
+         (offset (eask-seq-str-max keys))
+         (fmt (concat "  %-" (eask-2str offset) "s  %s")))
+    (dolist (key keys)
+      (eask-msg fmt key (eask--command-desc key)))
+    (eask-msg "")
+    (eask-info "(Total of %s available script%s)" (length keys)
+               (eask--sinr keys "" "s"))))
+
+(defun eask--execute-command (name)
+  "Execute the command by NAME."
+  (eask-info "[RUN]: %s" name)
+  (funcall (eask-intern name)))
+
+(defun eask--unmatched-commands (commands)
+  "Return a list of COMMANDS that cannot be found in `eask-commands'."
+  (let (unmatched)
+    (dolist (command commands)
+      (unless (memq (eask-intern command) eask-commands)
+        (push command unmatched)))
+    unmatched))
+
+(eask-start
+  (cond ((null eask-commands)
+         (eask-info "(No command specified)")
+         (eask-help "core/command"))
+        ((eask-all-p)
+         (dolist (name (reverse eask-commands))
+           (eask--execute-command name)))
+        ((when-let ((commands (eask-args)))
+           (if-let ((unmatched (eask--unmatched-commands commands)))
+               (progn  ; if there are unmatched commands, don't even try to execute
+                 (eask-info "(Missing command%s: `%s`)"
+                            (eask--sinr unmatched "" "s")
+                            (mapconcat #'identity unmatched ", "))
+                 (eask-msg "")
+                 (eask--print-commands))
+             (dolist (command commands)
+               (eask--execute-command command))
+             t)))
+        (t (eask--print-commands))))
+
+;;; core/command.el ends here

lisp/help/core/command

@@ -0,0 +1,6 @@
+
+💡 Make sure you have specify a (eask-defcommand ..) function inside your Eask file!
+
+    [+] (eask-defcommand my-command
+    [+]   "This is a test command."
+    [+]   (message "My test commnad!"))