開發 API
本文檔提供了對公共 Eask API 的引用，您可以在您的項目和 Eask 的擴展。
加載 lisp/_prepare.el 以開始使用其他 Eask API。
(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))
每個 Elisp 腳本都應該在文件的最頂部有這個片段。
命令入口點。 每個命令文件都應在文件的某處包含此宏。
(eask-start
;; TODO: 在這裡設計你的命令！
)
如果終端支援顏色，則傳回非零。
(when eask-has-colors ...
Eask 的主目錄路徑。
(message "%s" eask-homedir)
Eask的呼叫程式路徑。
(message "%s" eask-invocation)
它可以是 node 可執行檔或 eask 執行檔本身。
如果 Eask 已打包，則傳回非零。
(when eask-is-pkg ...
命令分隔符號 -- 之後的 Eask 參數；傳回一個列表。
$ eask <command> -- args0 args1
輸出:
(message "%s" eask-rest) ; '(args0 args1)
命令分隔符號 -- 之後的 Eask 參數；傳回一個字串。
$ eask <command> -- args0 args1
輸出:
(message "%s" (eask-rest)) ; "args0 args1"
從項目根目錄指向 lisp 目錄。
(message "%s" eask-lisp-root) ; path/to/eask/cli/lisp/
傳回將要執行的程式的工作目錄。
(message "%s" (eask-working-directory)) ; path/to/current/work/space/
返回字符串中的當前命令。假設命令是：
$ eask init
然後，
(message "%s" (eask-command)) ; init
如果 COMMANDS 是目前命令，則傳回 t。
如果在沒有 Eask 文件存在的情況下可以運行的命令，則返回 t。
這允許一些命令仍然可以在不定義用戶的情況下執行目錄。 當您想在沒有的情況下進行正常操作時，這會很方便 觸摸用戶目錄。
如果命令是執行命令，則傳回 t。
加入這項功能是因為我們不想污染 error 和 warn 函數。
如果運行 Eask 作為檢查器，則返回 t。
如果沒有這個標誌，一旦發生錯誤，進程就會終止。此標誌允許您在不報告錯誤的情況下運行所有操作。
返回完整的腳本文件名。
(eask-script "extern/pacakge") ; {project-root}/lisp/extern/package.el
加載另一個 eask 腳本。
(eask-load "extern/ansi") ; load {project-root}/lisp/extern/ansi.el file
調用另一個 eask 腳本。
(eask-call "clean/elc") ; call command `eask clean-elc`
💡 我們不經常呼叫它，因為我們不希望直接執行另一個命令！
從 url 載入並評估腳本。
(eask-import "https://raw.githubusercontent.com/emacsmirror/emacswiki.org/master/yes-no.el")
;; 該腳本將在導入後即可使用！
如果 Emacs 版本低於特定版本，則定義範圍。
VERSION 是一個整數，將與 emacs-major-version 進行比較。
(eask-defvc< 28
;; 這在 Emacs 28 之前是缺失的； 定義它!
(defvar package-native-compile nil))
💡 這用於 Emacs 兼容性！
將來自範圍內標準輸出的所有消息靜音。
(eask--unsilent (message "你聽不到我! :("))
取消靜音來自範圍內標準輸出的所有消息。
(eask--unsilent (message "你聽的到我! :)"))
返回依賴項列表。
元素應該是 (NAME . VERSION) 或 (NAME . RECIPE-FORMAT)。
初始化包以供使用。
(eask-start
(eask-pkg-init)
;; 現在您可以使用安裝在 `package-user-dir` 中的包
)
💡 這通常在 eask-start 之後調用！
臨時使存檔可用的範圍。
參數 archives 可以是字串或字串列表。
(eask-with-archives "melpa"
(eask-package-install 'dash)) ; 安裝僅在 MELPA 中定義的包
💡 當您需要某些存檔中的特定套件時，這非常方便。
使用 archives 設定安裝套件。
參數 names 可以是符號或符號列表。
(eask-archive-install-packages '("gnu" "melpa")
'el2org) ; 接受列表
💡 這只會在套件遺失時安裝套件。
為包構建包描述符。
CURRENT 表示已安裝的包； 否則它將返回任何可用的來自選定包檔案的包。
通过索引返回一个命令行参数。
返回從命令行參數中提取的列表。
$ eask info --verbose 4 foo bar
它會忽略 --verbose 和 4，只返回 foo 和 bar。
當前加載的 Eask 文件的路徑。
當前加載的 Eask 文件的目錄。
檢查 NAME 是否是我們的目標 Eask 文件，然後返回它。
以下輸出來自 Emacs 28.1：
(eask--match-file "Eask") ; t
(eask--match-file "Eask.28") ; t
(eask--match-file "Eask.28.1") ; t
(eask--match-file "Eask.29") ; nil
(eask--match-file "Easkfile") ; t
(eask--match-file "Easkfile.28") ; t
(eask--match-file "Easkfile.29") ; nil
從 DIR 返回 Eask 文件列表。
考慮以下目錄樹：
. root
├── Eask
├── Eask.28
└── Eask.29
以下輸出來自 Emacs 28.1：
(eask--all-files "/root/") ; '(Eask Eask.28)
從 START-PATH 找到 Eask 文件。
考慮以下目錄樹：
.project
├─ src
│ └── config.el
├── Eask
├── Eask.28
└── Eask.29
以下輸出來自 Emacs 28.1：
(eask--find-files "/project/src/config.el") ; '(/project/Eask /project/Eask.28)
嘗試在 START-PATH 中加載 Eask 文件。
(eask--find-files "/project/src/") ; t
如果當前 Emacs 會話允許不安全的網絡連接，則返回 t。
如果啟用了 global 選項，則返回 t。
(when (eask-global-p)
user-emacs-directory) ; ~/.eask/
如果啟用了 config 選項，則返回 t。
(when (eask-config-p)
user-emacs-directory) ; ~/.emacs.d
💡 如果選項--config和--global都打開，則選擇全局空間。
這使用當前工作區，這是默認設置。
(when (eask-local-p)
user-emacs-directory) ; ./.eask/{emacs-version}/
💡 此函數僅在(eask-global-p)和(eask-config-p)是 false 時返回t！
如果啟用了 all 選項，則返回 t。
(when (eask-all-p)
;; 運行所有測試
...)
如果啟用了 quick 選項，則返回 t。
(unless (eask-quick-p)
(load user-init-file)
...)
如果啟用了 force 選項，則返回 t。
(package-delete .. (eask-force-p))
如果啟用了 development 選項，則返回 t。
(when (eask-dev-p)
(package-install 'ert-runner)) ; 安裝開發依賴
如果啟用了 debug 選項，則返回 t。
(when (eask-debug-p)
(error "在調試模式下執行..."))
如果啟用了 strict 選項，則返回 t。
(setq byte-compile-error-on-warn (eask-strict-p))
如果啟用/禁用 timestamps 選項，則返回 t / nil。
這些標誌不能在同一命令中共存。
(when (eask-timestamps-p)
(message "打印帶有時間戳的日誌！"))
如果啟用/禁用 log-level 選項，則返回 t / nil。
這些標誌不能在同一命令中共存。
(when (eask-log-level-p)
(message "打印帶有級別前綴的日誌！"))
如果啟用/禁用 log-file 選項，則返回 t / nil。
這些標誌不能在同一命令中共存。
(when (eask-log-file-p)
(message "讓我們創建一個日誌文件！"))
如果啟用了 color 選項，則返回 t。
(unless (eask-no-color-p)
(message "此字符串沒有 ANSI 代碼！"))
如果啟用了 allow-error 選項，則返回 t。
(unless (eask-allow-error-p)
(error "停在這裡。"))
如果啟用了 insecure 選項，則返回 t。
(when (eask-insecure-p)
;; 做一些危險的工作？
)
返回一個 string 表示 hostname + port number。
$ eask [command] --proxy "localhost:1000"
$ eask [command] --http-proxy "localhost:2000"
$ eask [command] --https-proxy "localhost:3000"
$ eask [command] --no-proxy "localhost:4000"
返回一個 string 表示目的地（輸出路徑）。
(write-file (or (eask-destination) "./dist")) ; 將文件寫入目標
返回一個整數表示當前打印層級的深度。
(setq print-level (eask-depth))
返回一個 整數 表示冗長級別。
(when (= (eask-verbose) 4)
(setq byte-compile-verbose t))
這些函數是 Eask-file DSL 的實際實現； 和將單詞 eask- 作為函數前綴。
有關詳細信息，請參閱 DSL 部分。
它在 plist 中保存包的 NAME、VERSION 和 DESCRIPTION。
(plist-get eask-package :name) ; 返回包名
從該變量擴展的三個函數：
(eask-package-name)(eask-package-version)(eask-package-description)
指向打包主文件。
來自包主文件的包描述符。
(package-desc-p eask-package-desc) ; 返回 t
⚠ 如果不能正確構造包描述符，這可以是 nil！
持有通配符規範中的文件模式列表。
包含可用腳本的列表，用戶可以使用 eask run-script 命令。
保存有關 Emacs 最低版本的信息。
(depends-on "emacs" "26.1")
函數將返回字符串中的 Emacs 版本。
(eask-depends-emacs-version)- 返回"26.1"
持有依賴項列表。
持有開發使用的依賴項列表。
別名 package.
別名 website-url.
別名 keywords.
別名 author.
別名 license.
別名 package-file.
別名 files.
別名 script.
別名 source.
別名 source-priority.
別名 depends-on.
別名 development.
別名 exec-paths.
別名 load-paths.
具有時間戳和日誌級別的記錄器實用程序。
日誌級別值在函數 eask--verb2lvl 中定義。
| 等級 | 描述 | 值 |
|---|---|---|
debug | 指定對調試應用程序最有用的細粒度信息事件。 | 4 |
log | 指定普通消息。 | 3 |
info | 指定在粗粒度級別突出顯示應用程序進度的信息性消息。 | 2 |
warn | 指定潛在的有害情況。 | 1 |
error | 指定可能仍允許應用程序繼續運行的錯誤事件。 | 0 |
The default level is log.
詳細級別表示為整數。
(setq eask-verbosity 4) ; 你可以設置從 0 到 4
記錄帶有時間戳的消息。
(setq eask-timestamps t)
Output:
2022-04-14 13:44:46 這是一條帶有時間戳的消息
記錄消息級別。 （默認值：nil）
(setq eask-log-level t)
輸出：
[DEBUG] 這是一條具有日誌級別的 DEBUG 消息
天氣生成日誌文件。 （默認值：nil）
(setq eask-log-level t)
使用命令 cat 查看日誌，
$ cat /.log/messages.log
定義每個日誌級別顏色。
(setq eask-level-color
'((debug . ansi-blue)
(log . ansi-white)
(info . ansi-cyan)
(warn . ansi-yellow)
(error . ansi-red)))
達到詳細等級時執行。
(when (eask-reach-verbosity-p 'debug)
;; TODO: 在這裡執行..
)
定義消息範圍。
(eask-with-verbosity 'debug
;; TODO: 在這裡執行..
)
除非冗長，否則此宏範圍內的所有內容都將被靜音。 僅當您指定 --verbose 4 時才會打印
全局選項。
定義覆蓋消息範圍。
(eask-with-verbosity 'debug
(eask-with-verbosity-override 'log
;; TODO: 在這裡執行..
)
(eask-with-verbosity-override 'info
;; TODO: 在這裡執行..
))
就像宏 eask-with-verbosity 一樣；但如果無法顯示則強制顯示消息。
(eask-debug "這是調試信息")
2022-04-14 17:31:54 [DEBUG] 這是調試信息
(eask-log "這是日誌消息")
2022-04-14 17:31:54 [LOG] 這是日誌消息
(eask-info "這是信息消息")
2022-04-14 17:31:54 [INFO] 這是信息消息
(eask-warn "這是警告消息")
2022-04-14 17:31:54 [WARNING] 這是警告消息
(eask-error "這是錯誤信息")
2022-04-14 17:31:54 [ERROR] 這是錯誤信息
標準輸出列印不含換行符。
(eask-println "打印到標準輸出！")
與函數 esk-print 類似，但末尾包含換行符。
(eask-println "打印到標準輸出！ (有換行符)")
類似於 message 函數，但會用顏色替換 unicode。
(eask-msg "用換行符打印此消息！")
類似於 eask-msg 函數，但末尾沒有換行符。
(eask-write "不帶換行符打印此消息...")
報告錯誤/警告取決於嚴格標誌。
(eask-report "This can be warning or error")
見選項 –strict.
非 nil 是為了防止 Emacs 被殺死。
(let ((eask--ignore-error-p t))
(error "Emacs can't die! :P"))
非 nil 停止錯誤/警告消息。
(let ((eask-inhibit-error-message t))
(error "This won't display at all!"))
防止 Emacs 被殺死。
(eask-ignore-errors
(error "Emacs can't die! :P"))
禁止顯示錯誤/警告消息。
(eask--silent-error
(error "This won't display at all!"))
防止 Emacs 被殺死並禁止顯示錯誤/警告消息。
(eask-ignore-errors-silent
(error "Nothing happens!"))
Send exit code.
This will kill Emacs process.
返回包文件列表。
返回擴展名為 .el 的包文件列表。
返回擴展名為 .elc 的包文件列表。
如果是單個文件包，則返回 nil。
如果是單個文件包，則返回 t。
返回當前包的大小。
⚠️ 這將返回一個字符串而不是字節。
使用響應消息輸出創建執行。
(eask-with-progress
"檔案下載中s... "
(eask-with-verbosity 'debug ; 通常與 `eask-with-verbosity` 一起使用
;; 執行一些操作..
)
"完成 ✓")
期望輸出：
檔案下載中... 完成 ✓
打印緩衝區並突出顯示 錯誤 和 警告。
(eask-print-log-buffer "*Package-Lint*")
💡 這對於創建 buffer 來顯示 errors 和 warnings 的 linters 會很方便。
打印位於 lisp/help/ 目錄下的幫助手冊。
(eask-help "core/search")
💡 這是在命令失敗時使用的，想給用戶一些提示！
返回可能的包名稱。
返回可能的包的入口點。