The Hy REPL

Hy’s read-eval-print loop (REPL) is implemented in the class hy.REPL. The REPL can be started interactively from the command line or programmatically with the instance method hy.REPL.run().

Two environment variables useful for the REPL are HY_HISTORY, which specifies where the REPL input history is saved, and HYSTARTUP, which specifies a file to run when the REPL starts.

class hy.REPL(spy=False, output_fn=None, locals=None, filename='<stdin>', allow_incomplete=True)

A subclass of code.InteractiveConsole for Hy.

A convenient way to use this class to interactively debug code is to insert the following in the code you want to debug:

(.run (hy.REPL :locals (locals)))

Note that as with code.interact(), changes to (locals) inside the REPL are not propagated back to the original scope.

run()

Start running the REPL. Return 0 when done.

Output functions

By default, the return value of each REPL input is printed with hy.repr. To change this, you can set the REPL output function with e.g. the command-line argument --repl-output-fn. Use repr() to get Python representations like Python’s own REPL.

Regardless of the output function, no output is produced when the value is None, as in Python.

Special variables

The REPL maintains a few special convenience variables. *1 holds the result of the most recent input, like _ in the Python REPL. *2 holds the result of the input before that, and *3 holds the result of the input before that. Finally, *e holds the most recent uncaught exception.

Startup files

Any macros or Python objects defined in the REPL startup file will be brought into the REPL’s namespace. Two variables are special in the startup file:

repl-spy

If true, print equivalent Python code before executing each piece of Hy code.

repl-output-fn

The output function, as a unary callable object.

Hy startup files can do a number of other things like set banner messages or change the prompts. The following example shows a number of possibilities:

;; Wrapping in an `eval-and-compile` ensures these Python packages
;; are available in macros defined in this file as well.
(eval-and-compile
  (import sys os)
  (sys.path.append "~/<path-to-global-libs>"))

(import
  re
  json
  pathlib [Path]
  hy.pypos *
  hyrule [pp pformat])

(require
  hyrule [unless])

(setv
  repl-spy True
  repl-output-fn pformat
  ;; Make the REPL prompt `=>` green.
  sys.ps1 "\x01\x1b[0;32m\x02=> \x01\x1b[0m\x02"
  ;; Make the REPL prompt `...` red.
  sys.ps2 "\x01\x1b[0;31m\x02... \x01\x1b[0m\x02")

(defn slurp [path]
  (setv path (Path path))
  (when (path.exists)
    (path.read-text)))

(defmacro greet [person]
  `(print ~person))