hy-1-2-0

name	hy-1-2-0
description	Lisp dialect embedded in Python providing prefix S-expression syntax, compile-time macros, quasiquoting, reader macros, and seamless access to Python built-ins and libraries. Use when writing Hy programs, creating Hy macros, converting between Python and Hy code, debugging Hy compilation, or building Lisp-style metaprogramming on Python.

Hy 1.2.0 (Crackers and Snacks)

Overview

Hy is a multi-paradigm Lisp dialect compiled to Python AST. It uses prefix S-expression syntax with parentheses-delimited forms, compiles to Python bytecode, and runs on CPython or PyPy. All Python built-ins and third-party libraries are directly available. Hy adds Lisp features: compile-time macros (regular and reader), quasiquoting, homoiconic model objects, bracket strings, f-strings with Hy expressions, and generalized n-ary operators.

Hy is not a standalone language — it compiles to Python AST which Python executes. Runtime semantics follow Python exactly; only syntax and compile-time features differ.

When to Use

• Writing programs in Hy's Lisp-style prefix syntax
• Creating or debugging macros (regular macros with defmacro, reader macros with defreader)
• Converting Python code to Hy (hy2py for Hy→Python, py2hy for Python→Hy)
• Configuring the Hy REPL (startup files, custom output functions, prompts)
• Debugging compilation issues (stale bytecode, macro expansion order, implicit names)
• Building DSLs or domain-specific syntax extensions via reader macros
• Using Hy's metaprogramming tools (hy.eval, hy.macroexpand, model patterns)
• Packaging Hy libraries for PyPI

Quick Start

Hello world:

(print "Hy, world!")

Basic operations (prefix syntax, n-ary operators):

(+ 1 2 3)          ; => 6
(- (* (+ 1 3 88) 2) 8)  ; => 176
(setv x 42)        ; variable assignment
(= x 42)           ; equality (== in Python, = in Hy)

Functions:

(defn fib [n]
  (if (< n 2)
    n
    (+ (fib (- n 1)) (fib (- n 2)))))

(print (fib 8))  ; => 21

Macros (compile-time code generation):

(defmacro do-while [condition #* body]
  `(do
     ~@body
     (while ~condition
       ~@body)))

(setv x 0)
(do-while x
  (print "Executed once."))

Run and translate:

hy myprogram.hy              ; run Hy file
hy                           ; start REPL
echo "(+ 1 2)" | hy2py       ; => 1 + 2
python3 -m py2hy code.py     ; Python → Hy
hyc compile myfile.hy        ; pre-compile to bytecode

Advanced Topics

Core Syntax & Data Types: Forms, models, literals, identifiers, mangling, strings, expressions, syntactic sugar → Core Syntax

Control Flow & Functions: Conditionals, loops, comprehensions, defn/fn, decorators, type parameters, annotations → Control Flow & Functions

Macros & Metaprogramming: Regular macros, reader macros, quasiquoting, macro scoping, pitfalls, compile-time evaluation → Macros & Metaprogramming

Classes & Modules: defclass, import/require, packaging Hy libraries, one-shot imports → Classes & Modules

CLI Tools & REPL: hy/hy2py/hyc commands, REPL configuration, startup files, environment variables → CLI Tools & REPL

Python Interoperability: Mangling, py/pys macros, using Hy from Python, py2hy converter → Python Interoperability

Semantics & Gotchas: Implicit import hy, evaluation order, bytecode caching, tracebacks → Semantics & Gotchas

Advanced Topics: Model patterns, hy.eval/hy.macroexpand, hy.gensym, reader API, recommended libraries → Advanced Topics