doomemacs/modules/feature/eval/README.org

#+TITLE: :feature eval

This modules adds support for evaluating code from inside Emacs, including
REPLs.

* Table of Contents :TOC:
- [[#install][Install]]
- [[#usage][Usage]]
  - [[#repls][REPLs]]
  - [[#code-evaluation][*Code Evaluation*]]
- [[#configuration][Configuration]]
  - [[#repls-1][REPLs]]
  - [[#code-evaluation-1][Code Evaluation]]

* 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/open-repl~
+ ~M-x +eval/send-region-to-repl~ while a selection (and REPL) is active

** *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 are defined for most of the languages Doom supports (check its README.org
to see if it does).

Otherwise, you can define your own for a specified major-mode with the =:repl=
setting.

~(set! :repl MAJOR-MODE FUNCTION)~

FUNCTION must return the repl buffer. Any window changes are ignored, then
handed off to shackle (assuming shackle-mode is on) to display in a popup
window.

#+BEGIN_SRC emacs-lisp
(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)
#+END_SRC

** Code Evaluation
Run regions or entire buffers with [[https://github.com/syohex/emacs-quickrun][Quickrun]]. Output is show in a popup window.

Quickrun includes support for many languages, usually by sending text directly
to interpreters or compilers. However, occasionally, you'll find a language
without support (like [[https://crystal-lang.org/][Crystal]]), or a language with better Emacs integration
(like elisp).

Here's how you define a "runner":

#+BEGIN_SRC emacs-lisp
(set! :eval 'crystal-mode
      '((:command     . "crystal")
        (:exec        . "%c %s")
        (:description . "Run Crystal script")))
#+END_SRC

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

#+BEGIN_SRC emacs-lisp
(set! :eval 'groovy-mode "groovy")
#+END_SRC

Or if you'd rather run an elisp command:

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