Development API

This document provides a reference to the public Eask API, which you may use in your projects and extensions to Eask.

Load lisp/_prepare.el to start using other 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))

Each Elisp scripts should have this snippet at the very top of the file.

Command entry point. Each command file should contain this macro somewhere in the file.

(eask-start
  ;; TODO: design your command here!
  )

Return non-nil if the terminal supports colors.

(when eask-has-colors ...

Eask’s home directory path.

(message "%s" eask-homedir)

Eask’s invocation program path.

(message "%s" eask-invocation)

It could be the node executable or the eask executable itself.

Return non-nil if Eask is packaged.

(when eask-is-pkg ...

Eask’s arguments after command separator `–’; return a list.

$ eask <command> -- args0 args1

Output:

(message "%s" eask-rest)  ; '(args0 args1)

Eask’s arguments after command separator `–’; return a string.

$ eask <command> -- args0 args1

Output:

(message "%s" (eask-rest))  ; "args0 args1"

Points to lisp directory from the project root.

(message "%s" eask-lisp-root)  ; path/to/eask/cli/lisp/

Return the working directory of the program going to be executed.

(message "%s" (eask-working-directory))  ; path/to/current/work/space/

Return the current command in string. Suppose the command is:

$ eask init

then,

(message "%s" (eask-command))  ; init

Return t if COMMANDS is the current command.

Return t if the command that can be run without Eask-file existence.

This allows some commands can still be executed without defining the user directory. This can be handy when you want to do normal operations without touching the user directory.

Return t if the command is the execution command.

This is added because we don’t want to pollute error and warn functions.

Return t if running Eask as the checker.

Without this flag, the process will be terminated once the error is occurred. This flag allows you to run through operations without reporting errors.

Return full script filename.

(eask-script "extern/pacakge")  ; {project-root}/lisp/extern/package.el

Load another eask script.

(eask-load "extern/ansi")  ; load {project-root}/lisp/extern/ansi.el file

Call another eask script.

(eask-call "clean/elc")  ; call command `eask clean-elc`

💡 We don’t often call this since we don’t wish to execute another command directly!

Load and evaluate the script from the url.

(eask-import "https://raw.githubusercontent.com/emacsmirror/emacswiki.org/master/yes-no.el")

;; The script will be available after the call!

Define the scope if the Emacs version is below a specific version.

VERSION is an integer and will be compared with emacs-major-version.

(eask-defvc< 28
  ;; This is missing before Emacs 28; define it
  (defvar package-native-compile nil))

💡 This is used for Emacs compatibility!

Mute all messages from standard output inside the scope.

(eask--unsilent (message "You can't hear me! :("))

Unmute all messages from standard output inside the scope.

(eask--unsilent (message "You can hear me! :)"))

Return a list of dependencies.

Elements should either be (NAME . VERSION) or (NAME . RECIPE-FORMAT).

Initialize packages for use.

(eask-start
  (eask-pkg-init)
  ;; Now you can use packages installed in `package-user-dir'
  )

💡 This is usually called after eask-start!

Scope that temporary makes archives available.

The argument ARCHIVES can either be a string or a list of strings.

(eask-with-archives "melpa"
  (eask-package-install 'dash))  ; install packages that are only defined in MELPA

💡 This is handy when you need certain packages from certain archives.

Install packages with archives setup.

The arugment names can be a symbol or list of symbols.

(eask-archive-install-packages '("gnu" "melpa")
                               'el2org)  ; accept list

💡 This only installs packages if they are missing.

Build package descriptor for a package.

CURRENT means installed packages; otherwise it will return any available packages from selected package archives.

Return a command-line argument by index.

Return a list that is extracted from command-line arguments.

$ eask info --verbose 4 foo bar

It will ignore --verbose and 4, and only returns foo, and bar.

Path to currently loaded Eask-file.

Directory to currently loaded Eask-file.

Check to see if NAME is our target Eask-file, then return it.

The following output is with 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

Return a list of Eask files from DIR.

Consider the following directory tree:

. root
├── Eask
├── Eask.28
└── Eask.29

The following output is with Emacs 28.1:

(eask--all-files "/root/")  ; '(Eask Eask.28)

Find the Eask-file from START-PATH.

Consider the following directory tree:

.project
├─ src
│ └── config.el
├── Eask
├── Eask.28
└── Eask.29

The following output is with Emacs 28.1:

(eask--find-files "/project/src/config.el")  ; '(/project/Eask /project/Eask.28)

Try load the Eask-file in START-PATH.

(eask--find-files "/project/src/")  ; t

Return t if the current Emacs session allows insecure network connections.

Return t if the global option is enabled.

(when (eask-global-p)
  user-emacs-directory)   ; ~/.eask/

Return t if the config option is enabled.

(when (eask-config-p)
  user-emacs-directory)   ; ~/.emacs.d

💡 If both options --config and --global are on, the global space is chosen over the config space.

This uses the current workspace, and this is the default.

(when (eask-local-p)
  user-emacs-directory)   ; ./.eask/{emacs-version}/

💡 This function returns t only when (eask-global-p) and (eask-config-p) are false!

Return t if the all option is enabled.

(when (eask-all-p)
  ;; Run all tests
  ...)

Return t if the quick option is enabled.

(unless (eask-quick-p)
  (load user-init-file)
  ...)

Return t if the force option is enabled.

(package-delete .. (eask-force-p))

Return t if the development option is enabled.

(when (eask-dev-p)
  (package-install 'ert-runner))  ; install development dependency

Return t if the debug option is enabled.

(when (eask-debug-p)
  (error "Executing in debug mode..."))

Return t if the strict option is enabled.

(setq byte-compile-error-on-warn (eask-strict-p))

Return t/nil if the timestamps option is enabled/disabled.

These flags can’t co-exist in the same command.

(when (eask-timestamps-p)
  (message "Print log with timestamps!"))

Return t/nil if the log-level option is enabled/disabled.

These flags can’t co-exist in the same command.

(when (eask-log-level-p)
  (message "Print log with level prefix!"))

Return t/nil if the log-file option is enabled/disabled.

These flags can’t co-exist in the same command.

(when (eask-log-file-p)
  (message "Let's create a log file!"))

Return t if the color option is enabled.

(unless (eask-no-color-p)
  (message "This string has no ansi code!"))

Return t if the allow-error option is enabled.

(unless (eask-allow-error-p)
  (error "Stop here."))

Return t if the insecure option is enabled.

(when (eask-insecure-p)
  ;; Do some dangerous tasks?
  )

Return a string represents 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"

Return a string represents the destination (output path).

(write-file (or (eask-destination) "./dist"))  ; write file to destination

Return an integer represents the depth of the current print level.

(setq print-level (eask-depth))

Return an integer represents the verbosity level.

(when (= (eask-verbose) 4)
  (setq byte-compile-verbose t))

These functions are the actual implementation of Eask-file DSL; and have the word eask- as the function prefix.

See DSL section for more information.

It holds package’s NAME, VERSION, and DESCRIPTION in a plist.

(plist-get eask-package :name)  ; return package name

Three functions that are extended from this variable:

• (eask-package-name)
• (eask-package-version)
• (eask-package-description)

Points to package main file.

Package descriptor from the package main file.

(package-desc-p eask-package-desc)  ; return t

⚠ This can be nil if the package-descriptor cannot be constructed correctly!

Holds a list of files pattern in wildcard specification.

Holds a list of available scripts that can be executed by user using the eask run-script command.

Holds information about Emacs minimum version.

(depends-on "emacs" "26.1")

Function will return Emacs version in string.

• (eask-depends-emacs-version) - return "26.1"

Holds a list of dependencies.

Holds a list of dependencies that are development used.

Alias of package.

Alias of website-url.

Alias of keywords.

Alias of author.

Alias of license.

Alias of package-file.

Alias of files.

Alias of script.

Alias of source.

Alias of source-priority.

Alias of depends-on.

Alias of development.

Alias of exec-paths.

Alias of load-paths.

Logger utility with timestamps and log level.

The log level value is defined in function eask--verb2lvl.

The default level is log.

The verbosity level is represented as an integer.

(setq eask-verbosity 4)  ; you could set from 0 to 4

Log messages with timestamps.

(setq eask-timestamps t)

Output:

2022-04-14 13:44:46 This is a message with timestamps

Log messages with level. (default: nil)

(setq eask-log-level t)

Output:

[DEBUG] This is a DEBUG message with log level

Weather to generate log files. (default: nil)

(setq eask-log-level t)

Use command cat to see the log,

$ cat /.log/messages.log

Define each log level color.

(setq eask-level-color
      '((debug . ansi-blue)
        (log   . ansi-white)
        (info  . ansi-cyan)
        (warn  . ansi-yellow)
        (error . ansi-red)))

Make execution when it reaches the verbosity level.

(when (eask-reach-verbosity-p 'debug)
  ;; TODO: execution here..
  )

Define verbosity scope.

(eask-with-verbosity 'debug
  ;; TODO: execution here..
  )

Everything in the scope of this macro will be muted unless the verbosity reaches. It will only be printed when you have specified --verbose 4 global option.

Define override verbosity scope.

(eask-with-verbosity 'debug
  (eask-with-verbosity-override 'log
    ;; TODO: execution here..
    )
  (eask-with-verbosity-override 'info
    ;; TODO: execution here..
    ))

Like macro eask-with-verbosity; but force display messages if it wasn’t able to display.

(eask-debug "This is DEBUG message")

2022-04-14 17:31:54 [DEBUG] This is DEBUG message

(eask-log "This is LOG message")

2022-04-14 17:31:54 [LOG] This is LOG message

(eask-info "This is INFO message")

2022-04-14 17:31:54 [INFO] This is INFO message

(eask-warn "This is WARNING message")

2022-04-14 17:31:54 [WARNING] This is WARNING message

(eask-error "This is ERROR message")

2022-04-14 17:31:54 [ERROR] This is ERROR message

Standard output printing without newline.

(eask-println "Print to stdout!")

Like the function eask-print but contains the newline at the end.

(eask-println "Print to stdout! (with newline)")

Like the message function but will replace unicode with color.

(eask-msg "Print this message with newline!")

Like the eask-msg function but without the newline at the end.

(eask-write "Print this message without newline...")

Report error/warning depends on strict flag.

(eask-report "This can be warning or error")

See option –strict.

Non-nil to prevent Emacs from being killed.

(let ((eask--ignore-error-p t))
  (error "Emacs can't die! :P"))

Non-nil to stop error/warning message.

(let ((eask-inhibit-error-message t))
  (error "This won't display at all!"))

Prevent Emacs from being killed.

(eask-ignore-errors
  (error "Emacs can't die! :P"))

Inhibit display error/warning messages.

(eask--silent-error
  (error "This won't display at all!"))

Prevent Emacs from being killed and inhibit display error/warning messages.

(eask-ignore-errors-silent
  (error "Nothing happens!"))

Send exit code.

This will kill Emacs process.

Return a list of package files.

Return a list of package files with .el extension.

Return a list of package files with .elc extension.

Return nil if single file package.

Return t if single file package.

Return size of the current package.

⚠️ This returns a string not bytes.

Create execution with the responsive message output.

(eask-with-progress
  "Downloading files... "
  (eask-with-verbosity 'debug  ; Often used with `eask-with-verbosity'
    ;; Execute some operations..
    )
  "done ✓")

Expect output:

Downloading files... done ✓

Print buffer and highlight the errors and warnings.

(eask-print-log-buffer "*Package-Lint*")

💡 This is handy for linters that create a buffer to display errors and warnings.

Print help manual located under lisp/help/ directory.

(eask-help "core/search")

💡 This is used when a command fails, and would like to give users some tips!

Return the possible package name.

Return the possible package’s entry point.