doomemacs/modules/feature/eval/README.org

• :feature eval
  • Install
  • Usage
  • Configuration
    • REPLs
    • Build Tasks
    • Code Evaluation

:feature eval

This module adds support for:

• Defining, invoking & interacting with REPLs,
• Defining & invoking build tasks for projects and files,
• and evaluating code or entire buffers, printing their output to a popup window.

Install

This module has no external dependencies. However, specific languages may require additional setup.

Check the README.org in that language's module for details.

Usage

• REPLs Invoked via:

  • :repl (evil ex-command)
  • <leader> o r in normal mode (or visual mode, which sends the selection to the open REPL)
  • M-x +eval/repl
  • M-x +eval/repl-send-region while a selection (and REPL) is active

• Build Tasks You will be prompted to select a task. Only the ones that meet the predicate will be listed.

  • :build (evil ex-command)
  • M-b (by default)
  • <leader> o b in normal mode
  • M-x +eval/build

• Code Evaluation Quickrun can be invoked via:

  • M-x +eval/buffer (or gR, or M-r)
  • M-x +eval/region
  • M-x +eval/region-and-replace
  • Evil users can use the gr operator to select and run a region.

Configuration

REPLs

REPLs have been defined for most of the languages DOOM supports (check its README.org to see if it does).

Otherwise, you can define your own:

A REPL definition consists of two parts: an interactive command that opens (and returns) a REPL buffer and a :repl definition that maps a major-mode to said command:

(defun +emacs-lisp/repl ()
  (interactive)
  (pop-to-buffer
   (or (get-buffer "*ielm*")
       (progn (ielm)
              (let ((buf (get-buffer "*ielm*")))
                (bury-buffer buf)
                buf)))))

(set! :repl 'emacs-lisp-mode #'+emacs-lisp/repl)

Build Tasks

A build task is little more than major-mode-local commands, comprised of an interactive command, an association with a major mode and an optional predicate function.

(defun +lua/run-love ()
  "Run the current project in love 10.0."
  (async-shell-command
   (format "/usr/bin/love %s"
           (shell-quote-argument (doom-project-root)))))

(defun +lua/build ()
  "Run a build script in the project root."
  (let ((default-directory (doom-project-root)))
    (compile "luajit build.lua")))

(defun +lua/generate-docs ()
  "Generate project documentation."
  (let ((default-directory (doom-project-root)))
    (compile "luadoc *.lua")))

(defun +lua-love-p ()
  "Returns non-nil if the current project is a love project."
  (doom-project-has! (and "main.lua" "config.lua")))

(set! :build 'run           'lua-mode #'+lua/run-love :when (+lua-love-p))
(set! :build 'build-project 'lua-mode #'+lua/build    :when (+lua-love-p))
(set! :build 'generate-docs 'lua-mode #'+lua/generate-docs)

Code Evaluation

Run regions or entire buffers with Quickrun. Output will be sent to a popup window.

Quickrun includes support for many languages, but occasionally, you'll find a language without support, such as Crystal. A "runner" can be defined like so:

(set! :eval 'crystal-mode
      '((:command     . "crystal")
        (:exec        . "%c %s")
        (:description . "Run Crystal script")))

A simpler version is simply to use the path to the binary:

(set! :eval 'groovy-mode "groovy")

Or if you'd rather run an elisp command:

(set! :eval 'emacs-lisp-mode #'+emacs-lisp-eval)